# RevoGrid Pro Documentation

> Full normalized Markdown export of the RevoGrid Pro portal documentation.

Source: https://pro.rv-grid.com

---

# Welcome to the RevoGrid Pro documentation!

URL: https://pro.rv-grid.com/guides/
Source: src/content/docs/guides/index.mdx
Description: Learn how to leverage the advanced features of RevoGrid Pro, access detailed documentation, and make the most of our support and resources.

This guide is designed to help you understand and utilize the advanced features of RevoGrid Pro.
We are going to provide you with the tools and knowledge needed to build complex, high-performance grid applications. Our goal is to:

1. **Save Integration Time**: Provide you with comprehensive examples and documentation to streamline the integration of advanced features into your grid applications.
2. **Offer Pro-Level Examples**: Present real-world examples that demonstrate how to implement complex Pro-level features effectively.
3. **Enhance Customization**: Show you how to extend our existing plugins and create your own custom functionalities to suit your specific needs.
4. **Enable Advanced Understanding**: Open up the Grid Core functionality and provide deep insights for those who are interested in customizing and extending the grid at a fundamental level.

## How to Get Started

Most of the information you need is available in our docs portal.
Start with [Installation](/guides/installation), then review [key concepts from the main docs](https://rv-grid.com/guide/).
From there, jump to the available features, plugins, and examples.
To jump start your project, you can use our [RevoGrid Pro boilerplates](https://github.com/revolist/revogrid-pro-boilerplate.git), which include examples for all major frameworks.
These product examples provide additional tips and insights to help you manage complex data workflows.

## Use AI with RevoGrid Pro

If you are using Codex, Cursor, Claude Code, or VS Code MCP clients, start with the hosted RevoGrid MCP guide:

- [How to use RevoGrid MCP](/guides/ai-mcp)
- [AI Agent Documentation Sources](/guides/ai-agent-documentation)

### Repository layout

The source repository is a pnpm workspace. Pro and standalone product packages live under `packages/`, the documentation and runnable demo apps live under `apps/`, shared example sources live under `examples/`, and Playwright suites live under `tests/`.

- apps/
  - portal/ Documentation website (Astro/Starlight)
    - src/
      - components/ Components rendered by documentation pages
      - content/docs/ MDX documentation files
  - demos/ Runnable demo catalog and framework previews
    - src/
      - catalog/ Demo catalog metadata
      - preview/ Framework preview lifecycles
- examples/
  - components/ Shared demo components used by docs and demos
    - src/components/ Vanilla, React, Vue, and Angular examples
  - angular/ Angular preview app and wrapper examples
  - react/ React preview app and wrapper examples
  - core/ Core example helpers
- packages/
  - pro/ RevoGrid Pro package
    - plugins/ Pro plugin source code
    - src/ Package entrypoints and shared exports
  - pivot/ Standalone Pivot package
  - gantt/ Standalone Gantt package
  - scheduler/ Standalone Scheduler package
  - kanban/ Standalone Kanban package
    - src/ Package entrypoints and shared exports
- revogrid/ Core grid library (Git submodule)
- tests/
  - e2e-pro/ Pro browser tests
  - e2e-enterprise/ Product integration browser tests
  - e2e-demos/ Demo browser tests
  - helpers/ Shared E2E helpers
- pnpm-workspace.yaml Workspace configuration

### Installation and Usage

1. Installation Instructions
  To get started, follow the installation process in our [Installation Guide](/guides/installation).
  This guide includes private npm, GitHub npm, pre-built release, and source-build options for Pro and standalone product packages.

2. Import Pro and Product Packages and CSS
  After installation, import the packages and CSS based on the features you need.
  Use Pro for advanced grid features, then add Pivot, Gantt, Scheduler, or Kanban from its standalone package.
  Here is a typical setup:

```ts
// Pro
import '@revolist/revogrid-pro/dist/revogrid-pro.css';
import { RowOddPlugin } from '@revolist/revogrid-pro';

// Standalone Pivot product
import '@revolist/pivot/styles.css';
import { PivotPlugin } from '@revolist/pivot';
```

Make sure package styles are included so features render correctly.

3. Review the Documentation
  Begin by exploring our detailed Pro documentation. We advice to start from simpler examples, then move to more advanced scenarios:
  - [Data Synchronization](/guides/faq/data-sync)
  - [Odd Rows](/guides/rows/row-odd/)
  - [Custom Row Header](/guides/rows/row-advanced-header/)
  - [Selection & Focus](/guides/selection/)
  - [Column Selection](/guides/selection/column-selection/)
  - [Multi-Range Selection](/guides/selection/multi-range-selection/)
  - [Event Manager](/guides/data-manage/event-manager-explanation)
  - [Collaborative Editing](/guides/data-manage/collaborative-editing/)
  - [Collaborative Presence](/guides/data-manage/collaborative-presence/)
  - [Pagination](/guides/grid-utilities/pagination)
  - [Formula](/guides/formula/overview/)
  - [Merge Cells](/guides/cells/cell-merge/)
  - …

4. Implement Examples
  Follow the provided examples to see how advanced features are implemented. Use these examples as a starting point for your own customizations.

5. Utilize Support Resources
  If you encounter challenges or have questions, make use of our support options. Reach out for personalized assistance or schedule a call with one of our creators.

## Conclusion

With detailed examples, extensive documentation we aim to provide everything you need to build powerful, customized grid applications efficiently. Dive in, explore the possibilities, and take your grid solutions to the next level with RevoGrid Pro.
For any questions or additional support, don't hesitate to reach out.

---

# AI Agent Documentation Sources

URL: https://pro.rv-grid.com/guides/ai-agent-documentation/
Source: src/content/docs/guides/ai-agent-documentation.mdx
Description: Choose the right RevoGrid Pro documentation source for an AI agent: llms.txt, the full corpus, split skill references, an installable skill, or MCP.

RevoGrid Pro publishes several documentation formats for AI agents. They all describe the same portal documentation, but serve different retrieval workflows. Start with the smallest source that answers the task, then retrieve more context only when needed.

These resources provide guidance and examples. When an agent can inspect the project, local source code and public TypeScript types remain the final authority for implementation details.

## Choose a source

| Source | Best for | What the agent receives |
| --- | --- | --- |
| [`llms.txt`](https://pro.rv-grid.com/llms.txt) | First lookup and URL discovery | A compact Markdown index of high-signal guides, API references, demos, and links to larger resources. |
| [`llms-full.txt`](https://pro.rv-grid.com/llms-full.txt) | Offline context or a one-shot research task | The complete normalized Markdown documentation corpus. |
| [`llms-skill.txt`](https://pro.rv-grid.com/llms-skill.txt) | Skill-aware agents that fetch only relevant references | A `SKILL.md` index that routes the agent to topic-specific reference files. |
| [`llms-skill/`](https://pro.rv-grid.com/llms-skill/) | Selective, URL-based retrieval | The same split skill index and individual Markdown references under `llms-skill/references/`. |
| [`revogrid-pro.skill`](https://pro.rv-grid.com/revogrid-pro.skill) | Installing reusable RevoGrid documentation context in a supported agent | A downloadable skill archive containing `SKILL.md` and its split reference files. |
| [RevoGrid MCP](/guides/ai-mcp) | Task-oriented structured retrieval | Core, Pro, and Enterprise docs, examples, feature resolution, migration notes, and typed plugin context. |

## Start with `llms.txt`

Fetch [`https://pro.rv-grid.com/llms.txt`](https://pro.rv-grid.com/llms.txt) when the agent needs to find the right RevoGrid page before reading it. The index favors high-signal pages, groups the remaining documentation by topic, and points to the full corpus and skill formats.

This is the best default for an agent that can follow links. It avoids placing the entire documentation corpus into context before the agent knows whether the task concerns Pivot, Gantt, filtering, or a core API.

```text
Read https://pro.rv-grid.com/llms.txt. Find the relevant RevoGrid Pro documentation,
then fetch only the pages needed for this task before proposing an implementation.
```

## Use the full corpus for broad context

[`https://pro.rv-grid.com/llms-full.txt`](https://pro.rv-grid.com/llms-full.txt) contains every portal documentation page as normalized Markdown. Each section includes its portal URL and source path, so an agent can trace guidance back to its documentation page.

Use it for a research or offline workflow that cannot follow many links. Avoid loading it by default if the agent has a limited context window; `llms.txt` or the split skill is usually more efficient.

## Use the split skill for selective retrieval

The split skill is designed for agents that understand `SKILL.md` instructions or can fetch Markdown files by URL.

- [`llms-skill.txt`](https://pro.rv-grid.com/llms-skill.txt) returns the root `SKILL.md` as plain text.
- [`llms-skill/`](https://pro.rv-grid.com/llms-skill/) returns the same index and exposes the individual references it links to.
- [`revogrid-pro.skill`](https://pro.rv-grid.com/revogrid-pro.skill) packages that index and all reference files as a downloadable skill archive.

The index groups references by product area. Read the index first, then fetch only the referenced Markdown files that match the task. This gives an agent structured guidance without sending unrelated documentation into its context.

```text
Read https://pro.rv-grid.com/llms-skill.txt first. Follow only the references for
the feature I am implementing, and validate API details against local TypeScript types.
```

If your agent supports skill archives, install [`revogrid-pro.skill`](https://pro.rv-grid.com/revogrid-pro.skill) to make the split documentation available as a reusable local skill. Otherwise, use the public `llms-skill.txt` URL and reference links directly.

## Use MCP for structured retrieval

The public files are documentation exports suited to direct HTTP retrieval. MCP
adds structured tools for agents that need examples, feature resolution, migration
notes, or typed plugin context. Both are token-free; MCP results label Pro and
Enterprise requirements explicitly.

For setup, supported clients, and example prompts, see [How to use RevoGrid MCP](/guides/ai-mcp).

## Recommended agent workflow

1. Fetch [`llms.txt`](https://pro.rv-grid.com/llms.txt) or read the installed split skill index.
2. Retrieve the smallest set of relevant guides and API references.
3. Query MCP for relevant Core or Pro examples, migrations, and typed context.
4. Inspect local source and public TypeScript types before writing or changing code.
5. Keep the implementation aligned with the retrieved documentation and the local project version.

This sequence gives agents quick discovery, focused context, and a final implementation check against the code they are changing.

---

# How to use RevoGrid MCP

URL: https://pro.rv-grid.com/guides/ai-mcp/
Source: src/content/docs/guides/ai-mcp.mdx
Description: Use the hosted RevoGrid MCP in Codex, Cursor, Claude Code, or VS Code to work with Core, Pro, and Enterprise docs, examples, plugins, migration notes, and typed API context.

RevoGrid MCP gives AI coding tools structured access to the unified RevoGrid
knowledge catalog:

```text
https://mcp.rv-grid.com
```

No MCP access token or authorization header is required. The same endpoint
searches Core, Pro, and Enterprise knowledge. Results retain `requiresPro`
metadata so agents can explain package and license requirements accurately.

RevoGrid has a wide API and plugin surface, with advanced features such as pivot,
event manager, history, specialized renderers, and custom editors. MCP helps an
AI tool retrieve the right implementation guidance before it writes code.

## What you can use it for

Use RevoGrid MCP when you want an AI tool to:

- find the best Core or Pro example for a specific framework
- determine whether a feature requires a Pro package before suggesting code
- build around typed plugin APIs instead of guessing event names or option shapes
- gather migration notes before upgrading a RevoGrid implementation
- work from real examples for pivot, export, filters, history, validation, or custom renderers

## Agent-readable documentation files

For public, text-only documentation sources—including the `llms.txt` index, full
corpus, split skill references, and downloadable skill—see
[AI Agent Documentation Sources](/guides/ai-agent-documentation).

Use MCP when your tool supports structured retrieval and typed context. Use the
public agent-readable files when it needs documentation it can fetch directly.

## Recommended setup

1. Add `https://mcp.rv-grid.com` to your AI coding tool.
2. Ask the agent to search RevoGrid MCP before writing code.
3. Ask it to validate the final implementation against RevoGrid types and examples.
4. If your project must remain Core-only, say so explicitly in the prompt.

## Install in AI coding tools

### Claude Code

```bash
claude mcp add --transport http revogrid https://mcp.rv-grid.com
```

### Codex

```bash
codex mcp add revogrid --url https://mcp.rv-grid.com
```

### Cursor

```json
{
  "mcpServers": {
    "RevoGrid": {
      "url": "https://mcp.rv-grid.com",
      "type": "http"
    }
  }
}
```

### VS Code

Install the `RevoGrid DataGrid MCP` extension, or configure the server directly:

```json
{
  "servers": {
    "RevoGrid MCP": {
      "url": "https://mcp.rv-grid.com",
      "type": "http"
    }
  },
  "inputs": []
}
```

## How to prompt effectively

The best prompts tell the agent:

1. your framework
2. whether the solution may use Pro features
3. which RevoGrid behavior matters most

### Good prompt examples

- `Build a Vue RevoGrid Pro pivot table. Search MCP first, use the best matching example, and explain the required plugin configuration.`
- `Create a React grid with RevoGrid Pro history and validation. Use MCP docs and types before writing code.`
- `Find the best RevoGrid example for advanced filter headers in Angular and adapt it to server-side filtering.`
- `Check if this feature is available in Core or Pro, then recommend the best matching implementation path.`
- `Find a Core-only fallback for this Pro feature.`

## Best practices

Prompt the agent to inspect RevoGrid MCP before generating code. This reduces
invented APIs and helps it start from real examples.

Ask the agent to verify plugin names, event payloads, config fields, and feature
usage against RevoGrid types.

MCP knowledge is token-free, but using a Pro or Enterprise package still requires
the appropriate product access. Ask for a Core-only fallback when needed.

Ask the agent to use the best matching demo or guide as the starting point, then
adapt it to your app.

## Example workflow

1. Add `https://mcp.rv-grid.com` to your MCP client.
2. Open your RevoGrid project.
3. Ask the agent to find the best matching examples and docs.
4. Ask it to adapt the result to your framework and data model.
5. Ask it to verify the result against RevoGrid types before finalizing.

---

# Flashing Cells

URL: https://pro.rv-grid.com/guides/cells/cell-flash/
Source: src/content/docs/guides/cells/cell-flash.mdx
Description: Highlight edited or programmatically updated cells and rows in RevoGrid.

Cell flashing makes recent changes visible in editable grids, live dashboards, and audit workflows. The Pro `CellFlashPlugin` can react to edits from `EventManagerPlugin`, undo/redo changes from `HistoryPlugin`, manual `flashcell` events, or direct plugin method calls.

The demo below updates market-style rows, supports burst/live updates, row flashing, custom duration, manual row flash, and undo/redo.

## Enable Cell Flash

Add `CellFlashPlugin` and mark columns with `flash`. Existing boolean predicates still work, and `EventManagerPlugin` keeps edit events connected to the source update flow.

```ts
import { CellFlashPlugin, EventManagerPlugin } from '@revolist/revogrid-pro';

grid.plugins = [EventManagerPlugin, CellFlashPlugin];
grid.eventManager = { applyEventsToSource: true };
grid.columns = [
  {
    name: 'Price',
    prop: 'price',
    flash: () => true,
  },
];
```

## Context-Aware Flashing

The `flash` callback receives the new value and a context object with the previous value, row model, row index, column, row type, and edit metadata. Return a boolean for simple behavior or a decision object to customize the flash.

```ts
grid.columns = [
  {
    name: 'Price',
    prop: 'price',
    flash: (value, context) => ({
      flash: true,
      rowFlash: Math.abs(Number(value) - Number(context.previousValue)) > 2,
      direction: Number(value) > Number(context.previousValue) ? 'up' : 'down',
      duration: 800,
      rowDuration: 1200,
      className: 'price-flash',
      rowClassName: 'large-move-row',
    }),
	    cellTemplate: cellFlashArrowTemplate({
	      symbols: { up: '+', down: '-', changed: '~' },
	      className: 'price-flash-arrow',
	      arrowClassName: 'price-flash-symbol',
	      directionClassNames: { up: 'positive', down: 'negative', changed: 'neutral' },
	    }),
  },
];
```

## Configure Timing And Queueing

Use `grid.cellFlash` or `additionalData.cellFlash` to tune behavior. Defaults preserve legacy behavior: enabled, cell-only, 1000ms duration, replace active flashes on each flash event, and clear on source reset.

```ts
grid.cellFlash = {
  duration: 700,
  rowDuration: 1000,
  mode: 'cell-and-row',
  queue: 'merge',
  maxActive: 300,
  clearOnSourceChange: true,
  respectReducedMotion: true,
	  aria: {
	    enabled: true,
	    live: 'polite',
	    atomic: true,
	    liveRegionClassName: 'rv-cell-flash-live-region',
	  },
  labels: {
    cellUpdated: state => `Updated ${String(state.prop)} in row ${state.rowIndex + 1}`,
    rowUpdated: state => `Updated row ${state.rowIndex + 1}`,
  },
  className: 'cell-flash-active',
  rowClassName: 'row-flash-active',
};
```

Queue modes:

- `replace` clears current flash state before applying the next batch.
- `merge` keeps existing flashes active until their own timers expire.

Announcement priority is: per-change `ariaLabel`, `aria.label`, `labels.cellUpdated` or `labels.rowUpdated`, then the built-in defaults. Use `labels` for normal localization and `aria.label` when one callback should fully own every announcement. The live-region politeness, atomic flag, and live-region class are also configurable through `aria`.

## Manual Flash API

Manual methods are available from the plugin instance. This is useful when updates come from a websocket, polling loop, or external calculation.

```ts
const plugins = await grid.getPlugins();
const cellFlash = plugins.find(plugin => plugin.constructor.name === 'CellFlashPlugin');

cellFlash.flashCell({
  rowIndex: 0,
  prop: 'price',
  previousValue: 100,
  value: 104,
  direction: 'up',
});

cellFlash.flashRows({
  rowIndex: 0,
  rowClassName: 'manual-row-flash',
});

cellFlash.clearFlash({ rowIndex: 0, prop: 'price' });
```

The existing event API is still supported:

```ts
grid.dispatchEvent(new CustomEvent('flashcell', {
  detail: {
    data: { 0: { price: 104 } },
    previousData: { 0: { price: 100 } },
    type: 'rgRow',
  },
}));
```

## Styling

The plugin sets `flash`, `flash-direction`, `data-flash-direction`, and duration CSS variables on active cells. Row flashes receive `flash-row` and the configured row class.

```css
revo-grid {
  --rv-change-highlight: rgba(255, 238, 0, 0.6);
  --rv-row-change-highlight: rgba(255, 238, 0, 0.22);
  --rv-cell-flash-up-color: #15803d;
  --rv-cell-flash-down-color: #dc2626;
  --rv-cell-flash-arrow-transition-duration: 0.3s;
  --rv-cell-flash-arrow-transition-timing: ease-in-out;
}

revo-grid[theme^='dark'] {
  --rv-change-highlight: rgba(250, 204, 21, 0.34);
  --rv-row-change-highlight: rgba(250, 204, 21, 0.16);
  --rv-cell-flash-up-color: #4ade80;
  --rv-cell-flash-down-color: #f87171;
}

revo-grid .rgCell[flash][flash-direction="up"] {
  color: var(--rv-cell-flash-up-color);
}

revo-grid .rgRow[flash-row].large-move-row {
  font-weight: 500;
}
```

When `respectReducedMotion` is enabled, users with reduced-motion preferences keep the flash attributes and final highlight state without the animation.

---

# Merge Cells

URL: https://pro.rv-grid.com/guides/cells/cell-merge/
Source: src/content/docs/guides/cells/cell-merge.mdx
Description: Combine adjacent cells into a single cell.

The Cell Merge feature allows you to combine adjacent body or pinned data cells into a single, larger cell, much like Excel's merge functionality. Use it to visually group related data within your grid.

For spreadsheet-style headers that span multiple rows or columns, use the [Multi Row Headers](/guides/columns/multi-row-header/) plugin instead.

### Why Use Cell Merge?

Cell Merge is a powerful tool that can help you:

- **Group Data Visually**: Highlight or group related data by merging cells, which improves the readability and interpretability of your grid.

### Example Use Cases

- **Data Grouping**: Use cell merging to visually segment related data or to emphasize specific sections of your grid.

### How It Works

The Cell Merge feature enables you to specify which cells should be merged into a larger cell. This larger cell will span across multiple columns and/or rows. The content of the merged cell will be centrally displayed, enhancing the layout of your grid.

Since this is a Pro feature, ensure that you have access to the Pro version of RevoGrid to utilize this functionality.

<div hidden>

```javascript
// fixing render for multiframework
```

</div>

---

# Highlight Cells and Styling

URL: https://pro.rv-grid.com/guides/cells/cell-style/
Source: src/content/docs/guides/cells/cell-style.mdx
Description: Learn how to style cells dynamically based on their values and implement custom event handling.

Highlighting and styling cells dynamically, allows you to create visually appealing and informative data grids.
By utilizing cell properties and custom templates, you can style cells based on their values, manage interactions, and enhance user experience.

## Dynamic Cell Styling

One of the easiest ways to provide visual feedback to users is through dynamic cell styling.
You can apply styles based on the content of the cells, such as changing the background color depending on the value.

You can also manage various events directly within the cell using the `cellProperties`.
This allows you to add interactivity to your cells, such as handling clicks or double clicks.

### Interactive Example

Below is a live example demonstrating dynamic cell styling and event handling:

This example shows:
- Dynamic background colors based on cell values
- Click event handling
- Custom cell templates

In this example, the **Price** column's background color changes based on its value:
- **Grey** for the first column,
- **Red** for prices below 10,
- **Orange** for prices between 10 and 20,
- **Green** for prices above 20,
- Clicking on the **Price** cell will log the value to the console, while double-clicking will display an alert with the price.

## Using Cell Templates for Advanced Styling

If you need more control over the rendering of cells, you can utilize cell templates. This allows for complex HTML structures within cells while maintaining the ability to style dynamically.
In this case, the **Price** cell uses a custom template to render a `div` element, allowing for more advanced styling and content manipulation.

## Conclusion

Capabilities for highlighting and styling cells enhance the user experience by providing meaningful visual feedback and interactivity. By utilizing dynamic styling, event handling, and custom templates, you can create a rich and engaging data grid that meets your specific requirements.

---

# Chart and Visualization

URL: https://pro.rv-grid.com/guides/cells/charts/
Source: src/content/docs/guides/cells/charts.mdx
Description: Discover the wide range of charts and visual renderers available in RevoGrid.

RevoGrid supports a variety of visual renderers and chart types, enabling users to present data in visually engaging and intuitive formats. Below is a description of each available feature:

## Chart Configuration API

Each chart type supports the following common configuration options:

```typescript
interface ChartConfig {
  name: string;           // Column name
  prop: string;          // Data property name
  minValue?: number;     // Minimum value for normalization
  maxValue?: number;     // Maximum value for normalization
  thresholds?: {         // Visual thresholds for value ranges
    value: number | string | boolean;  // Threshold value
    className: string;   // CSS class for styling
  }[];
  progress?: (config: { model: any; data: any; prop: string }) => number; // Custom progress calculation
}
```

## Progress Line Renderer
Displays a horizontal progress bar within a cell to visually represent a value's progression relative to a maximum limit. Useful for showing percentages or task completion statuses.

### Configuration
```typescript
{
  name: 'Linear',
  prop: 'num',
  minValue: 0,
  maxValue: 100,
  thresholds: [
    { value: 90, className: 'high' },
    { value: 50, className: 'medium' },
    { value: 0, className: 'low' }
  ],
  cellTemplate: progressLineRenderer,
  // Optional: Custom progress calculation
  progress: (config) => {
    // Calculate progress based on multiple fields
    const completed = config.model.completedTasks || 0;
    const total = config.model.totalTasks || 1;
    return (completed / total) * 100;
  }
}
```

## Progress Line with Value Renderer
Combines the progress line visualization with a numerical value label, offering both a visual and textual representation of the data.

### Configuration
```typescript
{
  name: 'Linear with Value',
  prop: 'num',
  minValue: 0,
  maxValue: 40,
  thresholds: [
    { value: 90, className: 'high' },
    { value: 30, className: 'medium' },
    { value: 0, className: 'low' }
  ],
  cellTemplate: progressLineWithValueRenderer,
  // Optional: Custom progress calculation
  progress: (config) => {
    // Calculate progress based on multiple fields
    const completed = config.model.completedTasks || 0;
    const total = config.model.totalTasks || 1;
    return (completed / total) * 100;
  }
}
```

## Circular Progress Renderer
Displays a circular progress bar within a cell to visually represent a value's progression relative to a maximum limit. Useful for showing percentages or task completion statuses.

### Configuration
```typescript
{
  name: 'Circular Progress',
  prop: 'num',
  cellTemplate: circularProgressRenderer
}
```

## Sparkline Renderer
Renders mini inline charts directly within cells to display trends or patterns in data over time, ideal for quick overviews of performance metrics.

### Configuration
```typescript
{
  name: 'Sparkline',
  prop: 'trend',
  minValue: 0,
  maxValue: 100,
  cellTemplate: sparklineRenderer
}
```

## Bar Chart Renderer
Generates horizontal or vertical bar charts inside cells to compare values across categories, making it perfect for categorical or segmented data.

### Configuration
```typescript
{
  name: 'Bars',
  prop: 'trend',
  minValue: 0,
  maxValue: 100,
  cellTemplate: barChartRenderer
}
```

## Timeline Renderer
Visualizes timelines within cells, enabling users to see task durations or event periods in an intuitive linear format.

### Configuration
```typescript
{
  name: 'Timeline',
  prop: 'timeline',
  timelineRange: { start: 0, end: 100 },
  cellTemplate: timelineRenderer
}
```

## Rating Star Renderer
Renders star icons to represent ratings, making it ideal for reviews or score-based data.

### Configuration
```typescript
{
  name: 'Rating',
  prop: 'rating',
  maxStars: 5,
  cellTemplate: ratingStarRenderer
}
```

## Badge Renderer
Displays badges with customizable fill and optional text colors. Data Grid Formatting can override the text color.

### Configuration
```typescript
{
  name: 'Badge',
  prop: 'status',
  badgeStyles: {
    Active: { backgroundColor: '#008620', color: '#fff' },
    Pending: { backgroundColor: '#ff9800', color: '#fff' },
    Completed: { backgroundColor: '#0068ba', color: '#fff' },
    Failed: { backgroundColor: '#f44336', color: '#fff' }
  },
  cellTemplate: badgeRenderer
}
```

## Change Renderer
Highlights changes in data with visual cues such as arrows or color-coded indicators, helping users track trends or differences over time.

### Configuration
```typescript
{
  name: 'Change',
  prop: 'num',
  cellTemplate: changeRenderer
}
```

## Thumbs Renderer
Displays thumbs-up or thumbs-down icons to indicate approvals, votes, or boolean-like states in a simple and user-friendly format.

### Configuration
```typescript
{
  name: 'Thumbs',
  prop: 'thumbs',
  cellTemplate: thumbsRenderer
}
```

## Pie Chart Renderer
Renders pie charts inside cells to display proportional data distribution, ideal for visualizing parts of a whole within a dataset.

### Configuration
```typescript
{
  name: 'Pie',
  prop: 'trend',
  cellTemplate: pieChartRenderer
}
```

---

# Heatmap/Coldmap Feature

URL: https://pro.rv-grid.com/guides/cells/heatmap/
Source: src/content/docs/guides/cells/heatmap.mdx
Description: Enhance your RevoGrid with dynamic heatmap and coldmap visualizations.

The **Heatmap Feature** provides dynamic color-based visualizations for grid cells, making it easy to interpret numerical data at a glance. By mapping cell values to color gradients, this feature enhances data visibility and helps users quickly identify patterns.

---

### Key Highlights

- **Heatmap and Coldmap Modes**:
  - **Heatmap**: Red-to-green gradient for highlighting data intensity.
  - **Coldmap**: Shades of blue for cooler, more subtle visualizations.

- **Customizable Value Ranges**: Automatically normalizes values between a defined `minValue` and `maxValue`.

- **WCAG-Compliant Font Colors**: Ensures text remains readable by dynamically adjusting font color (black/white) based on the background's luminance.

---

### Example Configuration

To enable the heatmap feature, set a custom cell template on the desired column:

```javascript
import { heatmapRenderer } from './heatmap';

grid.columns = [
  {
    name: 'Score',
    prop: 'score',
    minValue: 0, // Minimum value for normalization
    maxValue: 100, // Maximum value for normalization
    colorMap: 'heatmap', // Choose 'heatmap' or 'coldmap'
    cellTemplate: heatmapRenderer, // Apply the heatmap renderer
  },
];
```

---

# Multi Renderer

URL: https://pro.rv-grid.com/guides/cells/multi-renderer/
Source: src/content/docs/guides/cells/multi-renderer.mdx
Description: Display different types of data in the same column using multiple renderers.

The Multi Renderer feature allows you to display different types of data in the same column using different renderers based on the data type. This creates a more flexible and dynamic way to present your data.

### Why Use Multi Renderer?

Multi Renderer is particularly useful when you want to:

- **Handle Mixed Data Types**: Display different types of data (numbers, dates, sliders) in the same column
- **Create Dynamic Presentations**: Automatically choose the best way to display each value
- **Improve Data Visualization**: Use appropriate visualizations for different data types

### Example Use Cases

- **Mixed Data Columns**: When a column contains different types of data (e.g., numbers, dates, percentages)
- **Dynamic Formatting**: Automatically format values based on their type or content
- **Conditional Rendering**: Show different visualizations based on data conditions

### How It Works

The Multi Renderer works by:

1. Defining a set of renderers with conditions that determine when to use them
2. For each cell value, checking the conditions to determine which renderer to use
3. Applying the appropriate renderer to display the data
4. If no condition matches, using a default renderer

### Configuration

To use Multi Renderer, configure your column with the appropriate renderers and conditions:

```typescript
import { MultiColumn } from '@revolist/revogrid-pro';
import { editorSlider, editorCheckbox } from '@revolist/revogrid-pro';
import NumberColumnType from '@revolist/revogrid-column-numeral';
import DateColumnType from '@revolist/revogrid-column-date';

const numberType = new NumberColumnType('0.00');
const dateType = new DateColumnType();

const grid = document.createElement('revo-grid');
grid.columnTypes = {
  multi: MultiColumn,
};

grid.columns = [
  {
    prop: 'data',
    name: 'Mixed Data',
    columnType: 'multi',
    multiColumn: {
      defaultRenderer: numberType.cellTemplate,
      defaultEditor: numberType.editor,
      renderers: [
        {
          // Use dateRenderer for date strings
          condition: (value) => value instanceof Date ||
            (typeof value === 'string' && !isNaN(Date.parse(value))),
          renderer: dateType.cellTemplate,
          editor: dateType.editor,
        },
        {
          // Use sliderRenderer for numbers between 0 and 100
          condition: (value) => typeof value === 'number' && value >= 0 && value <= 100,
          renderer: editorSlider,
          editor: editorSlider,
        },
        {
          // Use checkboxRenderer for boolean values
          condition: (value) => typeof value === 'boolean',
          renderer: editorCheckbox,
          editor: editorCheckbox,
        },
      ],
    },
  },
];
```

### Configuration Options

The MultiColumn configuration accepts the following options:

```typescript
interface MultiColumnConfig {
  /**
   * Default renderer to use if no condition matches
   */
  defaultRenderer: ColumnRegular['cellTemplate'];

  /**
   * Default editor to use if no condition matches
   */
  defaultEditor?: EditorCtr;

  /**
   * Array of renderers with conditions
   */
  renderers: Array<{
    /**
     * Condition function that returns true if the renderer should be used
     */
    condition: (value: any) => boolean;

    /**
     * Renderer to use if the condition is true
     */
    renderer: ColumnRegular['cellTemplate'];

    /**
     * Optional editor to use if the condition is true
     */
    editor?: EditorCtr;
  }>;
}
```

### Example Data

```typescript
const data = [
  { data: 42 },                    // Will use numberRenderer
  { data: new Date() },            // Will use dateRenderer
  { data: 75 },                    // Will use sliderRenderer
  { data: '2024-03-15' },          // Will use dateRenderer
  { data: true },                  // Will use checkboxRenderer
];
```

### Best Practices

1. **Order Matters**: Place more specific conditions before general ones
2. **Default Renderer**: Always provide a default renderer for unmatched cases
3. **Type Checking**: Use proper type checking in conditions
4. **Editor Matching**: Match editors with their corresponding renderers
5. **Performance**: Keep condition functions simple and efficient

### Common Patterns

#### Date Detection
```typescript
condition: (value) => value instanceof Date ||
  (typeof value === 'string' && !isNaN(Date.parse(value)))
```

#### Numeric Range
```typescript
condition: (value) => typeof value === 'number' && value >= 0 && value <= 100
```

#### Boolean Values
```typescript
condition: (value) => typeof value === 'boolean'
```

#### String Pattern
```typescript
condition: (value) => typeof value === 'string' && value.startsWith('http')
```

---

# Same Value Merge

URL: https://pro.rv-grid.com/guides/cells/same-value-merge/
Source: src/content/docs/guides/cells/same-value-merge.mdx
Description: Automatically merge cells with identical values in a column.

The Same Value Merge feature automatically combines cells in a column when they contain identical values. This creates a cleaner, more organized view of your data by visually grouping repeated values.

### Why Use Same Value Merge?

Same Value Merge is particularly useful when you want to:

- **Reduce Visual Clutter**: Hide repeated values in a column, making the data easier to read
- **Highlight Data Patterns**: Quickly identify groups of identical values
- **Improve Data Presentation**: Create a cleaner, more professional look for your grids

### Example Use Cases

- **Category Grouping**: When displaying items grouped by category, merge cells with the same category name
- **Status Display**: Merge cells with the same status to make state changes more apparent
- **Hierarchical Data**: Visually group related items in hierarchical data structures

### How It Works

The Same Value Merge plugin works by:

1. Checking each cell against the nearest comparable visible rows above and below it in columns marked with `merge: true`
2. If the values are identical, repeated values are hidden and internal borders are removed
3. This creates a visual effect of merged cells while maintaining the original data structure

When row grouping or Pivot row drill-down inserts group rows, those rows participate in the comparison only when they carry the merged column's value. Deeper group rows without that column value are skipped.

Same Value Merge is a visual merge. It does not create real merged grid ranges and does not change selection, focus, copy, or edit behavior. Use the Cell Merge plugin when you need explicit row or column spans.

### Configuration

To enable Same Value Merge for specific columns, set the `merge` property to `true` in your column configuration:

```javascript
const columns = [
  { prop: 'id', name: 'ID' },
  { prop: 'category', name: 'Category', merge: true }, // Enable merging for this column
  { prop: 'name', name: 'Name' }
];
```

### Sticky Merge Start Cells

Use `merge: { sticky: true }` when the first visible cell in a same-value run should stay visible while users scroll. This marks only the merge start cell as sticky; it does not pin every cell in that row.

```ts
import {
  SameValueMergePlugin,
  StickyCellsPlugin,
} from '@revolist/revogrid-pro';

const columns = [
  { prop: 'id', name: 'ID' },
  {
    prop: 'region',
    name: 'Region',
    merge: { sticky: true },
  },
  { prop: 'category', name: 'Category' },
];

grid.plugins = [SameValueMergePlugin, StickyCellsPlugin];
grid.columns = columns;
```

`SameValueMergePlugin` can register Sticky Cells automatically for `merge.sticky`, but adding `StickyCellsPlugin` explicitly keeps the dependency visible and matches the standalone Sticky Cells setup.

### Grouped Merge Boundaries

Some datasets need repeated values to merge only inside another column's run. For example, a `quantity` column may contain the same value across many rows, but it should stop merging when the controlling `workcenter` or operation changes.

Use a merge group with one leader column:

```javascript
const columns = [
  { prop: 'batch', name: 'Batch', merge: true },
  { prop: 'material', name: 'Material' },
  { prop: 'operationNo', name: 'Operation' },
  {
    prop: 'workcenter',
    name: 'Work Center',
    merge: {
      mergeGroup: 'operation',
      mergeLeader: true,
      mergeDependsOn: ['material', 'operationNo'],
    },
  },
  {
    prop: 'quantity',
    name: 'Quantity',
    merge: { mergeGroup: 'operation' },
  },
  {
    prop: 'tool',
    name: 'Tool',
    merge: { mergeGroup: 'operation' },
  },
];
```

`workcenter` is the leader for the `operation` group. It merges only while its own value, `material`, and `operationNo` all match. `quantity` and `tool` are followers: they still require their own values to match, but they cannot merge beyond the leader's boundary.

### Merge Configuration

```ts
type SameValueMergeConfig = {
  mergeGroup?: string;
  mergeLeader?: boolean;
  mergeDependsOn?: ColumnProp[];
  sticky?: boolean;
};
```

- `mergeGroup` connects columns that should share a leader boundary.
- `mergeLeader` marks the column that defines the boundary for a group.
- `mergeDependsOn` adds row fields that must match before the configured column can merge.
- `sticky` marks merge start cells for Sticky Cells. Only cells rendered as the start of a merge run become sticky.

If a column uses `merge: { mergeGroup: '...' }` and no matching leader is found, it falls back to ordinary same-value merge behavior.

---

# Sticky Cells

URL: https://pro.rv-grid.com/guides/cells/sticky-cells/
Source: src/content/docs/guides/cells/sticky-cells.mdx
Description: Pin selected row cells near the top after their source row starts scrolling out of view.

Sticky Cells keep important checkpoint cells visible while users scroll through a virtualized grid. Mark cells with `stickyCell`; when the row starts crossing the top visibility edge, the marked row renders through the pinned top row area and is trimmed from the main viewport until the next sticky row replaces it.

## Usage

Add `StickyCellsPlugin` to the grid and define a column `stickyCell` predicate.

```ts
import { StickyCellsPlugin } from '@revolist/revogrid-pro';

const stickyCell = ({ model }) => model.isCheckpoint === true;

const columns = [
  {
    name: 'Account',
    prop: 'account',
    stickyCell,
  },
  {
    name: 'Status',
    prop: 'status',
    stickyCell,
  },
];

grid.plugins = [StickyCellsPlugin];
```

If any cell in a row is marked as sticky, that row can become the active sticky row.

## With Other Header Plugins

Sticky Cells render through the header layer, so the plugin can be combined with grouped headers and filter headers. When using the filter header plugin, register filtering before sticky cells so Sticky Cells wraps the final header content:

```ts
import {
  AdvanceFilterPlugin,
  FilterHeaderPlugin,
  StickyCellsPlugin,
  ColumnStretchPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [
  AdvanceFilterPlugin,
  FilterHeaderPlugin,
  StickyCellsPlugin,
  ColumnStretchPlugin,
];

grid.filter = {};
grid.additionalData = {
  stretch: 'all',
};
```

## Behavior

- One sticky row is active by default. Set `stickyCells.maxRows` to keep multiple recent sticky rows pinned.
- A marked row becomes sticky once 10% of that source row has scrolled above the viewport top.
- Sticky cells work across `colPinStart`, `rgCol`, and `colPinEnd`.
- Custom `cellTemplate` output is reused in the pinned sticky row.
- Existing `pinnedTopSource` rows remain before plugin-managed sticky rows.
- Active sticky source rows are trimmed out of the main row viewport.
- Plugin-managed sticky pinned rows receive the `sticky-cells-pinned-row` class and attribute. They also expose `data-sticky-cells-pinned-row="true"`, `data-sticky-cells-source-index`, and `data-sticky-cells-mode`.

```css
revo-grid .sticky-cells-pinned-row {
  font-weight: 500;
}
```

`data-sticky-cells-mode` is `"row"` for ordinary Sticky Cells rows and `"cell"` for integrations that pin only selected cells, such as `merge: { sticky: true }` in Same Value Merge.

Sticky Cells are a display layer. Selection, editing, and focus behavior still belong to the underlying grid cells.

---

# Column Collapse

URL: https://pro.rv-grid.com/guides/columns/column-collapse/
Source: src/content/docs/guides/columns/column-collapse.mdx
Description: Make grouped columns collapsible with the ability to show/hide child columns

The Column Collapse plugin allows you to make grouped columns collapsible.
When a group is collapsed, only columns marked as "sealed" remain visible, while other columns are hidden.
If no sealed column exists, the group falls back to a single placeholder column that keeps the expand affordance visible.

## Features

- Add collapse/expand functionality to column groups
- Maintain "sealed" columns visible even when group is collapsed
- Fall back to a single placeholder column when no sealed child exists
- Support for nested column groups
- Customizable initial collapse state
- Smooth animations and intuitive UI

## Installation

The Column Collapse plugin is included in the RevoGrid Pro package. To use it, simply import and add it to your grid's plugins:

```javascript
import { ColumnCollapsePlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [ColumnCollapsePlugin];
```

## Usage

To make a column group collapsible:

1. Add the `collapsible` property to the group configuration
2. Mark important columns as `sealed` to keep them visible when collapsed
3. Optionally provide `placeholder` on the group to customize the fallback placeholder header or cell

```javascript
const grid = document.createElement('revo-grid');
grid.plugins = [ColumnCollapsePlugin];

// Configure columns with collapsible groups
grid.columns = [
  {
    id: 'personalInfo',
    name: 'Personal Information',
    collapsible: true, // Enable collapse for this group
    children: [
      {
        prop: 'name',
        name: 'Name',
        sealed: true // This column will stay visible when collapsed
      },
      {
        prop: 'email',
        name: 'Email'
      },
      {
        prop: 'phone',
        name: 'Phone'
      }
    ]
  },
  {
    id: 'addressInfo',
    name: 'Address',
    collapsible: true,
    children: [
      {
        prop: 'street',
        name: 'Street',
        sealed: true
      },
      {
        prop: 'city',
        name: 'City'
      },
      {
        prop: 'country',
        name: 'Country'
      }
    ]
  }
];

// Optional placeholder customization when no sealed column exists
grid.columns.push({
  name: 'Contact',
  collapsible: true,
  collapsed: true,
  placeholder: {
    header: 'Contact hidden',
    cellTemplate: (h) => h('span', undefined, 'Expand to view'),
  },
  children: [
    { prop: 'altEmail', name: 'Alt Email' },
    { prop: 'mobile', name: 'Mobile' },
  ],
});

// Sample data
grid.source = [
  {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '123-456-7890',
    street: '123 Main St',
    city: 'New York',
    country: 'USA'
  },
  // ... more rows
];
```

## Best Practices

1. Use `sealed` for essential columns that should always be visible
2. Keep group names concise to avoid UI clutter
3. Use `placeholder` when you want custom fallback content for groups without sealed children
4. Use nested groups sparingly to maintain clarity
5. Consider your users' needs when deciding which columns to make collapsible

The Column Collapse plugin helps manage complex data grids by allowing users to focus on relevant information while keeping essential data visible at all times.

---

# Column Hide

URL: https://pro.rv-grid.com/guides/columns/column-hide/
Source: src/content/docs/guides/columns/column-hide.mdx
Description: Implementing Column Hiding

RevoGrid provides the ability to hide specific columns in your grid, allowing you to focus on the most relevant data for your users.
This feature is particularly useful when working with large datasets where not all columns need to be visible at once.

`Column hiding` is a feature that allows you to hide specific columns in your grid, making them invisible to users. This is useful for:

- Focusing on specific data points
- Reducing visual clutter
- Creating different views of the same dataset
- Implementing column visibility toggles

The `ColumnHidePlugin` supports three ways to hide columns:

## Using the `hide-columns` attribute

You can specify which columns to hide using the `hide-columns` attribute on your RevoGrid element:

```html
<revo-grid hide-columns="name,age"></revo-grid>
```

## Using the `hideColumns` property

Framework wrappers typically bind properties instead of attributes:

```tsx
<RevoGrid hideColumns={['name', 'age']} />
```

You can also update it at runtime:

```javascript
grid.hideColumns = ['name', 'age'];
```

## Using `additionalData.hiddenColumns`

You can also hide columns programmatically using the `additionalData` property:

```javascript
const grid = document.querySelector('revo-grid');
grid.additionalData = {
  hiddenColumns: ['name', 'age']
};
```

This approach is particularly useful when you need to dynamically update which columns are hidden based on user interactions or application state.

## Events

The `ColumnHidePlugin` emits a `hiddencolumnsupdated` event whenever the hidden columns are updated:

```javascript
grid.addEventListener('hiddencolumnsupdated', (event) => {
  const { hiddenColumns } = event.detail;
  console.log('Hidden columns updated:', hiddenColumns);
});
```

This event can be used to synchronize the UI with the current state of hidden columns.

## Implementation Details

The `ColumnHidePlugin` works by:

1. Tracking which columns should be hidden in a `Set`
2. Updating the column visibility when the configuration changes
3. Preserving the hidden state when columns are updated
4. Supporting attribute, property, and programmatic configuration

---

# Column Move With Groups

URL: https://pro.rv-grid.com/guides/columns/column-move-with-groups/
Source: src/content/docs/guides/columns/column-move-with-groups.mdx
Description: Move grouped column headers without breaking the column-group structure.

`ColumnMoveAdvancedPlugin` enables drag-and-drop for grouped column headers. It builds on RevoGrid's core column move behavior and adds the group-aware rules needed for `ColumnGrouping` columns.

Use it when your grid has nested column groups and users need to reorder whole header bands without manually rebuilding the `columns` array.

## Setup

Import the plugin from `@revolist/revogrid-pro` and register it in the grid `plugins` array.

```ts
import { ColumnMoveAdvancedPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');

grid.plugins = [ColumnMoveAdvancedPlugin];
grid.columns = [
  {
    name: 'Personal Information',
    children: [
      { prop: 'firstName', name: 'First Name' },
      { prop: 'lastName', name: 'Last Name' },
      { prop: 'age', name: 'Age' },
    ],
  },
  {
    name: 'Address',
    children: [
      { prop: 'street', name: 'Street' },
      { prop: 'city', name: 'City' },
      { prop: 'country', name: 'Country' },
    ],
  },
];
```

`ColumnMoveAdvancedPlugin` extends the core `ColumnMovePlugin` implementation, so you do not need a separate column-move plugin entry for the common setup.

## Column Groups

Groups use the standard RevoGrid `ColumnGrouping` shape: a header object with a `name` and a `children` array. Children can be regular columns or another nested group.

```ts
grid.columns = [
  {
    name: 'Customer',
    children: [
      { prop: 'name', name: 'Name' },
      {
        name: 'Contact',
        children: [
          { prop: 'email', name: 'Email' },
          { prop: 'phone', name: 'Phone' },
        ],
      },
    ],
  },
  {
    name: 'Location',
    children: [
      { prop: 'city', name: 'City' },
      { prop: 'country', name: 'Country' },
    ],
  },
];
```

Leaf columns keep their normal column behavior: data binding, templates, sorting, filtering, resizing, and editing still belong to the regular column definitions.

## Move Behavior

Dragging a group header moves all leaf columns owned by that group as one block. During the drag, the drop indicator snaps to valid group boundaries instead of arbitrary leaf-column positions.

When the move completes, the plugin remaps the internal group indexes for every group level. This is the part plain `ColumnMovePlugin` does not handle for grouped headers.

Dragging an individual leaf column still works, but the plugin keeps the column inside its current group at the active grouping depth. This prevents a single leaf column from being dropped into a different group and leaving the header tree inconsistent.

Move a group by dragging the group header. Move a single leaf column by dragging the leaf header. Leaf-column moves are constrained to the compatible group area.

## Events

The plugin uses the standard column drag event names.

| Event | When it fires | Cancelable |
| --- | --- | --- |
| `columndragstart` | Before drag state is created. The detail is the dragged column or group data. | Yes |
| `beforecolumndragend` | Before the order is committed. The detail includes `startPosition`, `newPosition`, and moved items. | Yes |
| `columndragend` | After a successful drag flow finishes. | No |

```ts
grid.addEventListener('columndragstart', (event) => {
  const data = event.detail;

  if ('children' in data) {
    console.log('Group drag started:', data.name);
  }
});

grid.addEventListener('beforecolumndragend', (event) => {
  const { startPosition, newPosition } = event.detail;

  if (!canMoveColumns(startPosition, newPosition)) {
    event.preventDefault();
  }
});
```

## Framework Usage

For framework wrappers, pass the plugin class through the wrapper's `plugins` prop or input.

```tsx
import { RevoGrid } from '@revolist/react-datagrid';
import { ColumnMoveAdvancedPlugin } from '@revolist/revogrid-pro';

export function CustomerGrid({ rows, columns }) {
  return (
    <RevoGrid
      source={rows}
      columns={columns}
      plugins={[ColumnMoveAdvancedPlugin]}
    />
  );
}
```

```vue
<script setup lang="ts">
import { ColumnMoveAdvancedPlugin } from '@revolist/revogrid-pro';

const plugins = [ColumnMoveAdvancedPlugin];
</script>

<template>
  <RevoGrid :source="rows" :columns="columns" :plugins="plugins" />
</template>
```

## Compatibility

- Works with the standard nested `ColumnGrouping` structure.
- Supports nested group levels by remapping indexes across all group levels after a group move.
- Preserves regular leaf-column drag behavior, constrained to compatible group boundaries.
- Ignores row-header drag attempts.
- Uses the same `columndragstart`, `beforecolumndragend`, and `columndragend` event names as core column moving.

Use [Multi Row Headers](/guides/columns/multi-row-header/) when you need spreadsheet-style multi-level header spanning. Use [Column Collapse](/guides/columns/column-collapse/) when the same grouped headers should collapse or expand.

---

# Column Stretch

URL: https://pro.rv-grid.com/guides/columns/column-stretch/
Source: src/content/docs/guides/columns/column-stretch.mdx
Description: Implementing Column Stretching.

RevoGrid provides the ability to automatically adjust the width of columns to fit the table's width.
This is particularly useful when you have fewer columns than needed to enable the horizontal scrollbar, and you want to distribute the available space evenly or according to specific criteria.

In this article, we’ll walk you through the process of implementing column stretching in RevoGrid using the `ColumnStretchPlugin`. We'll also explore the different configurations available for stretching the columns.

## What is it?

`Column stretching` is a feature which allows you to automatically adjust the width of columns to fit the entire width of the table. The width of each column is calculated based on the number of columns and their respective sizes, ensuring the grid's width is fully utilized. This feature is especially useful when working with a small number of columns.

### Stretch Configurations

The Column Stretch plugin may conflict with other column size configurations. The following cases will prevent column stretching:

- Columns with explicit `size` property set
- Columns with `autoSize` enabled
- When the total width of all columns exceeds the available space (negative remaining width)

In these cases, the stretch configuration will be ignored for those specific columns to preserve their intended sizing behavior.

RevoGrid supports different types of stretch configurations through the `StretchConfig` type:

- **`'none'`**: No column stretching will be applied. Columns retain their default width.
- **`'last'`**: Only the last column will stretch to fill the remaining width.
- **`'all'`**: All columns will stretch evenly to fill the table's width.
- **`number`**: A specific column (by index) will stretch to fill the remaining width.

- To stretch only the last column:
  ```javascript
  grid.additionalData = { stretch: 'last' };
  ```

- To stretch a specific column by index (e.g., the second column):
  ```javascript
  grid.additionalData = { stretch: 1 };
  ```

- To stretch all columns evenly:
  ```javascript
  grid.additionalData = { stretch: 'all' };
  ```

By using the `ColumnStretchPlugin`, you can easily manage the width of columns in RevoGrid, making sure your table layout looks clean and is fully utilized. Whether you want to stretch all columns evenly or just the last one, this plugin offers flexibility to suit your needs.

Experiment with the different stretch configurations to see which works best for your data grid!

---

# Column Type Renderer

URL: https://pro.rv-grid.com/guides/columns/column-type-renderer/
Source: src/content/docs/guides/columns/column-type-renderer.mdx
Description: Show type icons in column headers with columnTypeRenderer.

`columnTypeRenderer` is a Pro column header template that displays an icon next to the header label based on the column's `columnType`.

Use it when users should quickly recognize typed fields, such as IDs, numeric values, currency amounts, decimals, booleans, or text columns. It is assigned through `columnTemplate`, while `columnType` tells the renderer which icon to show.

```typescript
import { columnTypeRenderer } from '@revolist/revogrid-pro';

grid.columns = [
  {
    prop: 'id',
    name: 'Identifier',
    columnType: 'id',
    columnTemplate: columnTypeRenderer,
  },
  {
    prop: 'amount',
    name: 'Amount',
    columnType: 'currency',
    columnTemplate: columnTypeRenderer,
  },
];
```

Supported built-in icons are selected for `id`, `integer`, `currency`, `decimal`, and `boolean`. Any other value, or a missing `columnType`, falls back to the string icon.

`columnTypeRenderer` only changes the column header rendering. Cell formatting, editing, validation, and export behavior still come from the column definition or from entries registered in `grid.columnTypes`.

---

# Multi Row Headers

URL: https://pro.rv-grid.com/guides/columns/multi-row-header/
Source: src/content/docs/guides/columns/multi-row-header.mdx
Description: Render spreadsheet-style multi-level headers from nested column groups.

The Multi Row Header plugin renders banded, multi-level headers from the same nested `ColumnGrouping` structure RevoGrid already uses for grouped columns. Use it when shallow leaf columns should fill the unused header depth while deeper branches continue to show stacked group bands.

This is the header-focused feature to use for AG Grid or DevExtreme-style multi-level headers. It is separate from `CellMergePlugin`, which only merges body and pinned data cells.

## Setup

```ts
import { MultiRowHeaderPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [MultiRowHeaderPlugin];
grid.multiRowHeader = true;
```

## Nested Columns

Define headers with the existing `children` column-group structure. Leaf columns still own data binding, sorting, filtering, editing, templates, and resizing.

```ts
grid.columns = [
  {
    name: 'Group A',
    children: [
      { name: 'Athlete 1', prop: 'athlete' },
      {
        name: 'Group B',
        children: [
          { name: 'Country 1', prop: 'country' },
          {
            name: 'Group C',
            children: [
              { name: 'Sport 1', prop: 'sport' },
            ],
          },
        ],
      },
    ],
  },
];
```

## Header Spanning

By default, shallow leaf headers span unused group rows. This matches the common spreadsheet behavior where a leaf header under a shallower branch fills the remaining vertical header space.

Disable spanning for a single column when you want balanced empty group space above the leaf:

```ts
grid.columns = [
  {
    name: 'Balanced',
    children: [
      {
        name: 'Flat Leaf',
        prop: 'flat',
        suppressSpanHeaderHeight: true,
      },
      {
        name: 'Nested',
        children: [{ name: 'Nested Leaf', prop: 'nested' }],
      },
    ],
  },
];
```

You can also disable spanning for the whole plugin:

```ts
grid.multiRowHeader = {
  spanLeafHeaders: false,
};
```

## Group Header Spanning

Set `spanHeaderHeight` on a column group when that group should fill every
remaining grouped-header row plus the leaf-header row:

```ts
grid.columns = [
  {
    name: 'January',
    spanHeaderHeight: true,
    children: [
      { name: 'Period Total', prop: 'januaryTotal' },
    ],
  },
  {
    name: 'February',
    children: [
      { name: 'Sales', prop: 'februarySales' },
      { name: 'Profit', prop: 'februaryProfit' },
    ],
  },
];
```

The descendant leaf remains the data column, but its header is covered by the
spanning group. Explicit group spans are independent of `spanLeafHeaders`.

Pivot uses this option for generated collapsed column groups. With
`MultiRowHeaderPlugin` enabled, the collapsed group label fills the remaining
header depth. Without it, the regular collapsed placeholder header remains
visible as a fallback.

When Pivot row-axis headers contain sorting, selection counts, or filter
controls, keep those leaf headers at their normal height while retaining
collapsed group spanning:

```ts
grid.multiRowHeader = {
  spanLeafHeaders: false,
};
```

`spanHeaderHeight` remains active because explicit group spanning is
independent of `spanLeafHeaders`.

## Configuration

```ts
grid.multiRowHeader = {
  spanLeafHeaders: true,
};
```

| Option | Default | Description |
| --- | --- | --- |
| `spanLeafHeaders` | `true` | Lets shallow leaf headers fill unused group depth. |

## Compatibility

- Works with nested `ColumnGrouping` definitions.
- Leaf headers keep sorting, filtering, custom templates, and resize behavior.
- Group headers continue through RevoGrid's normal group header render hooks.
- `ColumnCollapsePlugin` can be registered with `MultiRowHeaderPlugin` to add expand/collapse controls to groups.
- `spanHeaderHeight` lets a terminal group fill the remaining header depth while retaining its descendant data column.
- Pinned columns can split a group into pinned and unpinned visible bands, matching the behavior used by major data grids.

---

# Blank Values

URL: https://pro.rv-grid.com/guides/data-filter/blank-values/
Source: src/content/docs/guides/data-filter/blank-values.mdx
Description: Configure source-preserving blank semantics for Core and Pro filters without changing saved operator IDs.

RevoGrid filtering preserves the source value and own-property presence. It does
not implicitly turn `null`, `undefined`, `false`, `0`, arrays, or missing
properties into an empty display string before evaluating filters.

## Default policy

| Source state | Blank by default |
| --- | --- |
| `null` | Yes |
| Owned `undefined` | Yes |
| Exactly `""` | Yes |
| Missing own property | Yes |
| Whitespace-only string | No |
| `false` | No |
| `0` | No |
| `NaN` | No |
| `[]` | No |
| Non-empty array | No |
| Object or other value | No |

Only an own property counts as present. A value inherited through the row
prototype is treated as missing. `null` and `undefined` can both match **Is
blank** while remaining distinct raw values.

The stable saved-state IDs remain `empty` and `notEmpty`; no state migration is
required. Their default labels are **Is blank** and **Is not blank**, and **Is
not blank** is the exact inverse of the resolved blank predicate.

## Configuration and precedence

Set the grid policy in the filter configuration. A column can override any
individual field; resolution is Core defaults, then grid policy, then column
policy.

```ts
grid.filter = {
  blankSemantics: {
    whitespaceOnlyString: true,
    emptyArray: true,
    isBlank(value, context, fallbackResult) {
      // Final application override after the configured fallback.
      return value === 'N/A' || fallbackResult;
    },
  },
};

grid.columns = [{
  prop: 'tags',
  filter: ['array'],
  blankSemantics: {
    // Other fields continue to inherit from the grid policy.
    emptyArray: false,
  },
}];
```

The callback receives the raw source value, row model, column, property, parsed
value, own-property status, effective policy, and fallback result.

## Parsers and typed operators

A `cellParser` still supplies the value used by ordinary comparisons. Blank
evaluation uses the source value and missing-property context captured before
the parser runs.

Typed operators remain strict. `isTrue` matches only `true`; `isFalse` matches
only `false`; `isEmptyArray` and `isNotEmptyArray` match only arrays. Enabling
`emptyArray: true` intentionally allows `[]` to match both **Is blank** and **Is
empty array**. Invalid nonblank date values, including `false` and `NaN`, do not
match date comparisons and are not blank by default.

## Related guides

- [Array Filter](/guides/data-filter/filter-types/array-filter/)
- [Boolean Filter](/guides/data-filter/filter-types/boolean-filter/)
- [Date Filter](/guides/data-filter/filter-types/date-filter/)
- [Filter Expressions](/guides/data-filter/filter-expression/)

---

# Custom Filter Operators

URL: https://pro.rv-grid.com/guides/data-filter/custom-filter-operators/
Source: src/content/docs/guides/data-filter/custom-filter-operators.mdx
Description: Add application-specific filter predicates, value controls, parsed-value normalization, AST conditions, and remote filtering workflows.
Surface: grid

Use a custom filter operator when the standard text and number comparisons do not express an application rule. Custom operators use the Core `customFilters` configuration and work with both `FilterPlugin` and Pro's `AdvanceFilterPlugin`.

A custom operator has three parts:

1. A stable operator ID, used by saved filter state and Pro `FilterAst` conditions.
2. A `columnFilterType` identifying the column family that can show the operator.
3. A synchronous predicate that returns `true` when a row should remain visible.

## Quick start: add an operator to a built-in family

This operator appears with the ordinary string operators because its `columnFilterType` is `string` and the column uses `filter: 'string'`:

```ts
import type { LogicFunction } from '@revolist/revogrid';

const endsWithCode: LogicFunction = (value, expected) => {
  const suffix = String(expected ?? '')
    .trim()
    .toLowerCase();
  if (!suffix) return true;

  return String(value ?? '')
    .toLowerCase()
    .endsWith(suffix);
};
endsWithCode.extra = 'input';

grid.columns = [
  { prop: 'sku', name: 'SKU', filter: 'string' },
  { prop: 'name', name: 'Product', filter: 'string' },
];
grid.filter = {
  customFilters: {
    endsWithCode: {
      columnFilterType: 'string',
      name: 'Ends with code',
      func: endsWithCode,
    },
  },
};
```

Open the SKU filter, choose **Ends with code**, and enter a suffix. Returning `true` for an empty input keeps dynamic editing from temporarily hiding every row.

Use a custom family when an operator should appear only on explicitly opted-in columns:

```ts
const matchesPriority: LogicFunction = (value, expected) =>
  !expected || String(value).toLowerCase() === String(expected).toLowerCase();
matchesPriority.extra = 'input';

grid.columns = [
  { prop: 'priority', name: 'Priority', filter: 'ticketPriority' },
];

grid.filter = {
  customFilters: {
    matchesPriority: {
      columnFilterType: 'ticketPriority',
      name: 'Matches priority',
      func: matchesPriority,
    },
  },
};
```

The family ID must match exactly. An operator registered for `ticketPriority` is not offered by a column configured with `filter: 'string'`.

## Choose the value control

Set `func.extra` to tell the standard filter panel how to collect the operator value:

| `func.extra`    | Panel control                     | Typical use                                        |
| --------------- | --------------------------------- | -------------------------------------------------- |
| `'input'`       | Text input                        | Codes, thresholds, and search values               |
| `'datepicker'`  | Native date input                 | One calendar-date value                            |
| Render function | Application-defined VNode content | Selects or compound values                         |
| Omitted         | No value control                  | Valueless rules whose predicate ignores `expected` |

For example, change the quick-start operator to a date input without replacing the filter panel:

```ts
const onOrAfter: LogicFunction = (value, expected) => {
  if (!expected) return true;
  return new Date(value).getTime() >= new Date(String(expected)).getTime();
};
onOrAfter.extra = 'datepicker';
```

A custom renderer receives the current value and controlled callbacks. Call `onInput()` with the next filter value; do not mutate the filter item directly:

```ts
import type { ExtraField } from '@revolist/revogrid';

const priorityControl: ExtraField = (h, context) =>
  h(
    'select',
    {
      value: context.value ?? '',
      onInput: (event: Event) =>
        context.onInput((event.target as HTMLSelectElement).value),
      onFocus: context.onFocus,
    },
    [
      h('option', { value: '' }, 'Any priority'),
      h('option', { value: 'low' }, 'Low'),
      h('option', { value: 'high' }, 'High'),
    ],
  );

matchesPriority.extra = priorityControl;
```

Use `include` only when the entire filter popup should be restricted to a known list of operator IDs. It is global to the filter configuration, so omitting another required built-in or custom ID removes that operation from the available families.

## Parsed values and evaluation context

RevoGrid calls a predicate as `func(parsedValue, conditionValue, context)`. When the column defines `cellParser`, both built-in and custom comparisons receive its result:

```ts
const within: LogicFunction = (value, expected) => {
  const target = Number(expected);
  return !Number.isFinite(target) || Math.abs(Number(value) - target) <= 5;
};
within.extra = 'input';

grid.columns = [
  {
    prop: 'price',
    name: 'Price',
    filter: 'number',
    cellParser: (model) =>
      Number(String(model.price ?? '').replace(/[^0-9.-]/g, '')),
  },
];
grid.filter = {
  customFilters: {
    withinFive: {
      columnFilterType: 'number',
      name: 'Within 5',
      func: within,
    },
  },
};
```

Use `cellParser` for reusable normalization rather than repeating source conversion in every predicate. The optional third argument provides source-aware details when a rule needs them:

```ts
const isOriginalNull: LogicFunction = (_value, _expected, context) =>
  context?.hasOwnProperty === true && context.sourceValue === null;
```

The context includes `model`, `column`, `property`, `sourceValue`, `parsedValue`, `hasOwnProperty`, and the resolved blank policy. Ordinary custom predicates receive `parsedValue`; Core blank operators intentionally use the original source value. See [Blank Values](/guides/data-filter/blank-values/) for that distinction.

## Restore and combine custom conditions

Use the operator ID in the same compatible state model as a built-in condition:

```ts
grid.filter = {
  customFilters: {
    endsWithCode: {
      columnFilterType: 'string',
      name: 'Ends with code',
      func: endsWithCode,
    },
  },
  multiFilterItems: {
    sku: [
      {
        id: 1,
        type: 'endsWithCode',
        value: '-EU',
        relation: 'and',
      },
    ],
  },
};
```

Keep `customFilters` present whenever restoring its conditions. Unknown operation IDs cannot be evaluated and are not a portable replacement for registering the predicate.

## Use the operator in Filter AST

Pro accepts an application-defined AST operator only when the same ID is registered in `customFilters`. The condition value must also be JSON-safe:

```ts
import { AdvanceFilterPlugin } from '@revolist/revogrid-pro';

grid.plugins = [AdvanceFilterPlugin];
grid.filter = {
  customFilters: {
    endsWithCode: {
      columnFilterType: 'string',
      name: 'Ends with code',
      func: endsWithCode,
    },
  },
};

const plugins = await grid.getPlugins();
const filter = plugins.find(
  (plugin) => plugin instanceof AdvanceFilterPlugin,
) as AdvanceFilterPlugin;

await filter.setFilterAst({
  type: 'condition',
  field: 'sku',
  operator: 'endsWithCode',
  valueType: 'string',
  value: '-EU',
});
```

Registering the predicate supplies both validation and execution for that custom AST operator. Without the registration, `setFilterAst()` rejects the tree as containing an unknown operator and leaves the previous filter active.

## Predicate or structured filter type?

| Requirement                                                                                    | Extension point                                                 |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Add one Boolean row test using the standard condition UI                                       | `customFilters` predicate                                       |
| Normalize stored data for several operators                                                    | Column `cellParser`                                             |
| Add a small input, date, or custom field beside one condition                                  | `func.extra`                                                    |
| Build a purpose-specific Pro popup body that owns several operators or a structured JSON value | `StructuredFilterType` plus matching `customFilters` predicates |
| Load the filtered dataset from a backend                                                       | Cancel `beforefilterapply` and reload `source`                  |

A custom structured type does not replace its evaluator. Its `operatorIds` define the UI-owned conditions, while matching `customFilters` entries define how those conditions evaluate. See [Custom Structured Filter Types](/guides/data-filter/structured-filter-types/) for the registry and commit contract.

## Keep asynchronous work outside predicates

Predicates are synchronous and may run once per row for every active condition. Keep them pure and fast: avoid requests, DOM work, shared-state mutation, and large allocations. Declaring a predicate `async` returns a `Promise`, not a deferred Boolean result, and therefore does not implement asynchronous filtering.

When the backend owns filtering, cancel local evaluation synchronously in `beforefilterapply`, serialize the requested state, and let the application's data controller replace the source:

```ts
let latestRequest = 0;

grid.addEventListener('beforefilterapply', (event) => {
  event.preventDefault();
  const request = ++latestRequest;
  const detail = (
    event as CustomEvent<{ filterItems: Record<string, unknown[]> }>
  ).detail;

  void fetch('/api/orders/filter', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(detail.filterItems),
  })
    .then((response) => response.json())
    .then((rows) => {
      if (request === latestRequest) grid.source = rows;
    });
});
```

Production controllers should also cancel stale requests and guard source replacement from triggering the same remote request again. For Pro, prefer the canonical `FilterAst` payload when the query can contain cross-column OR, nested groups, or NOT. See [Filter Events](/guides/data-filter/filter-events/) for a guarded remote example.

The direct `JSON.stringify()` above is appropriate for this scalar custom value. Compatible filter state from other filter families can contain values such as `Set`; use the persistence guidance in [Filter State and Presets](/guides/data-filter/filter-state/) before treating arbitrary `multiFilterItems` as a wire payload.

## Common mistakes

- Registering the operator under `customFilters` but using a different `columnFilterType` from the column's `filter` value.
- Forgetting `func.extra`, then expecting the standard popup to render an input.
- Returning a truthy `Promise` from an `async` predicate instead of handling remote work through `beforefilterapply`.
- Filtering formatted source strings in every predicate instead of normalizing once with `cellParser`.
- Mutating rows, filter state, or external state from a predicate that can run many times.
- Restoring a custom `multiFilterItems` or `FilterAst` operator without registering its predicate first.
- Using a custom renderer for a complete multi-operator popup experience; use a structured filter type for that scope.
- Putting `Date`, `Set`, functions, cycles, or non-finite numbers in a public `FilterAst` value; AST input must be JSON-safe.

## Related guides

- [Filtering Quick Start](/guides/data-filter/filter-basics/)
- [Filter State and Presets](/guides/data-filter/filter-state/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Custom Structured Filter Types](/guides/data-filter/structured-filter-types/)
- [Filter Events](/guides/data-filter/filter-events/)
- [Core filtering guide](https://rv-grid.com/guide/filters#create-a-custom-filter)

---

# Canonical Filter AST

URL: https://pro.rv-grid.com/guides/data-filter/filter-ast/
Source: src/content/docs/guides/data-filter/filter-ast.mdx
Description: Build, validate, edit, persist, and transport one canonical RevoGrid Pro filter tree.
Surface: grid

`FilterAst` is RevoGrid Pro's validated, JSON-safe Boolean filter tree. Use the same tree for local row evaluation, the grouped visual editor, saved views, and remote requests.

New to ASTs? Start with [What Is a Filter AST?](/guides/data-filter/what-is-filter-ast/) for a plain-language explanation, business use cases, and a smaller first example. This page is the complete technical contract.

> **Choose the simplest state model that fits.** Use `multiFilterItems` for ordinary per-column filtering and existing column controls. Use `FilterAst` for cross-column `OR`, nested groups, `NOT`, canonical saved views, or a transport-safe remote query. Canonical execution requires `AdvanceFilterPlugin`; Core `FilterPlugin` remains the right choice for ordinary Core filtering.

## Try the complete lifecycle

Start with **Nested routing**, inspect the effective tree and transport envelope, then type a quick search and apply another preset with **Preserve quick search** off and on. **Projectable** demonstrates a tree that ordinary column controls can reopen. **Try invalid AST** proves that validation leaves the active tree and visible rows unchanged. Open any column filter and select **Groups** to edit the canonical tree visually.

## Register the Pro plugin

```ts
import { AdvanceFilterPlugin, type FilterAst } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.filter = { groupedFilter: {} }; // optional Groups launcher
grid.columns = columns;
grid.source = rows;

const plugin = (await grid.getPlugins()).find(
  (item) => item instanceof AdvanceFilterPlugin,
) as AdvanceFilterPlugin;
```

Retrieve the runtime plugin from `await grid.getPlugins()`. Do not attach application callbacks or custom methods to the grid element.

## Build a tree

A condition is the smallest tree:

```ts
const openTickets: FilterAst = {
  type: 'condition',
  field: 'status',
  operator: 'equal',
  valueType: 'string',
  value: 'Open',
};
```

Join children with `and` or `or`, then negate any subtree with `not`:

```ts
const routingRule: FilterAst = {
  type: 'group',
  operator: 'or',
  children: [
    {
      type: 'group',
      operator: 'and',
      children: [
        openTickets,
        {
          type: 'condition',
          field: 'priority',
          operator: 'greaterThanOrEqual',
          valueType: 'number',
          value: 3,
        },
      ],
    },
    {
      type: 'not',
      child: {
        type: 'condition',
        field: 'vip',
        operator: 'isTrue',
        valueType: 'boolean',
      },
    },
  ],
};
```

Groups must contain at least one child. Evaluation short-circuits: `and` stops on the first false child, and `or` stops on the first true child.

## Node and value contract

| Node        | Required shape                                 | Meaning                                                                |
| ----------- | ---------------------------------------------- | ---------------------------------------------------------------------- |
| `condition` | `{ type, field, operator, valueType, value? }` | Evaluates one field. `field` accepts a string or numeric `ColumnProp`. |
| `group`     | `{ type, operator: 'and' \| 'or', children }`  | Joins one or more subtrees.                                            |
| `not`       | `{ type, child }`                              | Negates exactly one subtree.                                           |

`valueType` is one of `string`, `number`, `boolean`, `date`, `datetime`, `array`, or `unknown`. It describes the operand representation; it does not cast source values. Validation enforces scalar/date/datetime representations directly, while `array` and `unknown` rely on the selected operator's shape rules plus JSON safety. Values may contain only finite JSON primitives, arrays, and plain objects. Public input rejects functions, `undefined` operands, `Date`, `Set`, cycles, non-plain objects, and `NaN`/infinities.

- Date operands use `YYYY-MM-DD`.
- Ordinary datetime operands use UTC ISO strings ending in `Z`, such as `2026-09-03T08:30:00Z`.
- Use `unknown` for an opaque, JSON-safe structured operand. It does not disable JSON validation.
- Omit `evaluationMode` in application-authored canonical state. `selectionExclusion`, `dateObject`, `coercedNumericRange`, and `localTemporal` are compatibility metadata emitted when older UI/config models need evaluator-specific behavior.

When `field` matches a grid column, the local evaluator uses the column's parsed cell value. A field without a column reads the raw row property, which makes hidden model fields usable without adding hidden grid columns.

## Built-in operator reference

Every ID below is exported through `CANONICAL_FILTER_OPERATORS`.

| Family                 | Operators                                                                                  | `valueType` and operand                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Text and equality      | `equal`, `notEqual`, `beginsWith`, `contains`, `quickContains`, `notContains`              | Usually `string`; one required JSON value matching the declared type. Equality may use another declared scalar type. |
| Ordered and numeric    | `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`                         | Usually `number`; one required finite number.                                                                        |
| Range                  | `between`                                                                                  | Usually `number`; a required two-item array. Numeric row values are strict in canonical mode.                        |
| Membership             | `in`, `notIn`                                                                              | `array`; a required array. An empty array is structurally valid.                                                     |
| Blank, Boolean, array  | `isBlank`, `isNotBlank`, `isTrue`, `isFalse`, `isEmptyArray`, `isNotEmptyArray`            | No operand. Keep the field's semantic `valueType`, but omit `value`.                                                 |
| Explicit date/datetime | `dateEquals`, `dateBefore`, `dateAfter`, `dateOnOrBefore`, `dateOnOrAfter`, `dateNotEqual` | `date` or `datetime`; one required date/datetime string.                                                             |
| Date range             | `dateBetween`                                                                              | `date` or `datetime`; a required two-item array of valid date/datetime strings.                                      |
| Relative day/window    | `today`, `yesterday`, `last7Days`, `next30Days`                                            | `date` or `datetime`; omit `value`.                                                                                  |
| Relative week/month    | `thisWeek`, `lastWeek`, `nextWeek`, `thisMonth`, `lastMonth`                               | `date` or `datetime`; omit `value`.                                                                                  |
| Relative quarter/year  | `thisQuarter`, `nextQuarter`, `previousQuarter`, `thisYear`, `nextYear`, `previousYear`    | `date` or `datetime`; omit `value`.                                                                                  |
| Fiscal quarter         | `thisFiscalQuarter`, `nextFiscalQuarter`, `previousFiscalQuarter`                          | `date` or `datetime`; omit `value`.                                                                                  |
| Fiscal year            | `thisFiscalYear`, `nextFiscalYear`, `previousFiscalYear`                                   | `date` or `datetime`; omit `value`.                                                                                  |

Important operator boundaries:

- Valueless operators must omit `value`. Even `value: ''` is rejected.
- Canonical `in`/`notIn` use strict `Object.is` membership; an array cell matches when any member matches. `selectionExclusion` is a normalized, exclusion-oriented compatibility mode and is not the same contract as hand-authored canonical `notIn`.
- Numeric `between` accepts only numeric row values in canonical mode. Blank-like values and numeric strings are not numbers. Compatibility state may carry `coercedNumericRange` to preserve older slider behavior.
- `quickContains` is the canonical form of global quick search and retains quick-filter string coercion. Use ordinary `contains` for Core text-filter semantics.
- Relative operators use one `now` captured for the whole apply operation plus the resolved IANA timezone and fiscal policy. See [Date Filter](/guides/data-filter/filter-types/date-filter/) and [Datetime Filter](/guides/data-filter/filter-types/datetime-filter/) for temporal policy.
- A custom or structured operator ID is valid only when the resolved plugin configuration registers its evaluator. Its operand must still be JSON-safe.

## Apply, read, initialize, and clear

```ts
await plugin.setFilterAst(routingRule);
const effective = plugin.getFilterAst(); // defensive clone
await plugin.setFilterAst(undefined); // clear canonical state
```

`setFilterAst()` validates first and replaces the tree atomically. `getFilterAst()` returns a defensive clone of the effective tree, including an applied quick-filter branch. Mutating either the input object after application or a returned object does not update grid state; construct a replacement and call `setFilterAst()` again.

For initial state, assign the AST through `grid.filter`:

```ts
grid.filter = {
  filterAst: routingRule,
  multiFilterItems: previousColumnState,
  collection: legacyCollection,
};
```

When `filterAst`, `multiFilterItems`, and `collection` coexist, `filterAst` wins.

## Projectable and canonical-only trees

`projectable` means “can be represented as `MultiFilterItem` column controls,” not “valid.” A root `and` with independent single-field clauses can usually project:

```json
{
  "type": "group",
  "operator": "and",
  "children": [
    {
      "type": "condition",
      "field": "status",
      "operator": "equal",
      "valueType": "string",
      "value": "Open"
    },
    {
      "type": "condition",
      "field": "priority",
      "operator": "greaterThan",
      "valueType": "number",
      "value": 2
    }
  ]
}
```

A cross-field `or`, `not`, or unsupported shape remains canonical-only:

```json
{
  "type": "group",
  "operator": "or",
  "children": [
    {
      "type": "condition",
      "field": "status",
      "operator": "equal",
      "valueType": "string",
      "value": "Open"
    },
    {
      "type": "not",
      "child": {
        "type": "condition",
        "field": "vip",
        "operator": "isTrue",
        "valueType": "boolean"
      }
    }
  ]
}
```

Both trees are locally executable and transport-safe. Only the first can round-trip through ordinary independent column controls.

## Enable the visual grouped editor

```ts
grid.filter = { groupedFilter: {} };
```

`groupedFilter` opts the filter popup into a **Groups** launcher. The editor supports nested groups, `NOT`, rule reordering, rule/text mirrors, validation, preview counts, **Apply**, **Cancel**, and **Reset**. Edits are transactional: Apply replaces the active tree, Cancel leaves it untouched, and Reset clears the draft until applied.

Local preview counts stop at 25,000 eligible rows. For partial or remote data, never present the loaded page as the full dataset:

```ts
grid.filter = {
  groupedFilter: {
    remote: true,
    preview: async ({ ast, signal }) => {
      const response = await fetch('/tickets/filter-preview', {
        method: 'POST',
        signal,
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ filter: ast }),
      });
      return response.json() as Promise<{ matching: number; total: number }>;
    },
  },
};
```

The callback receives an `AbortSignal`; abort superseded requests and let abort errors propagate normally. `remote: true` without a callback displays a remote preview label rather than a misleading local total.

## Save, restore, and update by replacement

```ts
const saved = JSON.stringify(plugin.getFilterAst());
localStorage.setItem('ticket-filter', saved);

try {
  const json = localStorage.getItem('ticket-filter');
  await plugin.setFilterAst(json ? JSON.parse(json) : undefined);
} catch (error) {
  console.error('The saved filter is invalid.', error);
}
```

To update one part, clone/build the next tree and reapply it:

```ts
const current = plugin.getFilterAst();
if (current?.type === 'group') {
  await plugin.setFilterAst({
    ...current,
    children: [...current.children, anotherCondition],
  });
}
```

Do not mutate applied or returned objects. Compatibility conversion helpers preserve today's existing filter behavior, but they are not a guarantee that every future Pro operator will losslessly round-trip through an older saved-view schema. Persist the canonical tree you actually apply.

## Compose quick search

```ts
grid.quickFilter = { text: 'timeout', debounceMs: 0 };
await plugin.setFilterAst(routingRule);
// Default: clears the current or pending quick filter.

grid.quickFilter = { text: 'timeout', debounceMs: 0 };
await plugin.setFilterAst(routingRule, { preserveQuickFilter: true });
// Effective tree is routingRule AND the generated quickContains branch.
```

`getFilterAst()` returns that effective composition. Preserve mode uses the latest applied or pending `grid.quickFilter` value.

## Events and remote ownership

`filterastchange` fires immediately before the existing cancelable `beforefilterapply` event. Its detail contains `{ filterAst, executionContext, origin, projectable }`; `origin` is `config`, `api`, `ui`, `quickFilter`, or `clear`.

```ts
import type {
  FilterAstChangeEventDetail,
  FilterExecutionContext,
} from '@revolist/revogrid-pro';

type FilterRequest = {
  filter: FilterAstChangeEventDetail['filterAst'];
  context: FilterExecutionContext;
};
let request: FilterRequest | undefined;

grid.addEventListener('filterastchange', (event) => {
  const { filterAst, executionContext, origin, projectable } = event.detail;
  request = { filter: filterAst, context: executionContext };
  console.log({ origin, projectable, request });
});

grid.addEventListener('beforefilterapply', (event) => {
  // This event carries matching filterAst/executionContext semantic inputs.
  // Cancel when the remote datasource owns filtering and row replacement.
  event.preventDefault();
  void fetch('/tickets/search', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(request),
  });
});
```

`executionContext` contains one ISO `now`, an IANA `timeZone`, and JSON-safe resolved blank semantics per column. A non-serializable custom `isBlank` callback appears only as `customEvaluator: true`; the backend must implement an equivalent policy. RevoGrid intentionally does not compile AST to SQL, REST, or GraphQL—that translation belongs to the application/backend boundary.

## Atomic validation and diagnostics

Invalid input rejects without partially updating rows or state:

```ts
grid.addEventListener('filterasterror', (event) => {
  const { attemptedAst, diagnostics, origin } = event.detail;
  console.table(diagnostics); // [{ path, code, message }]
  reportInvalidSavedView({ attemptedAst, diagnostics, origin });
});

try {
  await plugin.setFilterAst({
    type: 'group',
    operator: 'and',
    children: [],
  } as FilterAst);
} catch {
  // Previous AST and visible rows are still active.
}
```

Paths use JSONPath-like locations such as `$.children[0].value`.

| Code                     | Cause                                                                     |
| ------------------------ | ------------------------------------------------------------------------- |
| `invalid-node`           | A node is not an object.                                                  |
| `max-depth`              | Nesting exceeds 100 levels.                                               |
| `cycle`                  | The AST node graph contains a cycle.                                      |
| `invalid-group-operator` | A group operator is not `and` or `or`.                                    |
| `empty-group`            | A group has no children.                                                  |
| `missing-child`          | A `not` node has no child.                                                |
| `invalid-discriminator`  | `type` is not `condition`, `group`, or `not`.                             |
| `invalid-field`          | `field` is not a string or number.                                        |
| `invalid-operator`       | `operator` is missing or empty.                                           |
| `unknown-operator`       | No built-in or registered evaluator matches the ID.                       |
| `invalid-value-type`     | `valueType` is not supported.                                             |
| `unexpected-value`       | A valueless operator received `value`.                                    |
| `missing-value`          | A value-taking operator omitted `value`.                                  |
| `invalid-array-value`    | A range is not a two-item array, or membership is not an array.           |
| `value-type-mismatch`    | The operand does not match its declared type.                             |
| `non-finite-number`      | A number is `NaN` or infinite.                                            |
| `non-json-value`         | A value contains a function, `undefined`, or another non-JSON value.      |
| `value-cycle`            | An operand array/object contains a cycle.                                 |
| `non-plain-object`       | An operand is a class instance, `Date`, `Set`, or other non-plain object. |

Registered structured filter types may also return `invalid-structured-value` when their own operand validator rejects a value.

## Parsed fields, blanks, dates, and custom operators

Parsed columns evaluate their parsed cell value; hidden/raw model fields evaluate the raw property. Blank operators additionally preserve Core's source identity, property-presence check, and resolved grid/column blank policy. If local policy uses `blankSemantics.isBlank`, remote code sees `customEvaluator: true` and must reproduce it.

Relative time uses the operation's captured clock rather than calling `new Date()` for every row. Configure timezones, week starts, and fiscal periods through the [Date Filter](/guides/data-filter/filter-types/date-filter/) and [Datetime Filter](/guides/data-filter/filter-types/datetime-filter/) settings.

Register an evaluator before applying its canonical ID:

```ts
grid.filter = {
  customFilters: {
    riskAtLeast: {
      columnFilterType: 'number',
      name: 'Risk at least',
      func: (value, operand) => {
        const minimum = Number((operand as { minimum: number }).minimum);
        return typeof value === 'number' && value >= minimum;
      },
    },
  },
};

await plugin.setFilterAst({
  type: 'condition',
  field: 'internalRisk', // not a displayed column
  operator: 'riskAtLeast',
  valueType: 'unknown',
  value: { minimum: 7 },
});
```

Custom predicates run synchronously in the filtering hot path. Keep them pure: avoid DOM access, requests, mutation, and avoidable allocation. Group ordering matters for short-circuit performance, so put cheap/selective clauses early when practical. A remote or virtual datasource must evaluate the canonical request against the whole backend dataset—not only the page currently loaded in the browser.

## Common mistakes

- Using `FilterAst` for a simple column filter that `multiFilterItems` already represents.
- Supplying `value: ''` to a valueless operator instead of omitting `value`.
- Expecting `valueType` to cast source data.
- Sending `Date`, `Set`, `undefined`, non-finite numbers, class instances, or cyclic objects.
- Treating `projectable: false` as invalid instead of canonical-only.
- Mutating the original or returned AST instead of applying a replacement.
- Forgetting that `setFilterAst()` clears quick search unless preservation is requested.
- Evaluating only the currently loaded page for a remote dataset.
- Translating relative dates remotely without the event's exact execution context.

Continue with [What Is a Filter AST?](/guides/data-filter/what-is-filter-ast/) for the conceptual and business overview, [Filtering Quick Start](/guides/data-filter/filter-basics/) for column-state basics, [Advanced Filtering Overview](/guides/data-filter/filter-showcase/) for the wider Pro filtering surface, [Filter State and Presets](/guides/data-filter/filter-state/) for view persistence, [Filter Events](/guides/data-filter/filter-events/) for lifecycle integration, and [Custom Filter Operators](/guides/data-filter/custom-filter-operators/) for custom UI and evaluator patterns.

---

# Filter AST Side Panel

URL: https://pro.rv-grid.com/guides/data-filter/filter-ast-side-panel/
Source: src/content/docs/guides/data-filter/filter-ast-side-panel.mdx
Description: Mount RevoGrid Pro's canonical grouped filter editor in an application side panel.
Surface: grid

<style>{`
  :root {
    --sl-content-width: 67.5rem;
  }
`}</style>

The grouped Filter AST editor is not limited to a column popup. Mount the same editor in a persistent side panel, drawer, or inspector and keep the grid plugin responsible for configured fields and operators, validation, preview, and applying the canonical tree.

Resolve the installed plugin after the grid initializes, mount the editor into a connected host, and destroy the returned handle with your framework component:

```ts
const plugin = (await grid.getPlugins()).find(
  item => item instanceof AdvanceFilterPlugin,
);

const editor = plugin.mountFilterAstEditor(editorHost, {
  preset: 'fixed-list',
  conditionSlots: initialAst.children,
});

// Component teardown
editor.destroy();
```

When the mounted editor is the only filtering surface, set
`filter.columnFilterButton` to `false`. This removes the compact button and its
hover/focus layout reservation from every column header while leaving filtering,
the active AST, and the mounted editor enabled.

The `fixed-list` preset accepts a flat root **AND** tree of predeclared conditions. Pass those definitions as `conditionSlots` so their field and predicate remain visible after clearing. Fields stay fixed, while each predicate badge can select another operator supported by that column. Each active row has a compact, accessible clear action. Clearing removes its value from the draft and omits the condition from the canonical AST; entering or selecting a new valid value applies it again. A cleared valueless predicate, such as “VIP is false,” makes its predicate badge the explicit Apply action. **Clear all** clears every slot, applies `undefined`, and restores every grid row without removing the predefined controls.

Choose reusable value controls in the column configuration. The example renders
Priority’s compatible scalar numeric predicates with the shared single-value
slider without adding editor configuration at the mount site:

```ts
{
  name: 'Priority',
  prop: 'priority',
  filter: 'number',
  filterAstValueEditor: { kind: 'slider', min: 1, max: 5, step: 1 },
}
```

Omitted slider bounds are derived from the grid source. Use mount-level
`valueEditors` only when a particular surface needs a field- or
field/operator-specific override; those overrides take precedence over the
column default without changing the canonical predicate.

The preset keeps each field fixed as a plain anchor, presents each read-only operator phrase as a compact theme-aware badge, exposes only the configured value editor, omits placeholder boxes for operators that need no value, and applies effective changes after a short debounce. Builder chrome, grouping, add/remove/reorder actions, mode switch, and footer are intentionally absent. `editor.reset(ast)` remains the explicit synchronization boundary: it maps conditions in the supplied effective AST back onto the stable slots and clears omitted slots. Successful changes continue through the existing `filterastchange` event.

Use the default `builder` preset for the complete nested AND/OR/NOT rule builder, or `read-only` to inspect a tree without mutation. Nested configuration can override structure, capabilities, presentation, workflow, and interaction independently; incompatible flat trees are rejected rather than silently flattened.

This surface reuses the grouped editor's configured operators, selection sources, structured filter mounts, localization, validation, preview, and canonical apply path. It does not embed every complete classic per-column popup; reusable controls converge through the same lower-level filter contracts.

The mounted editor belongs to its application host and inherits the public `--rv-filter-ast-editor-*` variables defined there. Use `surface-bg`, `surface-color`, `control-bg`, `text-color`, and the corresponding `control-border`, `divider`, `active-*`, or `muted-color` variables to align it with the surrounding application theme. Unset variables use the editor's standalone defaults.

For the underlying model and business case, read [What Is a Filter AST?](/guides/data-filter/what-is-filter-ast/). For the complete API and operator contract, continue with [Canonical Filter AST](/guides/data-filter/filter-ast/).

---

# Filter Badges

URL: https://pro.rv-grid.com/guides/data-filter/filter-badges/
Source: src/content/docs/guides/data-filter/filter-badges.mdx
Description: Show synchronized active-filter badges, customize their labels and details, or replace their complete rendering.
Surface: grid

Filter badges give users an always-visible summary of the active filter model. `AdvanceFilterPlugin` owns the badge list, refreshes it when filters change, and routes remove and clear actions through the same filtering workflow as the popup and programmatic APIs.

## Quick start

Register `AdvanceFilterPlugin`, then enable its plugin-owned badge list through the grid property:

```typescript
import { AdvanceFilterPlugin } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.filter = true;
grid.filterBadges = true;
```

The plugin mounts the list in the grid's header slot. Set `grid.filterBadges = false` to remove it. You can also assign an options object instead of `true`:

```typescript
grid.filterBadges = {
  ariaLabel: 'Order filters',
  emptyLabel: 'All orders are visible',
  className: 'order-filter-list',
  badgeClassName: 'order-filter-badge',
};
```

The list starts with **No active filters** by default. Each active condition becomes its own badge; multiple conditions for one column remain separate and include their `AND` or `OR` relation in the default label.

## Remove and clear filters

Every default badge has a remove button. Removing one condition preserves the remaining conditions and deletes the column entry when its last condition is removed. The badge list stays synchronized even when `beforefilterapply` is canceled for remote filtering.

The default renderer does not add a **Clear all** button. To clear filters programmatically, use the active plugin:

```typescript
const filterPlugin = (await grid.getPlugins()).find(
  (plugin) => plugin instanceof AdvanceFilterPlugin,
) as AdvanceFilterPlugin | undefined;

await filterPlugin?.clearFiltering();
```

A complete custom renderer also receives a `clear()` action. Its `items` expose individual `remove()` actions:

```typescript
grid.filterBadges = {
  render: ({ items, clear }) => {
    const region = document.createElement('section');
    region.setAttribute('aria-label', 'Active filters');

    const list = document.createElement('div');
    list.setAttribute('role', 'list');

    for (const item of items) {
      const entry = document.createElement('div');
      entry.setAttribute('role', 'listitem');

      const removeButton = document.createElement('button');
      removeButton.type = 'button';
      removeButton.textContent = `${item.label} — remove`;
      removeButton.addEventListener('click', () => void item.remove());

      entry.append(removeButton);
      list.append(entry);
    }

    const clearButton = document.createElement('button');
    clearButton.type = 'button';
    clearButton.textContent = 'Clear all filters';
    clearButton.disabled = items.length === 0;
    clearButton.addEventListener('click', () => void clear());

    region.append(list, clearButton);
    return region;
  },
};
```

## Default labels and details

Default labels use the column name, localized operator name, and a compact value summary. Selection filters report the number of excluded values, ranges show their endpoints, and structured filter types can supply their own compact summaries.

When a condition has a longer explanation, the badge includes an info button. It toggles a plain-text tooltip, exposes `aria-controls` and `aria-expanded`, and closes on Escape. Unknown object values are summarized without exposing transport JSON.

Use `formatLabel` and `formatDetails` when the default badge structure is correct but its text is application-specific:

```typescript
grid.filterBadges = {
  formatLabel: ({ column, prop, operatorName, filter, index }) => {
    const name = column?.name ?? String(prop);
    const relation = index ? `${filter.relation?.toUpperCase() ?? 'AND'} ` : '';
    return `${name}: ${relation}${operatorName}`;
  },
  formatDetails: ({ filter }) =>
    `Applied value: ${String(filter.value ?? 'none')}`,
  removeAriaLabel: (item) => `Remove condition ${item.label}`,
  detailsAriaLabel: (item) => `Explain condition ${item.label}`,
};
```

Both format callbacks receive `prop`, `filter`, the condition `index`, the matching `column` when available, and `operatorName`. `formatDetails` should return an empty string to suppress the info control; returning `undefined` allows the built-in details to be used.

## Accessibility and styling options

The default renderer provides these semantics:

- The root has `aria-label="Active filters"` and `aria-live="polite"`.
- An empty list uses `role="status"`; an active list uses `role="list"` with `role="listitem"` badges.
- Remove buttons default to `Remove {label} filter`.
- Details buttons default to `Show details for {label}`.

Customize the root label with `ariaLabel`, the empty message with `emptyLabel`, and the two button labels with `removeAriaLabel` and `detailsAriaLabel`. Add classes without replacing the built-in styles through `className`, `badgeClassName`, `removeButtonClassName`, and `emptyClassName`.

The default shell owns these semantics. A complete `render` callback replaces the list and releases its managed `role`, so your renderer must provide suitable roles, labels, focus behavior, and controls.

## Customize badge content

`renderBadge` replaces only the label content inside the default badge shell. The plugin still renders the list semantics, optional details control, and remove button:

```typescript
grid.filterBadges = {
  renderBadge: ({ item }) => {
    const strong = document.createElement('strong');
    strong.textContent = item.label;
    return strong;
  },
};
```

Use `renderEmpty` to replace only the content inside the default empty-state element:

```typescript
grid.filterBadges = {
  renderEmpty: () => {
    const message = document.createElement('span');
    message.textContent = 'No filters — showing every row';
    return message;
  },
};
```

`renderBadge`, `renderEmpty`, and `render` can return DOM nodes, a `DocumentFragment`, numbers, or nested arrays of supported values. Returned strings are always inserted as text, never parsed as HTML:

```typescript
grid.filterBadges = {
  renderBadge: ({ item }) => [item.label, '<em>text, not markup</em>'],
};
```

To render HTML or Markdown, sanitize it with your application's renderer and return the resulting DOM nodes or fragment. RevoGrid does not parse renderer strings as markup.

## Observe badge-model changes

`onChange` runs after each badge refresh, including the initial render. It receives the current read-only badge items:

```typescript
grid.filterBadges = {
  onChange: (items) => {
    activeFilterCount.textContent = String(items.length);
  },
};
```

Each item contains a render key, label, optional details, source filter context, and `remove()` action. Treat the array and items as read-only; update filtering through the provided actions or the filter plugin APIs.

## Options reference

| Option                  | Purpose                                                                           |
| ----------------------- | --------------------------------------------------------------------------------- |
| `className`             | Adds classes to the plugin-owned root.                                            |
| `badgeClassName`        | Adds classes to each default badge.                                               |
| `removeButtonClassName` | Adds classes to each default remove button.                                       |
| `emptyClassName`        | Adds classes to the default empty-state element.                                  |
| `ariaLabel`             | Labels the live badge region.                                                     |
| `emptyLabel`            | Replaces the default **No active filters** message.                               |
| `removeAriaLabel`       | Produces the accessible label for a remove button.                                |
| `detailsAriaLabel`      | Produces the accessible label for a details button.                               |
| `formatLabel`           | Produces the badge's plain-text label.                                            |
| `formatDetails`         | Produces the complete plain-text details explanation.                             |
| `renderBadge`           | Replaces label content while retaining the default shell and actions.             |
| `renderEmpty`           | Replaces content inside the default empty-state shell.                            |
| `render`                | Replaces the complete list; use `item.remove()` and `clear()` to retain behavior. |
| `onChange`              | Observes the current badge items after every refresh.                             |

## Common mistakes

- Registering `filterBadges` without `AdvanceFilterPlugin`. The property is implemented and managed by that plugin.
- Expecting a string returned by a render callback to become HTML. Strings are intentionally text-safe; return trusted DOM nodes for rich content.
- Using full `render` without wiring `item.remove()` and `clear()`. Replacing the complete UI also makes your application responsible for its controls.
- Assuming the default renderer includes a clear-all action. It provides per-condition removal; add a custom control or call `clearFiltering()`.
- Omitting accessibility from a full renderer. Unlike `renderBadge` and `renderEmpty`, full `render` replaces the list structure and its managed role.
- Mutating the items received by `onChange`. Use the filter APIs so the grid, remote filtering, and badges stay synchronized.
- Treating badge actions as an editor for every canonical AST. Badges can summarize a grouped AST that cannot project to `MultiFilterItem`, but per-condition removal is available only for projectable state; update that tree with `setFilterAst()` or clear it with `clearFiltering()`.

## Related guides

- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)
- [Filtering Quick Start](/guides/data-filter/filter-basics/)
- [Filter State and Presets](/guides/data-filter/filter-state/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Filter Events](/guides/data-filter/filter-events/)

---

# Quick Start

URL: https://pro.rv-grid.com/guides/data-filter/filter-basics/
Source: src/content/docs/guides/data-filter/filter-basics.mdx
Description: Enable RevoGrid filtering, choose text and number operators, set initial conditions, clear filters, and react to filter changes.
Surface: grid

Use this guide when you need the shortest path from an unfiltered grid to a useful filtering workflow. RevoGrid Core already includes text and number conditions. Add `AdvanceFilterPlugin` only when you need selection lists, sliders, dates, expressions, grouped logic, quick filtering, or the [structured filter types](/guides/data-filter/filter-types/overview/).

## Choose a filter model

Use the smallest model that expresses the product requirement:

| Need | Recommended model | Why |
| --- | --- | --- |
| Ordinary local column filters | `multiFilterItems` | The smallest Core-compatible model; columns combine with AND. |
| Existing Core or legacy remote integration | `multiFilterItems` | Keeps the familiar column-condition format. |
| Saved views, remote requests, cross-column OR, nested groups, or NOT | `FilterAst` | JSON-safe canonical tree with one portable meaning. |

For a new remote integration, start with `FilterAst` and the accompanying `executionContext`; do not build a new backend contract around runtime-only values in `multiFilterItems`. The [Filter State and Presets](/guides/data-filter/filter-state/) guide shows both shapes, and the [Canonical Filter AST](/guides/data-filter/filter-ast/) guide defines the remote contract.

## 1. Enable filtering

Set the grid-level `filter` property explicitly, then choose a filter family on each column that needs filtering:

```ts
const grid = document.querySelector('revo-grid')!;

grid.columns = [
  { prop: 'name', name: 'Name', filter: 'string' },
  { prop: 'status', name: 'Status', filter: 'string' },
  { prop: 'amount', name: 'Amount', filter: 'number' },
  { prop: 'internalId', name: 'Internal ID', filter: false },
];

grid.filter = true;
grid.source = [
  { name: 'Anna', status: 'Open', amount: 120 },
  { name: 'John', status: 'Pending', amount: 80 },
  { name: 'Steve', status: 'Closed', amount: 240 },
];
```

The grid-level property enables the filter plugin. It defaults to `true`; setting it explicitly makes application intent clear. The column-level property controls the button and available operators for that column. Do not initialize the grid with `filter = false` and expect a later `true` assignment to install the plugin dynamically.

| Column `filter` value | Use it for                                   |
| --------------------- | -------------------------------------------- |
| `true` or `'string'`  | Text values                                  |
| `'number'`            | Numeric comparisons                          |
| `false`               | No filter button                             |
| `string[]`            | Several Core, Pro, or custom filter families |

## 2. Choose an operator

Core string columns provide these saved operator IDs:

| Operator                   | Meaning                   |
| -------------------------- | ------------------------- |
| `contains` / `notContains` | Includes or excludes text |
| `begins`                   | Starts with text          |
| `eq` / `notEq`             | Equal or not equal        |
| `empty` / `notEmpty`       | Is blank or is not blank  |

Core number columns provide `eqN`, `neqN`, `gt`, `gte`, `lt`, `lte`, `empty`, and `notEmpty`. Operator IDs are used in saved state, configuration, and event payloads; the popup shows readable labels such as **Contains**, **>=**, and **Is blank**.

## 3. Start with an applied filter

Use `multiFilterItems` for both single and multiple conditions. The following configuration shows rows whose status is Open and whose amount is from 100 through 500:

```ts
grid.filter = {
  multiFilterItems: {
    status: [{ id: 1, type: 'eq', value: 'Open', relation: 'and' }],
    amount: [
      { id: 2, type: 'gte', value: 100, relation: 'and' },
      { id: 3, type: 'lte', value: 500, relation: 'and' },
    ],
  },
};
```

Conditions inside one column can use `and` or `or`. Different columns combine with AND. Use the [Canonical Filter AST](/guides/data-filter/filter-ast/) when you need cross-column OR, nested groups, or NOT.

### Update conditions reactively without replacing configuration

The `filter` property is reactive. When the grid already has localization, Pro options, or custom filters, spread the current object into a new configuration before replacing its active conditions:

```ts
const currentFilter = typeof grid.filter === 'object' ? grid.filter : {};

grid.filter = {
  ...currentFilter,
  multiFilterItems: {
    amount: [
      { id: 1, type: 'gte', value: 100, relation: 'and' },
      { id: 2, type: 'lte', value: 500, relation: 'and' },
    ],
  },
};
```

Assign a new object rather than mutating `grid.filter.multiFilterItems` in place; the new reference triggers the reactive update. Framework applications should use the equivalent state update. For a Pro tree with cross-column logic, use the same pattern with `filterAst` instead of `multiFilterItems`.

## 4. Apply only after confirmation

Filtering updates while the user edits by default. For a Save/Cancel workflow, disable dynamic filtering:

```ts
grid.filter = {
  disableDynamicFiltering: true,
};
```

## 5. Read and clear the result

Read the currently visible models with `getVisibleSource()`:

```ts
const visibleRows = await grid.getVisibleSource();
```

Clear through the active plugin to preserve configuration such as localization, selection options, expressions, and structured type registrations:

```ts
import { FilterPlugin } from '@revolist/revogrid';

const filterPlugin = (await grid.getPlugins()).find(
  (plugin) => plugin instanceof FilterPlugin,
);

await filterPlugin?.clearFiltering();
```

`AdvanceFilterPlugin` extends `FilterPlugin`, so the same lookup works for Pro and also clears its quick-filter and canonical AST state. If your application controls `grid.filter` by assignment instead, recreate the complete configuration with `multiFilterItems: {}`; assigning only the empty model would replace the other options.

## 6. React to changes

Use `afterfilterapply` for UI that depends on the filtered result. Use the cancelable `beforefilterapply` event when the application needs to inspect, rewrite, or delegate a request to a backend.

```ts
grid.addEventListener('afterfilterapply', async (event) => {
  const visibleRows = await grid.getVisibleSource();
  console.log(event.detail.multiFilterItems, visibleRows.length);
});

grid.addEventListener('beforefilterapply', (event) => {
  console.log('About to apply', event.detail.filterItems);
});
```

## 7. Add Pro filter controls

Register `AdvanceFilterPlugin`, then add the filter type to each matching column:

```ts
import {
  AdvanceFilterPlugin,
  FIlTER_SELECTION,
  FIlTER_SLIDER,
  FILTER_DATE,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'status', filter: ['string', FIlTER_SELECTION] },
  { prop: 'amount', filter: ['number', FIlTER_SLIDER] },
  { prop: 'createdAt', filter: [FILTER_DATE] },
];
grid.filter = true;
```

## Customize the experience

Each concern has a focused customization boundary; combine only the ones your UI needs.

| Need | Configure or call |
| --- | --- |
| Application-specific operator | `filter.customFilters` |
| Purpose-built filter popup | `filter.structuredFilterTypes` |
| Server-backed selection values | `filter.selection.getItems(prop, { search, signal })` |
| Global toolbar search | `grid.quickFilter` |
| Visual nested-rule editor | `filter.groupedFilter` or `plugin.mountFilterAstEditor()` |
| Saved view or remote query | `plugin.getFilterAst()` and `plugin.setFilterAst()` |

Use the [Filter Events](/guides/data-filter/filter-events/) guide when the application owns remote loading. Its example covers canceling local evaluation, sending the canonical request, and accepting only the latest response.

Choose a focused guide next:

- [Text Filter](/guides/data-filter/filter-types/text-filter/) for contains, equality, and begins-with conditions
- [Number Filter](/guides/data-filter/filter-types/number-filter/) for comparisons and numeric ranges
- [Selection Filter](/guides/data-filter/filter-types/filter-selection/) for checklists of values
- [Excel-Style Filter](/guides/data-filter/filter-types/filter-selection-excel-mode/) for staged Apply/Cancel checklists
- [Slider Filter](/guides/data-filter/filter-types/filter-slider/) for numeric ranges
- [Date Filter](/guides/data-filter/filter-types/date-filter/) for calendar-day rules
- [Datetime Filter](/guides/data-filter/filter-types/datetime-filter/) for exact instants
- [Boolean Filter](/guides/data-filter/filter-types/boolean-filter/) for strict Yes/No conditions
- [Array Filter](/guides/data-filter/filter-types/array-filter/) for empty and non-empty arrays
- [Structured Filter Types](/guides/data-filter/filter-types/overview/) for purpose-built popup controls
- [Quick Filter](/guides/data-filter/filter-types/quick-filter/) for multi-word search across columns
- [Filter Events](/guides/data-filter/filter-events/) for observation and remote delegation
- [Filter Badges](/guides/data-filter/filter-badges/) for synchronized active-filter summaries
- [Filter State and Presets](/guides/data-filter/filter-state/) for reusable and persisted views
- [Custom Filter Operators](/guides/data-filter/custom-filter-operators/) for application-specific predicates
- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/) for quick filtering, badges, expressions, presets, and grouped logic

## Common mistakes

- Setting a column's `filter` but not enabling `grid.filter` or registering the Pro plugin.
- Using string operators such as `eq` on a numeric column; use `eqN` for Core numeric equality.
- Expecting `multiFilterItems` to express cross-column OR; use `FilterAst` for that shape.
- Filtering formatted display text without a `cellParser`; conditions evaluate the parsed value when a parser exists.
- Treating `0` or `false` as blank. The default blank policy does not.

## Related guides

- [Blank Values](/guides/data-filter/blank-values/)
- [Filter Header](/guides/data-filter/filter-header/)
- [Filter Expressions](/guides/data-filter/filter-expression/)
- [Clear Filtering demo](https://demo.rv-grid.com/clear-filtering/ts)
- [Core filtering guide](https://rv-grid.com/guide/filters)

---

# Filter Events

URL: https://pro.rv-grid.com/guides/data-filter/filter-events/
Source: src/content/docs/guides/data-filter/filter-events.mdx
Description: Observe, modify, cancel, or delegate Core and Pro filtering through runtime events.
Surface: grid

Filter events let application code react after visible rows change, adjust the rows that will be trimmed, or cancel local evaluation and delegate a request to a backend.

## Local Core event sequence

A normal Core filter run emits these filter-plugin events in order:

| Order | Event                 | Cancelable | Important runtime detail                                            |
| ----- | --------------------- | ---------- | ------------------------------------------------------------------- |
| 1     | `beforefilterapply`   | Yes        | `collection`, full `filterItems`, source, and columns               |
| 2     | `beforefiltertrimmed` | Yes        | Filter model plus physical `itemsToFilter` indexes                  |
| 3     | `afterfilterapply`    | No         | `multiFilterItems`, original source, and first-condition collection |

Canceling `beforefilterapply` stops evaluation. Canceling `beforefiltertrimmed` stops the calculated filter trim from being installed. `beforetrimmed` and `aftertrimmed` are general grid events and can also run for grouping, tree visibility, or application-owned trims.

The Core filter plugin writes its calculated trim through the data provider, so its normal apply path does not emit the public `beforetrimmed` and `aftertrimmed` element events. Those events wrap calls through the grid's general `setTrimmed()` method; do not include them when reasoning about the filter-plugin sequence.

`filterconfigchanged` is different: it reports a new grid filter configuration and is not a per-run completion event.

## Read visible rows after filtering

`afterfilterapply.detail.source` is the original local source, not the filtered result. Read the provider-backed visible models with `getVisibleSource()`:

```ts
grid.addEventListener('afterfilterapply', async (event) => {
  const visibleRows = await grid.getVisibleSource();
  const detail = (
    event as CustomEvent<{
      multiFilterItems: Record<string, unknown[]>;
    }>
  ).detail;

  console.log('Active filters', detail.multiFilterItems);
  console.log('Visible rows', visibleRows.length);
});
```

The cast is intentional. The runtime Core plugin emits `afterfilterapply`, but the generated Core element event map in some current packages does not declare that event yet, so TypeScript may otherwise infer only the base `Event` type. Applications can also augment `HTMLRevoGridElementEventMap` centrally with the runtime detail type.

## Modify the calculated trim

Use `beforefiltertrimmed` when the application needs final control over physical row indexes:

```ts
grid.addEventListener('beforefiltertrimmed', (event) => {
  // Keep physical row 0 visible even when ordinary conditions reject it.
  delete event.detail.itemsToFilter[0];
});
```

Use this hook sparingly. A custom filter predicate or canonical AST condition is easier to persist and transport when the requirement is ordinary business logic.

## Cancel and delegate to a backend

Prevent `beforefilterapply` to stop local trimming, then load rows from the server. Guard the source replacement so reapplying the same active model does not create a request loop:

```ts
let loadedSignature = '';
let requestId = 0;

grid.addEventListener('beforefilterapply', async (event) => {
  const detail = (
    event as CustomEvent<{
      filterItems: Record<string, unknown[]>;
      filterAst?: unknown;
      executionContext?: unknown;
    }>
  ).detail;
  const transportState = detail.filterAst
    ? {
        filterAst: detail.filterAst,
        executionContext: detail.executionContext,
      }
    : { filterItems: detail.filterItems };
  const signature = JSON.stringify(transportState, (_key, value) =>
    value instanceof Set ? [...value] : value,
  );

  if (signature === loadedSignature) return;

  event.preventDefault();
  const activeRequest = ++requestId;
  const response = await fetch('/api/orders/filter', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: signature,
  });
  const rows = await response.json();

  if (activeRequest !== requestId) return;
  loadedSignature = signature;
  grid.source = rows;
});
```

With `AdvanceFilterPlugin`, set `filter.external: true` when the backend always owns filtering. The plugin then prevents local trimming itself while still emitting the same `beforefilterapply` payload. Your handler only needs to send the model and install the latest response; it should not emit `afterfilterapply`, because that event remains a local-filter completion signal.

```ts
grid.filter = { external: true };
grid.addEventListener('beforefilterapply', async (event) => {
  const { filterAst, executionContext } = event.detail;
  grid.source = await loadOrders({ filterAst, executionContext });
});
```

In production, also handle request failures and abort stale network work. The Pro Pagination, Infinity Scroll, and Server-Side Grouping plugins already implement this delegation flow.

Prefer Pro's canonical `filterAst` for new remote integrations. Compatible `filterItems` can contain runtime values such as the selection filter's excluded-value `Set`; the fallback above converts sets to arrays, but applications should still define and validate their complete wire contract. See [Filter State and Presets](/guides/data-filter/filter-state/).

## Pro AST events

`AdvanceFilterPlugin` emits canonical events in addition to the Core lifecycle:

| Event             | Detail                                                   | Use it for                                                 |
| ----------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
| `filterastchange` | `filterAst`, `executionContext`, `origin`, `projectable` | Persisting or transporting the effective canonical tree    |
| `filterasterror`  | Attempted AST, diagnostics, and origin                   | Showing validation errors without applying an invalid tree |

For a local Pro run, `filterastchange` is emitted before `beforefilterapply`. Pro also adds `filterAst`, `executionContext`, and temporal transport context to the Core before/after event details at runtime. Origins distinguish `config`, `api`, `ui`, `quickFilter`, and `clear` changes.

```ts
grid.addEventListener('filterastchange', (event) => {
  console.log(event.detail.origin, event.detail.filterAst);
});

grid.addEventListener('filterasterror', (event) => {
  console.error(event.detail.diagnostics);
});
```

## Quick Filter events

Changing `grid.quickFilter` wraps the local filter run with two Pro events:

```text
beforequickfilterapply
  → filterastchange
  → beforefilterapply
  → beforefiltertrimmed
  → afterfilterapply
afterquickfilterapply
```

`beforequickfilterapply` is cancelable. Its detail and `afterquickfilterapply` contain the normalized `quickFilter`, source, and columns. Remote Pro data plugins cancel the local quick-filter run and emit the completion event after the latest remote response wins.

## Common mistakes

- Do not treat `aftertrimmed` as filter-only; other grid features also trim rows.
- Do not read the original `source` field as the filtered result; call `getVisibleSource()`.
- Do not perform a remote request without `preventDefault()` or local filtering will run too.
- Do not assign remote rows without a loop guard and stale-request protection.
- Do not mutate `beforequickfilterapply.detail.quickFilter` expecting it to replace the property value; observe it or cancel and assign a new `grid.quickFilter` value.
- Do not assume generated element typings expose every plugin-emitted runtime field. Narrow or augment event detail types where needed.

## Related guides

- [Quick Filter](/guides/data-filter/filter-types/quick-filter/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Filter State and Presets](/guides/data-filter/filter-state/)
- [Custom Filter Operators](/guides/data-filter/custom-filter-operators/)
- [Filtering Quick Start](/guides/data-filter/filter-basics/)
- [Infinity Scroll](/guides/infinity-scroll/)

---

# Filter Expressions

URL: https://pro.rv-grid.com/guides/data-filter/filter-expression/
Source: src/content/docs/guides/data-filter/filter-expression.mdx
Description: Enable a current-column expression editor for RevoGrid Pro advanced filters.

The Pro advanced filter can expose an optional expression editor inside each filter popup. It is disabled by default. When enabled, the popup adds an **Expression** button and expandable editor panel at the bottom, after the regular filter controls. Users can type current-column filter logic as text; valid expressions apply live and compile into the grid's standard `multiFilterItems` model.

```ts
import { AdvanceFilterPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'status', name: 'Status', filter: ['string', 'selection'] },
  { prop: 'score', name: 'Score', filter: ['number', 'slider'] },
  { prop: 'updated', name: 'Updated', filter: ['date'] },
];

grid.filter = {
  expressions: {
    enabled: true,
    applyDebounceMs: 300,
    buttonLabel: 'Expression',
    placeholder: 'between 10 and 50\ncontains "north" AND not empty',
  },
};
```

## Current-column scope

Expressions are scoped to the column whose filter popup is open. You can omit the column name:

```txt
between 2024-01-01 and 2024-12-31 AND after 2024-06-01
```

You can also include the current column prop or name for readability:

```txt
updated between 2024-01-01 and 2024-12-31 AND updated after 2024-06-01
```

References to another column are invalid and do not change active filters.

For application-defined cross-column `OR`, nested groups, and `NOT`, use the public [Canonical Filter AST](/guides/data-filter/filter-ast/). The popup editor remains deliberately scoped to its current column.

## Parsed cell values

Expressions evaluate the current column's parsed value when `cellParser` is defined, just like ordinary comparisons. Blank expression operators use the raw source value and property-presence context from Core. See [Blank Values](/guides/data-filter/blank-values/) for the source-preserving contract.

## Syntax

Use `AND`, `OR`, and parentheses to group expressions:

```txt
(contains "north" OR contains "west") AND not empty
```

String columns support:

```txt
empty
not empty
= "Active"
!= "Archived"
begins "A"
contains "north"
not contains "draft"
```

Array columns support strict, valueless length checks:

```txt
empty array
not empty array
is empty array
is not empty array
```

Number and slider columns support:

```txt
> 10
>= 25
< 100
<= 500
between 250 and 640.42
```

Date columns support:

```txt
equals 2024-06-01
before 2024-12-31
after 2024-01-01
on or before 2024-12-31
on or after 2024-01-01
not equal 2024-07-04
between 2024-01-01 and 2024-12-31
today
yesterday
last 7 days
this month
last month
this quarter
next quarter
previous quarter
this year
next year
previous year
```

Selection-style text supports:

```txt
is "Open"
in ("Open", "Pending")
not in ("Closed", "Archived")
```

Registered structured filters use the same lossless mirror without exposing their transport JSON.
Objects, arrays, strings, numbers, booleans, and blank values remain typed:

```txt
structured "arrayTagsMatch" {
  mode: "none",
  values: ["renewal", "priority"],
  emptyOnly: false,
  exact: false
}
```

The editor highlights keywords, operators, properties, strings, numbers, booleans, and invalid
tokens. The grouped filter's Text view uses the same token presentation; when a structured filter
provides `describeCondition`, that filter-owned readable description replaces its transport value.
Legacy saved expressions containing a quoted JSON payload remain accepted.

## Validation and applying

The editor validates while users type. Valid expressions apply after `applyDebounceMs`; invalid expressions show diagnostics and keep the previous valid filters unchanged. Press `Ctrl+Enter` or `Cmd+Enter` to apply immediately.

The expression panel does not replace the normal popup content. Selection lists, slider controls, date inputs, and condition controls remain visible while the expression panel is expanded.

Expression filters are stored as hidden Pro filter items, so reset, active header state, filter events, and server-side filter payload handling continue to use the standard `multiFilterItems` flow.

## Localization

Expression labels use the existing filter localization path:

```ts
grid.filter = {
  expressions: true,
  localization: {
    captions: {
      expressionButton: 'Expression',
      expressionTitle: 'Filter expression',
      expressionPlaceholder: 'contains "north"',
      expressionApply: 'Apply',
      expressionInvalid: 'Invalid expression',
    },
  },
};
```

## Related guides

- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Selection Filter](/guides/data-filter/filter-types/filter-selection/)
- [Blank Values](/guides/data-filter/blank-values/)

---

# Filter Header

URL: https://pro.rv-grid.com/guides/data-filter/filter-header/
Source: src/content/docs/guides/data-filter/filter-header.mdx
Description: Add accessible text inputs, range controls, popup triggers, and optional compact templates directly to column headers.

`FilterHeaderPlugin` places common filter controls directly below each column label. Use it when users need fast, always-visible filtering; the normal filter icon remains available for the complete advanced-filter popup.

## Quick start

Register `FilterHeaderPlugin`, then configure filter families on the columns. It installs `AdvanceFilterPlugin` automatically:

```typescript
import {
  FilterHeaderPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [FilterHeaderPlugin];
grid.columns = [
  { name: 'Name', prop: 'name', filter: 'string' },
  { name: 'Status', prop: 'status', filter: ['selection'] },
  { name: 'Age', prop: 'age', filter: ['number', 'slider'] },
  { name: 'Tags', prop: 'tags', filter: ['array'] },
];
```

Text columns receive a debounced input. Popup-style and registered structured filters receive a compact trigger. Slider columns receive either an inline range control or a formatted range summary.

| Column filter family | Header control                                    |
| -------------------- | ------------------------------------------------- |
| Text and number      | Debounced inline input                            |
| Selection            | Popup trigger with included-value summary         |
| Date                 | Popup trigger with active-state indicator         |
| Boolean              | Popup trigger for the valueless Yes/No operators  |
| Array                | Popup trigger for empty/non-empty array operators |
| Slider               | Inline range control or formatted range summary   |
| Structured types     | Popup trigger using the type's readable summary   |

## Slider headers

A column containing the `slider` filter type renders the shared range slider directly in the header. The regular filter icon remains available for opening the full advanced-filter popup.

```ts
const columns = [{ name: 'Age', prop: 'age', filter: ['number', 'slider'] }];
```

Moving either handle applies the range immediately. Returning both handles to the full data range clears the slider filter.

## Popup trigger headers

For selection, date, boolean, and array popup filters, the header renders a popup trigger instead of a free text input. Clicking it opens the same advanced-filter popup available from the normal filter icon.

Selection triggers show `All` while no values are excluded. Opening a selection popup and closing it without changes keeps the header value as `All`; it does not expand to every selected item.

Customize that fallback through the standard advanced-filter localization captions:

```ts
const filter = {
  localization: {
    captions: {
      selectionAll: 'Any value',
    },
  },
};
```

When values are unchecked in the selection popup, the trigger shows a compact selected/total badge such as `8/9`. This is the default presentation and requires no additional configuration. Hover the badge to see the full selected-value summary. By default, that summary includes the number of matching rows for each value; set `hideFilterHeaderCount` on the column to hide those row counts.

Date triggers become active when a date condition has a value. Boolean and array triggers become active when one of their valueless operators is applied. Array support requires the array family in the column's filter array:

```ts
grid.columns = [{ name: 'Tags', prop: 'tags', filter: ['array'] }];
```

The array popup offers **Is empty array** and **Is not empty array**. See [Array Filter](/guides/data-filter/filter-types/array-filter/) for their strict array-value behavior.

## Custom header presentation

Every popup-style filter uses the same `FilterHeaderTemplateFunc` contract. A column template has the highest priority:

```tsx
import type { FilterHeaderTemplateFunc } from '@revolist/revogrid-pro';

const compactStatusHeader: FilterHeaderTemplateFunc = (h, { presentation }) => (
  <span class={{ 'status-summary': true, active: presentation.active }}>
    {presentation.summary}
  </span>
);

const columns = [{
  name: 'Status',
  prop: 'status',
  filter: ['selection'],
  filterHeaderTemplate: compactStatusHeader,
}];
```

The grid owns the actual button, focus behavior, tooltip, keyboard activation, and accessible name. A template only renders non-interactive visual content inside that button. Use `presentation.summary` for compact text and `presentation.details` for the full human-readable meaning. Returning `undefined` keeps the standard text or count fallback.

A custom registered structured type may provide the same template once for every column using that type:

```tsx
const temperatureFilter: StructuredFilterType = {
  id: 'temperatureRange',
  operatorIds: ['temperatureBetween'],
  render: context => <TemperatureEditor {...context} />,
  describeCondition: ({ condition }) => ({
    summary: `${condition.value.min}–${condition.value.max} °C`,
    details: `Temperature from ${condition.value.min} to ${condition.value.max} °C`,
  }),
  headerControl: {
    kind: 'popup',
    template: (h, { presentation }) => (
      <span>{presentation.summary}</span>
    ),
  },
};
```

Use `kind: 'popup'` when the filter needs custom badge, star, or summary content inside the grid-owned trigger. Use a `headerControl` resolver with `kind: 'inline'` when the type needs an interactive control such as a range slider. The resolver receives the same controlled body context as the popup, including aggregates and `replaceConditions()`, while the grid owns the outer non-sorting interaction boundary.

`describeCondition` is the source of truth for filter badges, grouped-filter text, header labels, and accessibility text. Keep it data-independent: it receives the condition and column configuration, not grid rows. This makes compact presentation safe for remote and very large datasets. A column-level `filterHeaderTemplate` overrides a type-owned popup template.

The template props also expose the column, canonical conditions, selection compatibility values, and the complete `presentation` object. The former top-level `active` and `text` fields remain as compatibility aliases; new code should use `presentation`.

Localize the surrounding accessible text with the normal filter captions:

```ts
const filter = {
  localization: {
    captions: {
      filterHeaderLabel: column => `Filter ${column.name ?? column.prop}`,
      filterHeaderSelectionSummary: (selected, total, details) =>
        `${selected} of ${total} selected${details ? `: ${details}` : ''}`,
    },
  },
};
```

## When to use the popup instead

Header controls prioritize quick changes and limited space. Keep the normal popup workflow for multiple conditions, expressions, Excel-style staged selection, grouped AST editing, or any control that needs explanatory content.

## Related guides

- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)
- [Selection Filter](/guides/data-filter/filter-types/filter-selection/)
- [Excel-Style Filter](/guides/data-filter/filter-types/filter-selection-excel-mode/)
- [Slider Filter](/guides/data-filter/filter-types/filter-slider/)
- [Array Filter](/guides/data-filter/filter-types/array-filter/)
- [Filter Expressions](/guides/data-filter/filter-expression/)

---

# Overview

URL: https://pro.rv-grid.com/guides/data-filter/filter-showcase/
Source: src/content/docs/guides/data-filter/filter-showcase.mdx
Description: Combine RevoGrid Core column filters with Pro structured controls, selection, slider, date, expressions, presets, and quick-filter workflows.

RevoGrid filtering narrows the visible row set without replacing the original source. Core provides the filter model and standard text/number operators; RevoGrid Pro adds richer inputs around the same model.

New to filtering? Begin with the [Filtering Quick Start](/guides/data-filter/filter-basics/) to enable filters, choose text and number operators, apply initial conditions, listen for changes, and clear the result.

For a scenario-led tour, read [Advanced Data Grid Filtering for E-commerce and Project Management](https://rv-grid.com/blog/advanced-data-grid-filtering-ecommerce-project-management) to see how the same capabilities support customer segmentation, order operations, and project-delivery queues.

[Open the standalone Advanced Filtering showcase](https://demo.rv-grid.com/filter-showcase/ts) to compare the TypeScript, React, Vue, and Angular implementations.

## Core and Pro at a glance

| Capability                                                                                                                       | Core | Pro                                                  |
| -------------------------------------------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------- |
| Text and number operators                                                                                                        | Yes  | Uses the same operators                              |
| Multiple conditions per column                                                                                                   | Yes  | Enhanced popup and header workflows                  |
| Programmatic `multiFilterItems`                                                                                                  | Yes  | Used by selection, slider, date, and expressions too |
| Parsed values through `cellParser`                                                                                               | Yes  | Shared by advanced filters                           |
| Canonical JSON-safe filter tree                                                                                                  | —    | `FilterAst` with nested `and`, `or`, and `not`       |
| Global multi-word quick filter                                                                                                   | —    | `AdvanceFilterPlugin`                                |
| Selection and cascading option lists                                                                                             | —    | Yes                                                  |
| Editable numeric range slider                                                                                                    | —    | Yes                                                  |
| Calendar and relative-date operators                                                                                             | —    | Yes                                                  |
| Structured filter bodies for tokens, fuzzy search, regex, facets, histograms, ratings, timelines, matrices, booleans, and arrays | —    | Yes                                                  |
| Inline header controls                                                                                                           | —    | `FilterHeaderPlugin`                                 |
| Current-column expression editor                                                                                                 | —    | Optional                                             |
| Pagination, infinite scroll, and server-side grouping adapters                                                                   | —    | Yes                                                  |

## Choose the right filtering workflow

Start with the smallest workflow that matches the user's task:

| User need                                                | Start with                                                                                          | Add when needed                                                                                                     |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Text or numeric conditions in a popup                    | [Text](/guides/data-filter/filter-types/text-filter/) or [Number](/guides/data-filter/filter-types/number-filter/) filters    | `AdvanceFilterPlugin` for richer controls and a canonical model                                                     |
| A checklist of known values                              | [Selection Filter](/guides/data-filter/filter-types/filter-selection/)                                           | [Excel mode](/guides/data-filter/filter-types/filter-selection-excel-mode/) for staged Apply/Cancel; cascade for dependent lists |
| A numeric interval                                       | [Slider Filter](/guides/data-filter/filter-types/filter-slider/)                                                 | Editable inputs or inline header controls                                                                           |
| Calendar days or exact instants                          | [Date](/guides/data-filter/filter-types/date-filter/) or [Datetime](/guides/data-filter/filter-types/datetime-filter/) filter | Timezone, week, and fiscal-calendar policy                                                                          |
| Fast controls inside headers                             | [Filter Header](/guides/data-filter/filter-header/)                                                 | Selection, slider, date, or boolean popup triggers                                                                  |
| Current-column power-user syntax                         | [Filter Expressions](/guides/data-filter/filter-expression/)                                        | Use AST instead for logic across columns                                                                            |
| Cross-column OR, nested groups, NOT, or remote transport | [Canonical Filter AST](/guides/data-filter/filter-ast/)                                             | The grouped editor for a visual workflow                                                                            |
| A data-shaped popup control                              | [Structured Filter Types](/guides/data-filter/filter-types/overview/)                               | Register a custom type when the built-ins do not fit                                                                |
| Search words across several columns                      | [Quick Filter](/guides/data-filter/filter-types/quick-filter/)                                                   | Restrict columns or tune the debounce                                                                               |
| Show removable active-filter summaries                   | [Filter Badges](/guides/data-filter/filter-badges/)                                                 | Custom labels, details, rendering, and clear actions                                                                |
| Save, restore, or package reusable views                 | [Filter State and Presets](/guides/data-filter/filter-state/)                                       | Canonical `FilterAst` for JSON-safe nested queries                                                                  |
| Add an application-specific row test                     | [Custom Filter Operators](/guides/data-filter/custom-filter-operators/)                             | Structured types for purpose-built popup bodies                                                                     |

## How Filter v2 improves existing filtering

“Filter v2” is an informal name for the canonical filtering architecture in Pro's `AdvanceFilterPlugin`; it is not a separate `FilterV2` class or a replacement Core plugin. Existing text, number, selection, slider, date, expression, and quick filters continue to use their current column configuration and UI. The advanced plugin converts their state into a JSON-safe `FilterAst` automatically.

This gives existing filtering a consistent model for local evaluation, saved views, and remote requests. It also adds nested `and`/`or` groups, cross-column `or`, `not`, atomic validation, and a shared date/time execution context. Simple trees are projected back into `multiFilterItems`, so existing integrations remain compatible; applications only need to use the AST API when they need the more expressive tree model.

This is primarily an improvement in capability, validation, and transport consistency. It does not promise that ordinary column filters will execute faster. Simple filtering still participates in the existing Core trimming and large-source lifecycle. See [Canonical Filter AST](/guides/data-filter/filter-ast/) for the tree shape, API, grouped editor, and remote event payloads.

## Explore the three presets

The Order Explorer opens with the **High-value Europe** filters already applied, making the active chips and filtered result count immediately visible. Use **Clear All** to reveal all 1,000 deterministic orders. Its presets are ordinary `multiFilterItems` models, so they can also be saved as views or created by application code.

- **High-value Europe** combines a Region selection with a Total slider range.
- **Recent expedited** combines the relative `last7Days` date operator with the Expedited selection.
- **Review queue** includes selected Status values and adds `gte` plus `lte` conditions to Total.

The result count comes from `grid.getVisibleSource()` after filtering. The grid-synced badge component mirrors the current model; removing a badge updates the plugin's canonical filter state, while **Clear All** assigns an empty filter model.

The toolbar's global search uses the public `grid.quickFilter` property. Try `Lisbon pending`: each word can match a different visible column in the same row. Search is whitespace-normalized, case-insensitive, and uses parsed cell values. Every word must match somewhere in the row, and the result is ANDed with all active column filters.

Scroll horizontally through the expanded order schema to try all fourteen [structured filter types](/guides/data-filter/filter-types/overview/) in context. Order, Customer, SKU, Region, Status, Total, Rating, Margin Change, Order Date, Renewal Date, Created At, Activity Time, Verified, and Tags each expose the matching purpose-built body while continuing to serialize into the same condition model.

  In the compatible `multiFilterItems` model, relations belong to conditions
  within one column. Conditions for the same column can use `and` or `or`, while
  different columns combine with AND. The expression editor is also
  current-column only. Use `FilterAst` or its grouped editor for cross-column
  OR, nested groups, and NOT.

## Configure the showcase building blocks

The showcase combines documented public features rather than introducing another filter API:

- Header controls come from [Filter Header](/guides/data-filter/filter-header/).
- Status and Region use [Selection Filter](/guides/data-filter/filter-types/filter-selection/) with [Selection Cascade](/guides/data-filter/filter-types/filter-selection-cascade/).
- Total combines the [Number Filter](/guides/data-filter/filter-types/number-filter/) and [Slider Filter](/guides/data-filter/filter-types/filter-slider/).
- Order Date uses the [Date Filter](/guides/data-filter/filter-types/date-filter/), while Created At uses [Datetime Filter](/guides/data-filter/filter-types/datetime-filter/).
- The toolbar search uses [Quick Filter](/guides/data-filter/filter-types/quick-filter/).
- Active chips use [Filter Badges](/guides/data-filter/filter-badges/).
- Presets follow [Filter State and Presets](/guides/data-filter/filter-state/).

Default popup controls apply while users edit. Set `disableDynamicFiltering: true` for the ordinary popup's Save/Cancel workflow. The separate [Excel-Style Filter](/guides/data-filter/filter-types/filter-selection-excel-mode/) always uses Apply/Cancel and also provides mini-filter actions, blanks, and date hierarchies.

- [Filtering Quick Start](/guides/data-filter/filter-basics/)
- [Structured Filter Types](/guides/data-filter/filter-types/overview/)
- [Quick Filter](/guides/data-filter/filter-types/quick-filter/)
- [Filter Events](/guides/data-filter/filter-events/)
- [Filter Header](/guides/data-filter/filter-header/)
- [Selection Filter](/guides/data-filter/filter-types/filter-selection/)
- [Excel-Style Filter](/guides/data-filter/filter-types/filter-selection-excel-mode/)
- [Selection Cascade](/guides/data-filter/filter-types/filter-selection-cascade/)
- [Slider Filter](/guides/data-filter/filter-types/filter-slider/)
- [Date and Datetime Filters](/guides/data-filter/filter-types/date-filter/)
- [Filter Badges](/guides/data-filter/filter-badges/)
- [Filter State and Presets](/guides/data-filter/filter-state/)
- [Custom Filter Operators](/guides/data-filter/custom-filter-operators/)
- [Current-column expressions](/guides/data-filter/filter-expression/)
- [Canonical local and remote Filter AST](/guides/data-filter/filter-ast/)
- [Clear Filtering demo](https://demo.rv-grid.com/clear-filtering/ts)

---

# Filter State and Presets

URL: https://pro.rv-grid.com/guides/data-filter/filter-state/
Source: src/content/docs/guides/data-filter/filter-state.mdx
Description: Initialize, update, save, restore, clear, and package reusable RevoGrid filter state without losing filter configuration.
Surface: grid

RevoGrid has two filter-state shapes. Choose the smallest one that represents the query you need:

| State             | Use it for                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `MultiFilterItem` | Core compatibility, ordinary column controls, and conditions that combine columns with AND |
| `FilterAst`       | Pro saved views, remote requests, cross-column OR, nested groups, and NOT                  |

`MultiFilterItem` is runtime-compatible, but some controls use values such as `Set`. `FilterAst` is the canonical JSON-safe choice for new persistence and transport integrations.

## Set initial column filters

Supply `multiFilterItems` inside the complete grid filter configuration. Each property is a column property, and each array contains that column's conditions:

```ts
import type { ColumnFilterConfig, MultiFilterItem } from '@revolist/revogrid';

const initialFilters: MultiFilterItem = {
  status: [{ id: 1, type: 'eq', value: 'Open', relation: 'and' }],
  total: [
    { id: 2, type: 'gte', value: 100, relation: 'and' },
    { id: 3, type: 'lte', value: 500, relation: 'and' },
  ],
};

const filterConfig: ColumnFilterConfig = {
  disableDynamicFiltering: false,
  multiFilterItems: initialFilters,
};

grid.filter = filterConfig;
```

Conditions within one column can use `and` or `or`. Different columns in `multiFilterItems` always combine with AND. Use `FilterAst` when the query requires cross-column OR, nested groups, or NOT.

## Update applied column state

Call the active filter plugin's `onFilterChange()` method to replace the complete compatibility model without replacing localization, custom operators, selection settings, or other filter configuration:

```ts
import { FilterPlugin, type MultiFilterItem } from '@revolist/revogrid';

const filterPlugin = (await grid.getPlugins()).find(
  (plugin) => plugin instanceof FilterPlugin,
);

const nextFilters: MultiFilterItem = {
  priority: [{ id: 1, type: 'eq', value: 'High', relation: 'and' }],
};

await filterPlugin?.onFilterChange(nextFilters);
```

`AdvanceFilterPlugin` extends Core's `FilterPlugin`, so the same lookup works when Pro filtering is installed. Passing `{}` removes all column conditions.

Use `afterfilterapply` to observe the applied compatibility state:

```ts
import type { MultiFilterItem } from '@revolist/revogrid';

grid.addEventListener('afterfilterapply', (event) => {
  const detail = (event as CustomEvent<{ multiFilterItems: MultiFilterItem }>)
    .detail;
  const appliedFilters = detail.multiFilterItems;
  console.log(appliedFilters);
});
```

## Create reusable presets

A preset can be a `MultiFilterItem`, but reassigning `grid.filter` with only that object would drop the rest of the configuration. Keep one factory that recreates every option:

```ts
import type { ColumnFilterConfig, MultiFilterItem } from '@revolist/revogrid';

function createFilterConfig(
  multiFilterItems: MultiFilterItem = {},
): ColumnFilterConfig {
  return {
    allowDuplicateOperators: true,
    disableDynamicFiltering: false,
    localization: {
      captions: {
        save: 'Apply',
        reset: 'Reset',
      },
    },
    multiFilterItems,
  };
}

const presets: Record<string, MultiFilterItem> = {
  openHighValue: {
    status: [{ id: 101, type: 'eq', value: 'Open', relation: 'and' }],
    total: [{ id: 102, type: 'gte', value: 1000, relation: 'and' }],
  },
  needsReview: {
    status: [
      { id: 201, type: 'eq', value: 'Pending', relation: 'or' },
      { id: 202, type: 'eq', value: 'On Hold', relation: 'or' },
    ],
  },
};

function applyPreset(name: keyof typeof presets) {
  grid.filter = createFilterConfig(presets[name]);
}

function clearPreset() {
  grid.filter = createFilterConfig({});
}
```

When the grid is already initialized, `onFilterChange(presets[name])` is usually simpler because it preserves the active configuration without recreating it.

## Save and restore canonical state

For new saved-view and backend integrations, use Pro's JSON-safe `FilterAst`. Register `AdvanceFilterPlugin`, read a defensive clone with `getFilterAst()`, and restore it atomically with `setFilterAst()`:

```ts
import { AdvanceFilterPlugin, type FilterAst } from '@revolist/revogrid-pro';

grid.plugins = [AdvanceFilterPlugin];

const plugin = (await grid.getPlugins()).find(
  (item) => item instanceof AdvanceFilterPlugin,
) as AdvanceFilterPlugin | undefined;

function saveView(storageKey: string) {
  const ast = plugin?.getFilterAst();
  if (ast) {
    localStorage.setItem(storageKey, JSON.stringify(ast));
  } else {
    localStorage.removeItem(storageKey);
  }
}

async function restoreView(storageKey: string) {
  const saved = localStorage.getItem(storageKey);
  const ast = saved ? (JSON.parse(saved) as FilterAst) : undefined;
  await plugin?.setFilterAst(ast);
}
```

`setFilterAst()` validates the whole tree before applying it. Invalid state rejects without replacing the previous valid filter. Passing `undefined` clears filtering. You can also set initial canonical state with `grid.filter = { filterAst }`; when initial `filterAst`, `multiFilterItems`, and the legacy `collection` are supplied together, `filterAst` takes precedence.

The canonical tree represents conditions, groups, and negation with JSON values. Do not put `Date`, `Set`, functions, cycles, or non-finite numbers in a public AST.

## Compatibility state and JSON

Do not send `MultiFilterItem` directly through `JSON.stringify()` without checking its values. For example, the selection filter stores excluded checklist values in a `Set`, and JSON serializes a `Set` as `{}`.

```ts
const compatibilityState = {
  status: [
    {
      id: 1,
      type: 'selection',
      value: new Set(['archived']),
      relation: 'and',
    },
  ],
};
```

Pro exports compatibility transport helpers that convert values such as `Set` and `Date` to JSON-friendly arrays and ISO strings. They are useful when maintaining an existing `MultiFilterItem` integration, but the compatibility format spans filter-specific runtime contracts. Do not assume those helpers provide a lossless saved-view format for every current or future Pro operator. Prefer `getFilterAst()` for new persistence and remote-filter payloads.

## Clear all filter state

Clear through the plugin so configuration stays installed:

```ts
import { FilterPlugin } from '@revolist/revogrid';

const filterPlugin = (await grid.getPlugins()).find(
  (plugin) => plugin instanceof FilterPlugin,
);

await filterPlugin?.clearFiltering();
```

With `AdvanceFilterPlugin`, `clearFiltering()` also clears quick-filter and canonical AST state. `await plugin.setFilterAst(undefined)` is the equivalent canonical operation and also clears the quick filter.

## Common mistakes

- Assigning `grid.filter = { multiFilterItems }` after configuring localization, custom filters, selection options, or structured filter types. Use `onFilterChange()` or recreate the complete configuration with a factory.
- Treating `multiFilterItems` as cross-column Boolean logic. Different columns combine with AND; use `FilterAst` for cross-column OR and nested groups.
- Mutating a previously applied object and expecting a reactive update. Create the next state and pass it to `onFilterChange()` or `setFilterAst()`.
- Serializing selection-filter `Set` values directly. Use canonical `FilterAst` for new saved views.
- Restoring untrusted JSON without handling rejection from `setFilterAst()`.
- Clearing state by disabling `grid.filter`. Call `clearFiltering()` to keep filtering installed and configured.

## Related guides

- [Filtering Quick Start](/guides/data-filter/filter-basics/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Filter Events](/guides/data-filter/filter-events/)
- [Selection Filter](/guides/data-filter/filter-types/filter-selection/)
- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)

---

# Filter types

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/
Source: src/content/docs/guides/data-filter/filter-types/index.mdx
Description: Choose a RevoGrid Pro structured filter type and open a focused setup, state, and configuration guide for that control.

---

# Array Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/array-filter/
Source: src/content/docs/guides/data-filter/filter-types/array-filter.mdx
Description: Filter array-valued cells with strict empty-array and non-empty-array operators.

The Pro Array Filter adds two valueless operators for array-valued cells. Add
`AdvanceFilterPlugin` and use the `array` family:

## Quick start

```ts
import { AdvanceFilterPlugin, FILTER_ARRAY } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'tags',
    name: 'Tags',
    filter: [FILTER_ARRAY],
  },
];
```

## Operators

| Default label      | Saved operator ID | Matches                    |
| ------------------ | ----------------- | -------------------------- |
| Is empty array     | `isEmptyArray`    | Arrays with `length === 0` |
| Is not empty array | `isNotEmptyArray` | Arrays with `length > 0`   |

Non-arrays match neither operator. Sparse arrays use their actual `length`, so
`new Array(3)` is non-empty. The operators need no filter value and remain
visibly active when restored from `multiFilterItems`.

```ts
grid.filter = {
  multiFilterItems: {
    tags: [
      {
        id: 0,
        type: 'isEmptyArray',
        relation: 'and',
      },
    ],
  },
};
```

Expressions support `empty array`, `not empty array`, `is empty array`, and `is
not empty array`. See [Blank Values](/guides/data-filter/blank-values/) for the
separate configurable blank policy. With `emptyArray: true`, `[]` explicitly
matches both the Core blank operator and `isEmptyArray`.

## Related guides

- [Blank Values](/guides/data-filter/blank-values/)
- [Filter Expressions](/guides/data-filter/filter-expression/)
- [Boolean Filter](/guides/data-filter/filter-types/boolean-filter/)

---

# Array and Tags Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/array-tags/
Source: src/content/docs/guides/data-filter/filter-types/array-tags.mdx
Description: Filter array-valued cells by any, all, none, exact-set, or empty-array semantics.
Surface: grid

Use the array and tags filter for labels, skills, categories, flags, or nested models that resolve to a tag array. Tag identity is typed, so `1`, `'1'`, `true`, and `null` remain distinct values.

## Quick start

```ts
import { AdvanceFilterPlugin, FILTER_ARRAY_TAGS } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'tags',
    name: 'Tags',
    filter: ['array', FILTER_ARRAY_TAGS],
  },
];
grid.source = [{ tags: ['UI', 'API'] }, { tags: ['Docs'] }, { tags: [] }];
grid.filter = true;
```

The popup flattens provider-backed array values into at most 200 typed tag options. The base `'array'` family also keeps the ordinary empty/not-empty operators available.

When rows store tag IDs and a `ColumnDropdown` editor uses `{ value, label }`
options, keep the IDs in the row and filter model. The filter automatically
reuses the normalized dropdown labels in its popup, header summary, and
condition description.

```ts
const tagOptions = [
  { value: 1, label: 'UI' },
  { value: 2, label: 'API' },
];

grid.columns = [{
  prop: 'tags',
  columnType: 'dropdown',
  filter: ['array', FILTER_ARRAY_TAGS],
  dropdown: { source: tagOptions, config: { multiSelect: true, search: true } },
}];
```

For remote labels that are not present in the dropdown source, use
`arrayTags.formatLabel` globally or under `arrayTags.columns[prop]`. An explicit
formatter takes precedence over the dropdown label. Presentation never changes
identity: numeric ID `1` remains distinct from string ID `'1'` during matching
and saved-state restore.

## Operator and saved state

- Structured type: `FILTER_ARRAY_TAGS` (`'arrayTags'`)
- Operator: `ARRAY_TAGS_MATCH` (`'arrayTagsMatch'`)
- Value: `{ mode, values, emptyOnly, exact }`
- Modes: `'any' | 'all' | 'none'`

```ts
grid.filter = {
  multiFilterItems: {
    tags: [
      {
        id: 1,
        type: 'arrayTagsMatch',
        value: {
          mode: 'all',
          values: ['UI', 'API'],
          emptyOnly: false,
          exact: false,
        },
        relation: 'and',
      },
    ],
  },
};
```

This JSON-safe object is the programmatic restore shape. `any` matches at least one selected tag, `all` requires every selected tag, and `none` rejects rows containing any selected tag. `exact` compares the complete normalized set and is ignored for `none`. `emptyOnly` takes precedence and matches only an actual empty array.

## Read tags from nested values

Configure an accessor globally or by column property through `filter.arrayTags`. It receives the cell value plus `{ property, column, model }` context and must return the array to treat as tags.

```ts
import { defineAdvancedFilterConfig } from '@revolist/revogrid-pro';

grid.columns = [
  {
    prop: 'metadata',
    name: 'Labels',
    filter: ['array', FILTER_ARRAY_TAGS],
  },
];

grid.filter = defineAdvancedFilterConfig({
  arrayTags: {
    columns: {
      metadata: {
        accessor: (value) => value?.labels,
      },
    },
  },
});

grid.source = [
  { metadata: { labels: ['Priority', 'Customer'] } },
  { metadata: { labels: ['Internal'] } },
];
```

Use `arrayTags.accessor` for one global rule and `arrayTags.columns[prop].accessor` for exceptions. The per-column accessor wins. The same accessor is used to collect popup choices and evaluate rows.

Accessor functions are not serializable. Server-side filtering must implement the same extraction rule. For a high-cardinality or partially loaded remote source, provide complete array values or prepared `{ kind: 'arrayTags', values }` data rather than deriving choices from one page.

## Common mistakes

- Do not restore `type: 'arrayTags'`; saved conditions use `type: 'arrayTagsMatch'`.
- Do not return a scalar from the accessor. It must return the tag array.
- Do not expect string coercion: numeric `1` and string `'1'` are different tags.
- Do not combine `mode: 'none'` with `exact`; normalization disables exact mode for none.
- Do not use `emptyOnly` for `null`, missing, or sparse arrays. It delegates to strict empty-array semantics (`Array.isArray(value) && value.length === 0`).
- Do not forget to reproduce a custom accessor in a remote filter backend.

## Related guides

- [Structured Filter Types](./)
- [Array Filters](/guides/data-filter/filter-types/array-filter/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Custom and Remote Structured Filters](/guides/data-filter/structured-filter-types/)

---

# Boolean Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/boolean-filter/
Source: src/content/docs/guides/data-filter/filter-types/boolean-filter.mdx
Description: Filter boolean columns with dedicated Yes and No operators, with customizable labels for application-specific wording.

The Boolean Filter adds dedicated, valueless operators for columns whose source
values are boolean primitives. By default, users see **Yes** and **No** in the
advanced-filter popup.

## Quick start

Add `AdvanceFilterPlugin`, then assign `FILTER_BOOLEAN` to the column:

```typescript
import { AdvanceFilterPlugin, FILTER_BOOLEAN } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    name: 'Enabled',
    prop: 'enabled',
    filter: [FILTER_BOOLEAN],
  },
];

grid.source = [{ enabled: true }, { enabled: false }];
```

The string form is equivalent:

```typescript
{
  name: 'Enabled',
  prop: 'enabled',
  filter: ['boolean'],
}
```

## Operators

The displayed names and stored operator keys are intentionally separate:

| Default name | Operator key | Matches                       |
| ------------ | ------------ | ----------------------------- |
| Yes          | `isTrue`     | The boolean primitive `true`  |
| No           | `isFalse`    | The boolean primitive `false` |

The filter uses strict boolean matching. Values such as `'true'`, `'false'`,
`1`, `0`, `null`, and `undefined` are not coerced into boolean matches.
Configuring blank semantics does not change this typed behavior.

## Customize Yes and No

Use `defineAdvancedFilterConfig` to change the displayed operator names. The
operator keys remain `isTrue` and `isFalse`, so saved filter models and matching
behavior do not change.

```typescript
import { defineAdvancedFilterConfig } from '@revolist/revogrid-pro';

grid.filter = defineAdvancedFilterConfig({
  localization: {
    filterNames: {
      isTrue: 'Enabled',
      isFalse: 'Disabled',
    },
  },
});
```

Labels can use any application-specific wording, such as `Active` / `Inactive`
or localized translations.

## Programmatic filter model

Use the stable operator keys when restoring or sending a filter model:

```typescript
grid.filter = defineAdvancedFilterConfig({
  multiFilterItems: {
    enabled: [
      {
        id: 0,
        type: 'isTrue',
        relation: 'and',
      },
    ],
  },
});
```

## Related guides

- [Date Filter](/guides/data-filter/filter-types/date-filter/)
- [Blank Values](/guides/data-filter/blank-values/)
- [Array Filter](/guides/data-filter/filter-types/array-filter/)
- [Filter Selection](/guides/data-filter/filter-types/filter-selection/)
- [Advanced Filter Showcase](/guides/data-filter/filter-showcase/)

---

# Date range filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/calendar-range/
Source: src/content/docs/guides/data-filter/filter-types/calendar-range.mdx
Description: Filter date columns with an inclusive, accessible calendar range picker.

Use the calendar range for booking periods, reporting windows, delivery dates, and other workflows where users choose a fixed start and end day. It shares RevoGrid Pro's calendar navigation, range preview, keyboard focus, disabled-date behavior, and accessibility semantics.

## Quick start

```ts
import { defineCustomElements } from '@revolist/revogrid/loader';
import {
  AdvanceFilterPlugin,
  FILTER_CALENDAR_RANGE,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

defineCustomElements();

const grid = document.createElement('revo-grid');
grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'order', name: 'Order' },
  {
    prop: 'deliveryDate',
    name: 'Delivery',
    filter: ['date', FILTER_CALENDAR_RANGE],
  },
];
grid.filter = true;
document.querySelector('#app')!.append(grid);
grid.source = [
  { order: 'A-100', deliveryDate: '2026-09-02' },
  { order: 'A-101', deliveryDate: '2026-09-14' },
  { order: 'A-102', deliveryDate: '2026-10-01' },
];
```

## Operator and state

- Type ID: `FILTER_CALENDAR_RANGE` (`'calendarRange'`)
- Operator ID: `CALENDAR_RANGE_BETWEEN` (`'calendarRangeBetween'`)
- Value: inclusive ISO date-only bounds `{ from, to, inclusive: true }`

Both dates use `YYYY-MM-DD`. Partial or invalid ranges are not committed. The lower bound must not be after the upper bound in restored state; the interactive editor normalizes a reversed selection.

## Restore a range programmatically

```ts
import {
  CALENDAR_RANGE_BETWEEN,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

grid.filter = defineAdvancedFilterConfig({
  multiFilterItems: {
    deliveryDate: [
      {
        id: 1,
        type: CALENDAR_RANGE_BETWEEN,
        value: { from: '2026-09-01', to: '2026-09-30', inclusive: true },
        relation: 'and',
      },
    ],
  },
});
```

## Calendar configuration

```ts
import {
  createCalendarRangeStructuredFilterType,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

const calendar = createCalendarRangeStructuredFilterType({
  weekStartsOn: 1,
  timeZone: 'Europe/Lisbon',
  locale: 'pt-PT',
  minDate: '2026-01-01',
  maxDate: '2026-12-31',
  disabledDates: ['2026-12-25'],
  showOperator: true,
  showSelectionSummary: true,
  showClearButton: true,
  showCalendar: true,
  calendar: {
    views: ['month', 'year'],
    defaultView: 'month',
    showHeader: true,
    showNavigation: true,
    showPreviousButton: true,
    showNextButton: true,
    showMonthLabel: true,
    showWeekdays: true,
    showOutsideDays: true,
    allowOutsideMonthSelection: false,
    fixedWeeks: true,
    showTodayButton: true,
    isMonthDisabled: month => month === '2026-07-01',
    dayClassName: date => date.endsWith('-25') ? 'holiday' : undefined,
  },
  rangeValidation: {
    minDays: 2,
    maxDays: 31,
    allowSameDay: false,
    allowDisabledDates: false,
    validate: (range, context) =>
      range.from.slice(0, 7) === range.to.slice(0, 7)
        || 'Choose dates within one month',
  },
  onInvalidRange: (range, reason) => {
    console.info('Range rejected', range, reason);
  },
  dateFormat: { day: '2-digit', month: 'short', year: 'numeric' },
  formatDate: (date, context) =>
    new Intl.DateTimeFormat(context.locale, context).format(
      new Date(`${date}T12:00:00Z`),
    ),
});

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [calendar],
});
```

`disabledDates` can also be a callback receiving the ISO date and resolved locale/timezone context. When `weekStartsOn` or `timeZone` is omitted, it inherits the resolved date-filter policy for the column. The calendar renders a bounded month view, so a disabled-date callback does not scan grid rows.

### Filter visibility

| Option | Behavior |
| --- | --- |
| `showOperator` | Shows or hides the operator selector. The first configured operator remains active when hidden. |
| `showSelectionSummary` | Shows or hides the selected-range status chip. |
| `showClearButton` | Shows or hides the clear action. |
| `showCalendar` | Shows or hides the complete calendar body. |
| `operators` | Ordered allow-list for between and single-date operators. |

### Range validation

Validation runs before a completed range is committed. An invalid end date keeps the current start date, displays an accessible error, and leaves the previous filter condition unchanged.

| Option | Behavior |
| --- | --- |
| `rangeValidation.minDays` | Minimum inclusive number of selected calendar days. |
| `rangeValidation.maxDays` | Maximum inclusive number of selected calendar days. |
| `rangeValidation.allowSameDay` | Allows a one-day range. Defaults to `true`. |
| `rangeValidation.allowDisabledDates` | Allows unavailable dates inside a range. Defaults to `true` for compatibility. Endpoints must always be selectable. |
| `rangeValidation.validate` | Final application validator. Return `true`, `false`, or a user-facing error string. |
| `onInvalidRange` | Receives the normalized attempted range, reason, and resolved column/locale/timezone context. |

Invalid, zero, or negative `minDays` and `maxDays` values are ignored. Restored conditions remain a data contract: selection UI validation prevents new invalid interactions but does not silently delete saved filters.

## Independent Calendar component

The visual calendar is an independent Pro UI component exported from `@revolist/revogrid-pro`. Date parsing and calendar arithmetic remain in the `dates` module, but calendar rendering is no longer owned or exported by `plugins/dates/calendar`.

The filter's nested `calendar` object accepts the reusable component's presentation and interaction options:

| Option | Behavior |
| --- | --- |
| `views` | Available `month` and/or `year` views. |
| `defaultView` | Initial view when it is included in `views`. |
| `showHeader` | Hides the complete heading/navigation row. |
| `showNavigation` | Convenience switch for both navigation actions. |
| `showPreviousButton`, `showNextButton` | Independently control navigation actions. |
| `showMonthLabel` | Hides the month/year heading while preserving navigation geometry. |
| `showWeekdays` | Shows or hides weekday labels. |
| `showOutsideDays` | Renders adjacent-month days. |
| `allowOutsideMonthSelection` | Allows rendered adjacent-month days to be selected. |
| `fixedWeeks` | Uses a stable six-week grid when `true`. |
| `showTodayButton` | Shows the Today shortcut. |
| `isMonthDisabled` | Disables complete months in navigation and year view. |
| `dayClassName`, `renderDay` | Customize day presentation from ISO date and state context. |
| `formatMonth`, `formatWeekday`, `formatDayLabel` | Customize visible and accessible date text. |
| `translations` | Overrides any subset of calendar interface labels. |
| `validateSelection`, `onInvalidSelection` | Validates individual selections before `onSelect`. |
| `onViewChange` | Reports month/year view changes. |

The standalone component is controlled: consumers provide `month`, `focusedDate`, optional `selection`/`preview`, and the corresponding change callbacks. Bounds (`minDate`, `maxDate`) and `isDateDisabled` apply to mouse, keyboard, Today, navigation, and year-view interactions.

The previous flat `showOutsideDays`, `allowOutsideMonthSelection`, `fixedWeeks`, and `showTodayButton` filter options remain compatibility aliases. Nested `calendar` values take precedence.

## Localization

Date text uses the configured `locale`. Interface and accessibility text use the normal advanced-filter localization contract. `CALENDAR_RANGE_LOCALIZATION` exports the complete English fallback and stable keys:

```ts
import { defineAdvancedFilterConfig } from '@revolist/revogrid-pro';

grid.filter = defineAdvancedFilterConfig({
  localization: {
    filterNames: {
      calendarRangeBetween: 'Está no intervalo',
    },
    captions: {
      calendarRangeTitle: 'Intervalo de datas',
      calendarRangeBetween: 'entre',
      calendarRangeChooseEnd: 'Escolha a data final',
      calendarRangeEmpty: 'Nenhum intervalo selecionado',
      calendarRangeClear: 'Limpar intervalo de datas',
      calendarRangePreviousMonth: 'Mês anterior',
      calendarRangeNextMonth: 'Mês seguinte',
      calendarRangeCalendar: 'Calendário',
      calendarRangeToday: 'Hoje',
      calendarRangeInvalid: 'Escolha um intervalo válido',
      calendarRangeSameDay: 'Escolha duas datas diferentes',
      calendarRangeTooShort: 'Escolha um intervalo maior',
      calendarRangeTooLong: 'Escolha um intervalo menor',
      calendarRangeContainsDisabledDate: 'O intervalo contém uma data indisponível',
    },
  },
});
```

The independent `Calendar` also exports `CalendarTranslations` and `DEFAULT_CALENDAR_TRANSLATIONS`; its `translations` property accepts a partial override. Application-provided custom validation messages are displayed as supplied, so localize those strings in the application.

## Common mistakes

- Passing datetimes or locale-formatted strings in restored state; use ISO date-only values.
- Omitting `inclusive: true`; other values are rejected.
- Configuring only `locale` and expecting it to set timezone policy; locale formats text, while `timeZone` decides the civil date.
- Assuming disabled dates change source data or reject every programmatic condition; they primarily constrain calendar selection.
- Replacing `grid.filter` for localization without also retaining a configured `structuredFilterTypes` registration.

## Related guides

- [Date and Datetime Filters](/guides/data-filter/filter-types/date-filter/)
- [Relative or Rolling Window](/guides/data-filter/filter-types/relative-window/)
- [Structured Filter Types](/guides/data-filter/filter-types/overview/)
- [Blank Values](/guides/data-filter/blank-values/)

---

# Chip and Badge Toggle Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/chip-badge-toggles/
Source: src/content/docs/guides/data-filter/filter-types/chip-badge-toggles.mdx
Description: Present a small typed status set as configurable visual toggle chips.
Surface: grid

Use Chip and Badge Toggles when a column has a small, recognizable status set that is faster to scan as colored pills than as a long checklist.

## Quick start

```ts
import {
  AdvanceFilterPlugin,
  FILTER_CHIP_BADGE_TOGGLES,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'status',
    name: 'Status',
    filter: ['string', FILTER_CHIP_BADGE_TOGGLES],
  },
];
grid.filter = true;
```

The built-in derives its choices from parsed unique values. It supports finite numbers, booleans, and strings while keeping their types distinct.
When the column uses `ColumnDropdown` object options, badge labels automatically
reuse the matching option label while saved filter values remain the original
typed IDs. A configured `badge` result takes precedence over the dropdown label.

## Operator and state

| Body ID            | Saved operator       | Value shape                                                           |
| ------------------ | -------------------- | --------------------------------------------------------------------- |
| `chipBadgeToggles` | `chipBadgeSelection` | `{ values: (string \| number \| boolean)[], includeBlanks: boolean }` |

`includeBlanks` uses the grid's configured blank semantics. Selecting every available value and including blanks removes the no-op condition.

## Restore selected badges

```ts
grid.filter = {
  multiFilterItems: {
    status: [
      {
        id: 1,
        type: 'chipBadgeSelection',
        value: {
          values: ['Open', 'Blocked'],
          includeBlanks: false,
        },
        relation: 'and',
      },
    ],
  },
};
```

## Configure labels, colors, and order

Replace the built-in registration with a configured version. The stable type and operator IDs do not change:

```ts
import {
  FILTER_CHIP_BADGE_TOGGLES,
  createChipBadgeStructuredFilterType,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

const statusBadges = createChipBadgeStructuredFilterType({
  order: ['Blocked', 'Open', 'Done'],
  maxVisibleBadges: 20,
  badge: ({ value }) => ({
    label: String(value),
    color: value === 'Blocked' ? '#ef4444' : '#22c55e',
  }),
});

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [statusBadges],
});
grid.columns = [
  { prop: 'status', filter: ['string', FILTER_CHIP_BADGE_TOGGLES] },
];
```

`badge` may return a plain label or safe `{ label, className, color }` metadata. Labels render as text, not HTML. The default visible limit is 200 pills; the complete value set still controls matching when the mounted UI is limited.

## Common mistakes

- Do not use presentation labels as saved values. Filtering uses the original typed scalar value.
- Do not pass `null`, `undefined`, or `''` in `values`; represent blanks with `includeBlanks`.
- Do not create hundreds of status chips without setting a useful `maxVisibleBadges`; use the [Faceted List filter](../faceted-list/) for high-cardinality values.
- Do not replace the registration with a different ID. Keep `FILTER_CHIP_BADGE_TOGGLES` so column configuration and saved state remain compatible.

## Related guides

- [Structured Filter Types](./../)
- [Faceted List Filter](../faceted-list/)
- [Blank Values](/guides/data-filter/blank-values/)
- [Remote aggregates and custom structured filters](/guides/data-filter/structured-filter-types/)

---

# Date Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/date-filter/
Source: src/content/docs/guides/data-filter/filter-types/date-filter.mdx
Description: Filter calendar days with absolute comparisons, relative periods, timezones, fiscal calendars, and remote transport.
Surface: grid

Use the Pro date filter when a value represents a calendar day: due dates, business dates, holidays, or reporting periods. Use the [Datetime Filter](/guides/data-filter/filter-types/datetime-filter/) when values represent exact instants such as audit timestamps or scheduled executions.

## Quick start

```ts
import { AdvanceFilterPlugin, FILTER_DATE } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [{ prop: 'dueDate', name: 'Due date', filter: [FILTER_DATE] }];
grid.filter = true;
grid.source = [
  { dueDate: '2026-08-25' },
  { dueDate: '2026-08-26' },
  { dueDate: null },
];
```

A source `YYYY-MM-DD` keeps its written calendar date. A `Date`, epoch value, or ISO datetime with `Z` or an explicit offset is projected into the resolved timezone before the calendar day is compared.

## Advanced example

Start with browser-local behavior. Add a timezone, week-start, or fiscal-calendar policy only when the application has a defined business requirement.

## Filter a day or range

Date equality includes the complete civil day. A `between` range includes both selected days; internally it is evaluated as a half-open range whose end is the start of the following day.

```ts
grid.filter = {
  multiFilterItems: {
    dueDate: [
      {
        id: 1,
        type: 'between',
        value: {
          fromDate: '2026-08-01',
          toDate: '2026-08-31',
        },
        relation: 'and',
      },
    ],
  },
};
```

Use ISO calendar strings in persisted state so the intended day remains explicit.

## Configure timezone and calendar policy

```ts
grid.filter = {
  date: {
    timezoneMode: 'organization',
    organizationTimeZone: 'America/New_York',
    weekStartsOn: 1, // Monday; Sunday is 0
    fiscalYearStart: { month: 2, day: 1 },
    // Ordered allowlist used by every date and datetime menu.
    operators: ['equals', 'before', 'after', 'between', 'today', 'thisFiscalYear'],
    columns: {
      accountingDate: {
        timezoneMode: 'utc',
        // A column entry replaces the global operator list for this field.
        operators: ['between', 'thisFiscalYear'],
      },
      warsawDate: {
        timezoneMode: 'explicit',
        timeZone: 'Europe/Warsaw',
      },
    },
  },
};
```

Settings resolve field by field: defaults, grid policy, then the partial entry in `date.columns[prop]`.
The `operators` array is an ordered allowlist, so it also controls menu order. A column-level array
replaces the grid-level array for that field. The same date IDs configure datetime menus; the plugin
maps them to the corresponding datetime operators internally.

| Mode           | Resolved timezone                                              |
| -------------- | -------------------------------------------------------------- |
| `user`         | `userTimeZone`, otherwise the browser's resolved IANA timezone |
| `organization` | Required `organizationTimeZone`                                |
| `utc`          | `UTC`                                                          |
| `explicit`     | Required `timeZone`                                            |

With no date configuration, behavior remains browser-local and the week starts on Monday. Fiscal
operators are hidden until an effective `fiscalYearStart` is configured globally or for that column.
Once configured, all fiscal quarter and fiscal year operators are available by default; use
`operators` to show only the fiscal choices appropriate for the application. Date calculations still
use January 1 internally when evaluating existing persisted fiscal conditions without an authored
fiscal policy. Initialization rejects unknown operator IDs, invalid IANA names, week indexes outside
`0…6`, missing organization or explicit zones, February 29, and other fiscal dates that do not recur
every year.

The same instant can fall on different calendar days in Warsaw and New York. Calendar strings do not shift: `2026-08-05` remains August 5 under every timezone policy.

## Operators

The date filter provides:

- Comparisons: Equals, Before, After, On or before, On or after, Between, Not equal
- Blank policy: Is blank, Is not blank
- Rolling days: Today, Yesterday, Last 7 days, Next 30 days
- Weeks: This week, Last week, Next week
- Months: This month, Last month
- Calendar periods: This, Previous, and Next quarter or year
- Fiscal periods (when `fiscalYearStart` is set): This, Previous, and Next fiscal quarter or fiscal year

`last7Days` includes today plus the preceding six civil days. `next30Days` includes today plus the following 29 days. Calendar quarters remain January/April/July/October quarters; only fiscal operators use `fiscalYearStart`.

The expression editor uses the same evaluator and captured clock. Examples include `today`, `this week`, `next 30 days`, `this fiscal quarter`, and `between "2026-08-01" and "2026-08-31"`. Expressions still reference only their current column.

## Blank and invalid values

`isEmpty` and `isNotEmpty` use Core's configured blank policy. Invalid nonblank temporal values fail comparisons but are not automatically blank. `false` and `NaN` therefore do not become blank dates.

Read [Blank Values](/guides/data-filter/blank-values/) for policy precedence and missing-property behavior.

## Remote filtering

Each filtering run captures one reference instant. `beforefilterapply` exposes `temporalContext`, and pagination or infinity-scroll `loadData` receives it as the optional seventh argument; the first six arguments are unchanged.

```ts
loadData: async (
  skip,
  take,
  order,
  singleConditionFilters,
  multiConditionFilters,
  quickFilter,
  temporalContext,
) =>
  fetch('/api/rows', {
    method: 'POST',
    body: JSON.stringify({
      skip,
      take,
      order,
      multiConditionFilters,
      quickFilter,
      temporalContext,
    }),
  }).then((response) => response.json());
```

The JSON-safe envelope contains `referenceInstant`, each filtered temporal column's resolved timezone, and condition ranges keyed by `<column>:<filter id>`. UTC boundaries use `start` and `endExclusive`; an unbounded side is `null`.

## Common mistakes

- Using `date` for timestamps that must retain time-of-day precision; use [Datetime Filter](/guides/data-filter/filter-types/datetime-filter/).
- Assuming browser-local time matches the organization's reporting timezone.
- Treating the end of a date range as exclusive; the selected final day is included.
- Sending a relative operator to a server without the captured `temporalContext`.
- Treating invalid nonblank values as blanks.

## Related guides

- [Fiscal Date Filters](/guides/data-filter/filter-types/fiscal-date-filters/)
- [Datetime Filter](/guides/data-filter/filter-types/datetime-filter/)
- [Excel-Style Filter](/guides/data-filter/filter-types/filter-selection-excel-mode/#date-hierarchy)
- [Blank Values](/guides/data-filter/blank-values/)
- [Filter State and Presets](/guides/data-filter/filter-state/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Infinity Scroll](/guides/infinity-scroll/)

---

# Datetime Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/datetime-filter/
Source: src/content/docs/guides/data-filter/filter-types/datetime-filter.mdx
Description: Filter exact instants with second precision, explicit timezone policy, absolute ranges, relative periods, and programmatic state.
Surface: grid

Use the Pro datetime filter for timestamps that represent exact instants: created times, audit events, log entries, and scheduled executions. Use the [Date Filter](/guides/data-filter/filter-types/date-filter/) instead when the source represents a calendar day without a time.

## Quick start

```ts
import { AdvanceFilterPlugin, FILTER_DATETIME } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'createdAt',
    name: 'Created',
    filter: [FILTER_DATETIME],
  },
];
grid.filter = true;
grid.source = [
  { createdAt: '2026-08-26T10:30:00Z' },
  { createdAt: new Date('2026-08-26T14:45:00Z') },
  { createdAt: 1787741100000 },
];
```

Accepted source values are `Date`, epoch milliseconds, and ISO datetimes with `Z` or an explicit offset. Date-only and offset-free source strings are invalid for this type.

## Datetime operators

Datetime saved IDs prefix the shared temporal operator name with `datetime`:

| Example saved ID                                         | Meaning                                            |
| -------------------------------------------------------- | -------------------------------------------------- |
| `datetimeEquals`                                         | Exact selected second                              |
| `datetimeBefore` / `datetimeAfter`                       | Strict instant comparison                          |
| `datetimeOnOrBefore` / `datetimeOnOrAfter`               | Inclusive comparison                               |
| `datetimeBetween`                                        | Inclusive selected seconds                         |
| `datetimeNotEqual`                                       | Not the selected second                            |
| `datetimeIsEmpty` / `datetimeIsNotEmpty`                 | Shared blank policy                                |
| `datetimeToday`, `datetimeLast7Days`, `datetimeThisWeek` | Relative calendar periods in the resolved timezone |

The popup also provides month, quarter, year, and fiscal-period operators. Read the complete list in the [Date Filter operator reference](/guides/data-filter/filter-types/date-filter/#operators).

## Start with a range

```ts
grid.filter = {
  multiFilterItems: {
    createdAt: [
      {
        id: 1,
        type: 'datetimeBetween',
        value: {
          fromDate: '2026-08-26T09:00',
          toDate: '2026-08-26T17:00',
        },
        relation: 'and',
      },
    ],
  },
};
```

The `datetime-local` values are interpreted in the resolved timezone. Equality selects one second; between includes the final selected second. Internally these become half-open UTC ranges for reliable local and remote evaluation.

## Set an explicit timezone

```ts
grid.filter = {
  date: {
    timezoneMode: 'organization',
    organizationTimeZone: 'America/New_York',
    columns: {
      createdAt: {
        timezoneMode: 'explicit',
        timeZone: 'Europe/Lisbon',
      },
    },
  },
};
```

With no date policy, the datetime control uses the browser's local timezone. Configure an IANA timezone when all users must interpret relative periods and wall-clock input consistently.

## Invalid and DST values

- Offset-free source strings such as `2026-08-26T10:30:00` are invalid because they do not identify an instant.
- A wall-clock value inside a daylight-saving gap does not exist and is rejected.
- A repeated wall-clock value is ambiguous and is also rejected.
- Invalid nonblank values fail comparisons; they do not become blank automatically.

## Common mistakes

- Do not use `datetime` for source values such as `2026-08-26`; use `date`.
- Do not restore datetime state with unprefixed date operator IDs.
- Do not assume the browser timezone matches the organization's reporting timezone.
- Use ISO strings in persisted or remote state; JavaScript `Date` objects are not JSON-safe AST input.

## Related guides

- [Fiscal Date Filters](/guides/data-filter/filter-types/fiscal-date-filters/)
- [Date Filter](/guides/data-filter/filter-types/date-filter/)
- [Calendar Range](/guides/data-filter/filter-types/calendar-range/)
- [Timeline Brush](/guides/data-filter/filter-types/timeline-brush/)
- [Blank Values](/guides/data-filter/blank-values/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)

---

# Faceted List Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/faceted-list/
Source: src/content/docs/guides/data-filter/filter-types/faceted-list.mdx
Description: Filter typed scalar values with searchable all-row and visible-row counts.
Surface: grid

Use the Faceted List filter for a searchable value checklist that also shows how many rows contain each value and how many remain visible after other filters.

## Quick start

```ts
import {
  AdvanceFilterPlugin,
  FILTER_FACETED_LIST,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'region', name: 'Region', filter: ['string', FILTER_FACETED_LIST] },
];
grid.filter = true;
```

The body reads both all-row and visible-row value counts. The two counts make it easier to understand which options remain after other column filters are active.

## Operators and state

| Saved operator       | Value shape                               | Matches                       |
| -------------------- | ----------------------------------------- | ----------------------------- |
| `facetedListInclude` | `(string \| number \| boolean \| null)[]` | Values in the saved list      |
| `facetedListExclude` | `(string \| number \| boolean \| null)[]` | Values outside the saved list |

Typed identity is preserved: `1`, `'1'`, and `true` are different options. `null` is shown as **(Blank)** and `''` as **(Empty)**. Non-finite numbers, arrays, objects, and `undefined` are not facet values.

## Display labels for stored IDs

If the column uses `ColumnDropdown` with object options, the facet editor,
condition description, and header selection automatically show each option's
label while saved conditions continue to contain its typed value.

```ts
import { ColumnDropdown } from '@revolist/revogrid-pro';

const statuses = [
  { value: 10, label: 'Open' },
  { value: 20, label: 'Closed' },
];

grid.columnTypes = { dropdown: ColumnDropdown };
grid.columns = [{
  prop: 'statusId',
  columnType: 'dropdown',
  filter: ['number', FILTER_FACETED_LIST],
  dropdown: { source: statuses },
}];
grid.source = [{ statusId: 10 }, { statusId: 20 }];
```

For remote or separately loaded labels, configure `facetedList.formatLabel`
globally or under `facetedList.columns[prop]`. The explicit formatter wins over
the dropdown label and affects presentation only.

```ts
grid.filter = {
  facetedList: {
    columns: {
      statusId: { formatLabel: value => statusLabels.get(value as number) },
    },
  },
};
```

## Restore selected facets

```ts
grid.filter = {
  multiFilterItems: {
    region: [
      {
        id: 1,
        type: 'facetedListInclude',
        value: ['EMEA', 'APAC'],
        relation: 'and',
      },
    ],
  },
};
```

The editor may serialize the smaller equivalent include or exclude list. Selecting every available value removes the condition; selecting none is represented as a non-empty exclusion list so local and remote behavior remain consistent.

## Counts and remote data

Facets use the `valueCounts` aggregate in two scopes:

- `all` describes the complete source available to the filter.
- `visible` applies all active filters except the current facet's own condition.

Local grids derive both from provider-backed row state. Pagination and infinite-scroll grids should supply complete structured-filter aggregates when browser rows are only a window of the remote result.

## Common mistakes

- Do not stringify typed values before restoring them unless the source column is also text; numeric `1` and string `'1'` are intentionally distinct.
- Do not put whole option objects in facet conditions. Store their scalar `value`; use dropdown options or `formatLabel` for presentation.
- Do not assume the UI always saves an include condition. It chooses a smaller equivalent include or exclude representation.
- Do not use this type for arbitrary array-valued cells. Use the [Array and Tags filter](../array-tags/) for arrays.
- Do not treat the visible count as the total source count; it reflects other active filters.

## Related guides

- [Structured Filter Types](./../)
- [Token List Filter](../token-list/)
- [Chip and Badge Toggles](../chip-badge-toggles/)
- [Remote aggregates and custom structured filters](/guides/data-filter/structured-filter-types/)

---

# Selection Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/filter-selection/
Source: src/content/docs/guides/data-filter/filter-types/filter-selection.mdx
Description: Add searchable value checklists with live updates, custom option sources, templates, grouping, and cascading selection lists.

Selection filters let users include or exclude values through a searchable checkbox list. The list is a virtualized nested `revo-grid`, so large option sets render only the visible rows while preserving sorting, search, and checkbox behavior.

Use the default interaction for immediate checkbox updates. When users should review a staged checklist and choose **Apply**, use the dedicated [Excel-Style Filter](/guides/data-filter/filter-types/filter-selection-excel-mode/) preset.

## Quick start

Add `AdvanceFilterPlugin`, then include `selection` in the column's filter families:

```typescript
import { AdvanceFilterPlugin, FIlTER_SELECTION } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    name: 'Fruit',
    prop: 'name',
    filter: ['string', FIlTER_SELECTION],
  },
];

grid.filter = true;
grid.source = [{ name: 'Apple' }, { name: 'Banana' }, { name: 'Pear' }];
```

By default, checked values are included and unchecked values are stored as an excluded-value `Set`. Opening and closing a fully selected list does not create a filter.

Add `grid.filter = { selection: { sortDirection: 'asc' } }` when the options should be sorted rather than kept in source order.

  - Keep the default mode for immediate checkbox updates and optional live row
  filtering while users search. - Use [`selection.excelMode:
  'windows'`](/guides/data-filter/filter-types/filter-selection-excel-mode/) for a
  transactional checklist with Apply, Cancel, tri-state Select All, blanks, and
  date hierarchies.

## Windows Excel mode

`selection.excelMode: 'windows'` changes selection-filter columns into a staged, spreadsheet-style checklist. It keeps the same excluded-value `Set` model but adds Apply, Cancel, tri-state Select All, blanks, search actions, and optional date hierarchies.

See [Excel-Style Filter](/guides/data-filter/filter-types/filter-selection-excel-mode/) for the interactive four-framework example and complete behavior reference. This heading remains available for links created before the guide was separated.

## How the option list behaves

The selection popup keeps the search row fixed at the top and renders option rows through an internal `revo-grid`.

- Search still matches normalized option `value`.
- Select-all only affects currently searched and visible option rows.
- Checked state still means the value is included; unchecked values are stored in the selection filter's excluded-value `Set`.
- Opening and closing a fully selected popup does not create an empty selection filter, so `FilterHeaderPlugin` keeps showing `All`.
- Group rows are visual only; option checkboxes still belong to leaf option rows.

The old `.filter-list li` DOM shape is not part of the public API. Use the visible option behavior or `.filter-list-option` when tests need to interact with option rows.

## Control option values and sources

### Parsed cell values

When a column defines `cellParser`, the built-in selection option loader uses the parsed value for option labels, quick search, and row comparison. This lets rows keep identifiers or structured values while the filter presents and compares the normalized value returned by the parser. Context-aware cascading options use the same parsed values.

```typescript
const statusLabels = {
  1: 'Active',
  2: 'Paused',
};

grid.columns = [
  {
    prop: 'status',
    name: 'Status',
    filter: ['selection'],
    cellParser: (model, column) => statusLabels[model[column.prop]],
  },
];
```

If you provide `selection.getItems`, that custom loader remains the explicit source for option values and labels. See the Core guide on [filtering parsed values](https://rv-grid.com/guide/filters#filter-parsed-values) for the underlying `cellParser` contract.

### Extend source-row eligibility

The built-in selection and slider option loaders emit the cancelable `beforefilteroptionsourcerow` event before a source row contributes a value. Cancel the event to exclude application- or plugin-owned synthetic rows without coupling Advanced Filter to their data shape.

```typescript
import { BEFORE_FILTER_OPTION_SOURCE_ROW_EVENT } from '@revolist/revogrid-pro';

grid.addEventListener(BEFORE_FILTER_OPTION_SOURCE_ROW_EVENT, (event) => {
  if (event.detail.row.__summaryRow) {
    event.preventDefault();
  }
});
```

Grouping rows are excluded before the event is emitted. The `@revolist/pivot` plugin uses this extension automatically for subtotal and grand-total rows. A custom `selection.getItems` loader remains fully application-owned and does not scan or emit events for grid source rows.

## Search and context-aware options

### Quick-search filtering

By default, the selection popup search input does two things:

- narrows the option rows shown inside the popup
- applies a hidden `quickSearch` filter to the grid rows

This preserves the existing behavior for users who expect the grid to narrow while they type. Set `selection.quickSearchFiltering` to `false` when search should only help users find values in the popup and should not change the grid rows until they check or uncheck selection values.

```typescript
grid.filter = {
  selection: {
    quickSearchFiltering: false,
  },
};
```

When selection values are IDs but the popup renders names, use `selection.quickSearchFilter` to match the text users see. The matcher receives normalized `search`, normalized option `value`, display `label`, original `item`, and `columnProp`. If `quickSearchFiltering` remains enabled, grid rows are filtered by the matched option values, so row data can still store IDs.

```typescript
grid.filter = {
  selection: {
    getItems: {
      ownerId: () => [
        { value: 'usr-1', label: 'Ana Silva', email: 'ana@example.com' },
        { value: 'usr-2', label: 'Maks Doe', email: 'maks@example.com' },
      ],
    },
    quickSearchFilter: {
      ownerId: ({ search, label, item }) =>
        `${label} ${item.email}`.toLowerCase().includes(search),
    },
  },
};
```

### Context-aware cascading options

Enable context-aware selection options with `selection.cascadeOptions.enabled`.

- For column **X**, options are built from rows matching all active filters **except filters for X**.
- This keeps current-column values reversible while still narrowing related column options.
- `optionVisibility` supports `hide`, `disable`, and `show`; `hide` is the default.
- Header totals and tooltips always describe context-valid values, even when the popup shows the complete domain.
- The feature is opt-in, and default behavior is unchanged when omitted.

```typescript
grid.filter = {
  selection: {
    cascadeOptions: {
      enabled: true,
      optionVisibility: 'hide',
    },
  },
};
```

See [Cascading Selection Filters](/guides/data-filter/filter-types/filter-selection-cascade/) for a detailed comparison of all three modes and preserved exclusion behavior.

## Custom option sources

By default, the selection filter builds its checkbox list from the current grid data. Use `filter.selection.getItems` when the list should come from somewhere else, for example:

- server-side or infinite-scroll datasets
- a curated allow-list of accepted values
- normalized values that differ from the rendered cell text

Default lists are rebuilt when the popup opens. If a cell value is edited, rows are removed, or `grid.source` is replaced, the next selection popup reflects the latest column values. Values that no longer exist in the source are not shown unless you provide them through a custom `selection.getItems` loader.

When pinned rows should not contribute checkbox values, keep the default loader and restrict its row stores:

```typescript
grid.filter = {
  selection: {
    sourceRowTypes: ['rgRow'],
  },
};
```

The loader receives the current column `prop` and may return data synchronously or asynchronously.

```typescript
grid.filter = {
  selection: {
    getItems: async (prop) => {
      if (prop !== 'name') {
        return [];
      }

      const response = await fetch('/api/filter-options/names');
      const items = await response.json();

      return items.map((item: { id: string; title: string }) => ({
        value: item.id.toLowerCase(),
        label: item.title,
      }));
    },
  },
};
```

If only some columns need custom values, pass a record keyed by column prop:

```typescript
grid.filter = {
  selection: {
    getItems: {
      name: async () => [
        { value: 'apple', label: 'Apple' },
        { value: 'banana', label: 'Banana' },
      ],
      category: () => [
        { value: 'fresh', label: 'Fresh' },
        { value: 'frozen', label: 'Frozen' },
      ],
    },
  },
};
```

Keep `value` aligned with the value used during filter comparison. The built-in selection filter compares lower-cased string values, so custom lists should usually provide lower-cased `value` fields.

## Customize option presentation

### Custom option templates

Use `selection.itemTemplate` to render badges, icons, or richer labels inside the selection popup. The checkbox remains controlled by the filter plugin; the template only replaces the content next to it.

To reuse an existing column renderer without defining a second template, enable `selection.syncCellTemplate`. The option item is exposed as a synthetic row model, including metadata returned by `selection.getItems`, and the current column prop is set to the normalized filter value.

```typescript
grid.filter = {
  selection: {
    syncCellTemplate: {
      availability: true,
    },
    getItems: {
      availability: () => [
        { value: 'in stock', label: 'In stock', tone: 'green' },
        { value: 'backorder', label: 'Backorder', tone: 'amber' },
      ],
    },
  },
};
```

```typescript
grid.filter = {
  selection: {
    getItems: {
      availability: () => [
        { value: 'in stock', label: 'In stock', tone: 'green' },
        { value: 'backorder', label: 'Backorder', tone: 'amber' },
        { value: 'seasonal', label: 'Seasonal', tone: 'indigo' },
      ],
    },
    itemTemplate: {
      availability: (h, { item, label, checked }) =>
        h(
          'span',
          {
            class: `availability-badge availability-badge--${item.tone}`,
            'data-selected': String(checked),
          },
          label,
        ),
    },
  },
};
```

`itemTemplate` receives:

- `columnProp`: Current column property.
- `item`: Original item returned by `selection.getItems` or the default source loader.
- `value`: Normalized value used by selection filtering.
- `label`: Display label.
- `checked`: Whether the option is currently included in the result.

### Option progress

Use `selection.optionProgress` for a responsive distribution bar inside the selection-owned option
row. The label, track, and formatted value share the available width, and unchecked options switch
to the muted visual state automatically. Values read item metadata returned by `selection.getItems`.

```typescript
grid.filter = {
  selection: {
    getItems: {
      status: () => [
        { value: 'processing', label: 'Processing', count: 42 },
        { value: 'shipped', label: 'Shipped', count: 28 },
      ],
    },
    optionProgress: {
      status: {
        valueProp: 'count',
        getMax: ({ values }) => Math.max(1, ...values),
        formatValue: value => `${value} rows`,
      },
    },
  },
};
```

Use `getValue` instead of `valueProp` for derived values, and `max` or `getMax` to control the range.
`showValue: false` hides the trailing value while keeping the accessible progressbar. `ariaLabel`
accepts a string or formatter.

For secondary metadata that is not progress, `selection.optionColumns` still appends ordinary
read-only RevoGrid columns after the selection-owned checkbox and label column.

### Grouped option rows

Selection option rows can be grouped by fields on the option item. This is useful for large curated lists where users need a hierarchy such as family and color, region and country, or category and status.

```typescript
grid.filter = {
  selection: {
    grouping: {
      name: {
        props: ['family', 'color'],
        expandedAll: true,
      },
    },
    getItems: {
      name: () => [
        { value: 'apple', label: 'Apple', family: 'Tree fruit', color: 'Red' },
        { value: 'pear', label: 'Pear', family: 'Tree fruit', color: 'Green' },
        { value: 'lemon', label: 'Lemon', family: 'Citrus', color: 'Yellow' },
      ],
    },
  },
};
```

`selection.grouping` can also be a single `GroupingOptions` object when every selection-filter column should use the same grouping configuration.

### Nested-list plugins and settings

The selection list is a nested grid, and you can pass plugins or grid settings to that nested grid when you need additional rendering behavior.

```typescript
import { AdvanceFilterPlugin } from '@revolist/revogrid-pro';

class SelectionListPlugin {
  constructor(selectionGrid) {
    selectionGrid.setAttribute('data-selection-list-plugin', 'mounted');
  }
}

grid.plugins = [AdvanceFilterPlugin];
grid.filter = {
  selection: {
    plugins: {
      name: [SelectionListPlugin],
    },
    gridSettings: {
      name: {
        theme: 'compact',
        rowSize: 32,
        frameSize: 2,
        hideAttribution: true,
      },
    },
  },
};
```

`selection.plugins` and `selection.gridSettings` accept either a global value or a record keyed by column `prop`.

The filter list owns `source`, `columns`, and `grouping` so filtering, checkbox state, and virtualization stay consistent. Use `selection.grouping` for grouped option rows instead of `gridSettings.grouping`.

## Restore selection state

Selection filters store unchecked values as an excluded-value `Set`. To predefine a selection filter, add a hidden `selection` filter with values that should be excluded.

```typescript
grid.filter = {
  multiFilterItems: {
    name: [
      {
        id: 0,
        type: 'selection',
        value: new Set(['banana', 'lemon']),
        relation: 'and',
        hidden: true,
      },
    ],
  },
};
```

The [Excel-style demo](/guides/data-filter/filter-types/filter-selection-excel-mode/) uses this pattern for the Fruit column, so two fruit values are already unchecked when it loads. See [Filter State and Presets](/guides/data-filter/filter-state/) before persisting this model because a `Set` is not directly JSON-safe.

## Configuration reference

| Option                              | Purpose                                                                                                         |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `sortDirection`                     | Sort options with `'asc'`, `'desc'`, or `'none'`.                                                               |
| `excelMode`                         | Set to `'windows'` for the dedicated [Excel-style checklist](/guides/data-filter/filter-types/filter-selection-excel-mode/). |
| `quickSearchFiltering`              | Choose whether popup search also filters grid rows; defaults to `true`.                                         |
| `quickSearchFilter`                 | Match search text against labels or custom item metadata.                                                       |
| `sourceRowTypes`                    | Choose which row stores feed the default option loader.                                                         |
| `getItems`                          | Provide synchronous or asynchronous custom options globally or by column.                                       |
| `itemTemplate` / `syncCellTemplate` | Customize option content while the plugin retains checkbox behavior.                                            |
| `optionProgress`                    | Add selection-owned responsive progress with checked and unchecked visual states.                               |
| `optionColumns`                     | Append read-only metadata columns for non-progress option details.                                               |
| `grouping`                          | Group option rows using fields returned by `getItems`.                                                          |
| `plugins` / `gridSettings`          | Configure the nested option grid without replacing its owned source, columns, or grouping.                      |
| `cascadeOptions`                    | Build options from rows matching filters in other columns.                                                      |

Default-mode localization includes `selectionTitle` and `selectionSearchPlaceholder`. Excel mode adds the action and blank captions documented in [Excel-Style Filter](/guides/data-filter/filter-types/filter-selection-excel-mode/#localize-the-checklist).

## Related guides

- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)
- [Excel-Style Filter](/guides/data-filter/filter-types/filter-selection-excel-mode/)
- [Selection Cascade](/guides/data-filter/filter-types/filter-selection-cascade/)
- [Filter State and Presets](/guides/data-filter/filter-state/)
- [Filter Header](/guides/data-filter/filter-header/)
- [Filter Expressions](/guides/data-filter/filter-expression/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)

---

# Selection Cascade Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/filter-selection-cascade/
Source: src/content/docs/guides/data-filter/filter-types/filter-selection-cascade.mdx
Description: Enable context-aware cascading options for RevoGrid Pro selection filters.

Use `filter.selection.cascadeOptions.enabled` to make selection options context-aware.

In cascade mode, RevoGrid builds each column's selection list from rows matching all active filters **except filters for the current column**. This keeps the current column reversible while still narrowing options in related columns.

Use `optionVisibility` to control how values outside that context appear. A value is **context-valid** when at least one source row containing that value matches the active filters in the other columns.

| Mode | Options in the popup | Context-invalid options | Best suited for |
| --- | --- | --- | --- |
| `hide` | Context-valid values only | Not rendered | Compact, spreadsheet-style cascading filters |
| `disable` | Complete column domain | Visible but disabled | Showing users why a known value is currently unavailable |
| `show` | Complete column domain | Visible and interactive | Workflows where users must edit future filter state across the complete domain |

`hide` is the default when cascading is enabled. The modes change option presentation and interaction only; they do not change how rows are filtered.

## `hide`: show only relevant options

```ts
cascadeOptions: {
  enabled: true,
  optionVisibility: 'hide',
}
```

Use `hide` for the most direct cascading experience. If the Country filter leaves only Germany, the City popup contains only Berlin and Munich. Paris, Lyon, Warsaw, and Krakow are omitted because they cannot affect the rows in the current country context.

The current column's own filter is still ignored while its option list is built. For example, opening Country continues to show every country allowed by the other active columns, so users can reverse or broaden the Country selection.

## `disable`: reveal unavailable options

```ts
cascadeOptions: {
  enabled: true,
  optionVisibility: 'disable',
}
```

Use `disable` when users benefit from seeing the complete domain. With Germany active, Berlin and Munich remain interactive while cities from France and Poland remain visible with disabled checkboxes.

- Disabled options remain searchable and follow the configured sort order.
- Clicking a disabled option does not change the filter model.
- **Select All** and tree-selection cascades operate only on context-valid options.
- A custom `itemTemplate` receives `disabled: true` for unavailable options.

This mode is useful when an unavailable value should be discoverable without allowing it to change the current cascade.

## `show`: keep the complete domain interactive

```ts
cascadeOptions: {
  enabled: true,
  optionVisibility: 'show',
}
```

Use `show` when users must manage selections across the complete domain even when some values cannot currently affect visible rows. With Germany active, every city remains visible and interactive.

Changing Paris while Germany is active updates the stored City exclusion, but it does not immediately change the displayed rows because no German row has City = Paris. The change becomes observable if the Country filter is later broadened to include France. This makes `show` useful for preparing filter state ahead of an upstream change, but it is less compact than `hide` and offers less availability guidance than `disable`.

## Preserved exclusions and header summaries

Selection filters store excluded values. Every visibility mode preserves those exclusions when an option becomes context-invalid; cascading never silently prunes them.

For example, if Paris is excluded and Country is narrowed to Germany:

- `hide` temporarily removes Paris from the popup.
- `disable` keeps Paris visible and disabled.
- `show` keeps Paris visible and interactive.

When France becomes valid again, Paris returns with its previous unchecked state. The FilterHeader count and tooltip always summarize context-valid values, independently of popup mode. Consequently, `disable` and `show` can display more popup options than the denominator shown in the header badge.

Columns with `cellParser` build and compare their cascading options from parsed values, consistent with the Core [filter parsed values](https://rv-grid.com/guide/filters#filter-parsed-values) behavior.

Set `filter.selection.cascadeOptions.showDependencyNumbers` to `true` to show `1`, `2`, and later badges on active header filter icons in the order those filters are applied. The badges are hidden by default; omit this option or set it to `false` to keep them hidden.

- If `country = Germany` is active, opening the **city** filter shows `Berlin` and `Munich`.
- Opening the **country** filter still shows `Germany`, `France`, and `Poland`.
- The example uses `hide`; switch `optionVisibility` to `disable` or `show` to expose the complete City domain.
- The feature is opt-in and does not change behavior when cascading is disabled.

## Configuration

```ts
grid.filter = {
  multiFilterItems: {
    department: [{ id: 0, type: 'selection', value: ['sales', 'support'], relation: 'and' }],
    country: [{ id: 1, type: 'selection', value: ['france', 'poland'], relation: 'and' }],
  },
  selection: {
    cascadeOptions: {
      enabled: true,
      optionVisibility: 'hide',
      showDependencyNumbers: true,
    },
  },
};
```

## Compatibility with custom getItems

If `selection.getItems` is provided, that custom source is used as-is.
Cascade visibility modes are only applied to the built-in source loader; RevoGrid does not infer contextual availability for custom items.

## Related guides

- [Selection Filter](/guides/data-filter/filter-types/filter-selection/)
- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)
- [Filter Header](/guides/data-filter/filter-header/)

---

# Excel-Style Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/filter-selection-excel-mode/
Source: src/content/docs/guides/data-filter/filter-types/filter-selection-excel-mode.mdx
Description: Configure the Windows Excel-style staged checklist, search actions, blanks, custom values, and date hierarchies.
Surface: grid

Windows Excel mode turns every selection-filter column into a staged checklist modeled after the Windows Excel AutoFilter menu. Users search or check values, review the draft, and then choose **Apply** or **Cancel**.

  Excel mode does not read or write XLSX files and does not connect RevoGrid to
  Microsoft Excel. It only changes the interaction presented by the Pro
  selection filter.

## Quick start

Register `AdvanceFilterPlugin`, enable the selection family on a column, and set the global selection preset to `windows`:

```ts
import { AdvanceFilterPlugin, FIlTER_SELECTION } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { name: 'Status', prop: 'status', filter: [FIlTER_SELECTION] },
  { name: 'Owner', prop: 'owner', filter: ['string'] },
];
grid.filter = {
  selection: {
    excelMode: 'windows',
    sortDirection: 'asc',
  },
};
grid.source = [
  { status: 'Open', owner: 'Ana' },
  { status: 'Closed', owner: 'Maks' },
];
```

`selection.excelMode` is grid-wide selection configuration, but it only changes columns that include the `selection` filter. The Owner column above keeps its ordinary text-filter popup.

The example uses the same setup in Vanilla TypeScript, Vue, React, and Angular. Open the Fruit or Availability filter for a flat checklist, or Harvest date for the date hierarchy.

## Apply, cancel, and close

Excel mode is always transactional, even when `disableDynamicFiltering` is `false` or omitted:

- Checking values and typing in the mini-filter only changes the popup draft.
- **Apply** commits the draft and closes the popup.
- **Cancel**, Escape, outside click, the close button, and switching to another popup discard the draft.
- Replacing the grid source or filter configuration while the popup is open also discards its draft.
- Pressing Enter in the mini-filter applies the current search result and closes the popup.

The popup is checklist-only; it does not show the normal operator dropdown. Use the standard [Selection Filter](/guides/data-filter/filter-types/filter-selection/) when changes should apply immediately or users need the ordinary filter-family workflow.

<figure>
  <img
    src="/images/filter-selection/excel-mode-checklist.jpg"
    alt="Excel-style selection filter with a mini-filter, checked Select All control, collapsed year values, a Blanks option, and Apply and Cancel buttons."
  />
  <figcaption>
    Rows remain unchanged while the checklist is edited and update only after
    Apply.
  </figcaption>
</figure>

## Search and Select All

Typing a non-empty mini-filter selects the matching results and changes the parent action to **Select All Search Results**. Applying immediately keeps the matches and discards selections hidden by the search.

Enable **Add current selection to filter** when the result should instead be the union of the last applied selection and the current matches. Clearing the search returns the checklist to the last applied state.

**Select All** affects the currently visible or searched options. Parent checkboxes show a mixed state when only some of their leaf values are selected.

<figure>
  <img
    src="/images/filter-selection/excel-mode-search.jpg"
    alt="Excel-style selection filter searching for ap, with Select All Search Results, Add current selection to filter, and matching Apple and Grapes options."
  />
  <figcaption>
    Search selects its matches; Add current selection preserves the previously
    applied values as well.
  </figcaption>
</figure>

### Clearing the condition

Checked values are included. Internally, the selection filter stores unchecked values in an excluded-value `Set`. Applying either of these boundary states removes the selection condition:

- every available value is checked
- every available value is unchecked

This normalization avoids leaving a hidden condition that represents the complete option set.

## Blanks and option sources

Empty strings, `null`, and other normalized blank options share the **(Blanks)** item. It remains searchable and sorts after nonblank options in Excel mode.

By default, options are derived from the current grid rows and account for compatible filters on other columns. An explicit synchronous or asynchronous `selection.getItems` is authoritative:

```ts
grid.filter = {
  selection: {
    excelMode: 'windows',
    getItems: {
      status: async () => {
        const response = await fetch('/api/filter-options/status');
        return response.json(); // [{ value: 'open', label: 'Open' }, ...]
      },
    },
  },
};
```

Keep each `value` aligned with the normalized value used for row comparison. Custom item templates, grouping, nested-grid settings, parsed cell values, and cascading options work as described in the general [Selection Filter guide](/guides/data-filter/filter-types/filter-selection/).

## Date hierarchy

Excel mode creates a local-calendar **Year → Month → Day** tree only when the column provides all three signals:

```ts
grid.columns = [
  {
    name: 'Created',
    prop: 'createdAt',
    columnType: 'date',
    filter: ['date', 'selection'],
  },
];
```

The hierarchy starts collapsed and uses browser-locale month names. Multiple timestamps on the same local day share one day node. Parent and Select All checkboxes derive their mixed state from the raw leaf values. Invalid nonblank values remain selectable as flat root options, followed by **(Blanks)**.

<figure>
  <img
    src="/images/filter-selection/excel-mode-date-hierarchy.jpg"
    alt="Excel-style date checklist with 2025 and February expanded to day 03, and mixed-state checkboxes on Select All and the 2025 parent."
  />
  <figcaption>
    The hierarchy groups raw values by their browser-local calendar day while
    preserving each raw leaf for filtering.
  </figcaption>
</figure>

Setting only `columnType: 'date'`, or only including `date` in `filter`, is not enough. Without the full configuration, the column uses a flat selection list.

## Restore applied selection

Restore the same state model used by the default selection filter. The `Set` contains normalized values that should be unchecked:

```ts
grid.filter = {
  multiFilterItems: {
    status: [
      {
        id: 1,
        type: 'selection',
        value: new Set(['closed', 'archived']),
        relation: 'and',
        hidden: true,
      },
    ],
  },
  selection: {
    excelMode: 'windows',
  },
};
```

Do not replace the full `filter` object with only `multiFilterItems` when the grid also uses localization or selection settings. Build the complete configuration or use the active plugin APIs described in [Filter State and Presets](/guides/data-filter/filter-state/).

## Localize the checklist

Override only the captions the application needs:

```ts
import { defineAdvancedFilterConfig } from '@revolist/revogrid-pro';

grid.filter = defineAdvancedFilterConfig({
  localization: {
    captions: {
      selectionSearchPlaceholder: 'Search values...',
      selectionApply: 'Use values',
      selectionCancel: 'Discard',
      selectionSelectAll: '(All values)',
      selectionSelectAllSearchResults: '(All search results)',
      selectionAddCurrentSelection: 'Keep the current selection too',
      selectionBlanks: '(Empty)',
    },
  },
  selection: {
    excelMode: 'windows',
  },
});
```

`defineAdvancedFilterConfig` fills the remaining default filter names and captions.

## Common mistakes

- Expecting Excel mode on a column that does not include the `selection` filter.
- Treating the mini-filter as a live grid search; its draft is committed only by Apply or Enter.
- Expecting `disableDynamicFiltering` to remove Apply and Cancel from Excel mode.
- Saving `multiFilterItems` directly as JSON without converting selection `Set` values.
- Configuring only one of the two required date signals and expecting a hierarchy.
- Returning display labels from `getItems` that do not map to the values compared with row data.

## Related guides

- [Selection Filter](/guides/data-filter/filter-types/filter-selection/)
- [Filter State and Presets](/guides/data-filter/filter-state/)
- [Date Filter](/guides/data-filter/filter-types/date-filter/)
- [Filter Header](/guides/data-filter/filter-header/)
- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)

---

# Slider Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/filter-slider/
Source: src/content/docs/guides/data-filter/filter-types/filter-slider.mdx
Description: Add a numeric range slider with parsed bounds, editable inputs, formatted values, and optional inline header controls.

The slider filter gives numeric columns a two-handle range control. It derives minimum and maximum bounds from eligible row values and stores the active interval in the advanced filter model.

For a fuller example with formatting and additional slider options:

## Quick start

Add `AdvanceFilterPlugin`, then combine the `number` and `slider` filter families on a numeric column:

```ts
import { AdvanceFilterPlugin, FIlTER_SLIDER } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    name: 'Price',
    prop: 'price',
    filter: ['number', FIlTER_SLIDER],
  },
];
grid.filter = true;
grid.source = [{ price: 25 }, { price: 80 }, { price: 140 }];
```

Returning both handles to the complete data range clears the slider condition. Add `FilterHeaderPlugin` when the same range control should also appear directly in the column header.

Add options only when the default control needs customization:

```ts
grid.filter = {
  slider: {
    showRangeInputs: true,
    formatValue: (value) => `$${value.toFixed(2)}`,
  },
};
```

## Parsed cell values and bounds

When the slider column defines `cellParser`, the slider calculates its minimum and maximum bounds from parsed values and applies range filtering to those same values. Use this when the stored value needs normalization before numeric filtering.

Grouping rows and non-finite parsed values are excluded from the bound calculation. The `@revolist/pivot` plugin excludes its total rows through Advanced Filter's cancelable `beforefilteroptionsourcerow` extension event. If no finite values remain, the slider falls back to `0` for both bounds.

```typescript
grid.columns = [
  {
    name: 'Price',
    prop: 'priceInCents',
    filter: ['number', 'slider'],
    cellParser: (model, column) => Number(model[column.prop] ?? 0) / 100,
  },
];
```

See the Core guide on [filtering parsed values](https://rv-grid.com/guide/filters#filter-parsed-values) for the underlying `cellParser` contract.

## Configuration reference

The slider filter can be customized using the following configuration options:

| Option             | Type                  | Default                                      | Description                                                                                                                |
| ------------------ | --------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `headerView`       | `'slider' \| 'range'` | `'slider'`                                   | With `FilterHeaderPlugin`, shows either the interactive slider or a compact formatted `from–to` range in the column header |
| `showTooltips`     | boolean               | true                                         | Shows tooltips when hovering over the slider handles                                                                       |
| `showRangeDisplay` | boolean               | true                                         | Displays the current range values above the slider                                                                         |
| `showRangeInputs`  | boolean               | false                                        | Shows numeric inputs for editing the selected range                                                                        |
| `formatValue`      | function              | `(value) => value.toFixed(2)`                | Custom function to format the displayed values                                                                             |
| `formatInputValue` | function              | `(value) => String(value)`                   | Custom function to format values inside editable range inputs                                                              |
| `parseInputValue`  | function              | `(value) => Number(value.replace(',', '.'))` | Custom function to parse editable range input text                                                                         |

## Styling

The slider component supports custom styling through CSS variables:

```css
revo-grid {
  --slider-color: #c6c6c6; /* Color of the inactive slider track */
  --range-color: #0068f0; /* Color of the active slider range */
  --tooltip-bg: #333333; /* Tooltip background color */
  --tooltip-color: #ffffff; /* Tooltip text color */
}

/* Dark theme support */
revo-grid[theme^='dark'] {
  --slider-color: #c6c6c6;
  --range-color: #0068f0;
  --filter-input-bg: #333333;
  --filter-input-color: #ffffff;
  --tooltip-bg: #f2f2f6;
  --tooltip-color: #333333;
}
```

## Interaction behavior

1. **Range Selection**:
   - The slider provides two handles for selecting a range of values
   - Values are automatically normalized between the minimum and maximum values in your dataset
   - Real-time filtering as users adjust the range

2. **Tooltips**:
   - Interactive tooltips show the exact value when hovering over slider handles
   - Tooltips can be customized using the `formatValue` function
   - Position updates dynamically as the handles move

3. **Range Display**:
   - Optional display of current range values above the slider
   - Formatted values using the same `formatValue` function
   - Clear visual feedback of the selected range

4. **Theme Integration**:
   - Automatically adapts to light and dark themes
   - Customizable colors through CSS variables
   - Consistent look and feel with the rest of your grid

## Combine with other filters

The slider filter can be combined with other filter types for more complex filtering scenarios:

```typescript
grid.columns = [
  {
    name: 'Price',
    prop: 'price',
    filter: ['number', 'slider', 'selection'], // Combine with selection filter
  },
];
```

## Usage guidance

1. **User experience**:
   - Use `showTooltips` for precise value selection
   - Implement `formatValue` for meaningful value display
   - Enable `showRangeDisplay` for clear range visualization

2. **Accessibility**:
   - The handles are native range inputs and remain keyboard-operable.
   - Use `showRangeDisplay` or editable range inputs when users also need exact textual values.

## Related guides

- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)
- [Filter Header](/guides/data-filter/filter-header/)
- [Selection Filter](/guides/data-filter/filter-types/filter-selection/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)

---

# Fiscal Date Filters

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/fiscal-date-filters/
Source: src/content/docs/guides/data-filter/filter-types/fiscal-date-filters.mdx
Description: Configure fiscal years and quarters for Date, Datetime, Relative Window, expressions, and remote filtering.
Surface: grid

Fiscal filters answer business-calendar questions such as “orders in this fiscal quarter” or “events in the previous fiscal year.” Configure the first day of the fiscal year once, then use dynamic operators that move forward with the current date.

For example, with a fiscal year beginning on February 1, September 3, 2026 belongs to:

- the fiscal year from February 1, 2026 through January 31, 2027;
- the fiscal quarter from August 1 through October 31, 2026.

Calendar operators do not change meaning. “This quarter” in the Date or Datetime filter still uses January, April, July, and October boundaries; “This fiscal quarter” uses the configured fiscal calendar.

## Configure the fiscal year

`month` is one-based. The start must be a real calendar date that occurs every year, so February 29 is not accepted.

```ts
import { AdvanceFilterPlugin } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'accountingDate', name: 'Accounting date', filter: 'date' },
  { prop: 'postedAt', name: 'Posted at', filter: 'datetime' },
];
grid.filter = {
  date: {
    fiscalYearStart: { month: 2, day: 1 },
    timezoneMode: 'organization',
    organizationTimeZone: 'Europe/Lisbon',
  },
};
```

Once `fiscalYearStart` is configured, Date and Datetime menus include all six fiscal operators by default. The timezone decides which civil date is “today” when the period is resolved.

## Supported filters

| Filter | Fiscal behavior |
| --- | --- |
| [Date Filter](../date-filter/) | Supports This, Previous, and Next fiscal quarter and fiscal year. |
| [Datetime Filter](../datetime-filter/) | Supports the same periods for exact instants, resolved in the column timezone. Saved IDs use the `datetime` prefix. |
| [Relative Window](../relative-window/) | `thisQuarter`, `yearToDate`, and non-rolling custom quarter/year windows align to `fiscalYearStart`. |
| [Filter Expressions](/guides/data-filter/filter-expression/) | Supports phrases such as `this fiscal quarter` and `previous fiscal year` on date-aware columns. |
| [Date range filter](../calendar-range/) | Does not create fiscal periods automatically; users can select the fiscal boundary dates explicitly. |
| [Timeline Brush](../timeline-brush/) | Supports an opt-in `fiscalYear` mode that groups source values at the configured fiscal-year boundary. |
| [Time Matrix](../time-matrix/) | Does not use fiscal periods; it filters weekday and hour combinations. |

`fiscalYearStart` is shared date policy, but only controls that define aligned quarter or year semantics consume it.

## Group a Timeline Brush by fiscal year

Add `fiscalYear` to the Timeline Brush's enabled granularities to show fiscal-year bins. The mode uses the effective `fiscalYearStart` for the column, so a February 1 anchor produces bins from February 1 through January 31. It is opt-in to avoid duplicating the ordinary calendar-year mode.

```ts
import {
  FILTER_TIMELINE_BRUSH,
  createTimelineBrushStructuredFilterType,
} from '@revolist/revogrid-pro';

grid.columns = [
  {
    prop: 'accountingDate',
    name: 'Accounting date',
    filter: ['date', FILTER_TIMELINE_BRUSH],
  },
];
grid.filter = {
  date: {
    fiscalYearStart: { month: 2, day: 1 },
  },
  structuredFilterTypes: [
    createTimelineBrushStructuredFilterType({
      granularity: 'fiscalYear',
      granularities: ['year', 'fiscalYear'],
    }),
  ],
};
```

Use `format` when you want fiscal-specific labels such as `FY 2026`; the formatter receives the resolved fiscal-year start in its context.

## Choose the available fiscal operators

Use `date.operators` as an ordered allowlist. The same unprefixed IDs configure both Date and Datetime menus; Datetime maps them to its prefixed saved IDs internally.

```ts
grid.filter = {
  date: {
    fiscalYearStart: { month: 2, day: 1 },
    operators: [
      'thisFiscalQuarter',
      'previousFiscalQuarter',
      'nextFiscalQuarter',
      'thisFiscalYear',
      'previousFiscalYear',
      'nextFiscalYear',
    ],
  },
};
```

| Menu label | Date saved ID | Datetime saved ID |
| --- | --- | --- |
| This fiscal quarter | `thisFiscalQuarter` | `datetimeThisFiscalQuarter` |
| Previous fiscal quarter | `previousFiscalQuarter` | `datetimePreviousFiscalQuarter` |
| Next fiscal quarter | `nextFiscalQuarter` | `datetimeNextFiscalQuarter` |
| This fiscal year | `thisFiscalYear` | `datetimeThisFiscalYear` |
| Previous fiscal year | `previousFiscalYear` | `datetimePreviousFiscalYear` |
| Next fiscal year | `nextFiscalYear` | `datetimeNextFiscalYear` |

These operators need no value. They are resolved from the captured reference instant, timezone, and fiscal-year start every time filtering runs.

## Configure individual columns

Put exceptions in `date.columns`. A column inherits the grid policy, then applies its partial override. A column-level `operators` array replaces the global list for that field.

```ts
grid.filter = {
  date: {
    fiscalYearStart: { month: 1, day: 1 },
    operators: ['thisFiscalQuarter', 'thisFiscalYear'],
    columns: {
      accountingDate: {
        fiscalYearStart: { month: 2, day: 1 },
        operators: ['thisFiscalQuarter', 'previousFiscalQuarter'],
      },
      subscriptionDate: {
        fiscalYearStart: { month: 7, day: 1 },
        operators: ['thisFiscalYear', 'previousFiscalYear'],
      },
    },
  },
};
```

This is useful when subsidiaries, products, or reporting columns follow different calendars.

## Restore fiscal filter state

Date and Datetime fiscal conditions are value-free:

```ts
grid.filter = {
  date: {
    fiscalYearStart: { month: 2, day: 1 },
  },
  multiFilterItems: {
    accountingDate: [
      {
        id: 1,
        type: 'thisFiscalQuarter',
        relation: 'and',
      },
    ],
    postedAt: [
      {
        id: 2,
        type: 'datetimePreviousFiscalYear',
        relation: 'and',
      },
    ],
  },
};
```

The canonical Filter AST uses the unprefixed operator with the field's temporal value type:

```ts
{
  type: 'condition',
  field: 'accountingDate',
  operator: 'thisFiscalQuarter',
  valueType: 'date',
}
```

Do not save resolved start and end dates for these operators. Keeping the relative operator makes a saved view advance into the next fiscal period automatically.

## Use fiscal Relative Windows

Relative Window uses the fiscal calendar for its quarter and year alignment:

```ts
import {
  FILTER_RELATIVE_WINDOW,
  createRelativeWindowStructuredFilterType,
} from '@revolist/revogrid-pro';

grid.columns = [
  {
    prop: 'dueDate',
    name: 'Due date',
    filter: ['date', FILTER_RELATIVE_WINDOW],
  },
];

grid.filter = {
  date: {
    fiscalYearStart: { month: 2, day: 1 },
  },
  structuredFilterTypes: [
    createRelativeWindowStructuredFilterType({
      presets: ['thisQuarter', 'yearToDate'],
      customWindow: {
        units: ['quarter', 'year'],
        showRolling: false,
        defaultValue: {
          direction: 'last',
          amount: 1,
          unit: 'quarter',
          rolling: false,
        },
      },
    }),
  ],
};
```

- `thisQuarter` resolves the current fiscal quarter.
- `yearToDate` begins at the current fiscal-year start.
- A custom quarter or year with `rolling: false` follows complete fiscal periods.
- With `rolling: true`, the window is a duration from today and fiscal boundaries do not affect it.

Relative Window saves a versioned expression such as `{ version: 1, mode: 'preset', preset: 'thisQuarter' }`, not the resolved dates.

## Remote filtering

Fiscal periods depend on one reference instant and the effective policy for each column. When filtering is server-side, send the `temporalContext` supplied to `beforefilterapply`, pagination, or infinity-scroll loading. It contains:

- the captured `referenceInstant`;
- each temporal column's resolved timezone and `fiscalYearStart`;
- the resolved UTC `start` and exclusive `endExclusive` boundaries.

Using this envelope prevents the browser and server from resolving “this fiscal quarter” at different times or in different timezones.

## Common mistakes

- Configuring only `operators` without `fiscalYearStart`; fiscal operators stay hidden.
- Using zero-based months; January is `1`, not `0`.
- Expecting `thisQuarter` in the Date filter to become fiscal; use `thisFiscalQuarter`.
- Expecting Calendar Range to generate fiscal periods, or Timeline Brush to do so without enabling `fiscalYear`.
- Persisting resolved dates instead of the relative fiscal operator or Relative Window expression.
- Recalculating the period independently on a remote server instead of using `temporalContext`.

## Related guides

- [Date Filter](../date-filter/)
- [Datetime Filter](../datetime-filter/)
- [Relative or Rolling Window Filter](../relative-window/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Filter Expressions](/guides/data-filter/filter-expression/)

---

# Fuzzy Search Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/fuzzy-search/
Source: src/content/docs/guides/data-filter/filter-types/fuzzy-search.mdx
Description: Match scalar text approximately with a configurable similarity threshold and ranked preview.
Surface: grid

Use the Fuzzy Search filter for names, titles, and other text where misspellings or transposed characters should still find a result. It applies deterministic Damerau-Levenshtein similarity and previews the best matching unique values.

## Quick start

```ts
import { AdvanceFilterPlugin, FILTER_FUZZY } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'customer', name: 'Customer', filter: ['string', FILTER_FUZZY] },
];
grid.filter = true;
```

The popup lets users enter a term and adjust its similarity threshold. Keeping `'string'` also exposes exact text operators.

## Operator and state

| Body ID | Saved operator | Value shape                           |
| ------- | -------------- | ------------------------------------- |
| `fuzzy` | `fuzzy`        | `{ term: string, threshold: number }` |

The term is trimmed. The threshold is clamped to `0..1` and defaults to `0.55` when the saved value is missing or invalid. Matching is case-insensitive; exact and contained text score highly, while word-level similarity also contributes.

## Restore a fuzzy filter

```ts
grid.filter = {
  multiFilterItems: {
    customer: [
      {
        id: 1,
        type: 'fuzzy',
        value: { term: 'Jon Smth', threshold: 0.7 },
        relation: 'and',
      },
    ],
  },
};
```

An empty or whitespace-only term removes the condition.

## Key behavior

- The preview ranks at most five matches by default and considers at most 2,000 unique candidates.
- The predicate and preview use the same deterministic score.
- `null`, `undefined`, objects, and functions do not match; other scalar values are converted to text.
- The preview reads parsed unique column values. With remote or partially loaded rows, provide complete structured-filter aggregates when the preview must represent the full dataset.

The built-in has no per-column option object. Store the desired threshold in the condition value; create or replace a structured registration only when you need a different editor experience.

## Common mistakes

- Do not use a percentage such as `70`; thresholds use the `0..1` range, so use `0.7`.
- Do not expect the preview to scan an unlimited high-cardinality column; its candidate work is deliberately bounded.
- Do not use fuzzy search for exact identifiers. Use the [Token List filter](../token-list/) instead.

## Related guides

- [Structured Filter Types](./../)
- [Token List Filter](../token-list/)
- [Regular Expression Filter](../regular-expression/)
- [Remote aggregates and custom structured filters](/guides/data-filter/structured-filter-types/)

---

# Histogram Brush Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/histogram-brush/
Source: src/content/docs/guides/data-filter/filter-types/histogram-brush.mdx
Description: Filter numeric RevoGrid columns by brushing a range over their value distribution.

The histogram brush is useful for prices, durations, revenue, latency, and other numeric fields where users benefit from seeing the distribution before choosing a range. It reads finite parsed values from the column and commits an inclusive numeric interval.

## Quick start

`AdvanceFilterPlugin` registers the built-in type automatically. Add its stable ID to a numeric column:

```ts
import { defineCustomElements } from '@revolist/revogrid/loader';
import {
  AdvanceFilterPlugin,
  FILTER_HISTOGRAM_BRUSH,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

defineCustomElements();

const grid = document.createElement('revo-grid');
grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'product', name: 'Product' },
  {
    prop: 'revenue',
    name: 'Revenue',
    filter: ['number', FILTER_HISTOGRAM_BRUSH],
  },
];
grid.filter = true;
document.querySelector('#app')!.append(grid);
grid.source = [
  { product: 'Alpha', revenue: 120 },
  { product: 'Beta', revenue: 480 },
  { product: 'Gamma', revenue: 950 },
];
```

## Operator and state

- Type ID: `FILTER_HISTOGRAM_BRUSH` (`'histogramBrush'`)
- Operator ID: `HISTOGRAM_BRUSH_BETWEEN` (`'histogramBrushBetween'`)
- Value: `{ min: number, max: number, inclusive: true }`

Only finite parsed values participate in the histogram and range match. Returning both handles to the complete numeric domain removes the no-op condition. A logarithmic scale falls back to linear when the data includes zero or negative values.

## Restore a range programmatically

Use the same operator and JSON-safe value in `multiFilterItems`:

```ts
import {
  HISTOGRAM_BRUSH_BETWEEN,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

grid.filter = defineAdvancedFilterConfig({
  multiFilterItems: {
    revenue: [
      {
        id: 1,
        type: HISTOGRAM_BRUSH_BETWEEN,
        value: { min: 250, max: 800, inclusive: true },
        relation: 'and',
      },
    ],
  },
});
```

## Configuration

Replace the default registration with a configured instance. Passing only the replacement is enough; the plugin keeps the other built-ins.

```ts
import {
  createHistogramBrushStructuredFilterType,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

const histogram = createHistogramBrushStructuredFilterType({
  bins: 12, // a positive number or 'auto'
  scale: 'log',
  formatValue: (value) => `$${value.toLocaleString()}`,
  formatMatchCount: (count) => `${count.toLocaleString()} rows`,
  chart: {
    type: 'line', // 'bar' | 'line' | 'area'; default is 'bar'
    showPoints: true,
    formatTooltip: (bin, { minLabel, maxLabel, selected }) => ({
      title: `${minLabel} – ${maxLabel}`,
      details: [`${bin.count} rows`, selected ? 'Selected' : 'Outside selection'],
    }),
  },
});

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [histogram],
});
```

`bins: 'auto'` uses a deterministic Sturges-rule count, capped for predictable rendering. A fixed count is normalized to the supported range. Use `cellParser` on the column when stored values need conversion before numeric filtering.

The chart and range slider are separate shared controls. Default per-bin tooltips are keyboard
reachable and localize through `histogramBrushChart`, `histogramBrushItem`, `histogramBrushItems`,
`histogramBrushSelected`, and `histogramBrushOutsideSelection` captions. `formatTooltip` can return
different title/detail content for every bin.

## Common mistakes

- Omitting `AdvanceFilterPlugin`; the Core filter plugin does not render structured bodies.
- Adding the operator ID to `column.filter`; columns opt in with `FILTER_HISTOGRAM_BRUSH`, not `HISTOGRAM_BRUSH_BETWEEN`.
- Restoring strings such as `'250'`; the saved bounds must be finite numbers and `inclusive` must be `true`.
- Expecting `scale: 'log'` with zero or negative data; the editor intentionally uses linear geometry instead.
- Reassigning `grid.filter` with only `multiFilterItems` after configuring a custom registration; include `structuredFilterTypes` again or update the plugin state through its public API.

## Related guides

- [Structured Filter Types](/guides/data-filter/filter-types/overview/)
- [Rating or Progress Threshold](/guides/data-filter/filter-types/rating-progress-threshold/)
- [Statistical Presets](/guides/data-filter/filter-types/statistical-presets/)
- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)

---

# Number Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/number-filter/
Source: src/content/docs/guides/data-filter/filter-types/number-filter.mdx
Description: Configure Core numeric equality, comparisons, ranges, blank checks, initial state, and parsed values.
Surface: grid

Use the Core number filter for prices, quantities, percentages, scores, and other numeric fields. It needs no Pro plugin.

## Quick start

```ts
const grid = document.querySelector('revo-grid')!;

grid.columns = [
  { prop: 'price', name: 'Price', filter: 'number' },
  { prop: 'quantity', name: 'Quantity', filter: 'number' },
];
grid.filter = true;
grid.source = [
  { price: 120, quantity: 2 },
  { price: 80, quantity: 10 },
];
```

## Operators

| Saved ID   | Popup label  | Meaning                     |
| ---------- | ------------ | --------------------------- |
| `eqN`      | `=`          | Equal                       |
| `neqN`     | `!=`         | Not equal                   |
| `gt`       | `>`          | Greater than                |
| `gte`      | `>=`         | Greater than or equal       |
| `lt`       | `<`          | Less than                   |
| `lte`      | `<=`         | Less than or equal          |
| `empty`    | Is blank     | Uses the blank policy       |
| `notEmpty` | Is not blank | Inverse of the blank policy |

Numeric comparisons require the parsed cell value to be a number. Use `cellParser` when source values arrive as formatted strings.

## Start with a numeric range

Use two conditions joined by `and`:

```ts
grid.filter = {
  multiFilterItems: {
    price: [
      { id: 1, type: 'gte', value: 100, relation: 'and' },
      { id: 2, type: 'lte', value: 500, relation: 'and' },
    ],
  },
};
```

## Parse formatted source values

```ts
grid.columns = [
  {
    prop: 'price',
    name: 'Price',
    filter: 'number',
    cellParser: (model, column) =>
      Number(String(model[column.prop] ?? '').replace(/[$,]/g, '')),
  },
];
```

Filtering and bounds-based Pro controls use the parsed number. Blank checks still use the original source value and own-property presence.

## Choose Core conditions or a Pro control

Use Core operators when users know the exact threshold they want. Choose a visual control when the data shape should guide them:

- [Slider Filter](/guides/data-filter/filter-types/filter-slider/) for a simple inclusive interval
- [Histogram Brush](/guides/data-filter/filter-types/histogram-brush/) for a range over a visible distribution
- [Rating or Progress Threshold](/guides/data-filter/filter-types/rating-progress-threshold/) for stars, percentages, or scores
- [Statistical Presets](/guides/data-filter/filter-types/statistical-presets/) for relative population rules

## Common mistakes

- Use `eqN` for numeric equality and `eq` for text equality.
- Convert numeric strings with `cellParser`; `gt`, `gte`, `lt`, and `lte` do not treat arbitrary strings as numbers.
- Keep `0` distinct from blank unless your application explicitly changes the blank policy.
- Use two conditions for a range; there is no Core `between` operator in the popup.

## Related guides

- [Filtering Quick Start](/guides/data-filter/filter-basics/)
- [Text Filter](/guides/data-filter/filter-types/text-filter/)
- [Blank Values](/guides/data-filter/blank-values/)
- [Slider Filter](/guides/data-filter/filter-types/filter-slider/)

---

# Overview

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/overview/
Source: src/content/docs/guides/data-filter/filter-types/overview.mdx
Description: Choose a Core or Pro filter type and open the focused setup, state, and configuration guide for that control.
Surface: grid

Filter types cover Core condition families, Pro value controls, and global quick filtering. Choose the control that matches the column data and the way users need to narrow it.

## Common filter controls

| Type                                                     | Best for                                  |
| -------------------------------------------------------- | ----------------------------------------- |
| [Text](../text-filter/)                                  | Names, labels, codes, and descriptions    |
| [Number](../number-filter/)                              | Equality, comparisons, and numeric ranges |
| [Selection](../filter-selection/)                        | Searchable checklists of known values     |
| [Excel-style Selection](../filter-selection-excel-mode/) | Staged Apply/Cancel checklists            |
| [Selection Cascade](../filter-selection-cascade/)        | Context-aware dependent value lists       |
| [Slider](../filter-slider/)                              | Visual numeric interval selection         |
| [Date](../date-filter/)                                  | Calendar days and relative periods        |
| [Datetime](../datetime-filter/)                          | Exact instants and timezone-aware ranges  |
| [Boolean](../boolean-filter/)                            | Strict Yes/No values                      |
| [Array](../array-filter/)                                | Empty and non-empty arrays                |
| [Quick Filter](../quick-filter/)                         | Search words across several columns       |

Need reporting periods that do not start in January? Configure [Fiscal Date Filters](../fiscal-date-filters/) for Date, Datetime, and aligned Relative Window conditions.

## Structured control quick start

Structured filter types add purpose-built controls to the Pro filter popup while keeping the standard RevoGrid filter model. `AdvanceFilterPlugin` registers all built-ins, but each column opts into the controls it needs.

```ts
import {
  AdvanceFilterPlugin,
  FILTER_FACETED_LIST,
  FILTER_HISTOGRAM_BRUSH,
  FILTER_TOKEN_LIST,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'sku', filter: ['string', FILTER_TOKEN_LIST] },
  { prop: 'region', filter: ['string', FILTER_FACETED_LIST] },
  { prop: 'revenue', filter: ['number', FILTER_HISTOGRAM_BRUSH] },
];
grid.filter = true;
```

The first array entry keeps the ordinary string or number operators available. The structured type adds its specialized body above the ordinary condition list. Conditions still serialize as `multiFilterItems` and compile into the canonical `FilterAst`.

## Structured controls

| Type                                                          | Best for                              | Reads column data            |
| ------------------------------------------------------------- | ------------------------------------- | ---------------------------- |
| [Token List](../token-list/)                                  | Pasted exact values                   | No                           |
| [Fuzzy Search](../fuzzy-search/)                              | Approximate text matches              | Unique values for preview    |
| [Regular Expression](../regular-expression/)                  | Pattern-based text matching           | Unique values for preview    |
| [Faceted List](../faceted-list/)                              | Searchable values with counts         | All and visible value counts |
| [Chip and Badge Toggles](../chip-badge-toggles/)              | Small visual status sets              | Unique values                |
| [Histogram Brush](../histogram-brush/)                        | Numeric distributions and ranges      | Numeric values and bounds    |
| [Rating or Progress Threshold](../rating-progress-threshold/) | Stars, percentages, or scores         | No                           |
| [Statistical Presets](../statistical-presets/)                | Top 10%, average, quartiles, outliers | Numeric values and bounds    |
| [Calendar Range](../calendar-range/)                          | Inclusive date-only ranges            | No                           |
| [Relative Window](../relative-window/)                        | Rolling date periods                  | No                           |
| [Timeline Brush](../timeline-brush/)                          | Date or datetime density and ranges   | Temporal values              |
| [Time Matrix](../time-matrix/)                                | Weekday and hour schedules            | No                           |
| [Tri-state Boolean](../tri-state-boolean/)                    | All, Yes, No, and optional blanks     | Value counts                 |
| [Array and Tags](../array-tags/)                              | Any, all, none, exact, or empty tags  | Array values                 |

## Common setup pattern

Every focused guide uses the same three steps:

1. Register `AdvanceFilterPlugin` once on the grid.
2. Put the structured type constant in the matching column's `filter` array.
3. Use `multiFilterItems` only when the application needs an initial or restored condition.

```ts
grid.filter = {
  multiFilterItems: {
    sku: [
      {
        id: 1,
        type: 'tokenListAnyOf',
        value: ['EU-100', 'EU-200'],
        relation: 'and',
      },
    ],
  },
};
```

The saved `type` is the operator ID, not the structured body ID. Each type guide lists both IDs and the exact JSON-safe value shape.

## Configuration and remote data

Built-in factory options belong to the structured type registration, not to an individual column. Replace a built-in registration when you need custom formatting, limits, locale, colors, or other presentation policy.

For pagination and infinite-scroll datasets, the browser may hold only part of the result. Supply complete server aggregates when a data-derived control must represent the entire remote dataset rather than the loaded page.

Read [Custom Structured Filter Types](/guides/data-filter/structured-filter-types/) for registration replacement, lazy aggregates, remote prepared data, and building a custom body.

## Related guides

- [Filtering Quick Start](/guides/data-filter/filter-basics/)
- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Custom Filter Operators](/guides/data-filter/custom-filter-operators/)
- [Filter Expressions](/guides/data-filter/filter-expression/)

---

# Quick Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/quick-filter/
Source: src/content/docs/guides/data-filter/filter-types/quick-filter.mdx
Description: Add a debounced global search that composes with RevoGrid Pro column filters.
Surface: grid

Quick Filter is RevoGrid Pro's global row search. Use it for a toolbar search box that should look across several columns without creating one filter condition per field.

## Quick start

Register `AdvanceFilterPlugin`, configure the searchable columns, and assign the search text to `grid.quickFilter`:

```ts
import { AdvanceFilterPlugin } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'customer', name: 'Customer' },
  { prop: 'city', name: 'City' },
  { prop: 'status', name: 'Status', filter: 'string' },
];
grid.filter = true;

grid.quickFilter = 'Lisbon pending';
```

The direct `quickFilter` property is preferred. The older `additionalData.quickFilter` path remains available for compatibility.

## String and object forms

Use a string for the default 150 ms debounce and all visible regular data columns:

```ts
grid.quickFilter = 'Lisbon pending';
```

Use the object form to choose exact column properties or change the debounce:

```ts
grid.quickFilter = {
  text: 'Lisbon pending',
  columns: ['city', 'status'],
  debounceMs: 250,
};
```

| Field        | Default                      | Behavior                                  |
| ------------ | ---------------------------- | ----------------------------------------- |
| `text`       | Required                     | Trimmed and collapsed to single spaces    |
| `columns`    | Visible regular data columns | Exact, duplicate-free property list       |
| `debounceMs` | `150`                        | Finite values are clamped to at least `0` |

Omitting `columns` searches visible regular columns. Providing `columns: []` deliberately searches no fields and therefore matches no row while the query contains a token.

## How tokens match

Search is case-insensitive. Normalized text is split on spaces, and every token must appear in at least one searched column. Different tokens may match different columns in the same row.

For example, `Lisbon pending` matches a row when `Lisbon` appears in its city and `pending` appears in its status. This is equivalent to:

```text
(customer contains Lisbon OR city contains Lisbon OR status contains Lisbon)
AND
(customer contains pending OR city contains pending OR status contains pending)
```

Quick Filter reads parsed cell values. A column `cellParser` or Pro value-resolution hook therefore affects both global search and advanced filter option values. Dropdown columns are searched by their visible option labels, including every label in a multi-select value, even when the row stores option IDs through `valueKey`.

## Clear the search

Assign an empty or whitespace-only string:

```ts
grid.quickFilter = '';
```

Whitespace normalization means `'   '` also clears the active quick filter.

## Observe or intercept changes

Quick-filter changes emit a cancelable event before filtering and a completion event afterward:

```ts
grid.addEventListener('beforequickfilterapply', (event) => {
  console.log('Applying', event.detail.quickFilter);
});

grid.addEventListener('afterquickfilterapply', async (event) => {
  const visibleRows = await grid.getVisibleSource();
  console.log('Applied', event.detail.quickFilter, visibleRows.length);
});
```

Both event details contain the normalized `quickFilter`, current `source`, and columns. Clearing emits the same events with `quickFilter` set to `undefined`. If `beforequickfilterapply` is prevented, local filtering and `afterquickfilterapply` do not run.

## Combine with column filters

Quick Filter is ANDed with active column conditions and the canonical Filter AST:

```ts
grid.filter = {
  multiFilterItems: {
    amount: [{ id: 1, type: 'gte', value: 200, relation: 'and' }],
  },
};
grid.quickFilter = 'Lisbon pending';
```

A row must satisfy the amount condition and every quick-filter token. Quick Filter does not add a synthetic column entry to `multiFilterItems`; Pro composes it into the effective `FilterAst` with `quickContains` conditions.

## Remote data

The Pro Pagination, Infinity Scroll, and Server-Side Grouping plugins intercept `beforequickfilterapply`, prevent local filtering, and pass the normalized quick filter to their remote loaders. Pagination and Infinity Scroll receive it as the optional sixth `loadData` argument. They emit `afterquickfilterapply` only after the winning remote request updates the source.

For a custom remote adapter, prevent `beforequickfilterapply`, cancel or ignore stale requests, send `event.detail.quickFilter` to the backend, replace `grid.source`, and emit a completion signal only for the latest response.

## Common mistakes

- Do not expect `columns: []` to mean all columns; omit `columns` for the default search set.
- Do not split the query yourself. RevoGrid normalizes whitespace and applies its AND-across-tokens semantics.
- Do not expect each token to match the same column; tokens may match different fields in one row.
- Do not read `event.detail.source` as the filtered result. Use `getVisibleSource()` after local completion.
- Do not use the deprecated `additionalData.quickFilter` path in new code.

## Related guides

- [Filtering Quick Start](/guides/data-filter/filter-basics/)
- [Filter Events](/guides/data-filter/filter-events/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)

---

# Rating or Progress Threshold Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/rating-progress-threshold/
Source: src/content/docs/guides/data-filter/filter-types/rating-progress-threshold.mdx
Description: Filter ratings, percentages, and bounded scores with an accessible threshold control.

Use this filter for star ratings, completion percentages, health scores, and other bounded numeric values. Users choose greater-than-or-equal, equal, or less-than-or-equal and then set one threshold.

## Quick start

```ts
import { defineCustomElements } from '@revolist/revogrid/loader';
import {
  AdvanceFilterPlugin,
  FILTER_RATING_PROGRESS_THRESHOLD,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

defineCustomElements();

const grid = document.createElement('revo-grid');
grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'task', name: 'Task' },
  {
    prop: 'rating',
    name: 'Rating',
    filter: ['number', FILTER_RATING_PROGRESS_THRESHOLD],
  },
];
grid.filter = true;
document.querySelector('#app')!.append(grid);
grid.source = [
  { task: 'Design', rating: 4.5 },
  { task: 'Build', rating: 3 },
  { task: 'Review', rating: 5 },
];
```

## Operators and state

| Operator | Stable ID             | Meaning                                         |
| -------- | --------------------- | ----------------------------------------------- |
| At least | `RATING_PROGRESS_GTE` | Value is greater than or equal to the threshold |
| Exactly  | `RATING_PROGRESS_EQ`  | Value equals the threshold                      |
| At most  | `RATING_PROGRESS_LTE` | Value is less than or equal to the threshold    |

The condition value is one finite number. The type ID is `FILTER_RATING_PROGRESS_THRESHOLD` (`'ratingProgressThreshold'`). Values are clamped to `0…max` and aligned to the configured step.

## Restore a threshold programmatically

```ts
import {
  RATING_PROGRESS_GTE,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

grid.filter = defineAdvancedFilterConfig({
  multiFilterItems: {
    rating: [
      {
        id: 1,
        type: RATING_PROGRESS_GTE,
        value: 4,
        relation: 'and',
      },
    ],
  },
});
```

## Configuration

The default presentation is stars with `max: 5` and `step: 1`. Percent and score presentations default to a maximum of `100`.

```ts
import {
  createRatingProgressThresholdStructuredFilterType,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

const progress = createRatingProgressThresholdStructuredFilterType({
  unit: 'percent', // 'stars', 'percent', or 'score'
  max: 100,
  step: 5,
  formatValue: (value) => `${value}%`,
});

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [progress],
});
```

`max` and `step` must be positive. A step larger than the maximum is normalized to the maximum. `formatValue` changes the displayed value text; it does not transform source values.

## Common mistakes

- Using `FILTER_RATING_PROGRESS_THRESHOLD` as the condition operator; saved conditions use one of the three `RATING_PROGRESS_*` operator IDs.
- Supplying a string threshold such as `'80'`; restore a finite number.
- Using `formatValue` to convert a `0…1` source into a percentage. Use `cellParser` for conversion, then configure the visual domain.
- Choosing `RATING_PROGRESS_EQ` with fractional data while using a step that cannot select those fractions.
- Omitting the configured registration when replacing the complete `grid.filter` object later.

## Related guides

- [Structured Filter Types](/guides/data-filter/filter-types/overview/)
- [Histogram Brush](/guides/data-filter/filter-types/histogram-brush/)
- [Statistical Presets](/guides/data-filter/filter-types/statistical-presets/)
- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)

---

# Regular Expression Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/regular-expression/
Source: src/content/docs/guides/data-filter/filter-types/regular-expression.mdx
Description: Match or exclude scalar text with a validated regular expression and bounded preview.
Surface: grid

Use the Regular Expression filter when users need an explicit text pattern, such as an invoice prefix, an email domain, or a controlled identifier format.

## Quick start

```ts
import { AdvanceFilterPlugin, FILTER_REGEX } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'invoiceId', name: 'Invoice ID', filter: ['string', FILTER_REGEX] },
];
grid.filter = true;
```

The popup validates the pattern before committing it and previews matching unique values.

## Operators and state

| UI mode                | Saved operator    | Value shape                          |
| ---------------------- | ----------------- | ------------------------------------ |
| Matches pattern        | `regexMatches`    | `{ pattern: string, flags: string }` |
| Does not match pattern | `regexNotMatches` | `{ pattern: string, flags: string }` |

Supported flags are `i` for case-insensitive matching and `m` for multiline anchors. Flags are normalized into stable `im` order and duplicates are removed.

## Restore a regular expression

```ts
grid.filter = {
  multiFilterItems: {
    invoiceId: [
      {
        id: 1,
        type: 'regexMatches',
        value: { pattern: '^INV-\\d{6}$', flags: 'i' },
        relation: 'and',
      },
    ],
  },
};
```

An empty pattern removes the condition. Invalid patterns remain in the editor without replacing the last valid condition.

## Validation and preview

RevoGrid rejects invalid expressions and common nested-quantifier patterns that can cause catastrophic backtracking. The preview shows two matching unique values by default and scans at most 10,000 unique scalar values. Matching uses parsed scalar values; `null`, `undefined`, objects, and functions do not match either operator.

For remote or partially loaded rows, provide complete unique-value aggregates when the preview must describe the full result set. The saved pattern and flags remain the remote execution contract.

## Common mistakes

- Escape backslashes for JavaScript strings. A regex digit class is written as `\\d` inside the saved string.
- Do not add unsupported flags such as `g`, `s`, or `u`; only `i` and `m` are retained.
- Do not expect an invalid edit to clear a working filter; the last valid condition stays active.
- Do not use arbitrary user-supplied patterns without considering backend regex compatibility when filtering remotely.

## Related guides

- [Structured Filter Types](./../)
- [Fuzzy Search Filter](../fuzzy-search/)
- [Token List Filter](../token-list/)
- [Remote aggregates and custom structured filters](/guides/data-filter/structured-filter-types/)

---

# Relative or Rolling Window Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/relative-window/
Source: src/content/docs/guides/data-filter/filter-types/relative-window.mdx
Description: Filter dates with saved expressions such as last seven days, this quarter, or a custom rolling window.

Use relative windows for dashboards, queues, renewals, overdue work, and saved views that should move with the current date. Unlike a fixed calendar range, the saved state is an expression that resolves against the filter run's captured reference date.

## Quick start

```ts
import { defineCustomElements } from '@revolist/revogrid/loader';
import {
  AdvanceFilterPlugin,
  FILTER_RELATIVE_WINDOW,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

defineCustomElements();

const grid = document.createElement('revo-grid');
grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'task', name: 'Task' },
  { prop: 'dueDate', name: 'Due', filter: ['date', FILTER_RELATIVE_WINDOW] },
];
grid.filter = true;
document.querySelector('#app')!.append(grid);
grid.source = [
  { task: 'Renew license', dueDate: '2026-08-24' },
  { task: 'Send report', dueDate: '2026-08-26' },
  { task: 'Plan launch', dueDate: '2026-09-10' },
];
```

## Operator and state

Both the type and operator use the stable ID `'relativeWindow'`, exported as `FILTER_RELATIVE_WINDOW` and `RELATIVE_WINDOW_OPERATOR`.

Saved values are versioned expressions:

```ts
{ version: 1, mode: 'preset', preset: 'last7Days' }

{
  version: 1,
  mode: 'custom',
  direction: 'next',
  amount: 2,
  unit: 'week',
  rolling: false,
}
```

Preset IDs are `last7Days`, `today`, `thisMonth`, `thisQuarter`, `yearToDate`, and `overdue`. Custom directions are `last` and `next`; units are `day`, `week`, `month`, `quarter`, and `year`.

## Restore a relative window

```ts
import {
  RELATIVE_WINDOW_OPERATOR,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

grid.filter = defineAdvancedFilterConfig({
  multiFilterItems: {
    dueDate: [
      {
        id: 1,
        type: RELATIVE_WINDOW_OPERATOR,
        value: { version: 1, mode: 'preset', preset: 'last7Days' },
        relation: 'and',
      },
    ],
  },
});
```

The expression remains relative. Each filtering run captures one reference instant, so every row and date-aware condition in that run uses the same “today.”

## Configuration

The shortcut row and custom-window controls are independently configurable. Built-in preset IDs can be hidden, reordered, or mixed with application-specific shortcuts:

```ts
import {
  createRelativeWindowStructuredFilterType,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

const relativeWindow = createRelativeWindowStructuredFilterType({
  locale: 'en-GB',
  dateFormat: { day: '2-digit', month: 'short', year: 'numeric' },
  presets: [
    'today',
    'thisMonth',
    {
      id: 'next-fortnight',
      label: 'Next 14 days',
      title: 'Rolling from today',
      expression: {
        version: 1,
        mode: 'custom',
        direction: 'next',
        amount: 14,
        unit: 'day',
        rolling: true,
      },
    },
    'overdue',
  ],
  customWindow: {
    directions: ['last', 'next'],
    units: ['day', 'week', 'month'],
    showRolling: true,
    defaultValue: {
      direction: 'next',
      amount: 2,
      unit: 'week',
      rolling: false,
    },
  },
  showHeading: true,
  showPreview: true,
});

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [relativeWindow],
  date: {
    timezoneMode: 'organization',
    organizationTimeZone: 'Europe/Lisbon',
    weekStartsOn: 1,
    fiscalYearStart: { month: 2, day: 1 },
  },
});
```

Custom shortcuts do not extend or bypass the date-expression model. Each button is backed by a normal validated `RelativeDateWindowExpression`, and selecting it persists only that expression. Its `id` identifies the button; `label`, `ariaLabel`, `title`, and `disabled` control its presentation. A matching custom label is also used in the compact condition summary.

### Visibility and allowed values

| Option | Behavior |
| --- | --- |
| `presets` | Ordered built-in IDs and custom shortcuts. Use `false` or `[]` to hide the shortcut row. |
| `customWindow` | Custom editor settings. Use `false` to hide the whole Last/Next, amount, unit, and rolling section. |
| `customWindow.directions` | Allowed direction choices: `last`, `next`, or both. |
| `customWindow.units` | Allowed unit choices: `day`, `week`, `month`, `quarter`, and/or `year`. |
| `customWindow.showRolling` | Set to `false` to hide the rolling switch and keep the configured/default rolling policy. |
| `customWindow.defaultValue` | Initial direction, amount, unit, and rolling policy when no custom expression is saved. |
| `showHeading` | Set to `false` to hide the in-body title and description while retaining an accessible section label. |
| `showPreview` | Set to `false` to hide the resolved absolute-date preview. |
| `locale`, `dateFormat` | Format preview text only. |

For example, a compact preset-only editor can omit every other section:

```ts
createRelativeWindowStructuredFilterType({
  presets: ['today', 'last7Days', 'overdue'],
  customWindow: false,
  showHeading: false,
  showPreview: false,
});
```

The default remains unchanged when these options are omitted: all six built-ins, the complete custom editor, rolling switch, heading, and preview are shown. Duplicate shortcut IDs or expressions and invalid custom expressions are ignored. An empty direction or unit list hides the custom editor because it cannot produce a valid expression.

`locale` and `dateFormat` affect preview text only. Timezone decides the reference civil date, `weekStartsOn` controls calendar-week windows, and `fiscalYearStart` controls quarter and year policy where applicable.

For a custom expression, `amount` must be an integer from `1` through `10,000`. `rolling: true` uses a rolling duration; `rolling: false` resolves complete calendar units.

## Common mistakes

- Saving the preview's absolute `{ from, to }` range instead of the versioned expression; that turns a moving saved view into a fixed range.
- Omitting `version: 1` or using unsupported preset, direction, or unit strings.
- Treating `last7Days` as seven 24-hour durations; it is a civil-date window resolved in the column timezone.
- Using an offset-free datetime source for date filtering without first deciding the intended timezone and source contract.
- Assuming `locale` changes week start, fiscal policy, or timezone; configure those under `filter.date`.

## Related guides

- [Fiscal Date Filters](/guides/data-filter/filter-types/fiscal-date-filters/)
- [Date and Datetime Filters](/guides/data-filter/filter-types/date-filter/)
- [Calendar Range](/guides/data-filter/filter-types/calendar-range/)
- [Structured Filter Types](/guides/data-filter/filter-types/overview/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)

---

# Statistical Presets Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/statistical-presets/
Source: src/content/docs/guides/data-filter/filter-types/statistical-presets.mdx
Description: Filter numeric columns with stable top-percentile, average, quartile, outlier, and negative-value presets.

Statistical presets turn common analytical questions into one-click filters. Use them for metrics where users frequently ask for the top 10%, values above average, the bottom quartile, two-sigma outliers, or negative values.

## Quick start

```ts
import { defineCustomElements } from '@revolist/revogrid/loader';
import {
  AdvanceFilterPlugin,
  FILTER_STATISTICAL_PRESETS,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

defineCustomElements();

const grid = document.createElement('revo-grid');
grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'team', name: 'Team' },
  {
    prop: 'margin',
    name: 'Margin',
    filter: ['number', FILTER_STATISTICAL_PRESETS],
  },
];
grid.filter = true;
document.querySelector('#app')!.append(grid);
grid.source = [
  { team: 'North', margin: 18 },
  { team: 'South', margin: -4 },
  { team: 'West', margin: 31 },
  { team: 'East', margin: 9 },
];
```

## Operator and state

- Type ID: `FILTER_STATISTICAL_PRESETS` (`'statisticalPresets'`)
- Operator ID: `STATISTICAL_PRESET_OPERATOR` (`'statisticalPreset'`)
- Presets: `top10Percent`, `aboveAverage`, `bottomQuartile`, `outliersTwoSigma`, and `negativeOnly`
- Value: `{ preset, lower, upper, lowerInclusive, upperInclusive, outside }`

The popup computes statistics from the current finite parsed values. When a preset is selected, the resolved numeric boundaries are serialized into the condition. Those boundaries stay stable when the source later changes; reopen and select the preset again to recompute it.

## Restore a preset programmatically

Restore the resolved boundaries, not only the preset name:

```ts
import {
  STATISTICAL_PRESET_OPERATOR,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

grid.filter = defineAdvancedFilterConfig({
  multiFilterItems: {
    margin: [
      {
        id: 1,
        type: STATISTICAL_PRESET_OPERATOR,
        value: {
          preset: 'negativeOnly',
          lower: null,
          upper: 0,
          lowerInclusive: false,
          upperInclusive: false,
          outside: false,
        },
        relation: 'and',
      },
    ],
  },
});
```

`null` represents an unbounded side. `outside: true` matches values outside the serialized lower and upper boundaries and is used by the two-sigma outlier preset.

## Configuration

```ts
import {
  createStatisticalPresetsStructuredFilterType,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

const presets = createStatisticalPresetsStructuredFilterType({
  formatValue: (value) => `${value.toFixed(1)}%`,
  formatMatchCount: (count) => `${count.toLocaleString()} matches`,
});

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [presets],
});
```

Both callbacks change presentation only. Use `cellParser` when the stored value must be normalized before statistics and comparisons are calculated.

## Common mistakes

- Saving only `{ preset: 'top10Percent' }`; all boundary and inclusion fields are required for a valid restored condition.
- Expecting an applied preset to move automatically as rows change; its serialized boundaries are deliberately stable.
- Including `NaN`, `Infinity`, or nonnumeric strings in expected statistics; only finite parsed values participate.
- Treating `negativeOnly` as “zero or below”; its upper boundary is exclusive, so zero does not match.
- Recomputing boundaries independently with different quantile or variance rules when the application can save the condition emitted by the grid.

## Related guides

- [Structured Filter Types](/guides/data-filter/filter-types/overview/)
- [Histogram Brush](/guides/data-filter/filter-types/histogram-brush/)
- [Rating or Progress Threshold](/guides/data-filter/filter-types/rating-progress-threshold/)
- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)

---

# Text Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/text-filter/
Source: src/content/docs/guides/data-filter/filter-types/text-filter.mdx
Description: Configure Core text filtering with contains, begins-with, equality, blank checks, initial state, and parsed values.
Surface: grid

Use the Core text filter for names, labels, codes, descriptions, and other values that users should match by typing. It needs no Pro plugin.

## Quick start

```ts
const grid = document.querySelector('revo-grid')!;

grid.columns = [
  { prop: 'name', name: 'Name', filter: 'string' },
  { prop: 'status', name: 'Status', filter: 'string' },
];
grid.filter = true;
grid.source = [
  { name: 'Anna Silva', status: 'Open' },
  { name: 'John Smith', status: 'Pending' },
];
```

Open a column's filter button, choose **Contains**, enter text, and apply. Text equality, begins-with, and contains matching are case-insensitive.

## Operators

| Saved ID      | Popup label      | Needs a value |
| ------------- | ---------------- | ------------- |
| `contains`    | Contains         | Yes           |
| `notContains` | Does not contain | Yes           |
| `begins`      | Begins with      | Yes           |
| `eq`          | Equal            | Yes           |
| `notEq`       | Not equal        | Yes           |
| `empty`       | Is blank         | No            |
| `notEmpty`    | Is not blank     | No            |

An empty text input is a no-op. Blank operators use the grid's source-aware [blank policy](/guides/data-filter/blank-values/), not a display-string conversion.

## Start with a condition

```ts
grid.filter = {
  multiFilterItems: {
    status: [{ id: 1, type: 'eq', value: 'Open', relation: 'and' }],
  },
};
```

Combine alternatives within one column with `or`:

```ts
grid.filter = {
  multiFilterItems: {
    status: [
      { id: 1, type: 'eq', value: 'Open', relation: 'or' },
      { id: 2, type: 'eq', value: 'Pending', relation: 'and' },
    ],
  },
};
```

Different columns always combine with AND in `multiFilterItems`. Use [Filter AST](/guides/data-filter/filter-ast/) for cross-column OR.

## Filter a normalized value

Conditions receive `cellParser` output when the stored model needs normalization:

```ts
grid.columns = [
  {
    prop: 'customerCode',
    name: 'Customer code',
    filter: 'string',
    cellParser: (model, column) => String(model[column.prop] ?? '').trim(),
  },
];
```

## Common mistakes

- Use `eq`, not the numeric `eqN`, for a text column.
- Do not expect text conditions on different columns to combine with OR.
- Use [Selection Filter](/guides/data-filter/filter-types/filter-selection/) when users should choose from repeated known values instead of typing.
- Use [Token List](/guides/data-filter/filter-types/token-list/) when users paste several exact values at once.

## Related guides

- [Filtering Quick Start](/guides/data-filter/filter-basics/)
- [Number Filter](/guides/data-filter/filter-types/number-filter/)
- [Blank Values](/guides/data-filter/blank-values/)
- [Filter Header](/guides/data-filter/filter-header/)

---

# Time Matrix Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/time-matrix/
Source: src/content/docs/guides/data-filter/filter-types/time-matrix.mdx
Description: Filter timestamp columns by selected weekday and whole-hour combinations in a resolved timezone.
Surface: grid

Use the time matrix for activity schedules, support coverage, usage windows, or any timestamp question expressed as weekday plus hour. Users can select individual cells or start from Business hours, Weekends, and Nights presets.

## Quick start

```ts
import {
  AdvanceFilterPlugin,
  FILTER_TIME_MATRIX,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'occurredAt',
    name: 'Activity time',
    filter: ['datetime', FILTER_TIME_MATRIX],
  },
];
grid.source = [
  { occurredAt: '2026-08-24T09:30:00Z' },
  { occurredAt: '2026-08-25T22:15:00Z' },
];
grid.filter = true;
```

Row values must resolve to instants (`Date`, an ISO timestamp, or a numeric timestamp). The filter converts each instant to weekday and hour in the condition's timezone.

## Operator and saved state

- Structured type: `FILTER_TIME_MATRIX` (`'timeMatrix'`)
- Operator: `TIME_MATRIX_OPERATOR` (`'timeMatrix'`)
- Value: `{ version: 1, timeZone, ranges }`

Each range uses Sunday-based `weekday` (`0` is Sunday), an inclusive `startHour`, and an exclusive `endHour`.

```ts
grid.filter = {
  multiFilterItems: {
    occurredAt: [
      {
        id: 1,
        type: 'timeMatrix',
        value: {
          version: 1,
          timeZone: 'Europe/Lisbon',
          ranges: [
            { weekday: 1, startHour: 9, endHour: 17 },
            { weekday: 2, startHour: 9, endHour: 17 },
          ],
        },
        relation: 'and',
      },
    ],
  },
};
```

Use that JSON-safe value for programmatic restore. Adjacent selected hours are compacted into ranges. Selecting no cells or every hour of every day removes the no-op condition.

## Configure schedule presentation

```ts
import {
  createTimeMatrixStructuredFilterType,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

const activityTime = createTimeMatrixStructuredFilterType({
  timeZone: 'Europe/Lisbon',
  locale: 'en-GB',
  weekStartsOn: 1,
  useAmPm: false,
  // Context shading in the matrix.
  workingHours: { startHour: 8, endHour: 18 },
  weekendDays: [5, 6],
  // Shortcut buttons are configured independently.
  presets: {
    businessHours: {
      days: [1, 2, 3, 4],
      startHour: 9,
      endHour: 17,
      label: 'Core hours',
      description: 'Monday–Thursday, 09:00–17:00',
    },
    weekends: {}, // Inherits weekendDays ([5, 6]).
    nights: {
      days: [0, 1, 2, 3, 4, 5, 6],
      startHour: 20,
      endHour: 6, // An end before the start creates an overnight window.
    },
  },
});

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [activityTime],
});
```

`workingHours` and `weekendDays` shade schedule context; selected cells alone determine filtering. Defaults are 06:00–22:00 and Sunday/Saturday. If `timeZone` or `weekStartsOn` is omitted, it inherits the column's resolved date-filter settings.

The built-in shortcut defaults remain Business hours (Monday–Friday, 08:00–20:00), Weekends (the configured `weekendDays`, all day), and Nights (every day, 22:00–06:00).

| Option | Purpose |
| --- | --- |
| `workingHours` | Start/end boundaries for outside-working-hours shading. |
| `weekendDays` | Sunday-based days used for weekend shading and, by default, the Weekends shortcut. |
| `workingHours: false` | Disable outside-working-hours shading and remove that legend item. |
| `weekendDays: []` | Disable weekend shading and remove that legend item. |
| `showLegend: false` | Hide the complete schedule-context legend. |
| `presets.businessHours` | Configure `days`, `startHour`, `endHour`, `label`, and `description`, or use `false` to hide it. |
| `presets.weekends` | Configure `days`, `label`, and `description`, or use `false` to hide it. An empty object inherits `weekendDays`. |
| `presets.nights` | Configure `days`, an overnight-capable hour window, `label`, and `description`, or use `false` to hide it. |
| `presets: false` | Hide the complete shortcut row while retaining direct matrix selection. |

All days use Sunday-based numbering (`0`–`6`), and all hour boundaries are whole hours (`0`–`24`). A preset window whose `endHour` is earlier than `startHour` wraps across midnight. Invalid days or hour windows fall back to that preset's defaults.

For example, keep Business hours and hide the other shortcuts:

```ts
const activityTime = createTimeMatrixStructuredFilterType({
  presets: {
    weekends: false,
    nights: false,
  },
});
```

## Localization

`TIME_MATRIX_LOCALIZATION` exports the complete English fallback and stable keys. Override the operator through `filterNames` and authored UI/accessibility text through `captions`.

```ts
grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [activityTime],
  localization: {
    filterNames: {
      timeMatrix: 'Matches schedule',
    },
    captions: {
      timeMatrixTitle: 'Coverage schedule',
      timeMatrixDescription: 'Select included weekday and hour combinations.',
      timeMatrixClear: 'Clear schedule',
      'timeMatrixPreset.businessHours': 'Office hours',
      'timeMatrixPresetDescription.businessHours':
        'Monday–Friday office coverage',
    },
  },
});
```

Other stable captions cover the grid and legend, selected/unselected cell states, summaries, and all preset labels/descriptions. Per-instance `label` and `description` values on a preset take precedence over localization captions. Dynamic messages use named placeholders including `{day}`, `{start}`, `{end}`, `{state}`, `{hours}`, `{days}`, and `{timeZone}`. Weekday and clock text comes from `locale` and `useAmPm`, not fixed translated strings.

## Common mistakes

- Do not store local clock text such as `'09:30'`; the predicate needs an instant.
- Do not treat `endHour` as inclusive. `{ startHour: 9, endHour: 17 }` covers 09:00 through 16:59.
- Do not use locale weekday numbering in saved state; persisted weekday is always Sunday-based.
- Do not expect `workingHours` or `weekendDays` shading to add selected cells. Configure shortcut selections through `presets`.
- Use a valid IANA timezone. Invalid `timeZone` configuration throws.

## Related guides

- [Structured Filter Types](./)
- [Date and Datetime Filters](/guides/data-filter/filter-types/date-filter/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Custom and Remote Structured Filters](/guides/data-filter/structured-filter-types/)

---

# Timeline Brush Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/timeline-brush/
Source: src/content/docs/guides/data-filter/filter-types/timeline-brush.mdx
Description: Filter date and datetime columns by brushing an inclusive range over a compact temporal distribution.
Surface: grid

Use the timeline brush when users need to see where date or datetime values are concentrated before choosing a range. It bins parsed column values by day, week, or month and keeps the committed condition independent from the chart UI.

## Quick start

```ts
import {
  AdvanceFilterPlugin,
  FILTER_TIMELINE_BRUSH,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'createdAt',
    name: 'Created',
    filter: ['datetime', FILTER_TIMELINE_BRUSH],
  },
];
grid.source = [
  { createdAt: '2026-08-20T09:30:00Z' },
  { createdAt: '2026-08-24T16:15:00Z' },
];
grid.filter = true;
```

Use `'date'` instead of `'datetime'` for ISO date-only values such as `2026-08-20`. Selecting the complete displayed domain is a no-op and removes the timeline condition.

## Operator and saved state

- Structured type: `FILTER_TIMELINE_BRUSH` (`'timelineBrush'`)
- Operator: `TIMELINE_BETWEEN` (`'timelineBetween'`)
- Value: `{ from, to, inclusive: true }`

Date columns store inclusive ISO dates. Datetime columns store inclusive ISO instants.

```ts
grid.filter = {
  multiFilterItems: {
    createdAt: [
      {
        id: 1,
        type: 'timelineBetween',
        value: {
          from: '2026-08-20T00:00:00.000Z',
          to: '2026-08-24T23:59:59.999Z',
          inclusive: true,
        },
        relation: 'and',
      },
    ],
  },
};
```

This is also the programmatic restore shape. Keep the operator ID in `type`; the structured type ID belongs in the column definition.

## Configure the timeline

Replace the built-in registration with a configured instance. The stable ID stays the same, so every column using `FILTER_TIMELINE_BRUSH` receives these options.

```ts
import {
  createTimelineBrushStructuredFilterType,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

const timeline = createTimelineBrushStructuredFilterType({
  granularity: 'week', // 'day' | 'week' | 'month'
  binCap: 48,
  timeZone: 'Europe/Lisbon',
  locale: 'en-GB',
  format: { day: '2-digit', month: 'short', year: 'numeric' },
  chart: {
    type: 'area', // 'bar' | 'line' | 'area'; default is 'bar'
    height: 72,
    showPoints: true,
    formatTooltip: (bin, { fromLabel, toLabel, selected }) => ({
      title: fromLabel === toLabel ? fromLabel : `${fromLabel} – ${toLabel}`,
      details: [`${bin.count} events`, selected ? 'Selected' : 'Outside selection'],
    }),
  },
});

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [timeline],
  date: { weekStartsOn: 1 },
});
```

`timeZone` and `weekStartsOn` inherit the column's resolved `filter.date` settings when the factory does not override them. Dense spans are deterministically coarsened to stay within `binCap`.

The chart is a reusable presentation control; the dual-range slider remains independent. Its default
tooltips are keyboard reachable and localize through `timelineBrushChart`, `timelineBrushItem`,
`timelineBrushItems`, `timelineBrushSelected`, and `timelineBrushOutsideSelection` captions. Use
`formatTooltip` for domain-specific rows or terminology.

For a partially loaded remote source, provide complete temporal aggregates or exported `TimelineBrushPreparedData`; otherwise the distribution can only describe rows loaded in the browser.

## Common mistakes

- Do not restore `type: 'timelineBrush'`; conditions use `type: 'timelineBetween'`.
- Do not mix date-only and datetime values in one column. Declare the base family explicitly.
- Do not pass display-formatted dates unless a `cellParser` converts them into valid date or instant values.
- Do not expect a full-domain selection to remain in state; it intentionally clears the no-op condition.
- For remote pagination, do not present page-local bins as the complete dataset distribution.

## Related guides

- [Structured Filter Types](./)
- [Date and Datetime Filters](/guides/data-filter/filter-types/date-filter/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Custom and Remote Structured Filters](/guides/data-filter/structured-filter-types/)

---

# Token List Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/token-list/
Source: src/content/docs/guides/data-filter/filter-types/token-list.mdx
Description: Filter scalar values against an exact list pasted or entered as tokens.
Surface: grid

Use the Token List filter when users already have an exact list of identifiers, SKUs, email addresses, or other scalar values. They can paste comma-, newline-, or tab-separated text instead of selecting values from the column.

## Quick start

`AdvanceFilterPlugin` registers the built-in body. Add `FILTER_TOKEN_LIST` to the column's filter families:

```ts
import { AdvanceFilterPlugin, FILTER_TOKEN_LIST } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'sku', name: 'SKU', filter: ['string', FILTER_TOKEN_LIST] },
];
grid.filter = true;
```

Keeping `'string'` in the array also exposes the ordinary text operators. Use only `FILTER_TOKEN_LIST` when the popup should contain only the token workflow.

## Operators and state

| UI mode   | Saved operator    | Value shape | Matches                                                   |
| --------- | ----------------- | ----------- | --------------------------------------------------------- |
| Is any of | `tokenListAnyOf`  | `string[]`  | A non-null scalar whose string value is one of the tokens |
| None of   | `tokenListNoneOf` | `string[]`  | Any value that does not match the **Is any of** rule      |

Input is trimmed, empty tokens are removed, duplicates keep their first position, and comparisons are exact and case-sensitive. Objects and functions never match **Is any of**. The body does not scan source rows, so it is also suitable when the complete value list comes from outside the grid.

## Restore a token list

Use the operator ID—not `FILTER_TOKEN_LIST`—inside `multiFilterItems`:

```ts
grid.filter = {
  multiFilterItems: {
    sku: [
      {
        id: 1,
        type: 'tokenListAnyOf',
        value: ['EU-100', 'EU-200', 'US-500'],
        relation: 'and',
      },
    ],
  },
};
```

Assign an empty `multiFilterItems` object to clear restored filters:

```ts
grid.filter = { multiFilterItems: {} };
```

## Key behavior

- Pasting `EU-100, EU-200\nUS-500` creates three tokens.
- Numeric and boolean cell values are compared through their string representation.
- The condition value is a JSON-safe array and can be transported with the canonical filter AST.
- Removing every token removes the owned condition instead of saving an empty no-op filter.

## Common mistakes

- Do not save `type: 'tokenList'`; that is the body ID. Save `tokenListAnyOf` or `tokenListNoneOf`.
- Do not expect fuzzy or case-insensitive matching. Use the [Fuzzy Search filter](../fuzzy-search/) for approximate text.
- Do not pass one comma-containing value when commas are meaningful inside the value; pasted commas are delimiters.

## Related guides

- [Structured Filter Types](./../)
- [Faceted List Filter](../faceted-list/)
- [Regular Expression Filter](../regular-expression/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)

---

# Tri-state Boolean Filter

URL: https://pro.rv-grid.com/guides/data-filter/filter-types/tri-state-boolean/
Source: src/content/docs/guides/data-filter/filter-types/tri-state-boolean.mdx
Description: Filter strict boolean values with All, Yes, No, and an optional blanks-as-No policy.
Surface: grid

Use the tri-state boolean filter when a boolean column needs one compact control for **All**, **Yes**, and **No**. It is especially useful when missing values may optionally belong to the No result.

## Quick start

```ts
import {
  AdvanceFilterPlugin,
  FILTER_TRI_STATE_BOOLEAN,
} from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  {
    prop: 'approved',
    name: 'Approved',
    filter: ['boolean', FILTER_TRI_STATE_BOOLEAN],
  },
];
grid.source = [{ approved: true }, { approved: false }, { approved: null }];
grid.filter = true;
```

The editor reports Yes, No, and blank counts from provider-backed `valueCounts`. Choosing All removes its condition.

## Operator and saved state

- Structured type: `FILTER_TRI_STATE_BOOLEAN` (`'triStateBoolean'`)
- Operator: `TRI_STATE_BOOLEAN_OPERATOR` (`'triStateBoolean'`)
- Value: `{ state: 'yes' | 'no', coerceBlank: boolean }`

Yes matches strict `true`. No matches strict `false`; with `coerceBlank: true`, it also matches values classified as blank by the active Core blank policy.

```ts
grid.filter = {
  multiFilterItems: {
    approved: [
      {
        id: 1,
        type: 'triStateBoolean',
        value: { state: 'no', coerceBlank: true },
        relation: 'and',
      },
    ],
  },
};
```

Use the same condition for programmatic restore. There is no saved `{ state: 'all' }` condition because All means no filtering.

## Configure blank behavior

The blank toggle delegates to the shared Core blank-semantics policy. Configure that policy at grid level and override individual columns only when necessary.

```ts
grid.filter = {
  blankSemantics: {
    null: true,
    undefined: true,
    emptyString: true,
    whitespaceOnlyString: false,
    missingProperty: true,
  },
};

grid.columns = [
  {
    prop: 'approved',
    filter: ['boolean', FILTER_TRI_STATE_BOOLEAN],
    blankSemantics: {
      emptyString: false,
    },
  },
];
```

The structured body is already built in and has no presentation factory options. Customize its operator label with `localization.filterNames.triStateBoolean` and body captions through the standard advanced-filter localization config.

## Common mistakes

- Do not use strings such as `'true'` and `'false'`; Yes and No match boolean primitives strictly.
- Do not persist All as an active condition; remove the column's condition instead.
- Do not assume `coerceBlank` means every falsy value. It uses configured blank semantics, not JavaScript truthiness.
- Do not duplicate blank rules in application code; set grid- or column-level `blankSemantics`.
- For remote data, provide complete `valueCounts` if the browser holds only a page of rows.

## Related guides

- [Structured Filter Types](./)
- [Boolean Filters](/guides/data-filter/filter-types/boolean-filter/)
- [Blank Value Semantics](/guides/data-filter/blank-values/)
- [Custom and Remote Structured Filters](/guides/data-filter/structured-filter-types/)

---

# Custom Structured Filter Types

URL: https://pro.rv-grid.com/guides/data-filter/structured-filter-types/
Source: src/content/docs/guides/data-filter/structured-filter-types.mdx
Description: Configure the structured filter registry, lazy and remote aggregates, built-in replacements, and custom popup bodies.
Surface: grid

Structured filter types add purpose-built controls to the Pro column-filter popup without replacing RevoGrid's filter model. A type is one **popup body plus the operator IDs it owns**. The grid still owns the popup shell, header, active-state icon, close behavior, **Groups** launcher, ordinary condition list, and optional **Expression** editor.

Start with the [Structured Filter Types overview](/guides/data-filter/filter-types/overview/) when choosing or configuring a built-in. This guide covers the shared registry contract, aggregate access, remote data, built-in replacement, and application-defined types.

The [`Advanced Filtering: Order Explorer`](https://demo.rv-grid.com/filter-showcase/ts) exposes every built-in on a dedicated order column and lets you switch among the TypeScript, React, Vue, and Angular implementations.

## Register and select a type

`AdvanceFilterPlugin` registers all 14 built-ins. Registration alone does not change a column: opt in through the column's existing `filter` field. A column can combine its base family with one or more structured types.

```ts
import {
  AdvanceFilterPlugin,
  FILTER_FACETED_LIST,
  FILTER_HISTOGRAM_BRUSH,
  FILTER_TOKEN_LIST,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = [
  { prop: 'project', filter: ['string', FILTER_TOKEN_LIST] },
  { prop: 'region', filter: ['string', FILTER_FACETED_LIST] },
  { prop: 'revenue', filter: ['number', FILTER_HISTOGRAM_BRUSH] },
];
grid.filter = defineAdvancedFilterConfig({
  allowDuplicateOperators: false,
});
```

When a structured type is selected, its body appears above the ordinary condition list. Its owned operators are omitted from that list so the popup does not expose duplicate controls, while operators from the column's base family remain available. Multiple structured IDs can be placed in the same `filter` array when their bodies should appear together.

## State, AST, and expression ownership

Every editor reads and commits ordinary `MultiFilterItem` conditions. A condition has the same stable fields used elsewhere by filtering: `id`, `type`, `value`, and `relation`. The registry limits a body to its declared `operatorIds`, preserves unrelated conditions, reuses condition IDs where possible, and removes the owned condition when the control returns to its no-op state.

`AdvanceFilterPlugin` converts those conditions into canonical `FilterAst` condition nodes. Structured values are JSON-safe, so operator IDs and values survive AST and saved-view serialization without an opaque UI-only state layer. The current-column Expression editor and the grouped AST editor remain grid-owned surfaces; a custom structured body does not need to recreate either one.

  Operator IDs must be unique across registered structured types. Registering a
  second type that claims an operator owned by a different type throws.
  Registering the same stable type ID replaces that type, which is how a
  configured built-in overrides its default presentation.

## Lazy aggregate access

A body declares only the provider-backed projections it may use through `aggregateNeeds`:

| Need           | Result                                             |
| -------------- | -------------------------------------------------- |
| `values`       | Parsed column values in row order                  |
| `uniqueValues` | First-seen unique parsed values                    |
| `valueCounts`  | `{ value, count }` entries                         |
| `numericRange` | Finite numeric `values`, `count`, `min`, and `max` |

Registering a type and creating its aggregate accessor do not scan rows. The first `context.aggregates.get(need, scope)` call performs the scan and caches it for that popup-body render; built-in bodies that need a projection call it as they render. The default scope is `'all'`; pass `'visible'` to use the provider's currently visible item indexes. Both scopes exclude synthetic rows and resolve values through the grid's parsed-value path.

```ts
const allCounts = context.aggregates?.get('valueCounts');
const visibleCounts = context.aggregates?.get('valueCounts', 'visible');
```

Asking for an undeclared need throws, which keeps data dependencies explicit.

### Complete aggregates for remote rows

Pagination and infinite-scroll grids only keep a window of rows in the browser. Supply server-produced aggregates through `structuredFilterAggregates` so counts, previews, histograms, and presets describe the complete remote result set instead of the loaded page. The callback is lazy and cached once per need, scope, type, and open popup. Return `undefined` when a request should use the local-row fallback.

```ts
import type { StructuredFilterAggregateProvider } from '@revolist/revogrid-pro';

const remoteAggregates: StructuredFilterAggregateProvider = {
  complete: true,
  get({ typeId, column, need, scope }) {
    if (
      typeId === FILTER_FACETED_LIST &&
      column.prop === 'region' &&
      need === 'valueCounts'
    ) {
      return scope === 'visible'
        ? response.visibleRegionCounts
        : response.allRegionCounts;
    }
    if (
      typeId === FILTER_HISTOGRAM_BRUSH &&
      column.prop === 'revenue' &&
      need === 'numericRange'
    ) {
      return response.revenueRange;
    }
    return undefined;
  },
};

grid.filter = defineAdvancedFilterConfig({
  structuredFilterAggregates: remoteAggregates,
});
```

Set `complete: true` for a partially loaded remote row source. A missing aggregate then fails explicitly instead of silently deriving an incomplete result from the loaded page. For very large numeric, timeline, or array columns, implement `getPrepared()` and return the exported compact `HistogramPreparedData`, `StatisticalPresetsPreparedData`, `TimelineBrushPreparedData`, or `{ kind: 'arrayTags', values }` shape. Those bodies use server bins, resolved preset boundaries/counts, timeline buckets, or unique tags directly and do not request row-level arrays.

The filter condition itself remains the remote execution contract: stable operator IDs plus JSON-safe values are forwarded in `multiConditionFilters`. Date-aware filters also include resolved half-open UTC ranges, the captured reference instant, timezone, week start, and fiscal-year anchor in `temporalContext`.

Canonical `filterAst` and its `executionContext` are forwarded by pagination, infinite scroll, and server-side grouping. The execution context includes each column's resolved JSON-safe blank policy. If a column uses a JavaScript `isBlank` callback or an array/tags accessor function, configure the equivalent rule in the backend; functions are intentionally never serialized.

## Built-in guides

Each built-in now has a focused setup, saved-state, configuration, and troubleshooting guide:

| Built-in                     | Focused guide                                                                               | Aggregate need |
| ---------------------------- | ------------------------------------------------------------------------------------------- | -------------- |
| Token list                   | [Token List Filter](/guides/data-filter/filter-types/token-list/)                           | None           |
| Fuzzy search                 | [Fuzzy Search Filter](/guides/data-filter/filter-types/fuzzy-search/)                       | `uniqueValues` |
| Regular expression           | [Regular Expression Filter](/guides/data-filter/filter-types/regular-expression/)           | `uniqueValues` |
| Faceted list                 | [Faceted List Filter](/guides/data-filter/filter-types/faceted-list/)                       | `valueCounts`  |
| Chip and badge toggles       | [Chip and Badge Toggle Filter](/guides/data-filter/filter-types/chip-badge-toggles/)        | `uniqueValues` |
| Histogram brush              | [Histogram Brush Filter](/guides/data-filter/filter-types/histogram-brush/)                 | `numericRange` |
| Rating or progress threshold | [Rating or Progress Threshold](/guides/data-filter/filter-types/rating-progress-threshold/) | None           |
| Statistical presets          | [Statistical Presets Filter](/guides/data-filter/filter-types/statistical-presets/)         | `numericRange` |
| Calendar range               | [Calendar Range Filter](/guides/data-filter/filter-types/calendar-range/)                   | None           |
| Relative window              | [Relative Window Filter](/guides/data-filter/filter-types/relative-window/)                 | None           |
| Timeline brush               | [Timeline Brush Filter](/guides/data-filter/filter-types/timeline-brush/)                   | `values`       |
| Time matrix                  | [Time Matrix Filter](/guides/data-filter/filter-types/time-matrix/)                         | None           |
| Tri-state boolean            | [Tri-state Boolean Filter](/guides/data-filter/filter-types/tri-state-boolean/)             | `valueCounts`  |
| Array and tags               | [Array and Tags Filter](/guides/data-filter/filter-types/array-tags/)                       | `values`       |

## Configure built-ins by replacing registrations

Factory options belong to a structured type registration, not to the column. Replace the matching built-in in `structuredFilterTypes`, then opt columns into the same stable ID.

```ts
import {
  BUILT_IN_STRUCTURED_FILTER_TYPES,
  FILTER_HISTOGRAM_BRUSH,
  createHistogramBrushStructuredFilterType,
  defineAdvancedFilterConfig,
} from '@revolist/revogrid-pro';

const histogram = createHistogramBrushStructuredFilterType({
  bins: 16,
  formatValue: (value) => `${value.toFixed(1)} ms`,
});

grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: BUILT_IN_STRUCTURED_FILTER_TYPES.map((type) =>
    type.id === FILTER_HISTOGRAM_BRUSH ? histogram : type,
  ),
});
```

You can also pass only the replacement in `structuredFilterTypes`; `AdvanceFilterPlugin` registers the built-ins first and then replaces the matching stable ID.

## Create a custom structured type

A custom type needs two coordinated registrations:

1. `StructuredFilterType` defines the popup body and the operator IDs it may commit.
2. `customFilters` defines the predicate for each operator and maps it back to the same `columnFilterType` ID.

```ts
import {
  AdvanceFilterPlugin,
  defineAdvancedFilterConfig,
  structuredFilterButton,
  structuredFilterSection,
  type StructuredFilterType,
} from '@revolist/revogrid-pro';

const PRIORITY_PICKER = 'priorityPicker';
const PRIORITY_IS = 'priorityIs';

const priorityPicker: StructuredFilterType = {
  id: PRIORITY_PICKER,
  operatorIds: [PRIORITY_IS],
  headerControl: {
    kind: 'popup',
    template: (h, { presentation }) => h(
      'span',
      { class: 'priority-header-badge' },
      presentation.summary,
    ),
  },
  render(context) {
    const selected = context.conditions[0]?.value;
    return structuredFilterSection(
      'Priority',
      ['low', 'medium', 'high'].map((value) =>
        structuredFilterButton({
          label: value,
          pressed: selected === value,
          onClick: () =>
            void context.commit(
              selected === value ? [] : [{ type: PRIORITY_IS, value }],
            ),
        }),
      ),
      'Choose one priority.',
    );
  },
};

grid.plugins = [AdvanceFilterPlugin];
grid.filter = defineAdvancedFilterConfig({
  structuredFilterTypes: [priorityPicker],
  customFilters: {
    [PRIORITY_IS]: {
      columnFilterType: PRIORITY_PICKER,
      name: 'Is priority',
      func: (cellValue, expected) => cellValue === expected,
    },
  },
  localization: {
    filterNames: { [PRIORITY_IS]: 'Is priority' },
  },
});
grid.columns = [{ prop: 'priority', filter: ['string', PRIORITY_PICKER] }];
```

Declare `aggregateNeeds` only if the body derives choices or summaries from grid data, and call `context.aggregates.get()` only for those declared needs. Use `context.labels.operator()` and `context.labels.caption()` for localized text, and use `context.commit()` (or its equivalent alias `replaceConditions()`) rather than mutating filter state directly. `headerControl` is optional: a popup control supplies non-interactive trigger content, while a resolver may return an inline interactive control using the same controlled context.

The built-in types also implement the optional `mount(host, context)` adapter. It mounts the same controlled editor inside a grouped-filter rule, with the same aggregates, remote `preparedData`, date settings, labels, and condition contract as the regular popup. Custom structured types should implement `mount` when their JSON value needs an interactive grouped editor; without it, grouped mode preserves the value and shows an explicit unavailable-editor state instead of coercing an object to text.

Selection rules are handled similarly by the grouped builder itself: `in` / `notIn` use the existing provider-backed option source as an autocomplete with removable tags. Values are never parsed by commas, so a value such as `"North, America"` remains one value.

The plugin also exposes `registerStructuredFilterType()`, `unregisterStructuredFilterType()`, and `getStructuredFilterType()` on an `AdvanceFilterPlugin` instance for runtime registration. Configuration is usually simpler because `initConfig()` can rebuild the complete registry consistently.

## Related filtering guides

- [Structured Filter Types](/guides/data-filter/filter-types/overview/)
- [Custom Filter Operators](/guides/data-filter/custom-filter-operators/)
- [Advanced Filtering Overview](/guides/data-filter/filter-showcase/)
- [Canonical Filter AST](/guides/data-filter/filter-ast/)
- [Filter Expressions](/guides/data-filter/filter-expression/)
- [Blank Values](/guides/data-filter/blank-values/)

---

# What Is a Filter AST?

URL: https://pro.rv-grid.com/guides/data-filter/what-is-filter-ast/
Source: src/content/docs/guides/data-filter/what-is-filter-ast.mdx
Description: Understand Filter AST in plain language, why teams use it, and when it is the right filtering model.
Surface: grid

A Filter AST is a portable description of a filter. It records **what the filter means** as data, without tying that meaning to one filter popup, framework, database, or API.

You do not need compiler knowledge to use it. If you can read a sentence such as “show open, high-priority tickets or any ticket from a VIP customer,” you already understand the idea.

## AST in plain language

AST stands for **Abstract Syntax Tree**:

- **Abstract** means it keeps the meaning and leaves out presentation details such as buttons, labels, and popup layout.
- **Syntax** means it follows a small set of structural rules.
- **Tree** means a rule can contain smaller rules, like branches containing more branches and leaves.

In a RevoGrid Filter AST, the leaves are field conditions and the branches join them with `and`, `or`, or `not`.

Consider this business rule:

> Show a ticket when it is both open and high priority, or when the customer is a VIP.

Its tree reads like this:

```text
OR
├─ AND
│  ├─ status equals "Open"
│  └─ priority is at least 3
└─ customerTier equals "VIP"
```

The same rule as a RevoGrid `FilterAst` is ordinary JSON-shaped data:

```ts
import type { FilterAst } from '@revolist/revogrid-pro';

const ticketQueue: FilterAst = {
  type: 'group',
  operator: 'or',
  children: [
    {
      type: 'group',
      operator: 'and',
      children: [
        {
          type: 'condition',
          field: 'status',
          operator: 'equal',
          valueType: 'string',
          value: 'Open',
        },
        {
          type: 'condition',
          field: 'priority',
          operator: 'greaterThanOrEqual',
          valueType: 'number',
          value: 3,
        },
      ],
    },
    {
      type: 'condition',
      field: 'customerTier',
      operator: 'equal',
      valueType: 'string',
      value: 'VIP',
    },
  ],
};
```

The AST describes the question. It does not contain the rows, the matching results, or database-specific instructions.

## What “canonical” means

Applications often create filters in several places: column menus, a visual rule builder, quick search, saved views, and backend APIs. Without a shared format, each feature can describe the same rule differently.

RevoGrid's canonical `FilterAst` is the common contract between those paths. It is:

- **Meaningful:** nested Boolean logic is explicit rather than implied by UI state.
- **JSON-safe:** it can be serialized, stored, logged, and sent in a request.
- **Validated:** malformed trees are rejected before they replace the active filter.
- **Portable:** the same tree can drive local rows or be interpreted by your backend.
- **UI-independent:** a filter can survive a redesign or move between different applications.

“Canonical” does not mean RevoGrid automatically converts the tree to SQL, REST parameters, or GraphQL. Your backend owns that translation and must allow-list fields and operators before building a query.

## The business case

Filter AST becomes valuable when a filter is more than a temporary choice in one column menu.

| Need                                        | Business outcome                                                                              |
| ------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Saved views and reusable segments           | Users can return to the same definition instead of rebuilding it.                             |
| Shared rules across screens                 | A queue, dashboard, and export can use one filter contract.                                   |
| Remote or virtual data                      | The backend can evaluate the complete dataset instead of only the loaded page.                |
| Cross-column `OR`, nested groups, and `NOT` | Business rules are represented without flattening or changing their meaning.                  |
| Visual and programmatic editing             | A person can use the grouped editor while an application can generate the same structure.     |
| Validation and diagnostics                  | Invalid saved or generated rules fail as one atomic update, leaving the previous view active. |
| Auditing and troubleshooting                | A JSON filter is easier to inspect, compare, version, and log than transient UI state.        |

Typical examples include support queues, approval routing, fraud-review segments, inventory alerts, compliance views, and report definitions.

## When to use it

Use `FilterAst` when at least one of these is true:

- The rule needs `OR` across different fields, nested groups, or `NOT`.
- Users save, share, or reopen complex views.
- Filtering is executed by a remote data service.
- A visual rule builder and application code must exchange the same filter.
- You need a stable, JSON-safe filtering contract.

Use ordinary `multiFilterItems` instead when users only filter individual columns and all columns combine with `AND`. It is simpler and works with existing Core column controls. `FilterAst` is a Pro capability and requires `AdvanceFilterPlugin` for canonical execution.

## The three building blocks

Every tree is made from only three node types:

| Node        | What it says                                     | Everyday example            |
| ----------- | ------------------------------------------------ | --------------------------- |
| `condition` | Test one field with one operator.                | Status equals Open.         |
| `group`     | Join one or more child rules with `and` or `or`. | Open **and** high priority. |
| `not`       | Reverse the result of one child rule or group.   | **Not** archived.           |

A condition names the row field, operator, and operand type:

```ts
const condition: FilterAst = {
  type: 'condition',
  field: 'amount',
  operator: 'greaterThanOrEqual',
  valueType: 'number',
  value: 1000,
};
```

`valueType` describes the operand; it does not convert the values in your rows. For example, `valueType: 'number'` expects a real number rather than the string `'1000'`.

## Use a Filter AST in RevoGrid

Register `AdvanceFilterPlugin`, get its runtime instance, and apply the complete tree:

```ts
import { AdvanceFilterPlugin } from '@revolist/revogrid-pro';
import '@revolist/revogrid-pro/dist/revogrid-pro.css';

grid.plugins = [AdvanceFilterPlugin];
grid.columns = columns;
grid.source = rows;

const filterPlugin = (await grid.getPlugins()).find(
  (plugin) => plugin instanceof AdvanceFilterPlugin,
) as AdvanceFilterPlugin;

await filterPlugin.setFilterAst(ticketQueue);
```

Read the effective filter when you need to save or send it:

```ts
const currentFilter = filterPlugin.getFilterAst();
if (currentFilter) {
  localStorage.setItem('ticket-queue', JSON.stringify(currentFilter));
}
```

Restore the saved tree by parsing it and applying it again:

```ts
const savedFilter = localStorage.getItem('ticket-queue');
if (savedFilter) {
  await filterPlugin.setFilterAst(JSON.parse(savedFilter));
}
```

Clear it with `undefined`:

```ts
await filterPlugin.setFilterAst(undefined);
```

`setFilterAst()` replaces the tree as one atomic operation. `getFilterAst()` returns a defensive copy, so changing that returned object does not change the grid. Build the next tree and call `setFilterAst()` again.

## Let users build the tree visually

The AST is the data model, not a required user interface. A familiar filter rail, active chips, search field, ranges, and toggles can all compile into the same tree. This lets people filter in business language while the application gets a validated, portable definition.

[Open the Filter AST Side Panel article](/guides/data-filter/filter-ast-side-panel/). It mounts the same canonical grouped editor used by the filter dialog and exposes Vanilla TypeScript, Vue, React, Angular, shared grid setup, and styling sources.

Each interaction in the example rebuilds and applies the complete AST. Removing a chip removes its branch; **Clear all** applies `undefined`. The side panel owns presentation, while `AdvanceFilterPlugin` owns validation and execution.

For unrestricted rule creation, enable the grouped editor so users can create nested rules without writing JSON:

```ts
grid.filter = {
  groupedFilter: {},
};
```

The editor and the API work with the same canonical tree. A user can create a rule visually, your application can read it with `getFilterAst()`, and the saved result can be restored later with `setFilterAst()`.

## Send the same meaning to a backend

Listen for `filterastchange` to receive the effective AST and its execution context. The context fixes time-sensitive details such as the instant and timezone used for relative date rules.

For a remote data source, cancel local application in `beforefilterapply`, send the AST and execution context to your service, and replace the grid rows with the server result. The backend must evaluate the rule against the full dataset, not only the page loaded in the browser.

The [Canonical Filter AST reference](/guides/data-filter/filter-ast/) has the complete event example, remote-preview flow, operator table, value rules, and diagnostics.

## A safe implementation checklist

1. Start with `multiFilterItems` unless the product needs canonical or nested logic.
2. Treat the AST as untrusted input when it comes from storage, a URL, or another service.
3. Apply it through `setFilterAst()` so RevoGrid validates it atomically.
4. Store or transport the tree returned by `getFilterAst()`.
5. Send `executionContext` with remote requests, especially for relative dates and blank-value policy.
6. On the server, allow-list fields and operators and use parameterized database queries.
7. Test the same saved rule locally and remotely to confirm that both sides return the same rows.

## Common questions

### Is a Filter AST a string expression?

No. It is structured data. A string such as `status = "Open" AND priority >= 3` can be convenient for people, but an AST makes the grouping and types explicit for software.

### Does it replace column filters?

No. Simple column filtering remains the easiest choice for ordinary grid interactions. The AST is the shared model for cases that need richer logic, persistence, or transport.

### Can I store it in a database or URL?

Yes, if the surrounding storage or URL encoding is suitable for your size and security requirements. The AST is JSON-safe, but you should still validate restored state and avoid treating client-provided fields or operators as trusted database instructions.

### What does `projectable` mean?

Some ASTs can be shown again as independent column filters; those are projectable. A cross-column `OR` or `NOT` cannot be represented faithfully by ordinary column controls, so it is canonical-only. It is still a valid filter and can be edited in the grouped editor.

### Where is the complete technical contract?

Continue to [Canonical Filter AST](/guides/data-filter/filter-ast/) for every supported operator, exact value shapes, quick-filter composition, events, remote ownership, validation codes, and custom evaluators. See [Filter State and Presets](/guides/data-filter/filter-state/) for persistence patterns and [Filtering Quick Start](/guides/data-filter/filter-basics/) for simpler column filtering.

---

# Data Grid Formatting

URL: https://pro.rv-grid.com/guides/data-grid/context-menu/
Source: src/content/docs/guides/data-grid/context-menu.mdx
Description: Add spreadsheet-style context-menu defaults for cells, rows, groups, and columns while preserving application menu contributions.

`DataGridContextMenuPlugin` provides a complete, task-oriented menu without requiring every grid to define copy, edit, inspection, row, filter, formatting, sizing, grouping, column-management, and export actions from scratch. It auto-installs `ContextMenuPlugin`, `ColumnDialogPlugin`, Column Hide support, the cell inspector, and the spreadsheet formatting runtime. Add `AutoFillPlugin` and `EventManagerPlugin` explicitly when dragging a range handle should also stretch advanced formats such as Rating together with the values.

[Open the four-framework standalone example](https://example.rv-grid.com/data-grid-context-menu/)
or browse its source in
[`revogrid-demos/pro-data-grid-context-menu`](https://github.com/revolist/revogrid-demos/tree/main/pro-data-grid-context-menu).

## Enable the preset

```ts
import { DataGridContextMenuPlugin } from '@revolist/revogrid-pro';

grid.plugins = [DataGridContextMenuPlugin];
```

Installing the plugin enables its defaults. Set the property to `false` to keep the plugin registered while suppressing the preset:

```ts
grid.dataGridContextMenu = false;
```

The preset is a prepended context-menu contribution. Existing `rowContextMenu`, `columnContextMenu`, and independent plugin contributions remain after it by default.

## Customize by stable item ID

Hide or disable one generated command without rebuilding its parent submenu:

```ts
grid.dataGridContextMenu = {
  hiddenItems: {
    'row.delete': true,
  },
  disabledItems: {
    'row.duplicate': context => context.rows.length > 20,
  },
};
```

Resolvers receive a semantic `DataGridContextMenuContext` with the active `surface`, target rows, range, leaf columns, column group, and low-level menu context.

The surfaces are `cell`, `rowHeader`, `rowGroup`, `columnHeader`, and `columnGroupHeader`. Disable a whole surface with `areas`:

```ts
grid.dataGridContextMenu = {
  areas: { rowGroup: false },
};
```

## Extend or replace generated items

Use `items` for a simple extension. Use `getItems` when a surface needs complete replacement or transformation.

```ts
grid.dataGridContextMenu = {
  items: context => [{
    id: 'app.audit',
    name: 'Open audit history',
    action: () => openAuditHistory(context.rows[0]?.model),
  }],
  getItems: (context, defaults) =>
    context.surface === 'columnGroupHeader'
      ? [{ id: 'app.groupSummary', name: 'Open group summary' }]
      : defaults,
};
```

Set `includeHostItems: false` to suppress the application-provided base menu on enabled preset surfaces. Other plugin contributions still compose independently.

## Command lifecycle and remote data

Every built-in command first emits a cancelable `datagrid-context-menu-command` event:

```ts
grid.addEventListener('datagrid-context-menu-command', event => {
  if (event.detail.id === 'row.delete' && usesRemoteRows) {
    event.preventDefault();
    void deleteRowsOnServer(event.detail.context.rows);
  }
});
```

A `commandHandlers` entry also replaces local behavior:

```ts
grid.dataGridContextMenu = {
  commandHandlers: {
    'row.delete': context => api.deleteRows(
      context.rows.map(row => row.model.id),
    ),
  },
};
```

Local row mutation is hidden for remote/server-grouped runtimes until a handler is provided. Clipboard permission and export failures emit `datagrid-context-menu-error`; Cut clears cells only after the clipboard write succeeds.

## Undo and redo with History

Add `HistoryPlugin` to make built-in mutating context-menu commands participate
in the same chronological undo/redo stack as direct edits and row ordering:

```ts
import {
  DataGridContextMenuPlugin,
  HistoryPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [HistoryPlugin, DataGridContextMenuPlugin];
```

Each command is one atomic history step, including multi-cell Cut, Paste, cell
Clear, and row Clear. Structural tracking covers row insert, duplicate, delete,
pin, and unpin commands, plus column insert, duplicate, delete, pin, unpin, and
move commands. Undo and redo restore the complete affected row sources or
authored column tree.

Copy and Copy with headers are intentionally excluded because they do not
mutate grid state. Canceled, unavailable, and no-op commands create no entry.
Commands replaced through `commandHandlers` are application-owned and are not
snapshotted automatically, so remote side effects remain under application
control.

In-memory history preserves row objects and function-valued column definitions,
including nested groups, renderers, and editors. Persistent History adapters
require serializable row and column definitions; JSON storage cannot recreate
functions. See [History Undo/Redo](../data-manage/history/) for stack,
persistence, and replay details.

## Optional capabilities

Commands appear only when their runtime exists. Add the matching plugin to expose filtering, Excel export, row selection, column auto-size, column collapse, tree, or server-grouping actions. Set `unavailableItems: 'disable'` to show unavailable commands in a disabled state instead.

```ts
grid.dataGridContextMenu = {
  unavailableItems: 'disable',
  rowPinning: true,
};
```

Row pinning is opt-in. Column insertion, duplication, and deletion are also opt-in and require an application factory so every new column receives a unique schema key:

```ts
grid.dataGridContextMenu = {
  columnSchema: {
    createColumn({ action, sourceColumn }) {
      return {
        ...sourceColumn,
        prop: `${String(sourceColumn.prop)}-${action}-${crypto.randomUUID()}`,
      };
    },
  },
};
```

## Spreadsheet-style formatting

Cell and column-header menus include a type-aware **Format** submenu. Native
numeric values expose Number, Currency, Accounting, Percentage, and Scientific
presets; native `Date` values expose Date, Date & time, and Time. **More
formats…** opens a separate Format Cells dialog for locale, decimal and date
styles, font and fill, alignment, wrapping, borders, and a live preview.

See [Format Cells](./format-cells/) for the complete popup guide, including
selection behavior, physical coordinates, render-time application, direct plugin
usage, and runtime persistence limits.

Formatting changes presentation only. Raw source values used by editors,
sorting, filtering, and formulas are not rewritten. Cell commands target the
active range; column-header commands create a true column formatting default.

Map application column types explicitly when their values do not carry native
number or `Date` types:

```ts
grid.dataGridContextMenu = {
  formatting: {
    locale: 'en-GB',
    currencies: ['GBP', 'EUR', 'USD'],
    columnTypeKinds: {
      money: 'number',
      applicationDate: 'date',
    },
  },
};
```

Set `formatting: false` to remove the whole formatting submenu. Formatting
commands respect grid and per-cell readonly rules. Value presets preserve
authored custom cell templates; the rich dialog can still compose appearance
through `cellProperties` without replacing interactive content.

## Inspect raw cell and column data

**Inspect cell** opens a compact read-only popup for the exact invoked cell. It
shows the column label and property, row dimension and authored source index,
plus the raw value and its JavaScript type. The bounded serializer displays
dates, `undefined`, `bigint`, symbols, functions, accessors, and circular
references as selectable JSON-like inspection text without invoking getters or
`toJSON`.

Full enumerable row snapshots are opt-in because source models can contain
hidden or internal fields. **Inspect column** is available from leaf column
headers and shows the property, pinned dimension, visible and physical indexes,
type, readonly mode, sort order, filter configuration, rendered width, and
authored width bounds. The complete resolved column definition is also opt-in
because schema objects can contain private application metadata.

Limits and an application redaction hook are available when complete row or
column inspection is appropriate:

```ts
grid.dataGridContextMenu = {
  inspection: {
    includeRowData: true,
    includeColumnData: true,
    serialization: { maxDepth: 5, maxEntries: 100, maxOutputLength: 20_000 },
    redact(value, { kind }) {
      return kind === 'row' || kind === 'column'
        ? redactPrivateFields(value)
        : value;
    },
    localeText: { title: 'Cell details' },
  },
};
```

The limits bound recursive traversal and rendered output after JavaScript has
discovered an object's own keys. They are not a sandbox for hostile Proxy traps
or extremely wide objects; use `redact` to replace untrusted complex values.

Both inspectors remain available for readonly cells and readonly grids. Hide
them like any other built-in item with `hiddenItems: { 'cell.inspect': true,
'column.inspect': true }`, or replace their behavior through the matching
`commandHandlers` entry.

Grid readonly mode blocks all local data and schema mutations. Static and
functional column readonly rules hide Edit for the invoked cell; mixed Clear,
Cut, and Paste targets remain usable but skip every readonly cell. Copy and
non-mutating view commands remain available. Synthetic row-group records never
receive destructive row commands.

---

# Format Cells

URL: https://pro.rv-grid.com/guides/data-grid/format-cells/
Source: src/content/docs/guides/data-grid/format-cells.mdx
Description: Configure declarative and interactive spreadsheet-style value, visual presentation, appearance, and editor behavior for RevoGrid cells, rows, and columns.

The **Format Cells** dialog provides spreadsheet-style presentation controls
without changing the values stored in the grid source. Use it for number,
currency, date, and time display as well as typography, colors, alignment,
wrapping, and borders.

The dialog and the quick **Format** submenu are powered by
`DataGridFormattingPlugin`. Registering it also installs
`DataGridContextMenuPlugin`, which supplies the selection opened from cell and
column-header menus. Registering `DataGridContextMenuPlugin` as the entry point
continues to work and installs the same formatting runtime.

  Formatting created by the **Format Cells** dialog is runtime presentation
  metadata. The plugin does not write it into source row objects, change the raw
  cell value, or store an Excel-style format string beside the value.
  Declarative formatting is covered first below.

## Declarative cell, row, and column formatting

Register `DataGridFormattingPlugin`, then use either of these declarative
inputs:

- `column.dataGridFormat` accepts either a format for the whole column or a
  function that chooses a format for each cell.
- `grid.dataGridFormatting` defines reactive whole-column, whole-row, and cell
  presets. Reassigning this property replaces the declarative preset state and
  refreshes the grid.

This complete example formats positive amounts as GBP currency and negative
amounts as EUR accounting values. The resolver receives the current row and
cell value, so no external lookup function is needed. The example does not
retrieve the plugin or call `apply()`:

```ts
import type { ColumnRegular } from '@revolist/revogrid';
import {
  DataGridFormattingPlugin,
  type DataGridCellFormat,
} from '@revolist/revogrid-pro';

type InvoiceRow = {
  id: string;
  customer: string;
  amount: number;
};

const gbpFormat: DataGridCellFormat = {
  // Controls how the raw cell value is displayed.
  value: {
    // Uses the built-in currency formatter.
    kind: 'preset', preset: 'currency',
    // Applies UK number and currency conventions.
    locale: 'en-GB',
    // Displays the value as British pounds.
    currency: 'GBP',
    // Always displays two digits after the decimal point.
    decimalPlaces: 2,
    // Adds thousands separators, for example £1,200.00.
    useGrouping: true,
  },
  // Controls the visual styling of the formatted cell.
  appearance: {
    // Aligns the displayed value to the right of the cell.
    horizontal: 'right',
  },
};

const euroWarningFormat: DataGridCellFormat = {
  value: {
    kind: 'preset', preset: 'accounting',
    locale: 'en-GB',
    currency: 'EUR',
    decimalPlaces: 2,
  },
  appearance: {
    bold: true,
    textColor: '#b91c1c',
    fillColor: '#fef2f2',
    horizontal: 'right',
  },
};

const columns: ColumnRegular<string, InvoiceRow>[] = [
  { prop: 'customer', name: 'Customer' },
  {
    prop: 'amount',
    name: 'Amount',
    // Called independently for every cell in this column.
    dataGridFormat: ({ model }) =>
      model.amount < 0 ? euroWarningFormat : gbpFormat,
  },
];

const source: InvoiceRow[] = [
  { id: 'invoice-1', customer: 'Acme Ltd', amount: 1200 },
  { id: 'invoice-2', customer: 'Northwind', amount: -350.5 },
];

// Installs formatting, the Format Cells dialog, and its context-menu commands.
grid.plugins = [DataGridFormattingPlugin];
grid.columns = columns;
grid.source = source;
```

The resolver argument contains `{ model, value, prop, rowType }`. Return a
`DataGridCellFormat` to format the cell, or `undefined` when the column does not
define a format for that cell. For one format across the entire column, assign
the object directly instead:

```ts
dataGridFormat: gbpFormat;
```

When formatting is application state rather than column configuration, keep the
same presets in the reactive grid property:

```ts
grid.dataGridFormatting = {
  columns: [{ column: 1, format: gbpFormat }],
  rows: [{ row: 0, format: { appearance: { bold: true } } }],
  cells: [{
    range: { start: { row: 1, column: 1 } },
    format: euroWarningFormat,
  }],
};
```

Coordinates are zero-based physical indexes in the row and column source
arrays. A row preset applies to every current and future column at that row
coordinate. A column preset applies to every current and future row at that
column coordinate. Presets use regular body sources by default. Set `rowType`
or `colType` when targeting a pinned source.

The declarative precedence is cell preset, then row preset, then grid column
preset, then `column.dataGridFormat`. Runtime operations through
`DataGridFormattingPlugin.apply()`, `applyValueFormat()`, or `clear()` take
precedence over every declarative source. The raw values remain `1200` and
`-350.5` for editing, sorting, filtering, and application code.

Framework wrappers use the same grid property. In React and Vue, bind
`dataGridFormatting` directly. If a generated Angular wrapper version does not
yet declare that plugin property as an `@Input`, set
`gridElement.dataGridFormatting = formattingState` on the underlying
`HTMLRevoGridElement`. Do not put formatting state in `additionalData`; that
compatibility path is deprecated.

## Format a whole column, whole row, or individual cells

The mutation API uses the same zero-based physical coordinates as declarative
state. Complete-row and complete-column targets are explicit, so their intent
is not lost when the grid currently has no rows or columns:

```ts
const formatting = (await grid
  .getPlugins())
  .find(plugin => plugin instanceof DataGridFormattingPlugin);

if (!formatting) throw new Error('Formatting plugin is not installed.');

// The entire Amount column, including rows added later.
formatting.apply(
  { scope: 'columns', ranges: { start: 1 } },
  gbpFormat,
);

// The entire first body row, including columns added later.
formatting.apply(
  { scope: 'rows', ranges: { start: 0 } },
  { appearance: { bold: true, fillColor: '#fef3c7' } },
);

// One cell at physical row 1, physical column 1.
formatting.apply(
  { start: { row: 1, column: 1 } },
  euroWarningFormat,
);
```

`end` is inclusive and may be before `start`; the plugin normalizes reversed
ranges. Supply an array to format multiple independent ranges. Row targets may
set `rowType`, column targets may set `colType`, and cell ranges may set both.
The same targets work with `applyValueFormat()`, `patch()`, `clear()`,
`openDialog()`, and `inferValueKind()`.

## Enable Format Cells

Register the formatting plugin to make formatting available from cell and
column-header menus. It installs the context-menu integration and dialog
automatically:

```ts
import { DataGridFormattingPlugin } from '@revolist/revogrid-pro';

grid.plugins = [DataGridFormattingPlugin];
```

The one-line formatting panel is installed with the formatting runtime but is
disabled by default. Enable or disable it reactively with its dedicated grid
property:

```ts
grid.dataGridFormattingPanel = true;

// Hide it again without removing the formatting plugin.
grid.dataGridFormattingPanel = false;
```

Assign a `DataGridFormattingPanelConfig` object instead of `true` when the
toolbar also needs localized labels.

Do not register `DataGridContextMenuPlugin` separately. If your grid already
uses it as its main menu plugin, keep that setup; it installs
`DataGridFormattingPlugin` in the opposite direction and reuses one instance of
each plugin.

Right-click a writable cell or column header and open **Format**. The submenu
offers type-aware quick presets and two general actions:

- **More formats…** opens the complete Format Cells dialog.
- **Clear formatting** removes both value formatting and appearance formatting
  from the selected target.

For the complete context-menu configuration and command customization contract,
see [Data Grid Formatting](./context-menu/).

## Configure formatting defaults

Formatting options belong under `grid.dataGridContextMenu.formatting`:

```ts
type InvoiceRow = {
  id: string;
  customer: string;
  amount: number;
  issuedAt: string;
};

grid.dataGridContextMenu = {
  formatting: {
    autoAlignNumericValues: true,
    locale: 'en-GB',
    locales: ['en-GB', 'de-DE', 'fr-FR'],
    currencies: ['GBP', 'EUR', 'USD'],
    fontFamilies: ['Inter', 'Georgia', 'IBM Plex Mono'],
    columnTypeKinds: {
      money: 'number',
      applicationDate: 'date',
    },
    // Keep this column's active column-level format authoritative.
    protectedColumnProps: ['amount'],
    resolveStructuralRowIdentity: (row) => row.id,
  },
};
```

| Option             | Purpose                                                                                                                                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autoAlignNumericValues` | Right-aligns finite number and bigint values, plus Number, Currency, Accounting, Percentage, and Scientific formats, when horizontal alignment is Automatic. Effective advanced presentations keep their own layout. Defaults to `true`; set to `false` to disable this derived alignment. |
| `locale`           | Initial locale used by `Intl.NumberFormat` and `Intl.DateTimeFormat`. The browser locale is used when omitted.                                                                                                          |
| `locales`          | Locale choices shown in the dialog. A built-in list is used when omitted.                                                                                                                                               |
| `currencies`       | Currency choices shown by Currency and Accounting formats. The first entry is used by the dialog and quick presets.                                                                                                     |
| `fontFamilies`     | Application font choices shown in Typography.                                                                                                                                                                           |
| `columnTypeKinds`  | Maps application column types to `number`, `date`, `text`, `boolean`, `mixed`, or `unknown` for command availability. It does not convert values.                                                                       |
| `resolveValueKind` | Overrides value-kind inference for the complete selected target. It does not convert values.                                                                                                                            |
| `resolveStructuralRowIdentity` | Retains formatting across length-changing immutable source updates by matching old and new row objects with an application-owned stable identity. Object identity is used when omitted. |
| `scopes`           | Limits formatting to `cell`, `columnHeader`, or both.                                                                                                                                                                   |
| `protectedColumnProps` | Column `prop` values whose active column-level format masks cell and row formats. The masked state is retained and becomes effective again if protection is removed. |
| `advancedFormats`  | Configures compatible visual formats, individual format availability, custom definitions, and optional editor references. Set it to `false` to disable advanced formats.                                                |
| `localeText`       | Replaces dialog, preset, option, palette, and advanced-format registry labels for localization.                                                                                                                         |

### Protect a column format from overrides

Use `protectedColumnProps` when a column's value, appearance, or presentation
must remain uniform even when users or application code apply formats to a row
or individual cell. The setting is selected by stable column `prop`, not by a
physical column index:

```ts
grid.dataGridContextMenu = {
  formatting: {
    protectedColumnProps: ['amount'],
  },
};
```

Protection applies only while the column has an active column-owned format
from `column.dataGridFormat`, `dataGridFormatting.columns`, or a whole-column
runtime operation. Cell and row formats are still retained in formatting state;
they become effective again if the property is removed from the configuration.
Clearing the column format restores the normal newest-runtime-operation
precedence.

### Physical coordinates and source replacement

Formatting belongs to a physical source position, not to a row object or
business key:

```ts
grid.dataGridFormatting = {
  cells: [{
    range: {
      start: { row: 1, column: 1 },
      end: { row: 3, column: 2 },
    },
    format: euroWarningFormat,
  }],
};

// New row objects at the same source positions receive the same formatting.
grid.source = invoices.map((invoice) => ({ ...invoice }));
```

Replacing every record without changing source length preserves formats at the
same coordinates. Structural source changes retain formats with surviving row
objects, remove formats owned by deleted rows, and shift or pin retained
formats with their rows. If an application recreates row objects while also
inserting or deleting records, configure `resolveStructuralRowIdentity` with a
stable unique business key so the old and new rows can be matched:

```ts
grid.dataGridContextMenu = {
  formatting: {
    resolveStructuralRowIdentity: (row) => row.id,
  },
};
```

Filtering only changes virtual order and does not change physical formatting
addresses.

## Accessibility and localization

Format Cells uses the shared modal focus trap and restores focus to the grid
when it closes. Every native input and select has a programmatic label;
icon-only actions expose a localized accessible name, pressed or expanded
state, and a tooltip on both hover and keyboard focus. Escape dismisses an open
control tooltip before a second Escape closes the dialog. Preset lists,
segmented controls, color palettes, and expandable sections support their
native or ARIA keyboard patterns, visible focus, forced-colors mode, and reduced
motion preferences.

Dialog labels, actions, tooltips, validation feedback, the plain-text example,
and palette color names come from `formatting.localeText`. Section templates
replace `{section}` with the localized section name:

```ts
grid.dataGridContextMenu = {
  formatting: {
    localeText: {
      title: 'Formatear celdas',
      close: 'Cerrar formato de celdas',
      bold: 'Negrita',
      expandSection: 'Abrir {section}',
      collapseSection: 'Cerrar {section}',
      invalidColor: 'Introduce un color hexadecimal válido.',
      textExample: 'Ejemplo de texto',
      colorLabels: {
        '#be185d': 'Rosa',
        '#2563eb': 'Azul',
      },
      advancedGroupLabels: {
        Indicators: 'Indicadores',
      },
      advancedFormatLabels: {
        heatmap: 'Mapa térmico',
      },
      advancedControlLabels: {
        'heatmap.midValue': 'Punto medio',
        'heatmap.highColor': 'Color alto',
      },
    },
  },
};
```

`localeText` is partial. Unspecified strings and palette names retain the
built-in English defaults. Every label map is merged by key, including
`presetLabels`, `optionLabels`, `colorLabels`, `advancedGroupLabels`,
`advancedFormatLabels`, `advancedFormatDescriptions`,
`advancedControlLabels`, and `advancedOptionLabels`.

Advanced controls use `<format id>.<control key>` keys. Select options append
the option value: `<format id>.<control key>.<option value>`. These same stable
keys localize application-defined formats; their registry-authored label or
description remains the fallback when a translation is omitted.

Set `formatting: false` to remove the formatting submenu while keeping the rest
of the context menu:

```ts
grid.dataGridContextMenu = {
  formatting: false,
};
```

This hides formatting commands; it does not remove declarative formats already
provided through `dataGridFormat` or `dataGridFormatting`.

## Value formatting

Value formats change only the string rendered in a cell. They do not replace
the raw value used by editing, sorting, filtering, formulas, or application
code.

The available presets are:

| Preset      | Display behavior                                                                                                            |
| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| Automatic   | Leaves value display to the column's existing renderer.                                                                     |
| Number      | Locale-aware numeric output with decimal and grouping controls.                                                             |
| Currency    | Locale-aware currency output using the selected ISO currency.                                                               |
| Accounting  | Currency output with accounting-style negative values.                                                                      |
| Percentage  | Locale-aware percentage output. With the default two decimal places, a raw value of `0.25` displays as `25.00%` in `en-US`. |
| Scientific  | Locale-aware scientific notation.                                                                                           |
| Date        | Date output with short, medium, long, or full date style.                                                                   |
| Time        | Time output with short, medium, or long time style.                                                                         |
| Date & time | Combined date and time output.                                                                                              |
| Plain text  | Displays the value as text.                                                                                                 |

Numeric formats support decimal places, thousands grouping, and negative-number
styles. Currency formats also expose the configured currency list. Date and
time formats support style controls and use the configured locale.

Quick menu commands are type-aware. Native JavaScript numbers and `bigint`
values expose numeric commands, while native `Date` values expose date and time
commands. Use `columnTypeKinds` or `resolveValueKind` to classify custom column
types and parseable date strings:

```ts
const issuedAtColumn = {
  prop: 'issuedAt',
  name: 'Issued',
  columnType: 'applicationDate',
};

grid.columns = [
  { prop: 'customer', name: 'Customer' },
  { prop: 'amount', name: 'Amount', columnType: 'money' },
  issuedAtColumn,
];

grid.dataGridContextMenu = {
  formatting: {
    columnTypeKinds: {
      money: 'number',
      applicationDate: 'date',
    },
  },
};
```

Type classification controls which quick commands are available; it does not
coerce the source value. Numeric presets format only `number` and `bigint`
values, so convert numeric strings to numbers before formatting them. Date
presets accept valid `Date` objects, parseable date strings, and non-negative
Excel serial-date numbers.

If a value cannot be converted by the selected formatter, the renderer falls
back to the original value's string representation instead of throwing.

Selecting `preset: 'currency'` is sufficient to activate the built-in
`Intl.NumberFormat` currency renderer. You do not install a separate currency
formatter. `currency`, `locale`, `decimalPlaces`, and `useGrouping` configure
that renderer.

## Exact Excel-compatible format codes

Choose **Custom** in Format Cells to edit an Excel-compatible number-format
code with a live preview. Invalid codes disable Apply. The exact code is stored
as a separate discriminated variant, so it cannot conflict with preset options:

```ts
const exactExcelFormat: DataGridCellFormat = {
  value: {
    kind: 'code',
    formatCode: '[Red][<0]#,##0.00;#,##0.00;"-";@',
    locale: 'en-GB',
  },
};
```

The internal formatter supports positive/negative/zero/text sections,
conditions and colors, locale/currency tokens, dates and elapsed time,
fractions, scientific notation, percentages, scaling, grouping, text
placeholders, quoted/escaped literals, and Excel spacing/fill instructions.
Raw source values are never replaced by their display text. Excel serial dates
use the shared dates module, including serial 60, while application `Date`
values remain `Date` values.

## Advanced visual formats

**Advanced format** is a category in the existing Value formatting list. Select
it to reveal a grouped icon list of compatible visual formats and the options
declared by the selected format. Every row remains visible in the details pane;
built-ins use Font Awesome SVG icons, and custom definitions without an icon
receive the standard formatting icon. The category includes only formats
compatible with every non-null value in the current selection. Choosing one
stores only its stable ID and serializable options in
`DataGridCellFormat.presentation`; source values remain unchanged. The
appearance inspector stays available, so inherited text color, fill,
typography, alignment, and borders can still be adjusted.

You can predefine the same format on a column or choose it per cell:

```ts
const columns: ColumnRegular<string, ProjectRow>[] = [
  {
    prop: 'completion',
    name: 'Completion',
    dataGridFormat: {
      presentation: {
        id: 'progress-line',
        options: { minValue: 0, maxValue: 100 },
      },
    },
  },
  {
    prop: 'metric',
    name: 'Metric',
    dataGridFormat: ({ model }) =>
      model.metricKind === 'history'
        ? { presentation: { id: 'sparkline' } }
        : {
            presentation: {
              id: 'heatmap',
              options: { minValue: 0, maxValue: 100 },
            },
          },
  },
];
```

Built-in formats and their required source shapes are:

| Value shape                            | Format IDs                                                                                              |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Finite number                          | `progress-line`, `progress-line-value`, `circular-progress`, `heatmap`, `rating`, `change`, `threshold` |
| Boolean                                | `boolean`, `thumbs`                                                                                     |
| String, number, or boolean             | `badge`, `avatar`, `avatar-with-text`                                                                   |
| Non-empty number array                 | `sparkline`, `bar`, `pie`                                                                               |
| Non-empty `{ value, color?, name? }[]` | `pie`                                                                                                   |
| Non-empty `{ start, end, label? }[]`   | `timeline`                                                                                              |
| Non-empty record of numeric values     | `summary-percentage`, `summary-aggregate`                                                               |

The chart-only column-header renderer is not a cell format and is intentionally
excluded. Mixed selections show a format only when every selected non-null
value matches its shape.

When edited, Sparkline and Bar chart cells accept comma-separated numbers or a
JSON number array. Timeline opens as compact JSON and saves a validated
`{ start, end, label? }[]` value, so structured data never becomes
`[object Object]` or a display string.

The built-in `boolean` format displays `Yes`/`No`, while `thumbs` is its visual
alternative. Both open the same typed `Yes`/`No`/`Not set` dropdown on edit.
Their dropdown values and options reuse the active cell template, so switching
one cell between Boolean and Thumbs changes both its grid presentation and its
editor presentation without adding a column type.

### Configure or disable formats

Compatible built-ins are enabled by default. Disable one format, change its
application defaults, or disable the Advanced category under the
context-menu formatting config:

```ts
grid.dataGridContextMenu = {
  formatting: {
    advancedFormats: {
      formats: {
        pie: false,
        heatmap: {
          defaults: { minValue: -20, maxValue: 50, colorMap: 'coldmap' },
        },
      },
    },
  },
};

// Removes the Advanced category but keeps value and appearance formats.
grid.dataGridContextMenu = {
  formatting: { advancedFormats: false },
};
```

Application-owned data such as badge styles, threshold definitions, dropdown
choices, and timeline bounds belongs in `defaults` or the column. The dialog
shows only controls declared by the format definition.

For the built-in Badge format, **Fill color** controls the badge background and
**Text color** controls the badge label. These colors do not paint the complete
cell. A matching `badgeStyles` entry supplies the fill fallback, while the label
inherits ordinary theme text until the user chooses an explicit **Text color**.

### Register an application format

Custom formats use the same registry and dialog controls as built-ins:

```ts
grid.dataGridContextMenu = {
  formatting: {
    advancedFormats: {
      customFormats: [
        {
          id: 'risk-meter',
          label: 'Risk meter',
          group: 'Application',
          valueKind: 'number',
          defaults: { maximum: 10, color: '#dc2626' },
          controls: [
            { type: 'number', key: 'maximum', label: 'Maximum', min: 1 },
            { type: 'color', key: 'color', label: 'Color' },
          ],
          cellTemplate: (h, { value, column }) =>
            h('meter', {
              min: 0,
              max: column.maximum,
              value,
              style: { accentColor: column.color },
            }),
        },
      ],
    },
  },
};
```

Use `isCompatible({ value, model, column, rowType })` instead of `valueKind`
when application data needs a more specific predicate.

## Editors for formatted cells

Formatting can select an editor for the actual cell being edited. The source
value preset can supply an editor, and an advanced-format definition can expose
its own `editor` reference. Editors remain optional dependencies supplied by
the application:

```ts
import DateColumnType from '@revolist/revogrid-column-date';
import { badgeRenderer, ColumnDropdown } from '@revolist/revogrid-pro';

const dateType = new DateColumnType();

grid.dataGridContextMenu = {
  formatting: {
    advancedFormats: {
      presetEditors: {
        date: dateType.editor,
        datetime: dateType.editor,
        time: dateType.editor,
      },
      customFormats: [
        {
          id: 'status-badge',
          label: 'Status badge',
          valueKind: 'scalar',
          cellTemplate: badgeRenderer,
          editor: ColumnDropdown.editor,
        },
      ],
    },
  },
};
```

Editor resolution happens for each cell, so two cells in one column can use
different editors when `dataGridFormat` returns different value presets or
presentations. If a configured editor reference cannot be resolved, the plugin
uses the column's original editor and then the grid's text editor.

An application-authored `editor` is protected by default. Set
`replaceAuthoredEditors: true` only when formatted cells should take ownership
globally. Advanced presentation renderers also protect an authored
`cellTemplate` by default; configure `replaceAuthoredTemplates` globally or
`replaceAuthoredTemplate` on one definition when that advanced renderer should
replace it. Ordinary value categories are an explicit presentation choice: a
non-Automatic category replaces the authored visual template, while Automatic
restores it.

## Appearance formatting

Numeric cells use spreadsheet-style right alignment by default while the
formatting plugin is installed. This applies to finite number and bigint source
values even when they have no stored format, and to Number, Currency,
Accounting, Percentage, and Scientific value formats. An explicit **Left**,
**Center**, or **Right** appearance choice overrides the default.
Advanced presentations such as Progress line and Rating stars retain their
renderer-owned layout while alignment is Automatic; an explicit appearance
alignment still overrides that layout.

To retain the grid's existing alignment instead, disable automatic numeric
alignment in the formatting configuration:

```ts
grid.dataGridContextMenu = {
  formatting: {
    autoAlignNumericValues: false,
  },
};
```

The appearance side of the dialog contains a live preview and these groups:

- **Typography:** font family, font size, bold, italic, underline, and
  strikethrough.
- **Colors:** text color and fill color, including predefined and custom colors.
- **Alignment:** horizontal alignment, vertical alignment, and text wrapping.
- **Borders:** border style and border color.

Appearance is composed with the column's existing `cellProperties`. Apart from
the enabled-by-default numeric alignment described above, formatting adds or
overrides only explicitly selected style values, so unrelated authored classes
and styles remain in place.

Columns with an authored `cellTemplate`, including selection-style columns,
keep the complete Format Cells category list. Choosing a concrete value format
switches the cell to that plain value presentation; choosing Automatic restores
the authored template. Row-drag content remains appearance-only. For an
advanced format supplied declaratively or through the plugin API, set
`replaceAuthoredTemplates` globally, or `replaceAuthoredTemplate` on that
definition, only when its renderer should explicitly own those cells.

## Copy and paste formatting

`DataGridFormattingPlugin` installs one `ClipboardPlugin` automatically. The
formatting plugin remains the owner of the format throughout copy and paste:

1. Copy asks the formatting runtime for the effective `DataGridCellFormat` at
   every selected physical cell.
2. RevoGrid-to-RevoGrid copy stores that canonical format in the versioned rich
   clipboard payload, together with typed values, formulas, range geometry,
   merges, and explicit dimensions.
3. Excel HTML import converts allowlisted Excel declarations into the same
   `DataGridCellFormat` model. Clipboard code never installs raw Excel CSS on a
   cell. Excel CSS escapes and named formats such as `Short Date` are normalized
   by the formatting plugin.
4. Paste sends values and formulas through the regular grid edit, readonly, and
   validation pipeline. Only accepted destinations receive formatting, applied
   as one formatting batch.
5. Copy back to Excel converts the canonical format into Excel HTML declarations
   and number-format codes without changing the source row value.

This keeps formatting created at every supported scope in sync: individual
cells, rectangular or independent ranges, complete rows, and complete columns.
The effective resolved format is copied, including inherited row or column
formatting; the destination receives a cell-level snapshot of that appearance.

Date handling follows the same non-destructive rule. Excel serial dates stay
typed numbers with a date/time format after import. When copying an application
`Date` or valid date-like value to Excel, only the outbound HTML representation
is converted to an Excel 1900-system serial. RevoGrid source data is not
rewritten.

Some Excel Desktop versions, including Excel for macOS, omit the typed `x:num`
attribute and expose only formatted display text. When that text is accompanied
by a recognized Accounting, Percentage, or date format, the formatting plugin
recovers the typed numeric or serial-date value before applying the canonical
format. It does not infer a type from unformatted visual text.

The same conversion covers the full Excel number-format family: Number,
Currency, Accounting, Percentage, Fraction, Scientific, Date, Time, combined
date-time, elapsed time, Special, and numeric/date/time Custom codes. General
and Text remain text without an explicit typed clipboard value. Conditions,
four-section positive/negative/zero/text rules, locale tokens, scaling commas,
literal affixes, spacing, and fill are compiled by the same formatting engine
used for cell rendering. See the
[display-only category matrix](/guides/grid-utilities/clipboard-json/#display-only-excel-category-coverage)
for the exact fallback policy.

The [native Excel interoperability matrix](/guides/grid-utilities/clipboard-json/#native-excel-interoperability-matrix)
shows the real Excel-to-RevoGrid rendering for the full tested number-format
family and representative appearance options. The formats shown there are
stored and rendered by this formatting plugin; clipboard code does not attach
Excel CSS to cells.

For the exact directional support matrix, custom clipboard handlers, rich MIME
contract, formulas, merges, dimensions, and the browser/native Excel boundary,
see [Smart Excel-Compatible Clipboard](/guides/grid-utilities/clipboard-json/).

## Range fill formatting

Register `AutoFillPlugin` and `EventManagerPlugin` alongside
`DataGridFormattingPlugin` to stretch the source range's effective formatting
together with the value sequence selected by AutoFill. A single Rating cell fills
Rating cells; a two-row or two-column source repeats its formats as a tile over the
extended range.

```ts
import {
  AutoFillPlugin,
  DataGridFormattingPlugin,
  EventManagerPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [DataGridFormattingPlugin, AutoFillPlugin, EventManagerPlugin];
```

Formatting remains owned by this plugin rather than being converted into cell CSS.
The source format is resolved from the same cell, row, column, and authored-column
precedence used during rendering. Destination formats are written as cell-level
runtime operations in one batch after the range edit is accepted. A source slot
with no effective format explicitly clears the corresponding destination slot, so
old destination formatting does not leak into the filled result.

See the [Autofill guide](/guides/data-manage/autofill/#filling-formatted-cells)
for value strategies, preview behavior, and range-fill setup.

## Excel export

Add `ExportExcelPlugin` when Format Cells presentation should be retained in an
`.xlsx` workbook. The Excel plugin discovers the formatting runtime during
export:

```ts
import {
  DataGridFormattingPlugin,
  ExportExcelPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [DataGridFormattingPlugin, ExportExcelPlugin];
```

The integration exports the current formatting automatically:

- Number, Currency, Accounting, Percentage, Scientific, Date, Time, Date &
  time, and Plain text presets become native Excel number-format codes.
- Numeric and date cells remain typed workbook values rather than preformatted
  strings, so Excel formulas, editing, and sorting continue to work.
- Font family and size, emphasis, text and fill colors, alignment, wrapping,
  and borders become workbook cell styles.
- Group rows become merged, indented workbook headings. Export follows the
  visible grouped projection, so collapsed descendants are not included.

Advanced visual formats are not converted into Excel chart drawings. A format
definition can provide `exportValue` to convert its structured data to a
workbook-safe scalar while leaving the grid source unchanged. The built-in
Timeline format does this automatically: multiple events export as readable
text such as `Build: 8–12; Review: 14–18` instead of `[object Object]`.
Advanced formats without `exportValue` continue to export their raw cell value,
ordinary value format, and appearance.

Authored `column.excelExport` properties remain the base export configuration.
An explicitly selected Format Cells value or appearance setting overrides the
corresponding workbook field for that target without replacing unrelated
column-owned export properties.

## Selection scope

The menu surface decides which formatting scope is created:

- From a **cell**, formatting applies to the active writable range. If the
  multi-range plugin owns several selected ranges and the menu opens inside
  them, all resolved writable cells in those ranges are targeted.
- From a **column header**, formatting creates a column-wide default at the
  physical column address. It applies to body and pinned rows rendered for that
  column.

Readonly behavior is resolved before the command runs:

- Grid-level readonly mode prevents formatting changes.
- Readonly cells are skipped in mixed cell selections.
- A formatting command is unavailable when no writable target remains.
- Synthetic grouping rows are not assigned cell formatting.

## Apply, Cancel, and Clear

The dialog edits a temporary draft:

- **Apply** commits the complete value, advanced presentation, and appearance
  draft to the selected cells or columns, closes the dialog, and refreshes the
  grid.
- **Cancel**, the close button, backdrop dismissal, and Escape close the dialog
  without committing the draft.
- **Clear formatting** commits an explicit clear operation for the selected
  target and refreshes the grid.

Clear formatting does not clear the source value. It removes only the rendered
format. An explicit clear also participates in cell-versus-column precedence,
which is important when a cell override and a column default both exist.

## Where formatting is stored

Formatting can come from declarative configuration or runtime operations:

- `column.dataGridFormat` remains part of the column definition.
- `grid.dataGridFormatting` is application-owned grid state. Reassigning it
  replaces all declarative grid presets.
- Formats created through the dialog or plugin API are held privately by the
  current `DataGridFormattingPlugin` instance; source rows are not modified.

The effective precedence is:

1. A runtime format or explicit clear created through `apply()`,
   `applyValueFormat()`, `clear()`, or the context menu.
2. A physical range preset in `grid.dataGridFormatting.cells`.
3. A row preset in `grid.dataGridFormatting.rows`.
4. A column preset in `grid.dataGridFormatting.columns`.
5. The column's static or function-based `dataGridFormat`.

Within runtime state, each apply or clear operation receives a new revision.
When matching runtime cell, row, and column operations overlap, the newest
revision wins. For example:

1. Format the `amount` column as Number.
2. Format one `amount` cell as Currency; that newer cell override wins.
3. Clear the entire `amount` column; the newer column clear wins over the older
   cell override.
4. Format the individual cell again; the newest cell format wins.

A whole-row operation follows the same rule. It is stored once for the physical
row, rather than expanded into the currently visible cells, so it also formats
columns added later.

A `DataGridCellFormat` used by any of these sources has up to three independent
layers: ordinary value formatting, an advanced visual presentation, and
appearance. Omit any layer that the cell does not need:

```ts
const format = {
  value: {
    kind: 'preset', preset: 'currency',
    locale: 'en-GB',
    currency: 'GBP',
    decimalPlaces: 2,
    useGrouping: true,
    negativeStyle: 'minus',
  },
  appearance: {
    bold: true,
    textColor: '#0f172a',
    fillColor: '#fef3c7',
    horizontal: 'right',
    wrap: false,
    borderStyle: 'solid',
    borderColor: '#f59e0b',
  },
  presentation: {
    id: 'progress-line',
    options: { minValue: 0, maxValue: 100 },
  },
} as const;
```

No `format` property is added to the example source row. Reading
`row.amount` still returns the original value.

## How formatting reaches rendered cells

After Apply, Clear, or a `grid.dataGridFormatting` assignment, the plugin asks
RevoGrid to refresh all rendered cells. For each non-grouping cell, it resolves
the effective format during `beforecellrender`:

1. Runtime and declarative sources are resolved using the precedence described
   above.
2. Appearance settings are composed into `cellProperties`.
3. A compatible advanced presentation renderer is supplied when one is
   configured. An authored `cellTemplate` or row-drag renderer remains protected
   unless replacement was explicitly enabled.
4. When there is no advanced renderer, a value-format renderer is supplied for
   a non-Automatic preset. This explicit choice replaces an authored visual
   template; Automatic leaves the authored template in place.
5. The underlying row model and raw value remain unchanged.

Because lookup happens during rendering, formatting follows virtualization,
scrolling, sorting, filtering, pinning, and ordinary grid refreshes. The plugin
does not inspect rendered DOM to reconstruct state.

## Save and restore formatting

Storage belongs to the application. After every runtime formatting change, the
plugin emits `datagridformattingchange` with the complete versioned state. Save
`event.detail.state` wherever the application already stores user preferences,
then pass it back through `grid.dataGridFormatting.state` when creating the
grid.

For example, use `localStorage` without adding storage behavior to the plugin:

```ts
const storageKey = 'invoice-grid-formatting';
const savedState = localStorage.getItem(storageKey);

grid.plugins = [DataGridFormattingPlugin];
grid.dataGridFormatting = {
  // Restore runtime formats once; omit state when nothing has been saved.
  state: savedState ? JSON.parse(savedState) : undefined,
};

grid.addEventListener('datagridformattingchange', ({ detail }) => {
  // detail.state is the complete snapshot; no merge with older state is needed.
  localStorage.setItem(storageKey, JSON.stringify(detail.state));
});
```

The event fires after dialog **Apply**, **Clear formatting**, `apply()`,
`applyValueFormat()`, `clear()`, `setState()`, undo, and redo. Assigning
`dataGridFormatting.state` restores state without emitting another event, so it
does not create a save loop or a history entry.

Declarative `columns`, `rows`, and `cells` remain application defaults. The runtime
snapshot contains only user or API operations that override them, including
explicit clears and cell/row/column operation order. Source rows and raw values
remain unchanged.

### Save to a server or application store

Load state first, assign it to the grid, and save the same complete event
payload. Wrap it with your dataset version (or another stable layout token) so
the server can reject stale coordinates:

```ts
const saved = await formattingApi.load(documentId);

grid.dataGridFormatting = {
  state: saved?.formatting,
};

let documentVersion = saved?.version;
let pendingSave = Promise.resolve();

grid.addEventListener('datagridformattingchange', ({ detail }) => {
  // Serialize writes so an older response cannot overwrite a newer edit.
  pendingSave = pendingSave.then(async () => {
    const result = await formattingApi.save(documentId, {
      version: documentVersion,
      datasetVersion: currentDatasetVersion,
      formatting: detail.state,
    });
    documentVersion = result.version;
  });
});
```

`detail.state` is already a complete JSON-serializable snapshot: save it as a
replacement, not as a partial patch. On reload, restoring the snapshot does not
emit another persistence event. The application owns request batching,
authentication, retries, error messages, and conflict handling; the formatting
plugin only reports state changes.

Formatting addresses are physical indexes in the corresponding body or pinned
source arrays. They remain valid when row objects are replaced, edited, or
loaded again in the same order. If server sorting, filtering, pagination, or a
new dataset version changes that physical order, do not apply the old snapshot
blindly: reject it by `datasetVersion`, or migrate its coordinates before
assigning `grid.dataGridFormatting.state`. No row key callback is required or
consulted by the formatting runtime.

### Undo and redo

Add History when formatting changes should use the same undo and redo stack as
data edits. `HistoryPlugin` installs Event Manager automatically:

```ts
import {
  DataGridFormattingPlugin,
  HistoryPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [DataGridFormattingPlugin, HistoryPlugin];
```

Each Apply or Clear operation is one history entry. Undo and redo restore the
complete previous or next formatting state and emit
`datagridformattingchange`, so the application saves the replayed state through
the same listener. No additional history configuration is required.

### Manual state control

The plugin instance also exposes `getState()` and `setState()`:

```ts
const saved = formatting.getState();
formatting.setState(saved);
```

State version 2 includes runtime row, column, and physical-cell operations,
explicit clears, dimension types, and revision order. It is JSON-safe when custom
presentation options are JSON-safe.

## Programmatic formatting API

`DataGridFormattingPlugin` also provides methods for application-driven
formatting. It still installs the context menu and dialog; you only need to
retrieve the instance when application code must apply, inspect, clear, or open
formatting programmatically. Use the grid's plugin collection rather than
attaching custom methods to the grid element:

```ts
import {
  DataGridFormattingPlugin,
  type DataGridFormattingSelection,
} from '@revolist/revogrid-pro';

type InvoiceRow = { id: string; amount: number };

const invoice: InvoiceRow = { id: 'invoice-1', amount: 1200 };

grid.columns = [{ prop: 'amount', name: 'Amount' }];
grid.plugins = [DataGridFormattingPlugin];
grid.source = [invoice];

const formatting = (await grid.getPlugins()).find(
  (plugin) => plugin instanceof DataGridFormattingPlugin,
) as DataGridFormattingPlugin<InvoiceRow> | undefined;

formatting?.configure({
  locale: 'en-GB',
  currencies: ['GBP', 'EUR'],
});

// Zero-based physical indexes into the rgRow and rgCol source arrays.
const selection: DataGridFormattingSelection = {
  start: { row: 0, column: 0 },
};

formatting?.apply(selection, {
  value: {
    kind: 'preset', preset: 'currency',
    locale: 'en-GB',
    currency: 'GBP',
    decimalPlaces: 2,
  },
  appearance: {
    bold: true,
    horizontal: 'right',
  },
});
```

`start` identifies the first physical source cell. The optional inclusive
`end` defaults to `start`, so one coordinate formats one cell. `rowType` and
`colType` default to `rgRow` and `rgCol`.

```ts
// Entire physical row across four columns.
formatting?.patch({
  start: { row: 3, column: 0 },
  end: { row: 3, column: 3 },
}, {
  appearance: { bold: true },
});

// Three rows by two columns.
formatting?.apply({
  start: { row: 3, column: 1 },
  end: { row: 5, column: 2 },
}, {
  appearance: { fillColor: '#fef3c7' },
});

// Independent or overlapping ranges are accepted as an array.
formatting?.clear([
  { start: { row: 0, column: 0 }, end: { row: 1, column: 1 } },
  { start: { row: 8, column: 4 } },
]);
```

Physical indexes address the unfiltered `source` arrays directly. Sorting,
filtering, and viewport order do not change which source models are targeted.
The plugin stores those coordinates directly and resolves the current source
row and column only when it needs rendering or callback context.

The public methods are:

| Method                                               | Purpose                                                                                                                       |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `configure(config)`                                  | Sets dialog and rendering options such as locale, currencies, fonts, and localized labels.                                   |
| `apply(selection, format)`                           | Replaces the selected target's complete value, advanced presentation, and appearance format.                                  |
| `applyValueFormat(selection, valueFormat)`           | Selects an ordinary value presentation, retains appearance, and replaces an active advanced visualization.                    |
| `clear(selection)`                                   | Applies an explicit clear that suppresses lower-priority declarative formats for the selected target.                         |
| `getFormat(address)`                                 | Resolves the effective format at a physical cell address.                                                                     |
| `getColumnFormat(address)`                           | Resolves the effective format for a complete physical column.                                                                 |
| `getState()`                                         | Returns a portable, versioned snapshot of runtime Apply and Clear operations.                                                 |
| `setState(state)`                                    | Replaces runtime operations, refreshes the grid, and emits `datagridformattingchange`.                                        |
| `openDialog(selection, valueKind, valueFormatting?)` | Opens Format Cells for an application-provided selection. Pass `false` as the third argument for appearance-only editing.     |

For example, open the same dialog programmatically:

```ts
formatting?.openDialog(selection, 'number');
```

Or inspect and clear the known target:

```ts
const current = formatting?.getFormat({ row: 0, column: 0 });

if (current?.value?.preset === 'currency') {
  formatting?.clear(selection);
}
```

## Practical recommendations

- Use physical coordinates for persisted formatting. Replacing source objects
  at the same positions preserves formatting; moving records does not move it.
- Keep source values typed and unformatted; let the renderer own presentation.
- Use `columnTypeKinds` to control type-aware command availability for custom
  column types and parseable date strings; it does not coerce numeric strings.
- Use column-header formatting for broad defaults and cell formatting for
  exceptions.
- Choose Automatic to restore a custom interactive template after displaying a
  plain value format.
- Listen to `datagridformattingchange` and persist `detail.state` in the
  application-owned browser store, state manager, or server API.

---

# Cell and Row Notes

URL: https://pro.rv-grid.com/guides/data-grid/notes/
Source: src/content/docs/guides/data-grid/notes.mdx
Description: Add versioned cell and row notes with severity, mentions, filtering, offline drafts, and XLSX export.

`GridNotesPlugin` adds metadata notes without changing source rows. Every note is addressed by a stable host row ID and, for cell notes, a column prop. Sorting, filtering, pinning, grouping, clipboard values, and CSV output therefore remain independent from note content.

## Configure the plugin

```ts
import {
  GridNotesPlugin,
  InMemoryGridNoteAdapter,
} from '@revolist/revogrid-pro';

const adapter = new InMemoryGridNoteAdapter();

grid.plugins = [GridNotesPlugin];
grid.gridNotes = {
  adapter,
  getRowId: row => row.id,
  getRowLabel: row => row.status,
  getCurrentUser: () => ({
    id: session.user.id,
    name: session.user.name,
    avatarUrl: session.user.avatarUrl,
  }),
  mentions: {
    search: (query, signal) => directory.searchUsers(query, { signal }),
  },
  can: ({ action, target, user }) => permissions.can(action, target, user),
  excel: { includeNotesSheet: true },
};
```

`getRowId` is required. It must be pure, stable, and globally unique across body and pinned row stores. A visual row index is not a valid ID. Duplicate visual presentations of the same authored row should resolve to the same ID; synthetic group and subtotal rows should not receive an authored ID.

`getRowLabel` is optional and controls the human-readable value displayed in a note title. Use it to bind a field such as `status`; the stable `getRowId` value is never shown in the popover.

The bundled in-memory adapter is a reference implementation for demos and tests. Production applications should implement `GridNoteStorageAdapter` against their API. Bulk `loadSummaries()` responses contain marker metadata and a 120-character excerpt only. Full bodies come from `getNote()`, while version bodies are paged through `listVersions()`.

Set `GridNoteUser.avatarUrl` on authors and users returned by the mention directory to show their image beside their name in note metadata and mention suggestions. If an image cannot load, the plugin retains an accessible initials avatar, using `GridNoteUser.color` when supplied.

## Interaction

- Open the row context menu for **Add cell note** or **Add row note**.
- Press Shift+F2 on the focused cell.
- Select a coloured corner marker without entering cell edit mode.
- Select the row-gutter bar or dot to open the row note and the other cell notes on that row.
- Save with Ctrl+Enter or Command+Enter.

The portalled dialog closes on Escape, outside pointer interaction, or when its virtualized anchor disappears. Unsaved text is retained in local storage and dirty close attempts use `confirmDiscard`.

Selecting **Delete** opens a confirmation panel inside that same dialog. It does not call the browser-native confirmation API.

## Adapter concurrency

`upsert`, `delete`, and `restoreVersion` receive an idempotent mutation ID and expected version. An adapter should throw `GridNoteConflictError` when the current version changed. Restore creates a new current version with `restoredFromVersionId`; it never rewinds or mutates the append-only log.

Empty text is treated as a confirmed delete. Transient saves retry with jittered exponential backoff, pause while the browser is offline, and clear the persisted draft only after success.

## Severity filter and export

The context menu includes a multi-select **Filter by note severity** submenu. Matching is row-wide: a row remains when its row note or any cell note has a selected severity. The plugin applies its own trimmed-state category, so ordinary filters keep their state.

When `ExportExcelPlugin` is also installed and `excel.includeNotesSheet` is true, XLSX output gains a Notes worksheet. It contains one row per current note, including target identity, severity, body, mentions, author, timestamps, and version count. Clipboard and CSV values are unchanged.

## Events

Listen for `gridnotechange`, `gridnotemention`, `gridnoteconflict`, `gridnoteerror`, and `gridnotefilterchange`. Mention events contain only users introduced relative to the previous version, including a restore that reintroduces a mention.

---

# Audit Trail History

URL: https://pro.rv-grid.com/guides/data-manage/audit-history/
Source: src/content/docs/guides/data-manage/audit-history.mdx
Description: Track, review, persist, restore, and export accountable RevoGrid data changes.

`AuditHistoryPlugin` records accountable data-change transactions for spreadsheet-like business workflows. Use it when the grid edits important records and your application needs to answer who changed what, when it changed, and how to recover it.

`HistoryPlugin` owns local undo and redo. `AuditHistoryPlugin` owns the reviewable change log, user metadata, persistence hooks, restore actions, and audit panel. Audit History automatically reuses an existing `HistoryPlugin` or installs one when needed; use `grid.history` when you need to configure History behavior.

## What To Try

The demo is wired like a production audit surface: edit cells, select a changed cell, filter the history, export records, and restore previous values from the panel.

    Change a cell and watch the panel add a timestamped record with user and before/after value details.

    Hover a marked cell to see the latest change summary while keeping the full audit trail in the panel.

    Click a cell or row to switch between focused cell history, row history, and full-grid history.

    Use restore actions to roll back a cell, row snapshot, or transaction while recording the restore itself.

## Why Use It

When users edit operational data, the final cell value is not enough. Audit history keeps the context around each change so business users, admins, and support teams can review the full lifecycle of a value.

    Record the current user, timestamp, action type, row identity, changed column, previous value, and new value.

    Group paste and range-edit operations into one transaction instead of treating every changed cell as an unrelated record.

    Restore a single cell, a row snapshot, or a complete transaction after accidental edits.

    Keep records in memory, browser `localStorage`, or a custom backend adapter.

## When To Use It

Audit history is useful when RevoGrid edits real business data, not temporary UI state.

    Track changes to orders, invoices, stock levels, delivery statuses, prices, and approvals.

    Review manual adjustments to budgets, forecasts, risk values, and reporting tables.

    Log edits to permissions, limits, subscriptions, account status, and configuration records.

    Explain why a value changed without guessing from the current dataset.

## Basic Setup

### Cell Change Indicators

The Audit History examples also mark edited cells directly in the grid. When a cell has recorded changes, the cell shows a small upper-right corner marker aligned to the cell edge. Hovering the cell uses `TooltipPlugin` to show the change count, latest before/after value, user, and timestamp.

This is built on existing plugin APIs: resolve the `AuditHistoryPlugin` instance, call `getCellHistory(rowId, column)` from cell rendering hooks, add tooltip attributes through `cellProperties`, and refresh visible rows when audit events fire.

```ts
const records = auditPlugin.getCellHistory(row.id, column.prop);
```

The marker is only a visual affordance. The audit panel remains the complete review and restore surface.

Use `AuditHistoryPlugin` with `EventManagerPlugin`. The event manager normalizes cell edits, range edits, paste operations, undo, redo, and audit restore replays into edit events the audit plugin and other edit integrations can observe.

Audit History delegates range-shaped restore updates through the existing History replay path. That means cell restore, row replacement restore, and transaction restore emit `beforehistedit`; `EventManagerPlugin` turns that into the normal `gridedit` flow; and `CellFlashPlugin` can flash restored cells from the same edit pipeline. Row insertion and snapshot restore still use direct source/data updates because they are not pure range patches.

1. Import the plugins, panel helper, and config type.

   ```ts
   import {
     AuditHistoryPlugin,
     CellFlashPlugin,
     EventManagerPlugin,
     createLocalStorageAuditHistoryAdapter,
     defineAuditHistoryPanel,
     type AuditHistoryConfig,
   } from '@revolist/revogrid-pro';
   ```

2. Provide the audit config.

   ```ts
   const auditHistory: AuditHistoryConfig = {
     getCurrentUser: () => ({
       id: 'avery-stone',
       name: 'Avery Stone',
       email: 'avery.stone@company.com',
     }),
     rowIdProp: 'id',
     storage: 'memory',
     onAuditRecord(record) {
       // Persist to your API, Supabase, Firebase, PostgreSQL, etc.
       console.log(record);
     },
   };
   ```

3. Register plugins and bind the config directly on the grid.

   ```ts
   grid.plugins = [EventManagerPlugin, AuditHistoryPlugin, CellFlashPlugin];
   grid.auditHistory = auditHistory;
   ```

   `HistoryPlugin` does not need to be listed for normal Audit History restore behavior. Add it explicitly only when the page also has direct History UI controls or you want to control plugin order yourself.

4. Mount the optional review panel.

   ```ts
   const auditPanel = defineAuditHistoryPanel(panelElement, grid, {
     pageSize: 25,
     allowExport: true,
     placement: 'right',
     restoreActions: ['cell', 'row'],
     formatDate: (value, { mode }) =>
       new Intl.DateTimeFormat(undefined, mode === 'day'
         ? { weekday: 'short', month: 'short', day: 'numeric' }
         : { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' }).format(new Date(value)),
     events: {
       beforeExport: ({ format }) => format !== 'json',
       beforeRestore: ({ type }) => type !== 'transaction',
     },
   });

   // Later:
   auditPanel.setPlacement('bottom');
   auditPanel.refresh();
   ```

The plugin still observes `additionalData.auditHistory` for older integrations, but new code should use the direct `grid.auditHistory` property.

## Stable Row Identity

Audit records should point to business records, not visual row positions. Row indexes can change after sorting, filtering, grouping, or lazy loading, so every row should expose a stable identity.

```ts
const rows = [
  { id: 'invoice-123', status: 'Draft', amount: 1200 },
  { id: 'invoice-124', status: 'Paid', amount: 800 },
];

const auditHistory: AuditHistoryConfig = {
  rowIdProp: 'id',
};
```

If your row identity is derived, use `getRowId` instead:

```ts
const auditHistory: AuditHistoryConfig = {
  getRowId: (row) => `${row.tenantId}:${row.invoiceNumber}`,
};
```

## What Gets Recorded

Each top-level audit item is an `AuditRecord`. A record contains one transaction ID and one or more `AuditChange` entries.

```ts
{
  id: 'audit-001',
  transactionId: 'tx-001',
  type: 'cell-change',
  changedAt: '2026-05-08T12:00:00Z',
  changedBy: {
    id: 'avery-stone',
    email: 'avery.stone@company.com',
  },
  changes: [
    {
      id: 'change-001',
      rowId: 'invoice-123',
      rowType: 'rgRow',
      column: 'status',
      oldValue: 'Draft',
      newValue: 'Approved',
    },
  ],
}
```

For a paste operation, the same record can contain many changes:

```ts
{
  transactionId: 'tx-002',
  type: 'bulk-paste',
  changedAt: '2026-05-08T12:05:00Z',
  changedBy: { id: 'avery-stone' },
  changes: [
    {
      id: 'change-002',
      rowId: 'invoice-123',
      rowType: 'rgRow',
      column: 'status',
      oldValue: 'Draft',
      newValue: 'Approved',
    },
    {
      id: 'change-003',
      rowId: 'invoice-124',
      rowType: 'rgRow',
      column: 'status',
      oldValue: 'Draft',
      newValue: 'Rejected',
    },
  ],
}
```

## Storage Options

    Use `storage: 'memory'` for demos, temporary sessions, and test fixtures.

    Use `storage: 'localStorage'` when browser persistence is enough for the workflow.

    Use `storage: 'custom'` with `storageAdapter` when your backend should load, append, save, or clear records.

    Use `storageProviders` to list cache or server providers. Provider loads refresh the panel automatically.

    Use `maxRecords` to bound retained records. The implementation defaults to `1000`.

For production systems, prefer a trusted server provider. If you include several providers, the default is intentionally isolated: the first provider that returns records owns the loaded audit trail, and later providers with records are ignored with a console warning. Set `mergeStorageProviders: true` only when your app deliberately wants to merge records by id across providers.

```ts
const auditHistory: AuditHistoryConfig = {
  getCurrentUser: () => currentUser,
  rowIdProp: 'id',
  storageProviders: [
    {
      async load() {
        const response = await fetch('/api/audit-history');
        return response.json();
      },
      async append(record) {
        await fetch('/api/audit-history', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(record),
        });
      },
      async save(records) {
        await fetch('/api/audit-history', {
          method: 'PUT',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(records),
        });
      },
      async clear() {
        await fetch('/api/audit-history', { method: 'DELETE' });
      },
    },
  ],
};
```

Provider write failures emit `auditerror` but do not block editing. Configuring `storageProviders` together with `storage` or `storageAdapter` shows a console warning because `storageProviders` takes precedence.

When you need a deliberate cache-plus-server merge, opt in explicitly:

```ts
const auditHistory: AuditHistoryConfig = {
  rowIdProp: 'id',
  mergeStorageProviders: true,
  storageProviders: [
    createLocalStorageAuditHistoryAdapter('invoices:audit-history'),
    serverAuditHistoryAdapter,
  ],
};
```

### Provider Load Flow

Provider chains are useful when the user should see cached history quickly while a server-backed provider loads the durable records.

1. The panel mounts and reads the current in-memory records.

2. Storage providers load in order. By default, the first provider that returns records owns the loaded audit trail.

3. The plugin emits `auditrecordsloaded` whenever loaded records are applied.

4. The built-in panel refreshes on `auditrecordsloaded`, `auditrecord`, and `auditrestore`, so async loads and external restore controls stay visible without polling.

Client-side records are excellent for review panels and recovery UX. Compliance-grade audit trails should be written to a trusted backend.

## Privacy And Policy Controls

Production audit logs often need more than raw before/after values. Use `ignoredColumns`, `sanitizeValue`, `getMetadata`, `canRestore`, and `immutable` to align the client behavior with your business rules.

```ts
const auditHistory: AuditHistoryConfig = {
  getCurrentUser: () => currentUser,
  rowIdProp: 'id',
  ignoredColumns: ['internalNotes'],
  sanitizeValue(value, context) {
    if (context.column === 'amount') {
      return '[redacted]';
    }
    return value;
  },
  getMetadata() {
    return {
      workspaceId: currentWorkspace.id,
      requestId: crypto.randomUUID(),
    };
  },
  canRestore({ type }) {
    return currentUser.role === 'admin' && type !== 'transaction';
  },
};
```

Use action-type policy when entire classes of audit records should be included or ignored:

```ts
const auditHistory: AuditHistoryConfig = {
  ignoredActionTypes: ['undo', 'redo'],
  trackedActionTypes: ['cell-change', 'bulk-paste', 'approval-submitted'],
  shouldTrackRecord({ type, changes, metadata }) {
    if (type === 'server-validation' && metadata?.severity === 'debug') {
      return false;
    }
    return changes.length > 0 || type === 'approval-submitted';
  },
};
```

For compliance-style screens where the client must not mutate local audit records, set `immutable: true`. This disables `clear`, `replaceRecords`, and restore actions in the plugin. Server-side immutability should still be enforced by your backend.

```ts
const auditHistory: AuditHistoryConfig = {
  storage: 'custom',
  storageAdapter,
  immutable: true,
};
```

## Review And Restore

The audit panel lets users inspect grid changes without leaving the page. Common review flows include full-grid history, selected-row history, selected-cell history, user filtering, date filtering, action-type filtering, and old/new value comparison.

    Switch between full-grid, selected-row, and selected-cell history without changing the underlying audit records.

    The panel refreshes after new audit records, provider-loaded batches, and restore events from other UI controls.

    `canRestore`, `beforeauditrestore`, and `immutable` let the app decide which restore actions users can run.

    Generate filtered CSV or JSON exports for reporting, support workflows, or backend handoff.

Use the plugin instance when you need audit data in custom UI:

```ts
const plugins = await grid.getPlugins();
const auditHistoryPlugin = plugins.find(
  (plugin) => plugin instanceof AuditHistoryPlugin,
);

const records = auditHistoryPlugin?.getRecords({ userId: 'avery-stone' });
const cellHistory = auditHistoryPlugin?.getCellHistory('invoice-123', 'status');
const rowHistory = auditHistoryPlugin?.getRowHistory('invoice-123');
const lastStatusChange = auditHistoryPlugin?.getLastChange('invoice-123', 'status');
const stats = auditHistoryPlugin?.getStats();
```

Restore helpers return `true` when a restore was applied:

```ts
auditHistoryPlugin?.restoreCell(change);
auditHistoryPlugin?.restoreRow('invoice-123');
auditHistoryPlugin?.restoreTransaction(transactionId);
```

Cell, row replacement, and transaction restores are replayed through `HistoryPlugin.replayChange()`. The restore itself is still recorded as `restore-cell`, `restore-row`, or `restore-transaction`, but the replay is guarded so it does not create a second normal edit record.

Use `recordEvent` for application-driven records that do not come from direct grid editing:

```ts
auditHistoryPlugin?.recordEvent({
  type: 'api-sync',
  changedBy: { id: 'webhook', name: 'Webhook' },
  presentation: {
    source: 'api',
    targetLabel: 'F1:F8',
    detailLabel: '8 cells recalculated',
  },
});
```

Custom action types are plain strings. When the record carries normal cell or row changes, existing restore helpers can use it for revert workflows:

```ts
auditHistoryPlugin?.recordEvent({
  type: 'approval-submitted',
  transactionId: 'approval-42',
  changedBy: currentUser,
  changes: [{
    rowId: 'invoice-123',
    rowIndex: 0,
    rowType: 'rgRow',
    column: 'status',
    oldValue: 'Draft',
    newValue: 'Approved',
  }],
  presentation: {
    source: 'api',
    verb: 'submitted approval',
    targetLabel: 'Invoice 123',
  },
});

auditHistoryPlugin?.restoreTransaction('approval-42');
```

Summary-only custom records are ignored unless you opt in with `allowEmpty: true`.

Use snapshots when users need a named restore point:

```ts
const snapshot = auditHistoryPlugin?.createSnapshot('Before Q4 close');
if (snapshot) {
  auditHistoryPlugin?.restoreSnapshot(snapshot);
}
```

Query helpers return defensive copies, so application code cannot accidentally mutate the plugin's internal audit log.

## Loading And Export

Use `refreshRecords` when your custom storage adapter can load existing records from a backend. A single `storageAdapter` still supports merge-by-id refreshes by default; pass `{ merge: false }` to replace the local set. Provider chains follow the configured provider policy: isolated by default, merged only with `mergeStorageProviders: true`.

```ts
await auditHistoryPlugin?.refreshRecords();
await auditHistoryPlugin?.replaceRecords(serverRecords, { merge: false });
```

Use `exportRecords` for custom export buttons or reporting workflows:

```ts
const csv = auditHistoryPlugin?.exportRecords({
  format: 'csv',
  filter: { actionType: 'bulk-paste' },
  includeMetadata: true,
});

const json = auditHistoryPlugin?.exportRecords({ format: 'json' });
```

Export failures are reported through `auditerror` with phase `export` and return an empty string. That keeps export buttons from crashing the page while still giving your app a single error channel for observability.

The built-in panel docks to the right of the grid by default and can be pinned with `placement: 'left' | 'right' | 'top' | 'bottom' | 'none'`. It includes timeline day grouping, search, user/column/action/date filter chips, scoped cell and row views, pagination, CSV/JSON export controls, hover restore/jump actions, row-click compare mode, optional mini close state, and i18n-friendly labels. Use `restoreActions`, callback-capable `allowCompare`, `formatDate`, and `events` to control panel actions. Pass `tooltips: false` to hide all help icons, or override/hide individual entries with `tooltips: { searchFilter: 'Find a record', clearFilters: false }`. Pass `labels` to rename visible text, placeholders, aria labels, action names, source labels, and dynamic strings such as pagination or selected row/cell summaries.

Listen for `beforeauditrestore` to validate or block a restore, and `auditrestore` after a restore succeeds. New audit records are emitted through `auditrecord`. Storage and hook failures are emitted through `auditerror`; loaded record batches are emitted through `auditrecordsloaded`.

## Production Flow

```txt
User edits grid
  -> EventManagerPlugin normalizes the edit
  -> AuditHistoryPlugin creates an audit transaction
  -> the record is stored locally or sent to your backend
  -> users review changes in the audit panel
  -> admins restore cells, rows, or transactions when needed
  -> range-shaped restores replay through HistoryPlugin and EventManagerPlugin
```

## Summary

`AuditHistoryPlugin` adds accountability to editable RevoGrid applications. Pair it with stable row IDs, a current-user provider, and a trusted persistence path when users edit important operational data.

---

# Autofill

URL: https://pro.rv-grid.com/guides/data-manage/autofill/
Source: src/content/docs/guides/data-manage/autofill.mdx
Description: Fill ranges with spreadsheet-like copy and sequence behavior.

The `AutoFillPlugin` adds spreadsheet-style drag fill to RevoGrid. Users select one
or more cells, drag the fill handle, and RevoGrid fills the target range with the
best matching strategy.

For a richer spreadsheet experience, pair it with `AutoFillPreviewPlugin`. The
preview plugin shows ghost values while the user is dragging, but it does not write
anything to the data store until the drop-time autofill is accepted.

  Select one or more seed cells in the demo below, then drag the fill handle to
  preview the values before releasing the mouse to commit them.

## Usage

```ts
import { AutoFillPlugin, AutoFillPreviewPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [AutoFillPlugin, AutoFillPreviewPlugin];
```

Use only `AutoFillPlugin` when you want values to appear only after mouse release.
Add `AutoFillPreviewPlugin` when users should see the predicted values before they
drop the mouse.

### Formula autofill ownership

`AutoFillPlugin` remains the single owner of fill-handle interaction, strategy
selection, preview matrices, and committed range edits. When `FormulaPlugin` is
used, it automatically installs or reuses that same `AutoFillPlugin` and adds a
result transformer for raw `=...` cells. It does not implement a second fill
pipeline. A host-provided AutoFill instance, including its custom strategies, is
therefore preserved.

The fill handle still requires range selection:

```ts
import {
  AutoFillPreviewPlugin,
  FormulaPlugin,
} from '@revolist/revogrid-pro';

grid.range = true;
grid.plugins = [FormulaPlugin, AutoFillPreviewPlugin];
```

`AutoFillPreviewPlugin` is optional. When present, preview and commit pass through
the same Formula transformer, so the formula shown during the drag is the formula
stored after release.

One row down:

| Seed formula | Filled formula |
| --- | --- |
| `=A1` | `=A2` |
| `=$A$1` | `=$A$1` |
| `=A$1` | `=A$1` |
| `=$A1` | `=$A2` |
| `=SUM(A1:B2,$C1:D$4)` | `=SUM(A2:B3,$C2:D$4)` |

One column right:

| Seed formula | Filled formula |
| --- | --- |
| `=A1` | `=B1` |
| `=$A$1` | `=$A$1` |
| `=A$1` | `=B$1` |
| `=$A1` | `=$A1` |
| `=SUM(A1:B2,$C1:D$4)` | `=SUM(B1:C2,$C1:E$4)` |

Each endpoint of a range moves independently. Quoted and unquoted sheet
qualifiers are retained, so copying `='Product List'!A1:B2` down produces
`='Product List'!A2:B3`. Multi-cell selections tile from the corresponding seed
cell in every direction. Moving a relative coordinate before row 1 or column A
produces `#REF!`.

## Filling formatted cells

Register AutoFill and Event Manager with the formatting plugin when the fill handle
should stretch both values and formatting. Event Manager confirms the accepted range
edit before formatting is applied:

```ts
import {
  AutoFillPlugin,
  AutoFillPreviewPlugin,
  DataGridFormattingPlugin,
  EventManagerPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [
  DataGridFormattingPlugin,
  AutoFillPlugin,
  EventManagerPlugin,
  AutoFillPreviewPlugin,
];
```

The formatting plugin resolves the effective format of every source cell,
including cell-, row-, and column-level formatting, and repeats that format as a
two-dimensional tile over the added cells. Advanced presentations such as Rating,
Progress, Badge, fonts, fills, borders, alignment, and number formats therefore
follow the same fill-handle gesture as the values. Existing source cells are not
rewritten, and formatting is applied only when the unified range edit is accepted.

See [Format Cells: range fill and clipboard](/guides/data-grid/format-cells/#range-fill-formatting)
for formatting ownership and persistence details.

### Crossing Pinned And Main Viewports

Add `MultiRangeSelectionPlugin` when users should be able to drag the autofill
handle from a pinned row or column into the main viewport, or from the main
viewport into a pinned section. Cross-viewport autofill is enabled by default
with multi-range selection.

```ts
import {
  AutoFillPlugin,
  MultiRangeSelectionPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [AutoFillPlugin, MultiRangeSelectionPlugin];
```

Cross-viewport autofill is scoped to visible viewport segments. If the main
viewport is scrolled, the plugin does not treat the pinned section and main data
as one hidden continuous range, and it does not write rows or columns behind the
scroll gap. The final selection is represented as multiple ranges so each visible
source and target segment remains explicit.

Disable the cross-viewport drag integration while keeping multi-range selection
enabled with:

```ts
grid.multiRangeSelection = { crossViewportAutofill: false };
```

## What Users See

1. Select a source cell or range.
2. Drag the small autofill handle from the selection corner.
3. Ghost values appear in the temporary target range when preview is enabled.
4. Release the mouse to commit the same values that were previewed.
5. Pressing escape, clearing the temporary range, or changing the source clears the preview.

Existing selected source cells are not visually replaced by preview values. The
preview only appears in the autofill target range.

## Built-In Strategies

AutoFill strategies are checked from most specific to most general. If no sequence
strategy can safely infer a pattern, RevoGrid repeats the selected values with copy
fallback.

| Strategy | User behavior | Example |
| --- | --- | --- |
| Linear numeric sequence | Continues a selected numeric interval. | `1, 3` -> `5, 7` |
| Single numeric step | Extends one selected number by `+1`. | `10` -> `11, 12` |
| Number in text | Continues labels with embedded numbers and preserves padding. | `INV-099` -> `INV-100`; `1st Floor` -> `2nd Floor` |
| Weekday names | Continues English weekday labels and wraps the week. | `Mon, Tue` -> `Wed` |
| Month names | Continues English month labels and wraps the year. | `Jan, Feb` -> `Mar` |
| Date unit sequence | Continues daily, weekly, monthly, quarterly, and yearly date intervals. | `2024-12-04, 2024-12-05` -> `2024-12-06` |
| Time sequence | Continues `HH:mm` and `HH:mm:ss` time intervals. | `09:00, 09:30` -> `10:00` |
| Boolean cycle | Repeats boolean-like toggle pairs. | `Yes, No` -> `Yes, No` |
| Text suffix sequence | Keeps compatibility with existing `Book 1`, `Book 2` fills. | `Book 1, Book 2` -> `Book 3` |
| Copy fallback | Repeats selected values when the pattern is plain or ambiguous. | `Draft, Approved` -> `Draft, Approved` |

## Strategy Notes

### Numeric Values

Select two or more numeric cells to preserve an interval. For example, selecting
`100` and `110` continues with `120`, `130`, and so on. Selecting one numeric cell
uses a simple `+1` sequence.

### Text With Numbers

AutoFill understands numbers inside labels, not only numbers at the end. It keeps
the visible text shape stable when the selected values are consistent.

```txt
Item 001 -> Item 002
INV-099 -> INV-100
1st Floor, 2nd Floor -> 3rd Floor
```

If labels use different prefixes, suffixes, or number formats, RevoGrid falls back
to copying the selected values instead of guessing.

### Dates And Times

Dates preserve the selected visible format when possible:

```txt
2024-12-04 -> 2024-12-05
2024/12/04 -> 2024/12/05
12/04/2024 -> 12/05/2024
```

Monthly, quarterly, and yearly fills are inferred from consistent month steps. Time
fills preserve `HH:mm` or `HH:mm:ss` and wrap across midnight.

### Weekdays And Months

Weekday and month strategies support English full names and three-letter labels.
The output format follows the source format:

```txt
Monday, Tuesday -> Wednesday
Mon, Tue -> Wed
January, February -> March
Jan, Feb -> Mar
```

### Boolean-Like Values

Boolean cycle supports `true/false`, `yes/no`, and `on/off`. String pairs require
both values in the selected range, so a single `Yes` cell is copied instead of
turning into an inferred toggle.

### Copy Fallback

Copy fallback is intentional. It handles plain text, mixed values, and unsupported
patterns by repeating the selected values exactly. This keeps AutoFill predictable
for status columns and other business data where guessing a sequence would be
surprising.

## Custom Strategies

Developers can register custom strategies for domain-specific patterns. Custom
strategies run before copy fallback, so they can override generic copy behavior.

```ts
import type { AutoFillStrategy } from '@revolist/revogrid-pro';

const priorityStrategy: AutoFillStrategy = (selectedData, direction, targetRange, context) => {
  // Return a matrix when your strategy supports the selection.
  // Return null to let the next strategy try.
  return null;
};

AutoFillPlugin.registerStrategy(priorityStrategy);
```

Return `null` when a strategy is not confident. Preview and final apply share the
same strategy list, so a custom strategy automatically affects both behaviors.

---

# Collaborative Editing

URL: https://pro.rv-grid.com/guides/data-manage/collaborative-editing/
Source: src/content/docs/guides/data-manage/collaborative-editing.mdx
Description: Learn how to add shared cell editing, presence, pending review, permissions, server commits, conflicts, and audit attribution to RevoGrid Pro.

Collaborative Editing is separately distributed to keep Yjs out of applications
that do not need it. Trial users should install
`@revolist/revogrid-collaborative-editing-trial` alongside
`@revolist/rv-pro-trial`. Collaborative Presence remains available from the
main Pro trial package.

`CollaborativeEditingPlugin` lets several users work on the same grid data at the same time. One user edits a cell, the edit is written into a shared Yjs document, and the other connected grids can receive the same change.

You do not need to know Yjs before using the plugin. Think of Yjs as the shared notebook where the browser stores collaborative changes. RevoGrid still renders the grid, your app still owns users and business rules, and your backend still decides what is finally saved.

Install collaborative editing as a separate package so Yjs is only loaded by applications that need realtime editing:

```sh
pnpm add @revolist/revogrid-collaborative-editing @revolist/revogrid-pro
```

Trial equivalent:

```sh
pnpm add @revolist/revogrid-collaborative-editing-trial @revolist/rv-pro-trial
```

## Live Demo: Split Collaborative Editing

The demo catalog includes a complete split-view example with two users editing the same shared document. Open it when you want to see the moving parts together instead of reading isolated snippets.

[Open the Collaborative Editing demo](https://demo.rv-grid.com/collaborative-editing/ts)

The demo shows:

- two grids on the same page using one collaborative document;
- Avery and Grace rendered with matching presence colors and avatars;
- live remote focus and selection markers through `CollaborativePresencePlugin`;
- the first grid with the `Task` column pinned while the second grid keeps it unpinned;
- `EventManagerPlugin` with `applyEventsToSource: false`;
- an in-memory presence transport that stands in for a realtime provider;
- a mock `commitAdapter` that logs server commits so the backend boundary is visible.

## The Mental Model

Collaborative editing has a few moving parts. The names are technical, but the ideas are simple.

    A user changes a cell. `EventManagerPlugin` normalizes that edit so collaborative editing sees cell edits, paste, range edits, undo, and redo through one pipeline.

    Presence means "where are the other users looking or editing?" Add `CollaborativePresencePlugin` when you want remote cursors, ranges, colors, and labels.

    In review mode, edits stay pending until your UI commits or discards them. This is useful when a manager, workflow, or server must approve changes.

    A commit is the point where your app asks the backend to accept changes. The plugin calls your `commitAdapter`; your backend can accept, rewrite, or reject each edit.

    A conflict happens when users edit the same row and column concurrently. The default policy keeps the change pending so your UI can show a decision.

    Audit records explain who changed what and when. Add `AuditHistoryPlugin` when committed collaborative edits should be logged.

The plugin coordinates grid edits, shared Yjs state, pending changes, conflicts, presence bridging, and audit integration. Your app still owns authentication, user identity, backend persistence, authorization, and the review UI.

## Beginner Setup

Start with the smallest local setup, then add the pieces your product needs.

### 1. Minimal Local Grid

This example needs no server and no transport. It is useful for learning the plugin and verifying that local cell edits enter the collaborative pipeline.

1. Import the base plugins.

   ```ts
   import {
     EventManagerPlugin,
   } from '@revolist/revogrid-pro';

   import {
     CollaborativeEditingPlugin,
     type CollaborativeEditingConfig,
   } from '@revolist/revogrid-collaborative-editing';
   ```

2. Give every row a stable id.

   ```ts
   const rows = [
     { id: 'task-1', task: 'Revenue forecast', owner: 'Avery', status: 'Draft' },
     { id: 'task-2', task: 'Vendor renewal', owner: 'Mina', status: 'Review' },
     { id: 'task-3', task: 'Headcount plan', owner: 'Jon', status: 'Approved' },
   ];

   const columns = [
     { prop: 'task', name: 'Task' },
     { prop: 'owner', name: 'Owner' },
     { prop: 'status', name: 'Status' },
   ];
   ```

3. Register plugins and bind configuration.

   ```ts
   const grid = document.querySelector('revo-grid')!;

   grid.columns = columns;
   grid.source = rows;
   grid.plugins = [
     EventManagerPlugin,
     CollaborativeEditingPlugin,
   ];

   grid.eventManager = { applyEventsToSource: false };

   const collaborativeEditing: CollaborativeEditingConfig = {
     documentId: 'local-learning-session',
     user: {
       id: 'avery',
       name: 'Avery Stone',
       color: '#2563eb',
       permissionLevel: 'editor',
     },
     rowIdProp: 'id',
   };

   grid.collaborativeEditing = collaborativeEditing;
   ```

`grid.eventManager = { applyEventsToSource: false }` is important. It lets collaborative editing own how edits are applied, reviewed, committed, or rolled back instead of letting each raw grid edit immediately mutate source data twice.

### 2. Two Grids On The Same Page

Use a shared Yjs document when two grids on one page should represent the same collaborative session. This is the easiest way to understand how two users share edits before connecting a real transport.

```ts
import * as Y from 'yjs';
import {
  CollaborativePresencePlugin,
  EventManagerPlugin,
} from '@revolist/revogrid-pro';
import {
  CollaborativeEditingPlugin,
} from '@revolist/revogrid-collaborative-editing';

const doc = new Y.Doc();
const plugins = [
  EventManagerPlugin,
  CollaborativePresencePlugin,
  CollaborativeEditingPlugin,
];

function configureGrid(grid: HTMLRevoGridElement, user: { id: string; name: string; color: string }) {
  grid.columns = columns;
  grid.source = rows.map(row => ({ ...row }));
  grid.plugins = plugins;
  grid.eventManager = { applyEventsToSource: false };
  grid.collaborativeEditing = {
    documentId: 'same-page-demo',
    user,
    rowIdProp: 'id',
    doc,
    presence: {
      enabled: true,
      showLabels: true,
      staleAfterMs: 15_000,
    },
  };
}

configureGrid(gridA, { id: 'avery', name: 'Avery Stone', color: '#2563eb' });
configureGrid(gridB, { id: 'grace', name: 'Grace Hopper', color: '#16a34a' });
```

Both grids use the same `documentId` and the same `doc`, so they are intentionally part of the same collaborative document.

`CollaborativeEditingPlugin` maps awareness state into presence users. `CollaborativePresencePlugin` renders those users as colored focus and range markers. For deeper cursor and range behavior, read [Collaborative Presence](/guides/data-manage/collaborative-presence/).

### 3. Review Mode With Pending Changes

Use review mode when users should make changes locally, inspect the pending list, then commit or discard those changes from your UI.

```ts
grid.collaborativeEditing = {
  documentId: `budget:${budgetId}`,
  user: currentUser,
  rowIdProp: 'id',
  mode: 'review',
  conflictPolicy: 'manual',
};
```

Read the plugin instance when your UI needs pending changes or review actions.

```ts
const plugins = await grid.getPlugins();
const collaborative = plugins.find(
  plugin => plugin instanceof CollaborativeEditingPlugin,
) as CollaborativeEditingPlugin | undefined;

const pending = collaborative?.getPendingChanges() ?? [];

await collaborative?.commitPendingChanges(pending.map(change => change.id));
collaborative?.discardPendingChanges();
```

Review mode is a good default for finance, procurement, admin, support, planning, and any workflow where users should not silently overwrite each other.

### 4. Commit Changes To A Server

Use `commitAdapter` when your backend must validate, persist, approve, reject, version, or rewrite edits.

```ts
grid.collaborativeEditing = {
  documentId: `forecast:${forecastId}`,
  user: currentUser,
  rowIdProp: 'id',
  mode: 'autoCommit',
  commitAdapter: {
    async commit(changes, context) {
      const response = await fetch(`/api/forecasts/${forecastId}/changes`, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({
          documentId: context.documentId,
          user: context.user,
          changes,
        }),
      });

      return response.json();
    },
  },
};
```

The response should describe which changes were committed and which were rejected. Rejected changes are rolled back to their previous local value.

```ts
[
  { id: 'change-1', status: 'committed' },
  { id: 'change-2', status: 'rejected', reason: 'Budget is locked' },
]
```

### 5. Add Business Permissions

Use `permissions.canEditCell` for user, role, row, tenant, or workflow-specific edit rules.

```ts
grid.collaborativeEditing = {
  documentId: `pricing:${priceBookId}`,
  user: {
    id: currentUser.id,
    name: currentUser.name,
    roles: currentUser.roles,
    permissionLevel: currentUser.permissionLevel,
  },
  rowIdProp: 'sku',
  permissions: {
    canEditCell({ user, row, prop, newValue }) {
      if (row?.locked) return false;
      if (prop === 'approvedPrice') return user.roles?.includes('pricing-admin') ?? false;
      if (prop === 'discount' && Number(newValue) > 0.2) return user.permissionLevel === 'manager';
      return user.permissionLevel === 'editor';
    },
  },
};
```

Client permissions improve UX and prevent obvious invalid edits early. They are not a security boundary; repeat important checks in your backend through `commitAdapter`.

## Connect More Than One Browser

A shared local `Y.Doc` is enough for demos and same-page tests. For real users in different browsers, add a transport.

```ts
import {
  createYjsWebSocketTransport,
} from '@revolist/revogrid-collaborative-editing';

grid.collaborativeEditing = {
  documentId: `project:${projectId}:tasks`,
  user: currentUser,
  rowIdProp: 'id',
  transport: createYjsWebSocketTransport({
    url: 'wss://collaboration.example.com',
    params: { token: sessionToken },
  }),
};
```

Use WebSocket when your product needs a controlled server, authentication, observability, and enterprise networking. Use WebRTC for peer-to-peer collaboration where your deployment can support signaling and peer connectivity. Use a custom transport when your application already wraps Yjs providers.

## Listen For Conflicts

The default `conflictPolicy` is `manual`. When two users edit the same row and column concurrently, the plugin emits `collaborativeconflict` and keeps the local change pending.

```ts
grid.addEventListener('collaborativeconflict', (event) => {
  const conflict = event.detail;

  showConflictDialog({
    rowId: conflict.local.rowId,
    column: conflict.local.prop,
    localValue: conflict.local.newValue,
    remoteValue: conflict.remoteValue,
    user: conflict.remoteUser,
  });
});
```

Set `conflictPolicy: 'lastWriteWins'` only for low-risk cells such as notes, draft comments, or transient planning values where silent overwrite is acceptable.

## Configuration Reference

### Business-Critical Properties

| Property | Type | Default | First-time guidance |
|:--|:--|:--|:--|
| `documentId` | `string` | `'revogrid-collaborative-document'` | The shared session name. Use the same value for every user editing the same business object, such as `budget:2026` or `project:alpha:tasks`. |
| `user` | `CollaborativeEditingUser` | `undefined` | The current editor. Provide at least `id` and `name`; without a user, local edits are ignored because edits must be attributable. |
| `rowIdProp` | `string` | `'id'` | The row field that uniquely identifies the business record. Use your real primary key, such as `invoiceId`, `sku`, `taskId`, or `employeeId`. |
| `commitAdapter` | `CollaborativeEditingCommitAdapter` | `undefined` | Your backend boundary. Add it when changes must be saved, validated, approved, rejected, versioned, or audited by a server. |
| `permissions` | `CollaborativeEditingPermissions` | `undefined` | Client-side business rules. Use this for role checks, locked rows, approval status, tenant rules, or field-level permissions. |
| `audit` | `CollaborativeEditingAuditConfig \| boolean` | enabled | Audit integration. Keep it enabled for operational, financial, admin, support, or regulated workflows. |
| `conflictPolicy` | `'manual' \| 'lastWriteWins'` | `'manual'` | How same-cell concurrent edits are handled. Keep `manual` for business data. |

### Runtime And Collaboration Properties

| Property | Type | Default | First-time guidance |
|:--|:--|:--|:--|
| `enabled` | `boolean` | `true` | Turns collaboration on or off without changing the plugin list. Useful for feature flags or read-only screens. |
| `doc` | `Y.Doc` | new isolated document | Pass this when your app owns the Yjs document or when several grids should share one local document. |
| `mode` | `'autoCommit' \| 'review'` | `'autoCommit'` | Use `autoCommit` for immediate server reconciliation. Use `review` when users need commit and discard buttons. |
| `transport` | `CollaborativeEditingTransport` | `undefined` | Connects different browsers. Without transport, collaboration is local to the current page or shared `doc`. |
| `presence` | `{ enabled, showLabels, staleAfterMs }` | enabled, labels shown | Controls the bridge into `CollaborativePresencePlugin`. Use it when users should see who is focused or editing. |

### `user`

`user` tells the plugin who is editing. It is used for presence labels, permission checks, commit requests, audit records, and conflict metadata.

```ts
const user = {
  id: 'u-123',
  name: 'Avery Stone',
  email: 'avery@example.com',
  initials: 'AS',
  color: '#2563eb',
  roles: ['planner', 'budget-editor'],
  permissionLevel: 'editor',
};
```

Use a stable application user id. Avoid session ids or display names as `id`, because audit history and server reconciliation need durable identity.

### `documentId`

`documentId` means "which shared document is this grid editing?"

```ts
documentId: `forecast:${forecastId}`
documentId: `project:${projectId}:schedule`
documentId: `tenant:${tenantId}:price-book:${priceBookId}`
```

Use the same `documentId` for every client editing the same dataset. Use a different `documentId` when two grids should not share edits or presence.

### `rowIdProp`

Collaborative editing stores cell changes by stable row identity. If `rowIdProp` is wrong, edits may apply to the wrong row after sorting or filtering.

```ts
const rows = [
  { invoiceId: 'INV-1001', status: 'Draft', total: 1200 },
];

grid.collaborativeEditing = {
  documentId: 'invoices:open',
  user,
  rowIdProp: 'invoiceId',
};
```

Use `id` only when every row really has a durable `id`. For generated, aggregated, or temporary rows, provide a stable key before enabling collaboration.

### `commitAdapter`

`commitAdapter` means "ask my backend whether these edits are accepted."

```ts
commitAdapter: {
  async commit(changes, context) {
    const response = await fetch('/api/reconcile-grid-changes', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({
        documentId: context.documentId,
        user: context.user,
        changes,
      }),
    });

    return response.json() as Promise<Array<{
      id: string;
      status: 'committed' | 'rejected';
      value?: unknown;
      reason?: string;
      metadata?: Record<string, unknown>;
    }>>;
  },
}
```

Return `committed` when the server accepts a change. Return `rejected` when validation, permissions, workflow status, version checks, or business rules fail.

### `permissions`

`permissions.canEditCell` runs before a local edit is accepted. It complements RevoGrid's `readonly` support:

- use column `readonly` for static UI-level rules
- use `permissions.canEditCell` for user, row, tenant, or workflow-specific rules

```ts
permissions: {
  canEditCell({ user, row, prop, newValue }) {
    if (row?.approvalStatus === 'Approved') return false;
    if (prop === 'budgetLimit') return user.roles?.includes('finance-admin') ?? false;
    if (prop === 'discount' && Number(newValue) > 0.2) return user.permissionLevel === 'manager';
    return user.permissionLevel === 'editor';
  },
}
```

### `audit`

When `AuditHistoryPlugin` is registered, collaboration commits are recorded as audit events by default.

```ts
audit: {
  enabled: true,
  actionType: 'collaborative-price-change',
  source: 'api',
}
```

Disable audit only for temporary or non-business data:

```ts
audit: false
```

## Commit Modes

Use `mode: 'autoCommit'` when the server should accept or reject each edit as soon as it is made.

Use `mode: 'review'` when users need an explicit commit/discard workflow. In review mode, edits are optimistic locally and remain in `getPendingChanges()` until the host commits or discards them through the plugin instance.

## Audit Trail

When `AuditHistoryPlugin` is registered and `audit.enabled !== false`, committed collaborative changes call `AuditHistoryPlugin.recordEvent()` with:

- `type: 'collaborative-edit'`
- current collaborative user
- transaction id
- row id, row index, column, old value, and new value
- collaborative metadata and document id

Use the Audit History storage hooks to persist those records to your backend.

## Common First-Time Mistakes

| Mistake | What happens | Fix |
|:--|:--|:--|
| Missing `EventManagerPlugin` | Edits do not enter the normalized collaborative edit pipeline. | Register `EventManagerPlugin` before `CollaborativeEditingPlugin`. |
| Missing `user` | Local edits are ignored because the plugin cannot attribute them. | Pass a stable `user` with at least `id` and `name`. |
| Missing or unstable `rowIdProp` | Edits can target the wrong row after sorting, filtering, or reordering. | Use a durable business id field. |
| Different `documentId` values | Users do not share the same collaborative document. | Use one stable `documentId` for every client in the same session. |
| Expecting automatic persistence | Local/Yjs state changes, but your backend is not updated. | Add a `commitAdapter`. |
| Expecting visible labels without presence plugin | Editing works, but remote cursors and ranges do not render. | Add `CollaborativePresencePlugin` and enable `presence`. |

## What To Read Next

- [Collaborative Presence](/guides/data-manage/collaborative-presence/) for remote cursors, selections, labels, stale users, and pinned-area behavior.
- [Audit Trail History](/guides/data-manage/audit-history/) for persisted change logs and restore workflows.
- [Event Manager](/guides/data-manage/event-manager-explanation/) for the edit event pipeline collaborative editing uses.

---

# Collaborative Presence

URL: https://pro.rv-grid.com/guides/data-manage/collaborative-presence/
Source: src/content/docs/guides/data-manage/collaborative-presence.mdx
Description: Render remote collaborator focus cells, selected ranges, labels, colors, stale-user cleanup, and source-index row patches in RevoGrid Pro.

`CollaborativePresencePlugin` shows where other users are looking or editing inside the grid. It renders colored focus rectangles, selected ranges, avatars, and user labels without changing the local user's focus, selection, editor, data history, or keyboard state.

Use it by itself when your app already has presence data, or use it with [Collaborative Editing](/guides/data-manage/collaborative-editing/) when Yjs awareness should drive remote cursors and ranges automatically.

## What It Does

    Show the single cell another user is focused on.

    Show another user's selected or active range.

    Render initials, names, and stable colors so users can identify each other quickly.

    Resolve marker positions from RevoGrid viewport state, including pinned columns, instead of querying physical cell DOM nodes.

Presence markers are overlays. They do not move local focus, create local selections, open editors, or persist data by themselves.

## Basic Setup

1. Import and register the plugin.

   ```ts
   import {
     CollaborativePresencePlugin,
   } from '@revolist/revogrid-pro';

   grid.plugins = [
     CollaborativePresencePlugin,
   ];
   ```

2. Provide users through `grid.collaborativePresence`.

   ```ts
   grid.collaborativePresence = {
     users: [
       {
         id: 'avery',
         name: 'Avery Stone',
         initials: 'AS',
         color: '#2563eb',
         activity: 'editing',
         focus: { x: 0, y: 1 },
         range: { x: 0, y: 1, x1: 2, y1: 3 },
         lastActiveAt: Date.now(),
       },
       {
         id: 'grace',
         name: 'Grace Hopper',
         initials: 'GH',
         color: '#16a34a',
         activity: 'viewing',
         focus: { x: 1, y: 0 },
         lastActiveAt: Date.now(),
       },
     ],
   };
   ```

The plugin observes `grid.collaborativePresence`, `grid['collaborative-presence']`, and `additionalData.collaborativePresence`.

## Cell And Range Coordinates

Presence coordinates use grid source indexes:

- `x` is the source column index in the target column area.
- `y` is the source row index in the target row area.
- `x1` and `y1` are the opposite range corner.
- `colType` defaults to `'rgCol'`.
- `rowType` defaults to `'rgRow'`.

```ts
grid.collaborativePresence = {
  users: [
    {
      id: 'avery',
      name: 'Avery Stone',
      color: '#2563eb',
      focus: { x: 0, y: 2 },
      range: { x: 0, y: 2, x1: 3, y1: 4 },
    },
  ],
};
```

For pinned columns, pass the matching column type. This keeps the marker in the pinned viewport instead of the main viewport.

```ts
grid.collaborativePresence = {
  users: [
    {
      id: 'grace',
      name: 'Grace Hopper',
      color: '#16a34a',
      focus: {
        x: 0,
        y: 1,
        colType: 'colPinStart',
        rowType: 'rgRow',
      },
    },
  ],
};
```

The plugin resolves source indexes through RevoGrid stores and viewport structures. This is important when sorting, filtering, pinning, or virtualization changes which physical cells are mounted.

## Configuration Reference

| Property | Type | Default | What it controls |
|:--|:--|:--|:--|
| `enabled` | `boolean` | `true` | Turns all presence markers on or off without removing the plugin. |
| `showLabels` | `boolean` | `true` | Shows or hides user name labels. Focus and range colors still render when labels are hidden. |
| `staleAfterMs` | `number` | `undefined` | Hides users whose `lastActiveAt` is older than the configured timeout. |
| `users` | `CollaborativePresenceUser[]` | `[]` | The remote users to render. Each user can provide `focus`, `range`, or both. |
| `remoteEdits` | `CollaborativePresenceRowPatch[]` | `[]` | Optional source-row patches for remote data changes that should update grid rows without resetting focus or selection. |

## User Shape

```ts
type CollaborativePresenceUser = {
  /**
   * Stable user id used to distinguish one collaborator from another.
   * Use your application user id, not a temporary session id or display name.
   */
  id: string;

  /**
   * Human-readable name shown in the presence label when `showLabels` is true.
   */
  name: string;

  /**
   * Optional short avatar text. If omitted, the label can derive initials from `name`.
   */
  initials?: string;

  /**
   * Optional marker color used for focus borders, range overlays, avatar, and label.
   * Keep this stable per user so collaborators are easy to recognize.
   */
  color?: string;

  /**
   * Optional activity state for your own presence model.
   * The plugin accepts viewing, editing, and idle states.
   */
  activity?: 'viewing' | 'editing' | 'idle';

  /**
   * Optional focused cell for this user.
   * `x` and `y` are source indexes in the specified column and row areas.
   * Set this to `null` when the user has no active focus to render.
   */
  focus?: {
    /** Source column index inside `colType`. */
    x: number;

    /** Source row index inside `rowType`. */
    y: number;

    /**
     * Column area that owns the focused cell.
     * Defaults to `rgCol`; use pinned column types for pinned cells.
     */
    colType?: 'colPinStart' | 'rgCol' | 'colPinEnd';

    /**
     * Row area that owns the focused cell.
     * Defaults to `rgRow`; use pinned row types for pinned rows.
     */
    rowType?: 'rgRow' | 'rowPinStart' | 'rowPinEnd';
  } | null;

  /**
   * Optional selected or active range for this user.
   * `x`, `y` and `x1`, `y1` are opposite corners in source indexes.
   * Set this to `null` when the user has no range to render.
   */
  range?: {
    /** Source column index for one range corner. */
    x: number;

    /** Source row index for one range corner. */
    y: number;

    /** Source column index for the opposite range corner. */
    x1: number;

    /** Source row index for the opposite range corner. */
    y1: number;

    /**
     * Column area that owns the range.
     * Defaults to `rgCol`; use pinned column types for pinned ranges.
     */
    colType?: 'colPinStart' | 'rgCol' | 'colPinEnd';

    /**
     * Row area that owns the range.
     * Defaults to `rgRow`; use pinned row types for pinned ranges.
     */
    rowType?: 'rgRow' | 'rowPinStart' | 'rowPinEnd';
  } | null;

  /**
   * Last known activity time for stale-user cleanup.
   * Accepts a timestamp, date string, or Date object.
   * Used only when `staleAfterMs` is configured.
   */
  lastActiveAt?: number | string | Date;
};
```

Use stable `id` values and consistent colors so the same person looks the same across grids and sessions.

## Labels And Stale Users

Use `showLabels: false` for dense grids where full labels would cover too much content.

```ts
grid.collaborativePresence = {
  showLabels: false,
  users,
};
```

Use `staleAfterMs` to hide users who disconnect or stop sending presence updates.

```ts
grid.collaborativePresence = {
  staleAfterMs: 15_000,
  users: remoteUsers.map(user => ({
    ...user,
    lastActiveAt: user.lastSeenAt,
  })),
};
```

## Remote Row Patches

`remoteEdits` can apply remote row updates directly into the RevoGrid data store without resetting the full source or disturbing the local editor state.

```ts
grid.collaborativePresence = {
  remoteEdits: [
    {
      rowIndex: 2,
      rowType: 'rgRow',
      data: {
        status: 'Approved',
        owner: 'Grace',
      },
    },
  ],
  users,
};
```

`rowIndex` is a source row index, not the currently visible row position. That keeps patches stable when the grid is sorted or filtered.

## With Collaborative Editing

When `CollaborativeEditingPlugin` has presence enabled, it maps Yjs awareness state into `CollaborativePresencePlugin`.

```ts
grid.plugins = [
  EventManagerPlugin,
  CollaborativePresencePlugin,
  CollaborativeEditingPlugin,
];

grid.collaborativeEditing = {
  documentId: `budget:${budgetId}`,
  user: currentUser,
  rowIdProp: 'id',
  presence: {
    enabled: true,
    showLabels: true,
    staleAfterMs: 15_000,
  },
};
```

Use direct `grid.collaborativePresence` updates when your app owns the realtime presence source. Use collaborative editing presence when Yjs awareness owns the realtime presence source.

---

# Event Manager

URL: https://pro.rv-grid.com/guides/data-manage/event-manager-explanation/
Source: src/content/docs/guides/data-manage/event-manager-explanation.mdx
Description: Get comprehensive documentation on the event management.

Learn how to handle, customize, and optimize events to create complex interactions and workflows with the Event Manager Plugin for RevoGrid. The main purpose of this plugin is to collect and dispatch edit events in one centralized location, simplifying event management.

The Event Manager Plugin aggregates various editing events into a single event, `gridedit`. This approach reduces the complexity of handling multiple event types individually, such as `clipboardrangepaste`, `beforeedit`, and `beforerangeedit`. By using the Event Manager Plugin, you can catch all these events through one unified event, making it a robust starting point for building your custom event management system.

## Key Features

- **Centralized Event Handling:** Collects multiple edit events into a single `gridedit` event.
- **Simplified Event Management:** Reduces the need to manage numerous event types individually.
- **Customizable Workflows:** Provides a foundation to create complex interactions and workflows.

## Unified payload

`data`, `previousData`, and `models` always use RevoGrid's normal numeric-row
and field-patch format. Feature plugins can add semantic information through
the ordered `domainChanges` array without changing that grid-data contract.
Replay-only feature state is kept separately in keyed `history` snapshots, so
internal undo data never appears as a synthetic grid field.

For example, a Kanban move can expose a normal `status` patch in `data`, identify
the operation as a card move in `domainChanges`, and keep its compact undo state
in `history`.

```ts
grid.addEventListener('gridedit', (event) => {
  const { data, previousData, domainChanges = [], eventTypes } = event.detail;

  // Common RevoGrid patches, regardless of which feature produced the edit.
  saveGridChanges({ data, previousData });

  // Optional feature semantics. One transaction may contain several entries.
  for (const change of domainChanges) {
    if (change.type === 'kanban-card') {
      const { action, cardId, previousCard, card } = change.detail;
      saveCardChange({ action, cardId, previousCard, card });
    }
  }

  if (eventTypes.includes('kanban-card-change')) {
    refreshKanbanSummary();
  }
});
```

The currently exported domain types and tags are:

| Feature | Domain type | `eventTypes` tag |
| --- | --- | --- |
| Gantt task | `gantt-task` | `gantt-task-change` |
| Gantt dependency | `gantt-dependency` | `gantt-dependency-change` |
| Gantt assignment | `gantt-assignment` | `gantt-assignment-change` |
| Kanban card | `kanban-card` | `kanban-card-change` |
| Scheduler event | `event-scheduler-event` | `event-scheduler-event-change` |

Domain changes are ordered. Bulk operations and scheduling cascades include all
affected entities, not only the item directly manipulated. Structural changes
can have no safe numeric row patch, so `data` may be empty while
`domainChanges` still fully describes the committed operation.

Use feature-specific types when you only consume one producer:

```ts
import type { KanbanEventManagerEvent } from '@revolist/kanban';

interface MyCard {
  id: string;
  status: string;
}

grid.addEventListener('gridedit', (event) => {
  const detail = event.detail as KanbanEventManagerEvent<MyCard>;
  detail.domainChanges?.forEach(({ detail: cardChange }) => {
    console.log(cardChange.action, cardChange.cardId);
  });
});
```

### Cancellation and source ownership

For ordinary grid edits, EventManager owns applying `data`; canceling
`gridedit` prevents that write. A feature event with
`sourceMutation: 'producer'` was already committed by Gantt, Kanban, or
Scheduler. Its `gridedit` is therefore observational and canceling it does not
roll the mutation back. Use the producer's cancelable `before` event for
validation instead.

When collection is enabled, consecutive compatible changes become one ordered
`gridedit` transaction and one undo step:

```ts
grid.eventManager = {
  collectEvents: true,
  collectEventsDelay: 100,
};
```

The transaction preserves the earliest previous state and latest committed
state for each entity. Do not rely on exact equality of `eventTypes`; use
`eventTypes.includes(...)` because a transaction may contain several tags.

Plugins that submit producer-owned history must also handle `beforehistoryedit`.
After successfully restoring their state, they call
`markEventManagerHistoryReplayHandled(detail, ownedHistoryKeys)` and cancel
that replay event.
This keeps malformed or unavailable producer history on its current undo/redo
stack instead of silently consuming it. Applications normally do not need to
read `history`; it is replay state owned by `HistoryPlugin` and the producer.

## Implementation

Here's a brief overview of how to implement the Event Manager Plugin in your RevoGrid setup.

### Step-by-Step Guide

1. **Import Required Modules:**
    Import the necessary modules from the RevoGrid library to start setting up the Event Manager Plugin.

2. **Define Edit Details Type:**
    Create a type for edit details that will help structure the event data.

3. **Create EventManagerPlugin Class:**
    Develop the `EventManagerPlugin` class to handle and dispatch edit events. This class listens for various edit events and dispatches a unified `gridedit` event.

    - **Collect Edit Events:** Listens for `clipboardrangepaste`, `beforeedit`, and `beforerangeedit` events.
    - **Dispatch Unified Event:** Dispatches the `gridedit` event after collecting details from the various edit events.

4. **Add Plugin to RevoGrid:**
    Attach the Event Manager Plugin to your RevoGrid instance and start listening for the `gridedit` event.

    ```javascript
    ...
      grid.plugins = [EventManagerPlugin];
    ...
    ```

For detailed implementation, please refer to the full code below.

The Event Manager Plugin is a powerful tool for managing edit events.
By consolidating multiple event types into a single, manageable event, it simplifies event handling and provides a solid foundation for developing custom workflows and interactions.

---

# Grouping with Aggregation

URL: https://pro.rv-grid.com/guides/data-manage/grouping-aggregation/
Source: src/content/docs/guides/data-manage/grouping-aggregation.mdx
Description: Learn how to implement data grouping with custom aggregation functions in RevoGrid

## Overview

The Grouping with Aggregation feature allows you to organize your data into hierarchical groups and display custom aggregated values for each group. This is particularly useful for displaying summary statistics, totals, averages, or custom calculations for grouped data.

## Key Features

- **Hierarchical Grouping**: Group data by multiple columns in a tree-like structure
- **Custom Aggregations**: Define custom aggregation functions for different data types
- **Visual Indicators**: Expandable/collapsible groups with aggregation values displayed
- **Flexible Templates**: Customize how group headers and aggregations are displayed

## Basic Usage

## Implementation

### 1. Import Required Components

```typescript
import { groupingAggregation } from '@revolist/revogrid-pro';
```

### 2. Define Aggregation Functions

Create custom aggregation functions for different columns. **Important**: Aggregation functions receive an array of complete data objects, not just the column values. You need to extract the specific property you want to aggregate:

```typescript
const aggregations = {
  price: (values: any[]) => {
    const prices = values.map(item => item.price);
    const sum = prices.reduce((acc, val) => acc + val, 0);
    const avg = sum / prices.length;
    return `Avg: $${avg.toFixed(2)}`;
  },
  quantity: (values: any[]) => {
    const quantities = values.map(item => item.quantity);
    const total = quantities.reduce((acc, val) => acc + val, 0);
    return `Total: ${total}`;
  },
  product: (values: any[]) => {
    return `${values.length} products`;
  }
};
```

### 3. Create Group Template

Use the `groupingAggregation` function to create a template that displays aggregations:

```typescript
const groupTemplate = (h: any, props: any) => {
  return groupingAggregation(h, props, aggregations);
};
```

### 4. Configure Columns

Apply the group template to columns that will be used for grouping:

```typescript
const columns = [
  { name: '🆔 ID', prop: 'id', size: 60 },
  { name: '📂 Category', prop: 'category', size: 120, template: groupTemplate },
  { name: '📁 Subcategory', prop: 'subcategory', size: 120, template: groupTemplate },
  { name: '📦 Product', prop: 'product', size: 150 },
  { name: '💰 Price', prop: 'price', size: 100 },
  { name: '📊 Quantity', prop: 'quantity', size: 100 },
  { name: '📅 Order Date', prop: 'orderDate', size: 120 },
  { name: '🚚 Delivery Date', prop: 'deliveryDate', size: 120 },
  { name: '👤 Customer', prop: 'customer', size: 150 },
  { name: '🌍 Region', prop: 'region', size: 100 },
  { name: '📋 Status', prop: 'status', size: 100 },
];
```

### 5. Set Up Grouping Configuration

Define which columns should be used for grouping:

```typescript
const grouping = {
  props: ['orderDate', 'category', 'subcategory']
};
```

### 6. Initialize the Grid

```typescript
const grid = document.createElement('revo-grid');
grid.source = yourData;
grid.columns = columns;
grid.grouping = grouping;
// Grouping is a built-in feature, no plugin needed
```

## Aggregation Function Examples

### Numeric Aggregations

```typescript
// Average
price: (values: any[]) => {
  const prices = values.map(item => item.price);
  const avg = prices.reduce((acc, val) => acc + val, 0) / prices.length;
  return `Avg: $${avg.toFixed(2)}`;
}

// Sum
quantity: (values: any[]) => {
  const quantities = values.map(item => item.quantity);
  const total = quantities.reduce((acc, val) => acc + val, 0);
  return `Total: ${total}`;
}

// Min/Max
price: (values: any[]) => {
  const prices = values.map(item => item.price);
  const min = Math.min(...prices);
  const max = Math.max(...prices);
  return `Range: $${min} - $${max}`;
}
```

### String Aggregations

```typescript
// Count
product: (values: any[]) => {
  return `${values.length} products`;
}

// Concatenation
names: (values: any[]) => {
  const names = values.map(item => item.name);
  return names.join(', ');
}

// Unique count
categories: (values: any[]) => {
  const categories = values.map(item => item.category);
  const unique = new Set(categories);
  return `${unique.size} unique categories`;
}
```

### Date Aggregations

```typescript
// Date range
orderDate: (values: any[]) => {
  const dates = values.map(item => new Date(item.orderDate));
  const sorted = dates.sort((a, b) => a.getTime() - b.getTime());
  const earliest = sorted[0].toLocaleDateString();
  const latest = sorted[sorted.length - 1].toLocaleDateString();
  return `${earliest} - ${latest}`;
}
```

## Advanced Configuration

### Custom Group Header Styling

You can customize the appearance of group headers by modifying the template function:

```typescript
const customGroupTemplate = (h: any, props: any) => {
  const aggregationValue = getAggregationValue(props);

  return h('div', {
    style: {
      display: 'flex',
      alignItems: 'center',
      gap: '8px',
      padding: '4px 8px',
      backgroundColor: '#f0f0f0',
      borderRadius: '4px'
    }
  }, [
    h('span', { style: { fontWeight: 'bold' } }, props.name),
    h('span', { style: { fontSize: '12px', color: '#666' } }, `(${aggregationValue})`)
  ]);
};
```

### Conditional Aggregations

You can apply different aggregation logic based on the column or group:

```typescript
const conditionalAggregations = {
  price: (values: any[]) => {
    const prices = values.map(item => item.price);
    const sum = prices.reduce((a, b) => a + b, 0);
    const avg = sum / prices.length;
    return `Avg: $${avg.toFixed(2)}`;
  }
};
```

## Best Practices

1. **Performance**: Keep aggregation functions lightweight, especially with large datasets
2. **User Experience**: Provide clear, meaningful aggregation labels
3. **Data Types**: Ensure aggregation functions handle the correct data types
4. **Error Handling**: Add validation for edge cases (empty arrays, null values)
5. **Accessibility**: Use descriptive text for screen readers

## Common Use Cases

- **Sales Reports**: Group by region/category with revenue totals
- **Inventory Management**: Group by department with stock quantities
- **Financial Data**: Group by account type with balance summaries
- **Project Management**: Group by team with task counts and completion rates

---

# History Undo/Redo

URL: https://pro.rv-grid.com/guides/data-manage/history/
Source: src/content/docs/guides/data-manage/history.mdx
Description: History and undo and redo capabilities in data grid, making it easier to manage user edits

The History Plugin brings powerful undo and redo capabilities to your data grid, making it easier to manage user edits and maintain data integrity.

Keyboard shortcuts like `Ctrl+Z` (or `Cmd+Z` on macOS) for undo and `Ctrl+Y` (or `Cmd+Y` on macOS) / or `Ctrl+Shift+Z` (or `Cmd+Shift+Z` on macOS) for redo are supported out of the box.

Shortcuts work from document keydown events by default, even when the grid does not currently have a focused cell. Set `keyboardShortcutsWithoutFocus: false` to require grid focus.

You can customize its behavior by using the BEFORE_UNDO_EVENT and BEFORE_REDO_EVENT hooks.

- Undo/Redo Management: Automatically tracks user changes with the ability to undo/redo actions using keyboard shortcuts.
- Configurable Stack Size: Tracks up to 200 changes by default, and accepts partial `history` config when you only need to override one option.
- Provider Persistence: Can load and save stack state through local cache and custom server providers for same-dataset sessions.
- Custom Event Hooks: Supports custom behavior via beforeundo and beforeredo events, allowing full control over the undo/redo process.
- Pro Editing Coverage: Tracks regular cell edits, Pro editor templates, textarea editors, range edits, clipboard paste, autofill, row-edit saves, and audit restore replays. `HistoryPlugin` installs its Event Manager dependency automatically.
- Context-menu Transactions: Tracks each built-in Cut, Paste, Clear, row mutation, or column-schema mutation as one chronological undo/redo action. Copy remains non-mutating and is not recorded.

### Additional details

Register `HistoryPlugin` to enable undo/redo. It automatically installs
`EventManagerPlugin` when an Event Manager instance is not already present, so
normal edit events enter the undo stack without a second undocumented plugin.

```ts
import {
  HistoryPlugin,
  createLocalStorageHistoryAdapter,
} from '@revolist/revogrid-pro';

plugins = [HistoryPlugin];
```

Undo, redo, and public replay operations emit `beforehistedit`. The Event
Manager installed by History handles that event and emits the normal `gridedit`
flow. If your application already registers `EventManagerPlugin`, History
reuses that instance rather than creating a duplicate.

`AuditHistoryPlugin` automatically reuses or installs `HistoryPlugin` for restore replay, keyboard shortcuts, and existing History integrations. Keep History configuration on `grid.history`; Audit History does not define a nested History config.

### Context-menu history

When `HistoryPlugin` and `DataGridContextMenuPlugin` are installed together,
each built-in mutating command is atomic: a multi-cell Cut, Paste, cell Clear,
or row Clear creates one history entry, and undo restores all affected cells in
reverse edit order. Redo reapplies them in forward order.

History also snapshots the affected authored structure for these commands:

- Rows: insert above/below, duplicate, delete, pin top/bottom, and unpin.
- Columns: insert left/right, duplicate, delete, pin left/right, unpin, and move
  left/right/start/end.

Plain Copy and Copy with headers do not create entries because they do not
mutate the grid. A `commandHandlers` override is application-owned and is also
excluded: if a custom handler changes remote or application state, record and
restore that state in the application instead. Canceled, unavailable, and no-op
commands leave both stacks unchanged.

In-memory structural entries retain row object identity, nested column groups,
renderers, editors, and other function-valued column fields. Persisted entries
should use serializable row and column definitions; storage formats such as
JSON cannot restore functions. Context-menu replay temporarily bypasses
`clearOnSourceChange` only for its own row-source replacements. Unrelated
application source replacements continue to use the configured clearing policy.

`grid.history` is optional. Add it only when you need custom stacks, a smaller
or larger stack limit, or an initially disabled plugin.

```ts
grid.history = {
  maxStackSize: 100,
  keyboardShortcutsWithoutFocus: false,
};
```

### Persisting History

Undo and redo stacks are index-based, so persisted history is safe only when the user returns to the same dataset, row order, and compatible column schema. Structural context-menu entries additionally require serializable row and column definitions. For long-term recovery across changing data, use `AuditHistoryPlugin`, which restores by stable row identity.

Use `sourceId` to reject stale server states. With multiple providers, the plugin loads the first provider immediately, then applies later providers only when their `updatedAt` state is newer and their `sourceId` is compatible.

When storage is configured, `clearOnSourceChange` defaults to `false` so the initial data load does not erase the restored stack. Set it to `true` only when your app wants every source replacement to clear persisted undo/redo state.

```ts
grid.history = {
  sourceId: `invoices:${workspaceId}:${datasetVersion}`,
  storageProviders: [
    createLocalStorageHistoryAdapter('invoices:history'),
    {
      async load() {
        const response = await fetch('/api/grid-history');
        return response.json();
      },
      async save(state) {
        await fetch('/api/grid-history', {
          method: 'PUT',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(state),
        });
      },
      async clear() {
        await fetch('/api/grid-history', { method: 'DELETE' });
      },
    },
  ],
};
```

Listen to `historyerror` when you want to surface provider failures or skipped states:

```ts
grid.addEventListener('historyerror', (event) => {
  console.warn(event.detail.phase, event.detail.error);
});
```

To call `undo()`, `redo()`, `clear()`, `disable()`, or state helpers, get plugin instances
from the grid and find the `HistoryPlugin` instance.

```ts

async undo() {
  // get plugins from the grid
  const plugins = await this.gridRefNativeElement.getPlugins();
  const history = plugins.find((plugin) => plugin instanceof HistoryPlugin);
  if (history) {
    if (history.canUndo()) {
      history.undo();
    }
  }
}
```

For custom controls, listen to `historychanged` instead of reading plugin
internals. The event detail includes `undoStackSize`, `redoStackSize`,
`canUndo`, `canRedo`, and `disabled`.

### Row reorder history

When `HistoryPlugin` and `RowOrderPlugin` are installed together, every
successful row drop is one undo/redo action by default. This includes selected
row blocks and grouped drops that update group fields.

```ts
grid.history = {
  rowOrderHistory: 'track', // default
};
```

Use `rowOrderHistory: 'clear'` to discard existing history after a committed
drop, or `rowOrderHistory: 'preserve'` when another integration records a richer
domain snapshot. Gantt uses `preserve` and records canonical tasks and
dependencies together.

### Troubleshooting

- Undo/redo does not record changes: ensure `HistoryPlugin` is present in the
  grid's `plugins` array. Event Manager setup and keyboard shortcuts are
  automatic.
- Restore flashes are missing in Audit History: install `EventManagerPlugin` and `CellFlashPlugin`; Audit restore replay flows through `beforehistedit` and the normal edit event path.
- Calling plugin methods does not work: call `getPlugins()` first, then find
  `HistoryPlugin`.
- History clears after sort, filter, or source replacement: this is intentional
  because those operations can change visible row indexes. Successful row
  reorders are tracked unless `rowOrderHistory` is `clear` or `preserve`.
- Persisted history was skipped: check the `historyerror` event for a
  `storage-source-mismatch` phase and update the configured `sourceId`.
- Need a known-good reference: see code in:
  `revogrid-pro/src/components/history/**.**`.

### Key methods

The History Plugin provides four key methods to enhance control over `undo/redo` functionality:
- `clear()`: Resets both the undo and redo stacks, clearing all recorded changes.
- `disable(disable = true)`: Temporarily disables the plugin, preventing changes from being recorded or undo/redo operations from being triggered.
- `undo()`: Reverts the last change recorded in the undo stack and moves it to the redo stack for potential reapplication.
- `redo()`: Reapplies the most recent change from the redo stack, moving it back to the undo stack for further management.
- `canUndo()` / `canRedo()`: Returns whether undo or redo is currently available.
- `getUndoStackSize()` / `getRedoStackSize()`: Returns stack counts for custom controls.
- `isDisabled()`: Returns whether history is disabled.

These methods give developers flexibility in managing user actions and tailoring the plugin’s behavior to specific application requirements.

### Behind the Scenes

The plugin listens to edit events (onEditEvent) and tracks changes in undo and redo stacks. Keyboard shortcuts like Ctrl+Z for undo and Ctrl+Y (or Ctrl+Shift+Z) for redo are supported out of the box. You can customize its behavior by using the BEFORE_UNDO_EVENT and BEFORE_REDO_EVENT hooks.

Here’s a quick snippet showing how the plugin processes undo actions:

```ts
undo() {
  if (this.undoStack.length === 0) return;
  const lastChange = this.undoStack.pop();
  if (lastChange) {
    const event = this.emit(BEFORE_UNDO_EVENT, {
      data: lastChange.previousData,
      type: lastChange.type,
      lastChange,
    });
    if (!event.defaultPrevented) {
      const data = event.detail.data || lastChange.previousData;
      this.replayChange({
        data,
        type: event.detail.type || lastChange.type,
        models: lastChange.models,
        previousData: lastChange.data,
      });
      this.redoStack.push(lastChange);
    }
  }
}
```

`replayChange()` emits `beforehistedit` first. If no integration handles that event, History falls back to `providers.data.setRangeData(...)`.

Try it Out!

Add the History Plugin to your RevoGrid instance and experience seamless undo/redo functionality. This plugin is especially useful in applications that handle complex data operations, ensuring users can easily revert or reapply changes as needed.

<div hidden>

```javascript
// fixing render for multiframework
```

</div>

---

# Nested Grid

URL: https://pro.rv-grid.com/guides/data-manage/nested-grid/
Source: src/content/docs/guides/data-manage/nested-grid.mdx
Description: Learn how to use the Nested Grid to display hierarchical data within RevoGrid cells.

The Nested Grid allows you to display hierarchical data by embedding RevoGrids inside cells. This is particularly useful when you need to show detailed, structured data within a cell, such as project details, task lists, or any other nested data structure.

## Row Expansion

The Nested Grid combined with the Row Expansion plugin to provide a more interactive experience. Row expansion allows users to expand a row to reveal additional details or nested grids.

### Enabling Row Expansion

To enable row expansion, you can configure the grid as follows:

```typescript
import { RowExpandPlugin } from '@revolist/revogrid-pro';

grid.plugins = [RowExpandPlugin];
```

### Example Configuration

Here's an example of how to set up row expansion with nested grids:

```typescript
grid.columns = [
  { prop: 'id', name: 'ID', expand: true }, // Enable row expansion for this column
  { prop: 'name', name: 'Name' },
  {
    prop: 'details',
    name: 'Details',
  }
];

// Additional configuration for row expansion
grid.additionalData = {
  rowExpand: {
    expandedRows: new Set([1]), // Example of expanded rows
    expandedRowHeight: 200, // Height for the expanded row
    // Hide expand toggle based on row data
    hideExpand: (rowIndex, model) => {
      // Example: Hide expand toggle for rows without tasks
      return !model.tasks || model.tasks.length === 0;
    },
    template: (h, props) => {
      return h('revo-grid', {
        key: 'nested-grid',
        class: 'mt-1',
        style: {
          height: '100%',
          maxHeight: '90%',
          maxWidth: '95%',
        },
        theme: isDark() ? 'darkCompact' : 'compact',
        resize: true,
        readonly: true,
        columns: [
          { prop: 'id', name: '#', size: 50 },
          { prop: 'task', name: 'Task', size: 220 },
          {
            prop: 'status',
            name: 'Status',
            size: 150,
            cellProperties: ({ value }) => ({
              style: {
                color: '#fff',
                backgroundColor: value === 'Complete' ? '#00c874' : value === 'In Progress' ? '#fdaa3d' : '#e2435c',
              },
            }),
          },
        ],
        source: props.model.tasks, // Source data for the nested grid
        hideAttribution: true,
      });
    },
  },
};
```

## Configuration Options

The nested grid configuration supports all standard RevoGrid properties. Here are some commonly used options:

- `columns`: Array of column definitions for the nested grid
- `source`: Function that returns the data array for the nested grid
- `theme`: Theme to apply to nested grids
- `readonly`: Whether the nested grid should be read-only
- `rowSize`: Height of rows in the nested grid
- `resize`: Enable column resizing in nested grid
- Any other RevoGrid properties you want to apply to nested grids

### Row Expansion Options

The row expansion configuration supports several options to control expansion behavior:

- `expandedRows`: Set of row IDs that should be expanded by default
- `expandedRowHeight`: Height for expanded rows (in pixels)
- `hideExpand`: Controls visibility of expand toggle buttons, can be:
  - A boolean: `true` to hide all expand toggles
  - A function: `(rowIndex: number, model: any) => boolean` for conditional control

Example of conditional expand toggle visibility:

```typescript
grid.additionalData = {
  rowExpand: {
    // Hide expand toggle for rows that don't have nested data
    hideExpand: (rowIndex, model) => {
      return !model.hasNestedData || model.tasks?.length === 0;
    },
    // ... other configuration options
  }
};
```

## Best Practices

1. **Data Structure**: Organize your data hierarchically with clear parent-child relationships.
2. **Performance**: Consider the following for optimal performance:
   - Limit the number of nested grids visible at once
   - Keep nested data sets reasonably sized
   - Use read-only mode for nested grids if editing isn't required
3. **Responsive Design**: Ensure columns with nested grids have sufficient width.
4. **User Experience**: Use row expansion judiciously to enhance user interaction without overwhelming them with too much information at once.

## Advanced Usage

### Custom Cell Templates

You can combine nested grids with custom cell templates for rich data visualization:

```typescript
{
  prop: 'progress',
  name: 'Progress',
  cellTemplate: (h, props) => {
    const progress = props.model[props.prop] || 0;
    return h('div', {
      style: {
        width: '100%',
        height: '100%'
      }
    }, [
      h('div', {
        style: {
          width: `${progress}%`,
          backgroundColor: progress === 100 ? '#4CAF50' : '#2196F3'
        }
      })
    ]);
  }
}
```

---

# Row Expand Plugin

URL: https://pro.rv-grid.com/guides/data-manage/row-expand/
Source: src/content/docs/guides/data-manage/row-expand.mdx
Description: Learn how to use RowExpandPlugin for inline expandable row details.

The `RowExpandPlugin` adds inline expandable detail rows to RevoGrid. It is useful when a row needs a compact
secondary area for a form, nested grid, notes, preview content, or any row-local custom template.

Unlike the [Master Rows](/guides/data-manage/row-master/) feature, `RowExpandPlugin` does not render a
master-detail overlay. It inserts an expanded row into the regular row viewport and renders your
`rowExpand.template` inside that row.

Use `RowExpandPlugin` for inline detail rows that should stay in the normal grid flow. Use
[`MasterRowPlugin`](/guides/data-manage/row-master/) when the detail area must span the grid, stay aligned
through overlay rendering, or work as a full master-detail view across pinned areas.

## Basic Setup

Import the plugin and add it to the grid:

```ts
import { RowExpandPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [RowExpandPlugin];
```

Add `expand: true` to the column that should render the expand toggle:

```ts
grid.columns = [
  { prop: 'name', name: 'Name', expand: true },
  { prop: 'status', name: 'Status' },
];
```

Configure expanded row behavior with `grid.rowExpand`:

```ts
grid.rowExpand = {
  expandedRows: new Set([0]),
  expandedRowHeight: 220,
  template: (h, props) =>
    h('div', { class: 'row-detail' }, [
      h('strong', null, props.model.name),
      h('p', null, props.model.description),
    ]),
};
```

## Configuration

| Option | Type | Description |
| ------ | ---- | ----------- |
| `expandedRows` | `Set<number>` | Physical row indexes that should be expanded by default. |
| `expandedRowHeight` | `number` | Height, in pixels, for each expanded detail row. |
| `hideExpand` | `boolean \| ((rowIndex: number, model: any) => boolean)` | Hides the expand toggle for all rows or for specific rows. Return `true` to hide the toggle. |
| `template` | `(h: any, props: any) => VNode` | Renders the expanded row content. The template receives the row model and render context. |

`additionalData.rowExpand` is still supported for compatibility, but prefer the direct `grid.rowExpand`
property.

## Programmatic Expansion

The plugin listens for row expansion events:

```ts
import {
  ROW_COLLAPSE,
  ROW_COLLAPSE_ALL,
  ROW_EXPAND,
  ROW_EXPAND_ALL,
} from '@revolist/revogrid-pro';

grid.dispatchEvent(new CustomEvent(ROW_EXPAND, { detail: { rowIndex: 0 } }));
grid.dispatchEvent(new CustomEvent(ROW_COLLAPSE, { detail: { rowIndex: 0 } }));
grid.dispatchEvent(new CustomEvent(ROW_EXPAND_ALL));
grid.dispatchEvent(new CustomEvent(ROW_COLLAPSE_ALL));
```

The `rowIndex` value is the virtual row index at the time the event is dispatched.

## Difference From Master Rows

`RowExpandPlugin` and `MasterRowPlugin` both expose expandable row experiences, but their rendering models are
different:

| Capability | RowExpandPlugin | MasterRowPlugin |
| ---------- | --------------- | --------------- |
| Rendering model | Inline expanded row in the regular row viewport | Overlay-rendered master-detail row |
| Required plugins | `RowExpandPlugin` | `MasterRowPlugin` (`OverlayPlugin` is auto-installed) |
| Toggle setup | Set `expand: true` on a column | Use `EXPAND_COLUMN` or dispatch `ROW_MASTER` |
| Best for | Nested grids, row forms, compact detail rows | Full-width master-detail content and pinned-area spanning layouts |
| Layout scope | Constrained by regular grid row and columns | Can span across the grid through overlay rendering |

For the overlay-based master-detail implementation, read the
[Master Rows guide](/guides/data-manage/row-master/) or the [Row Master API](/api/row-master/).

## Example Use Cases

- Inline edit forms, as shown in the [Form Edit example](/guides/form-edit/).
- Nested grids inside expanded rows, as shown in the [Nested Grid guide](/guides/data-manage/nested-grid/).
- Compact row detail panels that do not need to span pinned columns or the full grid.

---

# Master Rows

URL: https://pro.rv-grid.com/guides/data-manage/row-master/
Source: src/content/docs/guides/data-manage/row-master.mdx
Description: A guide to using the Master Row Plugin.

The **Master Row Plugin** enhances the [RevoGrid](https://rv-grid.com/) grid component by enabling the creation and management of master-detail rows.
It is an extremely **complex and advanced feature**, despite its seemingly simple nature. Read more below.

	1.	Dynamic Overlay Synchronization: The Master Row Plugin creates a dynamic overlay that tracks grid scrolling.
  This ensures that master-detail information remains perfectly aligned and visible as you navigate through large datasets.
	2.	Expansive Master Detail Context: Unlike tree view, group view, or merge cell approaches, this plugin uniquely expands the master row context into the pinned area, allowing it to fill the entire grid. This capability provides a richer, more immersive data presentation and is exceptionally challenging to achieve.
	3.	Virtualized Performance: Despite the complexity of rendering an overlay that spans the grid, the layer remains virtualized. This ensures high performance and responsiveness, even when handling extensive and detailed master row content.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
  - [Basic Setup](#basic-setup)
  - [Configuration](#configuration)
  - [Custom Templates](#custom-templates)
  - [Programmatic Expand and Collapse](#programmatic-expand-and-collapse)
- [API Reference](#api-reference)

---

## Features

- **Expandable Rows:** Easily expand rows to reveal additional details.
- **Custom Templates:** Define how master rows are rendered using customizable templates.
---

## Basic Setup

1. **Import Necessary Plugins and Utilities:**

   ```javascript
   import { EXPAND_COLUMN, MasterRowPlugin, CellColumnFocusVerifyPlugin } from '@revolist/revogrid-pro';
   import type { RowMasterConfig } from '@revolist/revogrid';
   import './row-master.style.css';
   ```

2. **Define Columns:**

   ```javascript
   const columns: HTMLRevoGridElement['columns'] = [
     {
       prop: 'expand',
       ...EXPAND_COLUMN,
     },
     // ...
   ];
   ```

3. **Initialize the Grid with Plugins:**

   ```javascript
   const grid = document.querySelector('revo-grid');
     grid.source = makeData(10, 20);
     grid.columns = columns;

     // Define plugin
     grid.plugins = [
       MasterRowPlugin,
     ];

     const masterRow: RowMasterConfig = {
       rowHeight: 100,
       template: (h, data) => {
         return data.model.subRows?.map((subRow: Person) =>
           h('span', { class: { 'master-row': true } }, [
             h('img', { src: subRow.avatar, width: '20', height: '20' }),
             `${subRow.firstName} ${subRow.lastName} `,
           ]),
         );
       },
     };

     grid.masterRow = masterRow;
   }
   ```

### Configuration

The Master Row Plugin can be customized by assigning a `RowMasterConfig` object to `grid.masterRow`. The primary configuration option is the `template` function, which defines how the master row content is rendered.

#### RowMasterConfig

| Property | Type | Description |
| -------- | ---- | ----------- |
| `template` | `(h: Function, data: any) => JSX.Element` | A function that returns the JSX structure for the master row. It receives a rendering function `h` and the data context `data`. |
| `allowDetailEvents` | `readonly string[]` | Event names from the master detail area that are allowed to bubble to the parent grid. All RevoGrid events inside the detail area are stopped by default. |

### Custom Templates

Customize the master row by defining a `template` function that returns the desired JSX structure. This allows for flexible and dynamic rendering based on the row data.

```javascript
const masterRow: RowMasterConfig = {
  template: (h, data) => {
    return data.model.subRows?.map((subRow: Person) =>
      h('div', { class: { 'custom-master-row': true } }, [
        h('img', { src: subRow.avatar, width: '30', height: '30' }),
        `${subRow.firstName} ${subRow.lastName}`,
      ]),
    );
  },
};
```

To let selected events from nested detail content reach the parent grid, add them by name:

```javascript
const masterRow: RowMasterConfig = {
  allowDetailEvents: ['afteredit'],
  template: (h, data) => h('revo-grid', { source: data.model.details }),
};
```

### Programmatic Expand and Collapse

`EXPAND_COLUMN` toggles a single master row by dispatching the `ROW_MASTER` event with the current cell template payload. You can dispatch the same event directly when a toolbar, external control, or custom cell template needs to control master-row state.

For one row, pass the same cell template payload shape used by cell templates. The plugin treats this as a toggle:

```ts
import { ROW_MASTER } from '@revolist/revogrid-pro';

grid.dispatchEvent(new CustomEvent(ROW_MASTER, {
  detail: cellTemplateData,
}));
```

For multiple rows, pass a batch payload with a `rows` array. Each row target declares its desired final state with `expanded: true` or `expanded: false`, so one event can open and close different rows at the same time:

```ts
import { ROW_MASTER } from '@revolist/revogrid-pro';
import type { RowMasterBatchEvent } from '@revolist/revogrid-pro';

const detail: RowMasterBatchEvent = {
  rows: [
    { rowType: 'rgRow', rowIndex: 1, expanded: true },
    { rowType: 'rgRow', rowIndex: 3, expanded: false },
    { rowType: 'rowPinStart', rowIndex: 0, expanded: true },
  ],
};

grid.dispatchEvent(new CustomEvent(ROW_MASTER, { detail }));
```

`rowIndex` is the current virtual row index for the given `rowType`. The plugin converts every target to a stable internal row reference before applying the batch, so one event can safely mix opened and closed rows without later changes shifting earlier targets. If multiple targets resolve to the same row, the last entry wins.

### Automatic Collapse

Expanded master rows are cleared when the grid is about to change row visibility or row structure in a way that can invalidate the detail overlay position.

The plugin calls its internal `clearAllRows()` cleanup when:

- the grid source is replaced
- filtering is about to trim rows through `beforefiltertrimmed`
- row dragging starts

During that cleanup, expanded master rows are collapsed, detail overlay nodes are removed, duplicated detail rows are removed from the row item lists, and custom detail row heights are cleared. This prevents a filtered or replaced row from leaving stale detail height behind after the row itself is no longer visible.

To stop this automatic cleanup for one of these moments, listen for `BEFORE_ROW_MASTER_COLLAPSE` and call `preventDefault()`:

```ts
import { BEFORE_ROW_MASTER_COLLAPSE } from '@revolist/revogrid-pro';

grid.addEventListener(BEFORE_ROW_MASTER_COLLAPSE, (event) => {
  if (event.detail.reason === 'filter') {
    event.preventDefault();
  }
});
```

The event detail includes `reason` (`'source'`, `'filter'`, or `'drag'`) and `rows`, the expanded master rows that are about to be cleared.

Preventing the default cleanup means your application is responsible for handling any stale detail overlays or custom row heights if the related source row is no longer visible.

---

## API Reference

### MasterRowPlugin

A plugin class that manages master-detail rows within the RevoGrid component.

#### Methods

- **constructor(revogrid: HTMLRevoGridElement, providers: PluginProviders)**

  Initializes the plugin with the RevoGrid instance and plugin providers.

- **expandRow(type: DimensionRows, virtRowIndex: number)**

  Expands a specific row to show its master details.

- **collapseRow(type: DimensionRows, rowVIndexes: number[])**

  Collapses one or more rows, hiding their master details.

- **destroy()**

  Cleans up event listeners and other resources when the plugin is destroyed.

#### Events

The plugin listens to various RevoGrid events to manage the state of master rows, including:

- `AFTER_GRID_RENDER_EVENT`
- `BEFORE_ROW_RENDER_EVENT`
- `BEFORE_ROW_MASTER_COLLAPSE` - cancelable event fired before automatic master-row cleanup collapses expanded rows.
- `ROW_MASTER` - toggles one row from a cell template payload, or applies a batch of desired row states with `{ rows: [{ rowType, rowIndex, expanded }] }`.
- `OVERLAY_NODE`
- ...and more.

---

# Tree Data Grid

URL: https://pro.rv-grid.com/guides/data-manage/tree/
Source: src/content/docs/guides/data-manage/tree.mdx
Description: Enhance your RevoGrid with hierarchical data visualization using the TreeData Plugin.

The **TreeData Plugin** transforms parent-child relationships data into a hierarchical tree structure and provides the ability to group rows by `parentId` and is optimized for the best performance, making it suitable for large datasets.
It enables features such as expandable rows, and level indicators, making it ideal for applications that handle nested data.

## Tree Plugin vs Key Grouping

RevoGrid has two different ways to show hierarchical rows, and they solve different problems:

- **Key grouping** uses the grid's built-in `grouping` configuration, for example `grid.grouping = { props: ['country', 'city'] }`. The grid reads one or more column values, creates synthetic group header rows for each matching key, and places source rows under those generated groups. Use it when the hierarchy should be calculated from repeated values such as category, region, status, or date.
- **TreeDataPlugin** uses explicit row relationships from your data, normally `id` and `parentId`. The plugin keeps your original rows as the tree nodes, computes tree metadata such as level, expanded state, and visibility, and trims collapsed descendants from the viewport. Use it when the hierarchy already exists in the data, such as folders, tasks and subtasks, organization charts, bill of materials, or nested records.

In short, key grouping answers "which rows share the same values?", while the tree plugin answers "which row is the parent of this row?". Key grouping is value-driven and creates group rows; tree data is relationship-driven and renders your existing rows as parent and child nodes.

It is an extremely **complex and advanced feature**, despite its seemingly simple nature.

1. **Group Rows by Parent ID**: build hierarchical structures without modifying the original data, ensuring smooth performance even with large datasets.

2. **Complicated Drag-and-Drop**: The plugin supports **drag-and-drop between parent nodes** and automatically updates the `parentId` of the moved rows.

3. **Advanced Proxy System**: The plugin uses an advanced **proxy system** to handle sorting and filtering while keeping track of hierarchical relationships. This ensures that **all other plugins** remain unaffected by tree view manipulations, allowing for seamless integration.

4. **Metadata Computation**: The plugin computes tree metadata (e.g., level, expanded state, visibility) without modifying the underlying data. It uses a **recursive approach** to compute tree levels and visibility based on the parent-child relationships, and it leverages **row trimming** to optimize performance without altering the source data.

5. **Crucial for Other Plugins**: Beyond its core functionality, the Tree View plugin plays a **crucial role** in supporting other RevoGrid plugins. It facilitates **data transfer** between different components, ensuring compatibility with features like filtering, sorting, and row selection.

- **Hierarchical Data Support**: Automatically organizes flat data into a tree structure based on customizable `id`, `parentId`, and `level` fields.
- **Expandable Rows**: Expand and collapse rows dynamically to reveal or hide child rows.
- **Customizable Templates**: Supports tree-specific cell templates for better customization.
- **Root Parent Support**: Define custom root parent identifiers for flexibility in tree structure.

## Data Structure

To build the hierarchical tree structure, each data item must include the following fields:

- **`id`**: A unique identifier for each row.
- **`parentId`**: Links the item to its parent row. Root-level rows should use the `rootParentId` value (default: `'root'`).

Without these fields, the plugin cannot establish the necessary parent-child relationships for the tree structure.

```javascript
const data = [
  { id: '1', parentId: 'root', name: 'Parent 1' },
  { id: '2', parentId: '1', name: 'Child 1.1' },
  { id: '3', parentId: '1', name: 'Child 1.2' },
  { id: '4', parentId: 'root', name: 'Parent 2' },
];
```

## Additional Configuration Options

The plugin supports the following options for customization:
- idField: Defines the field representing unique row identifiers. Default: 'id'.
- parentIdField: Specifies the field indicating parent row IDs. Default: 'parentId'.
- levelField: Sets the field to store hierarchy levels. Default: 'level'.
- rootParentId: Defines the identifier for root-level rows. Default: 'root'.
- expandedRowIds: A Set of row IDs to predefine expanded rows.

### Example Configuration

You can provide these options via revogrid.additionalData?.tree to customize the plugin’s behavior:
```javascript
grid.additionalData = {
  tree: {
    idField: 'customId',
    parentIdField: 'customParentId',
    levelField: 'depth',
    rootParentId: null,
    expandedRowIds: new Set(['row1', 'row2']), // Pre-expanded rows
  },
};
```
By setting these options, you can adapt the plugin to different data structures and define default states for the tree.

### Animated Collapse and Expand

Tree rows can animate while they are trimmed during collapse and restored during expand. Enable `tree.animation`; TreeDataPlugin registers `DimensionAnimationPlugin` automatically when it is not already present.

```javascript
import { TreeDataPlugin } from '@revolist/revogrid-pro';

grid.plugins = [TreeDataPlugin];
grid.tree = {
  animation: true,
};
grid.dimensionAnimation = {
  duration: 180,
};
```

When `tree.animation` is not enabled, tree collapse and expand use the existing immediate trim behavior.

---

# Checkbox Editor

URL: https://pro.rv-grid.com/guides/editors/editor-checkbox/
Source: src/content/docs/guides/editors/editor-checkbox.mdx

The `editorCheckbox` is a custom cell editor for RevoGrid that provides a checkbox input
to edit boolean values directly within the grid cells.
 * **Features**:
- Renders a checkbox input element for cells, allowing users to toggle boolean values (`true/false`)
  with a simple click.
- Automatically dispatches a `celledit` event upon change, updating the grid's data model with
  the new value.
- Ensures seamless integration with RevoGrid by providing row and column details in the event payload.
- The demo combines checkbox editing with `RowOddPlugin` zebra striping and the
  `material`/`darkMaterial` themes.

---

# Counter Editor

URL: https://pro.rv-grid.com/guides/editors/editor-counter/
Source: src/content/docs/guides/editors/editor-counter.mdx
Description: A plus/minus counter editor for numeric values

The `editorCounter` is a custom cell editor for RevoGrid that provides plus and minus buttons
to increment/decrement numeric values within a specified range directly within the grid cells.

**Features**:
- Renders plus and minus buttons for easy value adjustment
- Supports customizable minimum and maximum values through column properties
- Configurable step size for increments/decrements
- Shows current value with optional display toggle
- Automatically dispatches a `celledit` event upon change
- Seamless integration with RevoGrid's data model
- Modern, responsive design with customizable theming

## Usage

Import the `editorCounter` and assign it to the `cellTemplate` property of a column in the RevoGrid:

```typescript
import { editorCounter } from '@revolist/revogrid-pro'
grid.columns = [
  {
    prop: 'quantity',
    name: 'Quantity',
    cellTemplate: editorCounter,
    min: 0,        // Minimum value (default: 0)
    max: 100,      // Maximum value (default: 100)
    step: 5,       // Step size for increments/decrements (default: 1)
    hideValue: false, // Set to true to hide the value display
  },
];
```

## Configuration Options

The counter editor supports several configuration options through column properties:

- `min` (number): The minimum allowed value (default: 0)
- `max` (number): The maximum allowed value (default: 100)
- `step` (number): The increment/decrement step size (default: 1)
- `hideValue` (boolean): Whether to hide the numeric value display (default: false)

## Event Handling

The counter editor dispatches a `celledit` event whenever the value changes. The event detail contains:
- `rgCol`: The column index of the edited cell
- `rgRow`: The row index of the edited cell
- `type`: The type of the cell
- `prop`: The property of the cell being edited
- `val`: The new numeric value after the change
- `preventFocus`: A flag to control grid focus behavior (default: true)

## Best Practices

1. **Step Size**: Choose a step size that makes sense for your data. For example:
   - Use 1 for integer values like quantities
   - Use 0.1 or 0.01 for decimal values like prices
   - Use 5 or 10 for larger ranges

2. **Value Range**: Set appropriate min and max values to prevent invalid data:
   - For quantities: min = 0, max = maximum stock level
   - For percentages: min = 0, max = 100
   - For ratings: min = 1, max = 5 (or your rating scale)

3. **Visual Feedback**: The editor provides visual feedback through:
   - Disabled buttons when at min/max values
   - Hover effects on buttons
   - Clear value display (unless hidden)

4. **Accessibility**: The editor supports keyboard interaction:
   - Tab navigation between buttons
   - Button states clearly indicated through styling
   - Numeric value visible by default

---

# Dropdown Editor

URL: https://pro.rv-grid.com/guides/editors/editor-dropdown/
Source: src/content/docs/guides/editors/editor-dropdown.mdx

The `ColumnDropdown` column type renders the Pro dropdown editor inside a grid cell. Use it for single-select values, or enable `config.multiSelect` when the cell value is an array.

Register `ColumnDropdown` in `columnTypes`, set `columnType: 'dropdown'` on a column, and provide a `dropdown.source` list with `{ value, label }` options.

**Features**:

- Supports single-select cells with scalar values
- Supports multi-select cells with array values through `config.multiSelect: true`
- Can enable search with `config.search: true`
- Saves changes through RevoGrid cell edit events, so the grid data model stays in sync
- Supports custom option and selected-value templates through the dropdown render callbacks
- Can mirror the column cell template in options and selected values with `dropdown.syncCellTemplate`

### Keep cell and dropdown templates in sync

Set `dropdown.syncCellTemplate` to `true` to reuse the column `cellTemplate` for both option rows and selected values. Object option fields are merged into the synthetic template model, so the same renderer can use metadata such as a status tone, avatar URL, or icon. Explicit `renderOption` and `renderValue` callbacks remain authoritative.

```typescript
const columns = [{
    prop: 'status',
    columnType: 'dropdown',
    cellTemplate: (h, { model, value }) => h('span', {
        class: `status-badge status-badge--${model.tone}`,
    }, model.label ?? value),
    dropdown: {
        syncCellTemplate: true,
        source: [
            { value: 'active', label: 'Active', tone: 'green' },
            { value: 'paused', label: 'Paused', tone: 'amber' },
        ],
    },
}];
```

---

# Row Editor

URL: https://pro.rv-grid.com/guides/editors/editor-row/
Source: src/content/docs/guides/editors/editor-row.mdx

The `RowEditPlugin` is a custom plugin for RevoGrid that provides row-level editing capabilities,
allowing users to edit entire rows inline with dedicated action buttons for saving or canceling changes.

 * **Features**:
- **Row Editing Mode:** Enables editing of entire rows by rendering editors for all cells in the selected row.
- **Inline Editors:** Supports inline editing of multiple cells in a row simultaneously.
- **Action Buttons:** Provides intuitive buttons for `Save` and `Cancel` actions:
  - `Save`: Dispatches `CELL_EDIT_SAVE_EVENT` to persist changes.
  - `Cancel`: Dispatches `CELL_EDIT_CANCEL_EVENT` to discard changes.
- **Event Handling:** Listens for key events to manage row editing:
  - `CELL_EDIT_EVENT`: Initiates row editing mode.
  - `CELL_EDIT_SAVE_EVENT`: Saves edited data and updates the grid model.
  - `CELL_EDIT_CANCEL_EVENT`: Cancels editing and restores original data.
  - `BEFORE_CELL_RENDER_EVENT`: Ensures cells in the editing row render with editors.

---

# Slider Editor

URL: https://pro.rv-grid.com/guides/editors/editor-slider/
Source: src/content/docs/guides/editors/editor-slider.mdx

The `editorSlider` is a custom cell editor for RevoGrid that provides a slider input
to edit numeric values within a specified range directly within the grid cells.

**Features**:
- Renders a slider input element for cells, allowing users to select numeric values by dragging a slider handle
- Supports customizable minimum and maximum values through column properties
- Automatically dispatches a `celledit` event upon change, updating the grid's data model with the new value
- Ensures seamless integration with RevoGrid by providing row and column details in the event payload

---

# Textarea Editor

URL: https://pro.rv-grid.com/guides/editors/editor-textarea/
Source: src/content/docs/guides/editors/editor-textarea.mdx

This editor is a custom cell editor for RevoGrid that allows users to handle multi-line text input, making it suitable for applications requiring
rich text editing capabilities within grid cells.

To move to the next line within the `TextAreaEditor`, the user should press `Shift + Enter`.

---

# Timeline Editor

URL: https://pro.rv-grid.com/guides/editors/editor-timeline/
Source: src/content/docs/guides/editors/editor-timeline.mdx
Description: A custom cell editor for managing date ranges with a visual timeline representation

The `editorTimeline` is a custom cell editor for RevoGrid that provides a visual timeline interface
for managing date ranges directly within grid cells.

**Features**:
- Visual timeline bar with progress indicator
- Date range selection with native date pickers
- Progress tracking based on current date
- Responsive design that fits within grid cells

---

# Customization

URL: https://pro.rv-grid.com/guides/event-scheduler/customization/
Source: src/content/docs/guides/event-scheduler/customization/index.mdx
Description: Customize scheduler labels, renderers, properties, styles, visual hooks, and states.

Event Scheduler can be customized at several levels. Start with labels, formatters, CSS variables, and classes when you only need to change text or visual styling. Use `eventScheduler.customization` when a product needs RevoGrid-style render hooks for generated scheduler headers, cells, event sections, or create previews.

The scheduler still owns projection, selection, drag/drop, resize, keyboard behavior, permission checks, conflicts, and mutation events. Custom render hooks should describe what a section looks like, while the scheduler continues to manage how that section behaves.

## Customization layers

| Layer | Use it for |
| --- | --- |
| `labels` | Rename built-in UI text such as resource labels, editor fields, action labels, and validation messages. |
| Formatters | Change displayed text without replacing markup, for example resource labels, time labels, day headers, hover labels, create-range labels, and tooltips. |
| Direct properties hooks | Add classes, inline styles, attributes, data fields, CSS variables, status colors, or simple renderers to scheduler surfaces. |
| `customization` | Replace or annotate scheduler headers, cells, event sub-sections, resize handles, badges, and create previews. |
| Conflict and state hooks | Customize conflict badges/tooltips and empty/loading/error overlay states. |
| CSS variables/classes | Theme the scheduler and target built-in state classes such as selected, conflict, locked, status, type, weekend, today, or non-working time. |

## Customization areas

| Area | Use it for |
| --- | --- |
| [Labels and formatters](./labels-formatters/) | Text-only labels, date/time display, resource names, hover labels, and tooltips. |
| [Event rendering](./events/) | Event button properties, content templates, badges, resize handles, tooltips, and status colors. |
| [Layout, headers, and cells](./layout/) | Column sizes, generated headers, time rows, day cells, resource rows, and timeline cells. |
| [Slots, hours, and markers](./slots-hours/) | Create previews, empty slots, closed hours, availability styling, and current-time markers. |
| [Conflicts and states](./conflicts-states/) | Conflict indicators, warning/error treatment, remote loading, empty, and error overlays. |
| [Context menus](./context-menu/) | Event, slot, day-header, and background commands. |
| [Styling and themes](./styling/) | CSS variables, built-in state classes, and white-label themes. |

## Choosing the right hook

- Use `labels` or formatters when the result is plain text.
- Use CSS variables when the built-in structure is correct and the change is visual.
- Use `eventProperties` or `statusColorResolver` when styling depends on event data.
- Use `customization.*Properties` to add classes, styles, ARIA labels, or data attributes without replacing content.
- Use `customization.*Template` only when the visible markup for that section needs to change.

Template hooks replace only the section they target. Scheduler-owned interaction handlers, selection state, permission attributes, drag/resize behavior, generated data attributes, conflict classes, and core accessibility attributes remain managed by the plugin.

For interaction callbacks, cancelable DOM events, selection, clipboard, keyboard shortcuts, and custom editor workflows, see [Editing and Interaction](../event-editing/).

For compact copyable examples of each major customization surface, see [Examples](../examples/). That page includes basic weekly setup, event templates, day headers, slot context menus, current-time markers, closed hours, read-only mode, cancelable selection, and theme snippets.

---

# Conflicts and States

URL: https://pro.rv-grid.com/guides/event-scheduler/customization/conflicts-states/
Source: src/content/docs/guides/event-scheduler/customization/conflicts-states.mdx
Description: Customize conflict warnings, empty overlays, loading overlays, and error states.

## Conflict display

Conflict customization is separate from general event rendering so products can apply a consistent warning/error treatment without replacing event content.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  customization: {
    conflicts: {
      className: ({ severity }) => `booking-conflict booking-conflict--${severity}`,
      properties: ({ conflictTypes }) => ({
        'data-conflict-types': conflictTypes.join(' '),
      }),
      indicator: (h, { severity }) =>
        h('span', { class: 'booking-conflict__badge' }, severity === 'error' ? 'Blocked' : 'Review'),
      tooltip: ({ label }) => `Planning issue: ${label}`,
    },
  },
};
```

The scheduler still adds built-in conflict classes, data attributes, and severity attributes to event blocks. Custom conflict hooks run only for conflicted segments.

## Empty, loading, and error states

Remote mode and local empty states can use product-specific wording and markup through `labels`, `emptyStateText`, and `customization.emptyState`.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  emptyStateText: 'No resources match this view.',
  labels: {
    remoteLoading: 'Loading bookings...',
    remoteError: 'Bookings could not be loaded.',
    remoteEmpty: 'No bookings in this range.',
  },
  customization: {
    emptyState: {
      template: ({ kind, label }) =>
        kind === 'error' ? `Action needed: ${label}` : label,
      properties: ({ kind }) => ({
        class: `booking-scheduler-state booking-scheduler-state--${kind}`,
      }),
    },
  },
};
```

The template can return a string or a DOM node. Property hooks can add classes, style variables, ARIA attributes, and data attributes to the overlay element.

---

# Context Menus

URL: https://pro.rv-grid.com/guides/event-scheduler/customization/context-menu/
Source: src/content/docs/guides/event-scheduler/customization/context-menu.mdx
Description: Customize scheduler context-menu actions for events, slots, headers, and background surfaces.

## Context menu actions

Use scheduler context-menu hooks when product actions depend on the clicked event, empty slot, resource, or scheduler surface. The default event and slot menus are generic conveniences; products can replace them, append shared actions, or keep built-ins and filter individual commands.

| Config | Purpose |
| --- | --- |
| `getSlotContextMenuItems` | Replaces the empty-slot menu for the clicked slot. |
| `getEventContextMenuItems` | Replaces the event-bar menu for the clicked event segment. |
| `getDayHeaderContextMenuItems` | Defines optional day-header menu commands for products that expose header actions. |
| `getBackgroundContextMenuItems` | Defines background/empty-scheduler-space commands. Slot backgrounds use this when no slot factory is supplied. |
| `contextMenuTemplate` | Replaces the rendered content for scheduler-specific menu items. |
| `onContextMenuAction` | Receives every scheduler-specific item selection with target context. |
| `hiddenItems` / `disabledItems` | Hide or disable built-in scheduler actions by id. |
| `items` / `itemFilter` | Compatibility hooks for appending raw Pro context-menu items or transforming built-ins. |

Scheduler-specific menu items support `id`, `label`, `icon`, `shortcut`, `disabled`, `hidden`, `danger`, `separator`, `group`, and `action`. Use `danger` for destructive actions, `separator` for visual breaks, and `disabled` / `hidden` functions when the command depends on event or slot state.

Menu item visibility and disabled state are resolved when the menu opens. If visibility depends on remote permissions or capacity checks, keep that state in application data and return it synchronously from `hidden` or `disabled`. Time-row context menus are optional; products that need them can use the underlying Pro row context-menu configuration until a dedicated scheduler time-row trigger is required.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  contextMenu: {
    enabled: true,
    hiddenItems: { confirm: true },
    getEventContextMenuItems: ({ segment }) => [
      {
        id: 'open-record',
        label: 'Open record',
        icon: 'fa-solid fa-arrow-up-right-from-square',
        shortcut: 'O',
        action: () => openPlanningRecord(segment?.event.id),
      },
      { id: 'event-edit-separator', separator: true },
      {
        id: 'duplicate-event',
        label: 'Duplicate',
        shortcut: 'Cmd+D',
        disabled: ({ segment }) => segment?.event.locked === true,
        action: ({ segment }) => duplicateBooking(segment?.event.id),
      },
      {
        id: 'delete-event',
        label: 'Delete',
        danger: true,
        disabled: ({ segment }) => segment?.event.readonly === true,
        action: ({ segment }) => deleteBooking(segment?.event.id),
      },
    ],
    getSlotContextMenuItems: ({ slot }) => [
      {
        id: 'create-booking',
        label: 'Create booking here',
        icon: 'fa-solid fa-plus',
        shortcut: 'C',
        action: () => createBookingAt(slot?.startDateTime),
      },
      {
        id: 'block-slot',
        label: 'Block this time',
        group: 'availability',
        action: ({ slot }) => createHoldAt(slot?.startDateTime),
      },
    ],
    getBackgroundContextMenuItems: () => [
      { id: 'refresh-availability', label: 'Refresh availability' },
    ],
    contextMenuTemplate: (h, item) =>
      item.separator
        ? null
        : h('span', { class: 'planner-menu-item' }, [
            item.icon ? h('span', { class: item.icon }) : null,
            h('span', null, item.label),
            item.shortcut ? h('kbd', null, item.shortcut) : null,
          ]),
    onContextMenuAction: ({ itemId, target, segment, slot }) => {
      trackSchedulerMenuAction({ itemId, target, eventId: segment?.event.id, slot });
    },
  },
};
```

Built-in context-menu actions continue to respect scheduler permissions, locked resources, read-only mode, disabled/non-selectable slots, and conflict rules. The default built-in labels can be changed through `labels`, and all built-ins can be removed with `hiddenItems`, transformed with `itemFilter`, or replaced entirely with target-specific factories.

Built-in menu labels are generic by default: `createEventHereAction`, `assignOpenEventAction`, `editEventAction`, `confirmEventAction`, and `markPlannedAction`. Integrations should use these generic event labels or replace the menus with target-specific factories.

---

# Event Rendering

URL: https://pro.rv-grid.com/guides/event-scheduler/customization/events/
Source: src/content/docs/guides/event-scheduler/customization/events.mdx
Description: Customize event colors, properties, content, badges, resize handles, tooltips, and accessible labels.

## Event branding

Event blocks support a lightweight styling layer before you use the grouped `customization.events` API.

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  statusColorResolver: (event) => {
    if (event.status === 'confirmed') return '#2563eb';
    if (event.status === 'planned') return '#d97706';
    if (event.status === 'blocked') return '#dc2626';
  },
  eventProperties: ({ event }) => ({
    class: `scheduler-event--${event.type ?? 'default'}`,
    style: {
      '--shift-accent': event.status === 'blocked' ? '#dc2626' : '#2563eb',
    },
    'data-shift-status': event.status,
  }),
  eventTemplate: (h, { event }) =>
    h('span', { class: 'shift-event-title' }, event.title),
};
```

`statusColorResolver` resolves the scheduler event accent color when the event does not already provide `event.color` and the status does not map to a built-in status class. `eventProperties` is merged onto the event button and can return `class`, `style`, attributes, data fields, or event handlers. `eventTemplate` replaces the default event content only; it does not replace the outer interactive event shell.

## Event section templates

Use direct event hooks when a product needs a simple public API for event bars in week and resource-timeline views.

| Config | Purpose |
| --- | --- |
| `eventTemplate` | Legacy top-level event content renderer. |
| `eventContentTemplate` | Replaces the default title, time, badge, and resource content block. |
| `eventProperties` | Adds classes, styles, attributes, data fields, or event handlers to the event button. |
| `eventTooltipTemplate` | Overrides the event `title` tooltip with custom details. |
| `eventBadgeTemplate` | Replaces individual status, type, category, or required-role badges. |
| `eventResizeHandleTemplate` | Replaces the visual content inside start/end resize handles. |

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  eventProperties: (context) => ({
    class: [
      'event-card',
      context.isSelected ? 'event-card--selected' : '',
      context.isLocked ? 'event-card--locked' : '',
      context.hasConflict ? 'event-card--conflict' : '',
      context.isShortEvent ? 'event-card--short' : '',
    ].filter(Boolean).join(' '),
    style: {
      '--event-accent': context.hasConflict ? '#dc2626' : context.event.color ?? '#2563eb',
    },
    'data-event-duration': context.duration,
  }),
  eventContentTemplate: (h, { event, resource, start, end, isFromPreviousDay, isContinuedToNextDay }) =>
    h('span', { class: 'event-card__content' }, [
      h('strong', { class: 'event-card__title' }, event.title),
      h('span', { class: 'event-card__time' }, `${start.slice(11, 16)}-${end.slice(11, 16)}`),
      resource ? h('span', { class: 'event-card__resource' }, resource.name) : null,
      isFromPreviousDay ? h('span', { class: 'event-card__continuation' }, 'From previous day') : null,
      isContinuedToNextDay ? h('span', { class: 'event-card__continuation' }, 'Continues') : null,
    ]),
  eventBadgeTemplate: (h, { kind, label, isLocked }) =>
    h('span', { class: `event-card__badge event-card__badge--${kind}` }, isLocked ? 'Locked' : label),
  eventResizeHandleTemplate: (h, { edge }) =>
    h('span', { class: `event-card__resize event-card__resize--${edge}` }),
  eventTooltipTemplate: ({ event, resource, duration, hasConflict }) =>
    `${event.title} | ${resource?.name ?? 'Unassigned'} | ${duration} minutes${hasConflict ? ' | Conflict' : ''}`,
};
```

Event render contexts include `event`, `resource`, the first real projected `segment`, the ordered `segments` represented by the bar, aggregate `start`, `end`, and `duration`, plus `day`, `status`, `type`, `isSelected`, `isDragging`, `isResizing`, `isLocked`, `hasConflict`, `isReadonly`, `isFromPreviousDay`, `isContinuedToNextDay`, and `isShortEvent`. Dragging and resizing state are currently reserved and remain `false` until the scheduler exposes public pointer-state rendering.

The legacy `first`, `last`, and `sliceSlot` fields remain available for source compatibility but are deprecated. Because hooks now run once per continuous bar, `first` and `last` are always `true`, while `sliceSlot` is the primary segment's `startSlot`. New code should use `segment.startSlot`, `segments`, and the aggregate range fields instead.

`customization.events` provides the grouped form of the same customization surface and layers on top of direct event properties where both are supplied. It customizes the event button and its internal sections. It applies to both week and resource timeline render modes.

When `customization.events.content` is configured, it is the authoritative content hook. Returning `null` or `undefined` restores the built-in event content rather than invoking `eventContentTemplate` or legacy `eventTemplate`. Without the grouped hook, Scheduler tries `eventContentTemplate`, then `eventTemplate`, and finally the built-in content.

| Hook | What it customizes |
| --- | --- |
| `className` | Adds one or more classes to the event button. |
| `style` | Adds inline styles or CSS custom properties to the event button. |
| `properties` | Adds attributes, classes, styles, or data attributes to the event button. |
| `content` | Replaces the default title, time, badge, and resource content block. |
| `continuationLabels` | Replaces previous/next-day continuation labels. |
| `badgeTray` | Replaces the tray that holds badges for multi-slot events. |
| `badge` | Replaces individual status, type, category, or required-role badges. |
| `resizeHandle` | Replaces the visual content inside start/end resize handles. |
| `tooltip` | Overrides the event `title` tooltip. |
| `ariaLabel` | Overrides the event button accessible label. |

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  customization: {
    events: {
      className: ({ event }) => `event-card event-card--${event.status ?? 'default'}`,
      style: ({ event }) => ({
        '--event-border-color': event.status === 'blocked' ? '#dc2626' : '#2563eb',
      }),
      properties: ({ event, segment }) => ({
        'data-event-id': event.id,
        'data-event-start-slot': segment.startSlot,
      }),
      content: (h, { event, resource, segment }) =>
        h('span', { class: 'event-card__content' }, [
          h('strong', { class: 'event-card__title' }, event.title),
          h('span', { class: 'event-card__resource' }, resource?.name ?? 'Unassigned'),
          segment.conflict ? h('span', { class: 'event-card__warning' }, 'Conflict') : null,
        ]),
      badge: (h, { kind, label }) =>
        h('span', { class: `event-card__badge event-card__badge--${kind}` }, label),
      tooltip: ({ event, resource }) => `${event.title} - ${resource?.name ?? 'Unassigned'}`,
      ariaLabel: ({ event }) => `Scheduled event ${event.title}`,
    },
  },
};
```

The outer event element remains a scheduler-managed button. It keeps click, double-click, pointer, selection, disabled move/resize state, conflict state, and accessibility wiring. Custom event content should avoid interactive controls inside the event button unless the product has tested the keyboard and pointer behavior carefully.

## Rendering content at the bottom of a bar

Each event assignment is rendered as one continuous visual bar. In vertical views the bar is anchored from the day's first slot cell; in resource timeline it is attached to the resource row. Event customization hooks therefore run once per visible bar rather than once per grid cell.

Use `context.segment` for the first real projected segment and `context.segments` when you need every day segment represented by a multi-day timeline bar. The aggregate `context.start`, `context.end`, and `context.duration` fields describe the complete visible bar.

To render content pinned to the bottom of a multi-slot bar — such as a status badge, category chip, or summary — use `badgeTray`. Its return value is placed directly inside the event button.

Include the `event-scheduler-event__badge-tray` wrapper class in the returned element to get the built-in absolute bottom positioning:

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  customization: {
    events: {
      content: (h, context) =>
        h('span', { class: 'my-event' }, [
          h('strong', { class: 'my-event__title' }, context.event.title),
          h('span', { class: 'my-event__time' }, `${context.start.slice(11, 16)}-${context.end.slice(11, 16)}`),
          h('span', { class: 'my-event__badge' }, String(context.event.status ?? '')),
        ]),
      badgeTray: (h, context) => {
        // Runs once for a multi-slot bar whose visible end is in this view.
        const status = String(context.event.status ?? '');
        if (!status) return null;
        return h('span', { class: 'event-scheduler-event__badge-tray' }, [
          h('span', { class: 'my-event__badge' }, status),
        ]);
      },
    },
  },
};
```

`badgeTray` does not fire for single-slot bars or for a bar whose visible end continues beyond the current view (`isContinuedToNextDay`). When `badgeTray` returns `null` or `undefined`, the default badge tray — which displays type, category, and required-role chips — is rendered instead.

---

# Labels and Formatters

URL: https://pro.rv-grid.com/guides/event-scheduler/customization/labels-formatters/
Source: src/content/docs/guides/event-scheduler/customization/labels-formatters.mdx
Description: Customize scheduler text, dates, resource labels, hover labels, and tooltips.

## Labels and formatters

Use labels and formatters for text-level customization. This keeps the built-in DOM, accessibility attributes, selection, tooltips, and editing behavior intact.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  locale: 'en-US',
  timeZone: 'America/New_York',
  labels: {
    resourceColumn: 'Crew',
    unassignedResource: 'Open demand',
    newEvent: 'New assignment',
    createEvent: 'Create shift',
    editEvent: 'Edit shift',
  },
  dayHeaderFormatter: (date) =>
    date.toLocaleDateString('en-US', {
      weekday: 'short',
      month: 'short',
      day: 'numeric',
      timeZone: 'America/New_York',
    }),
  timeLabelFormatter: (minutes) => `${Math.floor(minutes / 60)}:00`,
  timelineHeaderFormatter: ({ startDateTime, endDateTime }) =>
    `${startDateTime.slice(11, 16)}-${endDateTime.slice(11, 16)}`,
  hoverTimeFormatter: (minutes) => `Create at ${String(Math.floor(minutes / 60)).padStart(2, '0')}:00`,
  resourceLabelFormatter: (resource) => resource.name,
  resourceMetaFormatter: (resource) =>
    [resource.role, resource.metadata?.location].filter(Boolean).join(' - '),
  tooltipFormatter: ({ event, resource }) =>
    `${event.title}\n${resource?.name ?? 'Unassigned'}\n${event.startDateTime}`,
};
```

Built-in day, range, and timeline date labels use `locale` and `timeZone`. Formatter hooks take precedence when you need product-specific date or time strings, including date-only labels that should not shift when displayed in a non-UTC timezone.

Formatters are the best first choice when the content is still a string. Move to templates only when you need nested markup, custom badges, custom attributes, or section-specific replacement.

---

# Layout, Headers, and Cells

URL: https://pro.rv-grid.com/guides/event-scheduler/customization/layout/
Source: src/content/docs/guides/event-scheduler/customization/layout.mdx
Description: Customize scheduler column sizing, generated headers, time rows, day cells, resource rows, and timeline cells.

## Grouped customization API

Use the grouped `customization` API when you need precise control over generated scheduler surfaces.

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  customization: {
    columnSizes: {
      week: {
        timeColumnSize: 96,
        dayColumnSize: 220,
      },
      resourceTimeline: {
        resourceColumnSize: 260,
        timelineColumnSize: 144,
      },
    },
    headers: {
      dayTemplate: (h, context) =>
        h('span', { class: 'scheduler-day-header' }, context.defaultLabel),
      dayProperties: (context) => ({
        class: context.today ? 'scheduler-day-header--brand-today' : '',
        'data-scheduler-date': context.date,
      }),
      groupTemplate: (h, context) =>
        h('strong', { class: 'scheduler-range-header' }, context.defaultLabel),
    },
    cells: {
      resourceProperties: ({ resource }) => ({
        'data-resource-role': resource?.role,
      }),
      timelineProperties: ({ date, slotIndex }) => ({
        class: 'scheduler-timeline-slot',
        'data-scheduler-slot-key': `${date}:${slotIndex}`,
      }),
    },
    events: {
      properties: ({ event }) => ({
        'data-event-status': event.status,
      }),
      content: (h, { event, resource }) =>
        h('span', { class: 'scheduler-event-title' }, [
          h('strong', {}, event.title),
          h('small', {}, resource?.name ?? 'Unassigned'),
        ]),
      badge: (h, context) =>
        h('span', {
          class: `scheduler-event-chip scheduler-event-chip--${context.kind}`,
        }, context.label),
      resizeHandle: (h, context) =>
        h('span', {
          class: `scheduler-event-resize scheduler-event-resize--${context.edge}`,
        }),
    },
    createPreview: {
      createRangeTemplate: (context) =>
        `${context.title}: ${context.startLabel}-${context.endLabel}`,
      createRangeProperties: () => ({ class: 'scheduler-create-preview' }),
    },
    conflicts: {
      className: ({ severity }) => `scheduler-conflict scheduler-conflict--${severity}`,
      indicator: (h, context) =>
        h('span', { class: 'scheduler-conflict-badge' }, context.severity),
      tooltip: ({ label }) => `Review before saving: ${label}`,
    },
    emptyState: {
      template: ({ kind, label }) => `${kind}: ${label}`,
      properties: ({ kind }) => ({
        class: `scheduler-state scheduler-state--${kind}`,
      }),
    },
  },
};
```

Template hooks receive RevoGrid's `h` helper and a scheduler context object. Return a string, a VNode, `null`, or `undefined`. Returning `null` or `undefined` keeps the built-in section. Property hooks return attributes, `class`, `style`, or data attributes for the target element.

Custom properties are merged with built-in scheduler properties. Built-in interaction handlers and scheduler data attributes remain in place, so custom hooks should not attach drag, resize, selection, or mutation behavior directly.

## Column sizes

`customization.columnSizes` controls scheduler-owned column widths by view. These values are resolved before legacy top-level size props such as `timeColumnSize`, `dayColumnSize`, `resourceColumnSize`, and `timelineColumnSize`.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  customization: {
    columnSizes: {
      week: {
        timeColumnSize: 88,
        dayColumnSize: 180,
      },
      resourceTimeline: {
        resourceColumnSize: 280,
        timelineColumnSize: 120,
      },
    },
  },
};
```

Use week sizes for `day`, `week`, and `month` style calendar grids. Use resource timeline sizes when the first column is the pinned resource column and the remaining columns are timeline slots.

## Header templates and properties

Header customization targets the generated scheduler columns. For day headers, use the direct week-scheduler hooks when you only need day-header customization. Use `customization.headers` when you need to customize every generated header type.

Direct day-header hooks:

| Hook | Surface |
| --- | --- |
| `dayHeaderFormatter` | Formats the built-in day header label. |
| `dayHeaderTemplate` | Replaces the day header content. |
| `dayHeaderProperties` | Adds classes, styles, attributes, data fields, or event handlers to day headers. |

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  dayHeaderFormatter: (date) =>
    date.toLocaleDateString('en-US', {
      weekday: 'short',
      month: 'short',
      day: 'numeric',
      timeZone: 'UTC',
    }),
  dayHeaderTemplate: (h, context) =>
    h('span', { class: 'planner-day-header' }, [
      h('span', { class: 'planner-day-header__label' }, context.defaultLabel),
      context.today ? h('span', { class: 'planner-day-header__badge' }, 'Today') : null,
      context.holiday ? h('span', { class: 'planner-day-header__holiday' }, context.holidayLabel) : null,
      h('span', { class: 'planner-day-header__count' }, `${context.eventCount ?? 0} events`),
    ]),
  dayHeaderProperties: (context) => ({
    class: [
      context.today ? 'planner-day-header--today' : '',
      context.weekend ? 'planner-day-header--weekend' : '',
      context.holiday ? 'planner-day-header--holiday' : '',
    ].filter(Boolean).join(' '),
    style: {
      '--planner-day-event-count': context.eventCount ?? 0,
      ...(context.holiday ? { '--planner-day-state': 'holiday' } : {}),
    },
    'data-planner-day': context.date,
  }),
};
```

Day header context includes `defaultLabel`, `date`, `dayIndex`, `eventCount`, `today`, `weekend`, `holiday`, and `holidayLabel`. Holiday state is date-level: it comes from the primary scheduler calendar or global `kind: 'holiday'` availability entries. Resource-specific holidays stay on the scheduler body cells.

`customization.headers.dayTemplate` takes precedence over `dayHeaderTemplate` when both are provided. This lets applications keep older grouped customization config while adding direct day-header hooks where convenient.

Grouped header customization has one template hook and one matching properties hook per generated header section.

| Hook | Surface |
| --- | --- |
| `timeTemplate` / `timeProperties` | Pinned time header in day/week/month style views. |
| `resourceTemplate` / `resourceProperties` | Pinned resource header in resource timeline views. |
| `dayTemplate` / `dayProperties` | Day header cells. |
| `timelineTemplate` / `timelineProperties` | Resource timeline slot headers. |
| `groupTemplate` / `groupProperties` | Grouped range/day/timeline headers when column grouping is enabled. |

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  customization: {
    headers: {
      dayTemplate: (h, context) =>
        h('span', { class: 'brand-day-header' }, [
          h('strong', {}, context.defaultLabel),
          context.today ? h('small', {}, 'Today') : null,
          context.holiday ? h('small', {}, context.holidayLabel) : null,
          context.eventCount ? h('small', {}, `${context.eventCount} events`) : null,
        ]),
      dayProperties: (context) => ({
        class: [
          context.today ? 'brand-day-header--today' : '',
          context.weekend ? 'brand-day-header--weekend' : '',
          context.holiday ? 'brand-day-header--holiday' : '',
        ],
        'data-brand-date': context.date,
      }),
    },
  },
};
```

Header contexts include the active view, the default label, date or slot fields where relevant, event counts, today/weekend/holiday flags, holiday labels, and group kind for grouped headers.

## Cell templates and properties

Cell customization targets the scheduler body cells. Use property hooks when you only need classes, styles, or test/data attributes. Use templates when the default cell body should be replaced.

Use the direct time-axis hooks when the product only needs to control the pinned time column in day, week, or month-style views.

| Config | Purpose |
| --- | --- |
| `timeLabelFormatter` | Formats built-in time text such as `06:00`, `6 AM`, or `6:00`. |
| `timeLabelTemplate` | Replaces the pinned time-label cell content. |
| `timeRowProperties` | Adds classes, styles, attributes, data fields, or event handlers to time-label cells. |
| `timeRange` | Sets the visible start/end time and hides time outside that range. |
| `slotMinutes` | Sets row granularity with a 15-minute minimum, for example `15`, `30`, or `60`. When `snapMinutes` is omitted, interaction snapping follows this active value as zoom changes. |
| `rowSize` | Controls row density in pixels. |
| `nonWorkingTime` | Styles closed or outside-business-hours cells in the scheduler body. |

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  timeRange: { start: '06:00', end: '22:00' },
  slotMinutes: 30,
  rowSize: 40,
  timeLabelFormatter: (minutes) => {
    const hour = Math.floor(minutes / 60);
    const minute = minutes % 60;
    return `${hour % 12 || 12}:${String(minute).padStart(2, '0')} ${hour < 12 ? 'AM' : 'PM'}`;
  },
  timeLabelTemplate: (h, context) =>
    h('span', { class: 'planner-time-label' }, context.timeLabel),
  timeRowProperties: (context) => ({
    class: context.currentTimeLabel ? 'planner-time-row--current' : 'planner-time-row',
    style: {
      '--planner-time-start': context.startMinutes,
    },
    'data-planner-time': context.timeLabel,
  }),
  nonWorkingTime: {
    enabled: true,
    workingDays: [1, 2, 3, 4, 5],
    workingHours: { start: '08:00', end: '18:00' },
    className: 'planner-closed-hours',
  },
};
```

`customization.cells.timeTemplate` and `customization.cells.timeProperties` layer over the direct `timeLabelTemplate` and `timeRowProperties` hooks when both are provided. Use `rowSize` for compact, dense, or comfortable density presets, and use `timeRange` when night hours should be hidden from the grid instead of only styled as closed.

| Hook | Surface |
| --- | --- |
| `timeTemplate` / `timeProperties` | Time-label rows in week-style grids. |
| `dayTemplate` / `dayProperties` | Day/time slots in week-style grids. |
| `resourceTemplate` / `resourceProperties` | Resource rows in resource timeline grids. |
| `resourceGroupTemplate` / `resourceGroupProperties` | Group rows when resource grouping is enabled. |
| `timelineTemplate` / `timelineProperties` | Timeline cells in resource timeline grids. |

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  customization: {
    cells: {
      resourceProperties: ({ resource, unassigned, depth }) => ({
        class: [
          resource?.role ? `resource-row--${resource.role.toLowerCase()}` : '',
          unassigned ? 'resource-row--open-demand' : '',
        ],
        style: { '--resource-depth': depth },
        'data-resource-role': resource?.role,
      }),
      timelineProperties: ({ date, slotIndex, segmentCount }) => ({
        class: segmentCount > 0 ? 'timeline-slot--busy' : 'timeline-slot--open',
        'data-slot-key': `${date}:${slotIndex}`,
      }),
    },
  },
};
```

When a cell template is provided, the scheduler renders that template instead of the default cell content for that slot. Continuous event bars are rendered by the Scheduler's bar layer and remain independent of slot-cell content, so prefer cell properties when the goal is only styling or annotation.

---

# Slots, Hours, and Markers

URL: https://pro.rv-grid.com/guides/event-scheduler/customization/slots-hours/
Source: src/content/docs/guides/event-scheduler/customization/slots-hours.mdx
Description: Customize create previews, empty slots, closed hours, availability states, and current-time markers.

## Create previews

Create preview customization affects empty-slot hover labels and the drag-create range preview.

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  editable: true,
  allowCreate: true,
  customization: {
    createPreview: {
      hoverTimeProperties: ({ startDateTime }) => ({
        class: 'create-hover-slot',
        'data-hover-start': startDateTime,
      }),
      createRangeTemplate: ({ title, startLabel, endLabel, durationLabel, resource }) =>
        `${title} for ${resource?.name ?? 'Unassigned'}: ${startLabel}-${endLabel} (${durationLabel})`,
      createRangeProperties: ({ durationMinutes }) => ({
        class: durationMinutes >= 240 ? 'create-range--long' : 'create-range--short',
      }),
    },
  },
};
```

Use `hoverTimeProperties` for attributes and styling on the slot while the pointer is over a creatable time. Use `createRangeTemplate` and `createRangeProperties` for the range ghost shown during drag-create interactions.

## Empty slot customization

Empty slots are a primary extension point for booking, staffing, room planning, maintenance windows, pricing, capacity, and availability workflows. Use direct slot hooks when a product needs custom empty-cell content or behavior without replacing event bars.

| Hook | Purpose |
| --- | --- |
| `slotTemplate` | Renders custom content inside empty week or resource-timeline slots. Occupied slots keep their event bars. |
| `slotProperties` | Adds classes, styles, attributes, data fields, or event handlers to scheduler slot cells. |
| `slotTooltip` | Overrides the native tooltip for disabled, closed, priced, or capacity-based slots. |
| `onSlotClick` | Runs custom click behavior before built-in editor-open behavior. |
| `onSlotDoubleClick` | Runs custom double-click behavior for immediate create or custom workflows. |
| `onSlotContextMenu` | Receives the resolved slot when the scheduler context menu opens. |
| `isSlotDisabled` | Marks slots as disabled and blocks built-in create/editor behavior. |
| `isSlotSelectable` | Marks slots as non-selectable for create/selection UX. |

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  editable: true,
  allowCreate: true,
  slotTemplate: (h, context) =>
    h('span', { class: 'booking-slot-capacity' }, [
      context.disabled ? 'Closed' : `${getCapacity(context)} seats`,
    ]),
  slotProperties: (context) => ({
    class: [
      context.disabled ? 'booking-slot--closed' : '',
      !context.selectable ? 'booking-slot--invalid' : '',
      context.segmentCount > 0 ? 'booking-slot--busy' : 'booking-slot--open',
    ].filter(Boolean).join(' '),
    style: {
      '--booking-slot-capacity': getCapacity(context),
    },
    'data-booking-slot': context.startDateTime,
  }),
  slotTooltip: (context) =>
    context.disabled ? 'Outside working hours' : `Available from ${context.startDateTime}`,
  isSlotDisabled: (context) => isClosedForBusiness(context),
  isSlotSelectable: (context) => !hasBlockedAvailability(context),
  onSlotClick: (context, event) => {
    if (context.disabled) {
      event.preventDefault();
      showClosedSlotPopover(context);
    }
  },
  onSlotDoubleClick: (context) => {
    if (!context.disabled) createBookingImmediately(context);
  },
  onSlotContextMenu: (context) => {
    trackSlotMenuOpened(context);
  },
  contextMenu: {
    enabled: true,
    hiddenItems: {
      create: true,
      'assign-open': true,
    },
    items: ({ target, slot }) => target === 'slot' && slot
      ? [
          { name: 'Create booking', action: () => createBookingImmediately(slot) },
          { name: 'Block this time', action: () => blockSlot(slot) },
        ]
      : [],
  },
};
```

`slotTemplate` is intentionally limited to empty cells so products can customize available space without removing visible event bars. Use `customization.cells.dayTemplate` or `customization.cells.timelineTemplate` only when the whole scheduler body cell, including event rendering, should be replaced. Use `isSlotDisabled` and `isSlotSelectable` with `allowCreate` or conflict rules when closed hours should block create, drag, paste, and editor flows.

## Working and closed hours

Use working and closed-hour APIs when availability is part of the scheduler contract: business hours, weekends, holidays, lunch breaks, maintenance windows, or capacity holds. These hooks build on the existing `nonWorkingTime`, calendars, availability data, and conflict rules.

| Config | Purpose |
| --- | --- |
| `workingHours` | Defines global or per-weekday working ranges. Use `false` in `byDay` to close a weekday. |
| `closedHours` | Defines closed ranges such as lunch, maintenance, holidays, or blocked planning windows. |
| `availabilityRules` | Applies product-specific availability rules from slot context. |
| `closedSlotTemplate` | Renders custom content inside closed slots. |
| `closedSlotProperties` | Adds classes, styles, attributes, data fields, or event handlers to closed slots. |
| `closedSlotTooltip` | Overrides the native tooltip/title for closed slots. |
| `isTimeSlotAvailable` | Blocks built-in create/editor behavior when it returns `false`. |

Use `workingHours` for global business hours, `workingHours.byDay` for weekday-specific hours or closed weekends, `closedHours` for explicit closed ranges such as lunch or maintenance, and date-specific `closedHours` entries for holidays. Closed slots can be styled with `closedSlotProperties`, replaced with `closedSlotTemplate`, and explained through `closedSlotTooltip`.

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  editable: true,
  allowCreate: true,
  workingHours: {
    byDay: {
      1: { start: '08:00', end: '18:00' },
      2: { start: '08:00', end: '18:00' },
      3: { start: '08:00', end: '18:00' },
      4: { start: '08:00', end: '18:00' },
      5: { start: '08:00', end: '16:00' },
      0: false,
      6: false,
    },
  },
  closedHours: [
    {
      id: 'lunch',
      days: [1, 2, 3, 4, 5],
      ranges: { start: '12:00', end: '13:00' },
      title: 'Closed',
      reason: 'Lunch break',
      className: 'planner-slot--lunch',
    },
    {
      id: 'maintenance',
      dates: ['2026-06-10'],
      ranges: { start: '15:00', end: '17:00' },
      reason: 'Maintenance window',
      className: 'planner-slot--maintenance',
    },
  ],
  availabilityRules: ({ date, startMinutes }) =>
    date === '2026-06-12' && startMinutes >= 14 * 60
      ? { available: false, reason: 'Capacity hold', className: 'planner-slot--held' }
      : undefined,
  isTimeSlotAvailable: ({ date, slotIndex }) =>
    !isCompanyHoliday(date) && slotIndex !== 0,
  closedSlotProperties: ({ availabilityKind, reason }) => ({
    class: `planner-slot--closed planner-slot--${availabilityKind}`,
    style: {
      '--planner-closed-opacity': reason === 'Lunch break' ? 0.6 : 0.85,
    },
  }),
  closedSlotTooltip: ({ title, reason }) =>
    [title, reason].filter(Boolean).join(' - '),
  closedSlotTemplate: (h, { reason }) =>
    h('span', { class: 'planner-slot__closed-label' }, reason ?? 'Closed'),
};
```

Closed-slot context extends normal slot context with `available`, `availabilityKind`, `availabilityId`, `title`, and `reason`. Built-in create/editor behavior is blocked when `isTimeSlotAvailable` returns `false`, when `closedHours`/`availabilityRules` mark the slot unavailable, or when `isSlotDisabled` / `isSlotSelectable` deny the slot. For resource-specific calendars, remote availability, and holidays, continue using `calendars` and `eventSchedulerAvailability`; the closed-slot hooks style those states too.

## Current time marker

The current-time marker can use the built-in red line and badge, or it can be replaced by product-specific marker content. Week-style views render a horizontal marker on the active date. Resource timeline views render a vertical marker in the active timeline slot.

| Config | Purpose |
| --- | --- |
| `showCurrentTimeMarker` | Simple show/hide alias. |
| `currentTimeMarker` | Detailed marker config, including fixed `dateTime` for deterministic demos/tests. |
| `currentTimeUpdateInterval` | Live refresh interval in milliseconds. Defaults to `60000`; use `0` to disable automatic live refresh. |
| `currentTimeLabelFormatter` | Formats the marker label, such as `12:26`, `Now`, or a localized time. |
| `currentTimeMarkerTemplate` | Replaces marker content in week and resource timeline cells. |
| `currentTimeMarkerProperties` | Adds classes, styles, attributes, data fields, or event handlers to the marker cell. |

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  showCurrentTimeMarker: true,
  currentTimeUpdateInterval: 60_000,
  currentTimeLabelFormatter: ({ dateTime }) =>
    new Intl.DateTimeFormat('en-US', {
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date(dateTime)),
  currentTimeMarkerProperties: ({ orientation }) => ({
    class: orientation === 'horizontal'
      ? 'planner-now-marker planner-now-marker--horizontal'
      : 'planner-now-marker planner-now-marker--vertical',
    style: {
      '--event-scheduler-current-time-color': '#dc2626',
      '--planner-now-marker-thickness': '2px',
    },
  }),
  currentTimeMarkerTemplate: (h, context) =>
    h('span', { class: 'planner-now-marker__label' }, context.label),
};
```

Marker context includes `view`, `date`, `dayIndex`, `slotIndex`, `startMinutes`, `endMinutes`, `dateTime`, `label`, `position`, `orientation`, and, when available, `row`, `resourceId`, and `resource`. The marker is hidden when disabled, outside the visible date range, or outside the visible time range. Use `currentTimeMarker: { dateTime }` when the marker should point at a fixed instant rather than live `now`.

---

# Styling and Themes

URL: https://pro.rv-grid.com/guides/event-scheduler/customization/styling/
Source: src/content/docs/guides/event-scheduler/customization/styling.mdx
Description: Theme Event Scheduler with CSS variables, built-in classes, state selectors, and white-label styles.

## CSS variables and classes

Use CSS when the scheduler structure is correct and only the theme needs to change. The scheduler exposes classes and CSS variables for common states, including today, weekend, current time, conflict, selected, locked, unassigned, status, type, category, non-working time, hover time, ghost ranges, create ranges, editor surfaces, and context menus.

```css
.event-scheduler-plugin {
  --event-scheduler-accent: #0f766e;
  --event-scheduler-accent-soft: #ccfbf1;
  --event-scheduler-surface: #ffffff;
  --event-scheduler-surface-sunken: #f8fafc;
  --event-scheduler-grid-line: #d8dee6;
  --event-scheduler-current-time-color: #dc2626;
  --event-scheduler-weekend-bg: rgba(15, 118, 110, 0.04);
  --event-scheduler-hover-time-bg: rgba(15, 118, 110, 0.12);
  --event-scheduler-create-range-bg: rgba(15, 118, 110, 0.16);
}

.event-scheduler-event--status-confirmed {
  --event-scheduler-event-color: #2563eb;
}

.event-scheduler-event--type-maintenance {
  --event-scheduler-event-bg: #fff7ed;
  --event-scheduler-event-color: #c2410c;
}

.event-scheduler-day-cell__slot--non-working {
  opacity: 0.8;
}
```

Prefer CSS variables for broad theme changes. Prefer `eventProperties` and `customization.*Properties` when classes or attributes depend on event, resource, date, slot, conflict, or projection context.

## White-label themes

Scheduler styles are designed around CSS custom properties. Apply theme variables at the grid, plugin host, product shell, or global stylesheet level:

```css
.booking-scheduler revo-grid {
  --event-scheduler-accent: #315f8c;
  --event-scheduler-accent-soft: #e8f1f8;
  --event-scheduler-grid-line: #d8dee6;
  --event-scheduler-surface: #ffffff;
  --event-scheduler-surface-sunken: #f6f8fb;
  --event-scheduler-event-bg: #eef7f3;
  --event-scheduler-event-color: #16825c;
  --event-scheduler-conflict-warning-bg: #fff7ed;
  --event-scheduler-conflict-warning-color: #c2410c;
  --event-scheduler-remote-state-bg: rgba(255, 255, 255, 0.96);
}
```

Prefer CSS variables for broad white-label theming, and use render hooks only when the product needs different markup or data-driven content.

---

# Editing and Interaction

URL: https://pro.rv-grid.com/guides/event-scheduler/event-editing/
Source: src/content/docs/guides/event-scheduler/event-editing.mdx
Description: Create, move, resize, delete, validate, select, copy, paste, and handle interactions with the RevoGrid Scheduler lifecycle.

Enable editing with the master `editable` flag and the specific `allow*` permissions your product needs.

Editing is checked in layers. The scheduler first applies `editable`, `allowCreate`, `allowMove`, `allowResize`, `allowDelete`, event/resource locks, date locks, and permission hooks. It then projects the next schedule and rejects the mutation when conflicts resolve to `severity: 'error'`. Use this to block edits outside working hours.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  editable: true,
  allowCreate: true,
  allowMove: true,
  allowResize: true,
  allowDelete: true,
  conflicts: {
    enabled: true,
    rules: { 'outside-availability': 'error' },
  },
  createEventDraft: (context) => ({
    id: `event-${crypto.randomUUID()}`,
    resourceId: context.resourceId,
    title: 'New booking',
    startDateTime: context.startDateTime,
    endDateTime: context.endDateTime,
    status: 'draft',
  }),
  validateMutation: (detail) => {
    if (detail.event?.locked) {
      return 'Locked events cannot be changed.';
    }
  },
};
```

To enforce working hours, define them with `calendars` or `eventSchedulerAvailability`; then block the `outside-availability` conflict as shown above. `nonWorkingTime` can make closed cells visible, but it does not by itself reject create, move, resize, or editor changes.

Conflicts are evaluated against the projected next event array before the local mutation is committed. This means move, resize, create, edit, delete, bulk, template, paste, and recurrence actions can all be stopped by the same conflict configuration. Use `conflicts.policy: 'prevent'` when every detected conflict should block by default, or keep `policy: 'mark'` and promote only selected rules such as `overlap`, `outside-availability`, or `blocked-time` to `error`.

The before-change detail includes the projected `conflicts` array. Use it when the UI needs custom messages or business-specific decisions on top of configured conflict rules.

```ts
grid.addEventListener('event-scheduler-before-event-change', (event) => {
  const blockingConflict = event.detail.conflicts?.find((conflict) =>
    conflict.severity === 'error' &&
    event.detail.eventId !== null &&
    conflict.eventIds.includes(event.detail.eventId)
  );

  if (blockingConflict) {
    event.preventDefault();
  }
});
```

For one-off business rules that are not calendar rules, use `permissions.canCreate`, `permissions.canMutate`, or `validateMutation`. These hooks are useful for role checks, approval states, custom capacity rules, or backend-specific constraints.

If you prefer event-based validation, listen for `event-scheduler-before-event-change` and call `event.preventDefault()`. This is the same cancelable-before-event pattern used by RevoGrid editing events. Do not use `event-scheduler-event-changed` for cancellation; it fires after the scheduler has already accepted and applied the change.

```ts
grid.addEventListener('event-scheduler-before-event-change', (event) => {
  if (event.detail.action === 'move' && event.detail.event?.locked) {
    event.preventDefault();
  }
});
```

## Unified committed changes

Every successful create, edit, move, resize, delete, paste, duplicate,
recurrence, or bulk mutation also reaches EventManager's shared `gridedit`
stream. Inspect `event-scheduler-event-change` in `eventTypes` and the typed,
ordered `domainChanges` entries:

```ts
grid.addEventListener('gridedit', (event) => {
  if (!event.detail.eventTypes.includes('event-scheduler-event-change')) return;

  for (const change of event.detail.domainChanges ?? []) {
    if (change.type !== 'event-scheduler-event') continue;
    saveEventChange(change.detail);
  }
});
```

Each entry contains the Scheduler action, event ID, previous event, and
committed event. Creates have a null previous event; deletes have a null
committed event; bulk and server-canonical mutations include every affected
event. These snapshots are detached from Scheduler state.

`data`, `previousData`, and `models` contain normal row/field patches only when
an event keeps a stable canonical source index. Creates, deletes, and unstable
positions remain in `domainChanges`. The complete event collection used for
undo/redo is stored separately in `history`, never as a synthetic grid field.

Cancellation remains on `event-scheduler-before-event-change` and
`validateMutation`. Scheduler `gridedit` details have
`sourceMutation: 'producer'`, so they are observational: `preventDefault()`
does not roll back the committed schedule. With remote mutation hooks enabled,
Scheduler publishes only after ordered server commitment; rejected remote
mutations publish nothing.

When EventManager collection is enabled, consecutive Scheduler mutations merge
into one ordered transaction and one history step. Undo restores the earliest
snapshot and redo restores the latest committed snapshot.

## Undo and redo

`EventSchedulerPlugin` installs the shared `HistoryPlugin` automatically. Every
accepted create, edit, move, resize, delete, paste, duplicate, recurrence, or
bulk mutation is stored as one scheduler-owned event snapshot. Undo and redo
restore the complete event collection and rebuild the normal scheduler
projection, including conflicts, coverage, utilization, and event segments.

```ts
const plugins = await grid.getPlugins();
const history = plugins.find((plugin) =>
  plugin.constructor?.name === 'HistoryPlugin'
);

history.undo();
history.redo();
```

The normal History keyboard shortcuts, stack limits, persistence adapters,
`beforeundo`, `beforeredo`, `historychanged`, and `historyerror` behavior remain
available. Canceled or rejected scheduler mutations do not create entries, and
multi-event operations remain atomic.

Scheduler rows and columns are derived projection data, so history stores event
entities rather than visible grid cells. If the host persists every state
transition, listen to `historychanged` as well as the scheduler's final mutation
events and read `scheduler.getProjection()?.events` after undo or redo.

## Data ownership and save flows

Event Scheduler does not require one persistence model. Choose the data ownership flow that matches your app: upload all events as host state, save the final projected schedule, save every accepted mutation, or let remote hooks load and commit data.

Use `source` to upload host-owned data into the scheduler:

```ts
grid.eventSchedulerResources = resources;
grid.source = events;
```

The scheduler updates its accepted event list and `grid.source` after permissions, before hooks, `validateMutation`, and conflict rules pass. Final events such as `event-scheduler-event-created`, `event-scheduler-event-changed`, and `event-scheduler-event-deleted` fire afterward, so use them for persistence and framework state sync. Use before hooks or `validateMutation` for cancellation.

### Save the full projection after work

Use this flow when the user can make several local edits and your app saves the whole schedule later, for example from a toolbar Save button. Read `grid.source`; generated scheduler rows, columns, and segments remain internal render artifacts.

```ts
const plugins = await grid.getPlugins();
const scheduler = plugins.find((plugin) =>
  plugin.constructor?.name === 'EventSchedulerPlugin'
);

scheduler.createEvent({
  id: `event-${crypto.randomUUID()}`,
  resourceId: 'room-a',
  title: 'Design review',
  startDateTime: '2026-06-08T09:00:00.000Z',
  endDateTime: '2026-06-08T10:00:00.000Z',
});

scheduler.editEvent('booking-1', {
  resourceId: 'room-b',
  startDateTime: '2026-06-08T10:00:00.000Z',
  endDateTime: '2026-06-08T11:00:00.000Z',
});

scheduler.deleteEvent('hold-1');

const savedEvents = grid.source;
await api.saveSchedule({ events: savedEvents });

// Later, or after clearing the scheduler, upload the saved data back.
grid.source = savedEvents;
```

### Save incrementally while work happens

Use this flow when the host app owns canonical state and wants every accepted scheduler change to update that state immediately. Each final event carries `detail.events`, the full next accepted event list after the mutation.

```ts
let persistedEvents = [...initialEvents];

function persistSchedulerEvents(event: CustomEvent) {
  persistedEvents = event.detail.events;
  void api.saveEvents(persistedEvents);
}

grid.addEventListener('event-scheduler-event-created', persistSchedulerEvents);
grid.addEventListener('event-scheduler-event-changed', persistSchedulerEvents);
grid.addEventListener('event-scheduler-event-deleted', persistSchedulerEvents);

// Later, upload the persisted host state into a clean scheduler.
grid.source = persistedEvents;
```

The final event detail also includes action-specific context such as `eventId`, `event`, `previousEvent`, `action`, and `conflicts`. Use those fields for audit logs or targeted API calls, but keep `detail.events` as the simplest full-list state sync contract.

### Save through remote APIs

Use remote mode when the server owns the visible range or when loading the whole schedule up front is too expensive. Remote loaders upload visible data into the scheduler. `commitMutation` receives the accepted projected mutation request and can return canonical server events.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  remote: {
    enabled: true,
    mode: 'remote',
    loadResources: ({ signal }) =>
      api.loadResources({ signal }),
    loadEvents: ({ dateRange, resourceIds, signal }) =>
      api.loadEvents({ dateRange, resourceIds, signal }),
    validateMutation: (request) =>
      api.validateScheduleChange(request),
    commitMutation: async (request) => {
      const result = await api.saveScheduleChange({
        action: request.action,
        eventId: request.eventId,
        event: request.event,
        previousEvent: request.previousEvent,
        changes: request.changes,
        events: request.events,
        conflicts: request.conflicts,
      });

      return {
        accepted: true,
        events: result.events,
      };
    },
  },
};

const plugins = await grid.getPlugins();
const scheduler = plugins.find((plugin) =>
  plugin.constructor?.name === 'EventSchedulerPlugin'
);

// Reload the current visible range into a clean scheduler state.
await scheduler.refreshVisibleRange();
```

Remote `commitMutation` runs after the local mutation has been accepted. If the backend rejects the change, return `{ accepted: false, message }` or throw; with the default rollback behavior the scheduler restores the previous event list. See [Remote Data](/guides/event-scheduler/remote-data/) for paging, state events, errors, and refresh controls.

`validateMutation` is the config-level equivalent of the cancelable before-change event. It receives the same detail shape and can return `false` or a string to reject.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  validateMutation: ({ action, event, changes }) => {
    if (action === 'delete' && event?.status === 'completed') {
      return 'Completed events cannot be deleted.';
    }
    if (changes?.resourceId === 'locked-room') {
      return 'That room is locked.';
    }
  },
};
```

## Built-in editor

The built-in create/edit dialog supports unassigned, single-resource, and
multi-resource events. It keeps the compact `resourceId` shape for one selected
resource and writes `resourceIds` when two or more resources are selected:

```ts
{
  id: 'shared-maintenance',
  resourceIds: ['crew-a', 'crew-b'],
  title: 'Shared maintenance',
  startDateTime: '2026-06-08T08:00:00.000Z',
  endDateTime: '2026-06-08T10:00:00.000Z',
}
```

Multi-resource assignment is enabled by default. Disable it when each event
must belong to at most one resource:

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  allowMultiResourceAssignment: false,
};
```

With this option disabled, selecting another resource replaces the current
selection, and the built-in editor saves the assignment through `resourceId`.
The option only constrains the built-in editor; custom editors and
host-provided `resourceIds` remain application-owned.

The resource selector edits the event's inline assignment fields. If your
backend owns relationships through `eventSchedulerAssignments`, provide a
custom editor and update that assignment collection in the host application.

## Custom editor

Set `eventEditor: false` to disable the built-in editor, or provide a custom editor hook when the host app owns a drawer, modal, or approval flow:

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  eventEditor: (context) => {
    openProductDrawer({
      mode: context.mode,
      event: context.event,
      resources: context.resources,
      readOnly: context.readonly,
      validationMessage: context.validationMessage,
      onSave: context.submit,
      onDelete: context.delete,
      onClose: context.close,
    });
    return true;
  },
};
```

The editor helpers still route changes through permissions, conflicts, `event-scheduler-before-event-change`, local mutation, post-commit events, and remote mutation hooks.

## Interaction callbacks

Use named before hooks to validate or cancel user actions before local scheduler state changes. Return `false` to cancel with the default message, or return a string to cancel with a product-specific validation message.

| Before hook | Action |
| --- | --- |
| `beforeEventCreate` | Create from slot, editor create, template create, recurrence create |
| `beforeEventUpdate` | Editor/API updates and status changes |
| `beforeEventMove` | Drag move and bulk move |
| `beforeEventResize` | Drag resize |
| `beforeEventDelete` | Delete and bulk delete |
| `beforeEventDuplicate` | Duplicate selected events |
| `beforeEventLock` | Lock or unlock changes |
| `beforeSlotSelect` | Empty-slot selection/click before create behavior |

Final callbacks fire after the scheduler has committed local state and include enough context to update app state or persist to a backend.

| Final callback | Action |
| --- | --- |
| `onEventCreate` | Event created, including paste/duplicate/template-created events |
| `onEventUpdate` | Event updated or status changed |
| `onEventMove` | Event moved |
| `onEventResize` | Event resized |
| `onEventDelete` | Event deleted |
| `onEventDuplicate` | Duplicated event created |
| `onEventLock` | Event locked or unlocked |
| `onEventCopy` | Event copied into the scheduler clipboard |
| `onEventPaste` | Pasted event created |
| `onSelectionChange` | Event selection changed |
| `onSlotSelect` | Empty slot selected/clicked |
| `contextMenu.onContextMenuAction` | Scheduler context-menu item selected |

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  beforeEventMove: ({ event, changes }) => {
    if (event?.locked) return 'Locked events cannot be moved.';
    return validateMoveOnServerCache(event, changes);
  },
  beforeEventResize: ({ event, changes }) =>
    isOutsidePolicyWindow(event, changes) ? 'Outside policy window.' : undefined,
  beforeEventDelete: ({ event }) =>
    event?.metadata?.protected ? 'Protected events cannot be deleted.' : undefined,
  beforeSlotSelect: ({ date, startDateTime }) =>
    isClosedForBooking(date, startDateTime) ? 'This slot is closed.' : undefined,
  onEventMove: ({ event, previousEvent }) =>
    saveEventMove({ event, previousEvent }),
  onEventResize: ({ event, previousEvent }) =>
    saveEventResize({ event, previousEvent }),
  onEventDelete: ({ event }) =>
    archiveDeletedEvent(event),
  onSelectionChange: ({ eventIds }) =>
    setSelectedPlannerEvents(eventIds),
  contextMenu: {
    onContextMenuAction: ({ itemId, target, segment, slot }) =>
      trackSchedulerCommand({ itemId, target, eventId: segment?.event.id, slot }),
  },
};
```

The lower-level `event-scheduler-before-event-change`, `event-scheduler-before-event-select`, `event-scheduler-before-slot-select`, `event-scheduler-event-created`, `event-scheduler-event-changed`, `event-scheduler-event-deleted`, and `event-scheduler-event-selected` DOM events remain available for integrations that prefer event listeners. Call `preventDefault()` on the before events to cancel the pending scheduler action. `validateMutation` still runs in the same mutation pipeline for shared validation logic.

## Selection, clipboard, and keyboard

Scheduler selection supports selected events, selected slots, selected time ranges, multi-select, range select, copy, paste, duplicate, and keyboard-driven commands. Use the cancelable `event-scheduler-before-event-select` event when the host application owns selected event state: prevent the pending selection, update application state, then pass the accepted ids back through `selection.selectedEventIds`.

```ts
let selectedEventIds: readonly string[] = [];

grid.addEventListener('event-scheduler-before-event-select', (event) => {
  event.preventDefault();
  selectedEventIds = event.detail.eventIds;
  renderScheduler();
});

function renderScheduler() {
  grid.eventScheduler = {
    ...grid.eventScheduler,
    selectionMode: 'multiple',
    selection: {
      ...grid.eventScheduler?.selection,
      selectedEventIds,
      selectedSlot,
      selectedRange,
      clipboard: true,
      copyOffsetDays: 7,
      onChange: ({ eventIds }) => setSelectedEventIds(eventIds),
    },
    onSelectionChange: ({ eventIds, events }) =>
      syncInspectorSelection({ eventIds, events }),
    onSlotSelect: (slot) =>
      setSelectedSlot(slot),
  };
}
```

Accepted selections still emit `event-scheduler-event-selected`, `onSelectionChange`, and `selection.onChange`. A prevented selection does not emit final selection callbacks; the host re-applies its accepted state through the config.

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  beforeSlotSelect: ({ date }) =>
    isClosedForBooking(date) ? 'This slot is closed.' : undefined,
};

grid.addEventListener('event-scheduler-before-slot-select', (event) => {
  if (isReadOnlyResource(event.detail.resourceId)) {
    event.preventDefault();
  }
});
```

Use `clipboardAdapter` when copy/paste must integrate with product state, permissions, or a custom clipboard store. Paste remains disabled when there is no internal payload and `clipboardAdapter.hasPayload()` is false.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  clipboardAdapter: {
    hasPayload: () => appClipboard.has('scheduler-events'),
    read: () => appClipboard.get('scheduler-events'),
    write: (payload) => appClipboard.set('scheduler-events', payload),
    clear: () => appClipboard.delete('scheduler-events'),
  },
  onCopy: ({ eventIds }) => trackCopy(eventIds),
  onPaste: ({ event }) => persistCreatedEvent(event),
  onDuplicate: ({ event }) => persistCreatedEvent(event),
};
```

Keyboard shortcuts can be disabled globally, disabled per command, or rebound. Use `Mod` for Cmd on macOS and Ctrl on Windows/Linux.

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  keyboardShortcuts: {
    enabled: true,
    helpPanel: true,
    shortcuts: {
      copy: 'Mod+c',
      paste: 'Mod+v',
      duplicate: 'Mod+Shift+d',
      delete: false,
      lock: false,
      today: ['t', 'Home'],
    },
  },
};
```

Available keyboard commands are `escape`, `help`, `today`, `search`, `previous`, `next`, `cyclePrevious`, `cycleNext`, `open`, `create`, `edit`, `lock`, `delete`, `copy`, `paste`, `duplicate`, and `viewWeek`.

---

# Examples

URL: https://pro.rv-grid.com/guides/event-scheduler/examples/
Source: src/content/docs/guides/event-scheduler/examples.mdx
Description: Working Event Scheduler examples for setup, templates, menus, availability, read-only mode, cancelable selection, and custom themes.

This page collects small, product-neutral Event Scheduler examples. The same APIs work for shifts, bookings, appointments, staffing, rooms, maintenance, tasks, equipment, and team planning.

The runnable demo catalog includes these complete scheduler stories:

| Demo | Use it for |
| --- | --- |
| Event Staff Scheduler | Resource timeline, coverage, conflicts, templates, saved views, and remote-mode controls. |
| Employee Shift Planner | Week view with days on the x-axis, time on the y-axis, drag-create, move, resize, delete, and closed hours. |
| Room Booking Scheduler | Resource booking with availability windows, blocked time, conflicts, and grouped resources. |
| Equipment / Machine Scheduler | Maintenance planning, utilization, capacity rows, and exportable workload data. |

## Basic weekly scheduler

```ts
import {
  EventSchedulerPlugin,
  type EventSchedulerConfig,
  type EventSchedulerEventEntity,
} from '@revolist/scheduler';

const events: EventSchedulerEventEntity[] = [
  {
    id: 'booking-1',
    title: 'Customer onboarding',
    resourceId: 'room-a',
    startDateTime: '2026-06-08T09:00:00.000Z',
    endDateTime: '2026-06-08T11:00:00.000Z',
    type: 'booking',
    status: 'confirmed',
  },
];

const eventScheduler: EventSchedulerConfig = {
  view: 'week',
  weekStartDate: '2026-06-08',
  weekStartsOn: 1,
  visibleDays: [1, 2, 3, 4, 5],
  timeRange: { start: '06:00', end: '22:00' },
  slotMinutes: 30,
  locale: 'en-US',
  timeZone: 'UTC',
  editable: true,
  allowCreate: true,
  allowMove: true,
  allowResize: true,
  allowDelete: true,
  todayHighlight: true,
  showCurrentTimeMarker: true,
};

grid.plugins = [EventSchedulerPlugin];
grid.eventScheduler = eventScheduler;
grid.source = events;
```

## Custom event template

```ts
grid.eventScheduler = {
  ...grid.eventScheduler,
  eventProperties: ({ event, isSelected, hasConflict, isLocked }) => ({
    class: [
      'planner-event',
      isSelected ? 'planner-event--selected' : '',
      hasConflict ? 'planner-event--conflict' : '',
      isLocked ? 'planner-event--locked' : '',
    ].filter(Boolean).join(' '),
    style: {
      '--planner-event-accent': event.color ?? '#2563eb',
    },
  }),
  eventContentTemplate: (h, { event, resource, start, end, isShortEvent }) =>
    h('span', { class: 'planner-event__body' }, [
      h('strong', { class: 'planner-event__title' }, event.title),
      isShortEvent ? null : h('span', { class: 'planner-event__time' }, `${start.slice(11, 16)}-${end.slice(11, 16)}`),
      resource ? h('small', { class: 'planner-event__resource' }, resource.name) : null,
    ]),
  eventTooltipTemplate: ({ event, resource, duration }) =>
    `${event.title}\n${resource?.name ?? 'Unassigned'}\n${duration} minutes`,
};
```

## Custom day header

```ts
grid.eventScheduler = {
  ...grid.eventScheduler,
  dayHeaderFormatter: (date) =>
    new Intl.DateTimeFormat('en-US', {
      weekday: 'short',
      month: 'short',
      day: 'numeric',
      timeZone: 'UTC',
    }).format(date),
  dayHeaderTemplate: (h, context) =>
    h('span', { class: 'planner-day-header' }, [
      h('strong', null, context.defaultLabel),
      context.today ? h('span', { class: 'planner-day-header__badge' }, 'Today') : null,
      context.holiday ? h('span', { class: 'planner-day-header__holiday' }, context.holidayLabel) : null,
      h('small', null, `${context.eventCount ?? 0} events`),
    ]),
  dayHeaderProperties: ({ today, weekend, holiday }) => ({
    class: [
      today ? 'planner-day-header--today' : '',
      weekend ? 'planner-day-header--weekend' : '',
      holiday ? 'planner-day-header--holiday' : '',
    ].filter(Boolean).join(' '),
  }),
};
```

## Custom slot context menu

```ts
grid.eventScheduler = {
  ...grid.eventScheduler,
  contextMenu: {
    enabled: true,
    getSlotContextMenuItems: ({ slot }) => slot
      ? [
          {
            id: 'create-booking',
            label: 'Create booking here',
            shortcut: 'C',
            action: () => createBooking(slot),
          },
          {
            id: 'hold-slot',
            label: 'Block this time',
            group: 'availability',
            action: () => createHold(slot),
          },
        ]
      : [],
    onContextMenuAction: ({ itemId, target, slot }) =>
      analytics.track('scheduler_menu_action', { itemId, target, slot }),
  },
};
```

## Custom current time marker

```ts
grid.eventScheduler = {
  ...grid.eventScheduler,
  showCurrentTimeMarker: true,
  currentTimeUpdateInterval: 60_000,
  currentTimeLabelFormatter: ({ dateTime }) =>
    new Intl.DateTimeFormat('en-US', {
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date(dateTime)),
  currentTimeMarkerProperties: ({ orientation }) => ({
    class: `planner-now planner-now--${orientation}`,
    style: {
      '--event-scheduler-current-time-color': '#dc2626',
    },
  }),
  currentTimeMarkerTemplate: (h, { label }) =>
    h('span', { class: 'planner-now__label' }, label),
};
```

## Closed hours and availability

```ts
grid.eventScheduler = {
  ...grid.eventScheduler,
  workingHours: {
    byDay: {
      1: { start: '08:00', end: '18:00' },
      2: { start: '08:00', end: '18:00' },
      3: { start: '08:00', end: '18:00' },
      4: { start: '08:00', end: '18:00' },
      5: { start: '08:00', end: '16:00' },
      0: false,
      6: false,
    },
  },
  closedHours: [
    {
      id: 'lunch',
      days: [1, 2, 3, 4, 5],
      ranges: { start: '12:00', end: '13:00' },
      title: 'Closed',
      reason: 'Lunch break',
    },
  ],
  closedSlotTooltip: ({ title, reason }) =>
    [title, reason].filter(Boolean).join(' - '),
  closedSlotTemplate: (h, { reason }) =>
    h('span', { class: 'planner-slot__closed' }, reason ?? 'Closed'),
  isTimeSlotAvailable: ({ date, startMinutes }) =>
    date !== '2026-06-19' && startMinutes >= 8 * 60,
};
```

## Read-only mode

```ts
grid.eventScheduler = {
  ...grid.eventScheduler,
  editable: false,
  allowCreate: false,
  allowMove: false,
  allowResize: false,
  allowDelete: false,
  keyboardShortcuts: {
    enabled: true,
    shortcuts: {
      copy: 'Mod+c',
      paste: false,
      duplicate: false,
      delete: false,
      lock: false,
    },
  },
};
```

Read-only mode keeps rendering, selection, tooltips, context menus, and custom templates active while blocking scheduler mutations.

## Cancelable selection state

```ts
let selectedEventIds: readonly string[] = [];

grid.addEventListener('event-scheduler-before-event-select', (event) => {
  event.preventDefault();
  selectedEventIds = event.detail.eventIds.map(String);
  renderScheduler();
});

function renderScheduler() {
  grid.eventScheduler = {
    ...grid.eventScheduler,
    selectionMode: 'multiple',
    selection: {
      selectedEventIds,
      clipboard: true,
      onChange: ({ eventIds }) => {
        selectedEventIds = eventIds.map(String);
        renderScheduler();
      },
    },
    onSelectionChange: ({ events }) =>
      inspector.show(events),
    onEventMove: ({ events }) => {
      grid.source = [...events];
      void saveEvents(events);
    },
  };
}
```

Use the before-select event when selection lives in application state. Prevent the pending scheduler selection, update host state, then pass the accepted ids back through `selection.selectedEventIds`. Event arrays, visible ranges, and filters follow the same ownership model: the scheduler emits callbacks and the host updates `eventScheduler`, `source`, and related props.

## Custom styling and theme

```css
.booking-scheduler revo-grid {
  --event-scheduler-accent: #0f766e;
  --event-scheduler-accent-soft: #ccfbf1;
  --event-scheduler-grid-line: #d8dee6;
  --event-scheduler-current-time-color: #dc2626;
  --event-scheduler-weekend-bg: rgba(15, 118, 110, 0.05);
  --event-scheduler-event-bg: #eef7f3;
  --event-scheduler-event-color: #0f766e;
}

.planner-event--conflict {
  --event-scheduler-event-color: #b45309;
  --event-scheduler-event-bg: #fff7ed;
}

.planner-day-header--today {
  box-shadow: inset 0 -2px 0 var(--event-scheduler-accent);
}
```

Use CSS variables for broad theme changes. Use `eventProperties`, `dayHeaderProperties`, `slotProperties`, `closedSlotProperties`, and `currentTimeMarkerProperties` when styling depends on scheduler state.

## Related guides

- [Week View](../week-view/) covers day/time configuration, visible range, week start, locale, timezone, and edit ownership.
- [Customization](../customization/) documents the full visual customization category. Use [Event Rendering](../customization/events/) for templates and tooltips, [Slots, Hours, and Markers](../customization/slots-hours/) for slot and current-time examples, [Context Menus](../customization/context-menu/) for commands, and [Styling and Themes](../customization/styling/) for CSS hooks.
- [Availability](../scheduling-rules/availability/) covers calendars, working hours, blocked time, breaks, holidays, and outside-hours styling.
- [Editing and Interaction](../event-editing/) covers read-only mode, permissions, cancelable hooks, mutation events, selection, clipboard, keyboard shortcuts, custom editors, and persistence.

---

# Export

URL: https://pro.rv-grid.com/guides/event-scheduler/export/
Source: src/content/docs/guides/event-scheduler/export.mdx
Description: Export scheduler events, workload, conflicts, coverage gaps, visible schedules, and print views.

The event scheduler exports data from the current projection, so filters, visible resources, conflicts, coverage, and utilization match what the user is reviewing.

```ts
const scheduler = (await grid.getPlugins()).find(
  (plugin) => plugin.constructor?.name === 'EventSchedulerPlugin',
);

const projection = scheduler.getProjection();

const eventsCsv = scheduler.exportEvents({ format: 'csv' });
const workloadJson = scheduler.exportResourceWorkload({ format: 'json' });
const conflictsCsv = scheduler.exportConflicts({ format: 'csv' });
const coverageCsv = scheduler.exportCoverage({ format: 'csv', gapsOnly: true });
const visibleCsv = scheduler.exportVisibleSchedule({ format: 'csv' });

download(eventsCsv.content, eventsCsv.fileName, eventsCsv.mimeType);
```

For printable schedules, create an HTML view from the same projection.

```ts
const print = scheduler.createPrintView({
  title: 'Weekly Staff Schedule',
  includeEvents: true,
  includeWorkload: true,
  includeConflicts: true,
  includeCoverage: true,
});

const printWindow = window.open('', '_blank');
printWindow?.document.write(print.html);
printWindow?.print();
```

## Production Checklist

- Use stable ids for events, resources, assignments, templates, and coverage requirements.
- Store scheduler datetimes as ISO strings and define a product time-zone policy before persisting user edits.
- Keep `source` controlled by app state and persist every created, changed, and deleted event array.
- Enable `allowCreate` intentionally. It defaults to false.
- Add permission rules for locked resources, read-only events, completed statuses, and protected date ranges.
- Choose conflict policy deliberately. Use `prevent` or error rules for hard booking constraints.
- Use availability for real scheduling constraints and `nonWorkingTime` for visual closed-time guidance.
- Use `resourceGrouping`, `filters`, and `savedViews` for planner navigation instead of mutating source arrays.
- Use `coverage` and `utilization` only when the resource metadata needed for planning is present.
- Add remote validation and rollback for server-backed schedulers.
- Keep keyboard shortcuts enabled unless the host app owns all scheduler keyboard behavior.
- Expose export or print workflows from the plugin projection when planners need to share schedules.
- Test drag-create, move, resize, delete, selection, keyboard shortcuts, conflicts, and remote failure paths in the target framework.

---

# Grouping

URL: https://pro.rv-grid.com/guides/event-scheduler/grouping/
Source: src/content/docs/guides/event-scheduler/grouping.mdx
Description: Group scheduler resources by team, department, location, parent tree, or custom business rules.

Use `resourceGrouping` for team, department, location, room-building, machine-line, or sprint-team grouping. Parent-child resources can render as a tree.

```ts
grid.eventSchedulerResources = [
  { id: 'north', name: 'North Campus', role: 'Location' },
  { id: 'room-a', parentId: 'north', name: 'Room A', role: 'Room', metadata: { floor: '1' } },
  { id: 'room-b', parentId: 'north', name: 'Room B', role: 'Room', metadata: { floor: '2' } },
];

grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  resourceGrouping: {
    enabled: true,
    tree: true,
    groupBy: (resource) => String(resource.metadata?.floor ?? resource.group ?? 'Other'),
    groupSummaryFormatter: ({ summary }) =>
      `${summary.eventCount} events - ${summary.totalHours}h`,
  },
};
```

Group rows aggregate workload, coverage, and utilization summaries when those features are enabled.

## Resource Planner Patterns

Use `resourceTimeline` when resources are the main rows and time moves horizontally.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  dateRange: { start: '2026-06-08', end: '2026-06-14' },
  resourceColumnSize: 220,
  timelineColumnSize: 72,
  resourceGrouping: {
    enabled: true,
    groupBy: (resource) => resource.metadata?.location as string,
    tree: true,
    collapsed: false,
    groupSummaryFormatter: ({ summary }) =>
      `${summary.eventCount} events - ${summary.totalHours}h`,
  },
  resourceMetaFormatter: (resource) =>
    [resource.role, resource.metadata?.location].filter(Boolean).join(' - '),
};
```

Events without `resourceId`, `resourceIds`, or side-channel assignments render in the generated unassigned row when `unassigned.enabled` is not false.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  unassigned: {
    enabled: true,
    showCount: true,
    requiredRoleField: 'metadata.requiredRole',
    filter: { status: ['draft', 'planned'], role: 'Technician' },
    counterFormatter: (summary) => `${summary.visibleCount} open requests`,
    requiredRoleFormatter: ({ role }) => `Need ${role}`,
    assignmentValidator: ({ event, resource }) => {
      const required = event.metadata?.requiredRole;
      const skills = Array.isArray(resource.metadata?.skills)
        ? resource.metadata.skills
        : [];
      return !required || skills.includes(required) || `${resource.name} cannot fill ${required}.`;
    },
  },
};
```

Coverage compares required capacity with assigned event capacity in the visible range. Utilization calculates scheduled workload by resource.

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  coverage: {
    enabled: true,
    capacityField: 'capacity',
    countEvent: ({ event, resource }) =>
      event.status === 'cancelled' ? false : resource.capacity ?? 1,
  },
  utilization: {
    enabled: true,
    minHoursField: 'metadata.minHoursPerWeek',
    targetHoursField: 'metadata.targetHoursPerWeek',
    maxHoursField: 'metadata.maxHoursPerWeek',
    excludeStatuses: ['cancelled', 'blocked'],
  },
};
```

Use `filters` and `savedViews` to reduce projected data without mutating source arrays:

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  filters: {
    search: 'security',
    resourceRoles: 'Security',
    eventStatuses: ['planned', 'confirmed'],
    conflictsOnly: false,
    unassignedOnly: false,
  },
  activeSavedViewId: 'security-week',
  savedViews: {
    views: [
      { id: 'conflicts', label: 'Conflicts only', filters: { conflictsOnly: true } },
      { id: 'unassigned', label: 'Unassigned', filters: { unassignedOnly: true } },
      {
        id: 'security-week',
        label: 'Security team',
        dateRange: { start: '2026-06-08', end: '2026-06-12' },
        filters: { resourceRoles: 'Security' },
      },
    ],
  },
};
```

The projection exposes `filterSummary` with visible and hidden resource/event counts.

---

# Getting Started

URL: https://pro.rv-grid.com/guides/event-scheduler/introduction/
Source: src/content/docs/guides/event-scheduler/introduction/index.mdx
Description: Set up the standalone RevoGrid Event Scheduler for staff scheduling, shift planning, room booking, equipment planning, and team calendars.

`EventSchedulerPlugin` from `@revolist/scheduler` turns RevoGrid into a commercial scheduler for events on time grids. Use it for staff rosters, employee shifts, room reservations, machine plans, field crews, support queues, and sprint capacity.

The scheduler supports calendar and resource timeline views, editable event blocks, resources, assignments, calendars, availability, conflicts, grouping, templates, recurrence helpers, remote data, custom renderers, and export helpers.

## Install

```bash
pnpm add @revolist/revogrid @revolist/revogrid-pro @revolist/scheduler
```

Import the Pro and Scheduler styles once in your application entry:

```ts
import '@revolist/revogrid-pro/dist/revogrid-pro.css';
import '@revolist/scheduler/styles.css';
```

Create an empty grid and provide scheduler data through side-channel props. The scheduler owns the generated grid projection; your app owns persistence.

## Minimal Astro setup

The only required event fields are `id`, `startDateTime`, and `endDateTime`. Add `title`, `resourceId`, `status`, `type`, `metadata`, and resources when your product needs labels, capacity rows, filtering, styling, or persistence fields.

## Minimal TypeScript setup

If the grid already exists in your app, set the same properties directly:

```ts
import { EventSchedulerPlugin } from '@revolist/scheduler';

grid.plugins = [EventSchedulerPlugin];

grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  slotMinutes: 60,
  timeRange: { start: '08:00', end: '18:00' },
};

grid.source = [
  {
    id: 'booking-1',
    startDateTime: '2026-06-08T09:00:00.000Z',
    endDateTime: '2026-06-08T12:00:00.000Z',
  },
];
```

## What Event Scheduler does

Event Scheduler uses RevoGrid as the rendering and interaction surface for time-based planning. Instead of building ordinary data rows and columns yourself, you give the grid scheduler configuration, events, resources, and optional planning datasets. The plugin projects that data into timeline columns, resource rows, event blocks, drag handles, conflict indicators, non-working time, and editor interactions.

Use it when the main question is "who or what is booked, when, and against which capacity?" Common use cases include:

- staff and employee shift scheduling
- room, desk, vehicle, or equipment booking
- machine and production line planning
- field crew, support queue, and service dispatch calendars
- sprint, delivery, or team-capacity calendars

## Core concepts

- `events` are the scheduled blocks. Each event needs an `id`, `startDateTime`, and `endDateTime`. Add `title`, `resourceId`, `resourceIds`, or `assignmentIds` when the event needs a label or belongs to a person, room, machine, team, or other capacity.
- `resources` are the schedulable rows in resource planning. A resource can be a person, room, vehicle, machine, location, team, department, or parent group.
- `views` decide how time is shown. Use `day`, `week`, or `month` for calendar-style time grids, and `resourceTimeline` when each resource needs its own row across a visible date or time range.
- `projection` is the derived scheduler model. The plugin combines config, events, resources, assignments, availability, templates, coverage requirements, and filters into visible rows, columns, event lanes, conflict markers, group summaries, and overlays.
- `source` is the host-owned event input. The scheduler emits authored `gridedit` changes after accepted local, history, and remote mutations so the application can update its source state without triggering source lifecycle events for Scheduler-internal rendering.

## Data ownership

Use the scheduler props as the public data boundary:

- **Events**: Every event needs `id`, `startDateTime`, and `endDateTime`. `title`, `resourceId`, `resourceIds`, `status`, and `type` are optional. Use resource fields for resource timelines or leave them out for unassigned demand.
- **Resources**: Use resources for people, rooms, vehicles, machines, teams, locations, or parent groups. `calendarId`, `capacity`, `group`, `role`, and `metadata` feed calendars, grouping, coverage, utilization, and filters.
- **Assignments**: Use assignments when your system stores event-to-resource links separately from the event record. They are merged with `resourceId` and `resourceIds` during projection.
- **Availability**: Use dated `working`, `blocked`, `holiday`, and `break` windows for operational exceptions such as PTO, maintenance, temporary opening hours, or one-off closures.
- **Templates and coverage**: Use templates for repeated event creation and coverage requirements for required capacity/headcount checks.

`locked` and `readonly` events or resources reject normal edit flows. `color`, `className`, `status`, `type`, `category`, and `metadata` let products style, classify, filter, or persist scheduler records without replacing the scheduler model.

## Main props

- **`eventScheduler`**: Main `EventSchedulerConfig`. Controls the active view, visible date range, slot size, visible hours, editing permissions, event layout, conflicts, calendars, filters, labels, formatters, templates, remote loading, and customization hooks.
- **`source`**: The event blocks to render. Events contain stable ids and start/end datetimes, plus optional titles, status/type metadata, and resource or assignment links.
- **`eventSchedulerResources`**: The schedulable resources shown in resource-timeline flows. Use it for people, rooms, machines, teams, locations, vehicles, or parent groups.
- **`eventSchedulerAssignments`**: Optional assignment link data when events and resources are connected by a separate system table instead of direct `resourceId` fields.
- **`eventSchedulerAvailability`**: Optional working, blocked, holiday, or break windows for resource-specific availability and outside-availability conflict checks.
- **`eventSchedulerTemplates`**: Optional reusable event templates for quick creation and recurrence helpers.
- **`eventSchedulerCoverageRequirements`**: Optional staffing or capacity requirements used by coverage summaries and gap highlighting.
- **`columns`**: Usually empty for scheduler pages. The scheduler owns visual rows and columns internally while `source` remains the host-owned event input.

If application records use different property names, map the shared view meanings
once in `eventScheduler.fields`. The same mapping vocabulary is intended for
Scheduler, Gantt, and Kanban:

```ts
grid.eventScheduler = {
  weekStartDate: '2026-09-14',
  fields: {
    id: 'id',
    title: 'name',
    status: 'workflowStatus',
    start: 'startDate',
    end: 'endDate',
    color: 'color',
    progress: 'percentDone',
    resourceId: 'owner',
  },
};
```

Mappings select direct source properties and do not convert values. Scheduler
reads and writes the mapped fields while preserving other application fields.
`progress` is accepted so one mapping object can be shared by views; Scheduler
preserves it but does not render or edit progress.

Scheduler treats source rows as immutable. When it materializes an authored
mutation, unchanged rows keep their original references and only changed or
created rows are allocated. Replace application rows or the source array when
state changes; do not mutate source row objects in place. History uses shallow
array snapshots over those immutable rows so deleted records and custom fields
remain available to undo without cloning the complete schedule.

## Basic setup

```ts
import {
  EventSchedulerPlugin,
  type EventSchedulerConfig,
  type EventSchedulerEventEntity,
  type EventSchedulerResourceEntity,
} from '@revolist/scheduler';

const resources: EventSchedulerResourceEntity[] = [
  { id: 'room-a', name: 'Room A', role: 'Room', group: 'Conference' },
  { id: 'room-b', name: 'Room B', role: 'Room', group: 'Conference' },
];

const events: EventSchedulerEventEntity[] = [
  {
    id: 'booking-1',
    startDateTime: '2026-06-08T09:00:00.000Z',
    endDateTime: '2026-06-08T12:00:00.000Z',
    title: 'Customer workshop',
    resourceId: 'room-a',
    status: 'confirmed',
    type: 'booking',
  },
];

const eventScheduler: EventSchedulerConfig = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  dateRange: { start: '2026-06-08', end: '2026-06-08' },
  slotMinutes: 60,
  timeRange: { start: '08:00', end: '18:00' },
  editable: true,
  allowCreate: true,
  allowMove: true,
  allowResize: true,
  conflicts: { enabled: true, policy: 'mark', scope: 'same-resource' },
};

grid.plugins = [EventSchedulerPlugin];
grid.eventScheduler = eventScheduler;
grid.eventSchedulerResources = resources;
grid.source = events;
grid.columns = [];
```

For framework wrappers, bind `eventScheduler`, `eventSchedulerResources`, and `source` as grid properties.

## Blocking overlap and conflicts

Existing data can still render with conflict markers so users can review and fix it. To block future overlapping create, move, resize, and edit actions for the same resource, keep the scheduler in mark mode and promote only `overlap` to an error:

```ts
grid.eventScheduler = {
  ...grid.eventScheduler,
  conflicts: {
    enabled: true,
    policy: 'mark',
    scope: 'same-resource',
    rules: { overlap: 'error' },
  },
};
```

Error conflicts render with the built-in red conflict state. The same conflict result is used by the mutation pipeline, so an overlap introduced by create, move, resize, or edit is rejected before local events are committed.

## Where to start

1. Choose the view. Use `week` for a shift-style calendar, or `resourceTimeline` when each resource needs a row.
2. Define the visible range with `weekStartDate`, `dateRange`, `visibleDays`, `slotMinutes`, and `timeRange`.
3. Provide `eventSchedulerResources` when events need to be placed against staff, rooms, equipment, teams, or other capacity.
4. Provide `source` with ISO datetime strings and stable ids.
5. Add `calendars` for recurring working rules and `eventSchedulerAvailability` for dated working windows, breaks, holidays, or blocked time.
6. Enable editing only when the host app handles emitted changes. Start with `editable: false` for read-only schedules, then turn on `allowCreate`, `allowMove`, `allowResize`, and `allowDelete` as your persistence flow is ready.
7. Add conflict rules, templates, remote data, custom labels, or renderers after the basic schedule renders.

## Handling edits

The scheduler emits a cancelable before-change event before it commits local event changes. This follows the RevoGrid event pattern: call `preventDefault()` on the before event to cancel the mutation.

```ts
grid.addEventListener('event-scheduler-before-event-change', (event) => {
  if (event.detail.event?.locked) {
    event.preventDefault();
  }
});
```

`event-scheduler-event-created`, `event-scheduler-event-changed`, and `event-scheduler-event-deleted` fire after the mutation succeeds and after `grid.source` has been updated. Use them for persistence and framework state sync, not cancellation:

```ts
const syncEvents = (event: Event) => {
  const events = (event as CustomEvent<{ events: readonly EventSchedulerEventEntity[] }>).detail.events;
  setApplicationEvents([...events]);
  void saveSchedule(events);
};

grid.addEventListener('event-scheduler-event-created', syncEvents);
grid.addEventListener('event-scheduler-event-changed', syncEvents);
grid.addEventListener('event-scheduler-event-deleted', syncEvents);
```

If your toolbar owns the current range or active view, also handle navigation and view requests:

```ts
grid.addEventListener('event-scheduler-navigate-request', (event) => {
  const { action } = (event as CustomEvent<{ action: 'previous' | 'next' | 'today' }>).detail;
  // Update weekStartDate/dateRange in grid.eventScheduler here.
});

grid.addEventListener('event-scheduler-view-request', (event) => {
  const { view } = (event as CustomEvent<{ view: EventSchedulerConfig['view'] }>).detail;
  // Update grid.eventScheduler.view here.
});
```

For remote products, use the same ownership model: the scheduler can optimistically emit changes, but your app or `remote` hooks decide when backend mutations are committed, rejected, or rolled back.

## Next guides

- [Vertical vs Horizontal Time](./vertical-vs-horizontal/) helps choose between calendar-style and resource-timeline scheduling.
- [Timeline Views](../timeline-views/) explains day, week, month, and resource timeline configuration.
- [Week View](../week-view/) is a practical recipe for shift-style vertical week calendars.
- [Editing and Interaction](../event-editing/) covers create, move, resize, delete, editors, selection, clipboard, keyboard shortcuts, permissions, and validation.
- [Conflicts](../scheduling-rules/conflicts/) covers overlap, availability, locked-change, duration, capacity, prevention events, and assignment checks.
- [Event Scheduler Calendars](../scheduling-rules/calendars/) covers working days, holidays, and resource-specific operating hours.
- [Scheduling Rules](../scheduling-rules/) explains how calendars, availability, visual non-working time, and conflict policies work together.
- [Remote Data](../remote-data/) covers loading ranges, optimistic mutations, rollback, and load-more flows.
- [Customization](../customization/) groups labels, event rendering, layout/cells, slots/hours, conflicts/states, context menus, styling, interaction, and editor hooks.
- [Examples](../examples/) collects small product-neutral examples for setup, event templates, day headers, slots, current-time markers, context menus, availability, read-only mode, cancelable selection state, and custom themes.

Start with the Event Staff Scheduler demo for the full business story, or the Employee Shift Planner demo for a focused week-view shift workflow.

---

# Vertical vs Horizontal Time

URL: https://pro.rv-grid.com/guides/event-scheduler/introduction/vertical-vs-horizontal/
Source: src/content/docs/guides/event-scheduler/introduction/vertical-vs-horizontal.mdx
Description: Choose between calendar-style vertical scheduling and resource timeline scheduling.

Scheduling views usually answer one of three questions:

- "What happens during this day or week?"
- "What is happening across this month or year?"
- "Which resource is booked across this date range?"

Use a vertical time view for the first question, a calendar view for the second, and a horizontal resource timeline for the third.

## Vertical Time Scheduling

Vertical time scheduling is the familiar calendar layout. Time moves down the page, days are arranged across columns, and an event duration is shown by the event height.

This layout is best when users think in days, hours, and appointments:

| Good fit | Why |
| :-- | :-- |
| Staff shifts | Managers scan a day or week and adjust start/end times. |
| Appointments | Users compare open slots in a familiar calendar shape. |
| Room bookings for one location | The day is more important than a long resource list. |
| Personal or team calendars | The main task is finding a time window. |

Configure it with `day` or `week` views:

```ts
const verticalWeek = {
  view: 'week',
  weekStartDate: '2026-06-08',
  visibleDays: [1, 2, 3, 4, 5],
  slotMinutes: 30,
  timeRange: { start: '08:00', end: '18:00' },
  timeColumnSize: 88,
  dayColumnSize: 180,
};
```

Choose vertical time when the primary action is creating, moving, or resizing events inside a day or week.

## Calendar Overview

Use `month` for a conventional seven-column calendar with whole-day creation and day-preserving move/resize interactions. Use `year` for a twelve-mini-month overview that drills down by emitting a controlled month-view request. Calendar rows fill the data viewport, while the shared scheduler model continues to supply recurrence, filtering, availability, conflicts, selection, and event customization.

```ts
const calendarOverview = {
  view: 'month', // change to 'year' for the twelve-month overview
  weekStartDate: '2026-07-15',
  weekStartsOn: 1,
};
```

## Horizontal Resource Timeline

Horizontal scheduling puts resources on rows and time on columns. Time moves left to right, and an event duration is shown by the event width.

This layout is best when users compare many resources over the same window:

| Good fit | Why |
| :-- | :-- |
| Multi-room booking | Rooms stay fixed on the left while the schedule scrolls horizontally. |
| Equipment planning | Users compare utilization across machines, vehicles, or tools. |
| Field crews | Dispatchers see who is available across several days. |
| Open demand planning | Unassigned work can sit beside staffed resources. |

Configure it with `resourceTimeline`:

```ts
const horizontalTimeline = {
  view: 'resourceTimeline',
  dateRange: { start: '2026-06-08', end: '2026-06-12' },
  slotMinutes: 60,
  timeRange: { start: '08:00', end: '18:00' },
  resourceColumnSize: 240,
  timelineColumnSize: 72,
};
```

Choose a horizontal timeline when the primary action is comparing capacity, coverage, and conflicts across resources.

## Same Data, Different Projection

Both orientations use the same scheduler data:

- events define the booked work
- resources define people, rooms, machines, or teams
- assignments connect events to resources when the model needs many-to-many scheduling
- availability, calendars, conflicts, templates, and remote loading work across both layouts

The difference is projection. Vertical views emphasize time within a day or week, calendar views emphasize dates across a month or year, and horizontal views emphasize resources across a date range.

## Choosing a Default

Start with vertical time scheduling when users mostly edit individual events and think in daily calendars.

Start with a horizontal resource timeline when users mostly compare many resources, load large schedules from a server, or need coverage and utilization signals.

Many applications expose both. For example, a shift planner can use a week view for fast editing and a resource timeline for staffing coverage.

---

# Remote Data

URL: https://pro.rv-grid.com/guides/event-scheduler/remote-data/
Source: src/content/docs/guides/event-scheduler/remote-data.mdx
Description: Load scheduler resources and events from a server, refresh visible ranges, and handle optimistic save failures.

Use `remote` when events or resources are too large to ship up front, or when the scheduler must load only the visible date range.

For a comparison of host-owned full saves, host-owned incremental saves, and remote-backed saves, see [Data ownership and save flows](/guides/event-scheduler/event-editing/#data-ownership-and-save-flows).

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  remote: {
    enabled: true,
    loadEvents: async ({ dateRange, resourceIds }) => {
      const params = new URLSearchParams({
        start: dateRange.start,
        end: dateRange.end,
        resources: resourceIds?.join(',') ?? '',
      });
      const response = await fetch(`/api/scheduler/events?${params}`);
      return { events: await response.json() };
    },
    loadResources: async () => {
      const response = await fetch('/api/scheduler/resources');
      return { resources: await response.json() };
    },
    commitMutation: async (request) => {
      const response = await fetch('/api/scheduler/mutations', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(request),
      });
      if (!response.ok) {
        throw new Error('Save failed');
      }
      return { accepted: true, events: await response.json() };
    },
  },
};
```

The resource timeline demo includes remote-mode controls for refresh, load-more resources, and simulated save failure.

## Remote Options and State

Remote mode can load events, resources, availability, unassigned demand, and coverage for the visible range. It can also validate and commit accepted mutations.

```ts
const eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  dateRange: { start: '2026-06-08', end: '2026-06-14' },
  remote: {
    enabled: true,
    mode: 'remote',
    debounceMs: 150,
    overscanDays: 1,
    resourcePageSize: 50,
    loadEvents: ({ dateRange, filters, signal }) =>
      api.loadEvents({ dateRange, filters }, { signal }),
    loadResources: ({ cursor, limit, signal }) =>
      api.loadResources({ cursor, limit }, { signal }),
    loadAvailability: ({ dateRange, signal }) =>
      api.loadAvailability({ dateRange }, { signal }),
    loadCoverage: ({ dateRange, signal }) =>
      api.loadCoverage({ dateRange }, { signal }),
    validateMutation: ({ action, event, previousEvent }) =>
      api.validateScheduleChange({ action, event, previousEvent }),
    commitMutation: ({ action, event, previousEvent, events }) =>
      api.saveScheduleChange({ action, event, previousEvent, events }),
    optimistic: true,
    rollbackOnError: true,
    refreshPolicy: 'visible-range',
  },
};
```

Remote modes:

| Mode | Behavior |
| :-- | :-- |
| `local` | Remote controller is effectively off unless enabled hooks are used by the host. |
| `remote` | Visible data is loaded through remote hooks. |
| `hybrid` | Host can combine local side-channel data with remote range data. |

Remote state is available from `scheduler.getRemoteState()`. The plugin emits:

| Event | Purpose |
| :-- | :-- |
| `event-scheduler-remote-load-start` | A visible-range load begins. |
| `event-scheduler-remote-load-success` | A load target resolves. |
| `event-scheduler-remote-load-error` | A load target fails. |
| `event-scheduler-remote-mutation-pending` | A remote mutation starts. |
| `event-scheduler-remote-mutation-committed` | The backend accepts a mutation. |
| `event-scheduler-remote-mutation-rejected` | The backend rejects a mutation. |
| `event-scheduler-remote-state-change` | Loading, error, pending, paging, or empty state changes. |

Use `scheduler.refreshVisibleRange()` to reload the current range and `scheduler.loadMoreResources()` when paged resources report `hasMoreResources`.

---

# Scheduling Rules

URL: https://pro.rv-grid.com/guides/event-scheduler/scheduling-rules/
Source: src/content/docs/guides/event-scheduler/scheduling-rules/index.mdx
Description: Understand how Event Scheduler combines availability, calendars, and conflict policies into scheduling rules.

Event Scheduler separates the source of a scheduling rule from the way that rule is enforced. Availability and calendars describe when a resource can be used. Conflict settings decide whether a violation is shown as a warning, ignored, confirmed, or rejected.

This matters because closed time is not a single setting. A lunch break, a public holiday, an operating calendar, and a one-off shift extension all participate in the same conflict model, but they do not have the same precedence.

## Start With The Outcome

Most applications choose one of these setups:

| Goal | Configuration |
| :-- | :-- |
| Show conflicts but allow the user to save | `conflicts: { enabled: true, policy: 'mark' }` |
| Block every detected conflict | `conflicts: { enabled: true, policy: 'prevent' }` |
| Block only selected conflict types | `conflicts: { enabled: true, policy: 'mark', rules: { ... } }` |
| Turn conflict detection off | `conflicts: { enabled: false }` |

Use `rules` when different mistakes need different behavior:

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  conflicts: {
    enabled: true,
    policy: 'mark',
    rules: {
      overlap: 'error',
      'outside-availability': 'error',
      'blocked-time': 'error',
    },
  },
};
```

In this example:

- `overlap: 'error'` rejects an event when it overlaps another event in the same resource row.
- `'outside-availability': 'error'` rejects an event when it is outside the resource's working time.
- `'blocked-time': 'error'` rejects an event when it touches a blocked, holiday, or break window.

`error` means the local scheduler mutation is not committed for the changed event. Create, move, resize, edit, paste, template, recurrence, and bulk changes are checked against the projected next schedule before the event list is updated. Existing unrelated conflicts can remain on screen; they do not block an unrelated edit unless the edited event is part of a blocking conflict.

If you only want to display a conflict, use `warning`. If you want to hide a conflict from scheduler results, use `ignore`. If you want to require a custom confirmation flow, use `confirm`.

## Rule Names

The three most common rule names answer different user questions:

| Rule | User-facing meaning | Triggered by | Typical setting |
| :-- | :-- | :-- | :-- |
| `overlap` | "This booking collides with another booking." | Two visible event segments overlap on the same date. By default this is checked within the same resource. | Use `warning` when overlaps are allowed but should be visible. Use `error` for rooms, equipment, or people that cannot be double-booked. |
| `outside-availability` | "This booking is outside allowed working time." | The event is not fully covered by a dated `kind: 'working'` availability entry, or by the resolved calendar when no dated working availability applies. | Use `error` when users must schedule only inside shifts, operating hours, or resource calendars. |
| `blocked-time` | "This booking touches unavailable time." | The event overlaps a matching `kind: 'blocked'`, `kind: 'holiday'`, or `kind: 'break'` availability entry. | Use `error` for PTO, maintenance, lunch breaks, holidays, freezes, and other hard closures. |

The policy value attached to each rule controls enforcement:

| Rule policy | What the user sees | Does it block the local change? |
| :-- | :-- | :-- |
| `warning` | Conflict styling and conflict data with warning severity. | No. |
| `error` | Conflict styling and conflict data with error severity. | Yes, when the changed event is part of that conflict. |
| `confirm` | Conflict data with confirm severity for custom confirmation handling. | No automatic blocking by the conflict engine. Use mutation events or `validateMutation` if your app should stop the change until the user confirms. |
| `allow` | Conflict data stays visible as a warning. | No. |
| `ignore` | Conflict is removed from visible conflict results. | No. |

## Rule Inputs

The scheduler uses these inputs when it decides whether an event is valid for a resource and time range:

| Input | Purpose |
| :-- | :-- |
| `eventSchedulerAvailability` | Dated working, blocked, holiday, or break intervals. Use it for operational data that happens on specific dates. |
| `eventScheduler.calendars` | Recurring working days, holidays, working hours, and per-resource calendar resolution. Use it for the normal schedule baseline. |
| `eventScheduler.conflicts` | Converts detected conflicts into warnings, blocking errors, confirmation states, or ignored results. |
| `eventScheduler.nonWorkingTime` | Visual closed-cell styling for simple schedules. It does not create blocking conflicts by itself. |

Use availability when the answer depends on a date, such as PTO, maintenance, a temporary room closure, or an extra working shift. Use calendars when the answer is recurring, such as weekday business hours or a weekend crew calendar.

## Availability Kinds

`eventSchedulerAvailability` entries use `EventSchedulerAvailabilityKind`:

| Kind | Meaning | Conflict behavior |
| :-- | :-- | :-- |
| `working` | A dated interval where matching resources are available. | If any matching `working` availability exists for the resource/date, the event must be fully covered by matching working intervals or it receives `outside-availability`. |
| `blocked` | A dated unavailable interval, often for maintenance, holds, or PTO. | Events that overlap it receive `blocked-time`. |
| `holiday` | A dated unavailable interval for holiday closure or non-operating time. | Events that overlap it receive `blocked-time`. |
| `break` | A dated unavailable interval inside an otherwise working day. | Events that overlap it receive `blocked-time`. |

Unavailable entries are checked by overlap. If an event touches a matching `blocked`, `holiday`, or `break` interval, the scheduler raises a `blocked-time` conflict for the overlapping part.

Working entries are checked by coverage. If an event runs from `09:00` to `13:00`, the matching `working` availability must cover that whole range. A `09:00` to `12:00` working interval is not enough; the uncovered `12:00` to `13:00` portion creates an `outside-availability` conflict.

## Precedence

For each visible event segment, Event Scheduler applies rules in this order:

1. Check matching unavailable availability entries.
2. Check matching dated `kind: 'working'` availability for that resource/date.
3. If no dated working availability matches, check the resolved calendar.
4. Apply conflict policy and per-type rules to decide whether the detected conflict is shown or blocks the mutation.

Unavailable availability is always considered. Dated working availability is more specific than calendars for outside-availability checks. Calendars are the fallback only when no matching dated `kind: 'working'` availability exists for that resource/date.

This means a dated working entry can narrow or extend the calendar for that date. If a room normally follows a `08:00` to `18:00` calendar but has a dated `working` entry from `10:00` to `14:00`, events for that room/date must be covered by `10:00` to `14:00`. The calendar does not fill the rest of the day for outside-availability checks.

## Resource Matching

Availability can be global or resource-specific:

```ts
grid.eventSchedulerAvailability = [
  {
    id: 'all-hands-break',
    kind: 'break',
    title: 'Company break',
    startDateTime: '2026-06-08T12:00:00.000Z',
    endDateTime: '2026-06-08T13:00:00.000Z',
  },
  {
    id: 'room-a-maintenance',
    resourceId: 'room-a',
    kind: 'blocked',
    title: 'Projector maintenance',
    startDateTime: '2026-06-08T15:00:00.000Z',
    endDateTime: '2026-06-08T16:00:00.000Z',
  },
  {
    id: 'training-team-shift',
    resourceIds: ['trainer-a', 'trainer-b'],
    kind: 'working',
    title: 'Training shift',
    startDateTime: '2026-06-08T10:00:00.000Z',
    endDateTime: '2026-06-08T18:00:00.000Z',
  },
];
```

An availability entry without `resourceId` or `resourceIds` applies globally. An entry with `resourceId` applies to that one resource. An entry with `resourceIds` applies to any listed resource.

Calendars resolve per resource in this order:

1. `resource.calendarId`
2. `eventScheduler.calendars.resourceCalendarId(resource)`
3. `eventScheduler.calendars.primaryCalendarId`

If calendar resolution finds no calendar, calendar-based `outside-availability` checks are skipped for that resource/date. Availability rules can still create conflicts.

## Conflict Outcomes

Rule detection and mutation blocking are separate steps.

The scheduler first creates conflict records. Each conflict has a `type`, `policy`, `severity`, `message`, related event ids, related segment ids, and date/time metadata. Then the configured policy decides whether that conflict is just reported or whether it prevents a local mutation.

`blocked-time` is raised when an event overlaps matching `kind: 'blocked'`, `kind: 'holiday'`, or `kind: 'break'` availability. The conflict includes the event id, segment id, resource id when available, date, overlapping time range, and the availability id.

`outside-availability` is raised when an event is outside allowed working time. This can come from dated `kind: 'working'` availability or from the resolved calendar fallback.

`overlap` is raised when two events overlap on the same date. With the default `scope: 'same-resource'`, the events must also share the same resource. With `scope: 'global'`, overlaps are detected across resources.

By default, conflict behavior depends on `eventScheduler.conflicts.policy`:

| Policy | Default result |
| :-- | :-- |
| `mark` | Conflicts are warnings. Mutations are allowed unless a rule overrides the type. |
| `prevent` | Conflicts are blocking errors by default. |
| `allow` | Conflicts are ignored unless a rule overrides the type. |

Use `rules` when some conflict types should be stricter than others:

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  conflicts: {
    enabled: true,
    policy: 'mark',
    rules: {
      'outside-availability': 'error',
      'blocked-time': 'error',
      overlap: 'warning',
    },
  },
};
```

With this configuration, outside availability and blocked time reject create, move, resize, and edit mutations. Overlaps remain visible warnings.

You can customize conflict text with `messages`:

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  conflicts: {
    enabled: true,
    policy: 'mark',
    rules: {
      'blocked-time': 'error',
    },
    messages: {
      'blocked-time': 'This slot is closed. Choose another time.',
    },
  },
};
```

## Custom Event Prevention

Conflict rules are the declarative way to stop known scheduler violations. For product-specific checks that do not fit calendars, availability, or built-in conflict types, use the scheduler mutation lifecycle.

The main event-based prevention point is `event-scheduler-before-event-change`. It fires before the local event array is updated. Call `preventDefault()` to cancel the pending create, move, resize, edit, delete, paste, template, recurrence, or bulk mutation:

```ts
grid.addEventListener('event-scheduler-before-event-change', (event) => {
  if (event.detail.action === 'move' && event.detail.event?.status === 'completed') {
    event.preventDefault();
  }
});
```

Use `validateMutation` when you prefer a config-level hook instead of a DOM event. Return `false` or a string message to reject the same pending mutation:

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  validateMutation: ({ changes }) => {
    if (changes?.resourceId === 'locked-room') {
      return 'That room is locked.';
    }
  },
};
```

Do not use final events such as `event-scheduler-event-created`, `event-scheduler-event-changed`, or `event-scheduler-event-deleted` for prevention. Those fire after the scheduler has accepted the change and are meant for persistence and state sync.

For the full local mutation lifecycle, cancelable before events, permission hooks, and persistence events, see [Editing and Interaction](../event-editing/).

## Calendar Fallback

Calendars are the normal baseline when no dated working availability exists:

```ts
import {
  DEFAULT_CALENDAR,
  type CalendarEntity,
} from '@revolist/revogrid-pro';

const weekdayCalendar: CalendarEntity = {
  ...DEFAULT_CALENDAR,
  id: 'weekday',
  name: 'Weekday office hours',
  workingDays: [1, 2, 3, 4, 5],
  workingHours: { start: '08:00', end: '18:00' },
  holidays: ['2026-06-19'],
};

grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  calendars: {
    primaryCalendarId: 'weekday',
    calendars: [weekdayCalendar],
  },
  conflicts: {
    enabled: true,
    rules: { 'outside-availability': 'error' },
  },
};
```

With no matching `kind: 'working'` availability for a resource/date, the calendar decides whether the event is inside working time. An event on a holiday, a closed weekday, or outside `workingHours` receives `outside-availability`.

## Dated Working Overrides Calendar Hours

A dated working entry becomes the outside-availability rule for its matching resource/date:

```ts
grid.eventSchedulerAvailability = [
  {
    id: 'room-a-short-day',
    resourceId: 'room-a',
    kind: 'working',
    title: 'Short operating day',
    startDateTime: '2026-06-08T10:00:00.000Z',
    endDateTime: '2026-06-08T14:00:00.000Z',
  },
];
```

If `room-a` also has a calendar with `08:00` to `18:00` working hours, the dated working entry wins for June 8, 2026. A `09:00` to `10:00` event and a `14:00` to `15:00` event both receive `outside-availability` because the event is not fully covered by the dated working interval. The calendar is not used to fill those hours.

## Lunch Breaks and Blocked Time

Breaks are unavailable windows, not holes in working coverage:

```ts
grid.eventSchedulerAvailability = [
  {
    id: 'nurse-a-shift',
    resourceId: 'nurse-a',
    kind: 'working',
    title: 'Day shift',
    startDateTime: '2026-06-08T08:00:00.000Z',
    endDateTime: '2026-06-08T16:00:00.000Z',
  },
  {
    id: 'nurse-a-lunch',
    resourceId: 'nurse-a',
    kind: 'break',
    title: 'Lunch',
    startDateTime: '2026-06-08T12:00:00.000Z',
    endDateTime: '2026-06-08T12:30:00.000Z',
  },
];
```

An event from `11:30` to `12:30` is covered by the working shift, but it overlaps the lunch break. The result is `blocked-time`, not `outside-availability`.

## Holidays and Maintenance

Use `holiday` and `blocked` for unavailable windows that should conflict even when the calendar or working availability would otherwise allow the event:

```ts
grid.eventSchedulerAvailability = [
  {
    id: 'clinic-holiday',
    kind: 'holiday',
    title: 'Clinic closed',
    startDateTime: '2026-06-19T00:00:00.000Z',
    endDateTime: '2026-06-20T00:00:00.000Z',
  },
  {
    id: 'room-b-maintenance',
    resourceId: 'room-b',
    kind: 'blocked',
    title: 'Equipment maintenance',
    reason: 'Calibration',
    startDateTime: '2026-06-08T13:00:00.000Z',
    endDateTime: '2026-06-08T15:00:00.000Z',
  },
];
```

The holiday applies globally because it has no resource id. The maintenance entry applies only to `room-b`. Events that overlap either entry receive `blocked-time`.

## Split Working Coverage

Multiple working entries can combine to cover one event, but there cannot be a gap:

```ts
grid.eventSchedulerAvailability = [
  {
    id: 'room-c-morning',
    resourceId: 'room-c',
    kind: 'working',
    title: 'Morning setup',
    startDateTime: '2026-06-08T08:00:00.000Z',
    endDateTime: '2026-06-08T12:00:00.000Z',
  },
  {
    id: 'room-c-afternoon',
    resourceId: 'room-c',
    kind: 'working',
    title: 'Afternoon setup',
    startDateTime: '2026-06-08T13:00:00.000Z',
    endDateTime: '2026-06-08T17:00:00.000Z',
  },
];
```

An event from `09:00` to `11:00` is covered. An event from `11:00` to `14:00` is not covered because `12:00` to `13:00` is a gap between working intervals. The scheduler raises `outside-availability` for that event.

If you want the gap to be visibly unavailable and report a more specific conflict, add a `kind: 'break'` entry for the gap. The event will then receive `blocked-time` for the break overlap.

## Visual Non-Working Time

`nonWorkingTime` is useful for simple visual backgrounds:

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  nonWorkingTime: {
    enabled: true,
    workingDays: [1, 2, 3, 4, 5],
    workingHours: { start: '08:00', end: '18:00' },
    className: 'closed-cell',
  },
};
```

This marks closed cells, but it is not the rule source for blocking conflicts. Use `eventScheduler.calendars` or `eventSchedulerAvailability` when outside-working-time edits must produce `outside-availability`, then configure `eventScheduler.conflicts` to decide whether that conflict blocks.

---

# Availability

URL: https://pro.rv-grid.com/guides/event-scheduler/scheduling-rules/availability/
Source: src/content/docs/guides/event-scheduler/scheduling-rules/availability.mdx
Description: Show working time, blocked time, breaks, holidays, and resource-specific availability in Event Scheduler.

Availability entries describe time ranges that are working, blocked, break, or holiday periods. They can apply globally or to specific resources.

For the full precedence model between availability, calendars, and conflict policies, see the [Scheduling Rules overview](../).

```ts
grid.eventSchedulerAvailability = [
  {
    id: 'business-hours',
    kind: 'working',
    title: 'Business hours',
    startDateTime: '2026-06-08T08:00:00.000Z',
    endDateTime: '2026-06-08T18:00:00.000Z',
  },
  {
    id: 'room-a-maintenance',
    resourceId: 'room-a',
    kind: 'blocked',
    title: 'Maintenance',
    reason: 'Projector replacement',
    startDateTime: '2026-06-08T13:00:00.000Z',
    endDateTime: '2026-06-08T15:00:00.000Z',
  },
];

grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  nonWorkingTime: {
    enabled: true,
    workingDays: [1, 2, 3, 4, 5],
    workingHours: { start: '08:00', end: '19:00' },
    className: 'outside-shift-hours',
  },
};
```

Use `nonWorkingTime.workingHours` when the whole scheduler shares one operating window. Slots outside the configured windows are marked as closed/outside working hours and receive the scheduler non-working background. They also expose `data-event-scheduler-non-working="true"` and `data-event-scheduler-availability-reason="Outside working hours"` so apps can inspect or customize the cells without replacing the renderer.

Use named calendars when working hours differ by calendar or resource:

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  calendars: {
    primaryCalendarId: 'hospital-weekday',
    className: 'outside-shift-hours',
    calendars: [{
      id: 'hospital-weekday',
      name: 'Hospital weekday',
      timeZone: 'UTC',
      workingDays: [1, 2, 3, 4, 5],
      workingHours: { start: '08:00', end: '19:00' },
      holidays: [],
      hoursPerDay: 8,
    }],
  },
};
```

## Availability and Calendars

`eventSchedulerAvailability` and `eventScheduler.calendars` can be used together. They are resolved with these rules:

- `kind: 'blocked'`, `kind: 'holiday'`, and `kind: 'break'` entries are unavailable windows. Events that overlap them receive `blocked-time` conflicts.
- `kind: 'working'` entries are dated working windows. If matching working availability exists for a resource on a date, the event must be fully covered by those working intervals or it receives an `outside-availability` conflict.
- Calendars are the fallback for `outside-availability` checks when no matching dated `kind: 'working'` availability exists for that resource/date.

Use calendars for the recurring baseline, such as weekday hours, weekend crews, and resource calendars. Use availability for dated changes, such as extra opening hours, PTO, maintenance, one-off breaks, or temporary closures.

Timeline cells expose availability data attributes so apps can style or inspect availability state without replacing the scheduler renderer.

---

# Calendars

URL: https://pro.rv-grid.com/guides/event-scheduler/scheduling-rules/calendars/
Source: src/content/docs/guides/event-scheduler/scheduling-rules/calendars.mdx
Description: Define working days, holidays, working hours, and per-resource calendars for Event Scheduler.

Calendars describe when work is normally allowed. Event Scheduler uses them to mark closed cells, validate drag/create targets, skip non-working days during rollover, create outside-availability conflicts, and resolve the calendar that applies to a resource.

Use calendars for repeating business rules such as weekday schedules, weekend crews, holiday closures, and resource-specific operating hours. Use availability entries for dated working windows or exceptions such as one-off maintenance, PTO, blocked rooms, or breaks.

For detailed calendar-vs-availability precedence, including how dated working windows override calendar fallback checks, see the [Scheduling Rules overview](../).

Calendars do not automatically reject every edit outside working hours. They provide the working-hours model and produce `outside-availability` conflicts. To make those conflicts block create, move, resize, and edit mutations, configure the conflict rule as an error:

```ts
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  calendars: {
    primaryCalendarId: 'weekday',
    calendars: [weekdayCalendar],
  },
  conflicts: {
    enabled: true,
    rules: { 'outside-availability': 'error' },
  },
};
```

## Calendar Shape

Event Scheduler uses the same `CalendarEntity` shape as Gantt, so calendar definitions can be shared between planning views:

```ts
import { EventSchedulerPlugin } from '@revolist/scheduler';
import {
  DEFAULT_CALENDAR,
  type CalendarEntity,
} from '@revolist/revogrid-pro';

const weekdayCalendar: CalendarEntity = {
  ...DEFAULT_CALENDAR,
  id: 'weekday',
  name: 'Weekday coverage',
  timeZone: 'UTC',
  workingDays: [1, 2, 3, 4, 5],
  holidays: ['2026-06-19'],
  hoursPerDay: 8,
  workingHours: { start: '08:00', end: '18:00' },
};

grid.plugins = [EventSchedulerPlugin];
grid.eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  calendars: {
    primaryCalendarId: 'weekday',
    calendars: [weekdayCalendar],
  },
};
```

`DEFAULT_CALENDAR` is a Monday-Friday UTC calendar with no holidays and `hoursPerDay: 8`. Spread it when you want the standard defaults and only need to change the id, label, hours, or holidays.

  Calendar `workingDays` use ISO weekday numbers: Monday is `1` and Sunday is `7`. The older `nonWorkingTime.workingDays` option uses JavaScript day indexes, where Sunday is `0` and Saturday is `6`.

## Configuring Scheduler Calendars

Add calendars through `eventScheduler.calendars`:

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  timeRange: { start: '06:00', end: '22:00' },
  calendars: {
    enabled: true,
    primaryCalendarId: 1001,
    className: 'scheduler-closed-cell',
    calendars: [
      {
        ...DEFAULT_CALENDAR,
        id: 1001,
        name: 'Hospital weekday calendar',
        workingHours: { start: '08:00', end: '18:00' },
      },
      {
        ...DEFAULT_CALENDAR,
        id: 1002,
        name: 'Weekend coverage',
        workingDays: [5, 6, 7],
        workingHours: { start: '10:00', end: '20:00' },
      },
    ],
  },
};
```

Calendar ids can be strings or numbers. Internally the scheduler normalizes ids for lookup, so `primaryCalendarId`, resource `calendarId`, and entries in the `calendars` array should refer to the same logical id.

## Per-Resource Calendars

Each resource can point at its own calendar:

```ts
grid.eventSchedulerResources = [
  { id: 'alex', name: 'Alex Kim', role: 'RN', calendarId: 1001 },
  { id: 'weekend-team', name: 'Weekend team', role: 'RN', calendarId: 1002 },
];
```

The resolver order is:

1. `resource.calendarId`
2. `calendars.resourceCalendarId(resource)`
3. `calendars.primaryCalendarId`

Use `resourceCalendarId` when the calendar comes from metadata or an external rules table:

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  calendars: {
    primaryCalendarId: 'weekday',
    calendars,
    resourceCalendarId: (resource) =>
      resource.metadata?.employmentType === 'weekend' ? 'weekend' : undefined,
  },
};
```

## What Calendars Affect

Calendars are applied during projection and interaction:

- Closed days and holidays receive the calendar closed state.
- Slots outside `workingHours` are marked as outside working time.
- Events placed outside the resolved calendar produce an `outside-availability` conflict.
- Drag, resize, and create previews use the configured calendar when finding valid target dates.
- Moving an event past the bottom of a day can roll to the next schedulable day instead of stopping on a closed weekend or holiday.
- Conflict and permission hooks still run after calendar checks; calendars do not bypass app-level validation.
- Blocking is controlled by `eventScheduler.conflicts`, usually with `rules: { 'outside-availability': 'error' }` or `policy: 'prevent'`.

Calendar cells expose the same availability-style state used by the scheduler renderer. Use `className` on the calendars config for product-specific closed-cell styling:

```css
.scheduler-closed-cell {
  background: #f4f6f8;
  color: #8b929c;
}
```

## Working Hours

`workingHours` can be a single range or multiple ranges:

```ts
const splitShiftCalendar: CalendarEntity = {
  ...DEFAULT_CALENDAR,
  id: 'split-shift',
  name: 'Split shift',
  workingHours: [
    { start: '07:00', end: '11:00' },
    { start: '15:00', end: '21:00' },
  ],
};
```

The scheduler treats a slot as working when it overlaps at least one configured working-hours range. If `workingHours` is omitted, every visible time slot on a working day is treated as working.

An event is considered outside availability when its visible segment is not covered by a working calendar or by matching `eventSchedulerAvailability` entries. With the default conflict policy, that state is shown as a warning. With `rules: { 'outside-availability': 'error' }`, the scheduler rejects the mutation before it updates `source`.

`nonWorkingTime.workingHours` is different: it is a visual fallback for closed cells. Use it for simple background styling when you do not need calendar/resource rules. Use `calendars` or `eventSchedulerAvailability` when outside-working-hours edits must participate in conflict detection.

## Calendars vs Availability

Calendars are recurring operating rules. Availability is dated operational data. They are not mutually exclusive: the scheduler can use a calendar as the baseline and dated availability as the more specific rule for a particular resource/date.

Use calendars for:

- Standard weekday business hours
- Weekend-only teams
- Region-specific public holidays
- Resource calendars copied from workforce or Gantt planning data

Use availability for:

- Extra dated working windows
- One-time room maintenance
- PTO or sick leave
- Lunch breaks that vary by date
- Temporary blocked equipment

When both are present, availability is evaluated first for visible slot state. Unavailable entries win in this order: `kind: 'holiday'`, then `kind: 'blocked'`, then `kind: 'break'`. If any matching `kind: 'working'` availability exists for the resource/date, the slot is open only when it overlaps one of those dated working intervals; otherwise it is treated as closed for that date. If no matching dated working availability exists, the scheduler falls back to the resolved calendar.

The same precedence applies to conflicts. If dated availability entries define `kind: 'working'` for a resource/date and an event is not fully covered by those working intervals, the scheduler raises `outside-availability` from availability instead of checking the calendar. If no dated working availability applies, the calendar can raise `outside-availability`. Availability entries with `kind: 'blocked'`, `kind: 'holiday'`, or `kind: 'break'` raise `blocked-time` when events overlap them. Both conflict types can be made blocking from the conflicts configuration.

## Demo

The `event-scheduler-shift-week` demo includes a calendar selector with weekday, open, and training calendars. Switch between them to see closed hours, closed days, and holiday behavior update without changing the event source.

---

# Conflicts

URL: https://pro.rv-grid.com/guides/event-scheduler/scheduling-rules/conflicts/
Source: src/content/docs/guides/event-scheduler/scheduling-rules/conflicts.mdx
Description: Configure warning and blocking conflict rules for overlapping scheduler events and invalid mutations.

Conflict detection can mark overlaps, warn users, or block changes through the mutation lifecycle. This is also how you forbid events outside working hours: configure working time with `calendars` or `eventSchedulerAvailability`, then make the resulting `outside-availability` conflict blocking.

For a detailed explanation of how availability and calendar inputs become `outside-availability` and `blocked-time`, see the [Scheduling Rules overview](../).

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  conflicts: {
    enabled: true,
    policy: 'mark',
    scope: 'same-resource',
    minDurationMinutes: 30,
    rules: {
      overlap: 'error',
      'outside-availability': 'error',
      'blocked-time': 'error',
    },
  },
  validateMutation: (detail) => {
    const blocking = detail.conflicts?.some((conflict) => conflict.severity === 'error');
    if (blocking) {
      return 'This change creates a blocking scheduling conflict.';
    }
  },
};
```

`policy` sets the default behavior for all conflict types:

| Policy | Behavior |
| :-- | :-- |
| `mark` | Show conflicts as warnings and allow the mutation unless a specific rule is blocking. |
| `prevent` | Treat conflicts as blocking errors by default. |
| `allow` | Ignore conflicts unless a specific rule overrides the type. |

`rules` override the default policy per conflict type. Use `error` to reject the mutation, `warning` to mark it but allow it, `confirm` when your product wants a confirmation flow, and `ignore` to hide the conflict.

Common blocking rules:

```ts
conflicts: {
  enabled: true,
  policy: 'mark',
  rules: {
    overlap: 'error',
    'outside-availability': 'error',
    'blocked-time': 'error',
    'invalid-duration': 'error',
  },
}
```

`outside-availability` is raised when an event falls outside calendar working days/hours or outside explicit `kind: 'working'` availability intervals. `blocked-time` is raised when an event overlaps explicit blocked, holiday, or break availability. `nonWorkingTime` alone is visual and does not create blocking conflicts.

## Conflict Appearance

Conflict detection and conflict presentation are configured separately. Keep rules under `conflicts`, and choose how detected conflicts look under `customization.conflicts.appearance`:

```ts
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-08-17',
  conflicts: {
    enabled: true,
    policy: 'mark',
    scope: 'same-resource',
  },
  customization: {
    conflicts: {
      appearance: 'fill',
    },
  },
};
```

| Appearance | Behavior |
| :-- | :-- |
| `outline` | Keeps the existing conflict rings around the event. This is the default for backward compatibility. |
| `fill` | Uses the conflict severity background and text colors inside the event bar without the oversized conflict rings. |

Filled conflicts keep the warning or conflict state icon and the normal event shadow. Selection and keyboard focus indicators are unchanged, so `fill` removes only the conflict decoration rings—not accessibility or interaction feedback. The option works across scheduler views; it is especially useful in dense resource timelines where multiple outlines would consume lane space.

You can combine the built-in appearance with `customization.conflicts.className`, `properties`, `indicator`, and `tooltip` when a product needs additional presentation hooks. These hooks do not change whether a conflict blocks a mutation.

## Preventing Mutations

Conflict rules are the declarative way to stop invalid changes. When a conflict resolves to `severity: 'error'`, the scheduler rejects the mutation before it updates `source`.

For business rules that need code, use the same cancelable event pattern as RevoGrid editing. Listen to `event-scheduler-before-event-change` and call `preventDefault()` before the local commit:

```ts
grid.addEventListener('event-scheduler-before-event-change', (event) => {
  const hasBlockingConflict = event.detail.conflicts?.some((conflict) =>
    conflict.severity === 'error' &&
    event.detail.eventId !== null &&
    conflict.eventIds.includes(event.detail.eventId)
  );

  if (hasBlockingConflict || event.detail.event?.locked) {
    event.preventDefault();
  }
});
```

`validateMutation` is the config-level equivalent for synchronous validation. Return `false` or a string to reject the same pending mutation.

```ts
const eventScheduler = {
  validateMutation: (detail) => {
    if (detail.changes.resourceId === 'locked-room') {
      return 'That room cannot accept bookings.';
    }
  },
};
```

Do not use `event-scheduler-event-changed` for prevention. `event-scheduler-event-created`, `event-scheduler-event-changed`, and `event-scheduler-event-deleted` fire after the scheduler has accepted the mutation; use those events to persist or sync the emitted `detail.events` array.

Listen to conflict updates for side panels, badges, filters, or exports.

```ts
grid.addEventListener('event-scheduler-conflicts-updated', (event) => {
  renderConflictPanel(event.detail.conflicts);
});
```

Event blocks expose conflict classes and data attributes for custom styles.

---

# Templates and Recurrence

URL: https://pro.rv-grid.com/guides/event-scheduler/templates-recurrence/
Source: src/content/docs/guides/event-scheduler/templates-recurrence.mdx
Description: Create scheduler events from reusable templates and generate repeating shifts or bookings.

Templates define reusable event shapes. The plugin exposes helper methods for single events and recurring series.

```ts
grid.eventSchedulerTemplates = [
  {
    id: 'morning-shift',
    title: 'Morning shift',
    durationMinutes: 480,
    status: 'planned',
    type: 'shift',
    color: '#2563eb',
  },
];

const scheduler = (await grid.getPlugins()).find(
  (plugin) => plugin.constructor?.name === 'EventSchedulerPlugin',
);

scheduler.createRecurringEvents({
  templateId: 'morning-shift',
  resourceId: 'emp-alex',
  startDateTime: '2026-06-08T08:00:00.000Z',
  recurrence: {
    frequency: 'weekly',
    weekdays: [1, 3, 5],
    count: 6,
  },
  seriesId: 'alex-morning-series',
});
```

Generated events keep recurrence metadata so applications can present edit-series or delete-series workflows.

## Copy, Paste, Duplicate, and Bulk Helpers

Get the plugin instance to run imperative scheduler helpers:

```ts
const plugins = await grid.getPlugins();
const scheduler = plugins.find(
  (plugin) => plugin.constructor?.name === 'EventSchedulerPlugin',
);
```

Create one event from a template:

```ts
scheduler?.createEventFromTemplate({
  templateId: 'morning-shift',
  startDateTime: '2026-06-08T08:00:00.000Z',
  resourceId: 'team-a',
});
```

Copy a day or pattern into another date range:

```ts
scheduler?.duplicateScheduleRange({
  sourceStartDateTime: '2026-06-08T00:00:00.000Z',
  sourceEndDateTime: '2026-06-09T00:00:00.000Z',
  targetStartDateTime: '2026-06-09T00:00:00.000Z',
});
```

Selection helpers support copy, paste, duplicate, bulk delete, and bulk status changes:

```ts
scheduler?.setSelectedEventIds(['shift-a', 'shift-b']);
scheduler?.copySelectedEvents();
scheduler?.pasteCopiedEvents({ startDateTime: '2026-06-10T08:00:00.000Z' });
scheduler?.bulkUpdateSelectedEventStatus('confirmed');
```

All helper actions run through the same permissions, conflict, before-change, local mutation, event emission, and remote mutation pipeline as pointer and editor interactions.

---

# Timeline Views

URL: https://pro.rv-grid.com/guides/event-scheduler/timeline-views/
Source: src/content/docs/guides/event-scheduler/timeline-views.mdx
Description: Configure day/week time grids, month/year calendars, and horizontal resource timelines.

Event Scheduler has three projection families: vertical `day` and `week` time grids, true `month` and `year` calendar layouts, and the horizontal `resourceTimeline`. All of them share the same events, resources, filtering, recurrence, conflicts, permissions, selection, history, remote loading, and mutation APIs. For the full grid bootstrap, start with [Getting Started](../introduction/).

## Framework bindings

React, Vue, and Angular wrappers bind the same grid props. In React, keep the plugin array stable and pass empty host rows and columns:

```tsx
import { useMemo } from 'react';
import { RevoGrid } from '@revolist/react-datagrid';
import { EventSchedulerPlugin } from '@revolist/scheduler';

export function ResourceTimeline() {
  const plugins = useMemo(() => [EventSchedulerPlugin], []);

  return (
    <RevoGrid
      plugins={plugins}
      columns={[]}
      eventScheduler={eventScheduler}
      source={events}
      eventSchedulerResources={resources}
    />
  );
}
```

This example assumes `eventScheduler`, `events`, and `resources` are the same constants you would pass in Vanilla TS. Vue and Angular use the same prop names through their normal bindings. In Vue, use property bindings for direct grid properties, for example `:event-scheduler.prop="eventScheduler"`, `:source.prop="events"`, and `:event-scheduler-resources.prop="resources"`. In Angular, use `[eventScheduler]="eventScheduler"`, `[source]="events"`, and `[eventSchedulerResources]="resources"`.

## Choose a view

Use `day` and `week` when time should run vertically and days should be generated as columns. These views work well for shift calendars, appointment books, and detailed weekly planning.

Use `month` for a conventional seven-column calendar whose natural four to six week rows fill the available data viewport. Multi-day events are clipped into continuous week bars, adjacent-month dates remain visible, and dense days expose a `+N more` overlay. Use `year` for a responsive overview of twelve mini-months; choosing a month or day requests the detailed month view.

Use `resourceTimeline` when resources should be generated as rows and time slots should run horizontally. This layout is better for room booking, equipment planning, staff coverage, machine schedules, and custom multi-day resource timelines.

The main range controls are:

- `weekStartDate` anchors the active day, week, month, or year.
- `dateRange` sets an explicit visible range for timeline views. It does not reshape month/year calendars.
- `visibleDays` filters generated weekdays in time-grid/timeline views. Calendar month/year layouts keep seven weekday columns.
- `slotMinutes` controls visible slot granularity.
- `snapMinutes` controls drag, resize, paste, create, and keyboard snapping. When omitted, it follows the active `slotMinutes`, including zoom changes. An explicit value stays fixed across zoom levels.
- `timeRange` limits the visible hours within each day.

The main layout controls are:

- `timeColumnSize` controls the pinned time column in `day` and `week` views.
- `dayColumnSize` controls day columns in `day` and `week`; month columns are distributed across the viewport.
- `resourceColumnSize` controls the pinned resource column in `resourceTimeline`.
- `timelineColumnSize` controls each horizontal timeline slot in `resourceTimeline`.
- `columnGrouping` enables or disables grouped scheduler headers.
- `timelineHeaderRows` defines one to three resource-timeline header rows from coarse to fine.
- `eventLayout`, `maxStackedEvents`, and `compactThreshold` control overlapping event presentation.
- `rowSize` sets the baseline scheduler row height.
- `resourceTimelineRowSizing` lets dense resource rows grow with their simultaneous event lanes.

```ts
const resourceDayTimeline = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  dateRange: { start: '2026-06-08', end: '2026-06-08' },
  slotMinutes: 60,
  timeRange: { start: '6 AM', end: '10 PM' },
  resourceColumnSize: 220,
  timelineColumnSize: 120,
};

const resourceWeekTimeline = {
  ...resourceDayTimeline,
  dateRange: { start: '2026-06-08', end: '2026-06-14' },
  customization: {
    columnSizes: {
      resourceTimeline: {
        resourceColumnSize: 240,
        timelineColumnSize: 132,
      },
    },
    headers: {
      timelineTemplate: (h, context) =>
        h('span', { class: 'scheduler-slot-header' }, context.defaultLabel),
      timelineProperties: (context) => ({
        'data-scheduler-date': context.date,
      }),
    },
  },
};

const customRange = {
  ...resourceDayTimeline,
  dateRange: { start: '2026-06-08', end: '2026-06-10' },
  slotMinutes: 30,
  timelineColumnSize: 132,
};
```

For a practical vertical week setup, continue to [Week View](../week-view/). For raw configuration types, see the [Event Scheduler API reference](/api/event-scheduler/).

```ts
const monthCalendar = {
  view: 'month',
  weekStartDate: '2026-07-15',
  weekStartsOn: 1,
};

const yearOverview = {
  ...monthCalendar,
  view: 'year',
};
```

`month` now means this conventional calendar layout. Earlier releases projected it as a 31-column vertical time grid; applications that depended on that legacy geometry should use an explicit timeline range instead. There is no compatibility flag for the former rendering.

## Demo Sources

The examples keep two focused Event Scheduler demos:

| Demo id | Implementation |
| :-- | :-- |
| `event-scheduler-shift-week` | Shift planner with day, week, month, year, and resource views. |
| `equipment-machine-scheduler` | Dedicated seven-day equipment view with continuous multi-day runs and context-menu zoom. |

Useful source references:

- `examples/revogrid-demos/pro-advanced-scheduler/src/data.ts`
- `examples/revogrid-demos/pro-advanced-scheduler/src/scheduler.ts`
- `examples/components/src/components/event-scheduler/equipment-machine/base-config.ts`
- `examples/components/src/components/event-scheduler/equipment-machine/data.ts`
- `examples/components/src/components/event-scheduler/equipment-machine/index.ts`

## Column Widths

Scheduler column widths are controlled by the scheduler config and are applied when the view is projected into RevoGrid columns:

- `timeColumnSize` controls the pinned time column in day and week views.
- `dayColumnSize` controls time-grid day columns and supplies the initial calendar sizing hint.
- `resourceColumnSize` controls the pinned resource column in resource timeline views.
- `timelineColumnSize` controls each horizontal timeline slot in resource timeline day, week, and custom ranges.

Use wider `timelineColumnSize` values for custom ranges with fine-grained slots, such as 15-minute or 30-minute columns. Wider timeline slots improve header and event-label readability and naturally create more horizontal scroll space.

Use `customization.columnSizes` when the same scheduler instance switches modes and each mode needs a different width profile. Values under `customization.columnSizes[view]` take precedence over the legacy top-level width options:

```ts
const eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  customization: {
    columnSizes: {
      week: {
        timeColumnSize: 96,
        dayColumnSize: 220,
      },
      resourceTimeline: {
        resourceColumnSize: 260,
        timelineColumnSize: 144,
      },
    },
  },
};
```

## Timescale Zoom

Scheduler header context menus expose Zoom in and Zoom out when another configured level is available. Zoom changes the projected slot size without changing the configured `timeRange` or event dates. When `snapMinutes` is omitted, its effective value follows the active zoom slot, so zooming from 60-minute slots to 30-minute slots also changes interaction snapping from 60 to 30 minutes. An explicitly configured `snapMinutes` remains unchanged across zoom levels. If a level does not divide the visible time range evenly, Scheduler keeps a shorter final slot so the exact range end remains visible.

Use the built-in levels by omitting `zoom`, provide product-specific levels, or disable zoom:

```ts
const eventScheduler = {
  view: 'week',
  weekStartDate: '2026-07-27',
  slotMinutes: 30,
  snapMinutes: 10,
  timeRange: { start: '06:00', end: '17:00' },
  zoom: {
    levels: [15, 30, 45, 90, 120],
  },
};

const fixedTimescale = {
  ...eventScheduler,
  zoom: false,
};
```

The active configured `slotMinutes` is always retained as a zoom level. Invalid, duplicate, and out-of-range level values are ignored. Setting `zoom: false` or `zoom: { enabled: false }` removes the built-in zoom actions and makes the plugin's `canZoomIn()`, `canZoomOut()`, `zoomIn()`, and `zoomOut()` methods return `false`.

## Grouped Headers

Scheduler views use grouped headers by default so day, week, month, and resource timeline ranges can show broader date context above the leaf columns. Disable them when the extra header row is not useful for a compact embedded scheduler:

```ts
const eventScheduler = {
  view: 'week',
  weekStartDate: '2026-06-08',
  columnGrouping: false,
};
```

When `columnGrouping` is `false`, the scheduler returns flat RevoGrid columns. Day/week/month views show only day leaf headers, and resource timeline views show only timeline slot leaf headers after the pinned resource column.

## Adaptive Resource Rows

Resource timelines can grow only the rows that need more vertical space. Enable `resourceTimelineRowSizing` when several events can overlap for the same resource and fixed-height lanes make their labels or status icons difficult to read:

```ts
const eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-08-17',
  dateRange: { start: '2026-08-17', end: '2026-08-30' },
  rowSize: 44,
  resourceTimelineRowSizing: {
    enabled: true,
    minEventHeight: 24,
  },
};
```

`rowSize` remains the minimum row height. Scheduler calculates the maximum number of simultaneously overlapping lanes for each visible resource and grows that row enough to keep every bar at least `minEventHeight` pixels high. It does not use the resource's total event count, so sequential events that reuse one lane do not make the row taller.

Adaptive sizing is disabled by default. Use `resourceTimelineRowSizing: true` for the default `24` pixel minimum, or provide an object when the product needs a different minimum. Empty, grouped, sparse, and non-stacked rows keep `rowSize`; dense rows shrink back when filtering, reassignment, deletion, or another committed update reduces their lane count. Day, week, month, and year views continue to use their normal row behavior.

Row sizes come from projected scheduler lanes rather than DOM measurement, so vertical virtualization remains available. During a live drag or resize preview, row heights stay stable to avoid moving the pointer target; Scheduler recalculates them after the change is committed.

### Continuous multi-day bars

In `resourceTimeline`, an event spanning several dates is rendered as one continuous horizontal bar. Its top and bottom borders remain solid, its outer corners remain rounded, and it does not receive the dashed clipped-edge treatment used by vertically clipped day/week events. Continuation metadata is still retained for customization and accessibility.

Compact titles and state icons stay vertically centered when adaptive rows use the minimum event height. If a title is too wide, normal single-line ellipsis behavior still applies.

### Mode-aware resource timeline rows

Resource timelines use compact, scale-aware defaults based on the number of leaf columns per date. When a date spans multiple time columns, Scheduler combines its localized weekday, month, day, and year into one `day / time` hierarchy, such as `Thu, Dec 4, 2025` above hourly labels. When each date owns one column, it keeps separate `month / day / time` tiers so the shorter labels fit. Day-sized slots use `month / day`. A product can still define the hierarchy per mode, similar to a Gantt timescale:

```ts
const overviewMode = {
  slotMinutes: 360,
  timelineColumnSize: 64,
  timelineHeaderRows: [
    { id: 'day', unit: 'day' },
    { id: 'time', unit: 'time' },
  ],
};

const planningMode = {
  slotMinutes: 180,
  timelineColumnSize: 76,
  timelineHeaderRows: [
    { id: 'month', unit: 'month' },
    {
      id: 'day',
      unit: 'day',
      formatter: ({ defaultLabel }) => defaultLabel.toUpperCase(),
    },
    { id: 'time', unit: 'time' },
  ],
};
```

Rows must be ordered from the broadest unit to the leaf unit. Sub-day scales end in `time`; a `1440`-minute scale ends in `day`. Each row accepts its own formatter, while the existing `timelineHeaderFormatter` remains a compatible shortcut for the leaf row.

Header customization hooks map to RevoGrid column templates and properties. Returning `null` or `undefined` from a template keeps the built-in header content:

```ts
const eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  customization: {
    headers: {
      groupTemplate: (h, context) =>
        h('strong', { class: 'scheduler-date-group' }, context.defaultLabel),
      timelineProperties: (context) => ({
        class: 'scheduler-slot-header',
        'data-slot-start': context.startDateTime,
      }),
    },
  },
};
```

## Troubleshooting

- No rows or events render: check that `grid.plugins` includes `EventSchedulerPlugin`, `eventScheduler` is set, `source` is populated, and each event's `resourceId` matches an item in `eventSchedulerResources` for resource timelines.
- Events render but cannot be created, moved, or resized: enable `editable` and the needed `allowCreate`, `allowMove`, or `allowResize` flags. Permission callbacks, locked resources, and locked event statuses can still block a specific action.
- Custom `source` or `columns` disappear: this is expected while `eventScheduler` is active. The plugin projects scheduler rows and columns into RevoGrid and restores the host grid state when the scheduler config is removed.
- Range or slot labels look wrong: verify ISO `YYYY-MM-DD` dates, `dateRange`, `timeRange`, `slotMinutes`, and any `timelineHeaderFormatter` or `customization.headers` hooks.

---

# Week View

URL: https://pro.rv-grid.com/guides/event-scheduler/week-view/
Source: src/content/docs/guides/event-scheduler/week-view.mdx
Description: Build a practical calendar-style week scheduler for shifts, appointments, and short-range planning.

Use `view: 'week'` when users think in days and hours: employee shifts, appointment books, clinic rosters, classroom timetables, service windows, and team calendars. Time runs vertically, days are generated as columns, and event duration is shown by event height.

This page focuses on a vertical week scheduler. For the general setup, props, and data model, start with [Getting Started](../introduction/). For choosing between vertical time and horizontal resource rows, see [Vertical vs Horizontal Time](../introduction/vertical-vs-horizontal/). For `day`, `month`, `resourceTimeline`, column widths, and grouped headers, see [Timeline Views](../timeline-views/).

## Build a Week Planner

1. Configure the visible week.

   ```ts
   import {
     EventSchedulerPlugin,
     type EventSchedulerConfig,
     type EventSchedulerEventEntity,
     type EventSchedulerResourceEntity,
   } from '@revolist/scheduler';

   const eventScheduler: EventSchedulerConfig = {
     view: 'week',
     weekStartDate: '2026-06-08',
     weekStartsOn: 1,
     locale: 'en-US',
     timeZone: 'UTC',
     visibleDays: [1, 2, 3, 4, 5],
     slotMinutes: 30,
     snapMinutes: 15,
     timeRange: { start: '06:00', end: '22:00' },
     timeColumnSize: 88,
     dayColumnSize: 190,
     editable: true,
     allowCreate: true,
     allowMove: true,
     allowResize: true,
     allowDelete: true,
   };
   ```

   `slotMinutes` controls visible row granularity and has a 15-minute minimum. Use values such as `15`, `30`, or `60` minutes depending on the planning detail your product needs. `snapMinutes` controls create, drag, resize, paste, and keyboard snapping. When omitted, it follows the active slot size as the Scheduler zooms. Set it explicitly when editing precision should remain fixed across zoom levels; for example, display 30-minute rows while allowing 5-minute edits.

   `timeRange` controls the visible start/end time, so night hours can be hidden instead of rendered. `rowSize` controls density for compact, dense, or comfortable schedules, and `timeLabelFormatter` / `timeLabelTemplate` can replace the default `06:00` style labels.

   `locale` and `timeZone` control built-in day and range labels. Use `dayHeaderFormatter`, `timeLabelFormatter`, and `timelineHeaderFormatter` when your product needs a fully custom display format.

2. Provide the events and optional resources.

   ```ts
   const resources: EventSchedulerResourceEntity[] = [
     { id: 'alex', name: 'Alex Kim', role: 'Coordinator', group: 'Front desk' },
     { id: 'maria', name: 'Maria Cruz', role: 'Nurse', group: 'Clinical' },
   ];

   const events: EventSchedulerEventEntity[] = [
     {
       id: 'shift-alex-mon',
       resourceId: 'alex',
       title: 'Front desk',
       startDateTime: '2026-06-08T08:00:00.000Z',
       endDateTime: '2026-06-08T14:00:00.000Z',
       status: 'confirmed',
       type: 'shift',
     },
     {
       id: 'shift-maria-mon',
       resourceId: 'maria',
       title: 'Clinical floor',
       startDateTime: '2026-06-08T10:00:00.000Z',
       endDateTime: '2026-06-08T18:00:00.000Z',
       status: 'planned',
       type: 'shift',
     },
   ];
   ```

   In week view, resources do not become rows; days and time slots define the grid. Resource ids still matter for ownership, permissions, conflicts, calendars, availability, filters, exports, and later switching the same data to `resourceTimeline`.

3. Attach the scheduler to an empty grid.

   ```ts
   const grid = document.querySelector('revo-grid')!;

   grid.plugins = [EventSchedulerPlugin];
   grid.eventScheduler = eventScheduler;
   grid.eventSchedulerResources = resources;
   grid.source = events;
   ```

## Keep Edits Controlled

The scheduler updates `grid.source` and emits the next event array after accepted create, move, resize, edit, delete, template, paste, recurrence, and bulk actions. Persist that array and use it to update framework-owned state.

```ts
function syncEvents(event: CustomEvent<{ events: readonly EventSchedulerEventEntity[] }>) {
  void saveSchedule(event.detail.events);
}

grid.addEventListener('event-scheduler-event-created', syncEvents as EventListener);
grid.addEventListener('event-scheduler-event-changed', syncEvents as EventListener);
grid.addEventListener('event-scheduler-event-deleted', syncEvents as EventListener);
```

Use `event-scheduler-before-event-change`, `validateMutation`, or permission hooks when your product needs to reject a pending change before it is committed. The full lifecycle is covered in [Editing and Interaction](../event-editing/).

## Block Invalid Hours

To make a week planner practical, define working time with calendars or availability and make the resulting conflicts blocking.

```ts
grid.eventScheduler = {
  ...eventScheduler,
  calendars: {
    primaryCalendarId: 'weekday',
    calendars: [{
      id: 'weekday',
      name: 'Weekday shifts',
      timeZone: 'UTC',
      workingDays: [1, 2, 3, 4, 5],
      workingHours: { start: '08:00', end: '18:00' },
      holidays: ['2026-06-19'],
      hoursPerDay: 8,
    }],
  },
  conflicts: {
    enabled: true,
    policy: 'mark',
    rules: {
      'outside-availability': 'error',
      'blocked-time': 'error',
      overlap: 'warning',
    },
  },
};
```

Calendars are the recurring baseline. Use `eventSchedulerAvailability` for dated changes such as PTO, lunch breaks, holiday closures, maintenance, or temporary extra coverage. `nonWorkingTime` is useful for visual closed-cell styling, but it does not block edits by itself. The precedence model is covered in [Scheduling Rules](../scheduling-rules/).

## Switch the Visible Week

Keep `weekStartDate`, `visibleDays`, and `timeRange` in application state when the host toolbar owns navigation.

```ts
function setScheduler(next: Partial<EventSchedulerConfig>) {
  grid.eventScheduler = {
    ...grid.eventScheduler,
    ...next,
  };
}

grid.addEventListener('event-scheduler-navigate-request', (event) => {
  const { action } = (event as CustomEvent<{ action: 'previous' | 'next' | 'today' }>).detail;
  setScheduler({ weekStartDate: resolveNextWeekStart(grid.eventScheduler.weekStartDate, action) });
});

grid.addEventListener('event-scheduler-view-request', (event) => {
  const { view } = (event as CustomEvent<{ view: EventSchedulerConfig['view'] }>).detail;
  setScheduler({ view });
});
```

Use `day` for a focused daily schedule, `week` for the main shift-planning workflow, and `month` for a higher-level calendar. Use `resourceTimeline` when resources need their own rows and users compare capacity horizontally.

## Production Checklist

- Use ISO datetime strings and stable event ids.
- Decide whether `weekStartsOn` and `visibleDays` follow locale, business rules, or user settings.
- Put canonical events in `source`; keep `columns` empty while the scheduler owns the visual projection.
- Enable only the edit permissions your persistence flow can handle.
- Configure calendars or availability before turning outside-hours conflicts into blocking errors.
- Add resources even in week view when conflicts, permissions, reporting, or future resource timelines need them.
- Use the Employee Shift Planner demo as a focused week-view reference.

## Next Pages

- [Timeline Views](../timeline-views/) covers all scheduler views, date ranges, column widths, framework bindings, grouped headers, and demo source locations.
- [Editing and Interaction](../event-editing/) covers host-owned persistence, mutation events, validation, permissions, selection, clipboard, keyboard shortcuts, and editor replacement.
- [Scheduling Rules](../scheduling-rules/) covers calendar, availability, non-working time, and conflict-rule precedence.
- [Grouping](../grouping/) covers resource timelines, unassigned demand, coverage, utilization, filters, and saved views.
- [Templates and Recurrence](../templates-recurrence/) covers template creation, recurrence, duplicate, paste, selection, and bulk helpers.
- [Remote Data](../remote-data/) covers server-backed loading, optimistic saves, refresh, paging, and remote state events.
- [Customization](../customization/) covers the full visual customization category. Start with [Labels and Formatters](../customization/labels-formatters/), [Event Rendering](../customization/events/), and [Layout, Headers, and Cells](../customization/layout/).
- [Examples](../examples/) has compact weekly scheduler examples for custom event bars, day headers, current-time markers, closed hours, read-only mode, cancelable selection state, and themes.
- [Export](../export/) covers export helpers and production readiness.
- [Event Scheduler API reference](/api/event-scheduler/) lists raw config, hook, and event types.

---

# Excel Export

URL: https://pro.rv-grid.com/guides/excel-export/
Source: src/content/docs/guides/excel-export/index.mdx
Description: Export XLSX files and import CSV data with RevoGrid Pro.

RevoGrid Pro exports grid data to `.xlsx` workbooks through `ExportExcelPlugin`. The same plugin also keeps the historical CSV drag-and-drop import path, so existing integrations can keep using the `ExportExcelPlugin`, `grid.exportExcel`, and `export-excel` event names.

Use this page for the quick setup. Provider adapters, cell formatting, CSV import, and migration details are split into focused pages linked below.

## Quick Setup

Attach `ExportExcelPlugin` with your grid plugins:

```ts
import { ExportExcelPlugin } from '@revolist/revogrid-pro';

grid.plugins = [ExportExcelPlugin];
```

Trigger export through the event API:

```ts
grid.dispatchEvent(new CustomEvent('export-excel', {
  detail: {
    workbookName: 'orders.xlsx',
    sheetName: 'Orders',
  },
}));
```

Or call the plugin instance directly:

```ts
const plugins = await grid.getPlugins();
const excel = plugins.find((plugin) => plugin instanceof ExportExcelPlugin);

await excel?.export({
  workbookName: 'orders.xlsx',
  sheetName: 'Orders',
});
```

## Default Behavior

- The bundled provider is `write-excel-file` and exports `.xlsx` files only.
- Extensionless `workbookName` values receive `.xlsx`.
- `sheetName` is normalized for Excel worksheet rules.
- Export reads grid data stores, not rendered DOM rows, so virtualized offscreen rows are included.
- Body export follows the store's visible row projection, preserving current sort and filter order and the expanded/collapsed grouping view.
- Row order is pinned top rows, body rows, then pinned bottom rows.
- Columns follow `providers.column.getColumns('all')`.
- Grid-derived widths and freeze panes are inferred by default from column sizes, `colPinStart` columns, and pinned-top rows.

Direct export intentionally fails while `InfinityScrollPlugin` owns the row source because the browser holds only a moving window of remote rows. Fetch the complete dataset from your backend and export it from a temporary grid with a local source. See [Exporting to Excel with Infinity Scroll](/guides/infinity-scroll/#exporting-to-excel).

## Formatted And Grouped Exports

When `DataGridFormattingPlugin` and `ExportExcelPlugin` are active together,
Format Cells settings are transferred automatically to the workbook. This is
also the normal setup when `DataGridContextMenuPlugin` supplies Format Cells:

```ts
import {
  DataGridContextMenuPlugin,
  ExportExcelPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [DataGridContextMenuPlugin, ExportExcelPlugin];
```

The export keeps raw numeric and date values as workbook values and attaches
native Excel number formats for Number, Currency, Accounting, Percentage,
Scientific, Date, Time, Date & time, and Plain text presets. Excel can therefore
continue to calculate, sort, and edit those cells. Font family and size,
emphasis, text and fill colors, alignment, wrapping, and borders are mapped to
workbook cell styles.

Row grouping is exported from the visible provider projection. Group records
become merged, indented group-heading rows, while expanded descendants retain
their displayed order and descendants hidden by a collapsed group are omitted.
`context.exportMetadata.rowGrouping` also exposes each exported group row's
worksheet row, depth, label, and expanded state to custom providers.

Format Cells state is owned by the current `DataGridFormattingPlugin` instance.
Export it before destroying that plugin or the grid. Formatting follows
physical source coordinates, so replacing row objects at the same indexes does
not require identity configuration.

## Focused Guides

- [Export Providers](./providers/) explains provider precedence, default `.xlsx` limits, `providerOptions`, `deriveGridOptions`, optional ExcelJS and SheetJS adapters, workbook-module adapters, and custom providers.
- [Cell Formatting](./cell-formatting/) explains automatic Format Cells transfer, `column.excelExport`, formula/date/numeral/select helpers, grouped rows and headers, cell merge export support, and the provider context matrix.
- [CSV Import](./csv-import/) explains CSV-only drag/drop import, `allowDrag`, `allowedExtensions`, `skipColumnGeneration`, events, and plugin import helpers.
- [Migrating to v2.0](/guides/migration-v2/) explains the SheetJS removal, CSV-only default import, app-owned XLSX import, and provider migration paths as a breaking change from `2.0.8`.

## Related Export Guides

- [Excel Import and Export Libraries](/guides/excel-export/excel-import-export-libraries/) compares SheetJS, ExcelJS, read-excel-file, and write-excel-file for app-owned workbook workflows.
- [Gantt Grid, Export, Rendering](/guides/gantt/features/grid-export-rendering/) covers Gantt task-row export mapping and reporting recipes.
- [Pivot Export And State](/guides/pivot/concepts/export-state/) covers Pivot CSV, TSV, and state JSON helpers.
- [Export Excel API](/api/export-excel/) is the generated API reference for the complete public type surface.

---

# Cell Formatting

URL: https://pro.rv-grid.com/guides/excel-export/cell-formatting/
Source: src/content/docs/guides/excel-export/cell-formatting.mdx
Description: Format Excel export cells, formulas, column types, grouped headers, and merge spans.

Use `column.excelExport` when workbook output needs values or styles that differ from the rendered grid. Export formatting is data-source based and runs during export only.

When `DataGridFormattingPlugin` is also active, formatting applied through the
Format Cells UI is transferred automatically after column export callbacks.
The callback result remains the base cell configuration; explicitly stored
Format Cells value and appearance fields override only their corresponding
workbook fields. See [Format Cells](/guides/data-grid/format-cells/) for presets,
selection scope, and stable row identity.

## Column Export Callbacks

```ts
import type { ColumnRegular } from '@revolist/revogrid';

const columns: ColumnRegular[] = [
  {
    prop: 'price',
    name: 'Price',
    excelExport: {
      columnProperties: ({ value }) => ({
        value,
        fontWeight: 'bold',
        backgroundColor: 'E8EEF9',
      }),
      cellProperties: ({ value, rowType }) => ({
        value,
        type: Number,
        format: '$#,##0.00',
        align: 'right',
        fontWeight: rowType === 'rowPinEnd' ? 'bold' : undefined,
      }),
    },
  },
];
```

`columnProperties` formats the generated header cell. `cellProperties` formats body, pinned-top, and pinned-bottom cells.

`cellProperties` receives:

| Field | Meaning |
| --- | --- |
| `value` | Prepared export value after formula evaluation |
| `rawValue` | Original source value for the column |
| `model` | Original source row object |
| `rowIndex` | Index inside its source row segment |
| `rowType` | `rowPinStart`, `rgRow`, or `rowPinEnd` |
| `column` | Current column definition |
| `columnIndex` | Export column index |
| `revogrid` | Grid element |
| `providers` | Runtime plugin providers |

Callbacks can return:

- a primitive value to replace the exported value
- a cell object with `value` and style fields
- a style-only object, which keeps the prepared value
- `undefined`, which keeps the default prepared cell

## Style Fields

Common workbook style fields include:

| Field | Example |
| --- | --- |
| `fontFamily`, `fontSize`, `fontWeight`, `fontStyle` | text styling |
| `textColor`, `backgroundColor`, `fillPatternColor` | colors |
| `borderColor`, `leftBorderColor`, `rightBorderColor`, `topBorderColor`, `bottomBorderColor` | borders |
| `align`, `alignVertical`, `wrap`, `textRotation`, `indent` | alignment |
| `format` | number/date format |
| `height`, `columnSpan`, `rowSpan` | layout |

The bundled `write-excel-file` provider accepts `#E8EEF9` and bare RGB hex values such as `E8EEF9` for known color fields. Bare colors are prefixed before the provider calls `write-excel-file`.

Optional providers map this structural shape to their own workbook library. Unsupported fields may be ignored by a custom provider.

## Formula Export

Formula cells are evaluated by default. To preserve workbook formulas, use the final export-context transformer:

```ts
import { createFormulaExcelExportTransformer } from '@revolist/revogrid-pro';

grid.exportExcel = {
  exportTransformers: [
    createFormulaExcelExportTransformer({
      includeEvaluatedResult: true,
    }),
  ],
};
```

Because this transformer runs after the final visible row projection, generated headers, grouping, merges, and Format Cells integration, it translates grid A1 references to their actual worksheet row and column coordinates. If filtering or collapsed groups remove a referenced row or range, the transformer safely keeps the evaluated scalar instead of emitting a formula that points at the wrong record. Formula names are expanded by default; set `expandFormulaNames: false` only when your provider creates matching workbook-defined names.

When `includeEvaluatedResult` is enabled, providers that support cached formula results receive both the translated formula and the prepared result. The lower-level `createFormulaExcelExportCellProperties()` helper preserves a raw formula string but cannot remap references after rows or columns move, so reserve it for layouts where exported coordinates are guaranteed to match the source grid exactly.

## External Column Type Helpers

Date, numeral, and select column packages are optional app dependencies, so Pro exposes explicit Excel export helpers instead of importing those packages automatically:

```ts
import {
  createDateExcelExportColumnOptions,
  createNumeralExcelExportColumnOptions,
  createSelectExcelExportColumnOptions,
} from '@revolist/revogrid-pro';

const columns = [
  {
    prop: 'createdAt',
    name: 'Created',
    columnType: 'date',
    excelExport: createDateExcelExportColumnOptions({ format: 'yyyy-mm-dd' }),
  },
  {
    prop: 'amount',
    name: 'Amount',
    columnType: 'currency',
    excelExport: createNumeralExcelExportColumnOptions({ format: '$#,##0.00' }),
  },
  {
    prop: 'status',
    name: 'Status',
    columnType: 'select',
    source: [
      { value: 'open', label: 'Open' },
      { value: 'closed', label: 'Closed' },
    ],
    labelKey: 'label',
    valueKey: 'value',
    excelExport: createSelectExcelExportColumnOptions({
      column: {
        prop: 'status',
        source: [
          { value: 'open', label: 'Open' },
          { value: 'closed', label: 'Closed' },
        ],
        labelKey: 'label',
        valueKey: 'value',
      },
    }),
  },
];
```

Date helpers convert valid date-like values to `Date` cells. Numeral helpers convert finite numbers and numeric strings to number cells. Select helpers export the user-facing label for stored values.

## Grouped Rows, Grouped Headers, And Cell Merge

Row grouping follows the body store's visible item projection. Exported group
records become merged, indented heading rows, expanded descendants keep their
visible order, and descendants hidden by a collapsed group are omitted. Custom
providers can inspect `context.exportMetadata.rowGrouping` for exported
worksheet row numbers, group depth, labels, and expanded state.

Grouped column headers are applied automatically when the grid uses a grouped `columns` tree. Group header rows are inserted before the flattened leaf header row.

Cell merge spans are applied automatically when the grid has `cellMerge` data. The export transform maps grid row and column segment coordinates into provider matrix coordinates, accounting for generated header rows.

The built-in `write-excel-file` provider and ExcelJS adapter consume `columnSpan` and `rowSpan` values from `cellRows`. Custom providers can also read merge metadata from `context.exportMetadata.cellMerge`.

## Provider Context

Custom providers and transformers receive a prepared `ExcelExportProviderContext`:

| Field | Purpose |
| --- | --- |
| `cellRows` | Provider-ready matrix with header rows and formatted cells |
| `rows` | Plain row objects keyed by column prop, with formulas evaluated |
| `sourceRows` | Visible original row models with physical source index and row segment metadata |
| `headerRowsCount` | Number of generated header rows before data rows in `cellRows` |
| `gridDerivedOptions` | Width and freeze-pane hints inferred from current grid state |
| `exportMetadata` | Feature metadata such as row grouping, grouped headers, and cell merge ranges |

Use `cellRows` for formatted workbook output. Use `rows` for simple JSON-style providers that do not need formatting.

## Export Transformers

Use `exportTransformers` for final app-owned changes to the provider context:

```ts
grid.exportExcel = {
  exportTransformers: [
    (context) => ({
      exportMetadata: {
        generatedBy: 'orders-report',
      },
      providerOptions: {
        hideGridLines: true,
      },
    }),
  ],
};
```

Grid-level transformers run before per-export transformers:

```ts
await excel.export({
  exportTransformers: [
    (context) => {
      context.cellRows[0][0] = { value: 'Exported Orders', fontWeight: 'bold' };
    },
  ],
});
```

---

# CSV Import

URL: https://pro.rv-grid.com/guides/excel-export/csv-import/
Source: src/content/docs/guides/excel-export/csv-import.mdx
Description: Import CSV files with ExportExcelPlugin drag/drop, events, and explicit import options.

<style>{`
  .csv-import-demo {
    position: relative;
  }

  .csv-import-empty-state {
    position: absolute;
    inset: 0;
    z-index: 1;
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    gap: 0.5rem;
    color: #475569;
    text-align: center;
    pointer-events: none;
  }

  .csv-import-empty-state svg {
    width: 2rem;
    height: 2rem;
    margin-bottom: 0.25rem;
    fill: none;
    stroke: currentColor;
    stroke-linecap: round;
    stroke-linejoin: round;
    stroke-width: 1.5;
  }

  .csv-import-empty-state strong {
    color: #0f172a;
    font-size: 1rem;
  }

  .csv-import-empty-state span {
    font-size: 0.875rem;
  }

  .csv-import-demo.is-dark .csv-import-empty-state {
    color: #94a3b8;
  }

  .csv-import-demo.is-dark .csv-import-empty-state strong {
    color: #e2e8f0;
  }
`}</style>

`ExportExcelPlugin` imports CSV files by default. `.xlsx` and `.xls` parsing is app-owned; use a parser such as SheetJS, ExcelJS, or read-excel-file and assign normalized rows to the grid yourself.

For app-owned XLSX parsing choices, see [Excel Import and Export Libraries](/guides/excel-export/excel-import-export-libraries/).

## Drag And Drop

By default, users can drop a `.csv` file onto the grid:

Download sample CSV

Download the sample, then drag it onto the grid to verify the import flow.

Control drag/drop import with `grid.exportExcel`:

```ts
grid.exportExcel = {
  allowDrag: true,
  allowedExtensions: ['.csv'],
};
```

The same options are still accepted through legacy `additionalData.excel`, but new code should prefer `grid.exportExcel`.

## Import Options

| Option | Default | Description |
| --- | --- | --- |
| `allowDrag` | `true` | Enables CSV drag/drop import unless the grid is readonly |
| `allowedExtensions` | `['.csv']` | Case-insensitive filename suffixes accepted in addition to files whose MIME type is `text/csv` |
| `skipColumnGeneration` | `false` | Keeps current grid columns and maps CSV cells by current column order |

When `skipColumnGeneration` is `false`, the first CSV row becomes generated grid columns:

```csv
Name,Status
Ada,Open
Grace,Closed
```

The imported grid receives columns similar to:

```ts
[
  { prop: 0, name: 'Name' },
  { prop: 1, name: 'Status' },
]
```

When `skipColumnGeneration` is `true`, all CSV rows are imported as data and mapped to the existing export column order:

```ts
grid.columns = [
  { prop: 'name', name: 'Name' },
  { prop: 'status', name: 'Status' },
];

await excel.importFile(file, {
  skipColumnGeneration: true,
});
```

## Plugin Methods

Use `importFile()` when import is triggered by an app-owned upload control:

```ts
const plugins = await grid.getPlugins();
const excel = plugins.find((plugin) => plugin instanceof ExportExcelPlugin);

await excel?.importFile(file, {
  allowedExtensions: ['.csv', '.txt'],
  skipColumnGeneration: true,
});
```

Use `isCsv()` to validate a file before import:

```ts
if (excel?.isCsv(file, ['.csv'])) {
  await excel.importFile(file);
}
```

`isExcel()` remains as a deprecated compatibility alias. It is CSV-only and returns `false` for `.xlsx` files unless the caller explicitly allows that extension. It does not parse workbook files.

Acceptance is MIME-or-suffix based: `isCsvFile()` returns `true` when `file.type` is `text/csv` **or** the lower-cased filename ends with one of `allowedExtensions`. The configured suffixes are not a strict allowlist for files already identified with the CSV MIME type. Adding `.txt` or `.xlsx` only permits that filename suffix to enter the CSV text parser; it does not add a new parser.

## Import Events

Before applying imported rows, the plugin dispatches CSV-oriented events:

| Event | Detail |
| --- | --- |
| `excel-before-import` | `file`, `sheetName`, `csv`, and parsed `rows` |
| `excel-before-set` | All import detail plus mapped `jsonData` |

`sheetName` is a compatibility label and contains the filename.

Prevent either event to cancel replacing the grid source:

```ts
grid.addEventListener('excel-before-set', (event) => {
  const { jsonData } = event.detail;

  if (!jsonData.length) {
    event.preventDefault();
  }
});
```

## Parser Behavior

The default importer reads files with `FileReader.readAsText` and parses CSV values. It handles BOMs, CRLF/LF line endings, quoted values, escaped quotes, empty cells, and trailing blank lines.

When a file matches neither the CSV MIME type nor an allowed suffix, the plugin logs `Only CSV files are supported.` and returns without changing the grid. File-reading or parsing failures are caught, logged as `Failed to load CSV file:`, and also resolve `importFile()` without throwing. If your UI needs a rejected promise or a user-visible error state, validate and read the file in app code before calling the plugin. If the grid is readonly or `allowDrag` is `false`, drag/drop import does not activate.

For `.xlsx` uploads, parse the workbook outside the plugin and assign normalized data:

```ts
const { columns, rows } = await parseWorkbook(file);

grid.columns = columns;
grid.source = rows;
```

---

# Excel Import and Export Libraries

URL: https://pro.rv-grid.com/guides/excel-export/excel-import-export-libraries/
Source: src/content/docs/guides/excel-export/excel-import-export-libraries.mdx
Description: Compare SheetJS, ExcelJS, read-excel-file, and write-excel-file for XLSX import/export workflows with RevoGrid.

RevoGrid Pro includes an Excel export plugin, but most production apps still need to choose how uploaded workbook files are parsed, validated, normalized, and streamed into the grid.

Use this guide when your workflow is:

1. User uploads an Excel file.
2. Your app parses `.xlsx` data.
3. Your app converts the first sheet, selected sheet, or validated sheet into JSON.
4. RevoGrid receives normalized `columns` and `source` data.

The bundled `ExportExcelPlugin` exports `.xlsx` files through `write-excel-file` and imports CSV files by default. XLSX import is app-owned: install the parser you want, parse the workbook, then assign normalized rows to RevoGrid. For plugin options, see the [Excel export guide](/guides/excel-export/).

## Quick Recommendation

| Goal | Recommended library | Why |
| --- | --- | --- |
| Fast `.xlsx` upload to grid JSON | SheetJS | Broad format support, direct `sheet_to_json()` conversion, strong compatibility with real-world workbooks. |
| Full workbook editing or styled report generation | ExcelJS | Good API for worksheets, rows, formatting, formulas, tables, merged cells, and generated reports. |
| Simple validated upload forms | read-excel-file | Small API surface with schema-based parsing and validation. |
| Default RevoGrid Pro `.xlsx` export | write-excel-file | Lightweight writer used by the bundled export provider. |
| Huge browser imports | SheetJS or read-excel-file in a Web Worker | Keep parse work away from the UI thread and load rows into RevoGrid incrementally. |
| Backend import/export processing | SheetJS or ExcelJS | Pick SheetJS for broad import compatibility; pick ExcelJS when workbook editing and formatting matter more. |

## SheetJS

[SheetJS](https://docs.sheetjs.com/) is the strongest general-purpose choice for Excel upload workflows. It works in the browser and Node.js, reads workbook bytes from an `ArrayBuffer`, supports common spreadsheet formats, and converts worksheets directly into JSON.

Use it when the import goal is "Excel file in, JSON rows out".

```sh
pnpm add xlsx
```

```ts
import * as XLSX from 'xlsx';
import type { ColumnRegular, DataType } from '@revolist/revogrid';

export async function parseSheetJsFile(file: File): Promise<{
  columns: ColumnRegular[];
  rows: DataType[];
}> {
  const data = await file.arrayBuffer();
  const workbook = XLSX.read(data, { cellDates: true });
  const worksheet = workbook.Sheets[workbook.SheetNames[0]];
  const rows = XLSX.utils.sheet_to_json<Record<string, unknown>>(worksheet, {
    defval: '',
  });

  const columns = Object.keys(rows[0] ?? {}).map((key) => ({
    prop: key,
    name: key,
  }));

  return { columns, rows };
}
```

```ts
const { columns, rows } = await parseSheetJsFile(file);

grid.columns = columns;
grid.source = rows;
```

SheetJS is usually the best RevoGrid import fit for admin panels, ERP screens, analytics tools, and customer-provided enterprise spreadsheets where file shape is not perfectly controlled.

The tradeoff is that parsing large files on the main browser thread can freeze the UI. For large files, parse in a Web Worker and only send normalized data back to the page.

```ts title="xlsx-import.worker.ts"
import * as XLSX from 'xlsx';

self.onmessage = async (event: MessageEvent<File>) => {
  const workbook = XLSX.read(await event.data.arrayBuffer(), { cellDates: true });
  const worksheet = workbook.Sheets[workbook.SheetNames[0]];
  const rows = XLSX.utils.sheet_to_json<Record<string, unknown>>(worksheet, {
    defval: '',
  });
  const columns = Object.keys(rows[0] ?? {}).map((key) => ({
    prop: key,
    name: key,
  }));

  self.postMessage({ columns, rows });
};
```

```ts title="import-ui.ts"
const worker = new Worker(new URL('./xlsx-import.worker.ts', import.meta.url), {
  type: 'module',
});

worker.onmessage = ({ data }) => {
  grid.columns = data.columns;
  grid.source = data.rows;
};

worker.postMessage(file);
```

## ExcelJS

[ExcelJS](https://github.com/exceljs/exceljs) is better when you need to read, edit, preserve, or generate richer workbook structures. It is a good fit for financial reports, styled exports, workbook templates, formulas, tables, and merged-cell workflows.

Use it when the app needs workbook manipulation, not only raw import speed.

```sh
pnpm add exceljs
```

```ts
import ExcelJS from 'exceljs';
import type { ColumnRegular, DataType } from '@revolist/revogrid';

export async function parseExcelJsFile(file: File): Promise<{
  columns: ColumnRegular[];
  rows: DataType[];
}> {
  const workbook = new ExcelJS.Workbook();
  await workbook.xlsx.load(await file.arrayBuffer());

  const worksheet = workbook.worksheets[0];
  const headerRow = worksheet.getRow(1);
  const headerValues = Array.isArray(headerRow.values)
    ? headerRow.values.slice(1)
    : Object.values(headerRow.values);
  const headers = headerValues
    .map((value) => String(value ?? '').trim())
    .filter(Boolean);

  const columns = headers.map((header) => ({
    prop: header,
    name: header,
  }));

  const rows: DataType[] = [];
  worksheet.eachRow((row, rowNumber) => {
    if (rowNumber === 1) {
      return;
    }

    const model: DataType = {};
    headers.forEach((header, index) => {
      model[header] = row.getCell(index + 1).value ?? '';
    });
    rows.push(model);
  });

  return { columns, rows };
}
```

ExcelJS can also be used as an optional RevoGrid export provider when you need workbook features beyond the bundled provider.

```ts
import ExcelJS from 'exceljs';
import { createExcelJsExcelExportProvider } from '@revolist/revogrid-pro';

grid.exportExcel = {
  exportProvider: createExcelJsExcelExportProvider(ExcelJS),
};
```

The tradeoff is size and speed. ExcelJS is usually heavier than SheetJS for pure "parse and convert to JSON" imports.

## read-excel-file

[read-excel-file](https://www.npmjs.com/package/read-excel-file) is the best fit when uploads are simple and validation matters more than workbook feature coverage. It reads `.xlsx` files in the browser or Node.js and can map columns into typed JSON with a schema.

```sh
pnpm add read-excel-file
```

```ts
import readXlsxFile from 'read-excel-file';

const schema = {
  name: {
    column: 'Name',
    type: String,
    required: true,
  },
  age: {
    column: 'Age',
    type: Number,
  },
};

const { rows, errors } = await readXlsxFile(file, { schema });

if (errors.length) {
  throw new Error(`Invalid spreadsheet: ${errors[0].error}`);
}

grid.columns = [
  { prop: 'name', name: 'Name' },
  { prop: 'age', name: 'Age' },
];
grid.source = rows;
```

This is a strong choice for import forms, onboarding flows, and ETL-style screens where the workbook is really a typed table.

The tradeoff is that it is not intended to be a full workbook manipulation layer. If users upload complex workbooks with formulas, styles, merged headers, comments, or multiple business sheets, use SheetJS or ExcelJS instead.

## write-excel-file

[write-excel-file](https://www.npmjs.com/package/write-excel-file) is a lightweight `.xlsx` writer for browser and Node.js. It is also the default writer behind RevoGrid Pro's bundled Excel export provider.

For most RevoGrid exports, use `ExportExcelPlugin` directly:

```ts
import { ExportExcelPlugin } from '@revolist/revogrid-pro';

grid.plugins = [ExportExcelPlugin];

const plugins = await grid.getPlugins();
await plugins.find((plugin) => plugin instanceof ExportExcelPlugin)?.export({
  workbookName: 'orders.xlsx',
  sheetName: 'Orders',
});
```

Use `write-excel-file` directly when you are exporting app data that does not need the grid export pipeline.

```sh
pnpm add write-excel-file
```

```ts
import writeXlsxFile from 'write-excel-file';

await writeXlsxFile(
  [
    [
      { value: 'Name', fontWeight: 'bold' },
      { value: 'Revenue', fontWeight: 'bold' },
    ],
    [
      { value: 'North', type: String },
      { value: 12000, type: Number, format: '$#,##0' },
    ],
  ],
  {
    fileName: 'summary.xlsx',
    sheet: 'Summary',
  },
);
```

The tradeoff is intentional simplicity. If export needs template workbooks, charts, complex formulas, images, or heavy workbook editing, use ExcelJS or a custom provider.

## RevoGrid Import Pipeline

For RevoGrid imports, keep the parser separate from the grid:

1. Read the uploaded file.
2. Parse workbook data with the selected library.
3. Normalize headers into stable `ColumnRegular` objects.
4. Normalize each row into a plain object keyed by `column.prop`.
5. Validate and coerce values before assigning them to the grid.
6. Assign `grid.columns` before `grid.source`.

```ts
type ImportedTable = {
  columns: { prop: string; name: string }[];
  rows: Record<string, unknown>[];
};

async function importWorkbook(file: File): Promise<ImportedTable> {
  return parseSheetJsFile(file);
}

const imported = await importWorkbook(file);

grid.columns = imported.columns;
grid.source = imported.rows;
```

Avoid putting the raw workbook object into reactive application state. Workbooks can be large and contain circular or library-specific objects. Store the normalized rows, validation errors, and lightweight import metadata instead.

## Performance Notes

Browser-side Excel parsing becomes visible to users once files are large enough. The exact threshold depends on column count, formulas, styles, browser, device, and parser options, but imports around `100k+` rows are where main-thread parsing commonly starts to feel expensive.

For larger files:

- Parse inside a Web Worker.
- Limit the first preview to a small row count.
- Normalize rows in chunks.
- Keep the original workbook out of framework state.
- Show validation errors separately from accepted rows.
- Let RevoGrid render the normalized dataset with virtualization.

For very large or regulated imports, parse on the backend and send RevoGrid paged or streamed JSON instead of asking the browser to own the whole workbook lifecycle.

## Practical Choice

For most RevoGrid apps:

- Use `ExportExcelPlugin` with the bundled `write-excel-file` provider for grid export.
- Use SheetJS for flexible `.xlsx` upload and header inference.
- Use `read-excel-file` for small validated upload forms.
- Use ExcelJS when the workbook itself is the product: formatted reports, templates, formulas, tables, and workbook editing.

That gives the fastest path for common XLSX-to-grid imports while keeping advanced export and workbook-editing cases open through RevoGrid's custom provider contract.

---

# Export Providers

URL: https://pro.rv-grid.com/guides/excel-export/providers/
Source: src/content/docs/guides/excel-export/providers.mdx
Description: Choose the default XLSX provider, optional adapters, or a custom Excel export provider.

`ExportExcelPlugin` prepares one provider context, applies built-in feature transforms, applies custom `exportTransformers`, then passes the context to the selected provider.

Provider resolution is:

1. `plugin.export({ provider })`
2. `grid.exportExcel.exportProvider`
3. bundled `'write-excel-file'`

## Default Provider

The bundled provider is backed by `write-excel-file/browser` and exports `.xlsx` only:

```ts
await excel.export({
  workbookName: 'orders',
  sheetName: 'Orders',
});
```

Extensionless workbook names receive `.xlsx`, so `orders` becomes `orders.xlsx`.

The default provider rejects incompatible workbook output clearly:

- `writingOptions.bookType` must be `xlsx`.
- `workbookName` must be extensionless or end in `.xlsx`.
- Use an optional adapter or custom provider for formats such as `.xlsb`, `.xls`, `.csv`, or `.ods`.

## Provider Options

`providerOptions` are forwarded to the selected provider. For the bundled provider, they are merged into the options passed to `write-excel-file`.

```ts
await excel.export({
  workbookName: 'orders.xlsx',
  providerOptions: {
    fontFamily: 'Arial',
    fontSize: 12,
    hideGridLines: true,
    zoomScale: 90,
  },
});
```

By default, the export pipeline derives provider hints from the live grid:

| Derived option | Source |
| --- | --- |
| `columns` widths | Current grid column sizes |
| `stickyRowsCount` | Generated header row plus pinned-top rows |
| `stickyColumnsCount` | `colPinStart` columns |

Explicit `providerOptions` override derived values. Disable derivation for a single export with `deriveGridOptions: false`:

```ts
await excel.export({
  deriveGridOptions: false,
  providerOptions: {
    stickyRowsCount: 0,
    stickyColumnsCount: 2,
  },
});
```

## Grid-Level Provider

Use `grid.exportExcel.exportProvider` when one grid should consistently use the same workbook library:

```ts
grid.exportExcel = {
  exportProvider: myProvider,
};
```

Override it for one export call:

```ts
await excel.export({
  provider: anotherProvider,
  workbookName: 'report.xlsx',
});
```

## Optional ExcelJS Provider

ExcelJS is not bundled. Install it in your app and pass the module object to the provider factory:

```sh
pnpm add exceljs
```

```ts
import ExcelJS from 'exceljs';
import { createExcelJsExcelExportProvider } from '@revolist/revogrid-pro';

grid.exportExcel = {
  exportProvider: createExcelJsExcelExportProvider(ExcelJS),
};
```

The ExcelJS adapter consumes the formatted `cellRows` matrix, maps common cell formatting to ExcelJS styles, applies grid-derived widths and freeze panes, and writes/downloads the workbook through ExcelJS.

Use ExcelJS when export needs richer workbook styling, merge support, row heights, freeze panes, or library-specific worksheet setup.

## Optional SheetJS Provider

SheetJS is not bundled. Install it in your app and pass the module object to the provider factory:

```sh
pnpm add xlsx
```

```ts
import * as XLSX from 'xlsx';
import { createSheetJsExcelExportProvider } from '@revolist/revogrid-pro';

grid.exportExcel = {
  exportProvider: createSheetJsExcelExportProvider(XLSX),
};
```

The SheetJS adapter writes plain row objects from `context.rows`. It does not consume formatted `cellRows`, grouped header rows, or merge spans. Use ExcelJS or a custom provider when workbook formatting must be preserved.

## Workbook Module Adapter

Use `createWorkbookModuleExcelExportProvider()` for simple workbook-like modules that can create a worksheet from plain row objects:

```ts
import { createWorkbookModuleExcelExportProvider } from '@revolist/revogrid-pro';

grid.exportExcel = {
  exportProvider: createWorkbookModuleExcelExportProvider({
    createWorkbook,
    createWorksheet,
    appendWorksheet,
    writeFile,
  }),
};
```

Like the SheetJS adapter, the workbook-module adapter uses `context.rows`. Use a full custom provider when the library needs formatted cells, grouped headers, merge metadata, or custom workbook setup.

## Custom Provider

Any object that implements `ExcelExportProvider` can write the workbook:

```ts
import type { ExcelExportProvider } from '@revolist/revogrid-pro';

const myProvider: ExcelExportProvider = {
  id: 'app-provider',
  async export(context) {
    await writeWorkbook({
      fileName: context.workbookName,
      sheetName: context.sheetName,
      cells: context.cellRows,
      metadata: context.exportMetadata,
    });
  },
};
```

Custom providers should use the prepared context instead of reading rendered DOM rows. Virtualized rows are already included in `rows`, `sourceRows`, and `cellRows`.

Ordinary client-side virtualization includes every source row, but `InfinityScrollPlugin` deliberately retains only a moving window. `ExportExcelPlugin` therefore rejects direct export while Infinity Scroll owns the source. Fetch all rows from the backend and export them through a temporary grid with a local source; see [Exporting to Excel with Infinity Scroll](/guides/infinity-scroll/#exporting-to-excel).

## Provider Context Notes

The export context is built from RevoGrid data stores first, with grid element sources as a compatibility fallback. This matters for virtualized grids: providers should not query rendered rows because offscreen records may not be mounted in the DOM.

Pinned row segments are preserved in `sourceRows`:

- `rowPinStart` for pinned top rows
- `rgRow` for body rows
- `rowPinEnd` for pinned bottom rows

The prepared `rows` array keeps the same pinned-top, body, pinned-bottom order after formula evaluation. The formatted `cellRows` matrix adds generated header rows before those data rows.

For workbook providers:

- Use `cellRows` when you need formatted values, column-level cell properties, grouped headers, formulas, or merge spans.
- Use `sourceRows` when you need row-segment semantics, original models, or source indexes.
- Use `rows` only for plain row-object export where formatting and merge metadata do not matter.

If a grid data store is not initialized yet, export falls back to the grid element source for that segment. Missing pinned sources are treated as empty arrays.

For broader library selection guidance, see [Excel Import and Export Libraries](/guides/excel-export/excel-import-export-libraries/).

---

# Managing Reference Data

URL: https://pro.rv-grid.com/guides/faq/data-reference/
Source: src/content/docs/guides/faq/data-reference.mdx

Reference data represents static data in a key/value pair format.
This type of data typically remains constant between server requests, making it ideal for scenarios where meaningful labels need to be displayed alongside coded values. For example, a car make might be represented as `'aud': 'Audi'`.

Reference data mapping is a Core RevoGrid pattern. It uses column value handlers such as `cellParser` and does not require Pro plugins.

{/*
### Example Data Structure

The data returned from the server usually consists of codes (keys) that need to be mapped to their corresponding names (values) for display in the grid.
Here’s an example of how this data can be structured:

```javascript
// Data from server
const rowData = [
    { prod: 'toy', price: 28000 },
    { prod: 'bmw', price: 55000 },
    // ...
];

// Supporting reference data
const carMappings = {
    'toy': 'Toyota',
    'bmw': 'BMW',
    'aud': 'Audi',
    'hnd': 'Honda'
};
``` */}

## Strategies for Managing Reference Data

Value handlers provide a flexible way to map codes to display values. This method involves more coding but allows for greater customization in how data is formatted and saved.

- **Value Formatter**: Converts the key to a user-friendly value for display in the grid.
- **Value Parser**: Converts the user-selected value back into a key for saving in the underlying data.

{/* #### Example Configuration

Here’s how you can configure the grid to use value handlers:

```javascript
const gridOptions = {
    columns: [
        {
            prop: 'prod',
            cellTemplate: (h, params) => carMappings[params.value], // Convert code to name
        },
        cellCompare: (a, b) => { // Map data for sorting
            return carMappings[a] - carMappings[b];
        },
        cellParser: (model, column) => { // Map data for filtering, editing and saving
            return carMappings[model[column.prop]];
        }
    ],
    // Other grid options...
};
``` */}

## Conclusion

Effectively managing reference data is essential for ensuring that users see meaningful labels alongside coded values.

<div hidden>

```javascript
// fixing render for multiframework
```

</div>

---

# Data Synchronization

URL: https://pro.rv-grid.com/guides/faq/data-sync/
Source: src/content/docs/guides/faq/data-sync.mdx
Description: A guide covers core concepts and advanced tips for handling data.

We assume that you have already set up the basic version of RevoGrid and are familiar with configuring the `source` and `columns`. It is crucial to always mutate the data you pass to the grid, as this ensures optimal performance.
RevoGrid offers several popular approaches for working with data:

1. ### Grid-Centric Data Management:
   - You can work with the grid and, in the end, request the data directly from it.

      This approach allows you to subscribe to the `afteredit` event, which is triggered after a cell edit or range edit occurs.
      You can retrieve the current data from the `source` whenever you need it.

      Try to modify the data in the grid and check how it updates in real time.
      Check `Source code` for more details.

   ---

   ---

2. ### Source-Centric Data Management:
   - This method involves managing your data independently and handling events before cell editing.

      In this case, you need to pass your source array to the grid each time an edit occurs, which will trigger a grid re-render to display the updated data.

      As part of the Pro version, we provide the [**EventManagerPlugin**](../data-manage/event-manager-explanation), which consolidates range, clipboard, and cell edit events into a single common event called `gridedit`.

      You can utilize this plugin to catch the event, modify it, or even create your own custom event manager.
      Try to modify the data in the grid and check how it updates in real time.
   ---

   ---

3. ### Pagination and Dynamic Data Loading:

   - These two features are two sides of the same coin:
        - Pagination allows you to break your data source into manageable parts and load data from a server or cache for each page. For more information, check out the [**PaginationPlugin** and its documentation](../grid-utilities/pagination).
        - Dynamic data loading is an advanced version of pagination that loads data in chunks based on user interactions, such as scrolling, without displaying a page panel.

   With this approach, you can combine the two methods mentioned above to work with a complete or partial grid dataset, updating the data and passing it to the grid as needed.

## Best Practices

For best practices on data management and manipulation, please refer to our [Best Practices Guide](../faq/patterns). This section will help you optimize your grid's performance and usability.

---

# Best Practices

URL: https://pro.rv-grid.com/guides/faq/patterns/
Source: src/content/docs/guides/faq/patterns.mdx

When working with advanced data grids designed for large datasets, several key UI patterns and practices should be followed to ensure a seamless user experience and maintain high performance.

These patterns help create an interface that is intuitive, responsive, and efficient, even with significant data volumes. Here are some of the most important patterns to follow:

1. **Virtual Scrolling**
   - **Pattern**: Efficient handling of large datasets by rendering only visible rows and columns, reducing browser load.
   - **Best Practice**: Ensure custom rendering or plugins are compatible with virtual scrolling. Avoid heavy DOM manipulations outside the visible viewport to optimize performance.

2. **Lazy Loading**
   - **Pattern**: Load data as needed rather than all at once to improve performance.
   - **Best Practice**: Implement lazy loading, particularly with external data sources or APIs, ensuring data is fetched and rendered efficiently in chunks.

3. **Data Virtualization**
   - **Pattern**: Keep only a subset of data in memory, fetching and rendering only the data that is visible or near visible.
   - **Best Practice**: Ensure features like sorting, filtering, and grouping are optimized for large datasets and compatible with data virtualization.

4. **Custom Cell Renderers**
   - **Pattern**: Create custom renderers for complex cell content, such as images, buttons, or interactive elements.
   - **Best Practice**: Keep custom cell renderers lightweight to avoid performance bottlenecks. Optimize expensive operations that are repeated across many cells. Use cache mechanisms to improve performance.

5. **Responsive Design**
   - **Pattern**: Adapt grid layouts to varying screen sizes and resolutions.
   - **Best Practice**: Ensure the grid adjusts to different screen sizes with resizable columns and scrollable content. Use responsive features to manage column visibility or prioritize important data on smaller screens.

6. **Keyboard Navigation**
   - **Pattern**: Support keyboard navigation for seamless user interaction, especially for power users.
   - **Best Practice**: Ensure custom features integrate well with keyboard navigation, maintaining or enhancing keyboard accessibility. Consider custom keyboard shortcuts where applicable.

7. **Infinite Scrolling**
   - **Pattern**: Load additional data as the user scrolls down or across the grid.
   - **Best Practice**: Implement or support infinite scrolling, especially for large datasets, providing a smoother user experience compared to traditional pagination.

8. **Column and Row Pinning**
   - **Pattern**: Keep specific rows or columns visible while scrolling through the data.
   - **Best Practice**: Support pinning in customizations, especially for grids where headers or key identifiers need to remain visible.

9. **Custom Sorting and Filtering**
   - **Pattern**: Implement custom logic for sorting and filtering to provide more complex or domain-specific data interactions.
   - **Best Practice**: Ensure custom sorting and filtering are optimized for performance, potentially applying logic on the server-side for large datasets.

10. **Editable Cells and Inline Editing**
    - **Pattern**: Allow users to edit data directly within the grid for more intuitive data manipulation.
    - **Best Practice**: Ensure inline editing is user-friendly, supports keyboard shortcuts, and includes robust data validation and error handling.

11. **Event Handling and Customization**
    - **Pattern**: Hook into various events (e.g., cell click, row hover) for custom behaviors.
    - **Best Practice**: Optimize event listeners and clean them up when no longer needed to avoid performance issues and memory leaks.

12. **Context Menus and Tooltips**
    - **Pattern**: Enhance user interaction by providing additional options or information through context menus and tooltips.
    - **Best Practice**: Implement contextually aware and lightweight context menus and tooltips to ensure they don't interfere with performance.

13. **Theming and Custom Styling**
    - **Pattern**: Customize themes and styling to align the grid’s appearance with the overall application design.
    - **Best Practice**: Use CSS variables and custom properties for consistent and easy-to-manage styles, ensuring custom styles do not conflict with core styles or degrade performance.

14. **State Management**
    - **Pattern**: Manage the grid’s state (e.g., selected rows, applied filters) for consistency, especially in complex applications.
    - **Best Practice**: Integrate with a state management solution if necessary, ensuring the grid’s state is preserved across sessions or navigation.

15. **Big O Notation Considerations**
    - **Pattern**: Understand the computational complexity of operations to ensure performance remains optimal as data size increases.
    - **Best Practice**: Evaluate and optimize algorithms, especially for sorting, filtering, and rendering, to ensure they are efficient and scale well with large datasets.

16. **Accessibility (a11y)**
    - **Pattern**: Ensure the grid is accessible to all users, including those with disabilities.
    - **Best Practice**: Follow accessibility best practices, such as providing proper ARIA labels, ensuring keyboard accessibility, and supporting screen readers. Test with accessibility tools to identify and fix issues.

By adhering to these patterns, you can create an implementation that is not only performant and scalable but also user-friendly and accessible. These practices will help you build grids that efficiently handle large datasets while providing a seamless and intuitive user experience.

---

# Form Edit Example

URL: https://pro.rv-grid.com/guides/form-edit/
Source: src/content/docs/guides/form-edit.mdx
Description: Learn how to implement form-based row editing in RevoGrid

This example demonstrates how to implement form-based row editing using RevoGrid's row expand functionality. Instead of editing cells directly in the grid, users can click on a row to expand it and edit the data in a form format.

## Implementation Details

The form edit functionality is implemented using the `RowExpandPlugin`. When a row is expanded, a custom template renders a form with the row's data. The form is split into two columns for better organization.

Key implementation points:

1. **Row Expansion**: Uses RevoGrid's `RowExpandPlugin` to show/hide the form
2. **Form Layout**: Implements a two-column grid layout using Tailwind/UnoCSS
3. **Data Handling**: Updates the grid's source data when the form is saved
4. **Validation**: Can be extended to add form validation (not implemented in this basic example)

## Features

- Form layout
- Save and Cancel buttons
- Responsive form design
- Custom form fields for different data types
- Automatic grid update on save

## Usage

To implement this in your own project:

1. Import required plugins
2. Configure the grid columns
3. Set up the row expand template with your form fields
4. Handle form submission and data updates

```typescript
grid.additionalData = {
  rowExpand: {
    expandedRowHeight: 300,
    template(h, props) {
      // Form template implementation
    }
  }
};
```

## Customization

You can customize the form by:

- Adding more form fields
- Implementing validation
- Changing the layout
- Adding custom styling
- Implementing different field types

---

# Formula

URL: https://pro.rv-grid.com/guides/formula/
Source: src/content/docs/guides/formula/index.mdx
Description: Build Excel-style calculations in RevoGrid with formulas, A1 references, named ranges, and workbook data.

---

# A1 References and Autofill

URL: https://pro.rv-grid.com/guides/formula/a1-references-autofill/
Source: src/content/docs/guides/formula/a1-references-autofill.mdx
Description: Understand Formula coordinates and translate formulas safely during fill, pinning, sorting, insertion, and deletion.

Formula references use authored row and column coordinates. Start with this compact fixture:

```ts
import { FormulaPlugin } from '@revolist/revogrid-pro';

grid.range = true;
grid.plugins = [FormulaPlugin];
grid.columns = [
  { prop: 'qty', name: 'Quantity' },      // A
  { prop: 'rate', name: 'Rate' },         // B
  { prop: 'charge', name: 'Charge' },     // C
];
grid.source = [
  { qty: 2, rate: 5, charge: '=A1*$B$1' },
  { qty: 4, rate: 8, charge: null },
];
```

**Expected result:** C1 displays `10`. Filling C1 down writes `=A2*$B$1` to C2 and displays `20`: A's row is relative, while `$B$1` remains fixed.

## Autofill formulas like Excel

Set `grid.range = true` to expose the fill handle. `FormulaPlugin` automatically
installs or reuses `AutoFillPlugin`; applications should not add another formula
fill strategy or duplicate the fill pipeline. AutoFill continues to own the drag,
base sequence, preview, and commit. Formula only translates A1 references in seed
cells whose raw source value starts with `=`.

```ts
import {
  AutoFillPreviewPlugin,
  FormulaPlugin,
} from '@revolist/revogrid-pro';

grid.range = true;
grid.plugins = [FormulaPlugin, AutoFillPreviewPlugin]; // Preview is optional.
```

Vertical copy by one row:

| Reference | Seed | Result |
| --- | --- | --- |
| Relative | `=A1` | `=A2` |
| Fixed column and row | `=$A$1` | `=$A$1` |
| Relative column, fixed row | `=A$1` | `=A$1` |
| Fixed column, relative row | `=$A1` | `=$A2` |
| Mixed range | `=SUM(A1:B2,$C1:D$4)` | `=SUM(A2:B3,$C2:D$4)` |

Horizontal copy by one column:

| Reference | Seed | Result |
| --- | --- | --- |
| Relative | `=A1` | `=B1` |
| Fixed column and row | `=$A$1` | `=$A$1` |
| Relative column, fixed row | `=A$1` | `=B$1` |
| Fixed column, relative row | `=$A1` | `=$A1` |
| Mixed range | `=SUM(A1:B2,$C1:D$4)` | `=SUM(B1:C2,$C1:E$4)` |

References translate in vertical, horizontal, upward, leftward, and
two-dimensional fills. Multi-cell source ranges tile from their corresponding
seed cells. Sheet qualifiers and anchor markers are preserved, including
`Products!A1` and `'Product List'!$A1:B$2`. Named ranges, text literals, and
existing `#REF!` values are not rewritten. If a relative reference moves before
A1, that endpoint becomes `#REF!`.

Pinning, sorting, and filtering do not change these offsets: Formula resolves
the source and destination in the authored A1 coordinate space described below.
For non-contiguous projected selections, seed tiling follows the visible source
order. Preview and commit use the identical translated formula matrix.

For a two-dimensional fill from `=A1*$B$1`, the exact destinations are:

| Destination | Raw formula |
| --- | --- |
| One row down | `=A2*$B$1` |
| One column right | `=B1*$B$1` |
| One row down and one column right | `=B2*$B$1` |

With a multi-cell seed, Formula tiles each destination from the corresponding seed rather than treating the whole selection as one formula.

## How A1 references behave when the grid changes

RevoGrid separates a cell's **formula identity** from its **rendered position**.
Formula letters and row numbers describe the authored data coordinate. Pinning,
hiding, sorting, filtering, grouping, sticky rows, and row drag-order can render
that cell somewhere else without changing what its A1 address means.

This is the same principle as Excel Freeze Panes: freezing a column changes what
stays visible while scrolling, but it does not rename the column or rewrite its
formulas.

```text
Authored formula coordinates

      A          B       C       D
  Product      Region  Price   Total
                              =C1*124

After pinning Price left (rendered order only)

      C          A          B       D
    Price      Product    Region   Total
                                  =C1*124

C1 still means the authored Price column. The raw formula and result are unchanged.
```

### Authored order versus rendered order

Columns use the flattened leaf order supplied through `grid.columns`. In this
example the authored order is `[product, region, price, total]`, even while the
Price column is rendered in the left-pinned viewport.

| A1 letter | Authored property | Position after pinning Price left |
| --- | --- | --- |
| `A` | `product` | Second |
| `B` | `region` | Third |
| `C` | `price` | First, pinned left |
| `D` | `total` | Fourth |

Pinning or unpinning therefore never rewrites formula strings or named-range
definitions. A formula such as `=C1*124` remains bound to `price`, including
when the formula column itself is pinned separately from its precedents.

Column occurrences are matched by identity before RevoGrid considers their
`prop`. This matters when two authored columns intentionally use the same
property. If an application replaces every column object and those replacement
columns still have duplicate properties, there is no reliable way to tell the
occurrences apart after pinning. RevoGrid therefore leaves that mapping
unresolved instead of guessing from the rendered pin order. Preserve the column
objects across presentation changes, or use unique properties when columns need
independent A1 identities.

Rows use one initial authored sequence. Each source can contribute zero, one, or
many rows:

```text
pinnedTopSource → source → pinnedBottomSource
   first rows      next rows          final rows
```

After initialization, moving an existing row between those partitions keeps
its A1 identity. The same applies to sorting, filtering, grouping, sticky-row
duplicates, and row drag-order projections. Tracking is automatic and does not
require an id property in application rows. Applications that replace rows with
new immutable objects can optionally provide a stable row key; see
[Immutable row replacement](#immutable-row-replacement-advanced).

```text
Authored identity                     After pinning Noah to the top

  Row 1  Maya     C1 = 10               Noah     still C2 = 20
  Row 2  Noah     C2 = 20               Maya     still C1 = 10
  Row 3  Total    =SUM(C1:C2)            Total    still =SUM(C1:C2) = 30

Rendered position changed; the underlying row addresses did not.
```

### Presentation changes and structural changes

| Operation | What happens to A1 identity? | Are raw formulas rewritten? |
| --- | --- | --- |
| Pin or unpin a row/column | Preserved | No |
| Hide a column | Preserved; the hidden column still calculates | No |
| Sort, filter, group, trim, or restore rows | Preserved | No |
| Render a sticky-row duplicate | Resolves to its underlying authored row | No |
| Drag-order existing rows | Preserved as a runtime projection | No |
| Insert or delete rows/columns | Following coordinates shift | Yes, unless `autoUpdateRefs` is `false` |
| Explicitly reorder the authored column schema | Letters follow the new authored order | Existing formulas are not currently rewritten for the move |
| Replace all rows with new immutable clones, without `rowIdProp` | Treated as a newly authored dataset | No speculative rewrite |
| Replace rows with immutable clones, with `rowIdProp` | Existing IDs retain A1 identity; genuine inserts/deletes remain structural | Only for genuine inserts/deletes |
| Call `evaluateRawValuesFormula` directly | Uses the row and column arrays supplied by the caller | Not applicable; the helper only evaluates |

### Immutable row replacement (advanced)

Most applications do not need row identity configuration. Built-in pinning,
sorting, filtering, grouping, sticky rows, and drag ordering reuse the existing
row models and are tracked automatically.

If an application replaces source rows with fresh immutable clones, object
identity is no longer available. Set `rowIdProp` only when the configured field
is present, stable, and unique for every row:

```ts
grid.formulaNames = {
  rowIdProp: 'id',
  names: [{ name: 'Revenue', kind: 'range', ref: 'C2:C20' }],
};

grid.source = previousRows.map(row => ({ ...row }));
```

With that key, a cloned row keeps its authored A1 identity even if the new source
order changes or the row moves between pinned and body sources. If the same
immutable update genuinely inserts or deletes IDs, references shift using the
normal structural-edit rules. Rows with a missing key are not assumed to match,
and duplicate keys are ambiguous; use a real record key rather than a row index.

### Explicit schema reorder and standalone evaluation

The explicit column-reorder case is intentionally separate from pinning. If the
authored schema changes from `[A, B, C]` to `[B, A, C]`, `A1` now means the first
column in that new schema. Existing formula text is currently retained; Excel-style
move rewriting is not part of the pinning contract.

The standalone `evaluateRawValuesFormula` helper has no grid viewport or authored
schema to consult. Its A1 coordinates always follow the row and column arrays
passed to that call.

### What deletion does to formulas and ranges

Deletion is structural, so surviving references are normalized to the new row
numbers. For example, begin with:

```text
Row 1  A1 = 10
Row 2  A2 = 20
Row 3  A3 = 30

Direct reference: =A3
Range formula:    =SUM(A1:A3)
```

After deleting row 2, the old row 3 becomes row 2:

```text
Row 1  A1 = 10
Row 2  A2 = 30

=A3          → =A2
=SUM(A1:A3)  → =SUM(A1:A2)
```

If the deleted row was itself the target of a direct reference, that reference
becomes `#REF!`. A range that only partially overlaps the deleted block shrinks
to its surviving cells. Named ranges and named formulas follow the same rules.

### Disable structural rewriting

Set `autoUpdateRefs: false` when the application owns structural ref updates:

```ts
grid.formulaNames = {
  autoUpdateRefs: false,
  names: [],
};
```

**Expected result:** inserting or deleting rows/columns does not rewrite existing raw formula strings or named refs. Presentation operations still behave as described above.

:::tip[Recommended mental model]
Treat pinning, hiding, and runtime projections as viewport mapping. Treat genuine
insertion and deletion as spreadsheet structure changes. This keeps formulas
stable during ordinary grid interaction while keeping their visible A1 text
correct after the dataset structure changes.
:::

## Next steps

**Previous:** [Quick Start](/guides/formula/quick-start/) · **Next:** [Named Ranges](/guides/formula/named-ranges/) · **Deeper reference:** [Autofill guide](/guides/data-manage/autofill/)

---

# Async Formula Functions

URL: https://pro.rv-grid.com/guides/formula/async-functions/
Source: src/content/docs/guides/formula/async-functions.mdx
Description: Register grid-local service functions with loading, errors, events, caching, invalidation, and cancellation.

Use an async formula function when a mounted cell needs data from an application service. Calls are grid-local, case-insensitive, and must be the top-level formula call.

## A complete service-backed function

```ts
import { FormulaPlugin } from '@revolist/revogrid-pro';

grid.plugins = [FormulaPlugin];
grid.columns = [
  { prop: 'sku', name: 'SKU' },           // A
  { prop: 'service', name: 'Service' },   // B
  { prop: 'price', name: 'Service price' }, // C
];
grid.formulaWorkbook = { sheetId: 'Orders', rowIdProp: 'id' };

const plugins = await grid.getPlugins();
const formulas = plugins.find(plugin => plugin instanceof FormulaPlugin);
if (!formulas) throw new Error('FormulaPlugin is not mounted');

const disposeServicePrice = formulas.registerAsyncFormulaFunction({
  name: 'SERVICEPRICE',
  async handler([sku, service], { signal, rawArgs }) {
    const response = await fetch(
      `/api/prices/${encodeURIComponent(String(sku))}?service=${encodeURIComponent(String(service))}`,
      { signal },
    );
    if (!response.ok) throw new Error(`Price request failed: ${response.status}`);
    console.debug('Authored arguments:', rawArgs);
    return (await response.json()).price;
  },
});

grid.source = [{
  id: 'order-1',
  sku: 'B-200',
  service: 'priority',
  price: '=SERVICEPRICE(A1,B1)',
}];

// For example, dispose when this page is torn down.
window.addEventListener('pagehide', disposeServicePrice, { once: true });
```

**Expected result:** C1 first renders the default `#LOADING` state, then the returned price. The handler receives evaluated values (`B-200`, `priority`); `rawArgs` retains `A1` and `B1`.

## Map service errors

The default rejected value is `#ERROR`. Use `mapError` when users need a domain-specific state:

```ts
const dispose = formulas.registerAsyncFormulaFunction({
  name: 'SERVICEPRICE',
  handler: async ([sku], { signal }) => loadPrice(String(sku), signal),
  mapError: error =>
    error instanceof Error && error.message.includes('404') ? '#NOT_FOUND!' : '#SERVICE!',
});
```

**Expected result:** a missing SKU displays `#NOT_FOUND!`; other rejections display `#SERVICE!`. `mapError` takes precedence over `errorValue`.

## Observe and refresh states

```ts
const onStateChange = (event: CustomEvent) => {
  const { name, rowId, status, value, error } = event.detail;
  console.log({ name, rowId, status, value, error });
};
grid.addEventListener('asyncformulastatechange', onStateChange);

// Abort and clear cached SERVICEPRICE cells, then recalculate them on render.
formulas.invalidateAsyncFormulaFunction('SERVICEPRICE');

// Teardown
grid.removeEventListener('asyncformulastatechange', onStateChange);
dispose();
```

**Expected result:** a call emits `pending`, then `resolved` or `rejected`. Repeated renders of the same stable cell/formula/arguments share one request and cached result; invalidation causes a new request.

## Cancellation behavior

The handler's `signal` is aborted when its cell arguments or formula change, the function is invalidated/unregistered, or the plugin is destroyed. Pass that signal to `fetch` or your service client. A stale request's later resolution is ignored.

```ts
async handler([sku], { signal }) {
  const response = await fetch(`/api/prices/${sku}`, { signal });
  return (await response.json()).price;
}
```

**Expected result:** editing A1 from `B-200` to `A-100` aborts the B-200 request and starts one for A-100; only the current request can update the cell.

## Advanced: override a built-in name

Registering `VLOOKUP` intentionally shadows the synchronous built-in only for this mounted grid and only until its disposer runs. Other grids and `calculateFormulaWorkbook` retain the built-in implementation.

Async functions receive evaluated scalar arguments plus `rawArgs`. They cannot be nested inside another expression, and headless `calculateFormulaWorkbook` does not execute them. Load external service data before a backend calculation.

## Next steps

**Previous:** [Cross-sheet Formulas](/guides/formula/cross-sheet/) · **Next:** [Backend Calculation and Persistence](/guides/formula/backend-calculation/) · **Deeper reference:** [Formula API](/api/formula/)

---

# Backend Calculation and Persistence

URL: https://pro.rv-grid.com/guides/formula/backend-calculation/
Source: src/content/docs/guides/formula/backend-calculation.mdx
Description: Recalculate workbooks without a grid and choose whether to persist formulas, caches, or resolved snapshots.

Formula-derived values are not written back into source rows. Formula-aware mounted rendering, sorting, and filtering can consume derived values, while `grid.source` remains the authoritative raw data.

## Choose what to persist

| Strategy | Persist | Use when |
| --- | --- | --- |
| Formulas only | Raw rows containing `=...` | Every consumer can recalculate and no queryable cache is needed. |
| Formulas + calculated cache | Raw formulas plus `values`/patches | APIs, reports, or searches need current values without losing expressions. |
| Resolved snapshot | A separate copy with formulas replaced by values | Exporting or handing data to a system that cannot evaluate formulas. |

## Recommended: calculate a workbook

`calculateFormulaWorkbook` is synchronous, does not mount a grid, and does not mutate supplied rows. Each sheet needs a case-insensitively unique id, unique column properties, a stable `rowIdProp`, and a valid id on every row.

```ts
import { calculateFormulaWorkbook } from '@revolist/revogrid-pro';

const orders = {
  id: 'Orders',
  rowIdProp: 'id',
  columns: [
    { prop: 'sku', name: 'SKU' },
    { prop: 'qty', name: 'Quantity' },
    { prop: 'price', name: 'Price' },
    { prop: 'total', name: 'Total' },
  ],
  rows: [{
    id: 'order-1',
    sku: 'B-200',
    qty: 2,
    price: '=VLOOKUP(A1,\'Product List\'!A1:B2,2,FALSE)',
    total: '=B1*C1',
  }],
};
const products = {
  id: 'Product List',
  rowIdProp: 'id',
  columns: [
    { prop: 'sku', name: 'SKU' },
    { prop: 'price', name: 'Price' },
  ],
  rows: [
    { id: 'product-1', sku: 'A-100', price: 10 },
    { id: 'product-2', sku: 'B-200', price: 25 },
  ],
};

const result = calculateFormulaWorkbook({
  sheets: [orders, products],
  previousValues,
});

if (result.errors.length) {
  reportFormulaErrors(result.errors);
}

await database.transaction(async transaction => {
  for (const patch of result.patches) {
    await persistCalculatedCell(transaction, patch);
  }
});

previousValues = result.values;
```

**Expected result:** `values.Orders['order-1']` is `{ price: 25, total: 50 }`. On the first run, patches identify `Orders!C1` and `Orders!D1`, including sheet id, row id, property, formula, and calculated value. Passing the returned `values` unchanged as the next `previousValues` baseline produces no patches.

## Isolate formula errors

Errors are cell-level. An unknown function or circular dependency yields an entry in `errors` and an error-bearing patch, while independent cells still calculate.

```ts
const result = calculateFormulaWorkbook({
  sheets: [{
    id: 'Orders',
    rowIdProp: 'id',
    columns: [
      { prop: 'broken', name: 'Broken' }, // A
      { prop: 'qty', name: 'Quantity' }, // B
      { prop: 'price', name: 'Price' },  // C
      { prop: 'total', name: 'Total' },  // D
    ],
    rows: [{
      id: 'order-1',
      broken: '=UNKNOWN(A1)',
      qty: 2,
      price: 25,
      total: '=B1*C1',
    }],
  }],
});
```

**Expected result:** `errors` contains A1 with `#ERROR`, while D1 still calculates to `50`. Decide explicitly whether your transaction persists successful patches, rejects the whole workbook, or queues a correction.

## Scoped browser snapshot

For a simple one-sheet browser snapshot, evaluate only formula cells against the exact flat row and column arrays you supply:

```ts
import {
  evaluateRawValuesFormula,
  isFormula,
} from '@revolist/revogrid-pro';

const source = await grid.getSource();
const columns = await grid.getColumns();
const snapshot = source.map(row => {
  const resolved = { ...row };
  for (const column of columns) {
    const raw = row[column.prop];
    if (isFormula(raw)) {
      resolved[column.prop] = evaluateRawValuesFormula(raw, source, columns);
    }
  }
  return resolved;
});
```

**Expected result:** `snapshot` contains calculated values and `source` remains unchanged. This utility does not automatically reproduce mounted pin partitions, external sheets, async functions, or the grid's authored-identity runtime; use the workbook API for production multi-sheet recalculation.

The application owns scheduling, transactions, authorization, retries, conflict handling, and persistence. RevoGrid calculates the supplied snapshot but does not watch or write your database.

## Next steps

**Previous:** [Async Formula Functions](/guides/formula/async-functions/) · **Next:** [Supported Functions](/guides/formula/supported-functions/) · **Deeper reference:** [Formula API](/api/formula/)

---

# Cross-sheet Formulas

URL: https://pro.rv-grid.com/guides/formula/cross-sheet/
Source: src/content/docs/guides/formula/cross-sheet.mdx
Description: Look up values in external sheet datasets at mount time, after loading, and after updates.

External sheets are datasets available to the Formula engine; they are not additional mounted grids. Sheet ids are case-insensitively unique. Quote an id containing spaces, as in `'Product List'!A1:B2`, and give every sheet stable, unique row ids.

## Complete Orders and Product List fixture

Orders maps A=`sku`, B=`qty`, C=`catalogPrice`, D=`total`. Product List maps A=`sku`, B=`price`.

```ts
import { FormulaPlugin } from '@revolist/revogrid-pro';

const orderColumns = [
  { prop: 'sku', name: 'SKU' },
  { prop: 'qty', name: 'Quantity' },
  { prop: 'catalogPrice', name: 'Catalog price' },
  { prop: 'total', name: 'Total' },
];
const productColumns = [
  { prop: 'sku', name: 'SKU' },
  { prop: 'price', name: 'Price' },
];
const productRows = [
  { id: 'product-1', sku: 'A-100', price: 10 },
  { id: 'product-2', sku: 'B-200', price: 25 },
];
const orderRows = [{
  id: 'order-1',
  sku: 'B-200',
  qty: 2,
  catalogPrice: '=VLOOKUP(A1,\'Product List\'!A1:B2,2,FALSE)',
  total: '=B1*C1',
}];

grid.plugins = [FormulaPlugin];
grid.columns = orderColumns;
grid.formulaWorkbook = {
  sheetId: 'Orders',
  rowIdProp: 'id',
  externalSheets: [{
    id: 'Product List',
    rowIdProp: 'id',
    columns: productColumns,
    rows: productRows,
  }],
};
grid.source = orderRows;
```

**Expected result:** C1 displays `25` and D1 displays `50`. The raw formulas remain in `orderRows`.

## INDEX and MATCH

Use INDEX/MATCH when the lookup and return ranges should be explicit:

```ts
orderRows[0].catalogPrice =
  '=INDEX(\'Product List\'!B1:B2,MATCH(A1,\'Product List\'!A1:A2,0))';
grid.source = [...orderRows];
```

**Expected result:** C1 still displays `25`, then D1 displays `50`.

The tested lookup subset is `LOOKUP`, `VLOOKUP`, `HLOOKUP`, and `INDEX`/`MATCH`. `XLOOKUP` and arbitrary Excel workbook features are not supported.

## Load an external sheet later

Mount Orders with no Product List, then register it when the application finishes loading:

```ts
grid.formulaWorkbook = {
  sheetId: 'Orders',
  rowIdProp: 'id',
  externalSheets: [],
};
grid.source = orderRows;

const plugins = await grid.getPlugins();
const formulas = plugins.find(plugin => plugin instanceof FormulaPlugin);
if (!formulas) throw new Error('FormulaPlugin is not mounted');

formulas.upsertFormulaSheet({
  id: 'Product List',
  rowIdProp: 'id',
  columns: productColumns,
  rows: productRows,
});
```

**Expected result:** C1 first renders the mounted missing-sheet loading state, then changes to `25`; D1 changes to `50`. The synchronous backend calculator reports a missing sheet as an error instead of waiting.

## Update an external cell

```ts
formulas.updateFormulaSheetCell('Product List', 'product-2', 'price', 30);
```

**Expected result:** C1 changes from `25` to `30`, and D1 changes from `50` to `60`. The row id selects `product-2`; the final argument uses the column property `price`, not the A1 letter.

## Workbook lifecycle API

| Method | Use it when |
| --- | --- |
| `setFormulaWorkbook(config)` | Replacing the mounted sheet identity or the complete set of external sheets. |
| `upsertFormulaSheet(sheet)` | Adding a late-loaded sheet or replacing one dataset. |
| `updateFormulaSheetCell(sheetId, rowId, prop, value)` | Applying one known external cell update. |
| `removeFormulaSheet(sheetId)` | Making one external sheet unavailable. Dependent mounted formulas return to the missing-sheet loading state. |
| `setFormulaWorkbook(null)` | Detaching the mounted grid from workbook context. |

## Next steps

**Previous:** [Formula UI and Helpers](/guides/formula/formula-ui/) · **Next:** [Async Formula Functions](/guides/formula/async-functions/) · **Deeper reference:** [Formula API](/api/formula/)

---

# Formula UI and Helpers

URL: https://pro.rv-grid.com/guides/formula/formula-ui/
Source: src/content/docs/guides/formula/formula-ui.mdx
Description: Add a Formula Bar, dependency highlights, named dropdowns, and formula-driven styling independently.

`FormulaPlugin` owns calculation. The integrations below are optional and independently configurable.

## 1. Formula Bar

```html
<div id="formula-bar"></div>
<revo-grid id="orders"></revo-grid>
```

```ts
import {
  FormulaBarPlugin,
  FormulaPlugin,
} from '@revolist/revogrid-pro';

const grid = document.querySelector<HTMLRevoGridElement>('#orders');
const host = document.querySelector<HTMLElement>('#formula-bar');
if (!grid || !host) throw new Error('Formula UI hosts are missing');

grid.plugins = [FormulaBarPlugin, FormulaPlugin];
grid.columns = [
  { prop: 'qty', name: 'Quantity' },
  { prop: 'price', name: 'Price' },
  { prop: 'total', name: 'Total' },
];
grid.formulaBar = { host };
grid.source = [{ qty: 3, price: 10, total: '=A1*B1' }];

// Remove the external editor without removing Formula.
grid.formulaBar = null;
```

**Expected result:** focusing C1 shows raw `=A1*B1` in the Formula Bar while C1 renders `30`. Text and number drafts commit on Enter; dropdown, boolean, and date/time choices commit when selected.

The adaptive host selects a formula/text, number, percent, dropdown, boolean, date/time, or fallback cell editor. Existing text-only integrations may pass `{ el: input }` instead. See the [Formula API](/api/formula/) for custom adapters and the typed `getFormulaBarState()` / `setFormulaBarValue()` runtime.

## 2. Dependency highlighting

Formula installs or reuses `FormulaDependencyHighlightPlugin`. By default it highlights references only while a formula is being edited. Set `highlightOnFocus: true` to also highlight when a formula cell is merely focused.

```ts
grid.plugins = [FormulaPlugin];
grid.formulaDependencyHighlight = {
  highlightOnFocus: true,
  includeNamedRanges: true,
  dependencyClass: 'formula-source-cell',
  formulaCellClass: 'formula-active-cell',
  dependencyColors: ['#2563eb', '#dc2626', '#16a34a'],
};
```

**Expected result:** focusing C1 with raw `=A1*B1` marks A1 and B1 as dependencies and C1 as the active formula cell. Set `grid.formulaDependencyHighlight = false` to disable the behavior.

Highlights cover direct A1 cells/ranges and named ranges. They do not expand named formulas or a complete transitive dependency graph.

## 3. Named dropdown

`createNamedRangeDropdown` deduplicates a range into dropdown options. Register `ColumnDropdown` as the column type.

```ts
import {
  ColumnDropdown,
  FormulaPlugin,
  createNamedRangeDropdown,
} from '@revolist/revogrid-pro';

const source = [
  { allowed: 'Open', selected: 'Open' },
  { allowed: 'Open', selected: 'Closed' },
  { allowed: 'Closed', selected: null },
];
const names = [{ name: 'AllowedStatuses', kind: 'range' as const, ref: 'A1:A3' }];
const columns = [
  { prop: 'allowed', name: 'Allowed status' }, // A
  {
    prop: 'selected',
    name: 'Selected status',
    columnType: 'statusDropdown',
    dropdown: createNamedRangeDropdown('AllowedStatuses', {
      allSources: source,
      columns: [
        { prop: 'allowed', name: 'Allowed status' },
        { prop: 'selected', name: 'Selected status' },
      ],
      names,
    }),
  },
];

grid.plugins = [FormulaPlugin];
grid.columnTypes = { statusDropdown: ColumnDropdown };
grid.formulaNames = { names };
grid.columns = columns;
grid.source = source;
```

**Expected result:** the Selected status editor offers `Open` and `Closed` once each, even though `Open` appears twice in the named range.

## 4. Conditional formatting

The helper receives the current cell through `cellvalue` and 1-based `row` / `column` tokens.

```ts
import { createFormulaConditionalCellProperties } from '@revolist/revogrid-pro';

const source = [
  { status: 'Open' },
  { status: 'Closed' },
];
const columns = [{ prop: 'status', name: 'Status' }];

columns[0].cellProperties = createFormulaConditionalCellProperties(
  '=cellvalue="Closed"',
  { class: 'is-closed' },
  { allSources: source, columns },
);
grid.columns = columns;
grid.source = source;
```

```css
revo-grid .is-closed {
  color: #166534;
  background: #dcfce7;
  font-weight: 600;
}
```

**Expected result:** only row 2 receives `is-closed`. `=row=2` matches the same row; `=column=1` matches cells in the first authored column. Comparisons support `>`, `>=`, `<`, `<=`, `=`, and `<>` for numeric and string values.

## Composition checklist

- Configure `FormulaPlugin` once.
- Add a Formula Bar only when users need an editor outside the cell.
- Use `highlightOnFocus: true` only when passive focus should reveal dependencies.
- Register `ColumnDropdown` before assigning a named-range dropdown column.
- Supply the same source, columns, and names to helper factories that the grid uses.
- Tear down external listeners and set `grid.formulaBar = null` when removing their hosts.

## Next steps

**Previous:** [Named Ranges](/guides/formula/named-ranges/) · **Next:** [Cross-sheet Formulas](/guides/formula/cross-sheet/) · **Deeper reference:** [Formula API](/api/formula/)

---

# Named Ranges

URL: https://pro.rv-grid.com/guides/formula/named-ranges/
Source: src/content/docs/guides/formula/named-ranges.mdx
Description: Use workbook and sheet names for constants, ranges, reusable formulas, and runtime navigation.

Names replace repeated coordinates and values with business terms. `FormulaPlugin` installs or reuses the named-range runtime automatically. Register `NamedRangesPlugin` explicitly when your application needs its runtime methods, events, or Name Manager.

Names are case-insensitive. A name must start with a letter, underscore, or backslash; it cannot contain spaces, resemble an A1 cell such as `B12`, or match a FormulaJS function. Formula names must store a value beginning with `=`.

## 1. Named constant

```ts
import { FormulaPlugin } from '@revolist/revogrid-pro';

grid.plugins = [FormulaPlugin];
grid.columns = [
  { prop: 'subtotal', name: 'Subtotal' }, // A
  { prop: 'total', name: 'With tax' },   // B
];
grid.formulaNames = {
  names: [{ name: 'TaxRate', kind: 'constant', value: 0.2 }],
};
grid.source = [{ subtotal: 100, total: '=A1*(1+TaxRate)' }];
```

**Expected result:** B1 displays `120`. Changing `TaxRate` to `0.25` and reassigning `grid.formulaNames` recalculates B1 to `125`.

## 2. Named range

```ts
grid.columns = [
  { prop: 'label', name: 'Period' }, // A
  { prop: 'amount', name: 'Amount' }, // B
];
grid.formulaNames = {
  names: [{ name: 'SalesRevenue', kind: 'range', ref: 'B1:B3' }],
};
grid.source = [
  { label: 'Jan', amount: 100 },
  { label: 'Feb', amount: 200 },
  { label: 'Mar', amount: 300 },
  { label: 'Total', amount: '=SUM(SalesRevenue)' },
];
```

**Expected result:** B4 displays `600`.

:::note
`Revenue` is a FormulaJS function name, so this guide uses `SalesRevenue`. Name validation rejects function-name collisions instead of creating an ambiguous expression.
:::

## 3. Named formula

Build on the preceding range and add a reusable formula:

```ts
grid.formulaNames = {
  names: [
    { name: 'TaxRate', kind: 'constant', value: 0.2 },
    { name: 'SalesRevenue', kind: 'range', ref: 'B1:B3' },
    {
      name: 'AfterTaxSales',
      kind: 'formula',
      value: '=SUM(SalesRevenue)-SUM(SalesRevenue)*TaxRate',
    },
  ],
};

grid.source = [
  { label: 'Jan', amount: 100 },
  { label: 'Feb', amount: 200 },
  { label: 'Mar', amount: 300 },
  { label: 'Net', amount: '=AfterTaxSales' },
];
```

**Expected result:** B4 displays `480`. Circular names, including two formula names that refer to each other, resolve to `#ERROR`.

## 4. Workbook and sheet scope

An unqualified name first uses the active sheet's local definition, then the workbook definition. Qualify a name to bypass that precedence.

```ts
grid.formulaNames = {
  activeSheetId: 'Q4',
  names: [
    { name: 'TaxRate', scope: 'workbook', kind: 'constant', value: 0.2 },
    { name: 'TaxRate', scope: 'sheet', sheetId: 'Q4', kind: 'constant', value: 0.25 },
    { name: 'TaxRate', scope: 'sheet', sheetId: 'Q1', kind: 'constant', value: 0.1 },
  ],
};
grid.columns = [
  { prop: 'local', name: 'Local' },
  { prop: 'global', name: 'Workbook' },
  { prop: 'q1', name: 'Q1' },
];
grid.source = [{
  local: '=TaxRate',
  global: '=workbook!TaxRate',
  q1: '=Q1!TaxRate',
}];
```

**Expected result:** A1 displays `0.25`, B1 displays `0.2`, and C1 displays `0.1`. Duplicate display names are allowed across distinct scopes, but not twice within the same scope.

## Runtime management

Register the runtime explicitly, then retrieve it with a typed guard:

```ts
import {
  FormulaPlugin,
  NamedRangesPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [NamedRangesPlugin, FormulaPlugin];

const plugins = await grid.getPlugins();
const namedRanges = plugins.find(plugin => plugin instanceof NamedRangesPlugin);
if (!namedRanges) throw new Error('NamedRangesPlugin is not mounted');

const validation = namedRanges.validateFormulaNameRef({
  name: 'ForecastRange',
  kind: 'range',
  ref: 'D2:D20',
});
if (!validation.valid) throw new Error(validation.errors.join('; '));

namedRanges.upsertFormulaName({
  name: 'ForecastRange',
  kind: 'range',
  ref: 'D2:D20',
});
await namedRanges.jumpToFormulaName('ForecastRange');
namedRanges.deleteFormulaName('ForecastRange', 'workbook');
```

Listen on the grid for `formulanameschange`, `formulanamevalidationerror`, and `formulanamejump` when application UI needs to react to those operations.

```ts
const onNamesChange = (event: CustomEvent) => console.log(event.detail);
grid.addEventListener('formulanameschange', onNamesChange);

// Teardown
grid.removeEventListener('formulanameschange', onNamesChange);
```

The bundled manager provides create, edit, delete, validation, and range navigation:

```ts
import { defineFormulaNameManager } from '@revolist/revogrid-pro';

const panel = document.querySelector<HTMLElement>('#name-manager');
if (panel) defineFormulaNameManager(panel, grid, { pageSize: 50 });
```

## Reference updates and immutable data

With `autoUpdateRefs` enabled (the default), deterministic row/column insertions and deletions update range refs, named formulas, and raw source formulas. If row 1 is inserted before `B1:B3`, the name becomes `B2:B4`; deleting a referenced row shrinks the range. Set `autoUpdateRefs: false` to preserve authored strings unchanged.

Pinning, sorting, filtering, hiding, and other presentation changes never rewrite refs. Applications that replace every row with immutable clones may set `rowIdProp` to a stable, present, unique record key so surviving rows retain their authored identity. See [A1 References and Autofill](/guides/formula/a1-references-autofill/) for the full structural model.

## Putting names into an application

Add only the surface the user needs: Formula Bar for direct editing, Name Manager for registry maintenance, dependency highlighting for inspection, named dropdowns for list choices, and conditional formulas for styling. Each integration has an independent copyable example in [Formula UI and Helpers](/guides/formula/formula-ui/).

## Next steps

**Previous:** [A1 References and Autofill](/guides/formula/a1-references-autofill/) · **Next:** [Formula UI and Helpers](/guides/formula/formula-ui/) · **Deeper reference:** [Formula API](/api/formula/)

---

# Overview

URL: https://pro.rv-grid.com/guides/formula/overview/
Source: src/content/docs/guides/formula/overview.mdx
Description: Understand what Formula calculates, what remains in source data, and which guide to use next.

Formula adds spreadsheet-style calculations to RevoGrid. A source value beginning with `=` is stored as an expression, while the mounted grid renders its derived result. For example, source data can retain `=A1*B1` while the cell displays `30`.

The contract is deliberately narrower than Excel:

- A1 coordinates follow the authored row and column order, not the current sorted, filtered, pinned, or hidden presentation.
- Formula recalculates mounted cells when configured source or workbook data changes. It does not replace the raw formula in `grid.source` with the result.
- Invalid syntax, unknown functions, and circular references resolve to `#ERROR`. Autofill that moves a relative reference before A1 produces `#REF!`.
- Functions come from FormulaJS, but RevoGrid owns the expression parser. Use the [documented FormulaJS-backed subset](/guides/formula/supported-functions/), not assumed full Excel compatibility.

## Try the demo

The demo is an Orders grid connected to a Product List dataset. In the workbook legend, **Orders** is the mounted RevoGrid. **Product List** is external sheet data available to the formula engine; it is not a second mounted grid. On narrow screens the legend stacks these parts without changing that relationship.

| Control | What to observe |
| --- | --- |
| Select a formula cell | The Formula Bar shows the raw `=...` expression while the grid keeps showing the calculated value. |
| **Names on/off** | Formulas switch between readable names and direct A1 references without changing their results. |
| **Insert row** | References below the inserted row update to keep pointing at the same logical data. |
| **Name manager** | View and edit range, constant, and formula names used by the workbook. |
| **Raise catalog price** | Product List changes through the mounted Formula API and dependent Orders cells recalculate. |
| **Reload service lookup** | The async formula is invalidated, briefly shows its loading state, then renders the refreshed service value. |

## Choose your path

| Goal | Start here | Helpful first |
| --- | --- | --- |
| Add your first calculated column | [Quick Start](/guides/formula/quick-start/) | RevoGrid columns and source data |
| Copy formulas or understand A1 identity | [A1 References and Autofill](/guides/formula/a1-references-autofill/) | Quick Start |
| Replace coordinates with readable names | [Named Ranges](/guides/formula/named-ranges/) | A1 references |
| Add a Formula Bar, highlights, lists, or styling | [Formula UI and Helpers](/guides/formula/formula-ui/) | Quick Start |
| Look up values in another dataset | [Cross-sheet Formulas](/guides/formula/cross-sheet/) | A1 references |
| Call an application service from a formula | [Async Formula Functions](/guides/formula/async-functions/) | Quick Start |
| Recalculate and persist without a grid | [Backend Calculation and Persistence](/guides/formula/backend-calculation/) | Cross-sheet formulas |
| Check syntax and available functions | [Supported Functions](/guides/formula/supported-functions/) | Quick Start |

## Next steps

**Next:** [Quick Start](/guides/formula/quick-start/) · **Deeper reference:** [Formula API](/api/formula/)

---

# Quick Start

URL: https://pro.rv-grid.com/guides/formula/quick-start/
Source: src/content/docs/guides/formula/quick-start.mdx
Description: Install Formula, calculate line totals, aggregate results, and fill formulas into new rows.

## Install

```bash
pnpm add @revolist/revogrid @revolist/revogrid-pro
```

## 1. Calculate line totals

This complete Vanilla TypeScript example maps A to `qty`, B to `unitPrice`, and C to `total`. Register the custom element, attach the grid, configure Formula, and assign `source` last.

```html
<div id="grid" style="height: 320px"></div>
```

```ts
import { defineCustomElements } from '@revolist/revogrid/loader';
import { FormulaPlugin } from '@revolist/revogrid-pro';
import '@revolist/revogrid/dist/revo-grid/revo-grid.css';
import '@revolist/revogrid-pro/styles.css';

defineCustomElements();
const grid = document.createElement('revo-grid');
grid.columns = [
  { prop: 'qty', name: 'Quantity' },          // A
  { prop: 'unitPrice', name: 'Unit price' },  // B
  { prop: 'total', name: 'Total' },           // C
];
grid.plugins = [FormulaPlugin];
document.querySelector('#grid')?.append(grid);

grid.source = [
  { qty: 3, unitPrice: 10, total: '=A1*B1' },
  { qty: 2, unitPrice: 12, total: '=A2*B2' },
];
```

**Expected result:** C1 displays `30` and C2 displays `24`. Reading `grid.source` still returns the raw strings `=A1*B1` and `=A2*B2`.

## 2. Aggregate calculated cells

Add a third ordinary row whose C cell sums the first two calculated totals:

```ts
grid.source = [
  { qty: 3, unitPrice: 10, total: '=A1*B1' },
  { qty: 2, unitPrice: 12, total: '=A2*B2' },
  { qty: '', unitPrice: 'Grand total', total: '=SUM(C1:C2)' },
];
```

**Expected result:** C3 displays `54`. Formula resolves C1 and C2 before calculating their range total.

:::note
This example uses an ordinary source row so its A1 address is unambiguous. Pinned-top, main, and pinned-bottom rows share one authored coordinate space; learn that ordering in [A1 References and Autofill](/guides/formula/a1-references-autofill/).
:::

## 3. Fill a formula

Enable range selection to show the fill handle. Seed C1, then drag its handle down to C2.

```ts
grid.range = true;
grid.source = [
  { qty: 3, unitPrice: 10, total: '=A1*B1' },
  { qty: 2, unitPrice: 12, total: null },
];
```

**Expected result:** the fill writes raw `=A2*B2` into C2, which displays `24`. Relative references move with the destination; `$` anchors remain fixed.

`FormulaPlugin` installs or reuses its required Autofill, dependency-highlight, and named-range runtimes. You may register those plugins explicitly when you need their public APIs or custom configuration, but basic formulas do not require duplicate registrations.

## What happens when data changes?

Editing a referenced mounted cell causes dependent formula cells to recalculate. The source continues to own the expression, so persistence code sees `=A1*B1`, not `30`. Use [Backend Calculation and Persistence](/guides/formula/backend-calculation/) when you also need stored calculated values.

| Symptom | Cause |
| --- | --- |
| The cell displays text such as `A1*B1` | The source string is missing its leading `=`. |
| `#ERROR` | Syntax is invalid, a function/name is unknown, or the dependency is circular. |
| `#REF!` after fill | A translated relative reference moved before column A or row 1. |

## Framework examples

The complete demo has equivalent [Vanilla TypeScript](https://github.com/revolist/revogrid-pro/blob/master/examples/components/src/components/formula/Formula.ts), [React](https://github.com/revolist/revogrid-pro/blob/master/examples/components/src/components/formula/Formula.tsx), [Vue 3](https://github.com/revolist/revogrid-pro/blob/master/examples/components/src/components/formula/Formula.vue), and [Angular](https://github.com/revolist/revogrid-pro/blob/master/examples/components/src/components/formula/FormulaAngular.ts) sources.

## Next steps

**Previous:** [Overview](/guides/formula/overview/) · **Next:** [A1 References and Autofill](/guides/formula/a1-references-autofill/) · **Deeper reference:** [Formula API](/api/formula/)

---

# Supported Functions

URL: https://pro.rv-grid.com/guides/formula/supported-functions/
Source: src/content/docs/guides/formula/supported-functions.mdx
Description: Learn Formula expression syntax and browse verified FormulaJS-backed grid patterns.

Formula uses functions from FormulaJS through RevoGrid's own expression parser. This is a documented FormulaJS-backed subset, not full Excel compatibility and not every call accepted by the standalone FormulaJS JavaScript API.

## Grid formula syntax

- Stored grid formulas begin with `=`.
- Function arguments use commas.
- Values can come from A1 cells, rectangular A1 ranges, names, numbers, quoted strings, and `TRUE` / `FALSE`.
- Sheet ids containing spaces use quotes: `'Product List'!A1:B3`.
- Arithmetic supports `+`, `-`, `*`, `/`, parentheses, and unary signs.
- Comparisons support `>`, `>=`, `<`, `<=`, `=`, and `<>`.
- Nested supported function calls are evaluated from the inside out.

JavaScript array literals such as `[1,2,3]` are not grid formula syntax. Put values in cells and pass an A1 range such as `A1:A3`, or use a named range. Low-level `evaluate()` examples in the FormulaJS project are JavaScript API calls and may not be copyable grid formulas.

## Verified patterns

The following catalog uses one deterministic fixture and is exercised by the Formula documentation test.

## Lookup support

The tested lookup set is `LOOKUP`, `VLOOKUP`, `HLOOKUP`, and `INDEX` with `MATCH`. `XLOOKUP` is not currently supported. For a complete external-sheet fixture, see [Cross-sheet Formulas](/guides/formula/cross-sheet/).

## Error values

| Situation | Result |
| --- | --- |
| Unknown syntax/function or circular formula/name | `#ERROR` |
| Autofill translates a relative reference before A1 | `#REF!` |
| A mounted formula explicitly references an external sheet that is not registered | `#LOADING` |
| An async formula rejects without a custom `errorValue` or `mapError` | `#ERROR` |

FormulaJS exposes more functions than are shown here, but parser compatibility and argument shapes still matter. Verify an unlisted function with your actual data before treating it as part of an application contract.

## Next steps

**Previous:** [Backend Calculation and Persistence](/guides/formula/backend-calculation/) · **Next:** [Formula API](/api/formula/) · **Deeper reference:** [Quick Start](/guides/formula/quick-start/)

---

# Gantt Overview

URL: https://pro.rv-grid.com/guides/gantt/
Source: src/content/docs/guides/gantt/index.mdx
Description: RevoGrid Gantt with deterministic scheduling, timeline editing, dependencies, resources, baselines, and diagnostics.
Surface: gantt

<style>{`
  :root {
    --sl-content-width: 1000px;
  }
`}</style>

RevoGrid Gantt is a standalone commercial project-planning package built on RevoGrid. It combines a virtualized task table with a scheduling engine and interactive timeline for dependencies, resources, progress, critical path, baselines, and project analysis.

    Create a `revo-grid` element and configure Gantt through public element properties.
    [Start with TypeScript](/guides/gantt/introduction/vanilla-typescript/)

    Bind Gantt properties through `@revolist/react-datagrid`.
    [Start with React](/guides/gantt/introduction/react/)

    Use `@revolist/vue3-datagrid` with reactive project collections.
    [Start with Vue](/guides/gantt/introduction/vue/)

    Use the standalone `RevoGrid` wrapper and property bindings.
    [Start with Angular](/guides/gantt/introduction/angular/)

## How Gantt Fits Together

```txt
tasks + calendars + dependencies + resources + assignments
                         │
                         ▼
              deterministic scheduler
                         │
                         ▼
          projected task rows + timeline geometry
                         │
                         ▼
          RevoGrid rendering and interaction surface
```

Your application owns project data and persistence. `GanttPlugin` validates and schedules that data, projects it into task-table rows and timeline geometry, and routes supported edits back through Gantt mutation services. RevoGrid owns virtualization, columns, selection, keyboard navigation, and the browser rendering lifecycle.

## What You Can Build

- Work breakdown structures with tasks, summaries, and milestones.
- Automatic or manual schedules using calendars, dependencies, constraints, and deadlines.
- Resource assignments, capacity analysis, effort modes, and leveling.
- Baseline comparison, progress tracking, slack, and critical-path analysis.
- Editable timelines with drag, resize, progress, dependency, task-editor, and context-menu workflows.
- JSON and Microsoft Project interchange plus grid, Excel, and print-oriented export workflows.

## Recommended Path

1. Complete [Installation](/guides/gantt/introduction/installation/) and one framework quick start.
2. Follow the [project tutorial](/guides/gantt/tutorial/) to add dependencies, resources, editing, baselines, and export.
3. Learn the [data model](/guides/gantt/concepts/data-model/) and [scheduling model](/guides/gantt/scheduling/overview/).
4. Explore the searchable [Gantt examples](/guides/gantt/examples/).
5. Use the [Gantt API reference](/api/gantt/) for exact signatures.

  These guides document capabilities present in this repository. See <a href="/guides/gantt/reference/limitations/">Limitations</a> for intentional boundaries and Microsoft Project differences.

---

# Gantt Baselines

URL: https://pro.rv-grid.com/guides/gantt/concepts/baselines/
Source: src/content/docs/guides/gantt/concepts/baselines.mdx
Description: Capture a baseline snapshot of your schedule and overlay it beneath current task bars to visualise drift.
Surface: gantt

A **baseline** is a saved snapshot of task dates and progress at a specific point in time (e.g. when the project was approved).
The Gantt chart can overlay these baseline bars beneath the live bars, making schedule drift immediately visible.

---

## Adding a Baseline

Pass one or more `BaselineSnapshot` objects via `grid.ganttBaselines`:

```typescript
grid.ganttBaselines = [
  {
    id: 'baseline-approved',
    name: 'Approved Plan',
    capturedAt: '2026-04-01T08:00:00Z',
    tasks: [
      { taskId: 't1', startDate: '2026-04-06', endDate: '2026-04-22', duration: 13, progressPercent: 0 },
      { taskId: 't2', startDate: '2026-04-06', endDate: '2026-04-10', duration: 5,  progressPercent: 0 },
      { taskId: 't3', startDate: '2026-04-10', endDate: '2026-04-10', duration: 0,  progressPercent: 0 },
      { taskId: 't4', startDate: '2026-04-13', endDate: '2026-04-22', duration: 8,  progressPercent: 0 },
      { taskId: 't5', startDate: '2026-04-23', endDate: '2026-05-16', duration: 18, progressPercent: 0 },
      { taskId: 't6', startDate: '2026-04-23', endDate: '2026-05-09', duration: 13, progressPercent: 0 },
      { taskId: 't7', startDate: '2026-04-23', endDate: '2026-05-16', duration: 18, progressPercent: 0 },
      { taskId: 't8', startDate: '2026-05-16', endDate: '2026-05-16', duration: 0,  progressPercent: 0 },
    ],
  },
];
```

You can also capture a snapshot from the current scheduled state:

```typescript
const plugins = await grid.getPlugins();
const gantt = plugins.find((plugin) => plugin.constructor?.name === 'GanttPlugin');
const baseline = gantt?.captureBaseline?.({
  id: 'baseline-current',
  name: 'Current Approved Plan',
  capturedAt: '2026-04-15T08:00:00Z',
});

if (baseline) {
  grid.ganttBaselines = [
    ...(grid.ganttBaselines ?? []),
    baseline,
  ];
}
```

## Enabling the Overlay

Turn on baseline rendering through the `visuals` key in your project config:

```typescript
grid.gantt = {
  // …required fields
  visuals: {
    showBaseline: true,
    baselineId: 'baseline-approved', // optional — defaults to the latest snapshot
  },
};
```

When `showBaseline` is `true`, a translucent bar is drawn behind each live task bar showing its baseline position.

  Only tasks listed in `BaselineSnapshot.tasks` show a baseline bar. Tasks added after the snapshot was captured render without one.

## Multiple Baselines

You can store several snapshots and switch between them at runtime:

```typescript
// Initially show the approved plan
grid.gantt = { ...config, visuals: { showBaseline: true, baselineId: 'baseline-approved' } };

// Switch to a re-baseline after scope change
grid.gantt = { ...config, visuals: { showBaseline: true, baselineId: 'baseline-replan' } };
```

## Variance Columns

When a baseline is visible, each projected task row also exposes optional variance fields:

| Field | Description |
|---|---|
| `startVarianceDays` | Current scheduled start minus baseline start, in calendar days |
| `finishVarianceDays` | Current scheduled finish minus baseline finish, in calendar days |
| `durationVariance` | Current scheduled duration minus baseline duration |
| `progressVariancePercent` | Current progress minus baseline progress, in percentage points |

Add the default columns when users need to inspect drift numerically:

```typescript
grid.columns = [
  createDefaultTaskTableColumn('name'),
  createDefaultTaskTableColumn('startVarianceDays'),
  createDefaultTaskTableColumn('finishVarianceDays'),
  createDefaultTaskTableColumn('durationVariance'),
  createDefaultTaskTableColumn('progressVariancePercent'),
];
```

## BaselineSnapshot Fields

| Field | Type | Description |
|---|---|---|
| `id` | `BaselineId` | Unique identifier for this snapshot |
| `name` | `string` | Human-readable label (e.g. `"Q1 Approved Plan"`) |
| `capturedAt` | `ISODateTimeString` | When the snapshot was taken |
| `tasks` | `BaselineTaskSnapshot[]` | Per-task date and progress records |

### BaselineTaskSnapshot Fields

| Field | Type | Description |
|---|---|---|
| `taskId` | `TaskId` | References the live task |
| `startDate` | `ISODateString` | Baseline start date |
| `endDate` | `ISODateString` | Baseline end date |
| `duration` | `number` | Baseline task duration |
| `progressPercent` | `number` | Baseline progress (0–100) |

---

# Data Model

URL: https://pro.rv-grid.com/guides/gantt/concepts/data-model/
Source: src/content/docs/guides/gantt/concepts/data-model.mdx
Description: Required grid properties and Gantt entity collections.
Surface: gantt

This page is for wiring the minimum data surface.

Required entry points on `HTMLRevoGridElement`:

- `gantt`: project config (`GanttPluginConfig`)
- `source`: flat task rows
- `ganttCalendars`: `CalendarEntity[]`

Optional linked collections:

- `ganttDependencies`: `DependencyEntity[]`
- `ganttResources`: `ResourceEntity[]`
- `ganttAssignments`: `AssignmentEntity[]`
- `ganttBaselines`: `BaselineSnapshot[]`

Public shape is declared in:

- `packages/gantt/src/gantt/grid/gantt-plugin.types.ts`
- `packages/gantt/src/gantt/core/domain.ts`

## Flat Task Source Rows

Gantt reads task data from flat grid rows. Required fields are `id`, `name`, `startDate`, and either `duration` or `endDate`.

The public source row names match task-table editing conventions:

- `duration` maps to internal `duration`.
- `percentDone` maps to internal `progressPercent`.
- `taskMode` maps to internal `manuallyScheduled` (`manual` or `auto`).
- `workflowStatus` stores the optional authored workflow key: `not-started`, `in-progress`, `done`, or `blocked`.
- `status` is calculated after scheduling from `% Done`, actual finish, scheduled dates, calendars, splits, and the project `statusDate`; it is not authored or editable.

When both `duration` and `endDate` are present, `duration` is the scheduling input and Gantt resolves `endDate` from `startDate + duration`. This matches task-table editing, where duration edits drive the finish date. Use `endDate` without `duration` when the finish date should be the authored input.

Projected grid rows remain display-ready. `GanttGridRow.status` is the calculated human-readable label, while `GanttGridRow.statusKey` and `statusIndicator` contain `complete`, `on-schedule`, `late`, or `future-task`. The authored workflow value is projected separately as `workflowStatus` and `workflowStatusKey`. Custom source fields are preserved by task id across recalculation and structural task changes unless the row is replaced without those fields.

Legacy source or JSON tasks that contain one of the old workflow values in `status` are migrated to `workflowStatus` when the new field is absent. New serialization emits only `workflowStatus`.

## Temporal Field Precision

Task temporal fields (`startDate`, `endDate`, `actualStartDate`, `actualFinishDate`) accept:

- ISO date: `YYYY-MM-DD`
- UTC ISO datetime: `YYYY-MM-DDTHH:mm:ss.sssZ`

Runtime normalization rules:

- Datetime input is preserved and used for intraday scheduling precision.
- Date-only input is normalized to `T00:00:00Z`.

For new integrations, prefer explicit UTC datetime values when you need hour/minute planning behavior.

---

# Dependencies

URL: https://pro.rv-grid.com/guides/gantt/concepts/dependencies/
Source: src/content/docs/guides/gantt/concepts/dependencies.mdx
Description: Dependency types, lag/lead, and validation behavior.
Surface: gantt

Dependencies constrain automatic successors using the relationship type and optional lag:

| Type | MSP token | Constraint |
|---|---|---|
| `finish-to-start` | `FS` | Successor starts after predecessor finishes. |
| `start-to-start` | `SS` | Successor starts no earlier than predecessor starts. |
| `finish-to-finish` | `FF` | Successor finishes no earlier than predecessor finishes. |
| `start-to-finish` | `SF` | Successor finishes no earlier than predecessor starts. |

## Using Lag and Lead

Use `lagDays` for lag or lead:

```typescript
grid.ganttDependencies = [
  {
    id: 'build-test',
    predecessorTaskId: 'build',
    successorTaskId: 'test',
    type: 'finish-to-start',
    lagDays: -2,
  },
];
```

Positive `lagDays` delays the successor. Negative `lagDays` is lead time and allows overlap, matching Microsoft Project's negative lead syntax.

`lagCalendar` in scheduling config controls whether lag is interpreted as calendar days or working days.

## Inline Cell Syntax

Inline predecessor/successor cells accept MSP-style tokens:

```text
1FS
2SS+3
3FF-1d
task-4SF-2
```

Blank or invalid lag normalizes to `0`. The optional `d` suffix is accepted. Whitespace around tokens is ignored.

## Validation Behavior

Important dependency behavior:

- Circular dependency chains are invalid schedule data. RevoGrid reports them as `dependency-cycle` issues with the involved `taskIds` and `dependencyIds`.
- New dependency edits that would create a cycle are rejected before they change the Gantt store.
- Task row drops that would make dependency partners parent/child through the outline are rejected before the drop is committed.
- Imported projects that already contain a cycle still render, but automatic dependency propagation and drag/resize dependency clamping are not applied while the active dependency graph is cyclic.
- Missing predecessor/successor references produce issues.
- Dependency links are rendered in the overlay layer and can be created/edited interactively.

This matches the Microsoft Project scheduling model: a loop such as `Setup load balancer -> Configure firewall -> Setup load balancer` cannot produce a valid schedule. Remove or change one of the invalid links, then rerun scheduling.

When building diagnostics UI, inspect the scheduling result issues:

```typescript
const cycle = schedulerResult.issues.find((issue) => issue.code === 'dependency-cycle');

if (cycle) {
  console.warn('Dependency cycle', {
    taskIds: cycle.taskIds,
    dependencyIds: cycle.dependencyIds,
  });
}
```

## Examples

### Auto Successor Clamps to FS Dependency

An automatic successor cannot silently move before its predecessor allows:

```typescript
grid.source = [
  {
    id: 'design',
    name: 'Design',
    startDate: '2026-04-01',
    duration: 3,
    taskMode: 'auto',
  },
  {
    id: 'build',
    name: 'Build',
    startDate: '2026-04-01',
    duration: 2,
    taskMode: 'auto',
  },
];

grid.ganttDependencies = [{
  id: 'design-build',
  predecessorTaskId: 'design',
  successorTaskId: 'build',
  type: 'finish-to-start',
  lagDays: 0,
}];
```

Expected result: `design` ends on `2026-04-03`, so `build` is scheduled no earlier than `2026-04-04`. If the user drags `build` left, the effective bar snaps back to the dependency-valid date.

### Manual Successor Keeps Date and Warns

Manual tasks preserve authored dates, but dependency violations remain visible:

```typescript
grid.source = [
  { id: 'design', startDate: '2026-04-01', duration: 3 },
  {
    id: 'review',
    name: 'Manual Review',
    startDate: '2026-04-02',
    duration: 1,
    taskMode: 'manual',
  },
];

grid.ganttDependencies = [{
  id: 'design-review',
  predecessorTaskId: 'design',
  successorTaskId: 'review',
  type: 'finish-to-start',
  lagDays: 0,
}];
```

Expected result: `review` stays on `2026-04-02` and receives a `manual-dependency-violation` warning because the dependency requires `2026-04-04`.

See the [Advanced dependencies demo](https://demo.rv-grid.com/gantt-dependencies-advanced/ts) for a runnable project containing FS, SS, FF, and SF links with lag and lead.

Implementation sources:

- `packages/gantt/src/gantt/engine/dependency-graph.ts`
- `packages/gantt/src/gantt/engine/scheduler-engine/validation.ts`
- `packages/gantt/src/gantt/features/dependencies/`

---

# Tasks, Summaries, And Milestones

URL: https://pro.rv-grid.com/guides/gantt/concepts/tasks/
Source: src/content/docs/guides/gantt/concepts/tasks.mdx
Description: Task types and hierarchy behavior.
Surface: gantt

Task hierarchy is represented by `parentId`.

- `type: 'task'`: normal scheduled item.
- `type: 'summary'`: rollup row; dates and progress come from children.
- `type: 'milestone'`: zero duration (`startDate === endDate`, `duration: 0`).

Scheduling-relevant source fields include `duration`, `durationUnit`, `durationIsElapsed`, `taskMode`, `constraintType`, `constraintDate`, `deadlineDate`, `effortMode`, `workHours`, `workUnit`, `percentDone`, `actualStartDate`, `actualFinishDate`, `remainingDuration`, `splitRanges`, `priority`, and `canLevel`. See [Duration Units and Conversion](/guides/gantt/scheduling/durations/) for mixed units and text input.

`duration`, `remainingDuration`, and `workHours` are stored in canonical hours. `durationUnit` is retained display/edit metadata for duration spans, while `workUnit` independently controls Work. Text quantities are converted to hours on input and converted from hours only when rendered.

Source row contract: `GanttTaskSourceRow` in `packages/gantt/src/gantt/grid/gantt-plugin.types.ts`. Internal task entities use `manuallyScheduled`, `duration`, and `progressPercent` in `packages/gantt/src/gantt/core/domain.ts`.

---

# How Gantt Builds On RevoGrid

URL: https://pro.rv-grid.com/guides/gantt/customization/how-gantt-builds-on-revogrid/
Source: src/content/docs/guides/gantt/customization/how-gantt-builds-on-revogrid.mdx
Description: Division of responsibilities between RevoGrid and Gantt plugin layers.
Surface: gantt

RevoGrid provides row/column virtualization, editing, selection, scrolling, and base rendering. Gantt extends that with timeline projection, dependency overlays, scheduling, and resource planning.

Implementation layers:

- Grid/plugin orchestration: `packages/gantt/src/gantt/grid/gantt-plugin.ts`
- Scheduling engine: `packages/gantt/src/gantt/engine/`
- Projection and timeline model: `packages/gantt/src/gantt/projection/`
- Interaction features: `packages/gantt/src/gantt/features/`

Use this split when debugging behavior: if data rules changed, inspect `engine`; if visual output changed, inspect `projection/features`; if event routing changed, inspect `grid`.

---

# Gantt Timeline and Zoom

URL: https://pro.rv-grid.com/guides/gantt/customization/timeline-zoom/
Source: src/content/docs/guides/gantt/customization/timeline-zoom.mdx
Description: Configure timeline scale, zoom behavior, wheel interaction, and visual timeline overlays.
Surface: gantt

The Gantt timeline can be configured at two levels:

1. `zoomPreset` for fast setup with built-in levels.
2. `zoom` for full control over levels, wheel behavior, and anchor strategy.

Use `weekStartsOn` when week headers or week ticks should align to a specific
weekday. Gantt defaults to Sunday-start weeks.

---

## Quick Start with `zoomPreset`

Use a built-in preset when you only need a standard timeline scale:

```typescript
grid.gantt = {
  // ...required project fields
  zoomPreset: 'week-month',
};
```

Supported presets:

- `'minute-hour'` (15-minute ticks grouped by hour)
- `'hour-day'` (hour ticks grouped by day)
- `'day-week'`
- `'week-month'`
- `'month-quarter'`
- `'quarter-year'`
- `'year-quarter'`
- `'multi-year-quarter'`

By default, the interactive zoom ladder starts at `day-week` and excludes the intraday presets for performance. Use `zoomPreset: 'hour-day'`, `zoomPreset: 'minute-hour'`, or explicit `zoom.levels` when an intraday timeline is required.

## Week Start

Week-based timeline headers, week ticks, and padded week ranges use Sunday by default:

```typescript
grid.gantt = {
  // ...required project fields
  weekStartsOn: 0, // Sunday, default
};
```

Set `weekStartsOn: 1` when the Gantt should use Monday-start weeks:

```typescript
grid.gantt = {
  // ...required project fields
  weekStartsOn: 1, // Monday
  zoomPreset: 'week-month',
};
```

`weekStartsOn` accepts `0` for Sunday or `1` for Monday. It affects timeline week boundaries only; task calendars still use their own `workingDays` configuration.

## Time Modes

Gantt timeline modes are defined by `tickUnit` + `headerRows` in each zoom level.

- `minute-hour`: 15-minute timeline resolution for intraday planning windows.
- `hour-day`: hourly timeline resolution grouped under day headers.
- `day-week`: daily planning view.
- `week-month`: weekly planning view.
- `month-quarter`: monthly planning view.
- `quarter-year`, `year-quarter`, `multi-year-quarter`: portfolio and long-range views.

Recommended usage pattern:

- Opt into `minute-hour` for short execution windows and handoffs.
- Opt into `hour-day` for same-day and next-day coordination.
- Use `day-week` or coarser for baseline and milestone planning.

  Intraday modes (`minute-hour`, `hour-day`) control timeline granularity and interaction scale. Temporal fields still use the same names, but when you need intraday precision you should pass UTC datetime values (`...Z`) instead of date-only strings.

## Hour Mode

Use hour mode when task bars should move, resize, and create on hour boundaries
instead of whole-day boundaries. The important settings are:

- `timelinePrecision: 'hour'` makes timeline interactions use hour precision by default.
- `zoomPreset: 'hour-day'` starts the visible timeline with one column per hour.
- `snap.unit: 'hour'` forces task create, move, and resize snapping to hours even if the active zoom level changes later.
- `snap.workingTime` controls whether snapping can use working-time rules. Closed weekdays, holidays, and closed hours are skipped only when `scheduling.excludeHolidaysFromDuration` is also `true`.

```typescript
grid.gantt = {
  // ...required project fields
  timelinePrecision: 'hour',
  zoomPreset: 'hour-day',
  snap: {
    unit: 'hour',
    workingTime: true,
  },
  scheduling: {
    excludeHolidaysFromDuration: true,
  },
  calendars: [
    {
      id: 'standard',
      name: 'Standard',
      workingDays: [1, 2, 3, 4, 5],
      workingHours: [{ start: '09:00', end: '17:00' }],
      hoursPerDay: 8,
    },
  ],
  tasks: [
    {
      id: 'task-1',
      name: 'Same-day implementation',
      startDate: '2026-04-06T09:00:00.000Z',
      endDate: '2026-04-06T13:00:00.000Z',
    },
  ],
};
```

  `timelinePrecision` controls interaction precision. `zoomPreset` and `zoom.defaultLevelId`
  control the initial visible scale. Keep them aligned for an hour-first experience,
  or set `zoom.defaultLevelId: 'day-week'` if you want hour snapping while opening
  on a coarser planning view.

When `snap.workingTime` is `true` or omitted and
`scheduling.excludeHolidaysFromDuration` is `true`, hour snapping uses the
primary project calendar:

- A drag before `09:00` snaps forward to `09:00`.
- A drag after `17:00` snaps forward to the next working opening.
- Weekend or holiday drags snap to the next or previous working opening depending on the interaction direction.

Set `snap.workingTime: false` when users should be able to place tasks in
non-working hours while still snapping to the start of each hour.

If `scheduling.excludeHolidaysFromDuration` is `false` or omitted, hour
snapping rounds to the start of the hour and does not move drags out of
non-working time.

## Full Zoom Configuration

Use `zoom` when you need custom levels, min/max bounds, locale, or wheel interaction rules.

```typescript
grid.gantt = {
  // ...required project fields
  zoomPreset: 'week-month',
  zoom: {
    enabled: true,
    defaultLevelId: 'hour-day',
    minLevelId: 'minute-hour',
    maxLevelId: 'quarter-year',
    locale: 'en-US',
    zoomAnchorMode: 'pointer',
    wheelZoomEnabled: true,
    wheelZoomTrigger: 'ctrlKey',
    wheelZoomMode: 'discrete',
    invertWheelDirection: false,
  },
};
```

  If both `zoomPreset` and `zoom.defaultLevelId` are provided, the resolved zoom config uses the `zoom` values where specified.

## Custom Zoom Levels

You can define your own `zoom.levels` list from finest to coarsest.

```typescript
grid.gantt = {
  // ...required project fields
  zoom: {
    levels: [
      {
        id: 'minute-hour',
        label: '15 Min / Hour',
        tickUnit: 'minute',
        tickCount: 15,
        tickWidth: 44,
        headerRows: [
          { id: 'day', unit: 'day' },
          { id: 'hour', unit: 'hour' },
          { id: 'minute', unit: 'minute', count: 15 },
        ],
      },
      {
        id: 'hour-day',
        label: 'Hour / Day',
        tickUnit: 'hour',
        tickWidth: 52,
        headerRows: [
          { id: 'day', unit: 'day' },
          { id: 'hour', unit: 'hour' },
        ],
      },
      {
        id: 'day-week',
        label: 'Day / Week',
        tickUnit: 'day',
        tickWidth: 56,
        headerRows: [
          { id: 'week', unit: 'week' },
          { id: 'day', unit: 'day' },
        ],
      },
      {
        id: 'week-month',
        label: 'Week / Month',
        tickUnit: 'week',
        tickWidth: 84,
        headerRows: [
          { id: 'month', unit: 'month' },
          { id: 'week', unit: 'week' },
        ],
      },
      {
        id: 'month-quarter',
        label: 'Month / Quarter',
        tickUnit: 'month',
        tickWidth: 120,
        headerRows: [
          { id: 'year', unit: 'year' },
          { id: 'month', unit: 'month' },
        ],
      },
    ],
    defaultLevelId: 'hour-day',
  },
};
```

## Wheel Zoom Options

Control whether users can zoom with the mouse wheel and which modifier key is required.

```typescript
grid.gantt = {
  // ...required project fields
  zoom: {
    wheelZoomEnabled: true,
    wheelZoomTrigger: 'metaKey', // macOS Cmd key
    wheelZoomMode: 'smooth-discrete',
    invertWheelDirection: false,
  },
};
```

Available `wheelZoomTrigger` values:

- `'ctrlKey'`
- `'metaKey'`
- `'altKey'`
- `'shiftKey'`
- `'none'`

## Anchor Behavior During Zoom

`zoomAnchorMode` controls which point in the viewport stays stable when switching levels:

- `'pointer'`: keeps the date under the mouse pointer fixed.
- `'center'`: keeps the center date fixed.
- `'start'`: keeps the left edge date fixed.

```typescript
grid.gantt = {
  // ...required project fields
  zoom: {
    zoomAnchorMode: 'center',
  },
};
```

## Timeline Overlays

Timeline visuals are configured in `visuals`.

```typescript
grid.gantt = {
  // ...required project fields
  visuals: {
    projectLineDate: '2026-04-06',
    timeRanges: [
      {
        id: 'sprint-1',
        startDate: '2026-04-06',
        endDate: '2026-04-17',
        label: 'Sprint 1',
        color: '#5B8DEF',
      },
      {
        id: 'freeze',
        startDate: '2026-05-18',
        endDate: '2026-05-22',
        label: 'Code Freeze',
        color: '#F59E0B',
      },
    ],
    shadeNonWorkingTime: true,
  },
};
```

  `shadeNonWorkingTime` is accepted in both `zoom` and `visuals`. If both are set, zoom-level setting takes priority.

## Plugin Header Contributions

`GanttTimelineHeaderPlugin` owns the custom RevoGrid header template used by
the Gantt column. Other runtime plugins can discover it and append elements to
the resolved timeline header without creating another render root:

```typescript
import { GanttTimelineHeaderPlugin } from '@revolist/gantt';

// Inside another grid plugin, use its PluginProviders instance.
const timelineHeader = providers.plugins.getByClass(GanttTimelineHeaderPlugin);

const unregisterReleaseMarker = timelineHeader?.registerElement(
  'release-marker',
  (h) => h('div', {
    class: { 'my-release-marker': true },
    style: { left: '420px' },
  }, 'Release'),
);

// Call after closure-backed contribution state changes.
timelineHeader?.refresh();

// Call from the contributing plugin's teardown.
unregisterReleaseMarker?.();
```

Contribution renderers receive RevoGrid's native `HyperFunc` and the
immutable, resolved header geometry. They render after the built-in header
cells, non-working ranges, interaction range, and flag caps, in registration
order. The contributing plugin owns its data and styling; timeline scale,
viewport slicing, and scroll state remain owned by Gantt.

  Use `renderGanttTimelineHeader` directly only when building a custom RevoGrid
  column template. Normal Gantt integrations should configure `zoom` and use the
  discoverable header plugin only for cross-plugin UI contributions.

---

# Visual Configuration

URL: https://pro.rv-grid.com/guides/gantt/customization/visuals/
Source: src/content/docs/guides/gantt/customization/visuals.mdx
Description: Timeline overlays, labels, baseline, critical path, and marker hooks.
Surface: gantt

`gantt.visuals` controls overlays and rendering hooks:

- `percentDoneMode` selects the project-wide `number`, `bar` (default), or `circle` rendering for the managed `% Done` task-table column using the shared Pro progress renderers. An authored `{ prop: 'percentDone', mode: '...' }` column overrides it.

- `showBaseline`, `baselineId`
- `showCriticalPath`
- `showTaskLabels`
- `projectLineDate`, `showTodayLine`, `milestoneLines`
- `timeRanges`, `shadeNonWorkingTime`
- `taskMarkerHook`, `taskBarColorHook`, `taskBarContentHook`
- `taskTooltipFields`, `taskTooltipHook`

Use `taskTooltipFields` when you only need to choose which built-in fields appear in task-bar tooltips:

```ts
grid.gantt = {
  ...project,
  visuals: {
    taskTooltipFields: [
      'name',
      'startDate',
      'endDate',
      { field: 'percentDone', label: 'Complete' },
      'assignees',
    ],
  },
};
```

## Task tooltip API

`taskTooltipFields` is an ordered array. Each entry can be a field id string or an object with a `field` and optional `label`:

```ts
type GanttTaskTooltipField =
  | GanttTaskTooltipFieldId
  | { field: GanttTaskTooltipFieldId; label?: string };
```

Object entries let you rename a built-in line. Set `label: ''` to render only the value without a `Label: ` prefix.

```ts
visuals: {
  taskTooltipFields: [
    { field: 'name', label: '' },
    { field: 'percentDone', label: 'Done' },
  ],
}
```

Supported built-in fields:

| Field | Tooltip output |
|---|---|
| `summary` | Task name and completion percent, for example `Design - 50%`. |
| `name` | Task name. |
| `percentDone` | Completion percent. |
| `taskType` | Human-readable task type. |
| `status` | Human-readable task status. |
| `startDate` | Scheduled start date, formatted with `gantt.dateFormats.tooltip`. |
| `endDate` | Scheduled end date, formatted with `gantt.dateFormats.tooltip`. |
| `duration` | Formatted task duration in its retained or project-selected unit. |
| `taskMode` | `Auto Scheduled` or `Manually Scheduled`. |
| `schedulingWarnings` | Scheduling warnings joined into one line; skipped when empty. |
| `cost` | Formatted task cost; skipped when empty. |
| `assignees` | Comma-separated assignee names; skipped when empty. |

When `taskTooltipFields` is omitted, Gantt keeps the default tooltip: `summary`, `taskType`, `status`, `startDate`, `endDate`, `duration`, `taskMode`, `schedulingWarnings`, `cost`, and `assignees`. An empty array intentionally renders an empty tooltip.

`taskTooltipHook` has priority over `taskTooltipFields` and can replace the whole tooltip string:

```ts
visuals: {
  taskTooltipFields: ['name'],
  taskTooltipHook: ({ row }) => `${row.name}\n${row.status}`,
}
```

Return `null` or `undefined` from `taskTooltipHook` to fall back to `taskTooltipFields` or the default tooltip. Use the hook for custom row metadata that is not part of the built-in field list.

Type source: `packages/gantt/src/gantt/grid/gantt-plugin.types.ts`.
Rendering sources: `features/timeline-background/*`, `grid/gantt-column-type.ts`.

---

# Gantt Examples

URL: https://pro.rv-grid.com/guides/gantt/examples/
Source: src/content/docs/guides/gantt/examples/index.mdx
Description: Search every runnable RevoGrid Gantt demo by framework and planning topic, then open its preview, source, guide, and API reference.
Surface: gantt

The example browser reads the shared demo catalog directly. Every registered Gantt demo and framework variant appears here automatically; there is no separate manual inventory to maintain.

---

# Application State And Persistence

URL: https://pro.rv-grid.com/guides/gantt/features/application-state/
Source: src/content/docs/guides/gantt/features/application-state.mdx
Description: Keep Gantt project collections synchronized with framework state, APIs, databases, and real-time application updates.
Surface: gantt

Your application owns persisted project data. Gantt owns scheduling, validation, projection, and supported local mutations while the grid is mounted.

## State Boundary

Keep these collections together as one logical project snapshot:

- `source`: authored task rows.
- `ganttDependencies`.
- `ganttCalendars`.
- `ganttResources`.
- `ganttAssignments`.
- `ganttBaselines`.
- `gantt`: project metadata and behavior configuration.

When a server response or collaborative update arrives, replace affected arrays and assign a new `gantt` object when configuration changed. Do not mutate an existing array in place and expect framework or custom-element change detection to observe it.

```ts
function applyProject(snapshot: ProjectSnapshot) {
  grid.gantt = { ...snapshot };
  grid.ganttCalendars = [...snapshot.calendars];
  grid.ganttDependencies = [...snapshot.dependencies];
  grid.ganttResources = [...snapshot.resources];
  grid.ganttAssignments = [...snapshot.assignments];
  grid.ganttBaselines = [...snapshot.baselines];
  grid.source = snapshot.tasks.map(toSourceRow);
}
```

## Save Flow

1. Listen for the Gantt before-change events when the application needs authorization or validation.
2. Allow Gantt to commit supported local mutations.
3. Read the current project through the `GanttPlugin` instance or the application state updated by your integration.
4. Persist a complete snapshot or an application-defined patch.
5. Replace the public collections with the canonical server result when the server normalizes data.

Use [JSON project helpers](/guides/gantt/features/json-project-import-export/) for snapshots and [integration recipes](/guides/gantt/features/integrations-and-frameworks/) for REST, GraphQL, PostgreSQL, and Supabase-style persistence.

## Concurrent Updates

- Use stable entity IDs across every collection.
- Version project writes in your backend and reject stale updates.
- Re-run scheduling after dependency, calendar, task, resource, or assignment updates.
- Keep optimistic rollback data outside the rendered DOM.
- Use `gantt.readOnly` while a project is locked or awaiting approval.

See [Events And Methods](/guides/gantt/reference/events-methods/) for cancelable events and plugin access.

---

# Gantt Context Menu

URL: https://pro.rv-grid.com/guides/gantt/features/context-menu/
Source: src/content/docs/guides/gantt/features/context-menu.mdx
Description: Use the built-in Gantt row, column, and timeline context menus and extend them with RevoGrid Pro menu items.
Surface: gantt

Gantt contributes task and timeline actions through the RevoGrid Pro `DataGridContextMenuPlugin`; it does not replace your `rowContextMenu`, `columnContextMenu`, or `dataGridContextMenu` configuration. Gantt-compatible shared grid commands are composed first, then `dataGridContextMenu.getItems` and application items can extend the result.

The integration is enabled by default for every `GanttPlugin` instance. Set `gantt.contextMenu` to `false` to opt out of generated Gantt row, column, and timeline menu items while leaving application-provided RevoGrid context menu configuration untouched:

```ts
grid.gantt = {
  ...project,
  contextMenu: false,
};
```

You can also disable one generated surface at a time:

```ts
grid.gantt = {
  ...project,
  contextMenu: {
    row: false,
    column: true,
  },
};
```

## Row Menu

Right-click a task-table row or task bar to open task actions:

- `Add`
- `Convert to milestone`
- `Indent`
- `Outdent`
- `Delete`

The default actions dispatch Gantt events:

```ts
grid.addEventListener('gantt-task-create', (event) => {
  const { parentId, insertAfterTaskId } = event.detail ?? {};
});

grid.addEventListener('gantt-task-indent', (event) => {
  indentTask(event.detail?.taskId);
});

grid.addEventListener('gantt-task-outdent', (event) => {
  outdentTask(event.detail?.taskId);
});

grid.addEventListener('gantt-task-delete', (event) => {
  deleteTask(event.detail?.taskId);
});
```

`Add` uses the focused row or clicked task bar as the insertion anchor. When the anchor has descendants, Gantt inserts the new sibling after the full descendant block so the task tree stays valid. Context-menu creation names the row `New task 1`, `New task 2`, and so on, and does not open the task editor.

The generated row menu is suppressed on the pinned add-task draft row because that row is owned by the internal `GanttAddTaskRowPlugin` and is not a task entity. If you disable Gantt context-menu integration and provide your own `rowContextMenu`, use `isGanttAddTaskRow()` or the draft cell marker to skip that row. See [Add Task Row](/guides/gantt/interaction/add-task-row/).

### Confirming Delete

The built-in **Delete** item dispatches the normal Gantt delete command, then Gantt emits the cancelable `gantt-before-task-change` event with `detail.action === 'delete'` immediately before it mutates any task. Call `preventDefault()` to keep the task (and its descendants) unchanged.

```ts
grid.addEventListener('gantt-before-task-change', (event) => {
  if (event.detail.action !== 'delete') return;

  const name = event.detail.previousValues.name ?? 'this task';
  if (!window.confirm(`Delete ${name}?`)) {
    event.preventDefault();
  }
});
```

This protects deletion initiated from the default context-menu item and direct Gantt delete methods, so it is the preferred place for permission checks and a synchronous browser confirmation. It is called once per affected task; applications that allow bulk deletion should make their confirmation copy clear that descendants may also be removed.

`gantt-before-task-change` is synchronous. For an asynchronous application modal, prevent the original deletion, keep the selected task ids in application state, and call `gantt.deleteTasks(taskIds)` only after the user confirms. Guard the follow-up call so the same listener does not reopen the dialog, and recheck permissions before performing it.

## Column Menu

Right-click main grid headers to open column actions:

- `Sort ascending`
- `Sort descending`
- `Filter`
- `Hide column`
- `Columns`

Visibility follows the active column:

- Sort actions appear only when the target column has `sortable: true`.
- Filter appears only when the target column has `filter` configured.
- Hide column is available for a leaf task-table column; Columns opens the standard column-management dialog.
- If contextual filtering leaves no visible items, the menu is not opened.

Sort, filtering, hiding, and column management reuse the shared RevoGrid data-grid context-menu commands. Gantt removes incompatible generic commands such as row mutation, formatting, pinning, and schema operations.

## Timeline Menu

Right-click the pinned Gantt timeline/canvas header to open timeline actions:

- `Zoom`
- `Date range`
- `Show today`
- `Show flags` when milestone lines are configured

Zoom controls are hidden when the current zoom level cannot move further in either direction. Date range changes the visible timeline range; the visual toggles remain open after changing their checked state.

## Read-Only And Locked State

The row menu respects packaged Gantt protection state:

- `gantt.readOnly: true` hides mutating row actions.
- Selected locked tasks hide hierarchy actions.
- Mutation services still guard direct calls, so blocked task operations return `readonly-task`.

## Extending The Menu

Use the normal RevoGrid Pro menu config surfaces. Gantt keeps your custom items and contributes its generated items without mutating those configurations.

```ts
grid.rowContextMenu = {
  items: [
    {
      name: 'Open task details',
      action: (_event, focused, _range, _close, context) => {
        const task = context?.providers.data.getModel?.(focused?.y ?? 0, 'rgRow');
        openTaskDetails(task?.id);
      },
    },
  ],
};
```

## Customization

Gantt context menu customization has two layers:

- `gantt.contextMenu` controls the generated Gantt row, column, and timeline actions.
- `rowContextMenu` and `columnContextMenu` hold application menu config that should remain in the grid even when generated Gantt actions are disabled.

Use `gantt.contextMenu = false` when the application should fully own the menu:

```ts
grid.rowContextMenu = {
  items: [
    {
      name: 'Open planning panel',
      action: (_event, focused, _range, close, context) => {
        const task = context?.providers.data.getModel?.(focused?.y ?? 0, 'rgRow');
        openPlanningPanel(task?.id);
        close();
      },
    },
  ],
};

grid.gantt = {
  ...project,
  contextMenu: false,
};
```

Use partial opt-out when you want custom row actions but still want generated column and timeline actions:

```ts
grid.rowContextMenu = {
  items: [
    {
      name: 'Assign owner',
      action: (_event, focused, _range, close, context) => {
        const task = context?.providers.data.getModel?.(focused?.y ?? 0, 'rgRow');
        openOwnerPicker(task?.id);
        close();
      },
    },
  ],
};

grid.gantt = {
  ...project,
  contextMenu: {
    row: false,
    column: true,
  },
};
```

Keep `gantt.contextMenu` enabled when you want to append app actions after the default Gantt actions:

```ts
grid.rowContextMenu = {
  items: [
    {
      name: 'Show audit log',
      action: (_event, focused, _range, close, context) => {
        const task = context?.providers.data.getModel?.(focused?.y ?? 0, 'rgRow');
        showTaskAuditLog(task?.id);
        close();
      },
    },
  ],
};

grid.gantt = project;
```

You can also use a `resolve` function on the base RevoGrid menu config. Gantt preserves the resolver and the context menu plugin applies it to the composed menu:

```ts
grid.rowContextMenu = {
  items: [
    { name: 'Open task details', action: openTaskDetailsFromMenu },
  ],
  resolve(context) {
    return context.target === 'row' ? undefined : null;
  },
};
```

The packaged task editor item is controlled separately:

```ts
grid.ganttTaskEditorDialog = {
  contextMenu: false,
};
```

Set `ganttTaskEditorDialog.contextMenu` to `true` when `gantt.contextMenu` is disabled but the application still wants the default **Edit...** item. Leave it unset to follow `gantt.contextMenu`.

For packaged extension items, use the built-in Gantt context-menu helpers:

```ts
import { createGanttContextMenuExtensionItems } from '@revolist/gantt';

const customItems = createGanttContextMenuExtensionItems({
  duplicate: {
    copyName: (task) => `${task.name ?? 'Task'} copy`,
  },
  assignResource: {
    onAssignResource: (context) => {
      if (context.taskId) {
        openResourcePicker(context.taskId);
      }
    },
  },
  delete: false,
  export: { name: 'Export task rows' },
});

grid.rowContextMenu = {
  ...grid.rowContextMenu,
  items: [...(grid.rowContextMenu?.items ?? []), ...customItems],
};
```

## Legacy Context Menu

`rowContextMenu` and `columnContextMenu` remain application-owned low-level menu configuration. Use `dataGridContextMenu.getItems` when you need to transform the Gantt-compatible shared grid commands: registered Gantt contributions run first, then this application resolver receives the filtered items.

Gantt registers and disposes its own contribution with the plugin lifecycle. It does not rewrite host menu properties, so application-provided items are not duplicated during Gantt configuration updates.

The packaged task editor follows `gantt.contextMenu` by default for its **Edit...** row-menu item. Set `ganttTaskEditorDialog.contextMenu` to `false` to disable only the editor item, or `true` to keep the editor item when generated Gantt menus are disabled.

---

# Editing, Validation, Diagnostics

URL: https://pro.rv-grid.com/guides/gantt/features/editing-validation-diagnostics/
Source: src/content/docs/guides/gantt/features/editing-validation-diagnostics.mdx
Description: Wire Gantt permission checks, editor forms, popovers, validation, and diagnostics panels.
Surface: gantt

These APIs are presentation-free. They make decisions and shape data, while your application owns forms, popovers, panels, toasts, and persistence.

```ts
import {
  GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT,
  GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT,
  GANTT_BEFORE_TASK_CHANGE_EVENT,
  TASK_EDITOR_FIELD_SCHEMA,
  buildDependencyValidationSummary,
  buildResourceOverallocationSummary,
  createApprovalGateValidator,
  createForbiddenDateRangeValidator,
  createGanttBeforeTaskChangeValidationHandler,
  createGanttRoleEditabilityHelpers,
  createLockedPhaseValidator,
  createRoleGuardValidator,
  createTaskDetailPopoverModel,
  createTaskEditorFormValues,
  normalizeTaskEditorSubmit,
} from '@revolist/gantt';
```

## Role-Based Editability

Before-change events are cancelable. Use role helpers to decide whether a task, dependency, or assignment mutation should proceed. Call `event.preventDefault()` to stop the packaged mutation before the Gantt store changes; timeline previews are cleared and the next render keeps the previous task, dependency, or assignment data.

```ts
const policy = {
  roles: {
    viewer: [],
    planner: ['task:*', 'dependency:create', 'dependency:delete'],
    staffing: ['assignment:edit'],
    admin: ['*'],
  },
  fallback: 'deny',
} as const;

const editability = createGanttRoleEditabilityHelpers(policy);
const getRoleContext = () => ({ roles: currentUser.roles });

grid.addEventListener(GANTT_BEFORE_TASK_CHANGE_EVENT, (event) => {
  if (!editability.canEditTask(event.detail, getRoleContext())) {
    event.preventDefault();
  }
});

grid.addEventListener(GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT, (event) => {
  if (!editability.canEditDependency(event.detail, getRoleContext())) {
    event.preventDefault();
  }
});

grid.addEventListener(GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT, (event) => {
  if (!editability.canEditAssignment(event.detail, getRoleContext())) {
    event.preventDefault();
  }
});
```

Task before-change actions cover `move`, `resize`, `create`, `edit`, `progress`, `split`, `indent`, `outdent`, and `delete`. Dependency before-change actions cover `create`, `delete`, `edit`, and `replace`; `replace` is emitted by predecessor/successor inline field edits and includes `previousDependencies` plus proposed `dependencies` because one cell edit can add, update, and remove multiple links. Assignment edits emit proposed `assignments` and `previousAssignments`.

For task edits, `event.detail.sourcePatch` contains the flat source-row fields that the packaged Gantt store will write. Use it when persisting custom row fields or when your backend uses public source names such as `duration`, `percentDone`, and `taskMode`.

```ts
grid.addEventListener(GANTT_BEFORE_TASK_CHANGE_EVENT, (event) => {
  const { sourceIndex, sourcePatch, previousSourceValues } = event.detail;

  if (sourceIndex === undefined || !sourcePatch) {
    return;
  }

  queueTaskRowPersistence({
    rowIndex: sourceIndex,
    patch: sourcePatch,
    previousValues: previousSourceValues ?? {},
  });
});
```

## Custom Task Editor Forms

Use the field schema and initial value builder to render a framework form, then normalize submitted values into a `TaskUpdate` patch.

For a complete standalone UI example, see [Task Editing](../../interaction/task-editing/).

```ts
const fields = TASK_EDITOR_FIELD_SCHEMA.filter((field) =>
  ['name', 'startDate', 'endDate', 'progressPercent', 'resourceLabels'].includes(field.id),
);

const values = createTaskEditorFormValues(task, resources, assignments);

renderTaskEditor({
  fields,
  values,
  onSubmit(nextValues) {
    const result = normalizeTaskEditorSubmit(task, nextValues);

    if (!result.ok) {
      renderErrors(result.errors);
      return;
    }

    updateTask(task.id, result.patch);
  },
});
```

## Task Detail Popovers

`createTaskDetailPopoverModel()` returns sections, fields, warnings, and resource labels. Your app handles hover/focus, positioning, and rendering.

```ts
const model = createTaskDetailPopoverModel({
  row,
  task,
  resources,
  assignments,
});

renderPopover({
  title: model.title,
  subtitle: model.subtitle,
  sections: model.sections,
  resources: model.resourceAssignments.map((assignment) => assignment.displayValue),
});
```

## Dependency Diagnostics

Use dependency summaries to power badges, side panels, or task focus commands.

```ts
const summary = buildDependencyValidationSummary({
  conflicts: schedulerResult.conflicts,
  issues: schedulerResult.issues,
  rows: projectedRows,
});

renderDiagnosticsPanel({
  count: summary.totalCount,
  groups: summary.groups,
});
```

## Resource Over-Allocation Diagnostics

Use resource summaries when staffing dashboards need to show who is overloaded and when.

```ts
const overloads = buildResourceOverallocationSummary({
  rows: resourcePlanningRows,
  loadSummaries: resourceLoadSummaries,
  conflicts: schedulerResult.conflicts,
});

renderResourceHealth({
  count: overloads.totalCount,
  peakOverloadUnits: overloads.peakOverloadUnits,
  groups: overloads.groups,
});
```

## Custom Validation Recipes

Compose validators and attach the generated handler to `gantt-before-task-change`.

```ts
const validators = [
  createRoleGuardValidator({ policy }),
  createForbiddenDateRangeValidator({
    ranges: [{ startDate: '2026-05-20', endDate: '2026-05-27', label: 'release freeze' }],
  }),
  createLockedPhaseValidator({
    lockedPhaseIds: ['closed'],
    getPhaseId: (detail) => detail.taskId ? phaseByTaskId[detail.taskId] : null,
  }),
  createApprovalGateValidator({
    actions: ['move', 'resize', 'progress'],
    requiresApproval: (detail) => detail.changes.progressPercent === 100,
  }),
];

grid.addEventListener(
  GANTT_BEFORE_TASK_CHANGE_EVENT,
  createGanttBeforeTaskChangeValidationHandler({
    context: () => validationContext,
    validators,
    onReject: ({ decision }) => showValidationToast(decision.message ?? 'Change rejected'),
  }),
);
```

---

# Grid, Export, Rendering

URL: https://pro.rv-grid.com/guides/gantt/features/grid-export-rendering/
Source: src/content/docs/guides/gantt/features/grid-export-rendering.mdx
Description: Use Gantt row export mapping, column presets, status indicators, and context-menu extension recipes.
Surface: gantt

These helpers package common grid-side Gantt work without coupling your application to internal timeline layout data.

```ts
import {
  createGanttColumnPreset,
  createGanttContextMenuExtensionItems,
  createGanttExcelExportRecipe,
  createGanttPdfExcelReportingRecipe,
  createGanttTaskStatusIndicatorRecipe,
  createTaskStatusIndicators,
  mapGanttRowsToExcelExport,
} from '@revolist/gantt';
```

## Gantt Excel Export Mapping

Use `mapGanttRowsToExcelExport()` when exporting projected task rows. The mapper uses an allowlist of user-facing fields and skips renderer-only timeline metadata.

```ts
const rows = mapGanttRowsToExcelExport(taskRows, project, {
  includeResourceRows: false,
});

downloadWorkbook({
  sheetName: project.name,
  rows,
});
```

For shells that prefer a recipe object:

```ts
const recipe = createGanttExcelExportRecipe({
  rows: taskRows,
  project,
});

downloadWorkbook({
  fields: recipe.fieldNames,
  rows: recipe.rows,
});
```

## PDF And Excel Reporting

Use the combined reporting recipe when your app has separate toolbar buttons for stakeholder PDF reports and spreadsheet handoff. PDF uses the browser print dialog, so users can choose **Save as PDF**. Excel dispatches the Pro `export-excel` event, so include `ExportExcelPlugin` with the grid plugins.

```ts
import {
  GanttPlugin,
  createGanttPdfExcelReportingRecipe,
} from '@revolist/gantt';
import { ExportExcelPlugin } from '@revolist/revogrid-pro';

const grid = document.querySelector<HTMLRevoGridElement>('revo-grid');
const host = document.querySelector<HTMLElement>('#gantt-report');

if (!grid || !host) {
  throw new Error('Gantt report target was not found');
}

grid.plugins = [GanttPlugin, ExportExcelPlugin];
grid.gantt = project;

const reportRange = {
  startDate: '2026-05-01',
  endDate: '2026-05-31',
};

const reporting = createGanttPdfExcelReportingRecipe({
  grid,
  target: host,
  document,
  window,
  excel: {
    workbookName: `${project.name}.xlsx`,
  },
});

pdfButton.addEventListener('click', () => {
  const result = reporting.exportPdf(project, reportRange);

  if (!result.ok) {
    showExportError(result.reason);
  }
});

excelButton.addEventListener('click', () => {
  reporting.exportExcel({
    sheetName: 'Tasks',
  });
});
```

For a single "export report" action, call both commands together:

```ts
const result = reporting.exportReport(project, {
  range: { label: 'Executive status report' },
  excel: { sheetName: 'Task register' },
});

if (!result.pdf.ok) {
  showExportError(result.pdf.reason);
}
```

## Column Presets

Column presets group the default Gantt task-table columns into common planning views.

```ts
grid.columns = createGanttColumnPreset('schedule');
grid.source = [...taskRows];
```

Available presets include `core`, `schedule`, `dependencies`, `resources`, `baseline`, `cost`, `progress`, and `all`.

## Read-Only And Locked Indicators

Use indicator helpers to produce labels and class names for custom cell renderers.

```ts
const status = createTaskStatusIndicators({
  taskId: row.id,
  projectReadOnly,
  taskLocked: lockedTaskIds.has(row.id),
});

renderIndicatorCell({
  className: status.classNames.join(' '),
  title: status.label,
  indicators: status.indicators,
});
```

For multiple rows:

```ts
const indicatorRows = createGanttTaskStatusIndicatorRecipe({
  rows: taskRows,
  projectReadOnly,
  lockedTaskIds,
});
```

## Context Menu Extensions

Gantt installs separate RevoGrid Pro row and column context menus. Row menus are task-oriented (`Add`, `Convert to milestone`, `Indent`, `Outdent`, `Delete`). Main grid column menus expose search, sort, and filter actions. The pinned Gantt canvas column menu exposes timeline zoom controls.

Use the built-in context-menu helpers with `rowContextMenu` to add duplicate, assign-resource, export, or custom task actions.

```ts
const contextMenuItems = createGanttContextMenuExtensionItems({
  duplicate: {
    copyName: (task) => `${task.name ?? 'Task'} copy`,
  },
  delete: {
    confirm: (context) => window.confirm(`Delete ${context.task?.name ?? 'task'}?`),
    onDeleteTask: (context) => {
      if (context.taskId) {
        deleteTask(context.taskId);
      }
    },
  },
  assignResource: {
    onAssignResource: (context) => {
      if (context.taskId) {
        openResourcePicker(context.taskId);
      }
    },
  },
  export: {
    exportOptions: (context) => ({
      workbookName: 'gantt.xlsx',
      sheetName: context.task?.name ?? 'Gantt',
    }),
  },
});

grid.rowContextMenu = {
  ...grid.rowContextMenu,
  items: [...(grid.rowContextMenu?.items ?? []), ...contextMenuItems],
};
```

Disable individual items with `false`.

```ts
const exportOnly = createGanttContextMenuExtensionItems({
  duplicate: false,
  delete: false,
  assignResource: false,
  export: { name: 'Export visible Gantt tasks' },
});
```

---

# Integrations And Frameworks

URL: https://pro.rv-grid.com/guides/gantt/features/integrations-and-frameworks/
Source: src/content/docs/guides/gantt/features/integrations-and-frameworks.mdx
Description: Persist, import, export, print, and embed Gantt projects with framework-neutral recipes.
Surface: gantt

These recipes keep transport and framework ownership in your application. Inject `fetch`, state, database clients, DOM targets, and file readers/writers from your host app.

```ts
import {
  ProjectSnapshotGraphqlAdapter,
  ProjectSnapshotRestAdapter,
  ProjectSnapshotSupabaseAdapter,
  buildCreateProjectSnapshotTableSql,
  buildLoadProjectSnapshotSql,
  buildSaveProjectSnapshotSql,
  cloneProjectSnapshot,
  createJsonSnapshotRecipe,
  createPrintPdfExportRecipe,
  exportProjectSnapshot,
  parseProjectSnapshotJson,
  printGanttContainer,
} from '@revolist/gantt';
```

## JSON Snapshot Helpers

Use JSON helpers for local import/export, file handoff, tests, undo buffers, or backend payloads.

```ts
const draft = cloneProjectSnapshot(project);
const json = exportProjectSnapshot(draft, { space: 2 });
const parsed = parseProjectSnapshotJson(json);

if (parsed.ok) {
  applyProject(parsed.project);
}
```

For file picker flows:

```ts
const recipe = createJsonSnapshotRecipe({
  readText: () => fileInputText,
  writeText: (_fileName, contents) => saveTextFile(contents),
});

await recipe.save(project, 2);
const imported = await recipe.load();
```

## REST Persistence

`ProjectSnapshotRestAdapter` loads and saves serialized project snapshots through an injected `fetchImpl`.

```ts
const adapter = new ProjectSnapshotRestAdapter({
  url: '/api/gantt/project/demo',
  headers: { authorization: 'Bearer token' },
  fetchImpl,
  space: 2,
});

const project = await adapter.load();
await adapter.save(project);
```

## GraphQL Persistence

Use the GraphQL adapter when the backend exposes project snapshots through operations.

```ts
const adapter = new ProjectSnapshotGraphqlAdapter({
  url: '/graphql',
  fetchImpl,
  loadQuery: 'query LoadProject($id: ID!) { projectSnapshot(id: $id) }',
  saveMutation: 'mutation SaveProject($id: ID!, $snapshot: String!) { saveProjectSnapshot(id: $id, snapshot: $snapshot) }',
});

const project = await adapter.load({ variables: { id: 'demo' } });
await adapter.save(project, { variables: { id: 'demo' } });
```

## Supabase And PostgreSQL

Use SQL builders with any PostgreSQL executor, or the Supabase-like adapter with a compatible client shape.

```ts
await executor.query(buildCreateProjectSnapshotTableSql());
await executor.query(buildSaveProjectSnapshotSql(project));

const result = await executor.query(
  buildLoadProjectSnapshotSql(project.id),
);
```

```ts
const adapter = new ProjectSnapshotSupabaseAdapter(supabaseLikeClient);

await adapter.save(project);
const restored = await adapter.load(project.id);
```

## Print And Save As PDF

The print recipe prepares a Gantt container for browser printing. Users can choose Print or Save as PDF in the native dialog.

```ts
const result = printGanttContainer(host, {
  document,
  window,
  metadata: {
    title: project.name,
    subtitle: `${project.tasks.length} tasks`,
    range: { startDate: '2026-05-01', endDate: '2026-05-31' },
  },
});
```

For a reusable command:

```ts
const printRecipe = createPrintPdfExportRecipe({
  target: host,
  document,
  window,
});

printRecipe.exportProject(project, { label: 'May reporting window' });
```

## Framework Examples

Use the complete public-package workflow for your primary wrapper:

- [Vanilla TypeScript quick start](/guides/gantt/introduction/vanilla-typescript/)
- [React quick start](/guides/gantt/introduction/react/)
- [Vue 3 quick start](/guides/gantt/introduction/vue/)
- [Angular quick start](/guides/gantt/introduction/angular/)

Svelte remains a secondary integration recipe. Use the custom-element approach from the Vanilla guide until its packaged wrapper and support contract match the four primary framework paths.

The [Resource Planning demo](https://demo.rv-grid.com/gantt-resource-planning/ts) shows a host-owned resource filter UI. Filtering updates `grid.gantt.resourceFilterIds` without reading rendered cells.

Resource filtering updates `grid.gantt.resourceFilterIds`:

```ts
grid.gantt = {
  ...project,
  resourceFilterIds: selectedResourceIds.length === allResourceIds.length
    ? undefined
    : selectedResourceIds,
};
```

---

# JSON Project Import And Export

URL: https://pro.rv-grid.com/guides/gantt/features/json-project-import-export/
Source: src/content/docs/guides/gantt/features/json-project-import-export.mdx
Description: Serialize, clone, parse, and lightly validate complete Gantt project snapshots.
Surface: gantt

JSON project import/export provides a framework-neutral way to move complete Gantt project snapshots between files, APIs, tests, undo buffers, and server-side workflows. The helpers operate on `ProjectSnapshot` data only. They do not depend on the grid, DOM, or framework wrappers.

Import the helpers from `@revolist/gantt`:

```ts
import {
  cloneProjectSnapshot,
  createJsonSnapshotRecipe,
  exportProjectSnapshot,
  parseProjectSnapshotJson,
} from '@revolist/gantt';
```

## Export A Snapshot

Use `exportProjectSnapshot()` to serialize the current project snapshot.

```ts
const json = exportProjectSnapshot(project, { space: 2 });
```

The optional `space` value is passed to `JSON.stringify`, so you can use it for readable file exports.

## Import A Snapshot

Use `parseProjectSnapshotJson()` to parse JSON into a typed result instead of throwing for common invalid payloads.

```ts
const parsed = parseProjectSnapshotJson(json);

if (!parsed.ok) {
  showImportError(parsed.error);
  return;
}

applyProject(parsed.project);
```

The parser checks the top-level project shape:

- Required string fields: `id`, `name`, `version`, `currency`, `timeZone`, `primaryCalendarId`, and `updatedAt`.
- Required array fields: `tasks`, `dependencies`, `resources`, `assignments`, `calendars`, and `baselines`.

It intentionally performs lightweight validation. Run scheduler validation or your application-specific validation after import when you need deeper checks for dates, task references, dependency cycles, resource assignments, or business rules.

## Clone Before Editing

Use `cloneProjectSnapshot()` when you need a JSON-safe deep copy before staging edits.

```ts
const draft = cloneProjectSnapshot(project);
draft.name = 'Scenario copy';
```

The clone is detached from nested task, dependency, resource, assignment, calendar, and baseline arrays.

## File Picker Recipe

For host applications that own file pickers and save dialogs, use `createJsonSnapshotRecipe()` with injected text readers and writers.

```ts
const recipe = createJsonSnapshotRecipe({
  readText: () => selectedFile.text(),
  writeText: (fileName, contents) => downloadTextFile(fileName, contents),
  fileName: (project) => `${project.id}-snapshot.json`,
});

const imported = await recipe.load();
await recipe.save(project, 2);
```

The recipe throws an `Error` when load/save hooks are missing or the imported JSON fails parsing. Use the lower-level parser directly when you prefer result objects over exceptions.

## What The JSON Contains

The exported JSON is the project snapshot, not rendered grid state. It includes project metadata and entity arrays:

- Tasks
- Dependencies
- Resources
- Assignments
- Calendars
- Baselines

It does not include projected Gantt row fields, rendered timeline geometry, current scroll position, expanded row state, active selection, filters, or toolbar state.

## Persistence Adapters

The REST, GraphQL, Supabase, and PostgreSQL examples build on the same JSON snapshot helpers. Use those adapters when the snapshot should be loaded from or saved to an application backend.

See [Integrations And Frameworks](../integrations-and-frameworks/) for adapter examples.

---

# Locked Tasks

URL: https://pro.rv-grid.com/guides/gantt/features/locked-tasks/
Source: src/content/docs/guides/gantt/features/locked-tasks.mdx
Description: Use task-level locking to block packaged Gantt task mutations for protected tasks.
Surface: gantt

Locked tasks let an application protect individual tasks after approval, baseline capture, phase closure, or any other workflow decision. A locked task remains visible in the task table and timeline, but packaged Gantt task mutations are rejected for that task.

Set `locked: true` on the flat task source row:

```ts
const tasks = [
  {
    id: 'design-signoff',
    parentId: null,
    name: 'Design sign-off',
    type: 'milestone',
    workflowStatus: 'done',
    startDate: '2026-04-15',
    endDate: '2026-04-15',
    duration: 1,
    percentDone: 100,
    calendarId: 'standard',
    tags: ['approved'],
    locked: true,
  },
];
```

## What It Blocks

`locked: true` blocks packaged task mutations for the locked task:

- Timeline task movement and resizing.
- Split creation, movement, and removal.
- Progress updates.
- Inline task-field edits routed through the Gantt task mutation service.
- Indent and outdent actions.
- Child task creation under a locked parent.
- Delete when the selected task subtree contains a locked task.

Blocked task mutations return `readonly-task` and leave task data unchanged.

## What Still Works

Locking a task does not remove it from scheduling, rendering, or inspection flows:

- The task still renders in the table and timeline.
- Scheduler recalculation can still read the task and include it in dependencies, critical path, baselines, and diagnostics.
- Search, filter, sort, expand/collapse, scroll, and zoom remain available.
- Non-locked tasks continue to edit normally.

## Boundaries

The source-row `locked` field is task-level protection, not a complete permission or checkout system.

Dependency changes are not globally disabled by locking a task. Assignment/resource edits are also handled by their own mutation service. Use `gantt.readOnly` when the whole project should reject packaged task, dependency, and assignment mutations.

For application-specific policy, pair locked tasks with cancelable Gantt events or validation recipes.

```ts
grid.addEventListener('gantt-before-task-change', (event) => {
  if (lockedTaskIds.has(event.detail.taskId)) {
    event.preventDefault();
  }
});
```

## Visual Indicators

Use the status indicator helpers when you want to show a lock label, class name, icon, or tooltip in a custom renderer.

```ts
const status = createTaskStatusIndicators({
  taskId: row.id,
  taskLocked: row.locked === true,
});

renderIndicatorCell({
  className: status.classNames.join(' '),
  title: status.label,
  indicators: status.indicators,
});
```

The helper returns metadata only, so the host application can choose the exact icon and placement.

## Context Menu

The built-in Gantt row context menu hides hierarchy actions when the selected task is locked. Mutating row actions are also guarded by the task mutation service, so direct calls still return `readonly-task`.

---

# Microsoft Project Import And Export

URL: https://pro.rv-grid.com/guides/gantt/features/microsoft-project/
Source: src/content/docs/guides/gantt/features/microsoft-project.mdx
Description: Import Microsoft Project XML or native MPP14 schedules, and export Microsoft Project XML with the optional Gantt converter.
Surface: gantt

Microsoft Project conversion is shipped as an optional package so applications that do not exchange Project files do not include the XML or native MPP parser.

```sh
pnpm add @revolist/revogrid-gantt-msp
```

## Install the plugin

Register `GanttMspImportPlugin` beside `GanttPlugin` from `@revolist/gantt`:

```ts
import { GanttPlugin } from '@revolist/gantt';
import { GanttMspImportPlugin } from '@revolist/revogrid-gantt-msp';

grid.plugins = [GanttPlugin, GanttMspImportPlugin];
```

Get the installed converter and import a file selected by the user:

```ts
const plugins = await grid.getPlugins();
const converter = plugins.find(
  (plugin): plugin is GanttMspImportPlugin =>
    plugin instanceof GanttMspImportPlugin,
);

const result = await converter?.importFile(file, {
  projectId: 'customer-rollout',
  currency: 'EUR',
  timeZone: 'Europe/Lisbon',
});

console.table(result?.warnings);
```

The plugin applies imported tasks and project collections through the same reactive properties used by `GanttPlugin`. It returns the complete `ProjectSnapshot` as well, allowing the application to persist or inspect the imported data.

## Convert without a grid

The framework-neutral conversion functions can be used in upload handlers, persistence services, tests, and export actions:

```ts
import {
  exportMicrosoftProjectXml,
  importMicrosoftProjectMpp,
  importMicrosoftProjectXml,
} from '@revolist/revogrid-gantt-msp';

const { project, warnings } = importMicrosoftProjectXml(xml, {
  projectId: 'customer-rollout',
});

const exported = exportMicrosoftProjectXml(project);
downloadXml(exported.xml);

const native = await importMicrosoftProjectMpp(await mppFile.arrayBuffer(), {
  projectId: 'native-customer-rollout',
});
```

## File support

| Format | Import | Export | Notes |
| --- | --- | --- | --- |
| Microsoft Project XML (`.xml`) | Yes | Yes | Full initial XML mapping. |
| MPP14 (`.mpp`) | Yes | No | Native format produced by Project 2010 and later. |
| MPP8, MPP9, or MPP12 | No | No | Returns `unsupported-mpp-version`. |
| Encrypted MPP | No | No | Returns `encrypted-mpp-not-supported`. |

`importFile()` detects the OLE compound-document signature rather than trusting the extension. Browser `File` objects already provide the required `arrayBuffer()` method. A custom `.mpp` file-like object without binary access returns `binary-reader-unavailable`, and invalid native content returns `invalid-mpp`. Custom XML-only file-like objects can continue implementing only `name` and `text()`.

## Supported XML data

The adapter maps:

- task hierarchy, names, dates, durations, and notes;
- tasks, summary tasks, and milestones;
- completion progress;
- finish-to-start, start-to-start, finish-to-finish, and start-to-finish dependencies;
- the first task baseline exposed by the MSP XML converter.

The conversion result includes warnings when a safe default is introduced or a field cannot be represented. The initial adapter creates a standard Monday-Friday calendar because the underlying converter does not expose Microsoft Project calendar definitions.

## Native MPP14 data

The native importer maps task names, hierarchy, dates, durations, summary tasks, milestones, finish-to-start, start-to-start, finish-to-finish, and start-to-finish dependencies, plus first-baseline dates. It generates WBS codes and a standard Monday-Friday calendar.

The first native release intentionally defaults progress and dependency lag to zero, and omits notes, resources, assignments, Microsoft Project calendars, and additional baselines. The returned `unsupported-fields` warning makes this loss explicit. Native MPP export is not supported; export XML when the resulting schedule must be opened in Microsoft Project.

The converter package ships a genuine legacy `sample.mpp` under `examples/third-party/mpxj/` for signature and version testing. The fixture comes from MPXJ's LGPL-2.1 test corpus and includes its upstream license and exact provenance. Because it is MPP9, importing it returns `unsupported-mpp-version`.

---

# Read-Only Mode

URL: https://pro.rv-grid.com/guides/gantt/features/read-only-mode/
Source: src/content/docs/guides/gantt/features/read-only-mode.mdx
Description: Use Gantt read-only mode to block packaged task, dependency, and assignment mutations while keeping the schedule inspectable.
Surface: gantt

Read-only mode turns the packaged Gantt editing surface into an inspection surface. Users can still view the task table and timeline, navigate, search, filter, sort, zoom, and use non-mutating UI, but packaged project mutations are rejected.

Enable it on the Gantt config:

```ts
grid.gantt = {
  id: 'project-1',
  name: 'Project Roadmap',
  version: '1',
  currency: 'USD',
  timeZone: 'UTC',
  primaryCalendarId: 'standard',
  updatedAt: new Date().toISOString(),
  readOnly: true,
};
```

## What It Blocks

`readOnly: true` blocks mutations routed through the packaged Gantt services:

- Task changes: move, resize, split, progress edits, inline task-field edits, task creation, indent, outdent, and delete.
- Dependency changes: create, update, delete, and predecessor/successor field replacement.
- Assignment changes: assignee/resource field updates and assignment replacement.

Blocked mutations return a failure result instead of updating the stores. Task changes return `readonly-task`; dependency and assignment changes return `readonly-project`.

## What Still Works

Read-only mode does not turn the grid into a static screenshot. Non-mutating workflows remain available:

- Timeline rendering, task bars, dependencies, baselines, critical-path visuals, and diagnostics.
- Tree expand/collapse, search, filtering, sorting, scrolling, and zoom.
- External application-controlled state replacement, such as loading a different project snapshot or changing the Gantt config.

The built-in Gantt context menu also hides mutating row actions when the project is read-only.

## Difference From Grid Readonly

`gantt.readOnly` is a Gantt project mutation guard. It protects the packaged task, dependency, and assignment mutation paths.

The RevoGrid `readonly` property is a grid-level editing setting. Use it when you also want to prevent generic cell editing behavior outside Gantt's mutation services.

```ts
grid.readonly = true;
grid.gantt = {
  ...projectConfig,
  readOnly: true,
};
```

---

# Toolbar And Navigation

URL: https://pro.rv-grid.com/guides/gantt/features/toolbar-and-navigation/
Source: src/content/docs/guides/gantt/features/toolbar-and-navigation.mdx
Description: Build custom Gantt toolbar buttons for export, baselines, critical path, and timeline navigation.
Surface: gantt

These helpers let your application render its own toolbar while reusing Gantt command behavior.

The built-in `defineGanttToolbar()` command bar includes an Excel export icon button by default. The button dispatches the same Pro `export-excel` event as `exportGanttExcel()`, so add `ExportExcelPlugin` to the grid when you want the packaged plugin to create the workbook. Hide it with `controls: { exportExcel: false }` or hide the export group with `controls: { export: false }`.

## Built-In Toolbar

Use `defineGanttToolbar()` when you want the packaged Gantt command bar instead of rendering your own buttons. Mount it after assigning `grid.gantt` so it can read the initial visual state.

```ts
import { defineGanttToolbar } from '@revolist/gantt';

const toolbar = document.querySelector<HTMLElement>('#gantt-toolbar');
const grid = document.querySelector<HTMLRevoGridElement>('revo-grid');

if (!toolbar || !grid) {
  throw new Error('Gantt toolbar host or grid was not found');
}

grid.gantt = projectConfig;

defineGanttToolbar(toolbar, {
  grid,
  columns: [
    { prop: 'wbs', label: 'WBS' },
    { prop: 'name', label: 'Name' },
    { prop: 'startDate', label: 'Start Date' },
    { prop: 'duration', label: 'Duration' },
  ],
  visuals: {
    showDependencies: true,
    showBaseline: false,
    showCriticalPath: false,
  },
});
```

### Control Visibility

Every built-in toolbar option can be hidden with `controls`. Omitted control flags are visible by default, except `baseline`, which is opt-in.

```ts
defineGanttToolbar(toolbar, {
  grid,
  controls: {
    search: false,
    history: false,
    tree: false,
    zoom: true,
    zoomOut: false,
    tasks: true,
    indent: false,
    outdent: false,
    export: false,
    columns: false,
    dependencies: true,
    baseline: false,
    criticalPath: true,
  },
});
```

Parent group flags hide their child buttons:

| Parent flag | Child buttons |
| --- | --- |
| `history` | `undo`, `redo` |
| `tree` | `expandAll`, `collapseAll` |
| `zoom` | `zoomIn`, `zoomOut` |
| `tasks` | `addTask`, `indent`, `outdent` |
| `export` | `exportExcel` |

Leaf flags hide individual controls: `search`, `columns`, `dependencies`, `baseline`, and `criticalPath`.

Hidden visual controls do not write their local defaults back into `grid.gantt.visuals`. You can still set hidden visual behavior directly in `grid.gantt.visuals`.

The dependency toggle is display-only. Turning it off updates `grid.gantt.visuals.showDependencies = false`, which hides dependency arrows without clearing `grid.ganttDependencies` or changing scheduler dependency inputs.

```ts
import {
  captureGanttBaseline,
  createGanttToolbarQuickWinActions,
  exportGanttCsv,
  exportGanttExcel,
  fitGanttToProject,
  listGanttToolbarQuickWinActions,
  scrollGanttToToday,
  toggleGanttCriticalPath,
} from '@revolist/gantt';
```

## Direct Commands

Use direct helpers when you already know which button was clicked.

```ts
const grid = document.querySelector<HTMLRevoGridElement>('revo-grid');

if (!grid) {
  throw new Error('Gantt grid was not found');
}

await exportGanttCsv(grid, { filename: 'launch-plan' });
exportGanttExcel(grid, { workbookName: 'launch-plan.xlsx' });

await captureGanttBaseline(grid, { name: 'Sprint baseline' });
const criticalPathVisible = toggleGanttCriticalPath(grid);

await scrollGanttToToday(grid, { align: 0.5 });
await fitGanttToProject(grid, { viewportWidth: grid.clientWidth });
```

## Command Descriptors

Use `createGanttToolbarQuickWinActions()` when a framework toolbar should render generic command objects. Creating descriptors does not export, scroll, or mutate the grid. Work happens only when `run()` is called.

```ts
const actions = createGanttToolbarQuickWinActions(grid, {
  csv: { filename: 'launch-plan' },
  excel: { workbookName: 'launch-plan.xlsx' },
  baseline: { name: 'Sprint baseline' },
  today: { align: 0.5 },
  fitToProject: { viewportWidth: grid.clientWidth },
});

for (const action of listGanttToolbarQuickWinActions(actions)) {
  renderButton({
    id: action.id,
    label: action.label,
    title: action.title,
    onClick: () => void action.run(),
  });
}

declare function renderButton(command: {
  id: string;
  label: string;
  title: string;
  onClick: () => void;
}): void;
```

Disable individual commands by passing `false`.

```ts
const readonlyActions = createGanttToolbarQuickWinActions(grid, {
  csv: false,
  baseline: false,
});
```

## Behavior Notes

- CSV export uses the RevoGrid export plugin when a plugin with `exportFile()` is installed.
- Excel export dispatches the Pro Excel export event on the grid.
- Baseline capture looks for the Gantt runtime and appends the captured snapshot to `grid.ganttBaselines`.
- Critical path toggling updates `grid.gantt.visuals.showCriticalPath`.
- Today and fit-to-project navigation delegate to runtime methods when available, otherwise they compute timeline coordinates and call `grid.scrollToCoordinate()`.

---

# Add Task Row

URL: https://pro.rv-grid.com/guides/gantt/interaction/add-task-row/
Source: src/content/docs/guides/gantt/interaction/add-task-row.mdx
Description: Use the pinned Gantt add-task row and identify it with isGanttAddTaskRow.
Surface: gantt

`GanttPlugin` can show a pinned bottom row for quickly creating tasks by typing a name into the task table.

Enable it with `taskCreateRow: true` and `allowTaskCreate: true`:

```ts
import { GanttPlugin } from '@revolist/gantt';

grid.plugins = [GanttPlugin];
grid.gantt = {
  ...project,
  allowTaskCreate: true,
  taskCreateRow: true,
};
```

The row is hidden when Gantt is read-only or when resource planning mode is active.

## How It Works

`GanttPlugin` installs `GanttAddTaskRowPlugin` internally. Do not add `GanttAddTaskRowPlugin` to `grid.plugins` yourself.

The internal plugin owns a draft row in the `rowPinEnd` source. That draft row is not a task entity and is not written into `grid.source`. When the user edits the `name` cell with a non-empty value, Gantt creates a new root task at the end of the project and resets the draft row.

Only the `name` cell is editable. Other cells are rendered as inert cells, row drag is disabled for the draft row, and the generated Gantt context menu is suppressed on it.

## Identifying The Draft Row

Use `isGanttAddTaskRow()` when custom columns or actions need to skip the draft row:

```ts
import {
  GanttPlugin,
  isGanttAddTaskRow,
} from '@revolist/gantt';
import { RowSelectPlugin } from '@revolist/revogrid-pro';

grid.plugins = [GanttPlugin, RowSelectPlugin];
grid.columns = [
  {
    prop: 'selected',
    name: '',
    rowSelect: ({ model }) => !isGanttAddTaskRow(model),
    size: 56,
    readonly: true,
    filter: false,
  },
  // Task table columns...
];
```

This is useful for checkbox selection, custom cell renderers, and application actions that should apply only to real task rows.

## Custom Context Menus

When Gantt context-menu integration is enabled, the generated row menu does not open on the add-task draft row. If your application fully disables Gantt context-menu integration and owns `rowContextMenu` itself, keep the same rule in your resolver:

```ts
grid.rowContextMenu = {
  items: [
    { name: 'Open task details', action: openTaskDetailsFromMenu },
  ],
  resolve(context) {
    if (context.triggerElement.closest('[data-gantt-add-task-row-cell="true"]')) {
      return null;
    }

    return undefined;
  },
};

grid.gantt = {
  ...project,
  contextMenu: false,
};
```

For model-based checks inside item actions, read the focused row model from the action context and pass it to `isGanttAddTaskRow()`.

---

# Dependency Editing

URL: https://pro.rv-grid.com/guides/gantt/interaction/dependency-editing/
Source: src/content/docs/guides/gantt/interaction/dependency-editing.mdx
Description: Create, select, and delete dependency links in timeline.
Surface: gantt

Dependency editing supports:

- Drag-to-create links from dependency handles.
- Allowed-type filtering via `gantt.allowedDependencyTypes`.
- Hover/select styling and inline delete UI.
- Keyboard delete on selected dependency.

## Mobile And Touch Devices

On touch devices, dependency handles follow the same select-then-edit model as task-bar editing:

- Tap a task bar to select it.
- Gantt reveals larger dependency handles on the selected bar.
- Drag from a visible start or end dependency handle to another task bar.
- If the pointer lands on a target handle, Gantt uses that explicit endpoint.
- If the pointer lands on the target bar but not a handle, Gantt infers start or end from the pointer position relative to the bar midpoint.

Hidden dependency handles are not hit-testable on coarse pointers, so a swipe near the edge of an unselected task does not start dependency creation. This keeps timeline scrolling usable on phones and tablets while preserving precise dependency editing after task selection.

Implementation:

- `features/dependencies/drag-controller.ts`
- `features/dependencies/dependency-tool.ts`
- `features/dependencies/dependency-layer.ts`

---

# Drag, Resize, And Progress Editing

URL: https://pro.rv-grid.com/guides/gantt/interaction/drag-resize-progress/
Source: src/content/docs/guides/gantt/interaction/drag-resize-progress.mdx
Description: Timeline gesture interactions for task bars.
Surface: gantt

Implemented interactions:

- Drag task bars to move.
- Drag start/end handles to resize.
- Drag progress handle to update completion.

Each interaction has preview state and commit state and can trigger warning/diagnostic updates.

## Mobile And Touch Devices

Gantt supports phones, tablets, and hybrid devices through adaptive pointer handling. Desktop users can drag task bars and handles directly. Touch users get a safer select-then-edit flow so scrolling a dense timeline does not accidentally change the schedule.

On coarse-pointer devices:

- Tap a task bar to select it.
- Selection reveals larger resize, dependency, progress, and split handles.
- Drag the selected task bar to move the task.
- Drag a visible start/end handle to resize.
- Drag the visible progress handle to update completion.
- Start swiping from an unselected task bar when you want to pan the task table or timeline; hidden handles are not hit-testable until selection.

The mobile path keeps native panning available for unselected task bars and disables browser touch panning only on selected/active bars or visible edit handles. This preserves scroll-first behavior while still allowing precise edits after the user has selected the task.

The packaged task editor dialog also adapts to phone-width screens with a full-viewport, single-column layout and larger touch targets.

Implementation:

- `features/tasks/controllers/task-drag-controller.ts`
- `features/tasks/controllers/task-resize-controller.ts`
- `features/tasks/controllers/task-progress-controller.ts`
- `features/tasks/controllers/pointer-gesture.ts`
- `features/tasks/timeline-preview-layer.ts`

---

# Row Selection

URL: https://pro.rv-grid.com/guides/gantt/interaction/row-selection/
Source: src/content/docs/guides/gantt/interaction/row-selection.mdx
Description: Use RowSelectPlugin with Gantt task operations and row reordering.
Surface: gantt

`GanttPlugin` can work with the RevoGrid Pro `RowSelectPlugin` when you want checkbox-based task selection in the task table.

Add a row-select column, register `RowSelectPlugin`, and enable the row-order bridge when selected rows should move together during Gantt row reordering.

```ts
import { GanttPlugin, isGanttAddTaskRow } from '@revolist/gantt';
import { RowSelectPlugin } from '@revolist/revogrid-pro';

const grid = document.querySelector('revo-grid');

grid.plugins = [GanttPlugin, RowSelectPlugin];
grid.rowSelect = {
  rowOrder: true,
};
grid.columns = [
  {
    prop: 'selected',
    name: '',
    rowSelect: ({ model }) => !isGanttAddTaskRow(model),
    size: 56,
    readonly: true,
    filter: false,
  },
  // Task table columns...
];
```

The checkbox column uses physical task rows from `grid.source`. Gantt ignores resource rows and non-task rows when resolving checkbox selection for task operations.

Use `isGanttAddTaskRow()` when `taskCreateRow` is enabled so the pinned “Add new task” row does not render a checkbox. See [Add Task Row](/guides/gantt/interaction/add-task-row/) for the draft-row contract.

## Bulk Gantt Operations

When no explicit task ids are passed, Gantt resolves task ids in this order:

1. Checkbox-selected rows from `RowSelectPlugin`.
2. Gantt task range selection.
3. The currently focused or selected Gantt task.

This means toolbar buttons, context-menu actions, keyboard handlers, or application code can call the existing Gantt methods without manually collecting checkbox state:

```ts
const plugins = await grid.getPlugins();
const gantt = plugins.find((plugin) => plugin instanceof GanttPlugin);

gantt?.deleteTasks();
gantt?.indentTasks();
gantt?.outdentTasks();
gantt?.convertTasksToMilestones();
```

After a successful delete, Gantt clears the row-select checkbox state for task rows so removed tasks do not remain selected in `RowSelectPlugin`.

## Row Reordering

Gantt installs `RowOrderPlugin` internally. `RowSelectPlugin` does not automatically move all checked rows unless the row-select row-order integration is enabled:

```ts
grid.rowSelect = {
  rowOrder: true,
};
```

With `rowOrder: true`, dragging a checked task row moves the visible checked task rows as one compact block. Dragging an unchecked row keeps the normal Gantt row-order behavior.

## Framework Bindings

React:

```tsx
<RevoGrid
  plugins={[GanttPlugin, RowSelectPlugin]}
  rowSelect={{ rowOrder: true }}
  columns={[
    {
      prop: 'selected',
      name: '',
      rowSelect: ({ model }) => !isGanttAddTaskRow(model),
      size: 56,
      readonly: true,
      filter: false,
    },
    ...taskColumns,
  ]}
/>
```

Vue:

```vue
<RevoGrid
  :plugins="plugins"
  :row-select.prop="{ rowOrder: true }"
  :columns="columns"
/>
```

Angular:

```html
<revo-grid
  [plugins]="plugins"
  [rowSelect]="{ rowOrder: true }"
  [columns]="columns"
></revo-grid>
```

For Vue Gantt examples, use `.prop` for `row-select` because it is a direct grid plugin property.

---

# Task Editing

URL: https://pro.rv-grid.com/guides/gantt/interaction/task-editing/
Source: src/content/docs/guides/gantt/interaction/task-editing.mdx
Description: Inline editing, the default task editor dialog, and scheduler-backed mutation flow.
Surface: gantt

Task edits route through mutation services and scheduler recomputation. Before applying task changes, Gantt emits cancelable `gantt-before-task-change`; dependency field edits emit `gantt-before-dependency-change`; assignee edits emit `gantt-before-assignment-change`.

Command/event surface is defined in:

- `packages/gantt/src/gantt/grid/gantt-events.ts`
- `packages/gantt/src/gantt/grid/gantt-plugin.ts`

For persistence and audit, listen to the unified `gridedit` event and inspect its typed `domainChanges`. Successful Gantt mutations are tagged with `gantt-task-change`, `gantt-dependency-change`, or `gantt-assignment-change`; rejected changes do not add Gantt domain entries. The Gantt before-change events remain the cancellation boundary.

## Inline Editing

Inline Gantt edits update the task through the Gantt mutation services, recompute the project, and emit history snapshots for user changes. Initial project hydration is not recorded as a history step.

Call `event.preventDefault()` in a before-change listener to reject a field edit before the task, dependency, or assignment store is mutated. Rejected predecessor/successor edits leave the old dependency rows in place; rejected assignee edits leave the old assignment rows in place.

### Edit validation boundary

`resolveTaskEdit()` is the stable validation entry point for inline task fields. It converts a raw editor value into a validated `TaskUpdate` patch or returns an `invalid-field`, `invalid-value`, or `readonly-derived-field` failure. It does not mutate task data itself. The task mutation service applies the accepted patch, and the scheduling engine then recomputes derived dates and project state.

Task-table text-entry editors follow spreadsheet-style keyboard entry, including text, numeric, percentage, date-text, Duration, Remaining Duration, and Work fields. With a cell selected, typing a printable character starts a new value and replaces the displayed value; for example, pressing `4` opens the editor with `4`. Press Enter or double-click instead when you want to open and modify the existing value. Choice, checkbox, and calendar controls keep their domain-specific input behavior.

The task table and Task Information dialog select controls from the same framework-neutral `TaskEditorFieldSchema.kind` contract. Duration, Remaining Duration, and Work use the explicit `duration` kind, so both surfaces share text input semantics, duration-field identification, formatting, and parsing. Grid adapters still own RevoGrid `EditorBase` lifecycle and keyboard seeds, while dialog adapters own controlled form state; this keeps behavior reusable without coupling modal controls to grid DOM lifecycle.

A zero Duration schedules the row as a milestone, but its Duration remains editable. Entering a positive Duration in either the grid or Task Information dialog converts it back to a regular task automatically. Summary Duration remains read-only because the scheduler derives it from the child-task span.

Dialog control rendering is decomposed by responsibility under `packages/gantt/src/gantt-task-editor-dialog/field-controls/`: input, date, select, switch, tags, textarea, and labels/resource controls each own one control category. The top-level `FieldControl` only dispatches by the shared field kind.

The implementation is split by value category under `packages/gantt/src/gantt/engine/task-edit-service/internal/`: date, duration, numeric, boolean, progress, name, status, task-mode, effort-mode, and constraint handlers each own their parsing, validation messages, and patch creation. Consumers link directly to `engine/task-edit-service/index`, whose only responsibility is dispatching to the appropriate handler. This keeps custom label handling and schedule-aware validation consistent without collecting every edit rule into one service file or exposing handler registries as public API.

The split is internal and does not change imports, event names, field behavior, or `TaskEditResult`. Existing integrations should continue importing Gantt APIs from `@revolist/gantt`.

## Task Editor Dialog

`GanttPlugin` installs the packaged task editor dialog by default, so every Gantt grid gets the row context-menu editor without registering an extra plugin. The same editor contract is also available as presentation-free helpers: render controls from `TASK_EDITOR_FIELD_SCHEMA`, seed them with `createTaskEditorFormValues()`, and turn submitted values into a `TaskUpdate` patch with `normalizeTaskEditorSubmit()`.

The packaged dialog is responsive for mobile use. On phone-width viewports it becomes a full-viewport dialog, switches task fields and dependency rows to a single column, keeps the form body scrollable, and uses larger controls for touch input. The same validation and submit flow runs on desktop, tablet, and phone layouts.

## How It Works

The task editor demo opens the editor from the Gantt row context menu and includes the packaged Gantt toolbar:

- The grid renders normal Gantt tasks, dependencies, calendars, resources, and assignments.
- Right-click a task row and choose **Edit...**.
- Use row context-menu **Add** to insert a `New task N` row without opening the editor, or toolbar **Task** to create a task and open the same editor for the new row.
- The auto-installed task editor dialog adds the row-menu edit item and owns the native HTML `<dialog>`.
- New tasks open in the editor by default after the Gantt plugin emits its post-create lifecycle event. Set `ganttTaskEditorDialog.openOnCreate` to `false` when task creation should stay silent.
- The dialog renders a tabbed task information UI from `TASK_EDITOR_FIELD_SCHEMA`.
- **General** contains task name, status, task kind, dates, duration, and progress.
- **Advanced** contains effort mode, calendar, tags, constraints, manual scheduling, work, actual dates, inactive state, and leveling controls.
- **Predecessors** edits incoming dependency target, type, and lead/lag days. **Successors** remains available through customization but is hidden by default.
- **Resources** renders the resource assignment picker when resources and assignments are available.
- **Notes** provides a dedicated long-form notes editor.
- The patch preview calls `normalizeTaskEditorSubmit(task, values)` on every edit.
- The submit button applies the returned patch through the Gantt runtime/provider edit path, updates `grid.ganttAssignments` and `grid.ganttDependencies`, and refreshes the project.

```ts
grid.plugins = [GanttPlugin];
grid.ganttTaskEditorDialog = {
  title: 'Task details',
  description: 'Update task fields and save the changes to the project schedule.',
  applyLabel: 'Save changes',
  localeText: {
    tabs: {
      assignments: 'Team',
    },
    fields: {
      effortMode: 'Task type',
    },
    resourcesSearch: {
      placeholder: 'Find a resource',
    },
  },
};

const values = createTaskEditorFormValues(task, resources, assignments);
const result = normalizeTaskEditorSubmit(task, values);

if (result.ok) {
  updateTask(task.id, result.patch);
}
```

## Fields

The schema includes editable task fields such as `name`, `startDate`, `endDate`, `duration`, `progressPercent`, constraints, deadlines, actual dates, work, effort mode, effort-driven scheduling, inactive state, leveling controls, manual scheduling, and `notes`. It also includes display fields such as `resourceLabels`.

Date fields open as date-only controls by default. Use the field-level **Time** toggle in the packaged dialog when you need minute-level scheduling; the dialog stores the submitted value as a UTC ISO datetime.

Set `gantt.dateFormats.editor` when the packaged dialog should show custom date text instead of native date inputs. In that mode, the dialog uses a text input, calls your parser as the user types, and still submits ISO dates to `normalizeTaskEditorSubmit()` and the Gantt mutation services:

```ts
grid.gantt = {
  ...project,
  dateFormats: {
    locale: 'en-GB',
    timeZone: 'UTC',
    table: { day: '2-digit', month: '2-digit', year: 'numeric' },
    tooltip: { day: '2-digit', month: 'short', year: 'numeric' },
    editor: {
      options: { day: '2-digit', month: '2-digit', year: 'numeric' },
      parser(value) {
        const match = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(value.trim());
        return match ? `${match[3]}-${match[2]}-${match[1]}` : null;
      },
    },
  },
};
```

Custom date formats are presentation and input helpers only. Keep persisted tasks as `YYYY-MM-DD` dates or UTC datetimes ending in `Z`.

`resourceLabels` is read-only in the schema helper because `TaskUpdate` does not own assignment rows. The packaged dialog upgrades that field into a resource assignment picker and writes the selected resources to `grid.ganttAssignments`. Set `ganttTaskEditorDialog.resources` to `false` when you want the field to stay read-only.

Resource options show `ResourceEntity.avatarUrl` as a circular profile image. When no image is configured—or an image fails to load—the picker renders deterministic initials from the resource name, so every assignment remains visually identifiable without requiring avatar assets.

Entity panels include search controls: resource assignment searches by resource name and role, while predecessor and successor panels search task names. Resource lists, task dropdowns, dependency type dropdowns, and schema-backed select options are sorted A-Z by their displayed labels.

Use `ganttTaskEditorDialog.localeText` to translate or customize packaged dialog text. It covers tabs, field labels, field option labels, dependency type labels, empty states, search placeholders, switch labels, validation headings, save errors, and context-menu text. Existing top-level `title`, `description`, `applyLabel`, `resetLabel`, `closeLabel`, and `menuItemName` still work as direct overrides for those common labels.

## Customizing Tabs, Fields, and Controls

Use `ganttTaskEditorDialog.customization` to change the packaged editor without replacing it. Built-in tab ids are `details`, `predecessors`, `successors`, `assignments`, `advanced`, and `notes`. Set an item to `false` to remove it, use `hidden`, `title`, and `fields` to reconfigure it, and use `order` to place built-in and custom tabs. Nested customization takes precedence over the legacy top-level `fields` allow-list.

```ts
grid.ganttTaskEditorDialog = {
  fields: ['name', 'status', 'type', 'startDate', 'endDate', 'calendarId', 'tags', 'notes'],
  customization: {
    controls: {
      description: false,
      reset: false,
    },
    tabs: {
      order: ['details', 'successors', 'advanced', 'notes'],
      items: {
        details: { title: 'Main', fields: ['name', 'status', 'type', 'startDate', 'endDate'] },
        successors: { hidden: false },
        assignments: false,
      },
    },
  },
};
```

The shell controls are `header`, `title`, `description`, `close`, `tabs`, `validation`, `preview`, `reset`, `apply`, and `footer`. Setting one to `false` hides only the packaged control; custom content can still call the corresponding controller method.

### Adding a Custom Page

Custom pages use a framework-neutral DOM lifecycle. `mount` runs once when the page is shown, `update` receives fresh task/project/draft context, and `destroy` runs when the page is removed. The controller can update built-in values, resources, dependencies, application-owned custom values, validation errors, and the reset/close/submit lifecycle.

```ts
const auditPage = {
  mount(container, context) {
    let currentContext = context;
    const input = document.createElement('input');
    input.placeholder = 'External approval reference';
    container.appendChild(input);

    const onInput = () => {
      currentContext.controller.setCustomValue('approvalReference', input.value);
      currentContext.controller.setValidationErrors(input.value.trim() ? [] : ['Approval reference is required.']);
    };
    input.addEventListener('input', onInput);

    return {
      update(next) {
        currentContext = next;
        input.value = String(next.state.customValues.approvalReference ?? '');
      },
      destroy() {
        input.removeEventListener('input', onInput);
      },
    };
  },
};

grid.ganttTaskEditorDialog = {
  customization: {
    tabs: {
      order: ['details', 'audit', 'notes'],
      items: { audit: { title: 'Audit', renderer: auditPage } },
    },
  },
  async onSubmit({ result, customValues }) {
    await saveTaskAndApproval(result.patch, customValues.approvalReference);
  },
};
```

Custom values are passed to `onSubmit` but are never persisted implicitly. Custom validation errors block packaged submission until cleared.

### Replacing the Entire Editor

Set `customization.editor` to the same DOM renderer contract to replace the packaged dialog completely. The replacement receives the live project snapshot and shared draft controller, including `reset()`, `close()`, and `submit()`. Its lifecycle is destroyed when the editor closes or the plugin is removed.

### Calendar and Tags

`calendarId` is populated from the live Gantt calendars and validated before mutation. Changing it uses the normal task mutation, rescheduling, and history path. `tags` accepts comma-separated input; values are trimmed, blank entries are removed, and duplicates are removed while preserving their first-seen order.

Use `ganttTaskEditorDialog.openOnCreate = false` to keep toolbar or programmatic task creation from opening the dialog. The Gantt row context menu always creates silently through the default **Add** action when task creation is allowed, and the editor plugin prepends its **Edit...** item while preserving custom `rowContextMenu` or `contextMenu` items and `resolve` behavior. Set `gantt.contextMenu = false` to opt out of generated Gantt menu items, or set `ganttTaskEditorDialog.contextMenu` when only the packaged editor menu item should change.

## Task Colors

The Gantt row context menu and packaged task editor use the same shared color palette. Choosing a color updates the task through the normal Gantt mutation path, so source synchronization, cancelable before-change events, history, scheduling, and rendering stay consistent. **Default** clears the authored task color; `taskBarColorHook` remains authoritative when it returns a color.

Use `options` to replace the shared palette or `extendOptions` to add project colors. Any swatch can be disabled, as can the Default choice or the complete Color command:

```ts
grid.gantt = {
  ...project,
  contextMenu: {
    colorPalette: {
      extendOptions: [
        { value: '#7c3aed', label: 'Project violet' },
        { value: '#0f766e', label: 'Reserved teal', disabled: true },
      ],
      defaultOption: { label: 'Use project default' },
      colorAriaLabel: (option) => `Task color: ${option.label}`,
    },
    disabled: {
      delete: true,
    },
  },
};
```

Set `contextMenu.colorPalette` to `false`, `contextMenu.hidden.color` to `true`, or `contextMenu.disabled.color` to `true` to remove or disable this functionality. Set `colorPalette.defaultOption` to `false` to remove Default, or `colorPalette.disabled` to `true` to disable the whole submenu. The same `hidden` and `disabled` maps apply to the other built-in Gantt commands. Application commands supplied through RevoGrid's row-context-menu configuration continue to compose with the generated Gantt items.

The task editor inherits `gantt.contextMenu.colorPalette` by default. Use `ganttTaskEditorDialog.colorPalette` to configure its palette independently, or set it to `false` to remove the Color field from the editor. The editor-specific setting supports the same `options`, `extendOptions`, disabled choices, Default configuration, and accessible option-label resolver.

## Validation

`normalizeTaskEditorSubmit()` validates values before returning a patch:

- `name` cannot be empty.
- Date values must be ISO dates like `2026-05-12` or UTC datetimes ending in `Z`.
- `endDate` cannot be earlier than `startDate`.
- Numeric fields must be non-negative.
- `progressPercent` is clamped to `0..100`.
- Unsupported constraint values return field errors.

If both `startDate` and `endDate` are present, the helper recalculates `duration` from the date range. If values are unchanged, the default result omits them from the patch.

## Production Wiring

In production, keep the same flow but replace the demo's local source update with your persistence and project-state update path:

```ts
async function submitTaskEditor(task, values) {
  const result = normalizeTaskEditorSubmit(task, values);

  if (!result.ok) {
    renderFieldErrors(result.errors);
    return;
  }

  await api.updateTask(task.id, result.patch);
  grid.source = grid.source.map((row) =>
    row.id === task.id ? { ...row, ...result.patch } : row,
  );
}
```

The Gantt plugin still owns timeline projection and scheduling when the refreshed task source is applied.

The packaged dialog defaults to applying task field patches through the Gantt runtime/provider edit path and replacing the edited task's assignment rows in `grid.ganttAssignments`. This keeps task editor saves visible to `HistoryPlugin` instead of bypassing grid edit tracking with direct `grid.source` replacement. To persist edits first, provide `ganttTaskEditorDialog.onSubmit`; return `false` from that callback when your application has already applied the task and assignment updates and the plugin should skip the default patch.

Dependency tabs also patch `grid.ganttDependencies` by replacing links that involve the edited task. Existing dependency ids are preserved, new rows get deterministic ids, and lag supports negative lead or positive lag days.

Set `preview: true` only for diagnostics or documentation when you want to show the generated `TaskUpdate` JSON.

---

# Gantt Quick Start — Angular

URL: https://pro.rv-grid.com/guides/gantt/introduction/angular/
Source: src/content/docs/guides/gantt/introduction/angular.mdx
Description: Build a RevoGrid Gantt project in Angular with the standalone wrapper, typed property bindings, and managed task columns.
Surface: gantt

1. Complete [installation](/guides/gantt/introduction/installation/) for Angular.

2. Create a standalone component and bind every Gantt collection as a property.

   ```ts
   import { Component, ViewEncapsulation } from '@angular/core';
   import { RevoGrid } from '@revolist/angular-datagrid';
   import {
     GanttPlugin,
     createDefaultTaskTableColumn,
     type CalendarEntity,
     type DependencyEntity,
     type GanttPluginConfig,
     type GanttTaskSourceRow,
   } from '@revolist/gantt';

   @Component({
     selector: 'app-project-gantt',
     standalone: true,
     imports: [RevoGrid],
     encapsulation: ViewEncapsulation.None,
     styles: ['.project-gantt { display: block; width: 100%; height: 640px; }'],
     template: `
       <revo-grid
         class="project-gantt"
         [plugins]="plugins"
         [gantt]="project"
         [ganttCalendars]="calendars"
         [ganttDependencies]="dependencies"
         [columns]="columns"
         [source]="tasks"
       ></revo-grid>
     `,
   })
   export class ProjectGanttComponent {
     plugins = [GanttPlugin];
     project: GanttPluginConfig = {
       id: 'website-launch', name: 'Website launch', version: '1', currency: 'USD',
       timeZone: 'UTC', primaryCalendarId: 'standard',
       updatedAt: '2026-07-14T00:00:00.000Z', zoomPreset: 'day-week',
     };
     calendars: CalendarEntity[] = [{
       id: 'standard', name: 'Standard', timeZone: 'UTC',
       workingDays: [1, 2, 3, 4, 5], holidays: [], hoursPerDay: 8,
     }];
     tasks: GanttTaskSourceRow[] = [
       { id: 'design', name: 'Design', startDate: '2026-07-14', duration: 3, percentDone: 50, calendarId: 'standard' },
       { id: 'build', name: 'Build', startDate: '2026-07-17', duration: 5, percentDone: 0, calendarId: 'standard' },
     ];
     dependencies: DependencyEntity[] = [{
       id: 'design-to-build', predecessorTaskId: 'design', successorTaskId: 'build', type: 'FS', lagDays: 0,
     }];
     columns = [
       createDefaultTaskTableColumn('wbs'),
       createDefaultTaskTableColumn('name'),
       createDefaultTaskTableColumn('startDate'),
       createDefaultTaskTableColumn('duration'),
       createDefaultTaskTableColumn('percentDone'),
       createDefaultTaskTableColumn('predecessors'),
     ];
   }
   ```

3. Import the Pro and Gantt CSS files in the application-wide stylesheet or build entry, not in an encapsulated child stylesheet.

  Open the runnable <a href="https://demo.rv-grid.com/gantt-basic/angular">Angular demo</a> for the complete application source.

Continue with the [Gantt tutorial](/guides/gantt/tutorial/) and [application state guide](/guides/gantt/features/application-state/).

---

# Install RevoGrid Gantt

URL: https://pro.rv-grid.com/guides/gantt/introduction/installation/
Source: src/content/docs/guides/gantt/introduction/installation.mdx
Description: Install the standalone RevoGrid Gantt package, styles, and framework wrapper required to render a project.
Surface: gantt

Install `@revolist/gantt` alongside the core grid and Pro. Add only the framework wrapper your application uses.

1. Install the packages.

       ```bash
       pnpm add @revolist/revogrid @revolist/revogrid-pro @revolist/gantt
       ```

       ```bash
       pnpm add @revolist/revogrid @revolist/revogrid-pro @revolist/gantt @revolist/react-datagrid
       ```

       ```bash
       pnpm add @revolist/revogrid @revolist/revogrid-pro @revolist/gantt @revolist/vue3-datagrid
       ```

       ```bash
       pnpm add @revolist/revogrid @revolist/revogrid-pro @revolist/gantt @revolist/angular-datagrid
       ```

2. Import the product styles once in the application entry point.

   ```ts
   import '@revolist/revogrid-pro/dist/revogrid-pro.css';
   import '@revolist/gantt/styles.css';
   ```

3. Register `GanttPlugin` on the grid.

   ```ts
   import { GanttPlugin } from '@revolist/gantt';

   grid.plugins = [GanttPlugin];
   ```

4. Give the grid a visible size. Gantt needs both width and height to calculate its virtual viewport.

   ```css
   .project-gantt {
     display: block;
     width: 100%;
     height: 640px;
   }
   ```

  Evaluating Gantt? Follow the <a href="/guides/installation-npm-trial/">trial installation guide</a> and use `@revolist/gantt-trial` with its matching CSS path.

## Choose Your Framework

- [Vanilla TypeScript](/guides/gantt/introduction/vanilla-typescript/)
- [React](/guides/gantt/introduction/react/)
- [Vue 3](/guides/gantt/introduction/vue/)
- [Angular](/guides/gantt/introduction/angular/)

The general [Pro and product installation guide](/guides/installation/) covers private registry, pre-built, GitHub, source-build, and no-build distribution options.

---

# Gantt Quick Start — React

URL: https://pro.rv-grid.com/guides/gantt/introduction/react/
Source: src/content/docs/guides/gantt/introduction/react.mdx
Description: Build a typed RevoGrid Gantt project in React with memoized project collections, calendars, dependencies, and task columns.
Surface: gantt

1. Complete [installation](/guides/gantt/introduction/installation/) for React.

2. Create the component. Keep project collections and columns stable with `useMemo` so ordinary React renders do not replace Gantt state unnecessarily.

   ```tsx
   import { useMemo } from 'react';
   import { RevoGrid } from '@revolist/react-datagrid';
   import {
     GanttPlugin,
     createDefaultTaskTableColumn,
     type CalendarEntity,
     type DependencyEntity,
     type GanttPluginConfig,
     type GanttTaskSourceRow,
   } from '@revolist/gantt';

   import '@revolist/revogrid-pro/dist/revogrid-pro.css';
   import '@revolist/gantt/styles.css';

   export default function ProjectGantt() {
     const plugins = useMemo(() => [GanttPlugin], []);
     const project = useMemo<GanttPluginConfig>(() => ({
       id: 'website-launch',
       name: 'Website launch',
       version: '1',
       currency: 'USD',
       timeZone: 'UTC',
       primaryCalendarId: 'standard',
       updatedAt: '2026-07-14T00:00:00.000Z',
       zoomPreset: 'day-week',
     }), []);
     const calendars = useMemo<CalendarEntity[]>(() => [{
       id: 'standard', name: 'Standard', timeZone: 'UTC',
       workingDays: [1, 2, 3, 4, 5], holidays: [], hoursPerDay: 8,
     }], []);
     const source = useMemo<GanttTaskSourceRow[]>(() => [
       { id: 'design', name: 'Design', startDate: '2026-07-14', duration: 3, percentDone: 50, calendarId: 'standard' },
       { id: 'build', name: 'Build', startDate: '2026-07-17', duration: 5, percentDone: 0, calendarId: 'standard' },
     ], []);
     const dependencies = useMemo<DependencyEntity[]>(() => [{
       id: 'design-to-build', predecessorTaskId: 'design', successorTaskId: 'build', type: 'FS', lagDays: 0,
     }], []);
     const columns = useMemo(() => [
       createDefaultTaskTableColumn('wbs'),
       createDefaultTaskTableColumn('name'),
       createDefaultTaskTableColumn('startDate'),
       createDefaultTaskTableColumn('duration'),
       createDefaultTaskTableColumn('percentDone'),
       createDefaultTaskTableColumn('predecessors'),
     ], []);

     return (
       <RevoGrid
         className="project-gantt"
         plugins={plugins}
         gantt={project}
         ganttCalendars={calendars}
         ganttDependencies={dependencies}
         columns={columns}
         source={source}
       />
     );
   }
   ```

3. Give `.project-gantt` a fixed or flex-derived height.

   ```css
   .project-gantt { display: block; width: 100%; height: 640px; }
   ```

  Open the runnable <a href="https://demo.rv-grid.com/gantt-basic/react">React demo</a> for the complete application source.

Continue with the [Gantt tutorial](/guides/gantt/tutorial/) and [application state guide](/guides/gantt/features/application-state/).

---

# Gantt Quick Start — Vanilla TypeScript

URL: https://pro.rv-grid.com/guides/gantt/introduction/vanilla-typescript/
Source: src/content/docs/guides/gantt/introduction/vanilla-typescript.mdx
Description: Build a RevoGrid Gantt project with the custom element, typed project data, task columns, calendars, and dependencies.
Surface: gantt

1. Complete [installation](/guides/gantt/introduction/installation/) and add a mount element.

   ```html
   <div id="gantt"></div>
   ```

2. Register the custom element and create the project.

   ```ts
   import { defineCustomElements } from '@revolist/revogrid/loader';
   import {
     GanttPlugin,
     createDefaultTaskTableColumn,
     type CalendarEntity,
     type DependencyEntity,
     type GanttPluginConfig,
     type GanttTaskSourceRow,
   } from '@revolist/gantt';

   import '@revolist/revogrid-pro/dist/revogrid-pro.css';
   import '@revolist/gantt/styles.css';

   defineCustomElements();

   const project: GanttPluginConfig = {
     id: 'website-launch',
     name: 'Website launch',
     version: '1',
     currency: 'USD',
     timeZone: 'UTC',
     primaryCalendarId: 'standard',
     updatedAt: '2026-07-14T00:00:00.000Z',
     zoomPreset: 'day-week',
   };

   const calendars: CalendarEntity[] = [{
     id: 'standard',
     name: 'Standard',
     timeZone: 'UTC',
     workingDays: [1, 2, 3, 4, 5],
     holidays: [],
     hoursPerDay: 8,
   }];

   const tasks: GanttTaskSourceRow[] = [
     {
       id: 'design',
       name: 'Design',
       startDate: '2026-07-14',
       duration: 3,
       percentDone: 50,
       calendarId: 'standard',
     },
     {
       id: 'build',
       name: 'Build',
       startDate: '2026-07-17',
       duration: 5,
       percentDone: 0,
       calendarId: 'standard',
     },
   ];

   const dependencies: DependencyEntity[] = [{
     id: 'design-to-build',
     predecessorTaskId: 'design',
     successorTaskId: 'build',
     type: 'FS',
     lagDays: 0,
   }];
   ```

3. Configure and mount the grid. Set `source` after the element is connected.

   ```ts
   const host = document.querySelector('#gantt');
   if (!host) throw new Error('Missing #gantt');

   const grid = document.createElement('revo-grid');
   grid.className = 'project-gantt';
   grid.plugins = [GanttPlugin];
   grid.gantt = project;
   grid.ganttCalendars = calendars;
   grid.ganttDependencies = dependencies;
   grid.columns = [
     createDefaultTaskTableColumn('wbs'),
     createDefaultTaskTableColumn('name'),
     createDefaultTaskTableColumn('startDate'),
     createDefaultTaskTableColumn('duration'),
     createDefaultTaskTableColumn('percentDone'),
     createDefaultTaskTableColumn('predecessors'),
   ];

   host.appendChild(grid);
   grid.source = tasks;

   // Call when the hosting view is destroyed.
   const dispose = () => grid.remove();
   ```

  Open the runnable <a href="https://demo.rv-grid.com/gantt-basic/ts">Vanilla TypeScript demo</a> to inspect every source file.

Next, continue with the [Gantt tutorial](/guides/gantt/tutorial/) or read the [data model](/guides/gantt/concepts/data-model/).

---

# Gantt Quick Start — Vue 3

URL: https://pro.rv-grid.com/guides/gantt/introduction/vue/
Source: src/content/docs/guides/gantt/introduction/vue.mdx
Description: Build a reactive RevoGrid Gantt project in Vue 3 with the official wrapper, project collections, and managed task columns.
Surface: gantt

1. Complete [installation](/guides/gantt/introduction/installation/) for Vue 3.

2. Create a Vue component. Bind Gantt objects with Vue property bindings; do not serialize them as HTML attributes.

   ```vue
   <template>
     <RevoGrid
       class="project-gantt"
       :plugins="plugins"
       :gantt.prop="project"
       :gantt-calendars.prop="calendars"
       :gantt-dependencies.prop="dependencies"
       :columns="columns"
       :source="tasks"
     />
   </template>

   <script setup lang="ts">
   import { ref } from 'vue';
   import RevoGrid from '@revolist/vue3-datagrid';
   import {
     GanttPlugin,
     createDefaultTaskTableColumn,
     type CalendarEntity,
     type DependencyEntity,
     type GanttPluginConfig,
     type GanttTaskSourceRow,
   } from '@revolist/gantt';

   import '@revolist/revogrid-pro/dist/revogrid-pro.css';
   import '@revolist/gantt/styles.css';

   const plugins = [GanttPlugin];
   const project = ref<GanttPluginConfig>({
     id: 'website-launch', name: 'Website launch', version: '1', currency: 'USD',
     timeZone: 'UTC', primaryCalendarId: 'standard',
     updatedAt: '2026-07-14T00:00:00.000Z', zoomPreset: 'day-week',
   });
   const calendars = ref<CalendarEntity[]>([{
     id: 'standard', name: 'Standard', timeZone: 'UTC',
     workingDays: [1, 2, 3, 4, 5], holidays: [], hoursPerDay: 8,
   }]);
   const tasks = ref<GanttTaskSourceRow[]>([
     { id: 'design', name: 'Design', startDate: '2026-07-14', duration: 3, percentDone: 50, calendarId: 'standard' },
     { id: 'build', name: 'Build', startDate: '2026-07-17', duration: 5, percentDone: 0, calendarId: 'standard' },
   ]);
   const dependencies = ref<DependencyEntity[]>([{
     id: 'design-to-build', predecessorTaskId: 'design', successorTaskId: 'build', type: 'FS', lagDays: 0,
   }]);
   const columns = ref([
     createDefaultTaskTableColumn('wbs'),
     createDefaultTaskTableColumn('name'),
     createDefaultTaskTableColumn('startDate'),
     createDefaultTaskTableColumn('duration'),
     createDefaultTaskTableColumn('percentDone'),
     createDefaultTaskTableColumn('predecessors'),
   ]);
   </script>

   <style>
   .project-gantt { display: block; width: 100%; height: 640px; }
   </style>
   ```

  Open the runnable <a href="https://demo.rv-grid.com/gantt-basic/vue">Vue demo</a> for the complete application source.

Continue with the [Gantt tutorial](/guides/gantt/tutorial/) and [application state guide](/guides/gantt/features/application-state/).

---

# What Is A Gantt Chart?

URL: https://pro.rv-grid.com/guides/gantt/introduction/what-is-gantt/
Source: src/content/docs/guides/gantt/introduction/what-is-gantt.mdx
Description: Core concepts used by the standalone RevoGrid Gantt package.
Surface: gantt

> **Gantt = structured timeline for tasks with dependencies**

A **Gantt chart** is a **visual representation of a plan over time**. It’s a way to show tasks, their durations, and how they relate to each other on a timeline.

It answers only three things:

* **What** tasks exist
* **When** they happen
* **In what order / relation** they happen

---

## Core features of a pure Gantt

#### 1. Task model

Each task has:

* id
* start date
* end date (or duration)
* optional parent (hierarchy)

👉 This is the **data backbone**

---

#### 2. Timeline rendering

* Horizontal time axis
* Tasks rendered as bars
* Zoom levels (day / week / month)

👉 Without this, it’s not a Gantt

---

#### 3. Dependencies (defining feature)

Tasks can depend on each other:

* Finish → Start
* Start → Start
* Finish → Finish

👉 This is what makes it a **planning tool**, not just visualization

---

#### 4. Hierarchy (WBS — work breakdown structure)

* Parent / child tasks
* Expand / collapse

👉 Lets you represent real projects, not flat lists

---

#### 5. Direct manipulation

* Drag task → change start date
* Resize → change duration

👉 If this is missing → it's just a chart, not a planning tool

---

#### 6. Milestones

* Tasks with zero duration
* Represent key events

👉 Needed for any serious usage

---

#### 7. Progress (basic tracking)

* % completion per task
* Visual overlay on bars

👉 Not scheduling — just status

---

#### 8. Large data handling

* Thousands of tasks
* Smooth scroll
* Virtualization

👉 This is our competitive edge

---

## What is NOT part of Gantt (important boundary)

❌ Assigning people to time slots
❌ Calendar conflicts
❌ Shift planning
❌ Workforce shift-slot scheduling across personnel calendars

👉 That’s **scheduler territory** layered on top of Gantt fundamentals

---

## Mental model **“Grid-first Gantt”**

A Gantt is:

```text
Hierarchy (tree)
+ Timeline (x-axis)
+ Dependencies (graph edges)
```

* Left side = grid (tasks, editable)
* Right side = timeline (bars)

---

# Accessibility And Keyboard Navigation

URL: https://pro.rv-grid.com/guides/gantt/production/accessibility/
Source: src/content/docs/guides/gantt/production/accessibility.mdx
Description: Build accessible Gantt workflows with RevoGrid keyboard navigation, semantic task data, visible focus, and equivalent editing controls.
Surface: gantt

Gantt inherits grid-cell focus, selection, editing, and keyboard navigation from RevoGrid. Timeline gestures supplement those workflows; they must not be the only way to change or inspect a task.

## Application Checklist

- Provide meaningful task, resource, column, and toolbar labels.
- Keep focus outlines visible and meet contrast requirements in custom task-bar colors.
- Expose move, resize, progress, dependency, and hierarchy actions through task-table fields, menus, or application controls in addition to pointer gestures.
- Keep the packaged task editor available when complex fields cannot be edited comfortably inline.
- Preserve expected Tab, Enter, Escape, and arrow-key behavior in custom editors.
- Announce validation errors next to the affected input and keep canceled edits focused.
- Do not place essential information only in color, hover tooltips, or dependency geometry.

## Custom Content

When using `taskBarContentHook` or custom cell templates, return concise visible content and keep the task name available in the task table. Custom toolbar buttons need native button semantics, accessible names, and pressed state where applicable.

Test Gantt with keyboard-only navigation, browser zoom, high contrast, and a screen reader in the frameworks your application supports. See [Task Editing](/guides/gantt/interaction/task-editing/) and [Visual Configuration](/guides/gantt/customization/visuals/).

---

# Localization And Date Formatting

URL: https://pro.rv-grid.com/guides/gantt/production/localization/
Source: src/content/docs/guides/gantt/production/localization.mdx
Description: Localize Gantt labels and consistently format task-table, tooltip, editor, and timeline dates.
Surface: gantt

`gantt.labels` localizes packaged option labels, while `gantt.dateFormats` controls date display and parsing across the task table, tooltips, editor, and timeline.

```ts
grid.gantt = {
  ...project,
  labels: {
    taskMode: { auto: 'Automatisch', manual: 'Manuell' },
    status: {
      complete: 'Abgeschlossen',
      'on-schedule': 'Im Plan',
      late: 'Verspätet',
      'future-task': 'Zukünftig',
    },
    workflowStatus: {
      'not-started': 'Nicht begonnen',
      'in-progress': 'In Arbeit',
      done: 'Erledigt',
      blocked: 'Blockiert',
    },
  },
  dateFormats: {
    locale: 'de-DE',
    timeZone: 'Europe/Berlin',
    table: { day: '2-digit', month: '2-digit', year: 'numeric' },
    tooltip: { dateStyle: 'medium' },
  },
};
```

Task values remain ISO date or UTC ISO date-time strings. Formatting changes presentation, not persisted data. When an editor uses a non-ISO text format, provide both a formatter and parser so submitted values return to the supported ISO contract.

Use one project time zone, explicit calendar time zones, and UTC date-time values when hour/minute precision matters. See [Configuration Reference](/guides/gantt/reference/configuration-reference/#date-formatting) for callback contexts and parsing rules.

---

# Performance And Large Projects

URL: https://pro.rv-grid.com/guides/gantt/production/performance/
Source: src/content/docs/guides/gantt/production/performance.mdx
Description: Keep large Gantt projects responsive by preserving virtualization, stable inputs, bounded visual layers, and measured scheduling work.
Surface: gantt

RevoGrid virtualizes the task table and timeline projection. Preserve that advantage by updating project data through public collections rather than rendering parallel task DOM or reading state back from cells.

## Recommendations

- Use stable task and linked-entity IDs.
- Replace only collections that changed and keep wrapper inputs memoized or reactive at the correct boundary.
- Batch related task, dependency, calendar, resource, and assignment changes before triggering a new schedule pass.
- Keep custom cell and task-bar renderers pure and inexpensive.
- Limit visible marker and time-range overlays to information users need in the active view.
- Prefer column presets over rendering every analytical field at once.
- Measure scheduling separately from browser rendering with the Gantt scheduler benchmark, and use the browser benchmark for end-to-end interaction evidence.
- Test representative hierarchy depth, dependency density, resource assignments, and timeline span—not only row count.

## Current Boundary

Virtual rendering is implemented. A server-side, date-windowed Gantt project model is not currently part of the public contract, so the complete linked project graph must be available to the client scheduler. See [Limitations](/guides/gantt/reference/limitations/) before designing very large remote projects.

## Two benchmark layers

The Gantt scheduler benchmark isolates scheduling-engine recalculation in Node.js. It does not measure browser rendering, scrolling, pointer interactions, hierarchy projection, memory, or mounted DOM.

Run the scheduler benchmark with:

```bash
pnpm --filter @revolist/gantt bench
```

For the reproducible browser suite, raw JSON/CSV, exact environment, screenshot, video, and live workload, open the [RevoGrid Gantt browser benchmark](https://rv-grid.com/benchmarks/gantt). Its published matrix covers 100, 1,000, 5,000, and 10,000 tasks across sparse, normal, and highly connected dependency graphs, with one warm-up and five measured runs per isolated scenario.

The browser suite leads with the measurable capacity claim “10,000 editable tasks and 19,796 dependencies in a live browser demo.” It does not make a “fastest” claim or compare numbers collected with a different harness.

---

# Responsive And Touch Interaction

URL: https://pro.rv-grid.com/guides/gantt/production/responsive-touch/
Source: src/content/docs/guides/gantt/production/responsive-touch.mdx
Description: Configure layouts that preserve Gantt scrolling, selection, editing, and task handles on phones, tablets, and narrow containers.
Surface: gantt

Gantt uses the same configuration on desktop and coarse-pointer devices. Touch interaction follows a select-then-edit model so ordinary swipes keep scrolling the task table or timeline.

- Tap a task bar to select it and reveal larger move, resize, progress, dependency, and split handles.
- Drag a selected bar or visible handle to edit.
- Keep the task table wide enough for at least the task name and one scheduling field.
- Allow the Gantt container to shrink with `min-width: 0` inside flex and grid layouts.
- Use a fixed, viewport-derived, or parent-derived height; do not rely on content height.
- The packaged task editor becomes single-column and full-viewport on narrow screens.

```css
.gantt-shell {
  display: grid;
  grid-template-rows: auto minmax(0, 1fr);
  min-width: 0;
  height: min(760px, calc(100vh - 8rem));
}

.gantt-shell revo-grid {
  display: block;
  min-width: 0;
  height: 100%;
}
```

Do not add page-level touch handlers that compete with Gantt pointer handling. Place application toolbars outside the scrollable grid container and verify edge swipes on unselected bars do not mutate tasks.

---

# SSR And Client Rendering

URL: https://pro.rv-grid.com/guides/gantt/production/ssr/
Source: src/content/docs/guides/gantt/production/ssr.mdx
Description: Integrate RevoGrid Gantt with server-rendered applications while keeping custom-element registration and browser APIs client-only.
Surface: gantt

The scheduling data model is framework-neutral, but the Gantt grid renders in the browser. Register custom elements, access `document` or `window`, and mount the grid only on the client.

## Integration Rules

- Render a stable-height placeholder during SSR to avoid layout shift.
- Dynamically import the wrapper or Gantt component with SSR disabled.
- Call `defineCustomElements()` only in a browser entry or client lifecycle.
- Keep project data serializable across the server/client boundary.
- Do not create the grid during module evaluation in code that also runs on the server.
- Clean up listeners and element instances when client-side routes unmount.

```ts
if (typeof window !== 'undefined') {
  const { defineCustomElements } = await import('@revolist/revogrid/loader');
  defineCustomElements();
}
```

For React meta-frameworks, dynamically load the component client-side. For Vue/Nuxt use a client-only boundary. For Angular SSR, guard browser-only setup with the platform check used by your application.

The [Vanilla quick start](/guides/gantt/introduction/vanilla-typescript/) shows explicit mount and cleanup; the wrapper quick starts show property binding after hydration.

---

# Configuration Reference

URL: https://pro.rv-grid.com/guides/gantt/reference/configuration-reference/
Source: src/content/docs/guides/gantt/reference/configuration-reference.mdx
Description: Human-readable map of public Gantt config objects.
Surface: gantt

Public config entry points:

- `GanttPluginConfig`
  - `weekStartsOn?: 0 | 1` controls week header/tick alignment. Omit for Sunday (`0`); set `1` for Monday.
  - `timelinePrecision?: 'day' | 'hour'` controls the default precision for timeline task create, move, and resize interactions. Use `'hour'` with `zoomPreset: 'hour-day'` or `zoom.defaultLevelId: 'hour-day'` for hour-scale planning.
  - `snap?: { unit?: 'day' | 'hour'; workingTime?: boolean }` controls interaction snapping. `unit: 'hour'` keeps interactions on hour boundaries; `workingTime: true` or omitted skips holidays, closed weekdays, and closed `calendar.workingHours`.
  - `calendars?: CalendarEntity[]` can include intraday `workingHours` such as `{ start: '09:00', end: '17:00' }` plus `hoursPerDay` for hour-mode snapping and scheduling.
  - `durationSettings?: DurationSettings` controls the fixed/automatic display unit, compact display precision through `maximumFractionDigits` (default `1`), and conversions through `hoursPerDay`, `hoursPerWeek`, and `daysPerMonth`. See [Duration Units and Conversion](/guides/gantt/scheduling/durations/).
  - `fields?: ViewFieldMap` maps shared view meanings to properties in each authored task row. See [Task source field mapping](#task-source-field-mapping).
  - `allowedTaskTypes?: TaskType[]` restricts the choices in packaged Task Type column and dialog editors. Omit it to allow `task`, `milestone`, and `summary`; use `['task']` to prevent users from converting tasks to milestones or summaries.
  - `labels?: GanttLabelsConfig` customizes option labels, validation errors, scheduler warnings, and task-editor text from one project-level object. See [Labels, Errors, and Warnings](#labels-errors-and-warnings).
  - `dateFormats?: GanttDateFormatConfig` controls task-table, tooltip, editor, and timeline date presentation and parsing. See [Date Formatting](#date-formatting).
  - `visuals.percentDoneMode?: 'number' | 'bar' | 'circle'` controls the project default for the managed `% Done` task-table cell. It defaults to `bar`; `{ prop: 'percentDone', mode: 'circle' }` overrides it per column. See [Actuals and Progress](/guides/gantt/scheduling/progress/#percent-done-column-mode).
  - `taskCreateRow?: boolean` shows an opt-in pinned bottom “Add new task” row. It requires `allowTaskCreate: true` and is hidden for read-only or resource-planning views. See [Add Task Row](/guides/gantt/interaction/add-task-row/) for `GanttAddTaskRowPlugin` behavior and `isGanttAddTaskRow()` usage.
- `GanttSchedulingConfig`
- `GanttResourcePlanningConfig`
- `GanttVisualConfig`

## Task Source Field Mapping

Gantt uses the shared `ViewFieldMap` names also used by Scheduler and Kanban. The mapping values are property names in `grid.source`:

| Meaning | Gantt default |
| --- | --- |
| `id` | `id` |
| `title` | `name` |
| `status` | `workflowStatus` |
| `start` | `startDate` |
| `end` | `endDate` |
| `color` | `color` |
| `progress` | `percentDone` |

This lets one application record shape feed several views:

```ts
grid.gantt = {
  ...project,
  fields: {
    id: 'id',
    title: 'name',
    status: 'workflowStatus',
    start: 'startDate',
    end: 'endDate',
    color: 'color',
    progress: 'percentDone',
    resourceId: 'owner',
  },
};
```

The mapping changes property names only. Date and duration parsing, progress units, validation, and scheduling behavior stay the same. Gantt writes accepted task changes back with the authored property names and preserves unrelated row fields. `resourceId` is accepted so the mapping object can be shared, and its source value is preserved; Gantt resource scheduling continues to use `ganttAssignments`, where a task can have multiple assignments.

## Duration Settings

`durationSettings.defaultUnit` and `defaultWorkUnit` accept every `DurationUnit` or `'auto'`. Duration, Remaining Duration, and Work are stored as hours. `defaultUnit` controls task-span quantities while `defaultWorkUnit` independently controls Work; task `durationUnit` and `workUnit` win. `auto` displays sub-hour values as minutes, sub-day values as hours, and longer values as days without changing stored task data.

```ts
grid.gantt = {
  ...project,
  durationSettings: {
    defaultUnit: 'auto',
    defaultWorkUnit: 'hour',
    hoursPerDay: 8,
    hoursPerWeek: 40,
    daysPerMonth: 20,
  },
};
```

See [Duration Units and Conversion](/guides/gantt/scheduling/durations/) for mixed task units, flexible input, elapsed durations, defaults, and conversion behavior.

## Labels, Errors, and Warnings

Use `gantt.labels` as the project-level localization and message catalog. Error and warning overrides can be strings or formatter functions. The plugin keeps the existing result contract—such as `{ field, code, message }`—and changes only the resolved `message`.

```ts
grid.gantt = {
  ...project,
  labels: {
    errors: {
      taskEdit: {
        invalidRemainingDuration:
          'Remaining duration must be a value such as 5h, 2d, 3w, or 30m.',
      },
      taskEditor: {
        invalidRemainingDuration: 'Enter remaining time in hours or days.',
      },
      dependency: {
        taskReferenceNotFound: ({ value }) => `No task matches "${value}".`,
      },
    },
    warnings: {
      scheduler: {
        deadlineMissed: ({ taskId, date }) =>
          `Task ${taskId} missed its ${date} deadline.`,
      },
    },
    taskEditor: {
      applyLabel: 'Apply changes',
      status: {
        saveFailed: 'The task could not be saved.',
      },
    },
  },
};
```

Message groups identify the runtime surface: `taskEdit` for managed grid-cell edits, `taskMutation` for task operations and timeline interactions, `assignment`, `dependency`, and `taskEditor`. Scheduler issues and conflicts use `warnings.scheduler`. The exported `DEFAULT_GANTT_ERROR_LABELS` and `DEFAULT_GANTT_WARNING_LABELS` constants contain every supported key and the default English text.

The task-editor dialog inherits `gantt.labels.taskEditor`. A dialog-specific `localeText` option remains supported and takes precedence over the inherited project labels, which allows one editor instance to override selected text without duplicating the rest of the project locale.

## Date Formatting

Managed Gantt date columns display a localized medium date by default (for example, `Apr 6, 2026` with the default `en-US` locale). This applies consistently to Start, End, Actual Start/Finish, Early/Late Start/Finish, Constraint Date, and Deadline. ISO date-time task values such as `2026-04-06T09:00:00.000Z` remain unchanged in your data; only their cell display is formatted, and the default table display intentionally omits the time.

Set `gantt.dateFormats.locale`, `timeZone`, and `table` to choose your own project-wide table format. `table` accepts standard `Intl.DateTimeFormatOptions`:

```ts
grid.gantt = {
  ...project,
  dateFormats: {
    locale: 'en-GB',
    timeZone: 'Europe/London',
    table: {
      day: '2-digit',
      month: '2-digit',
      year: 'numeric',
    },
  },
};
```

For field-specific or application-defined output, provide a formatter callback. The context includes the managed field name, locale, time zone, and surface:

```ts
grid.gantt = {
  ...project,
  dateFormats: {
    table: (value, context) => {
      const date = new Date(value.length === 10 ? `${value}T00:00:00Z` : value);
      const prefix = context.field === 'deadlineDate' ? 'Due ' : '';

      return `${prefix}${new Intl.DateTimeFormat('de-DE', {
        day: '2-digit',
        month: 'short',
        year: 'numeric',
        timeZone: context.timeZone,
      }).format(date)}`;
    },
  },
};
```

Use `dateFormats.tooltip` and `dateFormats.timeline` for those surfaces. If editor text must use a non-ISO format, pair `dateFormats.editor.formatter` with `dateFormats.editor.parser` (or the shared `dateFormats.parser`) so edits are converted back to ISO date or UTC ISO date-time values before scheduling.

## Adaptive Mobile Interactions

Gantt automatically adapts pointer interactions for phones, tablets, and other coarse-pointer devices. There is no mobile-only configuration flag; the same `GanttPluginConfig` works across desktop and touch devices.

Mobile behavior is designed around **select-then-edit**:

- Mouse and trackpad users keep direct desktop interactions for moving, resizing, progress updates, dependency drawing, timeline panning, and split-panel resizing.
- Touch users tap a task bar first to select it and reveal larger resize, progress, dependency, and split handles.
- Dragging a selected task bar moves the task. Dragging a visible handle resizes, updates progress, edits splits, or creates dependencies.
- Plain touch scrolling in the task table or timeline remains scroll-first and should not move, resize, or create tasks accidentally.
- Hidden coarse-pointer handles are not hit-testable until the task is selected or interaction-active, so an edge swipe on an unselected task still behaves like navigation.
- Task editor dialogs switch to a single-column, full-viewport layout on narrow screens with larger controls for touch input.

The Gantt E2E suite includes a dedicated mobile project using an iPhone viewport. It verifies that unselected task-bar swipes do not mutate dates, tapping selects a task and exposes handles, and the task editor dialog fits a phone-sized viewport.

Canonical definitions:

- `packages/gantt/src/gantt/grid/gantt-plugin.types.ts`

For generated signatures, see [API: Gantt](/api/gantt/).

---

# Gantt Capability Coverage

URL: https://pro.rv-grid.com/guides/gantt/reference/coverage/
Source: src/content/docs/guides/gantt/reference/coverage.mdx
Description: Coverage matrix connecting supported Gantt capabilities to customer guides, public API areas, and runnable examples.
Surface: gantt

Use this matrix to move from a supported capability to its explanation, public contract, and—where behavior is visual or interactive—a runnable example. A missing example means the capability is configuration or integration guidance that does not benefit from a separate visual demo.

The matrix covers capabilities documented as supported by the current `@revolist/gantt` package. It deliberately does not imply support for capabilities that exist only in other Gantt products.

---

# Events And Methods

URL: https://pro.rv-grid.com/guides/gantt/reference/events-methods/
Source: src/content/docs/guides/gantt/reference/events-methods.mdx
Description: Use Gantt lifecycle events to validate changes and call public plugin methods for tasks, zoom, baselines, hierarchy, and snapshots.
Surface: gantt

['Project lifecycle', 'applyGantt|clearGantt|getProjectSnapshot'],
  ['Zoom and range', 'zoomIn|zoomOut|setZoomLevel|getZoomLevel|canZoomIn|canZoomOut|getVisibleRange'],
  ['Tasks', 'createTask|updateTask|finalizeTaskCreate|discardTaskCreate'],
  ['Hierarchy', 'indentTask(s)|outdentTask(s)|deleteTask(s)|convertTask(s)ToMilestones'],
  ['Baselines', 'captureBaseline'],
];

  ['gantt-before-task-change', 'Before create, move, resize, edit, progress, split, indent, outdent, delete, or milestone conversion.'],
  ['gantt-before-dependency-change', 'Before dependency create, delete, edit, or set replacement.'],
  ['gantt-before-assignment-change', 'Before task assignments are edited.'],
];

## Get The Plugin

Outside plugin code, locate the runtime through the grid's plugin collection.

```ts
import { GanttPlugin } from '@revolist/gantt';

const plugins = await grid.getPlugins();
const gantt = plugins.find((plugin) => plugin instanceof GanttPlugin);
```

Do not install reverse callbacks or custom methods directly on the grid element.

## Public Method Groups

Use the [Gantt API](/api/gantt/) for exact signatures and return types.

## Cancelable Before-Change Events

Call `preventDefault()` to reject a proposed packaged mutation.

```ts
grid.addEventListener('gantt-before-task-change', (event) => {
  if (!canEditTask(event.detail.taskId, event.detail.action)) {
    event.preventDefault();
  }
});
```

## Collect Committed Changes

Gantt publishes successful task, dependency, and assignment mutations through EventManager's existing `gridedit` event. This gives persistence and audit integrations one committed-change stream for grid edits and Gantt interactions such as moving, resizing, changing progress, editing hierarchy, and deleting tasks.

```ts
grid.addEventListener('gridedit', (event) => {
  for (const change of event.detail.domainChanges ?? []) {
    if (change.type === 'gantt-task') {
      if (change.detail.task) saveTask(change.detail.task);
    }
  }
});
```

Use `event.detail.eventTypes` to detect `gantt-task-change`, `gantt-dependency-change`, or `gantt-assignment-change`. `domainChanges` preserves the committed changes in order and includes previous and current domain state. Bulk operations and scheduler cascades include every affected task.

`data`, `previousData`, and `models` keep the normal grid row/field shape. Stable task-row updates appear there exactly like other grid edits; dependencies, assignments, creates, deletes, and reorders that do not have a safe row coordinate stay in `domainChanges`. Replay-only project snapshots are stored separately in `history` and are never mixed into grid fields.

Cancellation belongs to the corresponding `gantt-before-*-change` event. A Gantt change in `gridedit` has already committed, so calling `preventDefault()` there does not roll it back. When EventManager collection is enabled, consecutive Gantt mutations are emitted as one collected transaction and one history step.

## Commands And Notifications

The grid also uses typed events for task creation/edit requests, hierarchy commands, zoom, search, dependency hover/selection, task-created notification, and panel resize. Prefer exported event constants when code must be refactor-safe.

```ts
import {
  GANTT_TASK_CREATE_EVENT,
  GANTT_ZOOM_IN_EVENT,
} from '@revolist/gantt';

grid.dispatchEvent(new CustomEvent(GANTT_TASK_CREATE_EVENT));
grid.dispatchEvent(new CustomEvent(GANTT_ZOOM_IN_EVENT));
```

Application listeners should update or validate project data, not query rendered task-bar geometry. See [Application State](/guides/gantt/features/application-state/) for persistence ownership.

---

# Limitations And MSP Differences

URL: https://pro.rv-grid.com/guides/gantt/reference/limitations/
Source: src/content/docs/guides/gantt/reference/limitations.mdx
Description: Current Gantt scheduling boundaries and intentional differences.
Surface: gantt

Implemented behavior is MSP-inspired, not full MSP parity.

Current boundaries:

- Auto-leveling is forward-schedule oriented; backward mode stays warning-only.
- Leveling is delay-based and does not auto-insert new split ranges.
- Constraint and validation coverage is deterministic but narrower than full MSP option matrix.
- Docs describe current code behavior in `packages/gantt/src/gantt`, not aspirational features.

---

# Troubleshooting

URL: https://pro.rv-grid.com/guides/gantt/reference/troubleshooting/
Source: src/content/docs/guides/gantt/reference/troubleshooting.mdx
Description: Common Gantt setup and scheduling issues.
Surface: gantt

Common checks:

- Missing `ganttCalendars` or mismatched `calendarId`.
- Duplicate IDs in tasks/dependencies/resources/assignments.
- Dependency points to missing task ID.
- A circular dependency chain such as `Setup load balancer -> Configure firewall -> Setup load balancer`. The scheduler reports this as `dependency-cycle`; inspect the issue's `taskIds` and `dependencyIds`, then remove or change one of the links.
- Invalid task date ranges or malformed constraints.
- No visible timeline because viewport/zoom span does not include task dates.

## Task Jumps While Dragging

If a task appears to jump during drag or resize, first check for dependency validation issues. Automatic tasks normally clamp to the earliest date allowed by their predecessors. A circular dependency cannot produce a valid predecessor order, so RevoGrid reports `dependency-cycle` and leaves dependency clamping disabled until the cycle is fixed.

Use the scheduling result passed to your diagnostics flow to locate the invalid links:

```ts
const cycleIssue = schedulerResult.issues.find((issue) => issue.code === 'dependency-cycle');

if (cycleIssue) {
  console.table({
    tasks: cycleIssue.taskIds.join(', '),
    dependencies: cycleIssue.dependencyIds.join(', '),
  });
}
```

Validation and diagnostics are produced by:

- `engine/scheduler-engine/validation.ts`
- `engine/scheduler-types.ts`

---

# Gantt Upgrades

URL: https://pro.rv-grid.com/guides/gantt/releases/
Source: src/content/docs/guides/gantt/releases/index.mdx
Description: Upgrade guidance for standalone RevoGrid Gantt integrations.
Surface: gantt

Use the [Gantt migration guide](./migration/) when upgrading `@revolist/gantt`.

It covers package alignment, public imports, scheduling regression fixtures, application events, persistence, task-table columns, and timeline visuals.

The current public contract is documented in the [Gantt API reference](/api/gantt/). This documentation does not maintain release snapshots or generated API comparisons.

---

# Gantt Migration Guide

URL: https://pro.rv-grid.com/guides/gantt/releases/migration/
Source: src/content/docs/guides/gantt/releases/migration.mdx
Description: Upgrade a standalone RevoGrid Gantt integration using stable imports, project data, events, and application-level regression checks.
Surface: gantt

Use this checklist when upgrading `@revolist/gantt`.

1. Upgrade Gantt, Pro, the framework wrapper, and RevoGrid together.
2. Run the application against the documented package version shown on this page.
3. Replace repository-relative imports with the public package barrel.
4. Review the current [Gantt API reference](/api/gantt/) for exported contracts and deprecations.
5. Re-run schedule fixtures containing dependencies, calendars, constraints, resources, baselines, and manual tasks.
6. Verify cancelable `gantt-before-*` policies and persistence callbacks.
7. Check task-table columns and timeline visuals in each supported breakpoint.

```sh
pnpm up @revolist/gantt @revolist/revogrid-pro @revolist/revogrid
```

For a 1.x-to-2.x repository migration outside Gantt, also read the [general v2 migration guide](/guides/migration-v2/).

---

# Resource Planning View

URL: https://pro.rv-grid.com/guides/gantt/resources/resource-planning-view/
Source: src/content/docs/guides/gantt/resources/resource-planning-view.mdx
Description: Visualize resource-centric timelines and daily/weekly load bars.
Surface: gantt

The Resource Planning View switches the Gantt chart from a task-centric WBS to a resource-centric view. This allows managers to visualize daily or weekly load, capacity thresholds, and over-allocation hotspots.

Resource names include a compact avatar for faster scanning. Gantt derives a colored initials avatar from the resource name by default; supply `avatarUrl` on a resource to render its profile image instead.

## Enabling the Planning View

Use `gantt.resourcePlanning` to toggle the view and configure its behavior:

```typescript
grid.gantt = {
  resourcePlanning: {
    enabled: true,
    visibleResourceIds: ['alex', 'nina', 'ravi'],
    loadGranularity: 'day',
    capacityDisplay: 'line',
    overAllocationDisplay: 'highlight',
  },
};
```

```typescript
grid.ganttResources = [{
  id: 'alex',
  name: 'Alex Morgan',
  avatarUrl: '/images/team/alex-morgan.png',
  role: 'Lead Engineer',
  calendarId: 'standard',
  allocationCapacity: 100,
  hourlyCost: 120,
}];
```

### Configuration Options

| Option | Description |
|---|---|
| `enabled` | Toggle between task rows and resource load rows. |
| `visibleResourceIds` | Array of resource IDs to display in the planning view. |
| `loadGranularity` | `'day'` or `'week'`. The time bucket for load calculation. |
| `capacityDisplay` | `'line'` or `'none'`. Renders a capacity threshold on load bars. |
| `overAllocationDisplay` | `'highlight'` or `'none'`. Marks buckets exceeding capacity. |

## Resource Filtering

When you are in the normal task view, you can use `resourceFilterIds` to filter tasks assigned to specific resources while keeping ancestor summary tasks visible. This provides context-aware filtering within the project structure.

```typescript
grid.gantt = {
  resourceFilterIds: ['alex'],
};
```

  The Resource Planning View is highly dynamic. Changes to task dates or assignment units on the main grid are immediately reflected in the resource load bars.

---

# Resources and Assignments

URL: https://pro.rv-grid.com/guides/gantt/resources/resources-and-assignments/
Source: src/content/docs/guides/gantt/resources/resources-and-assignments.mdx
Description: Define resource capacity, assignments, and how they interact with task work.
Surface: gantt

Resources define the people, equipment, or facilities that perform work on your tasks. Assignments connect these resources to specific tasks with defined allocation units and work hours.

## Data Model

Resources and assignments are managed through two distinct collections:

```typescript
grid.ganttResources = [{
  id: 'alex',
  name: 'Alex',
  role: 'Engineer',
  calendarId: 'cal-standard',
  allocationCapacity: 100, // 100% capacity
  hourlyCost: 120,
}];

grid.ganttAssignments = [{
  id: 'assign-1',
  taskId: 'task-1',
  resourceId: 'alex',
  allocationUnits: 100, // 100% assignment
  workHours: 40,
  responsibility: 'Owner',
}];
```

### Capacity and Units
`allocationCapacity` and `allocationUnits` accept either a percent scale (`100`) or a decimal scale (`1.0`) for full capacity. The scheduling engine uses these values to calculate resource load and identify over-allocations.

## Resource Over-Allocation

When the `resourceLeveling` policy is set to `'warn'`, the scheduler calculates allocation by resource and working date. If assigned units exceed the resource's capacity on any given day, it reports a `resource-overallocation` conflict.

```typescript
grid.gantt = {
  scheduling: { resourceLeveling: 'warn' },
};
```

### Example: Over-Allocation Warning

If one resource is assigned to multiple overlapping tasks at 100% each, a warning will be triggered:

```typescript
grid.ganttResources = [{
  id: 'alex',
  name: 'Alex',
  allocationCapacity: 100,
}];

grid.ganttAssignments = [
  { taskId: 'build', resourceId: 'alex', allocationUnits: 100 },
  { taskId: 'docs', resourceId: 'alex', allocationUnits: 100 },
];
```

**Expected result**: On days where `build` and `docs` overlap, Alex is allocated at 200%. Each affected task receives a `resource-overallocation` warning in the grid and on the timeline.

---

## Next Steps
- **[Resource Planning View](../resource-planning-view)**: Visualize resource load on a dedicated timeline.
- **[Resource Leveling](../scheduling/leveling)**: Automatically resolve over-allocations by delaying tasks.
- **[Effort Modes](../scheduling/effort-modes)**: Control how assignments affect task duration.

---

# Calendars and Duration

URL: https://pro.rv-grid.com/guides/gantt/scheduling/calendars/
Source: src/content/docs/guides/gantt/scheduling/calendars.mdx
Description: Define working days, holidays, and how they affect task duration calculations.
Surface: gantt

`duration` is stored in hours and can be displayed or entered as minutes, hours, days, weeks, months, quarters, or years. Unit conversion uses `durationSettings` and the effective calendar; see [Duration Units and Conversion](/guides/gantt/scheduling/durations/). Enable calendar exclusion when weekends, holidays, and closed hours should be skipped:

```typescript
grid.gantt = {
  scheduling: {
    excludeHolidaysFromDuration: true,
  },
};
```

## Defining Calendars

Calendars use ISO weekday numbers where Monday is `1` and Sunday is `7`:

```typescript
grid.ganttCalendars = [{
  id: 'cal-standard',
  name: 'Standard',
  timeZone: 'UTC',
  workingDays: [1, 2, 3, 4, 5],
  holidays: ['2026-05-25'],
  hoursPerDay: 8,
}];
```

Each task references a calendar through `calendarId`. Resource capacity checks use the resource calendar when a resource is assigned.

`CalendarEntity.hoursPerDay` is the default conversion for task durations on that calendar. Project `durationSettings.hoursPerDay` can override it globally. Conversion settings do not change `workingDays`, `holidays`, or `workingHours` automatically.

## Working-Day Lag

Use working-day lag when dependency offsets should skip weekends and holidays:

```typescript
grid.gantt = {
  scheduling: {
    lagCalendar: 'working-days',
  },
};
```

**Example**: A one-day lag after a Friday skips the weekend and a Monday holiday, landing on Tuesday.

  Each task references a calendar via its `calendarId` field. Tasks on different calendars respect their own working days and holidays independently.

---

# MSP Compatibility

URL: https://pro.rv-grid.com/guides/gantt/scheduling/compatibility/
Source: src/content/docs/guides/gantt/scheduling/compatibility.mdx
Description: Understand how RevoGrid Gantt maps to Microsoft Project scheduling concepts and behavior.
Surface: gantt

The table below describes how RevoGrid Gantt maps to Microsoft Project (MSP) concepts. This ensures a familiar experience for planners transitioning from desktop project management tools.

| MSP concept | RevoGrid Gantt behavior |
|---|---|
| Manual vs automatic task mode | `taskMode: 'manual'` preserves authored dates and warns on dependency violations. Auto tasks are dependency-safe and are clamped to valid dates. |
| Scheduled Start / Finish | `startDate` and `endDate` in the rendered row are the scheduler's effective dates. For manual tasks, authored dates remain unless a warning is reported. |
| ASAP / ALAP | `scheduleFrom: 'project-start'` gives ASAP-style forward scheduling. `scheduleFrom: 'project-finish'` gives ALAP-style backward scheduling. |
| Dependencies | FS, SS, FF, and SF dependencies are supported. Positive `lagDays` delays a successor; negative `lagDays` is lead time. |
| Constraints | Six date constraints are supported: SNET, SNLT, FNET, FNLT, MSO, and MFO. |
| Deadlines | `deadlineDate` produces a warning indicator when a task finishes late. It does not move the task, matching MSP's deadline intent. |
| Resource over-allocation | `resourceLeveling: 'warn'` reports capacity violations. `resourceLeveling: 'auto'` performs deterministic delay-based leveling for eligible automatic tasks. |
| Effort/task type | `effortMode` supports `fixed-duration`, `fixed-work`, and `fixed-units`. Fixed-work and fixed-units can derive duration from work hours and assignment units. |
| Actuals and remaining duration | `actualFinishDate` pins completed work. `actualStartDate` and `remainingDuration` pin in-progress work when `progressRescheduling` is enabled. |
| Split tasks | `splitRanges` pause work inside a task span, render visual gaps, and extend the computed finish. |
| Critical path | Critical tasks, critical dependencies, early/late dates, and total slack are recomputed after all scheduling rules. |

  Microsoft Project has more scheduling knobs than this implementation, including status-date rescheduling options, per-resource Can Level, elapsed duration syntax, and automatic split-based leveling. RevoGrid exposes a deterministic subset designed for web-driven scheduling.

## Reference Links

Useful Microsoft Project references for comparison:

- [Task Mode field](https://support.microsoft.com/en-gb/office/task-mode-task-field-3b185518-0e9a-4774-ba51-7b8d191bb84a)
- [Task constraints](https://support.microsoft.com/en-us/office/set-a-task-start-or-finish-date-constraint-for-a-task-3a7544fa-e992-4647-911b-54cdbe508784)
- [Predecessors field and lead/lag](https://support.microsoft.com/en-us/office/predecessors-task-field-5a5ea9c2-14e6-4be7-9a3d-d8b6cba10cab)
- [Deadline field](https://support.microsoft.com/en-us/office/deadline-task-field-8c6c4acd-1324-484a-a92b-9bd2eb313dfa)
- [Resource leveling](https://support.microsoft.com/en-us/office/resource-leveling-dialog-box-0d280b16-2753-4630-8cca-8c50915df9f5)
- [Task types and effort-driven scheduling](https://support.microsoft.com/en-us/office/change-the-effort-driven-setting-for-task-types-18efd7c7-d146-4b06-bdbe-b6a11564bdf3)
- [Actual Start and Actual Finish](https://support.microsoft.com/en-us/office/actual-start-fields-b1b833a7-07f5-4c4d-858d-f9261d1be7f7)
- [Split a task](https://support.microsoft.com/en-au/office/split-a-task-20c8581b-6266-45e3-af54-cc7c3b10deca)
- [Critical path](https://support.microsoft.com/en-us/office/show-the-critical-path-of-your-project-in-project-ad6e3b08-7748-4231-afc4-a2046207fd86)

---

# Task Constraints

URL: https://pro.rv-grid.com/guides/gantt/scheduling/constraints/
Source: src/content/docs/guides/gantt/scheduling/constraints.mdx
Description: Apply explicit date constraints like SNET, MSO, and MFO to control the scheduler's behavior.
Surface: gantt

Constraints are explicit fields on a task that override or refine the automatic forward-pass scheduling:

```typescript
{
  id: 'integration',
  name: 'External Integration',
  constraintType: 'start-no-earlier-than',
  constraintDate: '2026-05-04',
  // other task fields
}
```

## Supported Constraint Types

| Constraint | MSP equivalent | Behavior |
|---|---|---|
| `start-no-earlier-than` | SNET | Start on or after the constraint date. |
| `start-no-later-than` | SNLT | Start on or before the constraint date. |
| `finish-no-earlier-than` | FNET | Finish on or after the constraint date. |
| `finish-no-later-than` | FNLT | Finish on or before the constraint date. |
| `must-start-on` | MSO | Start exactly on the constraint date. |
| `must-finish-on` | MFO | Finish exactly on the constraint date. |

## Soft vs. Hard Constraints

### Soft Constraints (SNET, SNLT, FNET, FNLT)
These constraints define a legal window for the task. If the dependency propagation moves the task outside this window, the scheduler will:
- Adjust the date to the nearest legal bound (if possible).
- Report a `constraint-window-conflict` if the dependency and constraint windows do not overlap.

### Hard Constraints (MSO, MFO)
Hard constraints are authoritative. They pin the task to an exact date, even if it violates dependencies.
- If a dependency requires a different date, the scheduler reports a `hard-constraint-conflict` or `dependency-constraint-conflict`.
- The task date is NOT moved to satisfy the dependency; the constraint wins.

  Microsoft Project also exposes flexible ASAP and ALAP as constraint types. RevoGrid models those at project level with `scheduleFrom`, not as per-task `constraintType` values.

---

# Critical Path and Slack

URL: https://pro.rv-grid.com/guides/gantt/scheduling/critical-path/
Source: src/content/docs/guides/gantt/scheduling/critical-path.mdx
Description: Automatically compute and highlight the critical path — the longest chain of tasks that determines the project end date.
Surface: gantt

The **critical path** is the chain of tasks that controls the calculated project finish date.
In Microsoft Project terms, critical tasks usually have zero total slack: if one slips, the project finish slips.
The Gantt plugin computes this path from the final scheduled graph and highlights it visually.

---

## Enabling Critical Path

Set `showCriticalPath: true` in the `visuals` section of your project config:

```typescript
grid.gantt = {
  visuals: {
    showCriticalPath: true,
  },
};
```

Critical tasks and the dependency arrows connecting them are highlighted in a distinct color (red by default).

## How It Works

The scheduler computes critical path after all scheduling rules (dependencies, constraints, actuals, etc.) have been applied.
It runs a backward pass over the graph to compute:

- **Early Start / Early Finish**: The earliest each task can begin and end.
- **Late Start / Late Finish**: The latest each task can begin and end without delaying the project.
- **Total Slack** = Late Start − Early Start.

| Field | Meaning |
|---|---|
| `earlyStartDate` | Effective scheduled start after all rules are applied. |
| `lateStartDate` | Latest date the task can occupy without delaying the project finish. |
| `totalSlackDays` | Working-day float between early and late dates. |
| `isCritical` | `true` when total slack is zero. |

  Summary tasks are treated as critical when at least one child task is critical. Milestone tasks with no slack also appear on the critical path.

## Dependency Types

All four dependency types (FS, SS, FF, SF) participate in critical path analysis. Lags (`lagDays`) are also factored in. A positive lag delays the successor, while a negative lag (lead time) can reduce the path length.

## MSP Comparison

RevoGrid follows the Microsoft Project model: dependencies and final scheduled dates drive total slack, and tasks with zero slack become critical.
Deadlines and resource leveling also influence the critical path by shifting dates or changing risk profiles.

## Critical State Is Projected

Do not set `isCritical` in `grid.source`. Gantt source rows describe authored task data, while `isCritical`, slack fields, early/late dates, and critical dependency styling are projected by the scheduler on each render.

If an application needs to persist critical-path state, persist the scheduling inputs instead: tasks, dependencies, constraints, calendars, assignments, and scheduling options. RevoGrid will recompute the critical path from those inputs.

## CSS Customization

Critical path styling uses data attributes on bar and arrow elements:

```css
/* Critical task bar */
.gantt-bar[data-critical] {
  --gantt-bar-color: #e53e3e;
}

/* Critical dependency arrow */
.gantt-dependency[data-critical] {
  stroke: #e53e3e;
}
```

See the [Critical path analysis demo](https://demo.rv-grid.com/gantt-critical-path-analysis/ts) for a live example.

---

# Deadlines

URL: https://pro.rv-grid.com/guides/gantt/scheduling/deadlines/
Source: src/content/docs/guides/gantt/scheduling/deadlines.mdx
Description: Use deadlineDate to track target dates without constraining the scheduling engine.
Surface: gantt

Use `deadlineDate` for target dates that should warn but not lock the schedule:

```typescript
{
  id: 'frontend',
  name: 'Development',
  deadlineDate: '2026-05-15',
  // other task fields
}
```

## Behavior

If a task finishes after its `deadlineDate`, the scheduler reports a `deadline-missed` conflict. This warning appears in:
- The **Scheduling Warning** column.
- The task **tooltip**.
- The row/bar **warning state**.
- A visual **timeline indicator** (usually a down-arrow on the deadline date).

## Deadline vs. Finish Constraint

Unlike a `must-finish-on` or `finish-no-later-than` constraint, a deadline **never moves the task**.
- It is purely an analytical tool to measure performance against a target.
- It does not affect the critical path or slack calculations of other tasks.

This matches Microsoft Project's distinction between a deadline and an inflexible finish constraint: a deadline is an alert, not a scheduling rule.

---

# Scheduling Direction

URL: https://pro.rv-grid.com/guides/gantt/scheduling/direction/
Source: src/content/docs/guides/gantt/scheduling/direction.mdx
Description: Configure forward (ASAP) or backward (ALAP) scheduling for your Gantt project.
Surface: gantt

Forward scheduling is the default and behaves like Microsoft Project's ASAP (As Soon As Possible) direction. Automatic tasks are placed as early as their dependencies and constraints allow.

```typescript
grid.gantt = {
  scheduling: {
    scheduleFrom: 'project-start',
    projectStartDate: '2026-04-06',
  },
};
```

When `projectStartDate` is set, automatic root tasks start from that anchor unless a dependency or constraint moves them later.

## Backward Scheduling (ALAP)

Backward scheduling behaves like Microsoft Project's ALAP (As Late As Possible) project-finish direction:

```typescript
grid.gantt = {
  scheduling: {
    scheduleFrom: 'project-finish',
    projectFinishDate: '2026-06-30',
  },
};
```

Automatic tasks without successors are placed as late as possible against `projectFinishDate`; predecessors are pulled earlier to satisfy outgoing dependencies. If `projectFinishDate` is omitted, the scheduler uses the latest task finish in the current data.

## Example: Project Finish Scheduling

Use project-finish scheduling for ALAP-style plans:

```typescript
grid.gantt = {
  scheduling: {
    scheduleFrom: 'project-finish',
    projectFinishDate: '2026-04-30',
  },
};

grid.source = [
  {
    id: 'build',
    name: 'Build',
    duration: 3,
  },
  {
    id: 'release',
    name: 'Release',
    duration: 1,
  },
];

grid.ganttDependencies = [{
  id: 'build-release',
  predecessorTaskId: 'build',
  successorTaskId: 'release',
  type: 'finish-to-start',
  lagDays: 0,
}];
```

**Expected result**: `release` is placed as late as possible against `2026-04-30`; `build` is pulled earlier so the FS relationship remains valid.

See the [Project-finish ALAP demo](https://demo.rv-grid.com/gantt-alap/ts) for a visible backward-scheduled chain anchored to a project finish date.

---

# Duration Units and Conversion

URL: https://pro.rv-grid.com/guides/gantt/scheduling/durations/
Source: src/content/docs/guides/gantt/scheduling/durations.mdx
Description: Enter, retain, format, and schedule task durations in minutes, hours, days, weeks, months, quarters, or years.
Surface: gantt

Gantt stores `duration`, `remainingDuration`, and task `workHours` in one canonical unit: **hours**. `durationUnit` controls Duration, Remaining Duration, and Duration Variance; `workUnit` independently controls Work. These unit fields affect display and editing, not storage. Different tasks can therefore retain different display units in the same column:

```ts
grid.source = [
  { id: 'review', name: 'Review', startDate: '2026-04-06T09:00:00Z', duration: 5, durationUnit: 'hour', workHours: 16, workUnit: 'day' }, // 5 hours, 2 days Work
  { id: 'build', name: 'Build', startDate: '2026-04-07', duration: 16, durationUnit: 'day', workHours: '40h' }, // 2 days, 40 hours Work
  { id: 'release', name: 'Release train', startDate: '2026-04-09', duration: 120, durationUnit: 'week' }, // renders 3 weeks
  { id: 'handoff', name: 'Handoff', startDate: '2026-04-30T16:00:00Z', duration: 0.5, durationUnit: 'minute' }, // renders 30 minutes
];
```

The managed Duration, Remaining Duration, Duration Variance, Work, tooltip, task editor, and Excel export surfaces include the unit label, with singular/plural output such as `1 hour`, `5 hours`, `1 day`, and `2 days`.

## DurationUnit

```ts
type DurationUnit =
  | 'minute'
  | 'hour'
  | 'day'
  | 'week'
  | 'month'
  | 'quarter'
  | 'year';
```

Minutes are supported. Persist new numeric data as canonical hours and include `durationUnit` when a particular display unit must be retained. At source hydration only, legacy unitless numeric values remain supported as day-based values (or the configured fixed default); hydrated task-store data is converted to hours.

When `durationUnit` is omitted and `defaultUnit` is `auto` (the default), the table chooses a readable display unit: values below one working hour use minutes, values below one working day use hours, and longer values use days. Work follows the same rule through `workUnit` and `defaultWorkUnit`. A unit entered by the user is retained, so `5 hrs` and `2 days` can coexist.

## Flexible input

The inline grid editor and Task Information editor accept a number followed by a short or long unit:

| Input | Meaning |
|---|---|
| `30m`, `30 min`, `30 mins` | 30 working minutes |
| `5h`, `5 hr`, `5 hrs` | 5 working hours |
| `2d`, `2 days` | 2 working days |
| `3w`, `3 wk`, `3 wks` | 3 working weeks |
| `2mo`, `2 months` | 2 working months |
| `1q`, `1 quarter` | 1 working quarter |
| `1y`, `1 year` | 1 working year |

A bare Duration or Remaining Duration edit uses the task's retained `durationUnit`, then `defaultUnit`, then days. A bare Work edit uses `workUnit`, then `defaultWorkUnit`, then hours. Every accepted edit is converted to hours before the task store is updated. Invalid or negative text is rejected. Work is person-time, so elapsed forms such as `2ed` are rejected for Work even though they are valid for task Duration.

## Conversion settings

Set project-wide conversion values with `gantt.durationSettings`:

```ts
grid.gantt = {
  ...project,
  durationSettings: {
    defaultUnit: 'auto', // or fix: 'minute' | 'hour' | 'day' | ...
    defaultWorkUnit: 'auto', // independent fixed/automatic Work unit
    hoursPerDay: 8,
    hoursPerWeek: 40,
    daysPerMonth: 20,
    maximumFractionDigits: 1, // default MSP-style compact precision
  },
};
```

With these settings:

- `1 day = 8 hours`
- `1 week = 40 hours = 5 working days`
- `1 month = 20 working days`
- `1 quarter = 3 working months`
- `1 year = 12 working months`

`defaultUnit` and `defaultWorkUnit` can be fixed independently, matching the distinction between task span and person-work. Both default to `auto`. `hoursPerDay` defaults to the effective task calendar's `hoursPerDay`, then 8. `hoursPerWeek` defaults to `hoursPerDay × workingDays.length`, commonly 40. `daysPerMonth` defaults to 20.

`maximumFractionDigits` controls rendered precision for Duration, Remaining Duration, Duration Variance, and Work. It defaults to `1`, trims trailing zeroes, and only affects presentation: `56.625 days` renders as `56.6 days`, while canonical stored hours are unchanged. Set it to `0` for whole units or a larger integer when a project needs more visible precision.

Changing `hoursPerDay` or `hoursPerWeek` changes conversion at edit, render, and scheduling boundaries. It does not rewrite stored hours and does not redefine the calendar's `workingDays`, holidays, or `workingHours`; configure those separately on `CalendarEntity`.

## Working time and elapsed time

Normal units consume working time. With an 8-hour day, `2d` is normally 16 working hours. When `scheduling.excludeHolidaysFromDuration` is enabled, the scheduler also skips closed weekdays, holidays, and configured intraday working-hour gaps.

Elapsed input uses an `e` prefix and runs continuously, ignoring the working calendar:

```ts
{ duration: 48, durationUnit: 'day', durationIsElapsed: true } // renders 2 elapsed days
```

The same value can be entered as `2ed` or `2 elapsed days`. `2d` means two working days; `2ed` means 48 continuous hours and can cross nights, weekends, and holidays. Elapsed aliases are supported for every `DurationUnit`, such as `30em`, `4eh`, and `1ew`.

  `durationIsElapsed` affects scheduling, not only formatting. Use it only for work that genuinely continues while the project calendar is closed.

## Summary tasks

Summary duration is derived from the earliest scheduled child start to the latest scheduled child finish. It is a span, not the sum of child durations. Summary Duration cells remain read-only even when their children use mixed units.

## Milestones and zero duration

Setting a task's Duration to `0` schedules and renders it as a milestone. Unlike a derived summary Duration, the milestone Duration cell remains editable. Entering any positive value, such as `4h` or `2d`, stores the converted canonical hours and changes the task type back to `task`. The same reversible behavior applies in the Task Information dialog.

## Programmatic helpers

The standalone Gantt package exports shared date-layer helpers used by source hydration, scheduling, editors, and projection. Duration parsing, conversion, and formatting live in one module, so every integration follows the same canonical-hour rules:

```ts
import {
  parseDuration,
  formatDurationValue,
  durationToHours,
  hoursToDuration,
  durationToElapsedHours,
  elapsedHoursToDuration,
  resolveDurationSettings,
} from '@revolist/gantt';
```

Use these helpers in custom editors or persistence adapters instead of implementing a second unit conversion table.

---

# Effort Modes

URL: https://pro.rv-grid.com/guides/gantt/scheduling/effort-modes/
Source: src/content/docs/guides/gantt/scheduling/effort-modes.mdx
Description: Model task types (Fixed Duration, Fixed Work, Fixed Units) to control how work and duration interact.
Surface: gantt

['fixed-duration', 'Preserve duration. Work and units do not recalculate duration.'],
  ['fixed-work', 'Preserve workHours and derive duration from assigned units and calendar.'],
  ['fixed-units', 'Preserve assignment units and derive duration from workHours and units.'],
];

Use `effortMode` to model Microsoft Project-style task types:

`workHours` is always stored as canonical hours. Set `workUnit` to retain a task-specific display unit, or enter Work as text such as `5h`, `2d`, or `3w`. Project `durationSettings.defaultWorkUnit` can fix the default Work unit independently from Duration.

## Formula

The duration formula for fixed-work/fixed-units is:

```text
duration = ceil(workHours / (hoursPerDay * totalAssignmentUnits))
```

## Example: Task Types

```typescript
grid.source = [
  {
    id: 'standup',
    name: 'Standup',
    effortMode: 'fixed-duration',
    duration: 1,
    workHours: 2,
  },
  {
    id: 'implementation',
    name: 'Implementation',
    effortMode: 'fixed-work',
    workHours: 32,
    workUnit: 'hour',
  },
];

grid.ganttAssignments = [
  {
    taskId: 'implementation',
    resourceId: 'alex',
    allocationUnits: 100,
  },
];
```

**Expected result**: `standup` keeps its one-day duration. `implementation` becomes four days (32h / 8h/day) with one 100% assignment.

See the [Progress and work demo](https://demo.rv-grid.com/gantt-progress-work/ts) for more examples.

---

# Engine Logic

URL: https://pro.rv-grid.com/guides/gantt/scheduling/engine/
Source: src/content/docs/guides/gantt/scheduling/engine.mdx
Description: Deep dive into the RevoGrid Gantt scheduling engine pipeline and conflict resolution.
Surface: gantt

['High', 'Actuals', "actualStartDate and actualFinishDate pin the task; the engine won't move them."],
  ['High', 'Hard Constraints', 'MSO / MFO dates win over dependencies; conflict reported.'],
  ['Medium', 'Dependencies', 'Auto-tasks are clamped to satisfy predecessors.'],
  ['Medium', 'Soft Constraints', 'Dates are adjusted to bounds where possible; conflict reported if windows are disjoint.'],
  ['Low', 'Authored Dates', 'Used as the starting point for root tasks or manual tasks.'],
];

The RevoGrid Gantt scheduling engine follows a deterministic pipeline to compute effective dates for all tasks. It processes data changes in five distinct phases to ensure dependency safety and constraint satisfaction.

## The 5-Step Pipeline

### 1. Topological Sort
The engine first builds a dependency graph and performs a topological sort. This ensures that tasks are ordered such that every predecessor is processed before its successors.
- Summary tasks are handled separately to ensure they can roll up dates from their children.
- Circular dependencies are detected and reported as `dependency-cycle` issues with the involved task and dependency IDs.

When the active dependency graph contains a cycle, the engine treats the project as structurally invalid schedule data. It does not try to calculate a dependency-valid order through the loop, and task drag/resize does not clamp against predecessor links until the cycle is resolved.

### 2. Forward Pass (ASAP)
In the default `scheduleFrom: 'project-start'` mode, the engine performs a forward pass:
- Root tasks (those without predecessors) are anchored to the `projectStartDate`.
- Successors are shifted forward to satisfy their incoming dependencies (FS, SS, FF, SF) plus any `lagDays`.
- The engine uses the successor's calendar to compute working-day offsets if `lagCalendar: 'working-days'` is enabled.

### 3. Constraint Application
Once the dependency-driven dates are known, the engine applies per-task constraints:
- **Soft Constraints**: SNET, SNLT, etc., refine the start date if the dependency date falls outside the constraint bound.
- **Hard Constraints**: `must-start-on` and `must-finish-on` override the forward pass results. If a hard constraint violates a dependency, a conflict is reported, but the constraint date wins.

### 4. Summary Rollup
After all leaf tasks have their dates resolved, the engine rolls up the schedule to summary (parent) tasks:
- A summary task's `startDate` is the minimum of its children's `startDate`.
- A summary task's `endDate` is the maximum of its children's `endDate`.
- Rollup is recursive, traversing the entire WBS (Work Breakdown Structure) tree.

### 5. Critical Path Analysis
The final phase computes the project's early and late dates using a backward pass from the project finish date:
- **Total Slack**: The number of days a task can be delayed without delaying the project finish.
- **Critical Path**: Tasks with zero total slack are marked as `isCritical`.
- This analysis helps planners identify the "chain" of tasks that determines the total project duration.

## Conflict Resolution

The engine prioritizes user intent and data integrity when scheduling rules collide:

  The scheduling engine runs synchronously on each render to provide immediate feedback during drag-and-drop or inline editing.

---

# Resource Leveling

URL: https://pro.rv-grid.com/guides/gantt/scheduling/leveling/
Source: src/content/docs/guides/gantt/scheduling/leveling.mdx
Description: Use automatic resource leveling to resolve over-allocations by delaying tasks.
Surface: gantt

Enable deterministic auto-leveling with:

```typescript
grid.gantt = {
  scheduling: {
    resourceLeveling: 'auto',
    resourceLevelingWithinSlack: false,
  },
};
```

Auto-leveling delays later overlapping automatic tasks until the resource is available, then reports `resource-leveling-adjustment`.

## Leveling Controls

Per-task leveling controls:

```typescript
const task = {
  priority: 900,           // 0-1000; higher priority is protected first
  canLevel: true,          // false keeps the task fixed during auto-leveling
  levelingDelayDays: 2,    // stored calendar-day delay applied by leveling
};
```

**Deterministic auto-leveling order**:
1. Non-levelable tasks first (fixed blockers).
2. Higher `priority` before lower `priority`.
3. Earlier start date, then task id.

## Constraints and Actuals

The leveling implementation avoids moving:
- Manually scheduled tasks.
- Tasks with `actualStartDate` or `actualFinishDate`.
- Summary tasks.
- Inactive tasks.
- Tasks pinned by `must-start-on` or `must-finish-on`.

  Microsoft Project leveling can delay or split tasks. RevoGrid leveling is deterministic and delay-based; it supports priority and slack-limited leveling but does not split tasks automatically.

---

# Manual Scheduling

URL: https://pro.rv-grid.com/guides/gantt/scheduling/manual/
Source: src/content/docs/guides/gantt/scheduling/manual.mdx
Description: Use taskMode to lock dates and override automatic dependency propagation.
Surface: gantt

Set `taskMode` on each task, or use `taskModeDefault` for tasks that omit it:

```typescript
{
  id: 'kickoff',
  name: 'Fixed Kickoff Event',
  taskMode: 'manual',
  startDate: '2026-04-20',
  endDate: '2026-04-20',
  duration: 0,
  // other task fields
}
```

Automatic tasks are dependency-safe. Dragging, resizing from the start edge, or editing an automatic successor before its predecessor allows will clamp the effective schedule to the dependency-valid date.

Manual tasks keep authored dates. If the manual start violates an active dependency, the scheduler reports `manual-dependency-violation` and the row/bar renders a scheduling warning indicator.

  Microsoft Project's Task Mode field defaults new tasks to manually scheduled in some desktop versions. RevoGrid defaults to automatic scheduling because dependency safety is the default expectation for this Gantt plugin. Set `taskModeDefault: 'manual'` to make omitted task modes behave manually.

## Dependency Violations

When a manual task is placed at a date that violates an incoming dependency (e.g., starts before a FS predecessor finishes), the scheduler does not move the task. Instead, it:
1. Records a `manual-dependency-violation` conflict.
2. Displays a warning icon in the "Scheduling Warning" column.
3. Highlights the task bar with warning styling.

This allows planners to maintain "best guess" or "negotiated" dates while still seeing where the logical project structure is broken.

---

# Overview Scheduling

URL: https://pro.rv-grid.com/guides/gantt/scheduling/overview/
Source: src/content/docs/guides/gantt/scheduling/overview.mdx
Description: Configure MSP-style scheduling with task modes, dependencies, constraints, calendars, deadlines, resources, leveling, actuals, and critical path.
Surface: gantt

['manual-dependency-violation', 'A manual task starts before an active dependency allows.'],
  ['dependency-constraint-conflict', 'A dependency cannot be satisfied because an explicit constraint wins.'],
  ['hard-constraint-conflict', 'A must-start/must-finish constraint overrides dependencies.'],
  ['constraint-window-conflict', 'Soft constraint and dependency windows do not overlap.'],
  ['deadline-missed', 'A task finishes after deadlineDate.'],
  ['resource-overallocation', 'A resource exceeds capacity on a scheduled working date.'],
  ['resource-leveling-adjustment', 'Auto-leveling shifted a task to remove over-allocation.'],
];

The Gantt scheduler computes effective task dates from authored dates, duration, task mode, dependencies, lag/lead, calendars, constraints, deadlines, resources, actuals, split ranges, and optional resource leveling.

Its compatibility target is Microsoft Project scheduling behavior: automatic tasks are dependency-safe, manual tasks preserve authored dates but show warnings, deadlines warn without constraining, and leveling can delay eligible work.

---

## Scheduling Configuration

Configure scheduling policies under `grid.gantt.scheduling`:

```typescript
grid.gantt = {
  scheduling: {
    taskModeDefault: 'auto',
    scheduleFrom: 'project-start',
    projectStartDate: '2026-04-06',
    excludeHolidaysFromDuration: true,
    lagCalendar: 'working-days',
    manualDependencyViolationBehavior: 'warn',
    resourceLeveling: 'warn',
    effortModeDefault: 'fixed-duration',
    progressRescheduling: 'remaining-duration',
  },
};
```

Definition source: `packages/gantt/src/gantt/grid/gantt-plugin.types.ts`.

## Scheduling Warnings

Warnings are reported as scheduler conflicts and projected into rows:

## Performance

Large-project scheduler performance is covered by the Gantt benchmark suite:

```bash
pnpm --filter @revolist/gantt bench
```

The benchmark exercises 1,000 and 3,000 task snapshots with dense dependencies and auto-leveling.

---

## Next Steps

Dive deeper into specific scheduling topics:

- **[MSP Compatibility](../compatibility)**: How RevoGrid maps to Microsoft Project.
- **[Engine Logic](../engine)**: The 5-step pipeline and conflict resolution.
- **[Scheduling Direction](../direction)**: Forward (ASAP) vs. Backward (ALAP).
- **[Calendars & Duration](../calendars)**: Working days, holidays, and lag calendars.
- **[Dependencies](../concepts/dependencies)**: FS, SS, FF, SF and lag/lead.
- **[Task Modes](../manual)**: Manual vs. Automatic scheduling.
- **[Constraints](../constraints)**: SNET, MSO, MFO and soft/hard rules.
- **[Deadlines](../deadlines)**: Target dates and missed deadline warnings.
- **[Resources & Assignments](../resources/resources-and-assignments)**: Resource capacity and assignments.
- **[Resource Planning View](../resources/resource-planning-view)**: Resource-centric timeline view.
- **[Resource Leveling](../leveling)**: Auto-leveling logic and priorities.
- **[Effort Modes](../effort-modes)**: Fixed work, duration, and units.
- **[Actuals & Progress](../progress)**: Tracking real-world status.
- **[Split Tasks](../split-tasks)**: Managing work gaps.
- **[Critical Path](../critical-path)**: Slack and schedule analysis.

---

# Actuals and Progress

URL: https://pro.rv-grid.com/guides/gantt/scheduling/progress/
Source: src/content/docs/guides/gantt/scheduling/progress.mdx
Description: Track project progress using actual start/finish dates and remaining duration.
Surface: gantt

Use actual fields to reflect progress:

```typescript
{
  id: 'qa',
  name: 'QA',
  actualStartDate: '2026-04-08',
  remainingDuration: 2,
  percentDone: 50,
}
```

## Calculated Status and Status Date

Set `gantt.statusDate` to the reporting date used by the read-only **Status** and **Status Indicator** columns. It defaults to today's ISO date when omitted and affects reporting only; it does not move tasks or timeline lines.

```ts
grid.gantt = {
  ...project,
  statusDate: '2026-04-08',
};
```

The calculated values are:

- `Complete` when `% Done` is 100 or Actual Finish exists.
- `Future Task` when the scheduled start is after the Status Date.
- `On Schedule` when linearly distributed reported completion covers the effective planned work through the day before the Status Date.
- `Late` when work has started or should have progressed but reported completion does not reach that boundary.

The comparison uses the effective task calendar, holidays, split ranges, and elapsed-duration rules. Incomplete milestones are Late before the Status Date, On Schedule on it, and Future Task after it. Summary tasks use rolled-up dates and progress. Because Gantt stores aggregate `% Done` rather than timephased actual work, completion is distributed linearly over the effective scheduled work span.

Use the editable **Workflow Status** field for `not-started`, `in-progress`, `done`, or `blocked`. Workflow Status never drives calculated Status or scheduling.

The default **Status**, **Status Indicator**, and **Workflow Status** columns use
the advanced selection filter. Their filter options reuse the same managed badge
or indicator template as the task-table cell, including projected row metadata.

## Percent Done column mode

The managed `% Done` column uses the Pro progress renderers and defaults to a horizontal `bar`. Choose the project default with `gantt.visuals.percentDoneMode`:

```ts
grid.gantt = {
  ...project,
  visuals: {
    percentDoneMode: 'circle',
  },
};
```

Override that default for an individual authored column with its `mode` property:

```ts
grid.columns = [
  { prop: 'name', name: 'Task' },
  { prop: 'percentDone', name: '% Done', mode: 'number' },
];
```

| Mode | Cell display |
|---|---|
| `number` | Percentage text such as `40%`. |
| `bar` | Horizontal progress bar plus percentage. This is the default. |
| `circle` | Circular progress indicator with the percentage centered inside. |

The column `mode` takes precedence over `visuals.percentDoneMode`. Both change presentation only. Values remain numbers from `0` through `100`; sorting, filtering, editing, scheduling, task-bar progress, and Excel export continue to use `percentDone`. A custom `cellTemplate` supplied on the `% Done` grid column overrides either managed mode.

## Progress-Aware Scheduling

Enable progress-aware scheduling:

```typescript
grid.gantt = {
  scheduling: {
    progressRescheduling: 'remaining-duration',
  },
};
```

When enabled:
- `actualStartDate` anchors in-progress work.
- `remainingDuration` replaces the planned duration for the remaining span.
- `actualFinishDate` pins completed work to the recorded finish.
- The schedule origin is shown as `Actual`.

## Example: Actuals and Remaining Duration

```typescript
grid.gantt = {
  scheduling: { progressRescheduling: 'remaining-duration' },
};

grid.source = [
  {
    id: 'in-progress',
    startDate: '2026-04-01',
    duration: 10,
    actualStartDate: '2026-04-03',
    remainingDuration: 2,
  },
  {
    id: 'complete',
    startDate: '2026-04-01',
    duration: 10,
    actualStartDate: '2026-04-02',
    actualFinishDate: '2026-04-04',
  },
];
```

**Expected result**: `in-progress` is anchored on `2026-04-03` and schedules 2 remaining days. `complete` is pinned to its actual dates.

---

# Split Tasks

URL: https://pro.rv-grid.com/guides/gantt/scheduling/split-tasks/
Source: src/content/docs/guides/gantt/scheduling/split-tasks.mdx
Description: Pause work inside a task span using split ranges.
Surface: gantt

Use `splitRanges` to pause work inside a task:

```typescript
{
  id: 'qa',
  name: 'QA',
  startDate: '2026-04-01',
  duration: 4,
  splitRanges: [{ startDate: '2026-04-03', endDate: '2026-04-04' }],
}
```

The scheduler extends the computed finish by the split duration so the task retains its planned working duration. Resource allocation checks skip split dates, and task bars render split ranges as visible gaps.

## Timeline Split Editing

- **Create**: Alt-drag inside a regular task bar.
- **Move**: Drag an existing split gap.
- **Remove**: Double-click a split gap.

## Example: Split Task with Resource Allocation

```typescript
grid.source = [{
  id: 'qa',
  startDate: '2026-04-01',
  duration: 4,
  splitRanges: [{ startDate: '2026-04-03', endDate: '2026-04-04' }],
}];
```

**Expected result**: the task keeps four working days of duration, but its computed finish extends. Resource allocation checks skip `2026-04-03` and `2026-04-04`.

---

# Build A Production Gantt Project

URL: https://pro.rv-grid.com/guides/gantt/tutorial/
Source: src/content/docs/guides/gantt/tutorial.mdx
Description: Extend the quick-start project with dependencies, editing, resources, critical path, baselines, persistence, and export.
Surface: gantt

This tutorial starts with any [framework quick start](/guides/gantt/) and builds toward the same data flow used by the full showcase.

1. **Add project hierarchy.** Keep task rows flat and connect children with `parentId`.

   ```ts
   grid.source = [
     { id: 'delivery', name: 'Delivery', type: 'summary', startDate: '2026-07-14', duration: 8 },
     { id: 'design', parentId: 'delivery', name: 'Design', startDate: '2026-07-14', duration: 3 },
     { id: 'build', parentId: 'delivery', name: 'Build', startDate: '2026-07-17', duration: 5 },
     { id: 'launch', name: 'Launch', type: 'milestone', startDate: '2026-07-24', duration: 0 },
   ];
   ```

2. **Add dependencies.** Use stable task IDs and one of `FS`, `SS`, `FF`, or `SF`.

   ```ts
   grid.ganttDependencies = [
     { id: 'd1', predecessorTaskId: 'design', successorTaskId: 'build', type: 'FS', lagDays: 0 },
     { id: 'd2', predecessorTaskId: 'build', successorTaskId: 'launch', type: 'FS', lagDays: 0 },
   ];
   ```

3. **Enable supported editing.** The managed task columns route edits through Gantt scheduling and validation.

   ```ts
   grid.gantt = {
     ...grid.gantt,
     allowTaskCreate: true,
     taskCreateRow: true,
     contextMenu: {},
   };
   ```

   Inline cell editing, timeline drag/resize/progress handles, dependency drawing, the task editor, and the context menu all use the same project state. See [Task Editing](/guides/gantt/interaction/task-editing/).

4. **Assign resources.** Resources and assignments are separate collections so multiple resources can work on one task.

   ```ts
   grid.ganttResources = [{
     id: 'designer', name: 'Avery', role: 'Designer', calendarId: 'standard',
     allocationCapacity: 100, hourlyCost: 90,
   }];
   grid.ganttAssignments = [{
     id: 'a1', taskId: 'design', resourceId: 'designer',
     allocationUnits: 100, workHours: 24, responsibility: 'Visual design',
   }];
   ```

5. **Show schedule analysis.** Critical path and baseline overlays are opt-in visual layers.

   ```ts
   grid.gantt = {
     ...grid.gantt,
     visuals: {
       ...grid.gantt?.visuals,
       showCriticalPath: true,
       showBaseline: true,
       baselineId: 'approved',
     },
   };
   grid.ganttBaselines = [{
     id: 'approved',
     name: 'Approved plan',
     capturedAt: '2026-07-14T00:00:00.000Z',
     tasks: [
       { taskId: 'design', startDate: '2026-07-14', endDate: '2026-07-16', duration: 24, progressPercent: 0 },
       { taskId: 'build', startDate: '2026-07-17', endDate: '2026-07-23', duration: 40, progressPercent: 0 },
     ],
   }];
   ```

6. **Persist complete project snapshots.** Keep application state authoritative and replace grid collections after a successful save or server update.

   ```ts
   import { exportProjectSnapshot, parseProjectSnapshotJson } from '@revolist/gantt';

   const json = exportProjectSnapshot(snapshot, { space: 2 });
   const restored = parseProjectSnapshotJson(json);
   if (restored.ok) applyProject(restored.project);
   ```

7. **Add reporting actions.** Grid CSV/Excel export covers task-table data; the print recipe prepares a combined task-table/timeline report.

   ```ts
   import { createPrintPdfExportRecipe } from '@revolist/gantt';

   const print = createPrintPdfExportRecipe({ target: document.querySelector('#gantt')!, document, window });
   print.exportProject(snapshot, { label: 'Delivery plan' });
   ```

  Treat emitted or edited collections as application state. Do not scrape rendered task bars or cells to reconstruct project data.

Next, browse [all Gantt examples](/guides/gantt/examples/), review [configuration](/guides/gantt/reference/configuration-reference/), or open the [API reference](/api/gantt/).

---

# Smart Excel-Compatible Clipboard

URL: https://pro.rv-grid.com/guides/grid-utilities/clipboard-json/
Source: src/content/docs/guides/grid-utilities/clipboard-json.mdx
Description: Rich Excel and RevoGrid copy and paste with extensible clipboard formats.

`ClipboardPlugin` adds rich, Excel-compatible range copy and paste. It negotiates the
best browser-visible representation in this order: the lossless RevoGrid payload,
application handlers, Excel HTML, generic HTML tables, and TSV/plain text.

Use `DataGridFormattingPlugin` for the recommended setup. It installs one clipboard
owner automatically, so copied values, formulas, formats, merged cells, and explicit
row/column sizes share one canonical clipboard document:

```ts
import { DataGridFormattingPlugin } from '@revolist/revogrid-pro';

grid.plugins = [DataGridFormattingPlugin];
```

The clipboard codec only extracts browser-visible Excel declarations. Their
normalization into `DataGridCellFormat`, storage, rendering, and conversion back to
Excel HTML are owned by `DataGridFormattingPlugin`; clipboard code never applies
cell CSS directly.

For the complete formatting model, cell/range/row/column scopes, precedence,
Format Cells UI, state persistence, and workbook export, see
[Format Cells](/guides/data-grid/format-cells/).

## What is preserved

| Capability                    | RevoGrid → RevoGrid                                                                  | Excel → RevoGrid                                                                                                                                                                                                                     | RevoGrid → Excel                                                                                    |
| ----------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| Values                        | Typed values through the rich payload, including serializable objects                | Explicit numeric/boolean HTML values stay typed. When Excel supplies display-only Accounting, Percentage, or date text, the formatting plugin uses the accompanying number format to recover a canonical number or Excel serial date | Numbers, booleans, percentages, and dates are emitted as typed Excel HTML values; text remains text |
| Formulas                      | A1 source, plus the evaluated cached value when FormulaPlugin is available           | Browser-visible A1 or R1C1 formulas normalize to FormulaPlugin-compatible A1. If Excel exposes only the displayed result, the formula source cannot be recovered                                                                     | A1 source becomes Excel-relative R1C1 with a typed cached result when FormulaPlugin is available    |
| Number and date formats       | Exact canonical preset or custom-code format                                         | `mso-number-format` becomes a canonical `{ kind: 'code' }` format                                                                                                                                                                    | Presets and exact codes become Excel number-format declarations                                     |
| Font and fill                 | Preserved through `DataGridCellFormat.appearance`                                    | Allowlisted font, emphasis, text color, and fill declarations are converted                                                                                                                                                          | Canonical typography and colors become Excel-compatible HTML styles                                 |
| Alignment and text layout     | Horizontal/vertical alignment, wrap, indent, rotation, and shrink-to-fit             | Supported Excel declarations are normalized into appearance options                                                                                                                                                                  | Canonical options are serialized back to Excel HTML                                                 |
| Borders                       | Per-edge style, color, and width                                                     | Supported shorthand and longhand Excel borders are normalized                                                                                                                                                                        | Per-edge borders are emitted; legacy uniform border options remain shorthand                        |
| Multiple ranges               | Sparse offsets and gaps are lossless in the rich payload                             | Multiple browser-visible HTML tables are decoded as ranges                                                                                                                                                                           | Each range is emitted as an HTML table; rich RevoGrid geometry remains available to RevoGrid        |
| Merged cells                  | Merge spans are carried and applied when every destination is writable               | `rowspan` and `colspan` become merge metadata                                                                                                                                                                                        | Merge metadata becomes `rowspan` and `colspan`                                                      |
| Row heights and column widths | Carried in the rich document; destination RevoGrid resizing is not applied currently | Parsed and retained, but destination RevoGrid resizing is not applied currently                                                                                                                                                      | Explicit sizes are emitted in the Excel HTML table                                                  |
| Application metadata          | Namespaced serializable contributors are lossless                                    | Available only when exposed by a registered handler                                                                                                                                                                                  | Written by compatible registered handlers                                                           |

Formatting is applied only after the existing provider-backed value paste is
accepted. Readonly cells, rejected validation targets, canceled edits, and
synthetic grouping rows do not receive formatting or merges.

Excel Desktop does not expose identical browser HTML on every platform. For
example, Excel for macOS may omit `x:num` and copy `$ 1,250.50`, `18.0%`, or
`8/20/26` as display text accompanied by Accounting, Percentage, or `Short Date`
format declarations. `DataGridFormattingPlugin` decodes Excel's CSS escapes and
named formats, converts those known display-only values to canonical numbers or
Excel serial dates, and stores the imported number format as a
`DataGridCellFormat`. Unknown or ambiguous text is left unchanged.

### Display-only Excel category coverage

Excel's browser HTML varies by platform, but the formatting owner covers every
documented cell number-format category when a usable format declaration is
present:

| Excel category          | Display-only value recovery                                                                                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| General                 | Kept as text unless Excel supplies an explicit typed attribute; visual text alone is ambiguous                                                                                                                            |
| Number                  | Localized decimals, grouping, negative signs, parentheses, and scaling commas become numbers                                                                                                                              |
| Currency and Accounting | Locale/currency tokens and aligned currency displays become numbers; the exact format code remains canonical formatting                                                                                                   |
| Percentage              | The displayed percentage is converted back to its underlying decimal value once per `%` token                                                                                                                             |
| Fraction                | Simple, mixed, fixed-denominator, and negative fraction displays become numbers                                                                                                                                           |
| Scientific              | Localized mantissas and signed `E` exponents become numbers                                                                                                                                                               |
| Date                    | Numeric and localized month-name dates become Excel serial dates using the format's token order and locale                                                                                                                |
| Time and Date & time    | 12/24-hour times, seconds, fractional seconds, and combined date-time displays become serial day values                                                                                                                   |
| Elapsed time            | `[h]`, `[m]`, and `[s]` duration displays—including values beyond 24 hours—become serial day fractions                                                                                                                    |
| Text                    | Kept exactly as text, including leading zeros                                                                                                                                                                             |
| Special                 | Postal, phone, social-security, and comparable placeholder formats recover their numeric value while retaining the exact format code                                                                                      |
| Custom                  | Numeric/date/time/text classification comes from the compiled code; four sections, conditions, colors, literals, spacing, fill, percentages, scaling, fractions, and scientific notation use the same engine as rendering |

Explicit `x:num` and boolean attributes always take precedence. Excel error
values and malformed, unsupported, or ambiguous display strings stay unchanged
instead of being guessed. These categories follow Microsoft's
[available number formats](https://support.microsoft.com/en-us/excel/get-started/available-number-formats-in-excel)
and [custom number-format rules](https://support.microsoft.com/en-us/excel/review-guidelines-for-customizing-a-number-format).

### Native Excel interoperability matrix

The following matrix was created as a real `.xlsx` workbook, opened in current
Excel Desktop for macOS, copied through the macOS system clipboard, pasted into
RevoGrid, and then copied from RevoGrid back into Excel. It is not an authored
HTML fixture.

![Native Excel clipboard format matrix pasted into RevoGrid](/images/clipboard/excel-native-format-matrix.png)

### Quick support checklist

Use this list to compare an Excel range with its RevoGrid result. **Native
tested** means the format was created in an actual `.xlsx` workbook and copied
through Excel Desktop for macOS and the system clipboard—not merely passed to
the HTML parser in a test.

| Cell data or number format       | Support                                                                                                                                                 | Native tested                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| General and plain numbers        | Supported; an explicit Excel numeric value stays numeric. Ambiguous display-only General text stays text                                                | Yes                                                                                          |
| Number                           | Supported, including decimals, grouping, signs, parentheses, and scaling commas                                                                         | Yes                                                                                          |
| Currency and Accounting          | Supported, including currency/locale tokens, aligned symbols, negative parentheses, and zero sections                                                   | Yes                                                                                          |
| Percentage                       | Supported; the displayed percentage is restored to its decimal value                                                                                    | Yes                                                                                          |
| Scientific                       | Supported, including signed exponents                                                                                                                   | Yes                                                                                          |
| Fraction                         | Supported, including simple, mixed, fixed-denominator, and negative fractions                                                                           | Yes                                                                                          |
| Date                             | Supported for short, long, numeric, month-name, and localized dates                                                                                     | Yes                                                                                          |
| Time, DateTime, and elapsed time | Supported for 12/24-hour time, seconds, fractional seconds, combined values, and `[h]`/`[m]`/`[s]` durations                                            | Yes                                                                                          |
| Text                             | Supported and emitted with Excel's Text format so leading zeros and number-like strings remain text                                                     | Yes                                                                                          |
| Special                          | Supported for numeric placeholder formats such as phone and postal masks                                                                                | Phone mask tested                                                                            |
| Custom                           | Supported for up to four sections, conditions, colors, literals, leading zeros, percentages, scaling, fractions, scientific notation, spacing, and fill | Positive/negative/zero sections, leading zeros, scaling, literals, and localized date tested |
| Boolean                          | Supported when Excel exposes Boolean typing; otherwise the displayed `TRUE`/`FALSE` is preserved as text                                                | Conditional on Excel payload                                                                 |
| Formula                          | Supported when the clipboard exposes A1/R1C1 source; otherwise only Excel's displayed/cached result can be preserved                                    | RevoGrid → Excel tested; Excel for macOS omitted formula source                              |

| Appearance or structure       | Support                                                                                                          | Native tested                                |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Font                          | Family, size, bold, italic, underline, strike-through, and text color                                            | Family, size, bold, italic, and color tested |
| Fill                          | Solid browser-visible cell background color                                                                      | Yes                                          |
| Alignment and layout          | Horizontal/vertical alignment, wrapping, indentation, text rotation, and shrink-to-fit                           | Alignment and wrapping tested                |
| Borders                       | Per-edge style, color, and width                                                                                 | Double/per-edge border tested                |
| Merged cells                  | Supported through HTML `rowspan`/`colspan` and the rich RevoGrid payload                                         | Automated copy/paste tested                  |
| Multiple ranges               | Lossless between RevoGrid instances; multiple Excel HTML tables are accepted                                     | Automated copy/paste tested                  |
| Row heights and column widths | Parsed and copied back to Excel HTML; applying imported sizes to the destination RevoGrid is not implemented yet | Metadata emission tested                     |
| RevoGrid application metadata | Supported through namespaced, serializable contributors in the rich payload                                      | Automated rich-payload tests                 |

### Unsupported or unavailable through browser clipboard

| Excel feature                                                                          | Current behavior                                                                                  |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Native BIFF/OLE clipboard records                                                      | Browsers do not expose them; RevoGrid uses HTML, plain text, and its versioned web custom format  |
| Pictures, charts, shapes, and other floating objects                                   | Not part of the cell-range clipboard contract                                                     |
| Comments, notes, threaded discussions, and attachments                                 | Not copied                                                                                        |
| Data validation rules, dropdown definitions, and non-serializable validator callbacks  | Not copied                                                                                        |
| Conditional-format rules, icon sets, data bars, and workbook themes                    | Rules are not copied; only browser-visible effective styles may be present in Excel HTML          |
| Named ranges, tables, filters, pivot state, external links, and workbook relationships | Not copied                                                                                        |
| Macros, VBA, ActiveX, and embedded objects                                             | Not copied or executed                                                                            |
| Formula source omitted by Excel                                                        | Cannot be reconstructed safely; RevoGrid preserves the displayed/cached result and does not guess |
| Unsupported or malformed display-only values                                           | Preserved as text instead of being coerced                                                        |
| Destination RevoGrid row/column resizing                                               | Size metadata is retained, but the destination grid is not resized in the current version         |
| Windows Excel native interoperability                                                  | Supported through the same browser-visible contract, but not yet manually verified in this matrix |

The pass deliberately records browser limits as limits. Excel for macOS exposed
`text/html`, `text/plain`, `text/rtf`, and `Files`, but its HTML omitted the raw
formula source and explicit numeric value for some display-only cells. RevoGrid
therefore preserves the displayed formula result in that direction and only
recovers a zero when the accompanying third number-format section identifies
the display literally. RevoGrid does not guess an unavailable formula. Native
Windows Excel remains a separate manual interoperability target because its
browser-visible clipboard payload can differ.

## How the representations work together

One copy operation writes several representations because the destination—not
the source—chooses which one it understands:

1. `application/x-revogrid-clipboard+json` version 2 is the lossless
   RevoGrid-to-RevoGrid document.
2. Registered application formats can override built-ins by priority.
3. `text/html` carries the richest browser-visible Excel-compatible table.
4. `text/plain` keeps the selection useful in editors and applications that do
   not understand structured clipboard formats.

On paste, RevoGrid negotiates in the same richest-first order. A malformed or
failing handler emits `clipboardformaterror` and falls through to the next
compatible representation instead of partially applying its result.

## Copying from RevoGrid to Excel

Copy writes an Excel-compatible HTML table alongside plain text and the lossless
RevoGrid payload. `DataGridFormattingPlugin` converts its canonical options back to
Excel number-format codes, font, fill, borders, alignment, wrapping, rotation, and
indentation. The clipboard owner also emits formulas with typed cached results,
merged-cell spans, and explicit row and column sizes.

Date and time application values remain unchanged in the grid. For Excel HTML only,
the formatting plugin converts valid date-like values to Excel 1900-system serials
and writes the matching number-format code. This lets Excel receive a real date cell
instead of display text while keeping the application's source model intact.

`ClipboardPlugin` can also be installed directly for values and custom formats. It
emits a one-time dependency warning and omits formatting metadata when no formatting
runtime is present.

## Browser and Excel boundary

Browsers expose `text/html`, `text/plain`, and permitted web custom formats; they do
not expose Excel's native BIFF/OLE clipboard records. RevoGrid therefore writes all
compatible browser representations and adds the versioned
`application/x-revogrid-clipboard+json` format for lossless grid-to-grid transfers.
Pictures, charts, comments, validation callbacks, and other native-only Excel objects
are outside the cell-range contract.

## Custom formats

Handlers have stable IDs, MIME types, priorities, detection, decoding, and optional
encoding. Higher priorities can override built-ins. A failing handler emits
`clipboardformaterror` and negotiation continues with the next compatible format.

```ts
import type { ClipboardFormatHandler } from '@revolist/revogrid-pro';

const handler: ClipboardFormatHandler = {
  id: 'acme-cells',
  mimeTypes: ['application/x-acme-cells+json'],
  priority: 2_000,
  canRead: ({ transfer }) =>
    transfer.types.includes('application/x-acme-cells+json'),
  read: ({ transfer }) =>
    JSON.parse(transfer.getData('application/x-acme-cells+json')),
  write: ({ document }) => [
    {
      type: 'application/x-acme-cells+json',
      data: JSON.stringify(document),
    },
  ],
};

grid.useClipboard = {
  formats: [handler],
  maxCells: 100_000,
  maxBytes: 10 * 1024 * 1024,
};
```

Runtime registration is disposable:

```ts
const clipboard = grid
  .getPlugins()
  .find((plugin) => plugin instanceof ClipboardPlugin);
const unregister = clipboard?.registerFormat(handler);
```

Serializable application metadata can be carried in the rich payload through
`registerMetadataContributor`. Non-serializable editors, validators, and callbacks
are intentionally never copied.

## Migrating from ClipboardJsonPlugin

`ClipboardJsonPlugin`, its `legacyJsonText` option, and the `$rv-parse_` plain-text
marker were removed in v2.8. Use `ClipboardPlugin` directly, or install
`DataGridFormattingPlugin` to include formatting support. Object-valued cells are
preserved grid-to-grid through the versioned RevoGrid MIME payload; `text/plain`
remains readable JSON/text for other applications.

```ts
// Before
import { ClipboardJsonPlugin } from '@revolist/revogrid-pro';
grid.plugins = [ClipboardJsonPlugin];

// After: values and custom clipboard formats
import { ClipboardPlugin } from '@revolist/revogrid-pro';
grid.plugins = [ClipboardPlugin];

// After: recommended when cell formatting is enabled
import { DataGridFormattingPlugin } from '@revolist/revogrid-pro';
grid.plugins = [DataGridFormattingPlugin];
```

Applications that persisted or manually generated `$rv-parse_` strings must decode
them before upgrading. The smart clipboard intentionally does not interpret marker
text because ordinary user text must remain ordinary text.

## Example

---

# Dimension Animation

URL: https://pro.rv-grid.com/guides/grid-utilities/dimension-animation/
Source: src/content/docs/guides/grid-utilities/dimension-animation.mdx
Description: Animate row and column dimension sizes for custom collapse, expand, and resize flows.

`DimensionAnimationPlugin` is a plugin that animates grid dimension sizes. Use it when a feature needs rows or columns to collapse, expand, or move between explicit sizes without replacing the grid's own virtualization and dimension systems.

The plugin only animates sizes. It does not own row visibility, trimming, grouping, ordering, or business state. Callers decide what should become hidden or visible, then use the plugin to make the size transition smooth.

## When to use it

- Animate custom row or column collapse and expand flows.
- Animate explicit size changes when you already know the start and end sizes.
- Coordinate delayed state changes around animation completion.
- Support integrations such as tree rows, where `TreeDataPlugin` handles trim state and `DimensionAnimationPlugin` handles the visual transition.

## Installation

```typescript
import { DimensionAnimationPlugin } from '@revolist/revogrid-pro';

const grid = document.querySelector('revo-grid');

grid.plugins = [DimensionAnimationPlugin];
grid.dimensionAnimation = {
  duration: 180,
  easing: 'easeOutCubic',
  types: ['rgRow'],
};
```

Configure the plugin through `grid.dimensionAnimation`. The older `additionalData.dimensionAnimation` path is still accepted for compatibility, but `grid.dimensionAnimation` is the supported API.

| Property | Default | Description |
| --- | --- | --- |
| `duration` | `180` | Animation duration in milliseconds. Use `0` to apply sizes synchronously. |
| `easing` | `'easeOutCubic'` | Easing used while interpolating sizes. Supports `'linear'`, `'easeOutCubic'`, or a custom `(progress) => number` function. |
| `types` | All row and column dimensions | Dimensions affected by requests that do not pass a specific `type`. |

## Controller API

After the plugin is registered, use its controller methods to animate indexes or explicit frames.

```typescript
const plugins = await grid.getPlugins();
const dimensionAnimation = plugins.find(
  plugin => plugin instanceof DimensionAnimationPlugin,
);

await dimensionAnimation?.collapse([0, 1, 2], {
  type: 'rgRow',
  indexKind: 'visual',
});

await dimensionAnimation?.expand([0, 1, 2], {
  type: 'rgRow',
  indexKind: 'visual',
});
```

Use `indexKind: 'physical'` when indexes refer to source rows or columns. Use `indexKind: 'visual'` when indexes refer to the current rendered order after sorting, filtering, trimming, pinning, or other view changes.

### Explicit frames

Use `animate()` when you already know the visual indexes and target sizes.

```typescript
await dimensionAnimation?.animate([
  {
    type: 'rgCol',
    visualIndex: 0,
    from: 220,
    to: 80,
  },
]);
```

The plugin cancels any in-flight animation that targets the same dimension index before starting the next one. Call `cancel()` directly to stop matching animations, or omit arguments to cancel all dimension animations.

```typescript
dimensionAnimation?.cancel('rgRow', [0, 1]);
dimensionAnimation?.cancel();
```

## Event API

You can also request animations by dispatching the `dimensionanimate` event from the grid element. The plugin attaches `detail.done` synchronously, so event-driven integrations can wait before applying follow-up logic.

```typescript
const detail = {
  action: 'collapse',
  indexes: [0],
  type: 'rgRow',
  indexKind: 'visual',
};

grid.dispatchEvent(new CustomEvent('dimensionanimate', { detail }));

await detail.done;
```

Listen to `beforedimensionanimate` to cancel an operation before it starts. Listen to `afterdimensionanimate` to react after the animation completes or is cancelled.

```typescript
grid.addEventListener('beforedimensionanimate', event => {
  if (event.detail.action === 'collapse' && shouldBlockCollapse()) {
    event.preventDefault();
  }
});

grid.addEventListener('afterdimensionanimate', event => {
  console.log(event.detail.results);
});
```

## Tree integration

Tree rows can use dimension animation automatically. Enable `tree.animation`; `TreeDataPlugin` registers `DimensionAnimationPlugin` when it is not already present.

```typescript
import { TreeDataPlugin } from '@revolist/revogrid-pro';

grid.plugins = [TreeDataPlugin];
grid.tree = {
  animation: true,
};
grid.dimensionAnimation = {
  duration: 180,
};
```

In this flow, `TreeDataPlugin` owns tree trim state and expansion state. `DimensionAnimationPlugin` only animates the affected row sizes during collapse and expand.

## API reference

- [Dimension Animation API](/api/dimension-animation/)
- [Tree guide](/guides/data-manage/tree/)

---

# Overlay Nodes

URL: https://pro.rv-grid.com/guides/grid-utilities/overlay-nodes/
Source: src/content/docs/guides/grid-utilities/overlay-nodes.mdx
Description: A guide to using the Overlay Plugin to display notes on grid rows.

The **Overlay Plugin** in RevoGrid provides a powerful way to display additional content over the grid cells. This guide demonstrates how to use it to show notes on specific rows.

  1. **Dynamic Overlay Positioning**: The Overlay Plugin automatically handles positioning and scrolling of overlay elements, ensuring they stay aligned with their corresponding grid rows.
  2. **Performance Optimized**: Despite rendering additional content, the overlay layer remains virtualized, maintaining high performance even with many notes.
  3. **Flexible Content**: You can display any type of content in the overlay, from simple notes to complex interactive components.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
  - [Basic Setup](#basic-setup)
  - [Adding Notes](#adding-notes)
  - [Customizing Notes](#customizing-notes)
- [API Reference](#api-reference)

---

## Features

- **Row-Specific Notes**: Display notes on specific grid rows
- **Automatic Positioning**: Notes automatically position themselves relative to their rows
- **Scroll Synchronization**: Notes stay aligned with their rows during scrolling
- **Custom Styling**: Fully customizable note appearance and behavior

---

## Basic Setup

1. **Import the Overlay Plugin:**

   ```javascript
   import { OverlayPlugin } from '@revolist/revogrid-pro';
   ```

2. **Initialize the Grid with the Plugin:**

   ```javascript
   const grid = document.querySelector('revo-grid');
   grid.plugins = [OverlayPlugin];
   ```

3. **Add Notes to Rows:**

   ```javascript
   // Dispatch an event to add a note
   grid.dispatchEvent(new CustomEvent('overlaynode', {
     detail: {
       nodeId: `note-${rowIndex}`,
       vnode: h('div', { class: 'note' }, 'Your note text here')
     }
   }));
   ```

### Adding Notes

To add a note to a specific row, you need to:

1. Create a unique `nodeId` for the note
2. Create a virtual node (vnode) for the note content
3. Dispatch the `overlaynode` event with the note details

```javascript
const addNote = (rowIndex, noteText) => {
  const noteNode = h('div', {
    class: 'note',
    style: {
      position: 'absolute',
      top: `${rowIndex * rowHeight}px`,
      left: '0',
      width: '100%',
      padding: '8px',
      backgroundColor: 'rgba(255, 255, 0, 0.2)',
      border: '1px solid #ffd700'
    }
  }, noteText);

  grid.dispatchEvent(new CustomEvent('overlaynode', {
    detail: {
      nodeId: `note-${rowIndex}`,
      vnode: noteNode
    }
  }));
};
```

### Customizing Notes

You can customize the appearance and behavior of notes by:

1. Modifying the note's CSS styles
2. Adding interactive elements
3. Implementing custom positioning logic

```javascript
const createCustomNote = (rowIndex, noteData) => {
  return h('div', {
    class: 'custom-note',
    style: {
      position: 'absolute',
      top: `${rowIndex * rowHeight}px`,
      left: '0',
      width: '100%',
      padding: '12px',
      backgroundColor: noteData.color || 'rgba(255, 255, 0, 0.2)',
      border: `1px solid ${noteData.borderColor || '#ffd700'}`,
      borderRadius: '4px'
    }
  }, [
    h('div', { class: 'note-header' }, noteData.title),
    h('div', { class: 'note-content' }, noteData.content)
  ]);
};
```

---

## API Reference

### OverlayPlugin Events

#### `overlaynode`

Dispatched to add or update a note in the overlay layer.

```typescript
interface OverlayNodeEvent {
  nodeId: string;
  vnode: VNode;
}
```

#### `overlayclearnode`

Dispatched to remove notes from the overlay layer.

```typescript
interface OverlayClearNodeEvent {
  nodeIds: string[];
}
```

### Methods

#### `refresh()`

Manually refresh the overlay layer's positioning and content.

---

# Local Pagination

URL: https://pro.rv-grid.com/guides/grid-utilities/pagination/
Source: src/content/docs/guides/grid-utilities/pagination.mdx
Description: Manage large datasets by breaking them into smaller, more manageable pages.

Enable `PaginationPlugin` to efficiently manage large datasets by breaking them into smaller, more manageable pages, enhancing both performance and user experience.
Pagination allows you to divide your dataset into discrete pages, each containing a specified number of rows.
Users can then navigate through these pages rather than scrolling through a long list of data.

This is especially useful when dealing with large datasets where loading all rows at once could affect performance. It gives you:

- **Improved Performance**: By loading only a subset of data at a time, pagination helps maintain grid performance even with large datasets.
- **Enhanced User Experience**: Users can easily navigate through data without being overwhelmed by a large number of rows.

---

# Smart Panel

URL: https://pro.rv-grid.com/guides/grid-utilities/smart-panel/
Source: src/content/docs/guides/grid-utilities/smart-panel.mdx
Description: Add configurable, formula-powered row, selection, and application summaries beside any RevoGrid.

`SmartPanelPlugin` adds a compact status surface that stays synchronized with
RevoGrid. It reads selection, focus, row visibility, tree/group nodes, pinned
viewports, checkbox row selection, formulas, and source changes from grid
providers instead of inspecting rendered DOM cells.

Use the defaults for spreadsheet-style selection statistics, or replace the
complete item list with application-specific formulas and resolvers. The panel
can sit directly below the grid or render into an application-owned host.

<figure>
  <img
    src="/images/smart-panel/selection-summary.png"
    alt="RevoGrid with a selected revenue range and a Smart Panel showing rows, range, cells, count, sum, average, minimum, and maximum."
    width="1440"
    height="730"
  />
  <figcaption>
    The default panel adds row context on the left and selection statistics on
    the right. Items appear only when their visibility conditions are met.
  </figcaption>
</figure>

## Quick setup

Install the plugin and enable range selection:

```ts
import { SmartPanelPlugin } from '@revolist/revogrid-pro';

const grid = document.querySelector<HTMLRevoGridElement>('revo-grid')!;

grid.range = true;
grid.plugins = [SmartPanelPlugin];
```

With no `smartPanel` configuration, the plugin creates a panel immediately
after `<revo-grid>`. It always shows the number of main data rows. When a range
contains more than one cell it can also show:

- A1-style range address
- Selected cell and numeric-value counts
- Sum, average, minimum, and maximum
- Visible versus total rows when filtering, tree collapse, grouping, or other
  trimming hides rows

The panel refreshes after edits, source and column updates, filtering, sorting,
trimming, pagination, row order, focus/range changes, multi-range changes,
checkbox row selection, and tree-state changes. Bursts are coalesced before
the provider snapshot is rebuilt.

## Configure panel items

Replace `items` to control exactly what appears:

```ts
grid.smartPanel = {
  locale: 'en-US',
  numberFormat: {
    maximumFractionDigits: 0,
  },
  items: [
    {
      id: 'rows',
      label: 'Rows',
      metric: 'visibleRows',
      align: 'left',
    },
    {
      id: 'range',
      label: 'Range',
      metric: 'rangeAddress',
      align: 'left',
      visible: ({ snapshot }) => snapshot.selectedCells.length > 1,
    },
    {
      id: 'revenue',
      label: 'Selected revenue',
      formula: '=SUM(SELECTION)',
      align: 'right',
      format: value => `$${Number(value).toLocaleString('en-US')}`,
    },
  ],
};
```

Every item needs a stable `id` and one value source: `metric`, `formula`, or
`resolve`. If more than one is supplied, resolution uses `resolve`, then
`formula`, then `metric`.

### Built-in metrics

| Metric | Result |
| --- | --- |
| `selectedCells` | Unique selected cells across the active and multi-ranges |
| `selectedRows` | Checkbox-selected rows when `RowSelectPlugin` is installed; otherwise rows represented by the cell range |
| `visibleSelectedRows` | Selected rows that remain visible after trimming |
| `selectedColumns` | Unique columns represented by the selected cells |
| `visibleRows` / `totalRows` / `hiddenRows` | Main data-row counts; synthetic grouping rows are excluded |
| `visibleNodes` / `totalNodes` | Main row-store nodes, including synthetic tree or grouping nodes |
| `focusedCell` / `focusedColumn` | Current A1 address or column label |
| `rangeAddress` | One or more A1 ranges, with pinned viewport ownership when needed |
| `numericCount`, `sum`, `average`, `min`, `max` | Finite numeric values from selected cells |
| `distinct` | Unique selected values |

### Formula items

Formula items use the same evaluator as RevoGrid formulas. Two dynamic names
are available:

- `SELECTION` — all values in the current item scope
- `VALUES` — an equivalent alias that reads naturally for row/column formulas

```ts
grid.smartPanel = {
  items: [
    { id: 'median', label: 'Median', formula: '=MEDIAN(SELECTION)' },
    { id: 'spread', label: 'Spread', formula: '=MAX(VALUES)-MIN(VALUES)' },
    {
      id: 'visible-arr',
      label: 'Visible ARR',
      formula: '=SUM(VALUES)',
      scope: 'visibleRows',
      column: 'arr',
    },
    {
      id: 'all-arr',
      label: 'All ARR',
      formula: '=SUM(VALUES)',
      scope: 'allRows',
      column: 'arr',
    },
  ],
};
```

`scope` defaults to `selection`. For `visibleRows` and `allRows`, set `column`
to evaluate one field. Without `column`, the panel flattens enumerable values
from every row in that scope.

  Smart Panel formulas do not require `FormulaPlugin`. Add `FormulaPlugin` when
  selected grid cells themselves contain formulas and the panel should aggregate
  their evaluated results instead of their raw `=...` source strings.

## Application summaries

Custom resolvers receive the complete provider-backed snapshot and may be
synchronous or asynchronous:

```ts
grid.smartPanel = {
  className: 'operations-panel',
  items: [
    {
      id: 'visibility',
      label: 'Visible accounts',
      align: 'left',
      resolve: ({ snapshot }) =>
        `${snapshot.visibleRowCount} of ${snapshot.totalRowCount}`,
    },
    {
      id: 'regions',
      label: 'Regions',
      align: 'center',
      resolve: ({ snapshot }) =>
        new Set(snapshot.visibleRows.map(row => row.region)).size,
    },
    {
      id: 'pipeline',
      label: 'Pipeline',
      scope: 'visibleRows',
      column: 'pipeline',
      formula: '=SUM(VALUES)',
      align: 'right',
      format: value => `$${Number(value).toLocaleString('en-US')}`,
    },
    {
      id: 'health',
      label: 'Health',
      align: 'right',
      resolve: ({ snapshot }) =>
        snapshot.visibleRows.every(row => row.health === 'On track')
          ? 'On track'
          : 'Needs attention',
      className: 'operations-panel__health',
    },
  ],
};
```

<figure>
  <img
    src="/images/smart-panel/custom-summary.png"
    alt="A customized RevoGrid Smart Panel showing visible accounts, regions, pipeline value, and portfolio health."
    width="1440"
    height="706"
  />
  <figcaption>
    Formula items and application resolvers can share the same left, center,
    and right aligned panel.
  </figcaption>
</figure>

The resolver context contains:

| Field | Description |
| --- | --- |
| `grid` | Host `HTMLRevoGridElement` |
| `providers` | RevoGrid plugin providers for advanced integrations |
| `snapshot` | One immutable-by-convention snapshot shared by every item in the refresh |
| `item` | Current item configuration |
| `values` | Values resolved from the item's `scope` and optional `column` |

`snapshot` includes ranges, selected cells and raw/evaluated values, checkbox
and range rows, selected columns, visible/all main rows, visible/all rows across
pinned stores, data-row and node counts, focus metadata, and a revision number.

## Item presentation

| Property | Default | Purpose |
| --- | --- | --- |
| `label` | none | Muted text before the value |
| `align` | `right` | Places the item in the `left`, `center`, or `right` group |
| `order` | declaration index | Orders items inside an alignment group |
| `priority` | `0` | Secondary sort and a `data-priority` styling hook |
| `visible` | `true` | Boolean or snapshot predicate controlling whether the item renders |
| `format` | panel formatter | Converts the resolved value into display text |
| `render` | none | Returns a safe `Node` or text string for custom presentation |
| `className` | none | Adds an application class to the item |
| `title` | none | Static string or context callback for the native title |

Strings returned from `render` or a resolver are inserted as text, never as raw
HTML. Return a DOM `Node` when richer content is required:

```ts
{
  id: 'status',
  render: value => {
    const badge = document.createElement('strong');
    badge.className = 'status-badge';
    badge.textContent = String(value);
    return badge;
  },
  resolve: ({ snapshot }) =>
    snapshot.hiddenRowCount ? 'Filtered' : 'Complete',
}
```

## Render into a custom host

Pass an element or a callback when layout belongs to the application:

```html
<div class="grid-layout">
  <revo-grid id="accounts"></revo-grid>
  <aside id="grid-insights"></aside>
</div>
```

```ts
grid.smartPanel = {
  host: () => document.querySelector('#grid-insights'),
  items,
};
grid.plugins = [SmartPanelPlugin];
```

The plugin never removes a user-owned host. Assign a new `smartPanel` object or
call `plugin.setHost(nextHost)` to move the existing component. Passing `null`
returns it to a plugin-owned host immediately after the grid.

## Panel configuration

| Property | Default | Description |
| --- | --- | --- |
| `host` | panel after grid | Element or callback providing the panel container |
| `items` | spreadsheet defaults | Complete ordered item configuration |
| `className` | none | Additional class on the panel host |
| `ariaLabel` | `Grid summary` | Accessible name for the status region |
| `hiddenWhenEmpty` | `false` | Hides the host when no configured items resolve visibly |
| `locale` | browser locale | Locale passed to `Intl.NumberFormat` |
| `numberFormat` | `{ maximumFractionDigits: 2 }` | Default numeric formatting options |
| `formatValue` | built-in formatter | Panel-wide value formatter used before item-level `format` |
| `onError` | none | Receives an isolated item/formula error |
| `schedule` | `microtask` | Use `animationFrame` to align refreshes with visual frame updates |

Assign `false` to hide the installed panel without removing the plugin:

```ts
grid.smartPanel = false;
```

Direct property assignments are observable. The legacy
`additionalData.smartPanel` configuration remains available for compatibility,
but new integrations should use `grid.smartPanel`.

## Runtime API and events

Retrieve the plugin instance through RevoGrid's plugin service:

```ts
const smartPanel = (await grid.getPlugins())
  .find(plugin => plugin instanceof SmartPanelPlugin);

const snapshot = smartPanel?.getSnapshot();
const items = smartPanel?.getItems();
await smartPanel?.refresh();
smartPanel?.setHost(document.querySelector('#grid-insights'));
```

| Method | Purpose |
| --- | --- |
| `getSnapshot()` | Returns the last committed provider snapshot |
| `getItems()` | Returns a copy of the last resolved item list |
| `getComponent()` | Returns the presentation-only `SmartPanelComponent` |
| `refresh()` | Immediately rebuilds and renders the snapshot; resolves when committed |
| `setHost(host)` | Moves the panel to a user host or back to an owned host with `null` |

| Event | Detail | Purpose |
| --- | --- | --- |
| `smartpanelchange` | `{ snapshot, items }` | Fires after the latest asynchronous refresh commits |
| `smartpanelerror` | `{ error, item }` | Reports one failed item while healthy items continue rendering |

When async item resolvers overlap, only the newest refresh commits. Use
`onError` or `smartpanelerror` for telemetry without taking down the rest of
the panel.

## Styling

The Pro stylesheet includes responsive wrapping at `720px`. Customize the
panel through its public variables and stable classes:

```scss
.operations-panel {
  --revo-smart-panel-background: #101615;
  --revo-smart-panel-color: #d7e2de;
  --revo-smart-panel-border: #2a3834;
  --revo-smart-panel-gap: 24px;

  border-radius: 12px;

  &__health .revo-smart-panel__value {
    color: #32d89b;
  }
}
```

| Selector | Role |
| --- | --- |
| `.revo-smart-panel` | Host status region |
| `.revo-smart-panel__group--left` | Left item group |
| `.revo-smart-panel__group--center` | Center item group |
| `.revo-smart-panel__group--right` | Right item group |
| `.revo-smart-panel__item` | One resolved item |
| `.revo-smart-panel__label` | Item label |
| `.revo-smart-panel__value` | Text or custom rendered value |

## Composition patterns

    Keep the defaults for range address, count, sum, average, min, and max.

    Combine visible/total row metrics with formulas scoped to `visibleRows`.

    Use node metrics beside data-row metrics to distinguish structural rows.

    Mount into a dashboard shell and add async resolvers or custom Nodes.

The component uses `role="status"`, `aria-live="polite"`, and the configured
accessible label. Keep item labels concise so selection gestures do not create
overly verbose screen-reader announcements.

---

# Tooltip

URL: https://pro.rv-grid.com/guides/grid-utilities/tooltip/
Source: src/content/docs/guides/grid-utilities/tooltip.mdx
Description: A comprehensive guide to using the RevoGrid Tooltip Plugin

The Tooltip Plugin is a Pro plugin that displays additional information when users hover over grid cells or other elements inside the grid. It creates a single managed tooltip element, reads content from cell attributes, and shows it after a short hover delay.

## Features

- Dynamic tooltip creation and positioning on `mouseover`, `mouseout`, and `mousemove`
- Automatic tooltip content from `data-tooltip` or `title` attributes
- Customizable tooltip appearance with `tooltip-type` and `tooltip-position` attributes
- Configurable show delay, animation, and cursor-following behavior
- Automatic mounting inside the active dialog/fullscreen container, with the document body as fallback
- Body fallback so grid and ancestor overflow containers cannot crop the tooltip
- Preserves the grid's effective LTR or RTL writing direction across the portal boundary
- Smart positioning that follows grid UI beyond the host while keeping tooltips within viewport boundaries
- Smooth show/hide transitions
- Support for different tooltip types (info, warning, error, etc.)

## Installation

The Tooltip Plugin is included in RevoGrid Pro. To use it, import and initialize it with your grid:

```typescript
import { TooltipPlugin } from '@revolist/revogrid-pro';

const grid = document.querySelector('revo-grid');
grid.plugins = [TooltipPlugin];
```

## Usage

### Basic Usage

The simplest way to use tooltips is by adding a `title` or `data-tooltip` attribute to your grid cells:

```typescript
grid.columns = [
  {
    prop: 'name',
    name: 'Name',
    cellTemplate: (createElement, props) => {
      return createElement('div', {
        title: 'User name',
        'data-tooltip': 'Full user name',
      }, props.model.name);
    },
  },
];
```

### Showing Behavior

Tooltips are shown only when the hovered element has a non-empty `data-tooltip` or `title` attribute. If both are present, `data-tooltip` is used. The plugin waits `500ms` before showing the tooltip by default, then hides it when the cursor leaves the tooltip target.

Use the `tooltip` grid property to control when and how the tooltip is shown:

```typescript
grid.tooltip = {
  enabled: true,
  showDelayMs: 250,
  animation: true,
  followCursor: true,
  themeVariables: ['--app-tooltip-accent'],
  appendTo: document.getElementById('tooltip-root') ?? document.body,
};
```

| Property | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enables or disables tooltip hover behavior. Disabling it hides any open tooltip immediately. |
| `showDelayMs` | `500` | Delay before showing the tooltip. Negative values are normalized to `0`. |
| `animation` | `true` | Enables the tooltip entrance and exit transition. |
| `followCursor` | `true` | Keeps the tooltip attached to the cursor while it is open. Set to `false` to keep the tooltip at its opening position. |
| `themeVariables` | `[]` | Additional CSS custom properties copied from the grid to the portal-mounted tooltip. |
| `appendTo` | Automatic | Element that receives the managed tooltip node. Runtime changes move the existing tooltip to the new target. |

Without `appendTo`, the plugin uses the closest open native dialog or active fullscreen element containing the grid, then falls back to `document.body`. This keeps the tooltip in the browser's active top-layer subtree while the body fallback prevents `overflow: hidden` on the grid or its ancestors from cropping it. For a custom target, prefer a top-level overlay root without clipping or CSS transforms. A target inside an overflow-clipping container can crop the tooltip.

Plugins that own tooltip-specific theme variables can register them without mutating application configuration:

```typescript
const unregister = tooltipPlugin.registerThemeVariables([
  '--my-plugin-tooltip-accent',
]);

// Call during plugin teardown.
unregister();
```

### Customizing Tooltip

You can control the tooltip position using the `tooltip-position` attribute and the `tooltip-type` attribute to change the tooltip type:

```typescript
createElement('div', {
  'data-tooltip': 'Custom positioned tooltip',
  'tooltip-position': 'right', // 'top', 'bottom', 'left', 'right'
  'tooltip-type': 'info', // 'info', 'warning', 'error', etc.
}, content);
```

## Best Practices

1. Keep tooltip content concise and relevant
2. Use appropriate tooltip positions based on available space
3. Choose tooltip types that match the information context
4. Consider mobile users when designing tooltip interactions
5. Use tooltips to provide supplementary information, not critical data

---

# Removing Attribution

URL: https://pro.rv-grid.com/guides/hide-attribution/
Source: src/content/docs/guides/hide-attribution.md
Description: Removing Attribution from RevoGrid

As a Pro version user of RevoGrid, you can easily remove attribution from your projects. To do this, simply apply one of the following attributes:

### Method 1: Using `hideAttribution`

Add the `hideAttribution` attribute to your RevoGrid component:

```html
<revo-grid hideAttribution></revo-grid>
```

### Method 2: Using `hide-attribution`

Alternatively, you can use the `hide-attribution` attribute:

```html
<revo-grid hide-attribution></revo-grid>
```

### Conclusion

By applying either of these attributes, the attribution will be hidden from your RevoGrid component.

If you have any questions or need further assistance, feel free to reach out to the RevoGrid support team.

---

# Infinity Scroll

URL: https://pro.rv-grid.com/guides/infinity-scroll/
Source: src/content/docs/guides/infinity-scroll.mdx
Description: Efficiently handle large datasets with dynamic loading as users scroll through the grid.

The Infinity Scroll feature enables dynamic data loading as users scroll through the grid, efficiently managing large datasets by loading data in chunks and cleaning up unused data to optimize memory usage.

## Key Features

- Dynamic data loading based on scroll position
- Pre-loads data ahead of scroll direction
- Efficient memory management by cleaning up off-screen data
- Configurable chunk size and buffer sizes
- Support for both known and unknown total data sizes
- Compatible with pinned top and bottom rows

## Basic Setup

To enable infinity scroll in your grid:

```typescript
import { InfinityScrollPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [InfinityScrollPlugin];
grid.pinnedTopSource = [{ id: 'status', name: 'Pinned status row' }];
grid.pinnedBottomSource = [{ id: 'summary', name: 'Pinned summary row' }];

grid.infinityScroll = {
  chunkSize: 50, // Number of rows per chunk
  bufferSize: 100, // How many rows to keep in buffer
  preloadThreshold: 0.75, // When to start loading more data (0-1)
  total: 1000, // Optional: total number of rows
  loadData: async (skip, limit, order, singleConditionFilters) => {
    // Fetch data from your API
    const response = await fetch(`/api/data?skip=${skip}&limit=${limit}&order=${JSON.stringify(order)}&filter=${JSON.stringify(singleConditionFilters)}`);
    const data = await response.json();
    return data; // You can return an array or { data, hasMore, total }
  }
};
```

The configuration is an observable grid property, so assigning a new object to
`grid.infinityScroll` updates the plugin. In Vue templates, use the kebab-case
alias with Vue's `.prop` modifier so the object is assigned as an element
property:

```vue
<RevoGrid
  :plugins="[InfinityScrollPlugin]"
  :infinity-scroll.prop="infinityScroll"
/>
```

`additionalData.infinityScroll` remains available as a deprecated compatibility
fallback for existing applications.

Pinned rows stay outside the remote loading lifecycle. Use the core
`pinnedTopSource` and `pinnedBottomSource` grid properties for static status,
summary, or action rows while `InfinityScrollPlugin` manages only the main
scrollable source.

## Configuration Options

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Type</th>
      <th>Default</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>chunkSize</code></td>
      <td><code>number</code></td>
      <td><code>undefined</code></td>
      <td>Number of rows to load in each chunk. Can be set dynamically by the grid.</td>
    </tr>
    <tr>
      <td><code>bufferSize</code></td>
      <td><code>number</code></td>
      <td><code>undefined</code></td>
      <td>Number of rows to keep in the memory buffer. Can be set dynamically by the grid.</td>
    </tr>
    <tr>
      <td><code>preloadThreshold</code></td>
      <td><code>number</code></td>
      <td><code>0.75</code></td>
      <td>When to trigger loading the next chunk (0–1).</td>
    </tr>
    <tr>
      <td><code>total</code></td>
      <td><code>number</code></td>
      <td><code>undefined</code></td>
      <td>Total number of rows. If omitted, the plugin grows the source as you scroll.</td>
    </tr>
    <tr>
      <td><code>loadData</code></td>
      <td><code>function</code></td>
      <td>Required</td>
      <td>
        Function that loads data chunks. Return <code>row[]</code> or{' '}
        <code>&#123; data: row[], hasMore?: boolean, total?: number &#125;</code>.
      </td>
    </tr>
  </tbody>
</table>

### Remote advanced filtering

For a new backend integration, use the canonical `filterAst` and
`executionContext` arguments. The tree is JSON-safe and preserves nested
groups, cross-column logic, structured operators, and quick-filter composition.
The context captures the single reference instant, timezone, and serializable
blank-value policy used by relative-date rules, so the server can evaluate the
same request as the grid.

```typescript
loadData: async (
  skip,
  limit,
  order,
  _singleConditionFilters,
  _multiConditionFilters,
  _quickFilter,
  _temporalContext,
  filterAst,
  executionContext,
) => {
  const response = await fetch('/api/data', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(
      {
        page: { skip, limit },
        order,
        filter: filterAst ? { filterAst, executionContext } : undefined,
      },
    ),
  });
  return response.json();
}
```

Register `AdvanceFilterPlugin` alongside `InfinityScrollPlugin` before using
this contract. Its `filterastchange` event and the `beforefilterapply` detail
expose the same canonical pair; see [Canonical Filter AST](/guides/data-filter/filter-ast/)
for the tree schema and [Filter Events](/guides/data-filter/filter-events/)
for a custom remote adapter.

#### Compatibility arguments

`loadData` keeps the established positional arguments for existing callers.
The fourth `singleConditionFilters` argument contains at most one condition per
column. The optional fifth `multiConditionFilters` argument contains every
advanced column condition and its relation; use it when an existing backend
supports multiple conditions for one column. The sixth argument is the
normalized global quick-filter payload, and the seventh is temporal transport
data for older date/datetime integrations. The eighth and ninth arguments are
the canonical `filterAst` and `executionContext` shown above.

`multiConditionFilters` can contain runtime-only values such as a selection
filter `Set`, so do not serialize it unchanged in new integrations. If an
existing backend requires it, normalize those values at that adapter boundary.

For example, if the Name column must contain `Remote` and must not contain
`Archived`, the fifth argument keeps both conditions and their relation:

```typescript
{
  name: [
    { id: 0, type: 'contains', value: 'Remote', relation: 'and' },
    { id: 1, type: 'notContains', value: 'Archived', relation: 'and' },
  ],
}
```

The fourth argument remains compatible with single-condition backends and, for
this example, contains only `{ name: { type: 'contains', value: 'Remote' } }`.
Use `multiConditionFilters` whenever the backend needs the full expression.

### Using `hasMore` for unknown total

When your backend does not provide a fixed `total`, return `hasMore` from
`loadData`. This is the most reliable way to tell the plugin when to stop
requesting additional chunks.

```typescript
grid.infinityScroll = {
  chunkSize: 100,
  loadData: async (skip, limit, order, singleConditionFilters) => {
    const response = await fetch('/api/data', {
      method: 'POST',
      body: JSON.stringify({ skip, limit, order, filter: singleConditionFilters }),
    });
    const result = await response.json();
    return {
      data: result.items,
      hasMore: result.hasMore,
    };
  },
};
```

### Dynamic `total` from backend

You can also return `total` from `loadData`. When provided, the plugin updates
its internal total size and uses it for source sizing and end detection.

## Memory Management

The plugin automatically manages memory by:
- Loading new chunks of data as the user scrolls
- Maintaining a buffer of rows before and after the visible area
- Cleaning up data that's far from the current viewport

## Exporting to Excel

`ExportExcelPlugin` exports grid source rows, not rendered DOM rows. Ordinary
client-side virtualization therefore exports the entire source, including rows
currently outside the viewport.

Infinity scroll is different: it keeps only a moving client-side window and may
represent remote, unloaded positions with placeholders. Export does not call
`loadData` repeatedly and cannot discover records that have never been loaded.
To prevent a misleading partial workbook, direct export now fails with an
actionable error while `InfinityScrollPlugin` is active.

If you need a complete workbook, fetch the export dataset from the same backend
API and pass those rows to `ExportExcelPlugin` instead of relying on the visible
infinite-scroll grid. The demo export button uses a temporary hidden grid with
the same columns so the visible grid is not disturbed while the workbook is
generated.

## Best Practices

1. **Choose Appropriate Chunk Size**
   - Smaller chunks mean more frequent loading but less memory usage
   - Larger chunks mean fewer API calls but more memory usage

2. **Configure Buffer Size**
   - Larger buffers provide smoother scrolling but use more memory
   - Smaller buffers save memory but might cause more loading events

3. **Optimize Data Loading**
   - Implement server-side pagination in your API
   - Return only necessary data fields
   - Consider data compression for large datasets

4. **Handle Loading States**
   - Show loading indicators during data fetching
   - Handle errors gracefully
   - Consider implementing retry logic for failed requests

## Example with Loading State

```typescript
grid.infinityScroll = {
  chunkSize: 50,
  bufferSize: 100,
  loadData: async (skip, limit, order, singleConditionFilters) => {
    try {
      // Show loading state
      const response = await fetch(`/api/data?skip=${skip}&limit=${limit}&order=${JSON.stringify(order)}&filter=${JSON.stringify(singleConditionFilters)}`);
      const data = await response.json();
      // Hide loading state
      return data;
    } catch (error) {
      console.error('Failed to load data:', error);
      return []; // Return empty array on error
    } finally {
      // Hide loading state
    }
  },
};
```

This implementation provides efficient handling of large datasets while maintaining optimal performance and user experience.

---

# Installing RevoGrid Pro Products

URL: https://pro.rv-grid.com/guides/installation/
Source: src/content/docs/guides/installation.mdx
Description: Learn how to install RevoGrid Pro and standalone product packages using either a pre-built release or our private npm registry.

### Which Package Do I Need?

- Install `@revolist/revogrid-pro` when you need advanced Pro features (filters, editors, grouping, tree, export, etc.) without Pivot.
- Install `@revolist/pivot` for Pivot tables, Pivot Charts, and the Pivot configurator. Keep Pro installed alongside it.
- Install `@revolist/gantt` for project timelines and dependencies, `@revolist/scheduler` for event/resource scheduling, or `@revolist/kanban` for workflow boards. Each is independently installable alongside Pro.
- If you are evaluating the trial version, use the matching trial package name, such as `@revolist/pivot-trial`.

```bash
npm install @revolist/revogrid-pro
npm install @revolist/pivot
```

Trial install:

```bash
npm config set "@revolist:registry=https://trial.rv-grid.com"
npm install @revolist/revogrid @revolist/rv-pro-trial @revolist/pivot-trial
```

If you are unsure, start with Pro and add only the standalone product package you need. For trial projects, import CSS from `@revolist/rv-pro-trial/dist/rv-pro-trial.css`.

#### Next Steps

After installation, you can start using RevoGrid Pro and the standalone products in your project. Check out our other guides for:
- [Basic Usage](/guides)
- [Component API](/api/aggregations)
- [Simple Example](/guides/rows/row-odd/)
- [Framework Boilerplates](https://github.com/revolist/revogrid-pro-boilerplate.git)

Each framework has its own set of components and examples that demonstrate how to use RevoGrid Pro products effectively in your chosen framework environment.

---

# Github Installation Guide

URL: https://pro.rv-grid.com/guides/installation-github/
Source: src/content/docs/guides/installation-github.mdx
Description: Learn how to install RevoGrid Pro products using GitHub Packages

[Private GitHub Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)

  1.	Ensure you have access to the GitHub repository.
  2.	Authenticate your npm client with GitHub by creating a .npmrc file in your project directory or user home directory with the following content:

```json
@revolist:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=YOUR_PERSONAL_ACCESS_TOKEN
```

3. Replace `YOUR_PERSONAL_ACCESS_TOKEN` with a GitHub token that has `read:packages` and repo permissions.
4.  **Install the packages**. Run the following commands to install the latest versions from the private package registry:

  ```bash
  npm install @revolist/revogrid-pro@latest
  npm install @revolist/pivot@latest
  ```

For additional guidance on installing from GitHub’s private registry, please refer to the [official GitHub Packages documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry).

To jump start your project with all major frameworks, check out our [Framework Boilerplates](https://github.com/revolist/revogrid-pro-boilerplate.git).

## Supply Chain Metadata

RevoGrid Pro product releases include SBOM files and Sigstore release signatures.

- SBOM files are generated in SPDX JSON and CycloneDX JSON formats.
- Package tarballs are signed with Sigstore Cosign keyless signing in the release workflow.
- The signed tarball is the same tarball published to GitHub Packages.

For verification commands and related policy links, see [Security and Supply Chain](/legal/security).

---

# Local Installation Guide

URL: https://pro.rv-grid.com/guides/installation-local/
Source: src/content/docs/guides/installation-local.mdx
Description: Learn how to install RevoGrid Pro products using local files

---

###  Option 1: Directly Include in Builds
  - Copy the  into your project’s `assets` or `libs` folder.
  - Link the necessary JavaScript and CSS files in your HTML or import them into your JavaScript/TypeScript files.

```html
<script src="path/to/revogrid-pro.js"></script>
<link rel="stylesheet" href="path/to/revogrid-pro.css" />
```

Or in your module-based project:

```javascript
import 'path/to/revogrid-pro.js';
import 'path/to/revogrid-pro.css';

// If using build tools like Webpack or Vite:
// Add the ./release folder path to your resolve or alias configuration to reference the files.

resolve: {
  alias: {
    '@revogrid-pro': path.resolve(__dirname, 'path/to/release'),
  },
},
```

This option is particularly suitable for quick testing or projects that don’t rely on npm for dependency management.

---

###  Option 2: package.json Using Local Files

For projects where you want to use local versions of RevoGrid Pro products during development, you can reference the package files directly in your package.json.
This method is especially useful if you’re working with a cloned version of the repository or testing custom modifications.

Steps to Import Using Local Files:

1. Download files from the link above and extract them to a local folder.

2. Set Up Local References in package.json. In your project’s package.json file, reference the local folders containing Pro and the standalone products. For example:

  ```json
  {
    "dependencies": {
      "@revolist/revogrid-pro": "file:./release/pro",
      "@revolist/pivot": "file:./release/pivot"
    }
  }
  ```

3. Install Dependencies. Run the following command to install the local plugin:

  ```bash
  npm install
  ```

4. NPM will create a symlink to the specified folders, allowing you to use the local files as if they were npm packages. Import each plugin from its owning package:

  ```js
  import { ColumnStretchPlugin } from '@revolist/revogrid-pro';
  import { PivotPlugin } from '@revolist/pivot';
  ```

To jump start your project with all major frameworks, check out our [Framework Boilerplates](https://github.com/revolist/revogrid-pro-boilerplate.git).

---

# No-Build JavaScript Usage

URL: https://pro.rv-grid.com/guides/installation-no-build/
Source: src/content/docs/guides/installation-no-build.mdx
Description: Use a delivered RevoGrid Pro JavaScript build directly from the browser without a bundler.

Use this setup when you want to load a delivered RevoGrid Pro JavaScript build from a plain HTML file, a static page, or a server-rendered page that does not use a JavaScript build pipeline.

RevoGrid Pro is not published as a public browser CDN package. Use the JavaScript/CSS build delivered from the portal, or install the private npm package in projects that have a build step. The no-build example below assumes the delivered Pro `dist` files are copied into your app.

## Live Preview

This preview uses the same grid configuration as the no-build HTML example below.

1. Copy the delivered Pro build into your static assets.

   Keep the whole Pro `dist` folder together because the ESM entry imports sibling chunk files.

   ```txt
   public/
     vendor/
       revogrid-pro/
         revogrid-pro.js
         revogrid-pro.css
         revogrid-pro*.js
   ```

2. Add the Pro stylesheet from your hosted asset path.

   ```html
   <link
     rel="stylesheet"
     href="/vendor/revogrid-pro/revogrid-pro.css"
   />
   ```

3. Load the public RevoGrid Core web component from jsDelivr.

   ```html
   <script src="https://cdn.jsdelivr.net/npm/@revolist/revogrid@latest/dist/revo-grid/revo-grid.js"></script>
   ```

4. Add an import map for Core package imports and the delivered Pro bundle.

   The standalone Core script defines `<revo-grid>`. The `@revolist/revogrid` import map entry is still required because the Pro ESM bundle imports Core helpers by package name.

   ```html
   <script type="importmap">
     {
       "imports": {
         "@revolist/revogrid": "https://cdn.jsdelivr.net/npm/@revolist/revogrid@latest/dist/index.js",
         "@revolist/revogrid-pro": "/vendor/revogrid-pro/revogrid-pro.js"
       }
     }
   </script>
   ```

5. Import the Pro plugins from a module script.

   ```html
   <script type="module">
     import {
       AdvanceFilterPlugin,
       ColumnStretchPlugin,
       FilterHeaderPlugin,
       RowOddPlugin,
     } from "@revolist/revogrid-pro";

     const grid = document.querySelector("revo-grid");
     grid.plugins = [
       AdvanceFilterPlugin,
       ColumnStretchPlugin,
       FilterHeaderPlugin,
       RowOddPlugin,
     ];
   </script>
   ```

## Complete HTML Example

Save this as an HTML file and open it through any static web server. Do not use a `file://` URL; browser module imports should be served over HTTP.

<CodePreview
  files={[
    { label: 'index.html', lang: 'html', code: noBuildExample },
  ]}
/>

The Pro ESM bundle imports `@revolist/revogrid` as a package name. Browsers do not resolve npm package names by themselves, so the import map tells the browser where each package entry points in your hosted assets.

---

# NPM Installation Guide

URL: https://pro.rv-grid.com/guides/installation-npm/
Source: src/content/docs/guides/installation-npm.mdx
Description: Learn how to install RevoGrid Pro and standalone product packages using npm

**1. Configure NPM Registry**

First, configure npm to use the RevoGrid registry:

```bash
npm config set "@revolist:registry=https://npm.rv-grid.com"
```

The command npm config set `@revolist:registry=https://npm.rv-grid.com` is used to configure npm
(Node Package Manager) to use a specific registry for packages that are scoped under the `@revolist`
namespace.

---

**2. Install RevoGrid Pro and the Products You Need**

Install the core grid and Pro, then add only the standalone product you need. For example, to add Gantt:

```bash
npm install @revolist/revogrid
npm install @revolist/revogrid-pro
npm install @revolist/gantt
```

Use `@revolist/scheduler`, `@revolist/kanban`, or `@revolist/pivot` instead of Gantt when that is the product you need.

---

**3. Framework Integration Packages**

For better integration with specific frameworks, you can install the corresponding framework package:

**React**

```bash
npm install @revolist/react-datagrid
```

**Angular**

```bash
npm install @revolist/angular-datagrid
```

**Vue**

```bash
npm install @revolist/vue3-datagrid
```

**Svelte**

```bash
npm install @revolist/svelte-datagrid
```

Read more about [RevoGrid Pro Tokens](/guides/installation-token).

To jump start your project with all major frameworks, check out our [Framework Boilerplates](https://github.com/revolist/revogrid-pro-boilerplate.git).

---

# NPM Installation Guide

URL: https://pro.rv-grid.com/guides/installation-npm-trial/
Source: src/content/docs/guides/installation-npm-trial.mdx
Description: Learn how to install RevoGrid Pro and standalone product trial packages using npm

No account, token, npm login, licence key, form submission, or approval email is
required. A new developer can follow this page immediately from a clean shell.

Trial access uses separate package names and asset paths from the full paid packages. After purchasing, switch each product trial to `@revolist/<product>` and switch Pro trial to `@revolist/revogrid-pro`.

    Clone or inspect the working trial example:
    [github.com/revolist/revogrid-pro-trial](https://github.com/revolist/revogrid-pro-trial.git).

    Trial packages use names such as `@revolist/rv-pro-trial` and
    `@revolist/gantt-trial`, `@revolist/scheduler-trial`,
    `@revolist/kanban-trial`, and `@revolist/pivot-trial`, with matching CSS filenames.

**1. Configure NPM Registry**

First, configure npm to use the public RevoGrid trial registry. No token or login is required:

```bash
npm config set "@revolist:registry=https://trial.rv-grid.com"
```

This command routes the `@revolist` scope through the public trial registry.
It does not change the default registry used for unscoped packages.

---

**2. Install RevoGrid Pro Trial**

Install the core grid and RevoGrid Pro trial package:

```bash
npm install @revolist/revogrid
npm install @revolist/rv-pro-trial
```

Use Pro exports from the trial package and import the trial CSS file:

```typescript
import '@revolist/rv-pro-trial/dist/rv-pro-trial.css';
import { RowOddPlugin } from '@revolist/rv-pro-trial';
```

Do not use the full package CSS path with the trial package:

```typescript
// Incorrect for trial packages
import '@revolist/rv-pro-trial/dist/revogrid-pro.css';
```

---

**3. Install a Standalone Product Trial**

Install only the product trial you need:

```bash
npm install @revolist/gantt-trial
# or: @revolist/scheduler-trial, @revolist/kanban-trial, @revolist/pivot-trial
```

Product trials build on Pro trial, so keep `@revolist/rv-pro-trial` installed.

```typescript
import '@revolist/rv-pro-trial/dist/rv-pro-trial.css';
import '@revolist/pivot-trial/dist/pivot-trial.css';
import { PivotPlugin, type PivotConfig } from '@revolist/pivot-trial';
import { commonAggregators } from '@revolist/rv-pro-trial';
```

Minimal Pivot setup:

```typescript
import { defineCustomElements } from '@revolist/revogrid/loader';
import '@revolist/rv-pro-trial/dist/rv-pro-trial.css';
import '@revolist/pivot-trial/dist/pivot-trial.css';
import { PivotPlugin, type PivotConfig } from '@revolist/pivot-trial';
import { commonAggregators } from '@revolist/rv-pro-trial';

defineCustomElements();

const grid = document.createElement('revo-grid');

const pivot: PivotConfig = {
  dimensions: [
    { prop: 'age' },
    {
      name: 'Date of Birth',
      prop: 'dateOfBirth',
      aggregators: {
        count: commonAggregators.count,
      },
    },
  ],
  rows: ['age'],
  values: [{ prop: 'dateOfBirth', aggregator: 'count' }],
  hasConfigurator: true,
};

grid.plugins = [PivotPlugin];
grid.pivot = pivot;
grid.source = [
  { name: 'John Doe', age: 25, dateOfBirth: '1998-01-15' },
  { name: 'Jane Smith', age: 30, dateOfBirth: '1993-03-22' },
];

document.getElementById('app')?.appendChild(grid);
```

Collaborative Editing is separately installed so applications that do not need
realtime editing do not load Yjs:

```bash
npm install @revolist/revogrid-collaborative-editing-trial
```

Import its API from the trial package and keep the main Pro trial installed for
`EventManagerPlugin` and other grid integrations:

```typescript
import { EventManagerPlugin } from '@revolist/rv-pro-trial';
import { CollaborativeEditingPlugin } from '@revolist/revogrid-collaborative-editing-trial';
```

---

**4. Framework Integration Packages**

For better integration with specific frameworks, you can install the corresponding framework package:

**React**

```bash
npm install @revolist/react-datagrid
```

**Angular**

```bash
npm install @revolist/angular-datagrid
```

**Vue**

```bash
npm install @revolist/vue3-datagrid
```

**Svelte**

```bash
npm install @revolist/svelte-datagrid
```

---

**5. Verify a Complete Starter**

The maintained starter declares its supported Node and pnpm versions. From a
clean clone:

```bash
git clone https://github.com/revolist/revogrid-pro-trial.git
cd revogrid-pro-trial
corepack enable
corepack install
pnpm install --frozen-lockfile
pnpm build
pnpm dev
```

To run its Chromium smoke tests on a machine that has never used Playwright:

```bash
pnpm test:e2e:install
pnpm test:e2e
```

The starter includes Tree, Pivot, Gantt, and Scheduler examples. Kanban is
installable as `@revolist/kanban-trial` but is not mounted in this starter.
Collaborative Editing is separately installable as
`@revolist/revogrid-collaborative-editing-trial` but is not mounted in this
starter. See the complete
[trial feature inventory](/legal/trial/#trial-feature-inventory).

---

# Build from Source

URL: https://pro.rv-grid.com/guides/installation-source/
Source: src/content/docs/guides/installation-source.mdx
Description: Learn how to build RevoGrid Pro and standalone products from source

For maximum control, you can build RevoGrid Pro and the standalone product packages from source.
This allows you to customize the build process if needed.

1. Clone the repository and navigate to the project directory.

```bash
git clone https://github.com/revolist/revogrid-pro.git
cd revogrid-pro
```

2. Run the build commands for Pro and the products you need.

```bash
pnpm build:pro
pnpm build:pivot
pnpm build:gantt
pnpm build:scheduler
pnpm build:kanban
```

3. After the build completes, the generated files are available in each package's `dist` folder, for example `/packages/pro/dist`, `/packages/pivot/dist`, and `/packages/gantt/dist`.

Choose the method that best suits your workflow, and install only the RevoGrid Pro products your application needs.

---

# Access Token Installation Guide

URL: https://pro.rv-grid.com/guides/installation-token/
Source: src/content/docs/guides/installation-token.mdx
Description: Learn how to use access tokens with RevoGrid Pro NPM Registry

Access tokens provide a secure way to authenticate with the RevoGrid Pro repository, especially useful for CI/CD environments or multi-user repository access. Instead of using password authentication, you can create and manage tokens for secure authorization.

### Prerequisites

Before creating access tokens, you must first configure and login to the npm server. Please follow the [NPM Installation Guide](/guides/installation-npm) instructions first.

### Creating an Access Token

To create a new token using the command line, run:

```bash
npm token create --registry=https://npm.rv-grid.com
```

You will be prompted for your password. After entering it, a new token will be displayed in the console:

```bash
┌──────────┬─────────────────────────┐
│ token    │ Ihj...                │
├──────────┼─────────────────────────┤
│ user     │ your-username           │
├──────────┼─────────────────────────┤
│ cidr     │                         │
├──────────┼─────────────────────────┤
│ readonly │ false                   │
├──────────┼─────────────────────────┤
│ created  │ 2025-03-21T01:02:03.00Z │
└──────────┴─────────────────────────┘
```

Make sure to copy and securely store the token value.

### Viewing Access Tokens

To view all your available tokens:

```bash
npm token list --registry=https://npm.rv-grid.com
```

This will display a list of all your active tokens:

```bash
┌────────┬─────────┬────────────┬──────────┬────────────────┐
│ id     │ token   │ created    │ readonly │ CIDR whitelist │
├────────┼─────────┼────────────┼──────────┼────────────────┤
│ b54f12 │ eyJhb.… │ 2024-03-21 │ no       │                │
└────────┴─────────┴────────────┴──────────┴────────────────┘
```

### Removing an Access Token

To remove a token, use its ID from the token list:

```bash
npm token delete tokenId --registry=https://npm.rv-grid.com
```

### Using Tokens in Your Project

You can use access tokens by creating a `.npmrc` file in your project directory with the following content:

```ini
@revolist:registry=https://npm.rv-grid.com
//npm.rv-grid.com/:_authToken=YOUR-AUTH-TOKEN
```

Replace `YOUR-AUTH-TOKEN` with the token value you received when creating the token.

### Token File Locations

The `.npmrc` file can be stored in several locations, which npm checks in the following order:

1. Project-specific: `/path/to/your/project/.npmrc`
2. User-specific: `~/.npmrc`
3. Global: `$PREFIX/etc/npmrc`
4. npm built-in: `/path/to/npm/npmrc`

### CI/CD Integration

For Continuous Integration/Continuous Delivery (CI/CD) systems, you can use access tokens stored in `.npmrc`. Add the following to your CI/CD environment's `.npmrc` file:

```ini
@revolist:registry=https://npm.rv-grid.com
//npm.rv-grid.com/:_authToken=YOUR-AUTH-TOKEN
```

### Multi-user Access

For teams working on the same project, you have two options for repository access:

1. **Individual Logins**: Each developer can use their own credentials to access the repository
2. **Shared Tokens**: Create and share access tokens among team members

### Troubleshooting

If you encounter issues with token authentication:

1. Verify your token is valid by running `npm token list`
2. Ensure your `.npmrc` file is properly formatted
3. Check that you're using the correct registry URL
4. Verify your network can access the npm registry

For additional support or questions, please contact our support team.

To jump start your project with all major frameworks, check out our [Framework Boilerplates](https://github.com/revolist/revogrid-pro-boilerplate.git).

---

# RevoGrid Kanban

URL: https://pro.rv-grid.com/guides/kanban/
Source: src/content/docs/guides/kanban/index.mdx
Description: Render the same RevoGrid source as an accessible, virtualized Kanban board with workflow columns, swimlanes, WIP rules, and customizable cards.
Surface: kanban

`KanbanPlugin` turns canonical `grid.source` rows into workflow cards without creating a second data model. Configured workflow columns become RevoGrid columns and optional swimlanes expand into native card rows. Every workflow cell contains at most one card, so RevoGrid owns both horizontal and vertical virtualization.

## Install

```bash
pnpm add @revolist/revogrid @revolist/revogrid-pro @revolist/kanban
```

```ts
import '@revolist/revogrid-pro/dist/revogrid-pro.css';
import '@revolist/kanban/styles.css';
```

    Keep cards in `grid.source`. Set `grid.kanban` to show the board and set it to `false` to restore the latest cards and table columns.

    RevoGrid providers own projected data, columns, dimensions, focus, viewport state, and plugin dependencies.

    Reorder cards, move across columns or lanes, drag a multi-selection, validate transitions, and enforce WIP limits.

    Replace card, header, lane, empty-state, and drag-preview content while the managed shell preserves interaction and accessibility.

## Minimal setup

```ts
import { KanbanPlugin, type KanbanConfig } from '@revolist/kanban';

const kanban: KanbanConfig = {
  columns: [
    { prop: 'todo', name: 'To do' },
    { prop: 'doing', name: 'In progress', wipLimit: 3 },
    { prop: 'done', name: 'Done' },
  ],
  card: { titleField: 'title', descriptionField: 'description' },
};

grid.plugins = [KanbanPlugin];
grid.kanban = kanban;
grid.kanbanCardEditorDialog = {};
grid.source = [
  { id: 'card-1', title: 'First card', status: 'todo', order: 1000 },
];
```

The default fields are `id`, `status`, and `order`. Configure `idField`, `columnField`, or `orderField` when your application uses other names.

`columns` is optional so Kanban can be enabled before workflow metadata or data
loads. An empty configuration and empty source render a stable empty board. If
cards arrive before columns, they remain visible in the managed **Unmapped**
column until the workflow configuration is supplied.

## How the projection works

```txt
canonical grid.source cards
        + KanbanConfig
              │
              ▼
  validated card and bucket indexes
              │
              ▼
RevoGrid columns + expandable swimlane card rows
```

Your application owns the card records and persistence. Kanban owns projection, interaction, validation, and local provider updates. Move events describe the exact changes to persist.

## Recommended path

1. Define stable card IDs and explicit [workflow columns](/guides/kanban/data-model/).
2. Add [swimlanes, WIP limits, and card rules](/guides/kanban/swimlanes-wip-rules/) if the workflow needs capacity or policy controls.
3. Configure the [packaged card editor or a replacement UI](/guides/kanban/card-editor/).
4. Connect [events and public methods](/guides/kanban/events-methods/) to application persistence.
5. Add [custom card content and translations](/guides/kanban/customization-i18n/).
6. Verify [accessibility and performance](/guides/kanban/accessibility-performance/) with production-sized data.

  Kanban is a presentation plugin rather than an application toolbar. Your application controls the table/Kanban switch by setting `grid.kanban`.

---

# Accessibility And Performance

URL: https://pro.rv-grid.com/guides/kanban/accessibility-performance/
Source: src/content/docs/guides/kanban/accessibility-performance.mdx
Description: Operate Kanban without a pointer and keep large boards responsive through native row virtualization and stable card identity.
Surface: kanban

## Accessibility contract

- The managed card shell exposes selection, read-only, invalid, and drag state without depending on custom card content.
- Each selectable card shell is keyboard focusable. Space picks up or drops, arrows move the proposed target, and Escape cancels. Enter requests the card-edit workflow and Shift+F10 opens the card context menu.
- Ctrl+Space or Cmd+Space toggles the focused card in the managed multi-selection. Shift+Space extends the selection from the current anchor. Keyboard pickup first synchronizes selection when the focused card was not already selected.
- A live region announces selection, pickup, target position, validation failures, completion, and cancellation using `KanbanLabels`.
- Cards expose checkbox selection state, read-only and invalid identity state, plus their supported keyboard shortcuts. Focus uses a persistent high-contrast outline that is distinct from the selected-card treatment.
- Column and swimlane controls have localized expand/collapse names.
- Motion used for card hover and disclosure controls is removed when the operating system requests reduced motion.
- Custom content should use meaningful headings and text, mark nested interactive controls so they do not initiate card movement, and maintain sufficient contrast for rule states.

Automated Kanban browser coverage verifies focus, selection modifiers, keyboard movement, live-region semantics, and reduced-motion CSS. Before release, also test custom cards at 200% and 400% zoom, in forced-colors/high-contrast mode, with keyboard-only navigation, and with the screen reader/browser combinations your application supports.

## Native row virtualization

RevoGrid virtualizes workflow columns and the projected card rows. A cell contains at most one card, avoiding nested virtual scrollers and keeping card focus, drag targets, and row ownership aligned with the grid provider model.

Use `cardRowHeight` to reserve equal space for every card row. Choose a value that fits the number of content bands in your card template; individual swimlane definitions can override it with `height`. RevoGrid virtualizes those rows directly, while card identity and canonical rank remain independent of the rendered row index.

```ts
grid.kanban = {
  columns,
  cardRowHeight: 176,
  customization: { cardContent },
};
```

Card content is contained within its reserved row, so an undersized custom template cannot overlap the next card. Increase `cardRowHeight` when adding metadata rows rather than relying on content overflow.

## Large-board guidance

- Use stable primitive IDs and finite numeric ranks.
- Keep render hooks pure and avoid creating network requests, timers, or global listeners inside templates.
- Put expensive derived values on the card record or memoize them outside the template.
- Configure `cardRowHeight` to fit the complete managed or custom card shell while keeping every projected row uniform.
- For known large server datasets, configure `kanban.remote.total` and `placeholder`; unloaded card rows use the same indexed skeleton pattern as Infinity Scroll.
- In placeholder mode, known positions participate in unfiltered visible counts and total/WIP counts, while placeholders remain non-interactive. Local filters still evaluate the records currently available to the board.
- Indexed page replacement and unfiltered card moves patch affected projection buckets, keeping interaction work independent from a full 100K projection rebuild.
- Persist committed move batches rather than rewriting the entire dataset for every pointer update.

The Kanban acceptance fixture covers 5,000 visible cards and verifies that rendered card DOM stays bounded while drag targets remain correct after virtual scrolling.

---

# Kanban Card Editor

URL: https://pro.rv-grid.com/guides/kanban/card-editor/
Source: src/content/docs/guides/kanban/card-editor.mdx
Description: Add the packaged Kanban CRUD dialog, map default or arbitrary fields, and replace the editor with application UI.
Surface: kanban

`KanbanCardEditorDialogPlugin` is a separate companion plugin that `KanbanPlugin` installs by default. It listens to the existing cancelable create, edit, and delete request events, then uses `KanbanPlugin`'s canonical mutation methods and history integration. The separate Open request remains application-owned for products that provide a distinct read-only detail view.

```ts
import { KanbanPlugin } from '@revolist/kanban';

grid.plugins = [KanbanPlugin];
grid.kanban = kanban;
grid.kanbanCardEditorDialog = {
  fields: [{
    id: 'points', label: 'Story points', kind: 'number', field: 'points',
    validate: (value) => Number(value) < 0 ? 'Story points cannot be negative.' : undefined,
  }],
};
```

The packaged form includes title, description, workflow status, swimlane, priority, tags, assignees, progress, start/end schedule, due date, and color. Matching schema IDs override those fields, `hiddenFields` removes them, and `fieldOrder` sets layout order. Additional schemas can map any `ColumnProp`, or use `read` and `write` for composite application records.

Field schemas support text, textarea, number, select, multiselect, tags, checkbox, date, datetime, color, assignees, and custom DOM controls. They can also provide icons, options, placeholders, defaults, parsing, formatting, readonly/required state, synchronous or asynchronous validation, and renderer cleanup lifecycles.

Assignee fields use the same resource picker as Scheduler and Gantt. Supply
schema `options` when your application owns a people directory. If the packaged
field has no explicit options, the editor derives a unique picker catalog from
the canonical Kanban cards through `card.assignees`, or `assigneeField` plus
`assigneeAvatarField`. Explicit options remain authoritative, and existing
mapped selections stay visible even before a directory is loaded.

## Validation

Each visible field runs its required check and synchronous or asynchronous
`validate` callback. Use the editor-level `validate` callback for cross-field or
remote rules; return a form message or a record keyed by field ID.

```ts
grid.kanbanCardEditorDialog = {
  fields: [{
    id: 'points', field: 'points', kind: 'number', required: true,
    validate: async (value) => await api.pointsError(value),
  }],
  validate: ({ draft }) => draft.startDate > draft.dueDate
    ? { dueDate: 'Due date must follow the start date.' }
    : undefined,
};
```

The validation lifecycle is observable through
`beforekanbancardeditorvalidate`, `beforekanbancardeditorfieldvalidate`,
`kanbancardeditorfieldvalidate`, `kanbancardeditorvalidate`, and
`kanbancardeditorinvalid`. The two `before...` events are cancelable. Their
details expose `setError`, allowing application validators to add field or form
errors without replacing editor persistence. Cancelled or invalid validation
always keeps the editor open and blocks the Kanban mutation.

Replacement editors call `context.controller.validate()` to run the same rules
and events as the packaged dialog. The plugin instance also exposes `validate()`
for an open editor.

## Persistence and identifiers

By default, Save calls `createCard` or `updateCard`, Delete calls `deleteCards`, and every successful operation is undoable. The fallback create ID is a collision-checked string. Use `createCardId` for numeric or domain IDs.

Use `onSubmit` and `onDelete` for remote persistence. Returning `false` tells the plugin that the application handled the mutation. Errors thrown by async hooks remain visible without closing the dialog.

## Replace or disable the editor

Set `grid.kanbanCardEditorDialog = false` or cancel the request event to retain an application-owned workflow. Explicitly registering `KanbanCardEditorDialogPlugin` remains supported and the Kanban dependency lifecycle reuses that instance. A full `customization.editor` DOM renderer receives the draft state and controller, so React, Vue, Angular, and other application UI can mount in place of the packaged modal.

```ts
grid.kanbanCardEditorDialog = {
  customization: {
    editor: {
      mount(container, context) {
        return mountApplicationEditor(container, context.controller);
      },
    },
  },
};
```

---

# Customization And i18n

URL: https://pro.rv-grid.com/guides/kanban/customization-i18n/
Source: src/content/docs/guides/kanban/customization-i18n.mdx
Description: Customize Kanban cards, headers, drag previews, empty states, CSS variables, labels, and locale-aware output.
Surface: kanban

## Managed card shell

Kanban owns the outer card shell, focus target, selection state, whole-card drag behavior, rule classes, and accessibility attributes. `customization.cardContent` replaces everything visible inside it.

```ts
customization: {
  cardContent: (h, { card, selected, badges }) =>
    h('div', { class: 'issue-card' }, [
      h('strong', null, card.summary),
      h('small', null, `${card.owner} · ${card.points} points`),
      selected ? h('span', null, 'Selected') : null,
      ...badges.map((badge) => h('span', { class: badge.className }, badge.label)),
    ]),
  cardProps: ({ card }) => ({
    class: card.blocked ? 'issue-card-shell--blocked' : '',
    title: card.summary,
  }),
}
```

The same customization object supports `dragPreview`, `swimlaneHeader`,
`swimlaneColumnHeader`, and `emptyState` templates. The swimlane-header context
reports `swimlaneColumnCollapsed`; compact mode keeps a managed vertical title
badge so labels remain readable. Template contexts use canonical cards and
projected metadata; do not query card DOM to recover product state.

## Swimlane header templates

Set `swimlaneTemplate` on an explicit swimlane when that lane needs to own its
complete header layout. This works in both `column` and `top` swimlane layouts:

```ts
grid.kanban = {
  ...config,
  swimlaneField: 'workstream',
  swimlaneLayout: 'top',
  swimlanes: [
    {
      id: 'product',
      title: 'Product experience',
      collapsible: true,
      swimlaneTemplate: (h, context) => h('div', { class: 'workstream-header' }, [
        h('span', { class: 'workstream-header__icon', 'aria-hidden': 'true' }, '◈'),
        h('span', { class: 'workstream-header__kicker' }, 'WORKSTREAM'),
        h('strong', null, context.swimlane.title),
        h('span', null, `${context.visibleCount} / ${context.totalCount}`),
        h('button', {
          type: 'button',
          onClick: context.toggleCollapsed,
        }, context.swimlane.collapsed ? 'Expand' : 'Collapse'),
      ]),
    },
  ],
};
```

`swimlaneTemplate` fully replaces the managed title, count, WIP badges, and
collapse button for that lane. Render the pieces your product needs and call
`context.toggleCollapsed()` when the custom header exposes collapse. The action
is guarded by the lane's `collapsible` setting. Kanban continues to own the
outer group row, lane identity, configured style, and accessibility label.

A definition-owned template takes precedence over
`customization.swimlaneHeader`. Lanes without one keep the board-wide custom
content or the default header.

## Workflow header templates

Set `columnTemplate` and `columnProperties` directly on a workflow definition,
using the same shape as a RevoGrid column:

```ts
grid.kanban = {
  ...config,
  columns: [
    {
      prop: 'active',
      name: 'Active',
      size: 280,
      wipLimit: 4,
      columnProperties: () => ({
        class: 'workflow-header-cell',
        style: { backgroundColor: 'var(--active-header)' },
      }),
      columnTemplate: (h, props, additionalData) => {
        const { column, visibleCount, totalCount, overWipLimit, toggleCollapsed } = props.kanban;
        const name = column.name ?? String(column.prop);
        return h('div', { class: overWipLimit ? 'workflow-header workflow-header--over' : 'workflow-header' }, [
          h('strong', null, name),
          h('span', null, `${visibleCount} / ${totalCount}`),
          h('button', { type: 'button', onClick: toggleCollapsed }, 'Toggle'),
          additionalData?.workspaceName
            ? h('small', null, additionalData.workspaceName)
            : null,
        ]);
      },
    },
  ],
};
```

`columnTemplate` fully replaces the inner managed workflow header. Kanban does
not append its default name, count, WIP badge, or collapse button, so render the
pieces your product needs and call `props.kanban.toggleCollapsed()` when the
custom header exposes collapse. Application `additionalData` is passed through
unchanged. RevoGrid's outer resizable header remains managed.

`columnProperties` is composed with Kanban's required header properties through
the shared Pro merging behavior: classes and styles combine, while required
workflow identity and interaction attributes win conflicts. Collapsed body
rails deliberately render `name` (or `String(prop)`) instead of invoking the
header template.

## Default content

Configure `card.titleField` and `card.descriptionField`, or provide formatter callbacks. The title defaults to the `title` field and falls back to the card ID.

Default cards can also render shared progress and assignee content without a
custom template:

```ts
grid.kanban = {
  ...config,
  card: {
    titleField: 'name',
    startDateField: 'startDate',
    endDateField: 'endDate',
    dateTimeZone: 'UTC',
    progressField: 'percentDone',
    assigneeField: 'owners',
    assigneeAvatarField: 'ownerAvatars',
  },
};
```

Assignee and avatar fields accept either scalar values or parallel arrays. For
The default date range appears directly after the card title and uses the
configured Kanban locale and optional `dateTimeZone`. For fully custom cards,
the managed shell continues to own focus, selection, accessibility, and drag
behavior.

## Labels and locale

English labels are bundled. Pass a partial `labels` object to replace every visible or assistive string used by your product:

```ts
grid.kanban = {
  ...config,
  locale: 'pt-PT',
  labels: {
    emptyColumn: 'Sem cartões',
    dropCardHere: 'Soltar um cartão aqui',
    editCard: 'Editar cartão',
    addCardHere: 'Adicionar cartão aqui',
    deleteCard: 'Eliminar cartão',
    cardContextMenu: 'Ações do cartão Kanban',
    cardCount: (visible, total) => `${visible} de ${total} cartões`,
    moveBlocked: (reason) => `Movimento bloqueado: ${reason}`,
  },
};
```

`locale` controls locale-aware query normalization for built-in card search and
the default date-range component. Other number and product-specific display
formatting remains template-owned. Kanban does not automatically download a
translation pack.

## CSS

Import the standalone Kanban stylesheet once:

```ts
import '@revolist/kanban/styles.css';
```

Prefer Kanban CSS variables and classes returned by card rules or customization hooks. Avoid changing managed-shell focus, selection, and drag-state elements in ways that hide their state.

Kanban follows the grid's `material`, `compact`, `darkMaterial`, and
`darkCompact` themes automatically. Its defaults derive from RevoGrid's public
`--revo-grid-*` tokens, while the semantic `--kanban-board-background`,
`--kanban-surface`,
`--kanban-card-background`, `--kanban-border`, `--kanban-text`,
`--kanban-muted`, `--kanban-accent`, and `--kanban-accent-strong` variables let
the host tune either theme without replacing component styles. Drag previews
copy the resolved Kanban tokens, so a body-mounted preview retains the active
dark theme.

---

# Cards, Columns, And Ordering

URL: https://pro.rv-grid.com/guides/kanban/data-model/
Source: src/content/docs/guides/kanban/data-model.mdx
Description: Define canonical Kanban cards, workflow columns, stable ranks, diagnostics, and board projection behavior.
Surface: kanban

## Canonical cards

Kanban reads and updates ordinary RevoGrid source rows. A card needs a stable ID, workflow-column value, and preferably a numeric order:

```ts
grid.source = [
  {
    workId: 'PAY-104',
    summary: 'Retry declined payments',
    stage: 'active',
    rank: 1000,
    team: 'billing',
  },
];

grid.kanban = {
  idField: 'workId',
  columnField: 'stage',
  orderField: 'rank',
  swimlaneField: 'team',
  columns: [
    { prop: 'queued', name: 'Queued' },
    { prop: 'active', name: 'Active' },
    { prop: 'done', name: 'Done' },
  ],
};
```

When a card has no rank, source order is used. The first move assigns fractional ranks between neighboring cards. If the available numeric gap becomes unsafe, Kanban rebalances only the destination bucket and reports the affected IDs in `kanbancardmove`.

## Shared view fields

Use `kanban.fields` when the same application records also feed Scheduler or
Gantt. The keys describe field meaning and the values name properties in your
source rows:

```ts
grid.kanban = {
  fields: {
    id: 'id',
    title: 'name',
    status: 'workflowStatus',
    start: 'startDate',
    end: 'endDate',
    color: 'color',
    progress: 'percentDone',
    resourceId: 'owner',
  },
  columns: [
    { prop: 'todo', name: 'To do' },
    { prop: 'doing', name: 'In progress' },
    { prop: 'done', name: 'Done' },
  ],
};
```

Kanban defaults these meanings to `id`, `title`, `status`, `startDate`,
`endDate`, `color`, `progress`, and `assignees`. An explicitly mapped shared
key takes precedence over the corresponding `idField`, `columnField`, or
`card.*Field` option. The older options remain available for existing boards.

The mapping only selects properties. It does not convert dates or progress
units. `resourceId` represents one resource identifier; Kanban also continues
to accept the established array form through `card.assigneeField`. Fields that
Kanban does not change, including application metadata, remain on the original
card. Moves, editor changes, remote updates, and undo/redo preserve authored
property names and do not add internal Kanban aliases to source rows.

## Remote card pages

Use `kanban.remote` when the canonical collection should arrive from one
whole-board offset/limit stream:

```ts
const loadCards = async (skip: number, limit: number) => {
  const response = await fetch(`/api/cards?skip=${skip}&limit=${limit}`);
  const result = await response.json();
  return {
    data: result.cards,
    total: result.total,
  };
};

grid.kanban = {
  columns,
  remote: {
    loadData: loadCards,
    total: 100_000,
    chunkSize: 100,
    preloadThreshold: 0.75,
    placeholder: (index) => ({
      id: `remote-${index}`,
      status: statuses[index % statuses.length],
      order: Math.floor(index / statuses.length),
    }),
  },
};
```

With `total` and `placeholder`, Kanban works like Infinity Scroll: it creates the
known number of lightweight positions, renders an animated skeleton for each
unloaded card row, and replaces the requested 100-card slice in place. The
placeholder only needs a unique temporary `id`, workflow column, swimlane when
configured, and rank fields. Its ID may differ from the returned server card ID;
the source offset owns replacement identity. The workflow, swimlane, and rank
values must match the corresponding server card. Scrolling directly to an
unloaded area requests that area's chunk; approaching a loaded chunk boundary
preloads the next one.

Without `placeholder`, remote mode retains append paging: page zero replaces
the current cards and later pages append as the board nears its scroll boundary.
Both modes preserve loaded cards on errors and expose the same inline retry
action.

The result can be a card array or `{ data, total?, hasMore? }`. In append mode,
a returned `total` takes precedence over `hasMore`; otherwise an explicit
`hasMore` wins, then the configured or previously returned total is consulted,
and only then does a short page end the stream. Indexed mode treats the
configured `total` as its fixed layout: every request must return its complete
requested slice, and response `total` or `hasMore` values must agree with that
layout. A mismatch keeps the slice retryable and emits the remote error event.

Local update and move operations preserve indexed server positions. Create and
delete are rejected in indexed mode because they would shift every later
offset; perform those operations on the server and call `refreshRemote()`.
Replacing `grid.source` externally restarts indexed loading from page zero. In
append mode, local CRUD does not rewind the cursor and an external source
replacement adopts its length as the next offset. Both behaviors invalidate a
late response.

The loader type and indexed chunk behavior are shared with
`InfinityScrollPlugin`, so the same application adapter can power a table or
Kanban view. Kanban needs the additional placeholder factory because an
unloaded card's workflow column and optional swimlane cannot be inferred from a
global total. The two plugins should not own one grid simultaneously because
Kanban projects cards into its own virtual rows.

## Workflow columns

`kanban.columns` is the workflow schema; `grid.columns` remains the canonical
table/card-field schema. A card belongs to a workflow column when
`card[columnField] === column.prop`.

Workflow definitions reuse the safe RevoGrid header and sizing subset and add
Kanban behavior such as WIP limits, collapse state, transition rules, metadata,
and card filtering.

The array is optional and defaults to `[]`. This supports loading workflow
metadata and cards independently: no columns plus no cards is an empty board,
while cards without configured columns use the managed **Unmapped** column by
default. Supplying workflow columns later rebuilds the projection from the same
canonical `grid.source` records.

```ts
columns: [
  { prop: 'queued', name: 'Queued', size: 260 },
  {
    prop: 'active',
    name: 'Active',
    minSize: 240,
    maxSize: 360,
    wipLimit: 4,
    allowedFrom: ['queued', 'active'],
    collapsible: true,
  },
]
```

Projected workflow columns keep the exact authored `prop`; no synthetic grid
property is introduced. If `name` is omitted, Kanban displays `String(prop)`.
The default `size` is 288 and `minSize` is 220. The core column-move plugin
handles header dragging; `kanbancolumnorderchange` exposes the resulting prop
order for persistence.

Every workflow column is collapsible by default. Set `collapsible: false` to lock a column open, or use `collapsed: true` for its initial state. At runtime, `setColumnCollapsed(prop, collapsed)` changes one column and `getCollapsedColumnProps()` returns the active collapsed set. A collapsed column remains visible as a narrow rail with a vertical resolved-name badge, so users can restore it without losing board context.

## Unknown and invalid data

- Unknown statuses render in a localized **Unmapped** column by default. Set `unmappedColumn: false` only when the host deliberately hides them.
- Missing or duplicate card IDs produce blocking diagnostics. Those cards remain visible but cannot be moved.
- Duplicate column props produce a blocking configuration diagnostic.
- Invalid numeric ranks fall back to source order and produce a diagnostic.

Listen to `kanbandiagnostics` or call `getDiagnostics()` on the plugin during development and after remote data refreshes.

## Counts

Column and swimlane headers distinguish:

- **visible count**: cards passing RevoGrid filters, Kanban search, and the optional predicate;
- **total count**: all canonical cards in that bucket.

WIP limits always use total counts so a filter cannot accidentally permit over-capacity work.

In append mode, both counts describe the cards loaded so far. In indexed mode,
known placeholder positions participate in total and visible counts, so loading
a page does not change an unfiltered header count. Placeholders remain
non-interactive, and active filters can exclude positions that cannot match.
Enforce server-side rules in the application whenever Kanban does not have the
authoritative records needed for the decision.

---

# Events And Methods

URL: https://pro.rv-grid.com/guides/kanban/events-methods/
Source: src/content/docs/guides/kanban/events-methods.mdx
Description: Validate and persist Kanban moves, observe selection and diagnostics, request CRUD flows, and call public plugin methods.
Surface: kanban

['gridedit', 'Unified committed card changes from EventManager; inspect kanban-card-change and typed domainChanges.'],
  ['beforekanbancardmove', 'Cancelable proposal with cards, previous locations, target, reason, and proposed records.'],
  ['kanbancardmove', 'Committed moved cards, every changed canonical record, locations, and destination-bucket rebalance IDs.'],
  ['kanbanselectionchange', 'Selected card IDs/records and replace, toggle, range, clear, or API reason.'],
  ['kanbancolumnorderchange', 'Runtime workflow column order after native header drag or API movement.'],
  ['kanbandropstatechange', 'Current valid, invalid, or order-preserving no-op target state and localized reason.'],
  ['kanbandiagnostics', 'Current source/config diagnostics.'],
  ['kanbancardcreaterequest', 'Host-owned create workflow request.'],
  ['kanbancardopenrequest', 'Host-owned card detail request; the packaged editor does not consume it.'],
  ['kanbancardeditrequest', 'Host-owned card editor request.'],
  ['kanbancarddeleterequest', 'Host-owned delete workflow request.'],
  ['beforekanbancardcreate / kanbancardcreate', 'Cancelable create proposal and committed canonical card.'],
  ['beforekanbancardupdate / kanbancardupdate', 'Cancelable update proposal and committed card with previous record.'],
  ['beforekanbancarddelete / kanbancarddelete', 'Cancelable atomic delete proposal and committed card batch.'],
  ['beforekanbancardeditorvalidate', 'Cancelable start of packaged or replacement-editor validation; listeners can add errors.'],
  ['beforekanbancardeditorfieldvalidate', 'Cancelable per-field validation proposal with value and setError.'],
  ['kanbancardeditorfieldvalidate', 'Committed valid, invalid, skipped, or cancelled result for one editor field.'],
  ['kanbancardeditorvalidate', 'Completed editor validation result with valid, cancelled, and errors.'],
  ['kanbancardeditorinvalid', 'Validation completion that blocked submission because errors or cancellation remain.'],
  ['kanbanremoteloadstart', 'A whole-board page request started with skip, limit, reason, and current remote state.'],
  ['kanbanremoteloadsuccess', 'A page was committed to canonical cards; detail includes the returned cards and updated state.'],
  ['kanbanremoteloaderror', 'A page failed without removing loaded cards; detail includes the error and retryable state.'],
];

## Get the plugin

```ts
import { KanbanPlugin } from '@revolist/kanban';

const plugins = await grid.getPlugins();
const kanban = plugins.find((plugin) => plugin instanceof KanbanPlugin);
```

Public methods are `getCards`, `getConfig`, `getProjection`, `createCard`, `updateCard`, `deleteCards`, `moveCards`, `getSelectedCardIds`, `setSelectedCardIds`, `revealCard`, `getColumnOrder`, `setColumnOrder`, `getCollapsedColumnProps`, `setColumnCollapsed`, `getSwimlaneColumnCollapsed`, `setSwimlaneColumnCollapsed`, `refresh`, `getDiagnostics`, `getRemoteState`, `loadMoreCards`, `refreshRemote`, `requestCreateCard`, `requestOpenCard`, `requestEditCard`, and `requestDeleteCards`. Obtain the plugin from RevoGrid rather than installing reverse callbacks on the grid element.

`await kanban.revealCard(cardId)` scrolls a currently rendered card's native
grid row and workflow column into view. It resolves to `false` when the card is
missing, filtered, or hidden by collapsed presentation state.

## Event reference

Event constants such as `BEFORE_KANBAN_CARD_MOVE_EVENT` and `KANBAN_CARD_MOVE_EVENT` are exported for refactor-safe listeners.

Every successful create, update, delete, or move also reaches the shared
`gridedit` stream with `kanban-card-change` in `eventTypes`. Its ordered
`domainChanges` contains one `kanban-card` entry per changed canonical card,
including cards re-ranked during a move. Each entry provides the action, card
ID, previous card, and committed card. Create uses a null previous card and
delete uses a null committed card.

`data`, `previousData`, and `models` contain only ordinary row/field patches for
cards that retain a stable canonical source index. Creates, deletes, and
position changes without a safe grid coordinate remain in `domainChanges`;
compact undo/redo state lives separately in `history`.

The Kanban `beforekanban*` events remain the cancellation boundary. A Kanban
`gridedit` has `sourceMutation: 'producer'`, is observational, and calling
`preventDefault()` does not roll back the already committed mutation.
Passing `skipHistory: true` to a mutation still publishes this event with
`recordHistory: false`, but History deliberately creates no undo entry.

Remote loading exports `KANBAN_REMOTE_LOAD_START_EVENT`,
`KANBAN_REMOTE_LOAD_SUCCESS_EVENT`, and `KANBAN_REMOTE_LOAD_ERROR_EVENT`.
Call `getRemoteState()` for `loading`, `nextOffset`, `hasMore`, `total`, and
`error`; `loadMoreCards()` requests the next page and `refreshRemote()` clears
cards and history, or reinitializes configured placeholders, before loading
page zero. Both loading methods return a
promise and deduplicate concurrent requests.

Editor validation constants are exported with
`KanbanCardEditorDialogPlugin`. `beforekanbancardeditorvalidate` and
`beforekanbancardeditorfieldvalidate` are cancelable; all other validation
events report committed results. Cancelling validation always blocks submit.

## Cancel and persist a move

```ts
grid.addEventListener(BEFORE_KANBAN_CARD_MOVE_EVENT, (event) => {
  if (!permissions.canMove(event.detail.cardIds, event.detail.target)) {
    event.preventDefault();
  }
});

grid.addEventListener(KANBAN_CARD_MOVE_EVENT, async (event) => {
  await api.saveCards(event.detail.changedCards);
});
```

Before-move listeners must make their cancel decision synchronously. Resolve remote authorization into local policy state before dragging begins.

CRUD request events remain the stable integration point. With `KanbanCardEditorDialogPlugin` installed they open the packaged workflow; without it, when it is disabled, or when a listener cancels the request, the application remains responsible. Committed mutation events are suitable for synchronizing remote state.

---

# Kanban Examples

URL: https://pro.rv-grid.com/guides/kanban/examples/
Source: src/content/docs/guides/kanban/examples.mdx
Description: Live RevoGrid Kanban examples for a basic board, swimlanes and WIP, custom cards and i18n, and persistence events.
Surface: kanban

## Basic workflow

The source rows remain ordinary application cards. Drag between columns or reorder within a workflow column.

## Swimlanes, rules, and blocking WIP

This example uses explicit team lanes, per-lane WIP limits, allowed origins, and an urgent-card rule.

## Custom cards and labels

The managed shell retains selection and drag behavior while the content, properties, and Portuguese labels are application-defined.

## Cancelable moves and persistence payloads

The locked card is rejected before mutation. Successful moves show the payload a persistence adapter receives.

These focused portal examples complement the full `kanban-board` demo, which is available in the examples catalog for TypeScript, React, Vue 3, and Angular. All variants use the same grid properties and `@revolist/kanban` imports.

---

# Filtering, History, And Application State

URL: https://pro.rv-grid.com/guides/kanban/filtering-history-state/
Source: src/content/docs/guides/kanban/filtering-history-state.mdx
Description: Combine RevoGrid filters with Kanban search, undo card moves, persist board state, and restore the table view.
Surface: kanban

## Filtering and search

Core RevoGrid filters are evaluated against canonical cards and the host's captured table columns. Kanban then composes its lightweight search and predicate:

```ts
grid.kanban = {
  ...config,
  filter: {
    query: searchInput.value,
    fields: ['title', 'owner', 'labels'],
    predicate: (card) => !card.archived,
  },
};
```

A card must pass all three layers: RevoGrid filters, query matching, and the predicate. Search defaults to the configured card title field.

Header counts expose visible and total cards when filters differ. WIP limits always count all canonical cards.

## Undo and redo

Kanban coordinates with `EventManagerPlugin` and `HistoryPlugin`. Each successful move or editor CRUD action contributes normal stable row patches plus typed card changes to the shared `gridedit` stream. Replay-only card state is kept in separate keyed `history` metadata. With EventManager collection enabled, consecutive operations merge by card ID into one transaction and one history step while preserving each card's earliest prior state and latest committed state. Undo/redo is replayed through Kanban rather than against projected lane rows, including source-length changes.

History is not cleared merely because filtering, sorting, or board projection refreshes. Replacing `grid.source` with an externally authored dataset clears Kanban history so an old move cannot overwrite newer host data.

## Persistence ownership

Listen to `kanbancardmove` and persist `event.detail.changedCards` in one transaction. This atomic list includes the moved cards and any destination-bucket cards whose ranks changed during a rebalance. `event.detail.cards` contains only the cards explicitly moved, while `rebalancedCardIds` identifies the subset re-ranked as part of the commit.

Use `beforekanbancardmove` for asynchronous-policy caches or synchronous authorization checks. Call `preventDefault()` to cancel before local state changes.

## Switching views

```ts
// Table to Kanban
grid.kanban = kanbanConfig;

// Kanban to table
grid.kanban = false;
```

Disabling Kanban restores the latest canonical source, latest host column definitions, and relevant table state. Sorting is not used for card order while the board is active; `orderField` remains authoritative. Re-enabling projects the current source again.

---

# Drag, Drop, And Selection

URL: https://pro.rv-grid.com/guides/kanban/interaction/
Source: src/content/docs/guides/kanban/interaction.mdx
Description: Move and select Kanban cards with pointer, touch, keyboard, auto-scroll, and atomic multi-card operations.
Surface: kanban

## Card movement

Cards can be reordered within a workflow column or moved across columns and swimlanes. The complete non-interactive card surface starts a pointer drag and the card itself is the keyboard pickup target. Pointer capture keeps the drag active outside a card, and drop indicators plus localized announcements expose the proposed target.

During a drag, Kanban auto-scrolls the board horizontally and RevoGrid vertically. Filtered cards remain in the canonical bucket; visible cards act as insertion anchors so hidden records keep deterministic ranks.

### Touch and mobile behavior

Kanban uses Pointer Events for mouse, pen, and touch rather than browser-native HTML drag-and-drop. A tap selects the card without creating a drag preview. Once touch movement crosses the drag threshold, pointer capture keeps the operation active and horizontal edge auto-scroll exposes off-screen workflow columns. Browser `pointercancel` events remove the preview and drop feedback without committing a move.

Draggable cards use `touch-action: pan-y`, so a vertical swipe can continue to scroll a long board from the card surface. A primarily horizontal gesture starts cross-column movement. Because mobile browsers arbitrate vertical gestures before application code, use the context menu, keyboard, or `moveCards()` API when an exact vertical reorder gesture is claimed by native scrolling.

Keep the grid sized to its container on phones; workflow columns retain their configured widths and scroll inside RevoGrid rather than compressing card content. Validate production integrations on physical iOS Safari and Android Chrome in addition to automated mobile emulation.

Empty alignment cells are not drop zones. A column exposes targets on its existing cards and once in the first empty cell immediately after its final visible card, preventing repeated empty placeholders across the swimlane.

## Multiple selection

- Click replaces the selection.
- Cmd/Ctrl-click toggles one card.
- Shift-click selects a contiguous range in board reading order.
- Dragging a selected card moves the entire selection.
- Dragging an unselected card first replaces the selection with that card.

A selection can span several columns and swimlanes. The move is atomic and preserves the selected cards' prior board reading order.

When filters change, selection is reduced to visible cards. Removed source rows are always pruned.

## Keyboard movement

Focus the card, then:

| Key | Action |
| --- | --- |
| Space | Pick up or drop the selected card group. |
| Arrow keys | Move the proposed target through positions, columns, and lanes. |
| Escape | Cancel the active keyboard drag. |

The live region announces pickup, target changes, validation failures, cancelation, and completion. Application card content remains inside the managed shell so custom templates cannot remove these interactions.

## Card context menu

Right-click a card or focus it and press the Context Menu key/Shift+F10. Kanban uses the same shared context-menu surface as Scheduler and Gantt, including Font Awesome SVG icons, keyboard navigation, nested menus, dividers, viewport-aware positioning, and theme colors.

The built-in menu provides:

- A single Edit request action.
- Move destinations grouped by workflow column and swimlane. If the invoked card belongs to the current multi-selection, the complete selection moves atomically.
- Add card here, scoped to the current column and swimlane.
- A visually separated destructive Delete request.

Move commands use the same rules, transitions, WIP checks, history entry, and persistence events as drag-and-drop. CRUD entries always emit the matching cancelable request event. Register `KanbanCardEditorDialogPlugin` to handle those requests with the packaged schema-driven editor, or omit/disable it when the host owns dialogs and persistence. The public Open request is still available for an application-owned detail view, but it is not duplicated in the packaged menu or editor. Hide any request action your application does not handle so the menu advertises only working capabilities.

Disable the generated entries or hide individual commands without replacing an application row menu:

```ts
grid.kanban = {
  ...config,
  contextMenu: {
    includeHostItems: true,
    hidden: {
      edit: ({ card }) => !permissions.canEdit(card),
      create: ({ column, swimlane }) => !permissions.canCreate(column.prop, swimlane.id),
      delete: ({ cardIds }) => !permissions.canDelete(cardIds),
    },
  },
};
```

Each `hidden` entry accepts a boolean or a predicate evaluated when the menu opens. The predicate receives the primary `card`, invoked `cardIds`, `column`, and `swimlane`. Set `contextMenu: false` to remove Kanban actions entirely. Visible strings remain configurable through `labels`, while `includeHostItems` composes application `rowContextMenu` entries. Host-owned `ContextMenuPlugin` instances are preserved across activation and teardown.

## Programmatic movement

Locate the plugin through RevoGrid's plugin collection and call `moveCards`:

```ts
const plugins = await grid.getPlugins();
const kanban = plugins.find((plugin) => plugin instanceof KanbanPlugin);

await kanban?.moveCards(
  ['CARD-12', 'CARD-19'],
  { columnProp: 'review', swimlaneId: 'platform', index: 0 },
  { reason: 'api' },
);
```

Programmatic moves use the same validation, events, provider update, ranking, and history path as pointer and keyboard moves.

---

# Kanban Limitations

URL: https://pro.rv-grid.com/guides/kanban/limitations/
Source: src/content/docs/guides/kanban/limitations.mdx
Description: Understand the intentional v1 boundaries for editing, remote data, dragging, view switching, sorting, and localization.
Surface: kanban

Kanban v1 intentionally keeps application policy and remote persistence outside the rendering plugin.

| Area | v1 behavior |
| --- | --- |
| View switcher | The host sets `grid.kanban`; no built-in table/Kanban toolbar is rendered. |
| Card forms | A separate opt-in editor plugin supplies local CRUD. Hosts can disable, intercept, schema-customize, or completely replace it and remain responsible for remote persistence. |
| Remote data | `kanban.remote` loads one whole-board offset/limit stream. A known `total` plus placement `placeholder` enables fixed Infinity-style indexed skeleton chunks; otherwise pages append. Indexed create/delete must happen on the server followed by `refreshRemote()` so offsets stay stable. Filtering stays local, and the application owns persistence and server-wide validation. |
| External drag | Cross-board, cross-window, file, and third-party drag targets are not supported. |
| Swimlane order | Configuration-owned; swimlanes cannot be drag-reordered. |
| Column order | Uses RevoGrid's core column move behavior. Pointer/touch capabilities follow that plugin; programmatic ordering remains available. |
| Sorting | Table sorting does not reorder board cards. `orderField` is authoritative while Kanban is active. |
| Translation packs | English is bundled; applications provide partial or complete translated labels. |
| Asynchronous validation | `beforekanbancardmove` cancelation is synchronous. Cache remote permissions before interaction. |

Card pointer interaction supports mouse, pen, and touch. Keyboard card movement uses the focusable managed card shell and does not depend on browser-native HTML drag-and-drop.

Unknown workflow values use the **Unmapped** column by default, while invalid or duplicate card identities remain visible but immovable. Treat diagnostics as data-quality errors rather than hiding affected records.

Kanban remote loading and `InfinityScrollPlugin` share the same generic loader
contract and fixed indexed chunks. Kanban additionally needs a lightweight
placement placeholder because a global total cannot identify an unloaded
card's workflow column or swimlane. Do not enable both loaders on the same
Kanban grid: Kanban must retain ownership of the projected row provider while
its remote controller owns canonical cards. If multiple row-source owners are
configured, the first active owner remains enabled and the later plugin
disables itself with a console warning.

---

# Swimlanes, WIP, And Rules

URL: https://pro.rv-grid.com/guides/kanban/swimlanes-wip-rules/
Source: src/content/docs/guides/kanban/swimlanes-wip-rules.mdx
Description: Group cards into lanes, define capacity policies, validate transitions, and apply ordered visual and permission rules.
Surface: kanban

Use swimlanes when each workflow column must be split by team, class of service, release, product area, or another card field.

## Swimlane placement

Swimlane labels render in a dedicated row-header column by default. Use
`swimlaneLayout: 'top'` to render a compact header across the workflow columns
before each lane instead. Both layouts keep counts, custom header content, and
per-lane collapse controls.

```ts
grid.kanban = {
  columns,
  swimlaneField: 'team',
  swimlaneLayout: 'top', // use 'column' for the dedicated label column
  swimlanes: [
    {
      id: 'product',
      title: 'Product team',
      collapsible: true,
      swimlaneTemplate: (h, context) => h('div', { class: 'product-lane' }, [
        h('strong', null, context.swimlane.title),
        h('span', null, `${context.visibleCount} / ${context.totalCount}`),
        h('button', { type: 'button', onClick: context.toggleCollapsed }, 'Toggle'),
      ]),
    },
    { id: 'platform', title: 'Platform team', collapsible: true },
  ],
};
```

`column` is the backward-compatible default. `swimlaneColumn` width and collapse
settings apply only to that dedicated-column layout. A lane's
`swimlaneTemplate` fully controls its header content in either layout while
Kanban keeps the outer lane row and identity semantics.

## Derived or explicit lanes

Setting only `swimlaneField` derives lanes in first-appearance order. Provide definitions when labels, order, heights, collapse controls, styles, or lane-specific WIP limits matter.

```ts
grid.kanban = {
  columns,
  swimlaneField: 'team',
  swimlanes: [
    { id: 'web', title: 'Web team', wipLimits: { active: 2 } },
    { id: 'api', title: 'API team', collapsed: false },
  ],
};
```

Swimlane order is configuration-owned and cannot be dragged in v1.

For a board that does not use swimlanes, disable the row-header presentation
directly in Kanban configuration:

```ts
grid.kanban = {
  columns,
  swimlaneColumn: false,
};
```

Cards still use the internal implicit lane for ordering and virtualization, but
no swimlane label or lane-collapse control is rendered.

## Collapsible swimlane labels

The swimlane row-header column can collapse independently from the lanes. In
its compact state it shrinks to a narrow rail and renders lane titles as
vertical badges; cards and lane heights are unchanged.

```ts
grid.kanban = {
  columns,
  swimlaneField: 'team',
  swimlaneColumn: {
    title: 'Teams',
    width: 176,
    collapsedWidth: 52,
    collapsible: true,
    collapsed: false,
  },
};
```

Use `getSwimlaneColumnCollapsed()` and `setSwimlaneColumnCollapsed(...)` on the
plugin instance when an application toolbar also needs to control the state.
This is separate from each swimlane definition's `collapsed` state, which
reduces that lane's projected row height.

## WIP behavior

Set a column `wipLimit`, or a lane `wipLimits` entry for a more specific bucket limit. `wipBehavior` defaults to `warn`:

- `warn` permits the move and renders/announces the over-limit state.
- `block` rejects the entire proposed move.

Multi-card moves validate the final batch count, not each card independently. A failed card or capacity check cancels the full move.

## Movement permissions

Use `allowedFrom` for simple workflow transitions and `rules` for application policy:

```ts
rules: {
  canDrag: (card) => card.locked ? 'Locked by another user' : true,
  canSelect: (card) => !card.archived,
  canEdit: (card) => card.permissions.includes('edit'),
  canDrop: ({ cards, targetColumn }) =>
    cards.some((card) => card.requiresApproval) && targetColumn.prop === 'done'
      ? 'Approval is required'
      : true,
}
```

Return `false` or a localized reason string to reject an action.

## Visual card rules

`cardRules` is an ordered declarative layer for badges, classes, styles, and permissions. Matching classes and badges accumulate, later styles override earlier properties, and any explicit permission denial wins.

```ts
cardRules: [
  {
    id: 'urgent',
    when: ({ card }) => card.priority === 'urgent',
    result: {
      className: 'card--urgent',
      badges: [{ label: 'Urgent' }],
      style: { '--kanban-card-accent': '#dc2626' },
    },
  },
]
```

---

# Migrating to 2+

URL: https://pro.rv-grid.com/guides/migration-v2/
Source: src/content/docs/guides/migration-v2.mdx
Description: Step-by-step guide for upgrading to RevoGrid Pro 2+

This guide covers every breaking change introduced in **v2.0** of `@revolist/revogrid-pro` and
the standalone product packages, and explains what to update in your codebase.

v2.0 is a **major release** with breaking changes in imports, plugin configuration, plugin
authoring, CSS setup, and product package structure. Read through the checklist below before
upgrading.

---

## Quick migration checklist

1. Upgrade `@revolist/revogrid` core to `^4.21.4`
2. Replace all sub-path imports with flat imports from `@revolist/revogrid-pro`
3. Replace hardcoded event strings with named constants from `@revolist/revogrid-pro`
4. Import `revogrid-pro.css` in your application entry point
5. Move plugin configuration from `grid.additionalData` to direct grid properties
6. Update custom plugins to extend `CorePlugin` instead of `BasePlugin`
7. Add `@revolist/revogrid-pro` alongside each standalone product
8. Move Pivot and Gantt imports to `@revolist/pivot` and `@revolist/gantt`
9. Update Excel export integrations that relied on bundled SheetJS or bundled workbook import parsing when upgrading from `2.0.8`
10. Rename authored Gantt task `status` fields to `workflowStatus` and treat the Status column as calculated/read-only
11. When upgrading from 2.7 to 2.8, replace model-backed formatting selections and version 1 formatting state with physical coordinates and state version 2
12. Replace `ClipboardJsonPlugin` and `$rv-parse_` clipboard text with `ClipboardPlugin` and the smart clipboard document
13. Move Event Scheduler event arrays from `eventSchedulerEvents` to `source` when convenient; the legacy property remains a deprecated compatibility alias

---

## 2.7 → 2.8 breaking changes

### Event Scheduler uses `source` for canonical events

Put the event entity array in the standard RevoGrid `source` property. The
deprecated `eventSchedulerEvents` property is still accepted and copies its
value into `source`, so existing integrations can migrate incrementally:

```ts
// Legacy compatibility alias
grid.eventSchedulerEvents = events;

// Preferred canonical API
grid.source = events;
```

Generated calendar slots and resource rows are internal projection data and no
longer replace the public property. After an accepted create, edit, delete,
undo/redo, or remote result, `grid.source` contains the latest canonical event
list. Existing scheduler mutation events still provide `detail.events`; use
those events to update React, Vue, or Angular application state and to persist
changes.

### DataGridFormattingPlugin is coordinate-only

v2.8 removes the formatting compatibility layer completely. The following 2.7
contracts are no longer accepted as formatting operation or state inputs:

- model-backed `{ scope, rows, columns, cells }` selections
- `getFormat(model, prop, rowType)`
- `getRowKey` and `rowKeyProp`
- formatting runtime state version 1 and row-key preset state

Cell operations now use inclusive, zero-based physical coordinates in the
selected row and column `source` stores:

```ts
plugin.apply({
  scope: 'cells',
  rows: [invoice],
  columns: [amountColumn],
  cells: [{ model: invoice, column: amountColumn, rowType: 'rgRow' }],
}, moneyFormat);

const format = plugin.getFormat(invoice, 'amount', 'rgRow');
```

```ts
plugin.apply({
  start: { row: 4, column: 2 },
  rowType: 'rgRow',
  colType: 'rgCol',
}, moneyFormat);

const format = plugin.getFormat({ row: 4, column: 2 });
```

Complete-column operations use a separate coordinate target so their format
also applies to future rows:

```ts
plugin.apply({
  scope: 'columns',
  ranges: { start: 2, end: 4, colType: 'rgCol' },
}, moneyFormat);

const format = plugin.getColumnFormat({ column: 2, colType: 'rgCol' });
```

Complete-row operations are symmetrical and also apply to columns added later:

```ts
plugin.apply({
  scope: 'rows',
  ranges: { start: 4, end: 6, rowType: 'rgRow' },
}, moneyFormat);

const format = plugin.getRowFormat({ row: 4, rowType: 'rgRow' });
```

`DataGridFormattingRuntimeState` now accepts only `version: 3`. v2.8 does not
read or infer formatting from version 1 or version 2 state. Applications must migrate
persisted state before assigning it to `grid.dataGridFormatting` or calling
`plugin.setState()`. The v3 format stores `row`, `column`, `rowType`, and
`colType` directly; `getRowKey` and `rowKeyProp` are unnecessary because
formatting remains attached to the physical coordinate when source objects are
replaced.

Value formats are now a strict discriminated union. Built-in formats use
`{ kind: 'preset', preset: 'currency', ... }`; exact Excel-compatible codes use
`{ kind: 'code', formatCode: '#,##0.00' }`. The ambiguous legacy
`{ preset, formatCode }` object is rejected. The RevoGrid rich clipboard payload
is correspondingly version 2; version 1 payloads are not inferred as v2.

`DataGridFormattingPlugin` no longer auto-installs `EventManagerPlugin`. Add it
explicitly when formatting mutations, managed clipboard paste, or accepted
autofill formatting must flow through the cancelable `gridedit` event. Add
`AutoFillPlugin` alongside Event Manager when fill-handle gestures should copy
formatting as well as values. `HistoryPlugin` continues to install Event Manager
automatically for undo and redo.

Bold cell formatting now uses the standard CSS `700` weight. This also makes
bold formatting imported from Excel visually match the source workbook.

### ClipboardJsonPlugin was replaced by ClipboardPlugin

v2.8 removes `ClipboardJsonPlugin`, `legacyJsonText`, and automatic decoding of
the `$rv-parse_` text marker. The marker overloaded `text/plain`, exposed an
internal serialization convention to external applications, and duplicated the
versioned smart clipboard document.

```ts
import { ClipboardJsonPlugin } from '@revolist/revogrid-pro';

grid.plugins = [ClipboardJsonPlugin];
```

```ts
import {
  ClipboardPlugin,
  DataGridFormattingPlugin,
} from '@revolist/revogrid-pro';

// Values and application-defined clipboard formats:
grid.plugins = [ClipboardPlugin];

// Or the recommended rich-formatting setup:
grid.plugins = [DataGridFormattingPlugin];
```

The smart plugin preserves objects, formulas, formatting, structures, and sparse
multi-range geometry in `application/x-revogrid-clipboard+json`, with HTML and
plain-text fallbacks for Excel and other applications. Decode any stored
`$rv-parse_` values in application code before assigning or pasting them; v2.8
treats marker text literally.

v2.8 also removes the clipboard implementation markers
`SMART_CLIPBOARD_PLUGIN`, `SmartClipboardRuntime`, and
`isSmartClipboardRuntime`. Application code that needs the installed plugin
instance should use the plugin class instead:

```ts
const clipboard = (await grid.getPlugins())
  .find(plugin => plugin instanceof ClipboardPlugin);
```

Custom Pro plugins can use the equivalent provider-backed lookup:
`providers.plugins.getByClass(ClipboardPlugin)`.

---

## 1. Core dependency version

v2.0 requires `@revolist/revogrid` **4.21.4 or later**. Earlier core versions are not supported.

```bash
npm install @revolist/revogrid@^4.21.4
# or
pnpm add @revolist/revogrid@^4.21.4
```

---

## 2. Import paths — flat surface only

v1.x supported sub-path imports that pointed to internal modules. These paths are **removed** in v2.0.
All exports are now available from the single package entry point.

```ts
import { commonAggregators } from '@revolist/revogrid-pro/aggregations';
import { CorePlugin }         from '@revolist/revogrid-pro/core';
import { FOCUS_APPLY_EVENT }  from '@revolist/revogrid-pro/events';
import { createMergedData }   from '@revolist/revogrid-pro/utils';
```

```ts
import {
  commonAggregators,
  CorePlugin,
  FOCUS_APPLY_EVENT,
  createMergedData,
} from '@revolist/revogrid-pro';
```

---

## 3. Event strings → named constants

v2.0 exports more than 135 named event constants. Replace every hardcoded event string with the
corresponding export to benefit from type checking and rename refactoring.

```ts
grid.addEventListener('beforecellfocus', handler);
grid.addEventListener('beforefocuslost', handler);
grid.addEventListener('beforekeydown', handler);
grid.addEventListener('aftersourceset', handler);
```

```ts
import {
  EVENT_BEFORE_CELL_FOCUS,
  EVENT_BEFORE_FOCUS_LOST,
  BEFORE_KEYDOWN_EVENT,
  AFTER_SOURCE_SET_EVENT,
} from '@revolist/revogrid-pro';

grid.addEventListener(EVENT_BEFORE_CELL_FOCUS, handler);
grid.addEventListener(EVENT_BEFORE_FOCUS_LOST, handler);
grid.addEventListener(BEFORE_KEYDOWN_EVENT, handler);
grid.addEventListener(AFTER_SOURCE_SET_EVENT, handler);
```

The full list of available constants is exported from `@revolist/revogrid-pro`.

---

## 4. CSS — required import

Starting in v2.0, the Pro plugin styles are **not** injected automatically. You must import the
stylesheet once in your application entry point.

```ts
// main.ts (or your app entry)
import '@revolist/revogrid-pro/dist/revogrid-pro.css';
```

```html
<link rel="stylesheet" href="https://cdn.example.com/revogrid-pro/dist/revogrid-pro.css" />
```

Import the stylesheet for each standalone product you use:

```ts
import '@revolist/pivot/styles.css';
import '@revolist/gantt/styles.css';
```

---

## 5. Plugin configuration — direct grid properties

v2.0 introduces a direct property system for Pro and standalone product plugin configuration. Plugin options
should now be assigned to their own grid property instead of being grouped under
`grid.additionalData`.

`additionalData` is deprecated for plugin configuration. It is still read as a legacy fallback during
the v2 migration window, but new code should use direct properties.

This is a breaking change because plugins no longer treat one large shared object as the primary
configuration surface. The old pattern made `additionalData` grow too quickly: unrelated plugins
shared the same object, and changing one key could notify every plugin observing `additionalData`.
That could cause unrelated state updates and unnecessary redraws. Direct properties make each plugin
observe only the configuration it owns.

```ts
grid.additionalData = {
  pivot,
  pagination,
  tree: {
    expandedRowIds,
  },
  rowExpand: {
    expandedRows,
  },
  rowAutoSize: {
    mode: 'auto',
  },
  eventManager: {
    applyEventsToSource: true,
  },
};
```

```ts
grid.pivot = pivot;
grid.pagination = pagination;
grid.tree = {
  expandedRowIds,
};
grid.rowExpand = {
  expandedRows,
};
grid.rowAutoSize = {
  mode: 'auto',
};
grid.eventManager = {
  applyEventsToSource: true,
};
```

For framework wrappers, bind the plugin property directly:

```tsx
<RevoGrid
  source={rows}
  columns={columns}
  plugins={plugins}
  pivot={pivot}
  pagination={pagination}
/>
```

```vue
<revo-grid
  :source="rows"
  :columns="columns"
  :plugins="plugins"
  :pivot="pivot"
  :pagination="pagination"
/>
```

```ts
import { Component, NO_ERRORS_SCHEMA } from '@angular/core';
import { RevoGrid } from '@revolist/angular-datagrid';

@Component({
  selector: 'my-grid',
  standalone: true,
  imports: [RevoGrid],
  // Allows Angular demos to bind RevoGrid plugin props that are not wrapper inputs.
  schemas: [NO_ERRORS_SCHEMA],
  template: `
    <revo-grid
      [source]="rows"
      [columns]="columns"
      [plugins]="plugins"
      [pivot]="pivot"
      [pagination]="pagination"
    ></revo-grid>
  `,
})
export class MyGridComponent {}
```

Common replacements:

| v1.x `additionalData` key | v2.0 property |
|---|---|
| `additionalData.pivot` | `grid.pivot` |
| `additionalData.pagination` | `grid.pagination` |
| `additionalData.tree` | `grid.tree` |
| `additionalData.rowExpand` | `grid.rowExpand` |
| `additionalData.rowAutoSize` | `grid.rowAutoSize` |
| `additionalData.masterRow` | `grid.masterRow` |
| `additionalData.transpose` | `grid.transpose` |
| `additionalData.rowContextMenu` | `grid.rowContextMenu` |
| `additionalData.columnContextMenu` | `grid.columnContextMenu` |
| `additionalData.eventManager` | `grid.eventManager` |
| `additionalData.infinityScroll` | `grid.infinityScroll` |
| `additionalData.cellMerge` | `grid.cellMerge` |
| `additionalData.excel` | `grid.excel` |
| `additionalData.hiddenColumns` | `grid.hideColumns` |

Core grid inputs such as `source`, `columns`, `plugins`, `theme`, `stretch`, `rowDefinitions`, and
`rowHeaders` are already direct RevoGrid properties. Keep binding those directly as before.

---

## 6. Custom plugins — extend `CorePlugin`

In v2.0 the recommended base class for all Pro plugins changed from `BasePlugin` (re-exported from
`@revolist/revogrid`) to `CorePlugin` (exported from `@revolist/revogrid-pro`). `CorePlugin` adds:

- `observeAttribute(name, callback)` — reacts to DOM attribute mutations
- `observeProperty(name, callback)` — reacts to direct JS property assignments

```ts
import { BasePlugin } from '@revolist/revogrid';

export class MyPlugin extends BasePlugin {
  constructor(grid, providers) {
    super(grid, providers);
    // plugin setup
  }
}
```

```ts
import { CorePlugin } from '@revolist/revogrid-pro';

export class MyPlugin extends CorePlugin {
  constructor(grid, providers) {
    super(grid, providers); // license banner injected here automatically
    // plugin setup
    this.observeProperty('myProp', (value) => {
      // react to grid.myProp = value
    });
  }
}
```

---

## 7. Standalone products — install Pro as a dependency

Pivot, Gantt, Scheduler, and Kanban require `@revolist/revogrid-pro` as a runtime dependency.
Install Pro explicitly alongside the products you use.

```bash
npm install @revolist/revogrid-pro @revolist/pivot @revolist/gantt
# or
pnpm add @revolist/revogrid-pro @revolist/pivot @revolist/gantt
```

Keep Pro and the standalone products on the **same version** (they are released together).

---

## 8. Pivot and Gantt use standalone packages

In v1.x, Pivot and Gantt plugins were part of `@revolist/revogrid-pro`. They now live in their
own `@revolist/pivot` and `@revolist/gantt` packages.

```ts
import { PivotPlugin, PivotConfig } from '@revolist/revogrid-pro';
import { GanttPlugin }              from '@revolist/revogrid-pro';
```

```ts
import { PivotPlugin, type PivotConfig } from '@revolist/pivot';
import { GanttPlugin }                   from '@revolist/gantt';
```

---

## 9. Excel export provider changes since 2.0.8

This is a breaking change for applications upgrading from `@revolist/revogrid-pro` `2.0.8` or earlier if they relied on bundled SheetJS, non-`.xlsx` default export output, or bundled `.xlsx` / `.xls` import parsing.

`ExportExcelPlugin`, `grid.exportExcel`, `export-excel`, `excel-before-import`, and `excel-before-set` keep their public names. The implementation contract changed so workbook-library choices stay app-owned and the default package is lighter.

| Area | In `2.0.8` and earlier | After this change |
| --- | --- | --- |
| Bundled export library | SheetJS `xlsx` | `write-excel-file` |
| Default export format | SheetJS-supported formats | `.xlsx` only |
| Default import | Workbook parsing through bundled dependency | CSV-only import |
| XLSX import | Plugin-owned | App-owned parser |
| Provider integration | Mostly implicit | Explicit provider objects or factories |
| Formatted workbook output | Reconstructed by provider | Prepared in `context.cellRows` |

### Default export

Use the bundled `.xlsx` provider for normal grid exports:

```ts
grid.plugins = [ExportExcelPlugin];

await excel.export({
  workbookName: 'report.xlsx',
  sheetName: 'Report',
});
```

The bundled provider now rejects non-`.xlsx` output:

```ts
await excel.export({
  workbookName: 'report.xlsb',
});

await excel.export({
  writingOptions: { bookType: 'xlsb' },
});
```

Use SheetJS, ExcelJS, workbook-module, or a custom provider when another workbook format is required.

### App-owned SheetJS

If an app depended on SheetJS output formats, install `xlsx` in the app and pass the module object into the SheetJS adapter:

```sh
pnpm add xlsx
```

```ts
import * as XLSX from 'xlsx';
import { createSheetJsExcelExportProvider } from '@revolist/revogrid-pro';

grid.exportExcel = {
  exportProvider: createSheetJsExcelExportProvider(XLSX),
};
```

The SheetJS adapter writes plain `context.rows` data. It is the compatibility path for apps that want SheetJS-owned workbook writing.

### App-owned ExcelJS

Use ExcelJS when migration requires formatted `cellRows`, merge spans, row heights, freeze panes, or richer workbook style mapping:

```sh
pnpm add exceljs
```

```ts
import ExcelJS from 'exceljs';
import { createExcelJsExcelExportProvider } from '@revolist/revogrid-pro';

grid.exportExcel = {
  exportProvider: createExcelJsExcelExportProvider(ExcelJS),
};
```

The ExcelJS adapter does not add ExcelJS to RevoGrid Pro dependencies. Your application owns the dependency and bundle cost.

### Custom providers

Custom providers should consume the prepared provider context instead of reading rendered grid rows:

```ts
const provider = {
  id: 'custom',
  async export(context) {
    await writeWorkbook(context.cellRows, {
      fileName: context.workbookName,
      sheetName: context.sheetName,
      metadata: context.exportMetadata,
    });
  },
};
```

Use `context.cellRows` when the provider needs formatted cells, grouped headers, formulas, or merge spans. Use `context.rows` only for plain row-object output.

### CSV-only default import

Default import now accepts CSV files. It reads files with `FileReader.readAsText`, dispatches `excel-before-import`, maps rows, dispatches `excel-before-set`, then updates the grid source unless either event is prevented.

`.xlsx` and `.xls` parsing is no longer bundled. For workbook uploads:

1. Install a parser such as SheetJS, ExcelJS, or read-excel-file.
2. Parse the file in app code.
3. Normalize workbook data into `columns` and `rows`.
4. Assign `grid.columns`, then `grid.source`.

See [Excel Import and Export Libraries](/guides/excel-export/excel-import-export-libraries/) for parser tradeoffs and examples.

### Feature-owned helpers

Feature-owned export helpers are still exported from Pro:

- Formula helper for exporting workbook formulas.
- Cell merge and grouped column transforms run automatically.
- Date, numeral, and select helpers are explicit utilities for optional column packages.
- `exportTransformers` are available on both `grid.exportExcel` and individual `plugin.export()` calls.

Provider contexts now include `cellRows`, `sourceRows`, `headerRowsCount`, `gridDerivedOptions`, and `exportMetadata`. Custom providers that need richer export output should consume those fields instead of reconstructing workbook state from `rows`.

When migrating custom providers, keep these rules in mind:

- Export data is prepared from data stores and grid source fallbacks, not rendered DOM rows.
- `sourceRows` preserves pinned segment semantics through `rowType` (`rowPinStart`, `rgRow`, `rowPinEnd`).
- `cellRows` includes generated headers and formatted provider cells; its data rows stay in pinned-top, body, pinned-bottom order.
- Missing pinned sources are empty. If a body data store is not initialized, export falls back to `grid.source`.

---

## Gantt Status is now calculated

The Gantt `Status` field now follows Microsoft Project-style reporting semantics and is read-only. Existing workflow values move to `workflowStatus`:

```ts
// Before
{ id: 'task-1', status: 'in-progress' }

// After
{ id: 'task-1', workflowStatus: 'in-progress' }
```

Legacy source and project JSON ingestion maps `status` to `workflowStatus` only when `workflowStatus` is absent. Serialization writes only `workflowStatus`. Remove code that edits the Status column and use the editable Workflow Status column or task-form field instead.

Set a project reporting date when deterministic results matter:

```ts
grid.gantt = {
  ...project,
  statusDate: '2026-04-08',
};
```

When omitted, `statusDate` defaults to today. Excel export now contains separate `Status` and `Workflow Status` columns, and label overrides are split between `labels.status` and `labels.workflowStatus`.

---

## Versioning strategy

Pro and the standalone product packages are released with the **same version number** (lockstep semver).

| Change type | Version bump |
|---|---|
| Breaking API/behavior change | **Major** (`2.0.0 → 3.0.0`) |
| New plugin or feature (backward-compatible) | **Minor** (`2.0.0 → 2.1.0`) |
| Bug fix | **Patch** (`2.0.0 → 2.0.1`) |

The RevoGrid core package (`@revolist/revogrid`) versions independently — always check its
changelog when upgrading core alongside the Pro product packages.

---

# Pagination Remote

URL: https://pro.rv-grid.com/guides/pagination-remote/
Source: src/content/docs/guides/pagination-remote.mdx
Description: Manage large datasets by breaking them into smaller, more manageable pages.

This example shows how to use pagination with remote data in the grid. To enable pagination you'll need to use the `PaginationPlugin`.
This plugin provides the necessary functionality to paginate data within the grid.

## Complete remote filter state

`loadData` keeps the original fourth argument for compatibility and passes the
complete advanced filter model as an optional fifth argument:

```ts
grid.pagination = {
  itemsPerPage: 50,
  initialPage: 0,
  total: 0,
  loadData: async (
    skip,
    take,
    order,
    singleConditionFilters,
    multiConditionFilters,
  ) => {
    return fetch('/api/orders', {
      method: 'POST',
      body: JSON.stringify({
        skip,
        take,
        order,
        filters: multiConditionFilters,
      }),
    }).then(response => response.json());
  },
};
```

Use `multiConditionFilters` for new integrations because it preserves every
condition and same-column relation. `singleConditionFilters` contains only the
first condition for each column.

<div hidden>

```javascript
// fixing render for multiframework
```

</div>

---

# Pivot Overview

URL: https://pro.rv-grid.com/guides/pivot/
Source: src/content/docs/guides/pivot/index.mdx
Description: Learn the Pivot mental model, when to use it, and how to build your first RevoGrid Pivot.

Pivot turns a flat fact table into an analytical view. You choose which fields define the row hierarchy, which fields define generated columns, and which fields become aggregated measures. RevoGrid stays responsible for rendering and interaction, while Pivot builds the grouped rows, generated headers, totals, and summary cells.

For raw type signatures, see [Pivot API](/api/pivot/) and [Pivot Config API](/api/pivot-config/). Use this guide set for behavior, defaults, and how the parts work together.

## When To Use Pivot

Use Pivot when your source rows represent detailed facts such as orders, transactions, tickets, or events, and users need to answer questions like:

- "Sales by region and quarter"
- "Count of incidents by team and priority"
- "Average margin by category and month"
- "Grand totals and subtotals across multiple hierarchies"

Use a normal grid when users mainly inspect or edit row-level records. Use Pivot when users need grouped analytical summaries.

## Core Vocabulary

- `dimension`: A field that can be placed on the row axis, column axis, or used as a value source.
- `row field`: A dimension listed in `rows`. It creates the vertical hierarchy.
- `column field`: A dimension listed in `columns`. It creates generated headers.
- `value`: A measure listed in `values`. It is aggregated into Pivot cells.
- `generated row`: A synthetic row produced by Pivot, not a raw input row.
- `generated column`: A synthetic column or column group produced by Pivot.
- `subtotal`: A summary for one intermediate branch of a hierarchy.
- `grand total`: A summary across the full filtered result.

## Mental Model

Client-side Pivot follows this shape:

```txt
source rows
  -> group by rows / columns
  -> aggregate values
  -> generate row hierarchy
  -> generate column hierarchy
  -> render with RevoGrid
```

Server-side Pivot keeps the same public config, but the aggregation step moves behind a remote engine boundary:

```txt
source rows
  -> analytical engine
  -> visible analytical window
  -> RevoGrid
```

That means the same concepts stay in place even when the data becomes too large for full client-side materialization.

## Conceptual Foundations

If you are new to Pivot tables or Business Intelligence (BI) concepts, we recommend starting with these conceptual guides:

- [What Is Pivot?](/guides/pivot/what-is-pivot/): The basic mental model of transforming flat data.
- [What is an OLAP Cube?](/guides/pivot/olap-cube-concepts/): Understanding multidimensional analysis and core operations.
- [Data Modeling for Pivot](/guides/pivot/data-modeling/): How to structure your facts and dimensions for the best results.

## First Working Pivot

1. Install Pro and the standalone Pivot package.

   ```bash
   pnpm add @revolist/revogrid @revolist/revogrid-pro @revolist/pivot
   ```

2. Import the plugin and any aggregators you want to expose.

   ```ts
   import {
     PivotPlugin,
     commonAggregators,
     type PivotConfig,
   } from '@revolist/pivot';
   import '@revolist/revogrid-pro/dist/revogrid-pro.css';
   import '@revolist/pivot/styles.css';
   ```

3. Register `PivotPlugin` on the grid.

   ```ts
   grid.plugins = [PivotPlugin];
   ```

4. Define a `PivotConfig`.

   ```ts
   const pivot: PivotConfig = {
     dimensions: [
       { prop: 'region', name: 'Region' },
       { prop: 'quarter', name: 'Quarter' },
       {
         prop: 'sales',
         name: 'Sales',
         aggregators: {
           ...commonAggregators,
         },
       },
     ],
     rows: ['region'],
     columns: ['quarter'],
     values: [{ prop: 'sales', aggregator: 'sum' }],
   };
   ```

5. Apply it through the direct `pivot` binding.

   ```ts
   grid.pivot = pivot;
   ```

   `additionalData.pivot` is still observed for legacy integrations, but new code should bind `pivot` directly.

## How To Read A PivotConfig

```ts
const pivot: PivotConfig = {
  dimensions: [...],
  rows: ['region', 'rep'],
  columns: ['year', 'quarter'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  totals: { grandTotal: true, subtotals: true },
  collapsed: true,
};
```

- `dimensions` describes the reusable field metadata.
- `rows` defines the row hierarchy from left to right.
- `columns` defines the generated header hierarchy from left to right.
- `values` defines which measures are aggregated in each visible cell.
- `totals` enables grand totals and subtotals.
- `collapsed` enables grouped row drill-down when the row hierarchy has multiple levels.
- `groupAggregations` makes grouped Pivot rows show aggregate values across generated metric columns.

## What RevoGrid Pivot Owns

When Pivot is active, `PivotPlugin` temporarily owns:

- the rendered `source`
- the rendered `columns`
- optional `pinnedBottomSource` for grand totals
- grouped-row metadata used for drill-down

When Pivot is cleared, the plugin restores the original source, columns, grouping, and pinned totals.

## Feature Map

- Client-side Pivot rows, columns, values, totals, and drill-down are implemented.
- Client-side grouped row aggregates are implemented through `pivot.groupAggregations`.
- `valuesOnRows`, flat headers, and the drag-and-drop configurator are implemented.
- Server-side Pivot exposes a first-class remote engine/store contract and plugin integration.
- Pivot Charts expose a renderer-neutral linked chart lifecycle, the first-party Pivot Charts renderer, persistence, external containers, and an optional modeless UI.
- The docs below describe the current implementation in `packages/pivot/src`, including Pivot core, Pivot Charts, and Pivot Config.

## Recommended Reading Order

1. [What Is Pivot?](/guides/pivot/what-is-pivot/)
2. [What is an OLAP Cube?](/guides/pivot/olap-cube-concepts/)
3. [Data Modeling for Pivot](/guides/pivot/data-modeling/)
4. [Dimensions](/guides/pivot/dimensions/)
5. [Aggregations](/guides/pivot/aggregations/)
6. [Configuration Reference](/guides/pivot/configuration-reference/)
7. [Totals](/guides/pivot/totals/)
8. [Values On Rows](/guides/pivot/values-on-rows/)
9. [Drill-Down](/guides/pivot/drilldown/)
10. [Sorting And Filtering](/guides/pivot/sorting-filtering/)
11. [Pivot Charts](/guides/pivot/concepts/charts/)
12. [Plugin Lifecycle](/guides/pivot/plugin-lifecycle/)
13. [Configurator](/guides/pivot/configurator/)
14. [Field Panel](/guides/pivot/field-panel/)
15. [Server-Side Pivot](/guides/pivot/server-side/)
16. [Caching And Cache Keys](/guides/pivot/caching/)
17. [OLAP Best Practices](/guides/pivot/olap-best-practices/)

---

# Aggregations

URL: https://pro.rv-grid.com/guides/pivot/concepts/aggregations/
Source: src/content/docs/guides/pivot/concepts/aggregations.mdx
Description: Learn how Pivot measures work, how aggregators are resolved, and how to design reliable summaries.

Aggregations turn raw field values into Pivot measures. A value field points to a source field, and an aggregator describes how that field should be summarized inside each Pivot cell.

## Dimension vs Measure

- A `dimension` groups facts.
- A `measure` summarizes facts.

In RevoGrid Pivot, both are built from the same field model. The difference is how you place them:

- `rows` and `columns` use a field as a grouping dimension.
- `values` uses a field as a measure source.

## Basic Value Configuration

```ts
values: [
  { prop: 'sales', aggregator: 'sum' },
  { prop: 'sales', aggregator: 'avg' },
  { prop: 'orders', aggregator: 'count' },
]
```

Each value becomes a separate measure in the generated Pivot output.

## How Aggregator Resolution Works

`values[].aggregator` is a string id. Pivot resolves that id against the matching dimension's `aggregators` map. If you use the configurator, those same registered aggregator ids populate the measure selector.

```ts
dimensions: [
  {
    prop: 'sales',
    name: 'Sales',
    aggregators: {
      sum: commonAggregators.sum,
      avg: commonAggregators.avg,
    },
  },
],
values: [{ prop: 'sales', aggregator: 'avg' }]
```

If the dimension does not expose the aggregator id, the measure cannot be resolved correctly.

## Built-In Summary Functions

The public remote/server-side summary model supports these stable ids:

- `sum`
- `min`
- `max`
- `avg`
- `count`

Client-side Pivot can also use custom aggregator functions through the dimension model.

## Multiple Measures

When you define multiple values, Pivot generates one measure per configured entry. That is useful for layouts like:

- Sales sum by quarter
- Margin avg by quarter
- Order count by quarter

On the client side, each generated value column uses the measure's `prop` and `aggregator`. On the remote side, result ids are stable summary ids such as `SalesAmount_sum` and `SalesAmount_avg`.

## Formatting Measures

Formatting belongs in the dimension metadata used by the generated columns. For example, attach a numeric column type or a custom template to the measure dimension so generated cells inherit the right rendering behavior.

## Custom Aggregators

Custom aggregators are useful when:

- you need a domain-specific summary
- the display value is not one of the common numeric summaries
- you are staying on the client-side path

Keep them lightweight. Client-side aggregators are run while materializing Pivot output, so very expensive functions will slow down large pivots.

## Average And Derived Measures

`avg` deserves special attention in OLAP-style systems:

- It is not additive.
- Correct remote planning often requires `sum + count` internally.
- Totals must be computed from underlying facts, not from already-averaged child cells.

The remote planner layer in this repository already models `avg` as a derived summary when planning server-side requests.

## Best Practices

- Prefer additive measures like `sum` and `count` when possible.
- Only expose aggregators that make business sense for the field.
- Keep stable aggregator ids across saved states and remote APIs.
- Name measures clearly in examples and UI text so users know whether they are looking at a sum, avg, or count.

## Next

Continue with [Configuration Reference](/guides/pivot/configuration-reference/) for the full `PivotConfig` surface.

---

# Pivot Charts

URL: https://pro.rv-grid.com/guides/pivot/concepts/charts/
Source: src/content/docs/guides/pivot/concepts/charts/index.mdx
Description: Turn a committed Pivot result into interactive, linked analytical charts with a built-in renderer or a custom headless integration.

Pivot Charts turn the current Pivot result into an interactive analytical
view. Pivot includes the renderer-neutral chart lifecycle, a first-party
SVG renderer, a searchable chart gallery, semantic drill-down, a current-frame
data table, persistence, export, localization, and server-side contracts. No
separate charting dependency is required.

`PivotChartsPlugin` owns chart data, lifecycle, persistence, drill,
synchronization, and rendering. The optional `PivotChartsUiPlugin` adds the
built-in controls for embedded workspaces, the modeless dialog, and the
**Pivot Chart…** context-menu action. Applications that only need a chart or
their own controls can install only the headless plugin.

<figure>
  <img
    src="/images/pivot-charts/overview.png"
    alt="A linked grouped-column Pivot chart open above the Pivot Fields Panel demo, with the chart gallery visible beside the plot."
  />
  <figcaption>
    A linked chart keeps the visualization synchronized with the committed
    Pivot while the modeless dialog remains available for exploration.
  </figcaption>
</figure>

## Choose a guide

| Guide | What it covers |
| --- | --- |
| [Chart types and compatibility](./chart-types/) | All 63 built-in types, required data channels, recommendations, and compatibility rules. |
| [Data and bindings](./data-and-bindings/) | Analytical frames, series and channel selection, totals, linking, data view, and limits. |
| [Drill-down and interactions](./drilldown-and-interactions/) | Cell-aware creation, breadcrumbs, synchronization modes, tooltips, legends, keyboard behavior, and events. |
| [Customization and export](./customization-and-export/) | Presentation, chart options, renderer styling, localization, PNG/PDF, and image encoders. |
| [Headless API and persistence](./headless-api-and-persistence/) | Plugin methods, `PivotChartRef`, model restore, custom renderers, and lifecycle events. |
| [Server data and performance](./server-data-and-performance/) | Complete-data providers, semantic scopes, cancellation, validation, dense data, and geographic capabilities. |

## Register Pivot Charts

For a chart-only integration, register the Pivot and headless chart plugins:

```ts
import {
  PivotChartsPlugin,
  PivotPlugin,
  createPivotChartsRenderer,
} from '@revolist/pivot';

grid.pivotCharts = {
  renderer: createPivotChartsRenderer(),
};
grid.plugins = [PivotPlugin, PivotChartsPlugin];
```

`grid.pivotCharts` is observable. Replacing the configuration updates locale
text and defaults, invalidates cached chart data, and refreshes linked charts.
This is where renderer options, a remote data provider, defaults, limits,
localization, and drill synchronization belong. The application container is
supplied later, when it exists.

## Render a chart outside the Pivot grid

A Pivot chart does not have to live in a popup or inside `<revo-grid>`.
`mountPivotChart()` renders into any application-owned `HTMLElement`.

| Experience | Plugins | Mount option |
| --- | --- | --- |
| Chart only | `PivotPlugin` + `PivotChartsPlugin` | Omit `controls` |
| Chart with your own controls | `PivotPlugin` + `PivotChartsPlugin` | Omit `controls`, then call `chart.update()` |
| Chart with built-in controls | Add `PivotChartsUiPlugin` | `controls: 'standard'` |

All three render in your container. None creates a popup.

### Chart only

```html
<revo-grid id="pivot"></revo-grid>
<div id="sales-chart" style="height: 420px"></div>
```

```ts
import {
  PivotChartsPlugin,
  PivotPlugin,
  createPivotChartsRenderer,
  mountPivotChart,
} from '@revolist/pivot';

const grid = document.querySelector<HTMLRevoGridElement>('#pivot')!;
grid.pivotCharts = { renderer: createPivotChartsRenderer() };
grid.plugins = [PivotPlugin, PivotChartsPlugin];

const chart = await mountPivotChart(grid, {
  container: document.querySelector<HTMLElement>('#sales-chart')!,
  presentation: { title: 'Sales by region' },
});
```

That is the complete integration. The chart defaults to grouped columns and
stays linked to the committed Pivot result.

### Chart with built-in controls

Add `PivotChartsUiPlugin`, then request the standard controls at mount time:

```ts
import {
  PivotChartsPlugin,
  PivotChartsUiPlugin,
  PivotPlugin,
  mountPivotChart,
} from '@revolist/pivot';

grid.plugins = [PivotPlugin, PivotChartsPlugin, PivotChartsUiPlugin];

const chart = await mountPivotChart(grid, {
  container: document.querySelector<HTMLElement>('#chart-workspace')!,
  controls: 'standard',
});
```

This embeds the same chart gallery, Data and Customize tabs, drill
breadcrumbs, current-frame table, and export actions used by the standard
dialog. The application still owns the outer container.

### Chart with your own controls

Use the chart-only mount and connect only the controls your product needs:

```ts
const chart = await mountPivotChart(grid, { container });

typeSelect.addEventListener('change', () => {
  void chart.update({
    chartType: typeSelect.value as PivotChartType,
  });
});
```

Use `chart.update()` for selected series, bindings, totals, link state,
presentation, theme, or chart-specific options. You do not need the UI plugin
for application-built controls.

## Mount after the DOM exists

The container must exist when `mountPivotChart()` runs. In Vue, React, and
other component frameworks, mount the chart in the framework's mounted effect
and destroy it during cleanup.

```vue
<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref } from 'vue';
import {
  mountPivotChart,
  type PivotChartRef,
} from '@revolist/pivot';

const grid = ref<HTMLRevoGridElement>();
const container = ref<HTMLElement>();
let chart: PivotChartRef | undefined;
let disposed = false;

onMounted(async () => {
  const mounted = await mountPivotChart(grid.value!, {
    container: container.value!,
  });
  if (disposed) mounted.destroy();
  else chart = mounted;
});

onBeforeUnmount(() => {
  disposed = true;
  chart?.destroy();
});
</script>

<template>
  <revo-grid ref="grid" />
  <div ref="container" class="chart" />
</template>

<style>
.chart { height: 420px; }
</style>
```

Use the equivalent mounted effect for React. In an Astro portal, call
`mountPivotChart()` immediately after the portal target has been appended.
An existing container may start hidden and become visible later: the built-in
renderer uses `ResizeObserver` and redraws when its size changes. Give it a
non-zero height when visible. Do not place a container, selector, or ref in
`grid.pivotCharts` or `grid.pivotChartsUi`.

## Open the modeless dialog

`PivotChartsUiPlugin.openChart()` remains available for an application toolbar
or the **Pivot Chart…** context-menu action. A grid owns at most one open
dialog, but it may also own any number of embedded charts.

Right-clicking a Pivot analytical cell creates a cell-aware initial scope:

- a group value opens its immediate children;
- a leaf value opens its siblings under the same parent;
- subtotal and grand-total cells choose the nearest valid breakdown;
- the clicked column path and measure become the initial series;
- values-on-rows preserve the clicked row measure.

The scope comes from committed Pivot row and column metadata, not DOM text or
a stale grid selection.

## What stays synchronized

Linked charts refresh after committed Pivot changes, filtering, sorting,
group expansion, source replacement, and theme changes. Unlinking stores a
bounded normalized dataset in the chart model; the snapshot then remains
stable until the chart is relinked.

Use the **Data** tab to choose totals, relationship bindings, drill
synchronization, and link state. Use **Customize** for presentation and
chart-specific options. **View data** switches the plot to the accessible
table for the current drill frame without mutating the Pivot or chart model.

## Demo and API

- Open the [live Pivot demo](/demo/pivot/) for the complete analytical
  workspace. The screenshot states in this guide come from the registered
  **Pivot Fields Panel** example, which also runs in all four framework
  wrappers.
- Use the [Pivot Charts API reference](/api/pivot-charts/) for exact generated
  interfaces and signatures.
- Continue with [Chart types and compatibility](./chart-types/).

---

# Chart Types and Compatibility

URL: https://pro.rv-grid.com/guides/pivot/concepts/charts/chart-types/
Source: src/content/docs/guides/pivot/concepts/charts/chart-types.mdx
Description: Choose among all 63 built-in Pivot chart types and understand their data-channel and compatibility requirements.

The built-in catalog is defined by `PIVOT_CHART_DEFINITIONS`. Each definition
owns its stable type ID, family, data view, required semantic channels,
constraints, interactions, presentation capabilities, preview dataset, option
schema, renderer, localized labels, and documentation slug.

The standard dialog evaluates every definition against the current dataset
before selection. Compatible recommendations appear first. Incompatible cards
stay visible and explain the missing channel or semantic requirement instead
of failing after selection.

<figure>
  <img
    src="/images/pivot-charts/gallery-compatibility.png"
    alt="The Pivot Charts gallery showing recommended charts, categorized real previews, and disabled range charts with guidance to add a low measure."
  />
  <figcaption>
    Every gallery card uses the real renderer. Disabled cards explain the
    missing binding, measure, hierarchy, or derived view.
  </figcaption>
</figure>

## Gallery behavior

- Search matches localized type names and descriptions.
- Categories follow the catalog family and order.
- Arrow keys move among cards, while <kbd>Enter</kbd> and <kbd>Space</kbd>
  select a compatible type.
- Preview charts are decorative, tooltip-free renderings of catalog fixtures.
- Only near-viewport previews mount; previews are cached by type, renderer,
  theme, and locale.
- Catalogs larger than 60 entries retain bounded visible-window behavior.
- A chart type is validated again by the headless plugin, so a custom picker
  cannot bypass compatibility rules.

## Comparison charts

| Type | Best for | Required data and constraints |
| --- | --- | --- |
| `groupedColumn` | Comparing multiple series across categories. | Category, value, and one or more series; signed values are supported. |
| `stackedColumn` | Comparing totals and their series contribution. | Category, value, and series; stacks signed values. |
| `normalizedColumn` | Comparing percentage composition across categories. | Category, value, and series; normalizes each category to 100%. |
| `rangeColumn` | Showing vertical low-to-high intervals. | Exactly one `low` and one `high` measure per category. |
| `lollipop` | A lighter single-series category ranking. | Category, value, and exactly one selected series. |
| `groupedBar` | Category comparison when labels are long. | Category, value, and series; signed values are supported. |
| `stackedBar` | Horizontal totals with composition. | Category, value, and series. |
| `normalizedBar` | Horizontal percentage composition. | Category, value, and series; normalizes to 100%. |
| `rangeBar` | Horizontal low-to-high intervals. | Exactly one `low` and one `high` measure. |

## Trend and area charts

| Type | Best for | Required data and constraints |
| --- | --- | --- |
| `line` | Trends across ordered categories. | Category, value, and series. |
| `smoothLine` | Visually continuous trends. | Same channels as `line`; smoothing changes geometry, not data. |
| `steppedLine` | State or price changes that hold until the next category. | Category, value, and series. |
| `smallMultiples` | Comparing many trends without overlapping lines. | Category and value with 1–12 series. |
| `annotatedTimeSeries` | Trends with emphasized analytical points. | Category, value, and series; date-like categories are recommended. |
| `area` | Trend magnitude with filled areas. | Category, value, and series. |
| `steppedArea` | Stepwise magnitude changes. | Category, value, and series. |
| `stackedArea` | Total trend plus series contribution. | Category, value, and series. |
| `normalizedArea` | Percentage composition over an ordered axis. | Category, value, and series; normalizes to 100%. |
| `rangeArea` | A low/high band over categories. | Exactly one `low` and one `high` measure. |
| `confidenceBand` | An uncertainty envelope around a trend. | Exactly one lower and one upper bound through `low` and `high`. |

## Part-to-whole charts

All part-to-whole types require non-negative values and select the first
available series when more than one series exists.

| Type | Best for | Required data |
| --- | --- | --- |
| `pie` | A small set of category shares. | Category, value, and exactly one series. |
| `donut` | Shares with a central visual summary area. | Category, value, and exactly one series. |
| `semiDonut` | A compact half-ring composition. | Category, value, and exactly one series. |
| `waffle` | Discrete-looking proportions in a 100-cell grid. | Category, value, and exactly one series. |

## Relationship charts

| Type | Best for | Required data |
| --- | --- | --- |
| `scatter` | Correlation between two measures. | One `x` and one `y` measure with complete paired observations. |
| `bubble` | Correlation with a third magnitude. | One `x`, one `y`, and one `size` measure. |
| `densityScatter` | Dense relationships where individual points overlap. | One `x` and one `y`; dense geometry is aggregated for rendering and accessibility. |
| `connectedScatter` | Showing the path or sequence between X/Y observations. | One `x` and one `y`; category order defines the connection order. |

The Data panel infers distinct X/Y bindings when possible. A measure already
used by one required relationship channel is disabled for the other.

## Polar charts

Polar charts require non-negative values.

| Type | Best for | Required data |
| --- | --- | --- |
| `rose` | Comparing magnitudes by angle and radius. | Category, value, and series. |
| `radarLine` | Comparing multivariate profiles. | Category, value, and series. |
| `radarArea` | Comparing filled multivariate profiles. | Category, value, and series. |
| `polarColumn` | Radial category comparison. | Category, value, and series. |
| `stackedPolarColumn` | Radial totals and composition. | Category, value, and series. |
| `normalizedPolarColumn` | Radial percentage composition. | Category, value, and series. |
| `radialBar` | A single-series circular progress comparison. | Category, value, and exactly one series. |
| `multiRingRadialBar` | Comparing several series as concentric rings. | Category, value, and series. |

## Distribution and statistical charts

| Type | Best for | Required data |
| --- | --- | --- |
| `histogram` | Frequency distribution across numeric bins. | Category/value input and one series; the analytical frame supplies or derives bins. |
| `stripDot` | Showing individual observations along a value axis. | Category/value input and one series. |
| `boxPlot` | Median, quartiles, spread, and outliers. | A derived distribution or quantile view for one series. |
| `violin` | Distribution shape and density. | A derived distribution or quantile view for one series. |
| `errorInterval` | Actual values with lower and upper error bounds. | One `actual`, one `low`, and one `high` measure. |
| `rangeInterval` | Comparing two or three interval-related series. | Category and value with 2–3 series. |

## Hierarchy charts

Hierarchy charts require row-hierarchy metadata and select one weight series.
Treemap and sunburst additionally require non-negative weights.

| Type | Best for | Required data |
| --- | --- | --- |
| `treemap` | Space-efficient nested proportions. | `hierarchy` plus one `weight` measure. |
| `sunburst` | Concentric hierarchy levels. | `hierarchy` plus one `weight` measure. |
| `icicle` | Depth-oriented rectangular hierarchy. | `hierarchy` plus one `weight` measure. |
| `circlePacking` | Nested hierarchy represented by packed circles. | `hierarchy` plus one `weight` measure. |

## Matrix and specialized charts

| Type | Best for | Required data |
| --- | --- | --- |
| `heatmap` | Comparing magnitude across category-by-series cells. | Category, value, and series. |
| `calendarHeatmap` | Activity intensity by date. | A date-semantic category, value, and exactly one series. |
| `waterfall` | Sequential positive and negative contribution to a result. | Category, value, and exactly one series. |
| `timelineRange` | Start/end intervals by category. | Exactly one `start` and one `end` measure. |

## Process, flow, and financial charts

| Type | Best for | Required data |
| --- | --- | --- |
| `funnel` | Stage-by-stage conversion or attrition. | Non-negative category/value data and one series. |
| `pyramid` | Hierarchical-looking stage magnitude. | Non-negative category/value data and one series. |
| `sankey` | Weighted directional flows. | `source`, `target`, and non-negative `weight` channels. |
| `chord` | Weighted relationships in a circular flow matrix. | `source`, `target`, and non-negative `weight` channels. |
| `candlestick` | Open/high/low/close price movement. | Exactly four series bound to `open`, `high`, `low`, and `close`. |
| `ohlc` | Compact open/high/low/close price ticks. | Exactly four OHLC series. |
| `volumePrice` | OHLC price movement plus traded volume. | Exactly five series: OHLC plus `volume`. |

## Combination and KPI charts

| Type | Best for | Required data |
| --- | --- | --- |
| `columnLine` | Comparing measures that benefit from column and line geometry. | Category/value data with at least two series. |
| `areaLine` | Comparing a filled magnitude with a trend. | Category/value data with at least two series. |
| `bullet` | Actual versus target in a compact linear view. | One `actual` and one `target` measure. |
| `gauge` | Actual versus target on a dial. | One `actual` and one `target` measure. |
| `kpi` | A headline value with target and optional variance. | One `actual`, one `target`, and optionally one `variance` measure. |
| `progressGauge` | Progress toward a target. | One `actual` and one `target` measure. |

## Compatibility rules

`evaluatePivotChartCatalog` and `evaluatePivotChartCompatibility` return
`compatible`, `inferred`, or `incompatible` results with structured reasons.
Compatibility checks cover:

- renderer support for the requested type;
- minimum and maximum channel counts;
- distinct required bindings such as X and Y or low and high;
- non-negative value constraints;
- hierarchy and semantic date requirements;
- derived distribution, range, flow, financial, and geographic views;
- safe category, series, and point limits.

When a compatible relationship chart is missing explicit bindings, the
catalog may return an inferred binding patch. Persisted models still retain
the resolved explicit bindings.

## Optional geographic pack

`createPivotChartGeographicCapabilityPack(provider)` creates a standalone host
for provider-owned `choropleth`, `proportionalSymbolMap`, and
`geographicHeatmap` views. Render these explicitly with `pack.render(...)`.
They are intentionally outside `PIVOT_CHART_TYPES` and the standard gallery.
The provider owns map assets, projected geometry, and licensing; Pivot
does not bundle a map library or geographic data.

[Previous: Pivot Charts overview](../) ·
[Next: Data and bindings](../data-and-bindings/) ·
[API reference](/api/pivot-charts/)

---

# Customization and Export

URL: https://pro.rv-grid.com/guides/pivot/concepts/charts/customization-and-export/
Source: src/content/docs/guides/pivot/concepts/charts/customization-and-export.mdx
Description: Customize chart presentation, semantic labels and tooltips, themes, localization, and PNG/PDF export.

Pivot Charts separate portable model presentation from renderer-wide styling.
Use `presentation` and `chartOptions` when the choice must persist with one
chart. Configure `createPivotChartsRenderer` when an application needs a
shared palette, typography, tooltip, or export pipeline.

<figure>
  <img
    src="/images/pivot-charts/customization.png"
    alt="The Pivot Chart Customize tab showing subtitle, legend, data-label and axis-title controls, grid-line and opacity options, and the theme selector."
  />
  <figcaption>
    The Customize tab combines portable presentation fields with the
    catalog-defined options supported by the selected chart.
  </figcaption>
</figure>

## Portable presentation

```ts
await chart.update({
  presentation: {
    title: 'Quarterly sales',
    subtitle: 'Committed orders only',
    legendPosition: 'bottom',
    dataLabels: true,
    xAxisTitle: 'Region',
    yAxisTitle: 'Revenue',
  },
  theme: 'material',
});
```

`legendPosition` accepts `top`, `right`, `bottom`, `left`, or `none`.
`theme` accepts `auto` or a renderer-supported theme string. The standard UI
offers follow-grid, default, material, compact, dark material, and dark compact
choices.

## Chart-specific options

The catalog generates a typed option schema for every chart:

| Option | Availability | Valid values |
| --- | --- | --- |
| `showGridLines` | Charts with axes. | Boolean. |
| `markOpacity` | Every built-in type. | `0.2`–`1` in `0.05` steps. |
| `strokeWidth` | Line, area, combination, radar line, and radar area. | `1`–`6` in `0.5` steps. |
| `fillOpacity` | Area-family, area-line, radar area, confidence band, and range area. | `0.1`–`0.9` in `0.05` steps. |

```ts
await chart.update({
  chartOptions: {
    showGridLines: false,
    markOpacity: 0.9,
    strokeWidth: 2.5,
  },
});
```

Unsupported keys, out-of-range values, and values that do not align with the
declared step are rejected during update and restore.

## Renderer styling

```ts
const renderer = createPivotChartsRenderer({
  className: 'sales-chart',
  fontFamily: '"IBM Plex Sans", sans-serif',
  categorySeparator: ' / ',
  palette: ['#2563eb', '#f97316', '#16a34a'],
  theme: ({ theme }) => ({
    ...theme,
    background: '#fffdf8',
    foreground: '#292524',
    grid: '#e7e5e4',
  }),
});
```

The theme callback receives the resolved light/dark base theme and current
render input. Renderer classes, theme colors, palette, fonts, labels, and
visible chart options are retained in image and document exports.

## Semantic label pipeline

Every visible label passes through one formatter. Kinds are `title`,
`subtitle`, `axisTitle`, `axisTick`, `category`, `legend`, `data`,
`annotation`, `summary`, and `specialized`.

```ts
const renderer = createPivotChartsRenderer({
  labels: {
    styles: {
      title: { fontSize: 20, fontWeight: 700 },
      category: { fill: '#475569', fontSize: 11 },
      data: { fontWeight: 600 },
    },
    formatter(context) {
      if (context.kind === 'legend') {
        return `Measure: ${context.defaultText}`;
      }
      if (context.kind === 'axisTick' && context.axis === 'y') {
        return null;
      }
      if (context.kind === 'data' && context.formattedValue) {
        return {
          text: context.formattedValue,
          ariaLabel:
            `${context.category?.label}: ${context.formattedValue}`,
          className: 'sales-chart-value',
        };
      }
      return undefined;
    },
  },
});
```

Return a string, a structured result, `null` to suppress one label, or
`undefined` to retain the default. Structured results can override text,
accessible text, classes, safe SVG typography, opacity, and visibility.

## Tooltip customization

```ts
const renderer = createPivotChartsRenderer({
  tooltip: {
    showDelayMs: 100,
    hideDelayMs: 60,
    followPointer: true,
    className: 'sales-chart-tooltip',
    formatter(context, defaultContent) {
      return {
        ...defaultContent,
        footer: context.drillable
          ? 'Open the next sales level'
          : 'Leaf value',
      };
    },
  },
});
```

The formatter receives raw and formatted values, category and series metadata,
relationship channels, mark color, and drillability. Return structured
content, plain text, an `HTMLElement`, or `null` to suppress one tooltip. Set
`tooltip: false` to disable tooltips.

## Full localization

`pivotCharts.localeText` supports deep partial overrides for dialog actions,
status and errors, breadcrumbs, gallery tabs/families, all chart names and
descriptions, compatibility reasons, chart options, data controls and table,
legend overflow, tooltips, accessibility text, context actions, themes,
totals, and number formatting.

```ts
grid.pivotCharts = {
  renderer: createPivotChartsRenderer(),
  localeText: {
    actions: {
      exportChart: 'Exportar',
      downloadPdf: 'Transferir PDF',
      viewData: 'Ver dados',
      viewChart: 'Ver gráfico',
    },
    chartTypes: {
      groupedColumn: 'Colunas agrupadas',
      boxPlot: 'Diagrama de caixa',
    },
    renderer: {
      formatNumber: (value) =>
        new Intl.NumberFormat('pt-PT').format(value),
    },
  },
};
```

## PNG, PDF, and image data

The built-in renderer advertises PNG and PDF through
`capabilities.downloadFormats`. The dialog's **Export** menu downloads the
current rendered chart. Programmatic downloads default to PNG:

```ts
await charts.downloadChart(chart.id, {
  fileName: 'quarterly-sales',
  fileFormat: 'pdf',
  width: 1_600,
  height: 900,
});

const dataUrl = await charts.getChartImageDataURL(chart.id, {
  width: 1_200,
  height: 675,
});
```

<figure>
  <img
    src="/images/pivot-charts/data-table-export-dark.png"
    alt="The dark-theme Pivot Chart dialog displaying the current-frame data table while the Export menu offers PNG and PDF downloads."
  />
  <figcaption>
    Data view and export operate on the current drill frame. Exported graphics
    keep the resolved theme and semantic formatting.
  </figcaption>
</figure>

Custom renderers should advertise only the formats they implement. The
first-party renderer also accepts `imageEncoder` and `pdfEncoder` callbacks
for applications that need a different rasterization or PDF pipeline.

[Previous: Drill-down and interactions](../drilldown-and-interactions/) ·
[Next: Headless API and persistence](../headless-api-and-persistence/) ·
[API reference](/api/pivot-charts/)

---

# Data and Bindings

URL: https://pro.rv-grid.com/guides/pivot/concepts/charts/data-and-bindings/
Source: src/content/docs/guides/pivot/concepts/charts/data-and-bindings.mdx
Description: Control the Pivot data projected into a chart, semantic channel bindings, totals, link state, and safety limits.

Pivot Charts project the committed Pivot result into a renderer-neutral
`PivotChartDataset`. The standard matrix is efficient for category/series
rendering, while the normalized analytical frame supplies stable fields and
observations for relationship, hierarchy, range, flow, financial, KPI, and
other specialized chart types.

<figure>
  <img
    src="/images/pivot-charts/relationship-bindings.png"
    alt="A scatter Pivot chart with the Data tab open, showing distinct X and Y measure selectors, totals, drill synchronization, and linked-state controls."
  />
  <figcaption>
    Relationship charts expose required semantic channels directly. The same
    panel controls totals, drill synchronization, and whether the data remains
    linked to the Pivot.
  </figcaption>
</figure>

## Dataset shape

```ts
interface PivotChartDataset {
  revision: number;
  source: 'client' | 'server';
  categories: PivotChartCategory[];
  series: PivotChartSeries[];
  values: Array<Array<number | null>>;
  displayValues?: Array<Array<string | null>>;
  hierarchies?: {
    row?: PivotChartHierarchyDefinition;
    column?: PivotChartHierarchyDefinition;
  };
  analyticalFrame?: PivotChartAnalyticalFrame;
}
```

`values` is row-major: `values[categoryIndex][seriesIndex]`. Optional
`displayValues` preserve the Pivot's formatted values for chart labels,
tooltips, data tables, and accessibility text. Categories and series retain
stable IDs, member paths, labels, member kinds, measures, and drill hierarchy
metadata.

The dataset revision identifies the committed Pivot snapshot that produced the
frame. Linked refreshes and drill requests use it to reject stale work.

## Normalized analytical frame

```ts
interface PivotChartAnalyticalFrame {
  fields: PivotChartFieldDescriptor[];
  observations: PivotChartObservation[];
  hierarchies?: PivotChartDataset['hierarchies'];
  derived?: {
    bins?: PivotChartJsonValue[];
    quantiles?: PivotChartJsonValue[];
    ranges?: PivotChartJsonValue[];
    flowEdges?: PivotChartJsonValue[];
    financial?: PivotChartJsonValue[];
    geographicFeatures?: PivotChartJsonValue[];
  };
}
```

Fields declare a stable ID, label, dimension/measure role, semantic type, source
field, aggregator, and optional format. Each observation stores dimension
values separately from numeric measures and optional display measures.
Specialized renderers consume the normalized fields and derived views instead
of guessing meaning from a series label.

## Semantic bindings

`PivotChartBindings` assigns stable field IDs to renderer channels. Empty and
omitted channels are equivalent.

| Channel group | Channels | Used by |
| --- | --- | --- |
| Standard matrix | `category`, `series`, `value` | Column, bar, line, area, part-to-whole, matrix, and combination types. |
| Relationship | `x`, `y`, `size`, `color`, `shape` | Scatter, bubble, density, and connected-scatter views. |
| Polar | `angle`, `radius` | Polar and radial layouts. |
| Hierarchy | `hierarchy`, `parent`, `child`, `weight` | Treemap, sunburst, icicle, and circle packing. |
| Flow | `source`, `target`, `weight` | Sankey and chord. |
| Range | `start`, `end`, `low`, `high` | Timeline, range, confidence, and error views. |
| Financial | `open`, `high`, `low`, `close`, `volume` | Candlestick, OHLC, and volume-price. |
| KPI | `actual`, `target`, `variance` | Bullet, gauge, KPI, and progress gauge. |
| Faceting and text | `facetRow`, `facetColumn`, `label`, `tooltip` | Small multiples and supplemental labels/tooltips. |

The chart gallery checks required channel counts before selection. For
relationship charts, the Data panel infers distinct X/Y measures when possible
and prevents the same field from satisfying both required channels.

```ts
await chart.update({
  chartType: 'bubble',
  bindings: {
    x: ['measure:cost:sum'],
    y: ['measure:revenue:sum'],
    size: ['measure:units:sum'],
  },
});
```

Use field IDs from `dataset.analyticalFrame.fields`, not visible labels.

## Series and values-on-rows

`seriesIds` selects a subset of dataset series. Types whose catalog definition
uses `firstAvailable` select one series even when the Pivot exposes several.
Types marked `all` retain the compatible series selection.

When the Pivot places values on rows, the category carries its measure.
`categoryMeasure` selects the required `{ prop, aggregator }` pair without
rewriting row paths or pretending the measure is a column series.

```ts
const dataset = await charts.getChartData({
  chartType: 'line',
  seriesIds: ['series:2026'],
  categoryMeasure: {
    prop: 'revenue',
    aggregator: 'sum',
  },
});
```

## Totals

`totals` accepts four modes:

| Mode | Included members |
| --- | --- |
| `none` | Leaf and group members only. |
| `grand` | Include grand totals. |
| `subtotals` | Include subtotals. |
| `all` | Include grand totals and subtotals. |

The default is `none`. Totals keep their semantic member kind, so charts,
tooltips, data tables, drill logic, and persisted models can distinguish them
from ordinary categories.

## Linked and unlinked data

A linked chart follows the current committed Pivot. Data, filters, sorting,
group expansion, source, Pivot model, and relevant theme changes schedule
coalesced refreshes.

Turning off **Keep linked to Pivot** stores the current bounded normalized
dataset in `model.dataset`. Later Pivot changes do not affect that chart.
Relinking removes the stored snapshot and projects the latest committed Pivot
state. Restore validates both linked models and embedded unlinked datasets.

## Current-frame data table

The header's **View data** action replaces the plot with a sortable accessible
table for the active drill frame. It:

- uses the same category order, series, and formatted display values as the
  chart;
- represents missing observations consistently;
- announces sort changes and exposes semantic table headers;
- does not alter the chart model, link state, Pivot, or drill state;
- switches back through **View chart**.

## Scope and limits

`getChartData` can request the immediate children of a semantic parent:

```ts
const dataset = await charts.getChartData({
  chartType: 'groupedColumn',
  totals: 'none',
  scope: {
    rowPath: ['Europe'],
    columnPath: [2026],
  },
});
```

Default safety limits are 1,000 categories, 250 series, and 50,000 data points.
The plugin validates limits, actual counts, matrix dimensions, observations,
bindings, and chart compatibility. Unsafe projections fail with a
`PivotChartError` rather than silently changing persisted data.

[Previous: Chart types and compatibility](../chart-types/) ·
[Next: Drill-down and interactions](../drilldown-and-interactions/) ·
[API reference](/api/pivot-charts/)

---

# Drill-down and Interactions

URL: https://pro.rv-grid.com/guides/pivot/concepts/charts/drilldown-and-interactions/
Source: src/content/docs/guides/pivot/concepts/charts/drilldown-and-interactions.mdx
Description: Navigate Pivot hierarchies from chart marks and synchronize chart drill state with the Pivot or application.

Pivot Charts carry row and column hierarchy metadata into every compatible
dataset. A mark can therefore identify the exact semantic category, series,
paths, measure, aggregator, and child state that produced it.

<figure>
  <img
    src="/images/pivot-charts/drilldown.png"
    alt="A Pivot chart drilled from All data into North, with a breadcrumb, child categories, and a semantic tooltip on a focused mark."
  />
  <figcaption>
    The breadcrumb is the navigation surface for the current row and column
    scope. Tooltips expose the full path, formatted value, and drill hint.
  </figcaption>
</figure>

## Cell-aware creation

With `pivotChartsUi.contextMenu: true` and `ContextMenuPlugin` installed,
right-clicking a Pivot analytical body cell contributes **Pivot Chart…**.
Creation resolves scope from committed Pivot metadata:

- group values open their immediate children;
- leaf values open siblings under the same parent;
- subtotal and grand-total cells use the nearest valid breakdown;
- the clicked column member and measure seed the series selection;
- values-on-rows retain the clicked category measure.

The context action composes with other menu contributions. It does not replace
application items or depend on visible DOM text.

## Mark activation

Pointer click and keyboard activation first look for an automatic semantic
drill target. When the category or series can drill, activation starts the
appropriate row, column, or two-axis drill action and does not emit
`pivot-chart-node-click`. The event is emitted only when no automatic drill
target exists.

The chart ref supports row, column, and two-axis targets:

```ts
if (chart.canDrillDown({ axis: 'row', category })) {
  await chart.drillDown({ axis: 'row', category });
}

await chart.drillDown({ axis: 'column', series });
await chart.drillDown({ axis: 'both', category, series });
```

Use `canDrillDown` before offering an application-owned drill control. It
checks hierarchy identity, level, child state, and the current active scope.

## Breadcrumb navigation

Each successful frame is stored in `PivotChartDrillState.frames`. The compact
breadcrumb shows the active row and column labels:

```ts
await chart.drillUp();
await chart.drillTo(1);
await chart.resetDrill();
```

Selecting **All data** resets to the root. Selecting an ancestor calls
`drillTo` directly; it does not replay every intermediate click. After a
successful UI drill, focus moves to the current breadcrumb item.

## Loading, cancellation, and retry

Drill loads are abortable and revision-checked:

- the last successful frame stays visible while the next frame loads;
- a newer action aborts or supersedes older work;
- stale provider completions are ignored;
- rendering failures roll back model and dataset state;
- successful scopes are cached;
- failed drill metadata is retained for `retryDrill()`.

The dialog displays the pending target, failure message, and retry action
without discarding the previous chart.

## Drill synchronization

`drillSyncMode` controls the relationship between chart navigation and the
Pivot frontier:

| Mode | Behavior |
| --- | --- |
| `chart` | Navigate only in the chart. |
| `pivot` | Synchronize the Pivot frontier and let the linked Pivot refresh drive the chart. |
| `both` | Commit the chart frame and synchronize the Pivot. |
| `event` | Emit `pivot-chart-drill-sync`; the application owns synchronization. |

For `pivot` and `both`, the active `PivotPlugin` applies the semantic frontier
unless `pivotCharts.synchronizeDrill` is provided. The custom adapter receives
the event detail and an `AbortSignal`.

```ts
grid.pivotCharts = {
  renderer: createPivotChartsRenderer(),
  defaultDrillSyncMode: 'event',
  async synchronizeDrill(detail, { signal }) {
    await saveAnalyticsRoute(detail.to, { signal });
  },
};
```

## Legend focus and selection

Series legends are keyboard-accessible guides, not drill controls. Activating
a legend item focuses that series, emphasizes matching marks, and mutes the
others. Activating it again or selecting the chart background clears the
focus. When a dense legend cannot fit, it shows a deterministic subset and a
localized hidden-series count.

## Semantic tooltips

Interactive marks use an application-owned tooltip card rather than native SVG
`title` text. The default tooltip includes:

- the complete category path;
- series identity and formatted value;
- the resolved mark color;
- X, Y, and size rows for relationship charts;
- a drill hint when the datum has children.

Pointer tooltips stay inside the viewport. Keyboard focus opens the same card
immediately and connects it with `aria-describedby`. <kbd>Escape</kbd> closes
the tooltip without closing the chart dialog. Gallery previews intentionally
do not create tooltips.

## Keyboard and accessibility

- The modeless dialog has a stable accessible name and restores focus when it
  closes.
- Gallery tabs, cards, breadcrumbs, legend items, chart marks, export actions,
  and the data table are keyboard operable.
- Marks have localized accessible names built from category, series, formatted
  value, relationship channels, and drillability.
- The data table uses headers, a caption, row headers, and sort announcements.
- Status regions announce loading, drill success, failure, and data-table sort
  changes without replacing visible content.

## Drill and interaction events

| Event | Purpose |
| --- | --- |
| `pivot-chart-node-click` | Reports the activated semantic datum and its paths/measure when no automatic drill target exists. |
| `pivot-chart-before-drill` | Cancelable event before a drill is committed. |
| `pivot-chart-drill-start` | Announces a pending drill frame. |
| `pivot-chart-drilled` | Supplies the committed model and dataset. |
| `pivot-chart-drill-error` | Reports the failed transition and error. |
| `pivot-chart-drill-reset` | Reports a successful reset to root. |
| `pivot-chart-drill-sync` | Delegates `pivot`, `both`, or `event` synchronization. |

Event payloads clone JSON-safe semantic state. See
[Headless API and persistence](../headless-api-and-persistence/) for the full
lifecycle event list.

[Previous: Data and bindings](../data-and-bindings/) ·
[Next: Customization and export](../customization-and-export/) ·
[API reference](/api/pivot-charts/)

---

# Headless API and Persistence

URL: https://pro.rv-grid.com/guides/pivot/concepts/charts/headless-api-and-persistence/
Source: src/content/docs/guides/pivot/concepts/charts/headless-api-and-persistence.mdx
Description: Create, update, drill, export, save, restore, and destroy Pivot charts through the plugin API.

`PivotChartsPlugin` is the source of truth for chart data and lifecycle.
`PivotChartsUiPlugin` is a client of that API; applications can build their
own gallery, settings, containers, or workspace without replacing the data
model.

For normal application-owned charts, use `mountPivotChart()`:

```ts
import { mountPivotChart } from '@revolist/pivot';

const chart = await mountPivotChart(grid, {
  container: document.querySelector<HTMLElement>('#dashboard-chart')!,
});
```

## Application-owned containers

The container does not need to be inside the grid. The default
`controls: 'none'` path renders only the chart and requires no UI plugin.
Request `controls: 'standard'` when the same container should include the
built-in configuration experience:

```ts
const chart = await mountPivotChart(grid, {
  container: document.querySelector<HTMLElement>('#chart-workspace')!,
  controls: 'standard',
});
```

`controls: 'standard'` requires `PivotChartsUiPlugin`; chart-only mounting does
not. Both return the same `PivotChartRef`. Give the mount container an explicit
height. The built-in renderer fills the available size and observes later
layout changes, including a mounted container that becomes visible later.
Treat the container as an empty chart mount point: mounting replaces its
children, and `chart.destroy()` leaves it empty.

Configuration controls are optional application UI. Each control can call the
same chart ref without recreating the renderer:

```ts
chartTypeSelect.addEventListener('change', async () => {
  await chart.update({
    chartType: chartTypeSelect.value as PivotChartType,
  });
});

dataLabelsCheckbox.addEventListener('change', async () => {
  await chart.update({
    presentation: { dataLabels: dataLabelsCheckbox.checked },
  });
});
```

See the [Pivot Charts overview](../) for complete minimal markup and setup for
chart-only, standard-control, and component-lifecycle integrations.

## Direct plugin access

Use the plugin instance when an advanced workflow needs collection-wide
methods such as restore, `getChartModels()`, or `destroyAllCharts()`:

```ts
const charts = (await grid.getPlugins()).find(
  (plugin) => plugin instanceof PivotChartsPlugin,
) as PivotChartsPlugin;
```

## Plugin methods

| Method | Purpose |
| --- | --- |
| `getChartData(options?)` | Project and validate a cached immutable dataset for the current Pivot revision and optional semantic scope. |
| `createChart(params)` | Create a model, resolve data, mount a renderer instance, and return `PivotChartRef`. |
| `updateChart(chartId, patch)` | Validate and queue a model/data/presentation update. |
| `refreshChart(chartId)` | Reproject a linked chart from the current committed Pivot. |
| `canDrillDown(chartId, target)` | Test a semantic row, column, or two-axis drill target. |
| `drillDownChart(chartId, target)` | Load and commit a child frame. |
| `drillUpChart(chartId)` | Navigate to the parent frame. |
| `drillToChart(chartId, frameIndex)` | Jump to a stored breadcrumb frame. |
| `resetChartDrill(chartId)` | Return to the chart's root frame. |
| `retryChartDrill(chartId)` | Retry the last failed drill transition. |
| `getChartModels()` | Return cloned serializable models for every active chart. |
| `restoreChart(model, options)` | Validate a saved model and recreate it in a supplied container. |
| `downloadChart(chartId, options?)` | Delegate an advertised PNG/PDF download to the renderer. |
| `getChartImageDataURL(chartId, options?)` | Request an image data URL from a capable renderer. |
| `destroyChart(chartId)` | Destroy one renderer and release its state. |
| `destroyAllCharts()` | Destroy every chart owned by the plugin. |

All updates for a chart are serialized. A later linked refresh cannot
partially overwrite an earlier options update.

## Create and update

```ts
const chart = await charts.createChart({
  container: document.querySelector('#sales-chart')!,
  chartType: 'groupedColumn',
  linked: true,
  totals: 'none',
  bindings: {},
  initialScope: {
    rowPath: ['Europe'],
    rowLabels: ['Europe'],
    columnPath: [2026],
    columnLabels: ['2026'],
  },
  presentation: {
    title: 'European sales',
    legendPosition: 'bottom',
  },
  theme: 'auto',
  chartOptions: {
    showGridLines: true,
    markOpacity: 0.9,
  },
  drillSyncMode: 'chart',
});

await chart.update({
  chartType: 'stackedColumn',
  totals: 'grand',
  presentation: { subtitle: 'Including grand total' },
});
```

Data-affecting patches reproject or validate a snapshot. Presentation, theme,
and chart-option changes reuse the current dataset. Failed renderer updates
roll back to the previous model and rendered input.

## `PivotChartRef`

The ref scopes common operations to one chart:

```ts
chart.id;
chart.container;
chart.model;

await chart.update({ linked: false });
chart.canDrillDown({ axis: 'row', category });
await chart.drillDown({ axis: 'row', category });
await chart.drillUp();
await chart.drillTo(0);
await chart.resetDrill();
await chart.retryDrill();
chart.getDrillState();
chart.focus();
chart.destroy();
```

`model` and `getDrillState()` return clones. Mutating them does not update the
active chart; call `update` or a drill method.

## Model and persistence

`PivotChartModel` version 2 contains:

- stable `chartId` and `chartType`;
- link state and an optional unlinked `dataset` snapshot;
- totals, series selection, values-on-rows measure, and semantic bindings;
- presentation, renderer theme, and validated chart options;
- breadcrumb/drill scope and drill synchronization mode.

```ts
const saved = charts.getChartModels();
localStorage.setItem('pivot-charts', JSON.stringify(saved));

const restoredModels = JSON.parse(
  localStorage.getItem('pivot-charts') ?? '[]',
);

for (const model of restoredModels) {
  await charts.restoreChart(model, {
    container: createWorkspacePanel(model.chartId),
  });
}
```

Restore parses the current model version, checks chart identity, renderer
support, options, bindings, selected series, hierarchy paths, dataset shape,
limits, and linked/unlinked rules. Older model versions are rejected rather
than implicitly migrated. Supply `chartId` in `PivotChartRestoreOptions` only
when the application intentionally replaces the persisted identity.

## Custom renderer contract

```ts
const renderer: PivotChartRenderer = {
  capabilities: {
    supportedTypes: ['groupedColumn', 'line'],
    download: true,
    downloadFormats: ['png'],
    imageDataUrl: true,
  },
  create(input) {
    const instance = mountApplicationChart(input);
    return {
      update(nextInput) {
        instance.update(nextInput);
      },
      focus() {
        instance.focus();
      },
      async download(options) {
        await instance.downloadPng(options);
      },
      async getImageDataURL(options) {
        return instance.getPngDataUrl(options);
      },
      destroy() {
        instance.destroy();
      },
    };
  },
};
```

`PivotChartRenderInput` contains the chart ID, container, chart type, validated
dataset, bindings, presentation, chart options, theme, locale text,
`chart`/`preview` render mode, and the semantic node-click callback. A custom
renderer must not mutate the supplied dataset or model state.

The UI gallery exposes only `capabilities.supportedTypes`. Download and image
actions are available only when the renderer advertises and implements them.

## Standard UI API

`PivotChartsUiPlugin.openChart(params)` accepts every
`PivotChartCreateParams` field except `container`; the UI owns its chart
container. `pivotChartsUi.dialogParent` can move the modeless host into an
application overlay root. Closing the dialog destroys its chart.

`PivotChartsUiPlugin.mountChart(params)` is the lower-level equivalent of
`mountPivotChart(..., { controls: 'standard' })`. It embeds the existing
gallery, Data, Customize, current-frame table, export, and drill controls in
the supplied application container. Prefer `mountPivotChart()` unless the UI
plugin instance is already part of a larger plugin-management workflow.

## Lifecycle events

| Event | Detail |
| --- | --- |
| `pivot-chart-created` | Chart ID and `PivotChartRef`. |
| `pivot-chart-updated` | Chart ID, update reason, and cloned model. |
| `pivot-chart-destroyed` | Chart ID. |
| `pivot-chart-node-click` | Semantic category/series, paths, measure, and aggregator. |
| `pivot-chart-error` | Optional chart ID and normalized `Error`. |
| `pivot-chart-before-drill` | Cancelable transition with from/to drill state. |
| `pivot-chart-drill-start` | Pending drill transition. |
| `pivot-chart-drilled` | Successful transition with model and dataset. |
| `pivot-chart-drill-error` | Failed transition and error. |
| `pivot-chart-drill-reset` | Successful reset transition. |
| `pivot-chart-drill-sync` | Synchronization request and selected mode. |

Update reasons are `data`, `options`, `theme`, `relink`, and `drill`.

[Previous: Customization and export](../customization-and-export/) ·
[Next: Server data and performance](../server-data-and-performance/) ·
[API reference](/api/pivot-charts/)

---

# Server Data and Performance

URL: https://pro.rv-grid.com/guides/pivot/concepts/charts/server-data-and-performance/
Source: src/content/docs/guides/pivot/concepts/charts/server-data-and-performance.mdx
Description: Supply complete semantic chart frames for remote Pivots and understand validation, cancellation, caching, limits, and dense rendering.

A remote Pivot viewport is only a window into the analytical result. Pivot
Charts never treat the visible rows or columns as the complete dataset.
Configure `PivotChartDataProvider` to return the complete immediate-child frame
for every requested semantic scope.

## Configure a provider

```ts
grid.pivotCharts = {
  renderer: createPivotChartsRenderer(),
  dataProvider: {
    async load(request, { signal }) {
      const response = await fetch('/api/pivot/chart-data', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(request),
        signal,
      });

      if (!response.ok) {
        throw new Error(`Chart data failed: ${response.status}`);
      }
      return response.json();
    },
  },
};
```

The provider is used for root projection, explicit scoped data, linked
refreshes, and drill frames. Local and server Pivots produce the same
`PivotChartDataset` contract after projection and validation.

## Request contract

`PivotChartDataRequest` includes:

| Field | Purpose |
| --- | --- |
| `requestId` | Unique request identity that the response must echo. |
| `viewId` and `fieldsVersion` | Identify the remote analytical view and field registry. |
| `loadOptions` | Committed Pivot filters, sorting, grouping, and engine options. |
| `uiState` | Optional Pivot UI hints. |
| `axisState` | Expanded row and column paths. |
| `chart.seriesIds` | Requested series selection. |
| `chart.categoryMeasure` | Values-on-rows measure selection. |
| `chart.totals` | Requested totals mode. |
| `chart.limits` | Effective category, series, and point limits. |
| `chart.bindings` | Stable semantic field-to-channel bindings. |
| `chart.scope` | Exact committed revision, row/column paths, and immediate-child depths. |

The semantic scope is absolute:

```ts
interface PivotChartSemanticScope {
  revision: number;
  rowPath: PivotPath;
  columnPath: PivotPath;
  rowDepth: number;
  columnDepth: number;
}
```

The response must contain every immediate child for that scope, not a
viewport-sized subset.

## Response contract

```ts
interface PivotChartDataResponse {
  requestId: string;
  scope: PivotChartSemanticScope;
  categories: PivotChartCategory[];
  series: PivotChartSeries[];
  values: Array<Array<number | null>>;
  displayValues?: Array<Array<string | null>>;
  hierarchies: {
    row?: PivotChartHierarchyDefinition;
    column?: PivotChartHierarchyDefinition;
  };
  totalCategoryCount: number;
  totalSeriesCount: number;
}
```

`categories.length` and `series.length` describe the returned complete frame.
The total counts let the client prove that the response is complete and within
limits. Hierarchy definitions and member hierarchy metadata are required when
the response contains drillable members.

## Strict validation

The client rejects:

- a response whose `requestId` differs from the request;
- any change to revision, row/column paths, or requested depths;
- partial frames whose returned and total counts disagree;
- value/display matrices with wrong dimensions;
- duplicate or unstable category/series IDs;
- malformed hierarchy levels or member paths;
- incompatible bindings, selected series, or values-on-rows measures;
- categories, series, or point counts above the effective limits;
- data that violates the selected chart's semantic constraints.

There is no visible-window fallback. A partial response would create a
misleading chart and is treated as an error.

## Cancellation and stale results

Every provider call receives an `AbortSignal`. Abort underlying HTTP, query,
and decoding work when possible. Root loads, linked refreshes, and drill
transitions carry monotonically increasing revisions. The plugin ignores a
completion that is no longer current even if the provider did not stop after
abort.

During drill, the last successful frame remains rendered. During a linked
refresh, the UI exposes a loading state and commits the replacement only after
data validation and renderer update succeed.

## Caching

The plugin caches immutable datasets by committed Pivot revision, effective
data options, bindings, and semantic scope. Concurrent equivalent requests
share the same promise. Successful drill scopes are cached per chart so
breadcrumb navigation does not repeatedly load unchanged data.

Replacing `grid.pivotCharts`, changing the Pivot model/source/filter/sort/group
state, or advancing the committed revision invalidates the relevant cache.
Application/server caches should use the same request identity inputs and must
still return the exact requested scope.

## Dense-data behavior

Defaults are:

```ts
const DEFAULT_PIVOT_CHART_LIMITS = {
  maxCategories: 1_000,
  maxSeries: 250,
  maxDataPoints: 50_000,
};
```

Within those limits, the renderer degrades deliberately:

- every legend position reserves a valid plot rectangle;
- long legends show a deterministic subset and localized hidden count;
- category ticks and data labels are thinned without removing data;
- Cartesian marks retain exact values;
- density scatter, connected trends, small multiples, and timeline geometry
  aggregate or sample above their accessibility thresholds;
- the renderer avoids creating one focus target for every dense source point
  when that would make keyboard navigation unusable.

Sampling affects rendered geometry, not the persisted normalized dataset.
Exceeding configured projection limits fails rather than silently truncating
the model.

## Renderer preview performance

The gallery uses the same chart definitions and renderer functions as full
charts, but with `renderMode: 'preview'`. Preview mode is decorative and omits
tooltips and interactive focus targets. Intersection-based mounting and cache
keys for type, renderer, theme, and locale prevent a 63-card gallery from
creating 63 active charts at once.

## Geographic capability

Geographic views are opt-in because map geometry, projections, tiles, and
licenses belong to the provider:

```ts
const pack = createPivotChartGeographicCapabilityPack(provider);

const host = await pack.render({
  container,
  chartType: 'choropleth',
  dataset,
  bindings: { geographic: ['dimension:country'], value: ['measure:sales'] },
});
```

The pack exposes `choropleth`, `proportionalSymbolMap`, and
`geographicHeatmap`. These views are not built-in gallery types and do not
change `PivotChartModel`. Importing Pivot Charts alone loads no geographic
assets or map dependency.

## Production checklist

- Return complete immediate-child frames from the analytical engine.
- Preserve stable field, category, series, hierarchy, and path identities.
- Echo the request ID and semantic scope exactly.
- Forward abort signals to network and query work.
- Set limits that match renderer and server budgets.
- Include formatted display values when chart and Pivot formatting must match.
- Log provider errors with request/view IDs without exposing raw sensitive
  source rows.
- Exercise root, linked refresh, drill, retry, breadcrumb, and stale-response
  paths before release.

[Previous: Headless API and persistence](../headless-api-and-persistence/) ·
[Pivot Charts overview](../) ·
[Remote Pivot guide](/guides/pivot/server-side/) ·
[API reference](/api/pivot-charts/)

---

# Configuration Reference

URL: https://pro.rv-grid.com/guides/pivot/concepts/configuration-reference/
Source: src/content/docs/guides/pivot/concepts/configuration-reference.mdx
Description: Complete reference for every public PivotConfig option in the current implementation.

`PivotConfig` is the public configuration model for both client-side and server-side Pivot. This page explains every option in the current implementation and how the options interact.

For raw signatures, see [Pivot Config API](/api/pivot-config/). Use this page for defaults, behavior, and practical guidance.

## Minimal Example

```ts
const pivot: PivotConfig = {
  dimensions: [
    { prop: 'region', name: 'Region' },
    { prop: 'quarter', name: 'Quarter' },
    { prop: 'sales', name: 'Sales', aggregators: commonAggregators },
  ],
  rows: ['region'],
  columns: ['quarter'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
};
```

## Core Data Model

### `dimensions`

Reusable field definitions. This is where you configure field labels, column behavior, and available aggregators.

- Purpose: Define the fields Pivot can reuse.
- Accepted value: `PivotConfigDimension[]`
- Default: `[]`
- Important interactions: `values[].aggregator` resolves against the matching dimension.

### `rows`

Ordered row hierarchy.

- Purpose: Define the vertical analytical hierarchy.
- Accepted value: `ColumnProp[]`
- Default: required
- Important interactions: row drill-down only becomes meaningful when the effective row hierarchy has more than one level.

### `columns`

Ordered generated column hierarchy.

- Purpose: Define the horizontal analytical hierarchy.
- Accepted value: `ColumnProp[]`
- Default: `[]`
- Important interactions: `flatHeaders`, `columnCollapse`, and column totals only matter when column fields exist.

### `values`

Measures to aggregate.

- Purpose: Define which fields are summarized inside each Pivot cell.
- Accepted value: `PivotConfigValue[]`
- Default: required
- Important interactions: values can render as columns or as synthetic rows through `valuesOnRows`.

## Layout Options

### `flatHeaders`

Flattens grouped column headers into single labels.

- Purpose: Reduce visible nesting in generated columns.
- Accepted value: `boolean`
- Default: `false`
- Common pitfall: flat headers still preserve analytical grouping, they only change header presentation. With `flatHeaders: false`, generated Pivot columns use RevoGrid grouped headers so repeated parent labels are visually grouped.

### `mergeValueHeaders`

Merges generated value headers into the terminal column header labels.

- Purpose: Remove repeated measure headers such as `Revenue` under every generated column member.
- Accepted value: `boolean`
- Default: `false`
- Behavior: with one value, terminal columns use the column member label, for example `Q1`; with multiple values, the value label is appended, for example `Q1 Revenue`.
- Important interactions: can be combined with `flatHeaders`; `valuesOnRows` already moves measures out of generated value columns.

### `valuesOnRows`

Moves values into the row hierarchy.

- Purpose: Render measures as synthetic row members.
- Accepted value: `boolean`
- Default: `false`
- Important interactions: affects row drill-down behavior because values become part of the effective row structure.

### `rowTree`

Controls the effective row hierarchy, including where measures appear.

- Purpose: Place the `$values` pseudo-field at the beginning, middle, or end of the row tree.
- Accepted value: `(ColumnProp | '$values')[]`
- Default: derived from `rows`, with `$values` appended only when `valuesOnRows: true`
- Important interactions: when provided, `rowTree` overrides the value placement implied by `valuesOnRows`.

### `rowAxisLayout`

Controls the visible layout of an active multi-level row hierarchy.

- Purpose: Choose between one compact hierarchy column and one column per row field.
- Accepted value: `'compact' | 'tabular'`
- Default: `'compact'` while row drill-down is active; otherwise `'tabular'`
- Behavior:
  - `'compact'` renders group labels and terminal row values in one localized Rows column.
  - `'tabular'` preserves separate visible columns for every configured row field.
- Important note: this changes only the grid presentation. Configured row fields remain separate in aggregation, grouping, configurator state, and remote requests.

## Configurator Options

### `hasConfigurator`

Enables the built-in Pivot configurator panel.

- Purpose: Let users rearrange fields visually.
- Accepted value: `boolean`
- Default: `false`

### `mountTo`

Custom configurator mount target.

- Purpose: Render the configurator outside the default grid wrapper.
- Accepted value: `HTMLElement`
- Default: internal grid wrapper mount

### `showColumns`

Hide or show the configurator columns zone.

- Purpose: Control configurator UI visibility.
- Accepted value: `boolean`
- Default: `true`

### `showRows`

Hide or show the configurator rows zone.

- Purpose: Control configurator UI visibility.
- Accepted value: `boolean`
- Default: `true`

### `showValues`

Hide or show the configurator values zone.

- Purpose: Control configurator UI visibility.
- Accepted value: `boolean`
- Default: `true`

### `i18n`

Configurator strings.

- Purpose: Override built-in English labels.
- Accepted value: `typeof PIVOT_CONFIG_EN`
- Default: built-in English copy

## Totals

### `totals`

Controls grand totals and subtotals.

- Purpose: Add analytical summary rows and columns.
- Accepted value: `PivotConfigTotals`
- Default: all disabled

Nested options:

- `grandTotal`
- `subtotals`
- `grandTotalLabel`
- `subtotalLabel`
- `suppressSingleChildSubtotals`
- `suppressGrandTotalWhenSingleLeaf`

See [Totals](/guides/pivot/totals/) for behavior examples.

## Drill-Down State

### `collapsed`

Initial row drill-down state.

- Purpose: Enable grouped row expansion behavior.
- Accepted value: `boolean`
- Default: disabled unless `expanded` is provided or `rowAxisLayout: 'compact'` is set
- Important note: only matters when the effective row hierarchy has more than one level

### `expanded`

Persisted grouped row expansion state.

- Purpose: Restore row drill-down state.
- Accepted value: `Record<string, boolean>`
- Default: `undefined`

### `groupAggregations`

Render aggregate values inside grouped Pivot drill-down rows.

- Purpose: Show grouped branch aggregates under generated Pivot metric columns, not only the group label.
- Accepted value: `boolean`
- Default: `false`
- Important note: currently applies to the client-side Pivot path. Server-side Pivot still needs backend-precomputed grouped aggregates for exact support.

### `groupLabelColumn`

Controls which visible row cell renders grouped row labels.

- Purpose: Keep grouped labels visible when grouped fields are hidden with column-hide.
- Accepted value: `'grouped' | 'firstVisible'`
- Default: `'grouped'`
- Behavior:
  - `'grouped'` keeps labels in the grouped field column.
  - `'firstVisible'` renders labels in the first currently visible row cell.

### `columnCollapse`

Generated column collapse config.

- Purpose: Enable collapsible Pivot column groups.
- Accepted value: `boolean | PivotColumnCollapseConfig`
- Default: enabled and collapsed when `columns` is non-empty
- Disable with: `false` or `{ enabled: false }`

Nested options when using the object form:

- `enabled`
- `collapsed` (defaults to `true`; set `false` to start expanded)
- `filterable`
- `aggregator`
- `placeholder`

### `columnLevels`

Per-level generated column behavior.

- Purpose: Override collapse, subtotal, filtering, and sorting behavior for a
  specific zero-based level in `columns`.
- Accepted value: `Record<number, PivotColumnLevelConfig>`
- Default: omitted; global Pivot and value-dimension settings apply

Level options:

- `collapsible`
- `collapsed`
- `subtotal` (applies while `totals.subtotals` is enabled)
- `subtotalLabel`
- `subtotalPosition`: `'before' | 'after'` (defaults to `'before'`)
- `subtotalValues`: ordered value-field subset (defaults to all Pivot values)
- `filterable`
- `sortable`

```ts
columns: ['year', 'quarter', 'month'],
totals: { subtotals: true },
columnLevels: {
  0: {
    subtotal: true,
    subtotalLabel: 'Year Total',
    subtotalPosition: 'before',
    subtotalValues: ['sales'],
    filterable: true,
    sortable: true,
  },
  1: {
    subtotal: false,
    filterable: false,
    sortable: false,
  },
}
```

An explicit `subtotal` value in `columnLevels` takes precedence over
`totals.disabledSubtotals.columns` for that level. `totals.subtotals` remains
the global on/off switch.

See [Column Totals With Drill-Down](/guides/pivot/totals/#column-totals-with-drill-down)
for the complete configuration matrix, resolution order, interaction
guarantees, and screenshots.

### `collapsedColumns`

Persisted generated column collapse state.

- Purpose: Restore collapsed column groups.
- Accepted value: `boolean | Record<string, boolean>`
- Default: `undefined`

## Engine Options

### `engine`

Switches between local and remote analytical execution.

- Purpose: Keep the same public Pivot config while changing where computation happens.
- Accepted value: object
- Default: omitted, which keeps current client-side behavior

Nested options:

### `engine.mode`

- Accepted value: `'client' | 'server'`
- Default: omitted
- Behavior: `'server'` makes `PivotPlugin` load through an adapter or remote store

### `engine.adapter`

- Accepted value: `PivotEngineAdapter`
- Behavior: custom execution boundary used directly by the plugin

### `engine.remoteStore`

- Accepted value: `PivotRemoteStore`
- Behavior: framework-agnostic HTTP or transport-backed store used by the server adapter

### `engine.viewId`

- Accepted value: `string`
- Default: `'default'`
- Behavior: backend semantic view or dataset identifier

### `engine.fieldsVersion`

- Accepted value: `string`
- Default: `'local'`
- Behavior: field registry version or checksum

### `engine.rowAxis`

- Accepted value: `Partial`
- Default: `{ offset: 0, limit: 100 }`
- Behavior: initial row-axis analytical window hint

### `engine.columnAxis`

- Accepted value: `Partial`
- Default: `{ offset: 0, limit: 24 }`
- Behavior: initial column-axis analytical window and hierarchy frontier.
  `expandedPaths` and `collapsedPaths` use typed analytical paths and are
  updated automatically by Pivot column expand/collapse controls in server
  mode.

## Realistic Example

```ts
const pivot: PivotConfig = {
  dimensions: [
    { prop: 'region', name: 'Region', sortable: true },
    { prop: 'rep', name: 'Rep' },
    { prop: 'year', name: 'Year' },
    { prop: 'quarter', name: 'Quarter' },
    {
      prop: 'sales',
      name: 'Sales',
      aggregators: commonAggregators,
    },
  ],
  rows: ['region', 'rep'],
  columns: ['year', 'quarter'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  totals: { grandTotal: true, subtotals: true },
  collapsed: true,
  groupAggregations: true,
  hasConfigurator: true,
};
```

## Common Mistakes

- Treating `dimensions` as optional metadata only. They are the field model Pivot depends on.
- Expecting `columns` to be required. A row-only Pivot is valid.
- Using `columnCollapse` without generated column groups.
- Assuming `engine` changes the public config shape. It only changes the execution path.

## Related Guides

- [Plugin Lifecycle](/guides/pivot/plugin-lifecycle/)
- [Configurator API](/guides/pivot/configurator-api/)
- [Field Panel](/guides/pivot/field-panel/)
- [Server-Side Pivot](/guides/pivot/server-side/)
- [OLAP Best Practices](/guides/pivot/olap-best-practices/)

---

# Dimensions

URL: https://pro.rv-grid.com/guides/pivot/concepts/dimensions/
Source: src/content/docs/guides/pivot/concepts/dimensions.mdx
Description: Understand Pivot dimensions, how they map to fields, and which column options carry over into Pivot.

A Pivot dimension is the reusable definition of a field. It tells Pivot what the field is called, how it should behave in generated headers, and which aggregators are valid when that field is used as a measure source.

## What A Dimension Is

Each dimension is a `PivotConfigDimension`. In practice it is a partial RevoGrid column definition plus Pivot-specific metadata.

```ts
const dimensions = [
  { prop: 'region', name: 'Region', sortable: true },
  { prop: 'quarter', name: 'Quarter' },
  {
    prop: 'sales',
    name: 'Sales',
    aggregators: {
      sum: commonAggregators.sum,
      avg: commonAggregators.avg,
    },
  },
];
```

`prop` is the source-of-truth field id. `rows`, `columns`, and `values` all refer back to these same `prop` values.

## How Dimensions Are Reused

- In `rows`, a dimension becomes part of the leading row hierarchy.
- In `columns`, a dimension becomes part of the generated header hierarchy.
- In `values`, the same field acts as the carrier for the aggregated measure.

This shared model is what keeps Pivot configuration consistent. You define a field once, then reuse it on whichever analytical axis makes sense.

## Column Options That Matter In Pivot

`PivotConfigDimension` extends `Partial`, so the most useful inherited options are:

- `prop`: The field id Pivot uses everywhere.
- `name`: Display label for generated headers and configurator entries.
- `sortable`: Enables sorting of generated members for that dimension.
- `order`: Initial sort direction for generated members when sorting is enabled.
- `filter`: Filter metadata carried into generated columns.
- `columnType`: Lets generated value columns reuse an existing column type.
- `template`: Custom rendering for generated cells or headers.
- `cellProperties`: Per-cell visual or behavioral overrides.
- `size`, `minSize`, `maxSize`: Width behavior for generated columns.

The most important rule is that Pivot does not invent a second metadata model. Generated columns are still RevoGrid columns, and the dimension is where their base behavior comes from.

## Aggregators Live On The Dimension

Dimensions also declare which aggregators are available when the field is used in `values`.

```ts
{
  prop: 'margin',
  name: 'Margin',
  aggregators: {
    sum: commonAggregators.sum,
    avg: commonAggregators.avg,
    max: commonAggregators.max,
  },
}
```

This matters in two places:

- `values[].aggregator` resolves against the dimension.
- The configurator uses the dimension's registered aggregators to populate its value selector.

## Good Dimension Design

- Keep `prop` stable. Changing it breaks saved Pivot layouts.
- Use business-friendly `name` values because generated headers reuse them.
- Define aggregators only where they make semantic sense.
- Avoid using display labels as identifiers. `prop` should be the identifier, `name` should be presentation.

## Common Mistakes

- Omitting a dimension for a field that later appears in `values`.
- Registering an aggregator on a text field just because the function exists.
- Expecting dimension order to control row or column placement. Placement is controlled by `rows` and `columns`, not by the `dimensions` array order.

## Next

Continue with [Aggregations](/guides/pivot/aggregations/) to see how measures are resolved from these dimensions.

---

# Drill-Down

URL: https://pro.rv-grid.com/guides/pivot/concepts/drilldown/
Source: src/content/docs/guides/pivot/concepts/drilldown.mdx
Description: Understand row expansion, column collapse, and the state that controls Pivot exploration.

Drill-down lets users move between summary and detail inside the Pivot structure. In the current implementation there are two separate drill-down concepts: grouped row expansion and generated column collapse.

## Row Drill-Down

Row drill-down is enabled when:

- the effective row hierarchy has more than one level
- `collapsed` is a boolean, `expanded` state exists, or `rowAxisLayout` is `'compact'`

```ts
const pivot: PivotConfig = {
  rows: ['region', 'rep'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  collapsed: true,
};
```

Behavior:

- `collapsed: true` starts grouped rows collapsed
- `collapsed: false` starts grouped rows expanded
- `expanded` stores per-group overrides using grouped path keys
- active row drill-down uses one compact Rows column by default
- `rowAxisLayout: 'tabular'` keeps one visible column per configured row field

Compact mode changes only the generated grid columns. The Pivot model, field
panel, persisted configuration, and remote requests continue to use separate
`region` and `rep` dimensions.

```ts
const pivot: PivotConfig = {
  rows: ['region', 'rep'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  collapsed: true,
  rowAxisLayout: 'tabular', // opt back into separate Region and Rep columns
};
```

`PivotPlugin` translates the Pivot row structure into RevoGrid grouping options, then emits `pivot-config-update` when users expand or collapse groups.

## Grouped Row Aggregates

Set `groupAggregations: true` to render aggregate values inside grouped Pivot rows.

```ts
const pivot: PivotConfig = {
  rows: ['region', 'rep'],
  columns: ['year'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  collapsed: true,
  groupAggregations: true,
};
```

Behavior:

- the grouped row still shows the expand/collapse UI and group label
- generated Pivot value columns show the aggregate for the current grouped branch
- nested groups aggregate only their own descendants
- collapsed groups still show their aggregate values

If you hide the grouped row field column (for example with `hide-columns="region"`), you can move the grouped label into the first visible row cell:

```ts
const pivot: PivotConfig = {
  rows: ['region', 'product'],
  columns: ['quarter'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
  collapsed: true,
  rowAxisLayout: 'tabular',
  groupAggregations: true,
  groupLabelColumn: 'firstVisible',
};
```

`groupLabelColumn` modes:

- `'grouped'` (default): keep label in the grouped field column
- `'firstVisible'`: render label in the first currently visible row cell

Current limitation:

- `groupAggregations` currently applies to the client-side Pivot path
- server-side Pivot still renders grouped labels only unless backend-precomputed grouped aggregates are added

## Column Drill-Down

Column drill-down is built into Pivot whenever `columns` is non-empty. Generated
groups start collapsed without additional configuration.

```ts
columns: ['year', 'quarter', 'month']
```

Behavior:

- generated Pivot column groups become collapsible
- generated groups start collapsed at the highest level and expand one level at a time
- set `columnCollapse: false` or `{ enabled: false }` to disable column drill-down
- set `columnCollapse: { collapsed: false }` to start with all generated groups expanded
- use `columnLevels` to override collapse, subtotal, filter, and sort behavior
  independently at each zero-based column level
- collapsed groups render a placeholder header/cell
- placeholder cells use a collapsed-bucket aggregator, not a naive sum of visible child cells
- expanded subtotal columns appear before descendant columns by default, keeping
  the parent aggregate visible and actionable
- `columnLevels[level].subtotalValues` can keep that aggregate to one value
  field—or any ordered subset—when the Pivot has multiple measures
- expanding reveals one level only; descendants and sibling branches keep
  their current state
- aggregate filters and sorting remain attached to the same analytical group
  when its compact and expanded presentations switch

Persisted state for generated groups lives in `collapsedColumns`.

See [Column Totals With Drill-Down](/guides/pivot/totals/#column-totals-with-drill-down)
for the complete subtotal/collapse behavior matrix, precedence rules, and
screenshots.

## Related Options

- `collapsed`: row drill-down default
- `expanded`: persisted row group expansion state
- `groupAggregations`: render aggregate values inside grouped client-side Pivot rows
- `groupLabelColumn`: choose where grouped row labels render (`'grouped'` or `'firstVisible'`)
- `columnCollapse`: enable and configure generated column collapse
- `columnLevels`: configure each generated column hierarchy level
- `collapsedColumns`: persisted generated column collapse state

## Placeholder Behavior

When a column group is collapsed, Pivot can render:

- a default placeholder header based on the group name
- a custom placeholder header or cell template
- a custom collapsed aggregator, globally or per value field

This is useful when a collapsed analytical bucket should still show a meaningful aggregate instead of just hiding all child columns.

## State Persistence

`PivotPlugin` emits `pivot-config-update` as users interact with grouped rows or collapsible columns. That event is the right place to persist the current Pivot state if you want drill-down state to survive reloads.

## Common Mistakes

- Expecting row drill-down with only one row field.
- Expecting grouped rows to show metric values without enabling `groupAggregations`.
- Expecting `columnCollapse` to work without generated column groups.
- Treating `expanded` as UI row indexes. It is persisted grouped state, not viewport position.

## Next

Continue with [Sorting And Filtering](../pivot/sorting-filtering/) or [Plugin Lifecycle](../pivot/plugin-lifecycle/).

---

# Export And State

URL: https://pro.rv-grid.com/guides/pivot/concepts/export-state/
Source: src/content/docs/guides/pivot/concepts/export-state.mdx
Description: Export visible Pivot data to CSV, copy Pivot data as TSV, and save Pivot layout as JSON.

Pivot export helpers turn the current visible Pivot grid into plain text that users can download, paste, or save. Pivot state JSON saves the Pivot configuration so the same report layout can be restored later.

## What Each Format Is For

CSV means comma-separated values. Use CSV when users need a file they can open in Excel, Numbers, Google Sheets, or another reporting tool. The Pivot CSV helper flattens grouped column headers into readable header paths and appends pinned bottom rows, such as grand totals, after the body rows.

TSV means tab-separated values. Use TSV for copy and paste because spreadsheets understand tabs as cell boundaries. The Pivot TSV helper keeps row-axis headers and column-axis headers separated, which makes pasted Pivot output easier to read.

State JSON is not table data. It is a saved Pivot configuration, including fields such as rows, columns, values, filters, totals, collapsed state, and expanded groups. Use state JSON when users need to save a report layout, share a layout, or restore a layout after reloading the page.

## Basic Setup

Import the helpers from `@revolist/pivot` with the Pivot plugin:

```ts
import {
  buildPivotCopyTsv,
  exportVisiblePivotToCsv,
  parsePivotStateJson,
  PivotPlugin,
  serializePivotStateJson,
  type PivotConfig,
} from '@revolist/pivot';
```

Render Pivot as usual:

```ts
const pivot: PivotConfig = {
  rows: ['region', 'channel'],
  columns: ['quarter'],
  values: [
    { prop: 'revenue', aggregator: 'sum', label: 'Revenue' },
    { prop: 'orders', aggregator: 'sum', label: 'Orders' },
  ],
  totals: {
    grandTotal: true,
    subtotals: true,
  },
};

grid.plugins = [PivotPlugin];
grid.pivot = pivot;
grid.source = rows;
```

## Read The Visible Grid Model

CSV and TSV helpers work from the current grid model, not from the original raw dataset. Pass the visible `columns`, visible `source`, and any `pinnedBottomSource`.

```ts
function readGridModel(grid: HTMLRevoGridElement & { pinnedBottomSource?: any[] }) {
  return {
    columns: grid.columns ?? [],
    source: grid.source ?? [],
    pinnedBottomSource: grid.pinnedBottomSource ?? [],
  };
}
```

This matters because Pivot generates columns and rows from the source data. Exporting the original array would miss generated value columns, grouped headers, subtotal rows, and grand-total rows.

## Export CSV

Use `exportVisiblePivotToCsv` when the user wants a file-oriented export:

```ts
const csv = exportVisiblePivotToCsv(readGridModel(grid));
```

For browser download:

```ts
const csv = exportVisiblePivotToCsv(readGridModel(grid));
const blob = new Blob([csv], { type: 'text/csv;charset=utf-8' });
const url = URL.createObjectURL(blob);
const link = document.createElement('a');

link.href = url;
link.download = 'pivot-report.csv';
link.click();

URL.revokeObjectURL(url);
```

CSV is best for file export, email attachments, imports into other systems, and audit snapshots.

## Copy TSV

Use `buildPivotCopyTsv` when the user wants clipboard text:

```ts
const tsv = buildPivotCopyTsv(readGridModel(grid));
await navigator.clipboard.writeText(tsv);
```

TSV is best for copy actions because pasting into a spreadsheet preserves cells without requiring the user to import a file.

You can also limit copy output when you know the selected props or selected rows:

```ts
const tsv = buildPivotCopyTsv({
  ...readGridModel(grid),
  selectedProps: ['region', '__pivot_grand_total__|revenue'],
  selectedRowIndexes: [0, 1, 2],
});
```

Only pass selected props that exist in the current visible columns. Missing props are ignored.

## Save State JSON

Use `serializePivotStateJson` to turn the current Pivot configuration into deterministic JSON:

```ts
const json = serializePivotStateJson(pivot);
localStorage.setItem('sales:pivot-state', json);
```

The JSON is wrapped with a kind and version so the parser can reject unsupported state:

```json
{
  "config": {
    "columns": ["quarter"],
    "rows": ["region", "channel"],
    "values": [{ "aggregator": "sum", "prop": "revenue" }]
  },
  "kind": "revogrid:pivot.state",
  "version": 1
}
```

Use `parsePivotStateJson` to validate and restore it:

```ts
try {
  const saved = localStorage.getItem('sales:pivot-state');

  if (saved) {
    grid.pivot = parsePivotStateJson(saved) as PivotConfig;
  }
} catch (error) {
  console.error('Could not restore Pivot state:', error);
}
```

State JSON is best for saved views, shared report layouts, user preferences, and restoring drill-down state after refresh.

## Practical Example

This example exposes four buttons:

- `CSV`: reads the visible Pivot grid and writes CSV text into the output box.
- `TSV`: reads the visible Pivot grid and writes clipboard-ready TSV into the output box.
- `State JSON`: serializes the current Pivot configuration.
- `Apply JSON`: parses the edited JSON and applies it back to the grid.

The important part is keeping the data export path separate from the state path:

```ts
let pivotConfig: PivotConfig = {
  rows: ['region', 'channel'],
  columns: ['quarter'],
  values: [
    { prop: 'revenue', aggregator: 'sum', label: 'Revenue' },
    { prop: 'orders', aggregator: 'sum', label: 'Orders' },
  ],
};

function showCsv() {
  output.value = exportVisiblePivotToCsv(readGridModel(grid));
}

function showTsv() {
  output.value = buildPivotCopyTsv(readGridModel(grid));
}

function showState() {
  output.value = serializePivotStateJson(pivotConfig);
}

function applyState() {
  pivotConfig = parsePivotStateJson(output.value) as PivotConfig;
  grid.pivot = pivotConfig;
}
```

## Common Mistakes

- Exporting the original source rows instead of the visible grid model. Use `grid.columns`, `grid.source`, and `grid.pinnedBottomSource`.
- Using CSV for copy and paste. TSV usually pastes into spreadsheet cells more reliably.
- Expecting state JSON to contain row data. It stores Pivot configuration, not the source dataset or exported result.
- Applying edited JSON without `try` / `catch`. Invalid JSON, unsupported versions, and invalid field shapes throw errors.
- Forgetting pinned bottom rows. If grand totals are enabled, include `pinnedBottomSource` so totals appear in CSV and TSV output.
- Saving functions in state JSON. State JSON can only contain JSON-safe configuration values; custom runtime callbacks must be restored by application code.

## Next

Continue with [Sorting And Filtering](../sorting-filtering/) or [Field Panel](../field-panel/).

---

# Field Metadata

URL: https://pro.rv-grid.com/guides/pivot/concepts/field-metadata/
Source: src/content/docs/guides/pivot/concepts/field-metadata.mdx
Description: Configure Pivot field labels, hidden dimensions, empty group labels, measure aliases, and selective subtotals.

Field metadata is the information Pivot uses to describe fields before they become row groups, column groups, filters, or measures. Use it to give users clearer labels, keep internal fields out of normal field lists, and make generated totals easier to read.

## Hidden Dimensions

Mark a dimension as `hidden` when it should still be available to the Pivot config but should not appear in normal field lists.

```ts
const dimensions = [
  { prop: 'region', name: 'Region' },
  { prop: 'quarter', name: 'Quarter' },
  {
    prop: 'internalSegment',
    name: 'Internal Segment',
    description: 'Internal reporting segment.',
    hidden: true,
  },
];

const pivot = {
  dimensions,
  rows: ['region'],
  columns: ['quarter', 'internalSegment'],
  filters: ['internalSegment'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
};
```

Hidden does not remove the field from the Pivot engine. In this example, `internalSegment` can still be used in `columns` and `filters`; it is only hidden from helper-driven field lists unless you explicitly show hidden fields.

## Show Hidden Fields In Search

Use `filterPivotDimensions` for searchable field lists. Hidden dimensions are omitted by default. Pass `{ showHidden: true }` when you want an admin or advanced-user mode that reveals them.

```ts
import { filterPivotDimensions } from '@revolist/pivot';

const visibleFields = filterPivotDimensions(dimensions, searchText);

const allFields = filterPivotDimensions(dimensions, searchText, {
  showHidden: true,
});
```

The helper searches `prop`, `name`, and `description`, so descriptions are useful for discovery even when the visible label is short.

## Empty And Null Group Labels

Real data often contains empty strings, `null`, or `undefined`. Pivot can replace those values with user-facing labels in row and column groups.

```ts
const pivot = {
  rows: ['region', 'channel'],
  columns: ['quarter'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
  groupLabels: {
    empty: '(Empty)',
    null: '(No value)',
  },
};
```

`groupLabels.empty` is used for empty strings (`''`). `groupLabels.null` is used for `null` and `undefined`. Without these options, the current implementation displays empty labels for those group members.

## Measure Aliases

Each value can have its own display label. Use `label` for the preferred generated measure name. Use `name` as a fallback when `label` is not set.

```ts
const pivot = {
  values: [
    { prop: 'revenue', aggregator: 'sum', label: 'Revenue $' },
    { prop: 'units', aggregator: 'sum', name: 'Units Sold' },
  ],
};
```

Aliases are useful when the source field name is technical, abbreviated, or shared by multiple reports.

## Disabled Subtotals

Global subtotals can stay enabled while specific subtotal rows or subtotal columns are skipped. Target subtotals by axis field or by zero-based axis level.

```ts
const pivot = {
  rows: ['region', 'channel', 'product'],
  columns: ['quarter', 'internalSegment'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
  totals: {
    grandTotal: true,
    subtotals: true,
    disabledSubtotals: {
      rows: {
        fields: ['channel'],
      },
      columns: {
        levels: [0],
      },
    },
  },
};
```

In this example, Pivot keeps subtotal generation enabled overall, skips row subtotals for the `channel` field, and skips column subtotals at level `0`.

## Complete Config

```ts
const pivot = {
  dimensions: [
    { prop: 'region', name: 'Region', description: 'Sales territory.' },
    { prop: 'channel', name: 'Channel', description: 'Go-to-market channel.' },
    { prop: 'product', name: 'Product' },
    { prop: 'quarter', name: 'Quarter' },
    { prop: 'internalSegment', name: 'Internal Segment', hidden: true },
    { prop: 'revenue', name: 'Revenue' },
    { prop: 'units', name: 'Units' },
  ],
  rows: ['region', 'channel', 'product'],
  columns: ['quarter', 'internalSegment'],
  filters: ['internalSegment'],
  values: [
    { prop: 'revenue', aggregator: 'sum', label: 'Revenue $' },
    { prop: 'units', aggregator: 'sum', name: 'Units Sold' },
  ],
  groupLabels: {
    empty: '(Empty)',
    null: '(No value)',
  },
  totals: {
    grandTotal: true,
    subtotals: true,
    disabledSubtotals: {
      rows: { fields: ['channel'] },
      columns: { levels: [0] },
    },
  },
};
```

## Common Mistakes

- Expecting `hidden: true` to prevent a field from being used in `rows`, `columns`, `filters`, or `values`. It only affects field-list helpers.
- Passing `{ showHidden: true }` to the Pivot config. It belongs to `filterPivotDimensions`, not `pivot`.
- Using only `groupLabels.empty` when the source data contains `null` or `undefined`.
- Disabling `totals.subtotals` and then expecting `disabledSubtotals` to do anything. Selective disabling only matters when `subtotals: true`.

---

# Field Panel

URL: https://pro.rv-grid.com/guides/pivot/concepts/field-panel/
Source: src/content/docs/guides/pivot/concepts/field-panel.mdx
Description: Show Pivot row, column, data, and filter fields above the grid.

The Pivot field panel renders the active field layout above the grid. Use it when users need to see or rearrange row, column, data, and filter fields without opening a separate configurator panel.

## Enable It

```ts
const pivot = {
  dimensions: [...],
  rows: ['region', 'rep'],
  columns: ['year', 'quarter'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  filters: ['year'],
  fieldPanel: {
    visible: true,
    showResetLayout: false,
    allowFieldDragging: true,
    allowFieldRemoving: false,
    showDataFields: true,
    showRowFields: true,
    showColumnFields: true,
    showFilterFields: true,
    texts: {
      dropFilterFieldsHere: 'Drop Filter Fields Here',
    },
  },
};
```

## Options

- `fieldPanel.visible`: mounts the compact in-grid field panel.
- `fieldPanel.showResetLayout`: shows the Reset layout action in Pivot configuration UI. Default is `false`.
- `allowFieldDragging`: enables drag-and-drop between panel areas.
- `allowFieldRemoving`: enables explicit removal from areas. Default is `false`.
- `showDataFields`, `showRowFields`, `showColumnFields`, `showFilterFields`: toggle individual areas.
- `fieldPanel.texts`: overrides field panel labels and placeholders.
- `filters`: stores the ordered filter fields shown in the filter area.

`fieldPanel.visible` is separate from `hasConfigurator`. Use `fieldPanel.visible` for the compact in-grid field strip, and `hasConfigurator` for the full side configurator.

## Reuse Dropdown Cell Templates

Filter fields with `filterOptions` can reuse the owning dimension's dropdown
presentation. Enable `dropdown.syncCellTemplate` and provide the same dropdown
source metadata used by the cell template:

```ts
const statusBadge = (h, { model, value }) =>
  h('span', { class: `status-badge ${model.tone}` }, value);

const pivot = {
  dimensions: [{
    prop: 'status',
    filterOptions: ['Open', 'Closed'],
    cellTemplate: statusBadge,
    dropdown: {
      syncCellTemplate: true,
      source: [
        { value: 'Open', label: 'Open', tone: 'green' },
        { value: 'Closed', label: 'Closed', tone: 'gray' },
      ],
    },
  }],
  filters: ['status'],
};
```

The synchronized content is used by both the compact field-panel selector and
the Pivot member-filter dialog. Explicit dropdown renderers remain
authoritative. When the field panel is mounted by `PivotPlugin`, grid
`columnTypes` and `additionalData` are forwarded to the template resolver.

---

# Formatting Presets

URL: https://pro.rv-grid.com/guides/pivot/concepts/formatting-presets/
Source: src/content/docs/guides/pivot/concepts/formatting-presets.mdx
Description: Format Pivot values with locale-aware number, currency, percent, and date presets, then highlight analytical cells with conditional formatting.

Formatting presets help Pivot reports show numbers, money, percentages, and dates in a readable way. Conditional formatting presets then help users spot high revenue, low margin, or other important analytical values.

## Basic Setup

Import the helpers from `@revolist/pivot` and create reusable formatters for the value types in your report:

```ts
import {
  createPivotValueFormatter,
  formatPivotValue,
  pivotConditionalFormattingPresets,
  createPivotConditionalCellProperties,
  PivotPlugin,
  type PivotConfig,
} from '@revolist/pivot';

const revenueFormatter = createPivotValueFormatter({
  preset: 'currency',
  currency: 'USD',
  locale: 'en-US',
  options: { maximumFractionDigits: 0 },
});

const marginFormatter = createPivotValueFormatter({
  preset: 'percent',
  locale: 'en-US',
  options: { minimumFractionDigits: 1, maximumFractionDigits: 1 },
});
```

`createPivotValueFormatter()` returns a function. Use it when the same formatting rule is reused by many cells. Use `formatPivotValue()` when you only need to format one value:

```ts
const formattedLabel = formatPivotValue(null, {
  preset: 'date',
  nullDisplay: 'No close date',
});
```

## Value Formatters

Pivot formatters are display helpers. They do not change the original source data or the aggregated number that Pivot calculates. Keep your source values as real numbers and dates, then format them at render time.

```ts
const columnTypes = {
  pivotCurrency: {
    cellTemplate: (_h, props) => revenueFormatter(props.value),
    cellProperties: () => ({ class: { 'align-right': true } }),
  },
  pivotPercent: {
    cellTemplate: (_h, props) => marginFormatter(props.value),
    cellProperties: () => ({ class: { 'align-right': true } }),
  },
};
```

Attach those column types to the Pivot dimensions that produce analytical value cells:

```ts
const pivot: PivotConfig = {
  dimensions: [
    { prop: 'region', name: 'Region' },
    { prop: 'closeDate', name: 'Close date', columnType: 'pivotDate' },
    { prop: 'segment', name: 'Segment' },
    { prop: 'revenue', name: 'Revenue', columnType: 'pivotCurrency' },
    { prop: 'marginRate', name: 'Margin', columnType: 'pivotPercent' },
  ],
  rows: ['region', 'closeDate'],
  columns: ['segment'],
  values: [
    { prop: 'revenue', aggregator: 'sum', label: 'Revenue' },
    { prop: 'marginRate', aggregator: 'avg', label: 'Avg margin' },
  ],
};
```

## Locale And Presets

The formatter presets use the browser `Intl` formatters. Choose the preset that matches the value:

- `number`: plain numeric values such as counts, units, or scores.
- `currency`: money values. Always provide `currency`, for example `"USD"` or `"EUR"`.
- `percent`: ratio values such as `0.315`, displayed as `31.5%`.
- `date`: date-only values.
- `datetime`: date and time values.

```ts
const integerFormatter = createPivotValueFormatter({
  preset: 'number',
  locale: 'en-US',
  options: { maximumFractionDigits: 0 },
});

const eurFormatter = createPivotValueFormatter({
  preset: 'currency',
  currency: 'EUR',
  locale: 'de-DE',
});

const dateFormatter = createPivotValueFormatter({
  preset: 'date',
  locale: 'en-US',
  options: { month: 'short', day: '2-digit', year: 'numeric' },
});
```

## Conditional Formatting Presets

Use `pivotConditionalFormattingPresets` to describe matching rules, and `createPivotConditionalCellProperties()` to turn those rules into a RevoGrid `cellProperties` function.

```ts
const conditionalCellProperties = createPivotConditionalCellProperties(
  [
    pivotConditionalFormattingPresets.gt(300000, {
      field: 'revenue',
      style: {
        backgroundColor: 'rgba(22, 163, 74, 0.16)',
        color: '#166534',
        fontWeight: '600',
      },
    }),
    pivotConditionalFormattingPresets.lt(0.28, {
      field: 'marginRate',
      style: {
        backgroundColor: 'rgba(220, 38, 38, 0.14)',
        color: '#991b1b',
        fontWeight: '600',
      },
    }),
    pivotConditionalFormattingPresets.between(0.28, 0.34, {
      field: 'marginRate',
      style: {
        backgroundColor: 'rgba(234, 179, 8, 0.14)',
        color: '#854d0e',
      },
    }),
  ],
  { match: 'all' },
);
```

Available presets:

- `gt(value, props)`: greater than a number.
- `lt(value, props)`: less than a number.
- `between(min, max, props)`: between two numbers, including both bounds.
- `equal(value, props)`: equal to a value.
- `textContains(value, props)`: contains text.

The optional `field` narrows a rule to a generated value field. For example, `field: 'revenue'` applies to generated revenue cells even when Pivot creates column paths such as `Software|revenue`.

## Analytical Cells

By default, `createPivotConditionalCellProperties()` only formats Pivot analytical cells. These are generated cells from the `values` area, not row header fields such as `region` or `closeDate`.

This default prevents a rule like `gt(300000)` from accidentally styling row dimensions that happen to contain comparable values. If you intentionally want rules to apply outside analytical value cells, enable `includeNonAnalytical`:

```ts
const allCellProperties = createPivotConditionalCellProperties(rules, {
  includeNonAnalytical: true,
});
```

Most Pivot reports should keep the default and attach conditional formatting to value dimensions:

```ts
const pivot: PivotConfig = {
  dimensions: [
    { prop: 'region', name: 'Region' },
    {
      prop: 'revenue',
      name: 'Revenue',
      columnType: 'pivotCurrency',
      cellProperties: conditionalCellProperties,
    },
    {
      prop: 'marginRate',
      name: 'Margin',
      columnType: 'pivotPercent',
      cellProperties: conditionalCellProperties,
    },
  ],
  rows: ['region'],
  columns: ['segment'],
  values: [
    { prop: 'revenue', aggregator: 'sum' },
    { prop: 'marginRate', aggregator: 'avg' },
  ],
};
```

## Practical Example

This report groups opportunities by region and close date, splits generated value columns by segment, formats revenue as currency, formats margin as a percent, and highlights high revenue or weak margin.

```ts
const rows = [
  { region: 'North America', closeDate: '2026-01-16', segment: 'Software', revenue: 184000, marginRate: 0.37 },
  { region: 'North America', closeDate: '2026-01-22', segment: 'Services', revenue: 126000, marginRate: 0.31 },
  { region: 'EMEA', closeDate: '2026-02-06', segment: 'Services', revenue: 118000, marginRate: 0.28 },
];

const pivot: PivotConfig = {
  dimensions: [
    { prop: 'region', name: 'Region' },
    { prop: 'closeDate', name: 'Close date', columnType: 'pivotDate' },
    {
      prop: 'revenue',
      name: 'Revenue',
      columnType: 'pivotCurrency',
      cellProperties: conditionalCellProperties,
    },
    {
      prop: 'marginRate',
      name: 'Margin',
      columnType: 'pivotPercent',
      cellProperties: conditionalCellProperties,
    },
  ],
  rows: ['region', 'closeDate'],
  columns: ['segment'],
  values: [
    { prop: 'revenue', aggregator: 'sum', label: 'Revenue' },
    { prop: 'marginRate', aggregator: 'avg', label: 'Avg margin' },
  ],
  totals: {
    subtotals: true,
    grandTotal: true,
  },
  groupLabels: {
    null: formatPivotValue(null, { preset: 'date', nullDisplay: 'No close date' }),
  },
};

const grid = document.querySelector('revo-grid');
grid.columnTypes = columnTypes;
grid.plugins = [PivotPlugin];
grid.pivot = pivot;
grid.source = rows;
```

## Common Mistakes

- Formatting the source data before Pivot aggregates it. Keep values numeric so `sum`, `avg`, and comparisons work correctly.
- Using `preset: 'percent'` with whole percentages. `31.5%` should usually be stored as `0.315`, not `31.5`.
- Forgetting `currency` when using the `currency` preset.
- Expecting conditional formatting to affect row fields by default. It targets analytical value cells unless `includeNonAnalytical` is enabled.
- Omitting `field` on a conditional rule when the report has several value fields. Without `field`, the rule can match every analytical value cell.
- Expecting `cellTemplate` formatting to change conditional comparisons. Conditional rules evaluate the raw cell value, not the formatted display string.

## Next

Continue with [Sorting And Filtering](../sorting-filtering/) or [Configuration Reference](/guides/pivot/configuration-reference/).

---

# Plugin Lifecycle

URL: https://pro.rv-grid.com/guides/pivot/concepts/plugin-lifecycle/
Source: src/content/docs/guides/pivot/concepts/plugin-lifecycle.mdx
Description: Understand how PivotPlugin applies, updates, and clears Pivot state on a RevoGrid instance.

`PivotPlugin` is the runtime layer that turns the direct `grid.pivot` config into rendered rows, generated columns, and grouped state. Understanding its lifecycle helps you persist user choices, avoid conflicting updates, and reason about when Pivot owns the grid payload.

## Activation

Pivot activates when:

- `PivotPlugin` is present in `grid.plugins`
- `grid.pivot` contains a config

The plugin observes the direct `pivot` property and reapplies Pivot whenever the config changes. Legacy `additionalData.pivot` updates are still supported for compatibility.

## What Happens On Apply

When `applyPivot` runs:

1. the plugin captures the original source, columns, grouping, and pinned-bottom rows on first activation
2. it decides whether to use the client or server execution path
3. it generates or loads Pivot rows and columns
4. it writes those generated structures back to the grid

This means Pivot is temporarily the owner of the rendered grid payload.

## Client Path

In client mode:

- raw grid source is read from the captured original data
- `createPivotData` materializes Pivot rows
- `pivotColumns` generates the column tree
- grand total rows are moved to `pinnedBottomSource`

## Server Path

In server mode:

- the plugin resolves a `PivotEngineAdapter`
- it builds a `PivotLoadRequest`
- it aborts any stale in-flight remote request
- only the latest response is allowed to update the grid

This is the last-write-wins behavior that protects the UI when filters or layouts change quickly.

## Configurator Integration

If `hasConfigurator` is enabled, the plugin renders the configurator and wires its updates back into the Pivot state. Each configurator update:

- emits `pivot-config-update`
- applies the updated config unless the event was prevented

## `pivot-config-update`

This event is the main integration point for external state ownership.

Use it to:

- persist layout changes
- sync Pivot state into a framework store
- restore `expanded` or `collapsedColumns` later

## Reapplication Triggers

Pivot recalculates when:

- `grid.pivot` changes
- legacy `additionalData.pivot` changes
- the underlying non-Pivot source changes
- the underlying non-Pivot columns change
- row drill-down or column collapse state changes through plugin-managed interactions

The plugin intentionally avoids treating already-generated Pivot rows or columns as new base inputs.

## Clearing Pivot

`clearPivot()`:

- aborts any remote load
- removes managed Pivot state
- restores the original source, columns, grouping, and pinned-bottom rows

Removing `grid.pivot` has the same practical effect. Removing legacy `additionalData.pivot` also clears Pivot when that legacy path is the active source.

## Best Practices

- Treat direct `grid.pivot` / framework `pivot` binding as the durable state you own.
- Listen to `pivot-config-update` if user changes should persist.
- Do not manually overwrite `grid.source` or `grid.columns` with Pivot active unless you mean to replace the base data and trigger a reapply.

## Related Guides

- [Configuration Reference](/guides/pivot/configuration-reference/)
- [Pivot Charts](/guides/pivot/concepts/charts/)
- [Configurator API](/guides/pivot/configurator-api/)
- [Field Panel](/guides/pivot/field-panel/)
- [Server-Side Pivot](/guides/pivot/server-side/)

---

# Sorting And Filtering

URL: https://pro.rv-grid.com/guides/pivot/concepts/sorting-filtering/
Source: src/content/docs/guides/pivot/concepts/sorting-filtering.mdx
Description: Learn what sorting and filtering affect in Pivot output and how client-side and remote/server-side behavior differ.

Sorting and filtering in Pivot operate on analytical members and generated measures, not on the final rendered cells alone. The same ideas exist in both client-side and server-side Pivot, but the execution layer is different.

## Client-Side Sorting

Client-side Pivot uses dimension metadata when generating row and column members.

Relevant dimension options:

- `sortable`
- `order`

If a Pivot column dimension is marked sortable, generated members for that dimension are ordered using the configured comparer and sort direction.

## Client-Side Filtering

Generated value columns inherit configured filter metadata from their dimensions, so the resulting grid can expose filter-ready columns. This is still based on the generated Pivot output, not on the raw fact table semantics of a remote analytical engine.

## What Actually Gets Sorted

In client mode:

- row hierarchy ordering comes from the grouped source data
- column hierarchy ordering comes from the configured dimension metadata
- measure cells are results of aggregation, not independently sorted records

## Server-Side Sorting And Filtering

In server mode:

- filter expressions are part of `PivotLoadRequest.loadOptions.filter`
- sort directives are part of `PivotLoadRequest.loadOptions.sort`
- the analytical engine is responsible for applying them before returning the visible window

That distinction matters because server-side Pivot should sort and filter the cube window, not just the already-rendered grid cells.

## Sort By Summary

The remote request contract also supports sort-by-summary semantics through `bySummary` on sort descriptors. Use that when your backend can rank groups by a measure rather than only by a dimension label.

## Best Practices

- Keep client-side sorting expectations simple: it orders generated members, not facts.
- Use remote/server-side filtering for large datasets or security-sensitive selectors.
- Do not rely on client-generated columns as the trust boundary for secure filtering. The field registry belongs on the server side.

## Next

Continue with [Plugin Lifecycle](/guides/pivot/plugin-lifecycle/) to see how Pivot owns and restores grid state.

---

# Totals

URL: https://pro.rv-grid.com/guides/pivot/concepts/totals/
Source: src/content/docs/guides/pivot/concepts/totals.mdx
Description: Learn how Pivot grand totals and subtotals work across rows and generated columns.

Totals help users move from detailed branch-level summaries to whole-table summaries. RevoGrid Pivot supports grand totals and subtotals through `pivot.totals`.

## The Totals Config

```ts
totals: {
  grandTotal: true,
  subtotals: true,
  grandTotalLabel: 'All Sales',
  subtotalLabel: 'Subtotal',
}
```

## What Each Option Does

- `grandTotal`: Adds a grand-total row. When column dimensions exist, it also adds grand-total value columns.
- `subtotals`: Adds subtotal rows for intermediate row branches and subtotal value columns for intermediate column branches.
- `grandTotalLabel`: Overrides the default `"Grand Total"` label.
- `subtotalLabel`: Overrides the default `"Subtotal"` label.
- `suppressSingleChildSubtotals`: Hides subtotal rows for single-source branches where the subtotal duplicates the only leaf.
- `suppressGrandTotalWhenSingleLeaf`: Hides the grand-total row when the whole result is one source-backed leaf.

## Smart Suppression

Use suppression when totals are enabled for broad reports, but small filtered results should avoid duplicate summary rows:

```ts
totals: {
  subtotals: true,
  grandTotal: true,
  suppressSingleChildSubtotals: true,
  suppressGrandTotalWhenSingleLeaf: true,
}
```

Suppression is conservative. Multiple source rows, multiple meaningful leaves, or disabled `subtotals` / `grandTotal` keep the existing total behavior.

## Row Totals

When row fields exist:

- subtotal rows are inserted after the descendants of each branch
- the grand-total row is rendered separately and pinned at the bottom

This keeps the detailed body rows readable while still making the full-table total visible.

## Column Totals

When column fields exist:

- intermediate column paths can expose subtotal value columns
- the full column hierarchy can expose grand-total value columns

Pivot does not create a separate total table. Totals become part of the generated analytical structure.

## Column Totals With Drill-Down

Column totals and column collapse are designed to work together. A collapsed
group shows one aggregate carrier. Expanding that group keeps the parent
aggregate visible as a subtotal column and reveals only the next configured
level.

<figure>
  <img
    src="/images/pivot/column-totals-collapsed.jpg"
    alt="Financial Pivot with the Year level collapsed into one aggregate column for each year, followed by grand-total measure columns."
  />
  <figcaption>
    Collapsed years use one aggregate carrier per year. Grand-total columns
    remain independent from the branch collapse state.
  </figcaption>
</figure>

<figure>
  <img
    src="/images/pivot/column-totals-expanded.jpg"
    alt="Financial Pivot with 2023 expanded to a Year Total subtotal followed by individually collapsed month columns."
  />
  <figcaption>
    Expanding 2023 reveals its configured Year Total first, followed by the
    next-level month groups. The subtotal spans the otherwise unused lower
    header depth.
  </figcaption>
</figure>

<figure>
  <img
    src="/images/pivot/column-totals-progressive.jpg"
    alt="Financial Pivot with 2023 expanded and January expanded into Sales, Profit, and Units Sold while later months remain collapsed."
  />
  <figcaption>
    Drill-down is progressive: expanding January reveals only January's
    measures. Sibling months stay collapsed and Year Total remains one Sales
    subtotal column.
  </figcaption>
</figure>

### Behavior Matrix

| Configuration | Collapsed group | Expanded group |
| --- | --- | --- |
| `totals.subtotals: false` | Uses the regular collapsed aggregate bucket. | Shows descendants without a parent subtotal column. |
| `totals.subtotals: true` and the level subtotal is enabled | Uses the level subtotal as the aggregate carrier. | Shows the same subtotal plus the next visible descendant level. |
| `columnLevels[level].subtotal: false` | Uses the regular collapsed aggregate bucket for that level. | Omits the subtotal for that level, even when other levels show subtotals. |
| `columnLevels[level].collapsible: false` | The level cannot enter a collapsed state. | The level stays expanded; its subtotal can still be shown. |
| `subtotalPosition: 'before'` | Position is not visible while the branch is compact. | Places the parent subtotal before descendant columns. This is the default. |
| `subtotalPosition: 'after'` | Position is not visible while the branch is compact. | Places the parent subtotal after descendant columns. |
| `subtotalValues: ['sales']` | The compact carrier exposes only Sales for that subtotal. | The subtotal contains only Sales, while descendant groups can still expose every configured measure. |
| `totals.grandTotal: true` | Grand-total columns and the pinned grand-total row remain visible. | Grand totals remain independent from individual branch expansion. |

### Recommended Per-Level Configuration

This configuration matches the screenshots:

```ts
const pivot: PivotConfig = {
  rows: ['country', 'segment'],
  columns: ['year', 'month'],
  values: [
    { prop: 'sales', aggregator: 'sum' },
    { prop: 'profit', aggregator: 'sum' },
    { prop: 'unitsSold', aggregator: 'sum' },
  ],
  columnCollapse: {
    enabled: true,
    collapsed: true,
  },
  columnLevels: {
    0: {
      collapsible: true,
      collapsed: true,
      subtotal: true,
      subtotalLabel: 'Year Total',
      subtotalPosition: 'before',
      subtotalValues: ['sales'],
      filterable: true,
      sortable: true,
    },
    1: {
      collapsible: true,
      collapsed: true,
      subtotal: false,
      filterable: false,
      sortable: false,
    },
  },
  totals: {
    subtotals: true,
    grandTotal: true,
  },
};
```

`columnLevels` uses the zero-based order of `columns`: level `0` configures
`year`, level `1` configures `month`, and so on.

### Resolution And Precedence

The following rules make mixed configurations predictable:

1. `totals.subtotals` is the global subtotal gate. When it is `false`, no
   `columnLevels[level].subtotal` setting can enable a subtotal.
2. With global subtotals enabled, an explicit
   `columnLevels[level].subtotal` overrides
   `totals.disabledSubtotals.columns` for that level.
3. An explicit `columnLevels[level].collapsible` overrides the global
   `columnCollapse` setting for that level. When omitted, the level inherits
   `columnCollapse.enabled`.
4. `columnLevels[level].collapsed` controls the initial state for that level
   and falls back to `columnCollapse.collapsed`.
5. Persisted `collapsedColumns` state wins over both initial-state defaults for
   the matching generated group.
6. `subtotalLabel`, `subtotalPosition`, `subtotalValues`, `filterable`, and
   `sortable` apply only to their configured level.
7. Grand-total columns do not belong to a generated hierarchy level, so
   `columnLevels` does not change them.

### Filtering And Sorting Through Collapse

The subtotal or collapsed aggregate represents one analytical group across
both visual states. A filter or sort applied to that aggregate therefore stays
active when the group expands or collapses:

- expanding does not broaden the filter to every newly visible child column
- collapsing does not discard the active filter or sort direction
- the active control moves between the compact carrier, parent group proxy,
  and visible subtotal without changing its analytical property
- `filterable: false` removes aggregate filter controls for that level
- `sortable: false` removes aggregate sorting for that level

The expand/collapse control appears before the group title. Expanding a group
reveals one hierarchy level only; it does not expand its descendants or sibling
branches.

### Header Spanning

A direct subtotal such as `Year Total` fills the unused descendant header rows
vertically. It remains one value column; it does not span horizontally across
the descendant columns. This keeps the subtotal aligned with deeper headers
without covering the parent expand/collapse control.

## Example

For:

```ts
rows: ['region', 'rep'],
columns: ['year', 'quarter'],
values: [{ prop: 'sales', aggregator: 'sum' }],
totals: { grandTotal: true, subtotals: true },
```

You get:

- leaf rows for each `region -> rep`
- subtotal rows for each `region`
- grand total at the bottom
- leaf value columns for each `year -> quarter`
- subtotal value columns for each `year`
- grand-total value columns across all years and quarters

## Important Notes

- Subtotals only appear when a hierarchy has more than one level to summarize.
- Grand totals use the configured label only for display. The internal total keys stay synthetic.
- A column subtotal remains the same analytical aggregate through collapse and
  expansion; only its header presentation changes.
- Per-level subtotal, collapse, filter, and sort settings are independent.
- In remote/server mode, totals stay part of the analytical contract and should be computed by the engine, not recomputed from visible UI cells.

## Common Mistakes

- Expecting `subtotals: true` to add subtotal rows when there is only one row field.
- Expecting grand totals to stay inside the body rows. In the current implementation, grand total rows are pinned bottom rows.
- Assuming `subtotal: true` can bypass `totals.subtotals: false`.
- Assuming expanding a year should expand every month below it.
- Confusing a regular collapsed bucket with a subtotal carrier. They look
  similarly compact, but only a level with an enabled subtotal exposes that
  same subtotal as a visible column after expansion.

## Next

Continue with [Values On Rows](/guides/pivot/values-on-rows/) or [Drill-Down](/guides/pivot/drilldown/).

---

# Values On Rows

URL: https://pro.rv-grid.com/guides/pivot/concepts/values-on-rows/
Source: src/content/docs/guides/pivot/concepts/values-on-rows.mdx
Description: Move Pivot measures into the row hierarchy and understand when that layout works best.

By default, Pivot renders measures as generated value columns. `valuesOnRows` flips that layout so measures become synthetic row members instead.

## Default Layout vs Values On Rows

Default layout:

```txt
rows: Region
columns: Quarter
values: Sales, Margin
```

This usually produces:

- one row branch per region
- one generated value column per quarter and measure

With `valuesOnRows: true`, the same measures become row members:

- Region
- Sales
- Margin

That is useful when:

- you have many measures and few row dimensions
- you want a more compact column area
- users compare measures vertically rather than horizontally

## Configuration

```ts
const pivot: PivotConfig = {
  rows: ['region'],
  columns: ['quarter'],
  values: [
    { prop: 'sales', aggregator: 'sum' },
    { prop: 'margin', aggregator: 'avg' },
  ],
  valuesOnRows: true,
};
```

## Explicit Values Position

Use `rowTree` with the `$values` pseudo-field when measures need to appear at a specific hierarchy level:

```ts
rowTree: ['carModel', 'cellId', '$values']
rowTree: ['carModel', '$values', 'cellId']
rowTree: ['$values', 'carModel', 'cellId']
```

`rowTree` is the explicit advanced API. If it is provided, it controls value placement even when `valuesOnRows` is also set.

## What Changes Internally

- Pivot adds a synthetic row field called `Values`.
- Generated value columns become value labels in the row hierarchy.
- Grouping and row drill-down now treat the value label as part of the row structure.

This is why row drill-down helpers account for `valuesOnRows` when deriving row props.

## Tradeoffs

Benefits:

- fewer generated columns
- easier comparison of multiple measures
- clearer layouts on narrow screens

Costs:

- more synthetic rows
- row drill-down can feel deeper because the value label becomes part of the hierarchy
- users expecting a spreadsheet-style “measures across columns” layout may find it less familiar

## When Not To Use It

Avoid `valuesOnRows` when:

- you only have one measure
- your users think in terms of wide analytical columns
- you already have a deep row hierarchy and want to keep rows compact

## Next

Continue with [Drill-Down](/guides/pivot/drilldown/) to see how row and column expansion behave in both layouts.

---

# Configurator

URL: https://pro.rv-grid.com/guides/pivot/configurator/
Source: src/content/docs/guides/pivot/configurator/index.mdx

---

# Configurator

URL: https://pro.rv-grid.com/guides/pivot/configurator/configurator/
Source: src/content/docs/guides/pivot/configurator/configurator.mdx
Description: Learn what the Pivot configurator does and how users interact with rows, columns, and values.

The configurator is the drag-and-drop field panel for Pivot. It gives users a visual way to rearrange dimensions between rows, columns, and values without writing a new `PivotConfig` by hand.

## What It Does

The configurator renders:

- a dimension list
- a rows drop zone
- a columns drop zone
- a values drop zone

When users move a field:

- the configurator emits updated rows, columns, or values
- `PivotPlugin` re-emits `pivot-config-update`
- the Pivot result is recomputed and the grid updates

## Enable It

```ts
const pivot: PivotConfig = {
  dimensions: [...],
  rows: ['region'],
  columns: ['quarter'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  hasConfigurator: true,
};
```

## Visibility Controls

Use these options to hide zones:

- `showRows`
- `showColumns`
- `showValues`

These only affect the configurator UI. They do not remove support for the corresponding Pivot feature.

The Reset layout action is hidden by default. Set `fieldPanel.showResetLayout: true` to expose it in either the full configurator or compact field panel.

## Mounting

By default, `PivotPlugin` creates the configurator inside the grid wrapper. If you set `mountTo`, it mounts into the supplied element instead.

## Aggregator Selection

The configurator’s value zone reads available aggregators from the matching dimension. That means aggregator choices stay consistent with the field definition, rather than being hard-coded in the panel.

## i18n

Configurator labels come from `i18n`. If omitted, Pivot uses the built-in English defaults from `PIVOT_CONFIG_EN`.

## Common Mistakes

- Enabling `hasConfigurator` without providing useful `dimensions`.
- Expecting hidden zones to disable Pivot features globally.
- Treating the configurator as the state owner. It is a UI for editing Pivot state, not the persistence layer.

## Next

Continue with [Field Panel](/guides/pivot/field-panel/) for the compact in-grid layout, [Configurator API](/guides/pivot/configurator-api/) for the standalone embedding surface, or [Server-Side Pivot](/guides/pivot/server-side/) for remote analytical usage.

---

# Configurator API

URL: https://pro.rv-grid.com/guides/pivot/configurator/configurator-api/
Source: src/content/docs/guides/pivot/configurator/configurator-api.mdx
Description: Use the standalone Pivot configurator and understand its callbacks, mounting model, and integration points.

The built-in configurator can be used through `PivotPlugin`, but it is also available as a standalone API. Use this when you want the field panel in a custom shell, sidebar, or framework-managed layout.

## Main Entry Point

```ts
import { definePivotConfigurator } from '@revolist/pivot';
```

`definePivotConfigurator(el, config, actions)` mounts the configurator into any element.

## Example

```ts
definePivotConfigurator(container, pivotConfig, {
  onUpdateConfiguration: (patch) => {
    pivotConfig = { ...pivotConfig, ...patch };
  },
  onUpdateColumns: (columns) => {
    pivotConfig = { ...pivotConfig, columns };
  },
  onUpdateRows: (rows) => {
    pivotConfig = { ...pivotConfig, rows };
  },
  onUpdateValues: (values) => {
    pivotConfig = { ...pivotConfig, values };
  },
});
```

## `PivotConfigurationActions`

The current callback surface is:

- `onUpdateConfiguration`
- `onUpdateColumns`
- `onUpdateRows`
- `onUpdateValues`
- `onUpdateFilters`

The zone callbacks receive the new ordered configuration for one edited zone.
`onUpdateConfiguration` receives a partial `PivotConfig` containing every zone
changed by one action. Prefer it when an integration must keep cross-zone drag,
group drag, or Rows/Columns transpose updates atomic and avoid multiple Pivot
regenerations. The individual callbacks remain available for compatibility.

## What The Configurator Does Not Own

The configurator does not:

- execute Pivot by itself
- persist state for you
- own the grid instance

It is purely a configuration UI. You decide where the updated state goes next.

## Embedded Via `PivotPlugin`

When `hasConfigurator` is enabled on `PivotConfig`, `PivotPlugin` internally uses the same standalone configurator surface and wires it to `pivot-config-update`.

That means:

- standalone usage and plugin-managed usage stay conceptually aligned
- examples built around the standalone API still apply to plugin-managed usage

## Visibility And i18n

The configurator reads:

- `showRows`
- `showColumns`
- `showValues`
- `i18n`

These options let you tailor the panel for a simpler or more controlled layout.

## Best Practices

- Keep the configurator state source-of-truth in one place, usually the same state object you pass to the grid.
- Provide stable `dimensions` metadata so labels and aggregators stay consistent.
- Persist the resulting `PivotConfig` rather than trying to persist the configurator UI separately.

## Related Guides

- [Configurator](/guides/pivot/configurator/)
- [Field Panel](/guides/pivot/field-panel/)
- [Plugin Lifecycle](/guides/pivot/plugin-lifecycle/)
- [Configuration Reference](/guides/pivot/configuration-reference/)

---

# Pivot Features

URL: https://pro.rv-grid.com/guides/pivot/features/
Source: src/content/docs/guides/pivot/features.mdx
Description: Current Pivot feature status sourced from the standalone Pivot package.

---

# Introduction

URL: https://pro.rv-grid.com/guides/pivot/introduction/
Source: src/content/docs/guides/pivot/introduction/index.mdx

---

# Data Modeling for Pivot

URL: https://pro.rv-grid.com/guides/pivot/introduction/data-modeling/
Source: src/content/docs/guides/pivot/introduction/data-modeling.mdx
Description: Learn how to structure your data for optimal performance and analytical flexibility in RevoGrid Pivot.

The quality of your Pivot analysis depends entirely on how your data is structured. To get the most out of RevoGrid Pivot, you should understand the difference between **Facts** and **Dimensions**.

## Facts vs. Dimensions

In the world of data modeling (specifically the **Star Schema**), data is divided into two categories:

### 1. Fact Tables (The "Events")
A Fact Table contains the quantitative data you want to measure. Each row represents a specific occurrence or transaction.
-   **Characteristics**: Usually has many rows, contains numeric "measures," and "foreign keys" to dimension tables.
-   **Example Fields**: `Price`, `Quantity`, `Duration`, `DiscountAmount`.

### 2. Dimension Tables (The "Context")
A Dimension Table contains descriptive attributes that provide context to your facts.
-   **Characteristics**: Usually has fewer rows, contains categorical text or dates.
-   **Example Fields**: `Product Name`, `Color`, `Region`, `Customer Segment`, `Date (Year/Month/Day)`.

## The "Perfect" Pivot Source

For RevoGrid's client-side Pivot, the "perfect" input is a **Denormalized Flat Table**. This means you have "joined" your facts and dimensions into a single list of objects before passing them to the grid.

### ❌ Bad Data Shape (Normalized)
The grid has to look up values in multiple places. Hard to pivot.
```json
// Transactions
[{ "id": 1, "product_id": 101, "amount": 50 }]
// Products
[{ "id": 101, "name": "Apple" }]
```

### ✅ Good Data Shape (Denormalized)
Everything the pivot needs is in one object.
```json
[
  {
    "id": 1,
    "product": "Apple",
    "category": "Fruit",
    "region": "North",
    "amount": 50,
    "date": "2024-05-01"
  }
]
```

## Modeling Best Practices

### 1. Numeric vs. Categorical
-   **Numbers** should be raw, unformatted values (e.g., `1200.50`, not `"$1,200.50"`). This allows aggregators like `sum` and `avg` to work correctly.
-   **Categories** should be stable strings. Avoid using ID numbers (like `1`, `2`, `3`) as labels; use human-readable names (like `"Active"`, `"Pending"`, `"Closed"`) so the generated headers make sense.

### 2. Date Hierarchies
Dates are the most common pivot dimension. Instead of just a raw ISO string, it is often helpful to provide pre-calculated date parts if you are doing client-side pivoting:
```json
{
  "orderDate": "2024-05-21",
  "year": 2024,
  "quarter": "Q2",
  "month": "May"
}
```
In your `PivotConfig`, you can then set `rows: ['year', 'quarter', 'month']` to create an instant time-drilldown experience.

### 3. Stability of Fields
The `prop` in your [Dimensions](/guides/pivot/dimensions/) should be stable. If you change a field name in your data, you must update the `prop` in your configuration, or the Pivot will fail to find the data.

## Large Scale Modeling (Server-Side)

If your "Fact Table" has millions of rows, you shouldn't denormalize it into a single JSON array for the browser. Instead, you should keep it in an **OLAP-optimized database** (like ClickHouse, BigQuery, or Snowflake) and use the [Server-Side Pivot](/guides/pivot/server-side/) mode.

In this mode, RevoGrid sends the "Analytical Request" (the rows, columns, and filters) to your backend, which performs the SQL `JOIN` and `GROUP BY` efficiently and returns only the visible summary.

## Next Steps

Now that your data is modeled correctly, learn how to define your [Dimensions](/guides/pivot/dimensions/) to tell RevoGrid how to use these fields.

---

# What is an OLAP Cube?

URL: https://pro.rv-grid.com/guides/pivot/introduction/olap-cube-concepts/
Source: src/content/docs/guides/pivot/introduction/olap-cube-concepts.mdx
Description: Understand the multidimensional "Cube" metaphor and how Online Analytical Processing (OLAP) powers advanced data discovery.

When working with RevoGrid Pivot, you will often hear the term **OLAP** (Online Analytical Processing) or **OLAP Cube**. While the name sounds complex, the concept is fundamental to modern business intelligence.

## The "Cube" Metaphor

In a traditional spreadsheet, data is 2-dimensional (Rows and Columns). In an **OLAP Cube**, data is **Multidimensional**.

Think of a "Cube" where each side represents a different category (a **Dimension**):
1.  **Product** (what we sold)
2.  **Time** (when we sold it)
3.  **Geography** (where we sold it)

Inside the cube, at the intersection of these three dimensions, lies the **Measure** (e.g., Sales Amount).

By "rotating" this cube, you can view the data from any angle. In RevoGrid Pivot, this "rotation" happens when you move fields between the Rows and Columns axes.

## Core OLAP Operations

OLAP cubes are designed to support four primary analytical operations, all of which are supported by RevoGrid:

### 1. Slicing
Slicing is like taking a single "slice" of the cube.
-   **Concept**: Picking one value for a dimension.
-   **Example**: "Show me sales only for the **Year 2024**."
-   **In RevoGrid**: This is achieved through [Filtering](/guides/pivot/sorting-filtering/).

### 2. Dicing
Dicing is like cutting a smaller "sub-cube" out of the big one.
-   **Concept**: Picking specific values across multiple dimensions.
-   **Example**: "Show me sales for **Electronics** in the **North Region** during **Q1**."
-   **In RevoGrid**: This is achieved by combining filters and row/column grouping.

### 3. Drill-Down / Drill-Up
Moving through the levels of a hierarchy.
-   **Concept**: Going from summarized data to detailed data (Drill-Down) or back (Drill-Up).
-   **Example**: Looking at sales by **Year**, then clicking to see **Quarters**, then **Months**.
-   **In RevoGrid**: Enabled via the `collapsed` property in [Drill-Down](/guides/pivot/drilldown/).

### 4. Pivoting (Rotating)
Changing the orientation of the axes.
-   **Concept**: Swapping Rows and Columns to see the data differently.
-   **Example**: Moving "Region" from the Row axis to the Column axis to compare regions side-by-side.
-   **In RevoGrid**: Performed via the [Configurator](/guides/pivot/configurator/) or by updating the `rows` and `columns` arrays in your code.

## Why "Cube" vs. "Flat Table"?

| Feature | Flat Table (SQL) | OLAP Cube |
| :--- | :--- | :--- |
| **Speed** | Slow for large aggregations (calculates on the fly) | Fast (aggregations are often pre-calculated) |
| **Complexity** | Requires complex `JOIN` and `GROUP BY` logic | Logical, business-friendly dimensions |
| **Scale** | Hard to scale to billions of rows for real-time UI | Designed for massive analytical scale |

## How RevoGrid Fits In

RevoGrid acts as the **Viewer** for your OLAP data.
-   **Client-Side**: RevoGrid builds a "virtual cube" in memory from your flat JSON data.
-   **Server-Side**: RevoGrid communicates with a real OLAP engine (like Snowflake, ClickHouse, or Cube.js) using the [Remote API](/guides/pivot/remote-api-reference/).

## Next Steps

Now that you understand the "Cube" metaphor, learn how to prepare your data for these operations in [Data Modeling for Pivot](/guides/pivot/data-modeling/).

---

# What Is Pivot?

URL: https://pro.rv-grid.com/guides/pivot/introduction/what-is-pivot/
Source: src/content/docs/guides/pivot/introduction/what-is-pivot.mdx
Description: A conceptual introduction to Pivot tables, the mental model, and how they transform flat data into analytical insights.

A **Pivot Table** is a data summarization tool that automatically sorts, counts, totals, or averages data stored in one table and displays the results in a second, organized table.

In RevoGrid, the Pivot plugin takes a "flat" list of records and transforms it into a multidimensional view where you can see relationships between different data points at a glance.

## The Transformation: From Facts to Insights

Imagine you have a list of sales transactions. Each row represents a single event:

<table>
  <thead>
    <tr>
      <th>Date</th>
      <th>Region</th>
      <th>Category</th>
      <th>Sales</th>
    </tr>
  </thead>
  <tbody>
    <tr><td>2024-01-01</td><td>North</td><td>Electronics</td><td>$500</td></tr>
    <tr><td>2024-01-02</td><td>South</td><td>Electronics</td><td>$300</td></tr>
    <tr><td>2024-01-03</td><td>North</td><td>Furniture</td><td>$1,200</td></tr>
    <tr><td>2024-01-04</td><td>North</td><td>Electronics</td><td>$450</td></tr>
  </tbody>
</table>

This "flat" view is great for data entry, but hard to read for analysis. A **Pivot** transforms it by choosing axes:

1.  **Row Axis**: Grouping data vertically (e.g., by **Region**).
2.  **Column Axis**: Grouping data horizontally (e.g., by **Category**).
3.  **Values**: The numbers you want to calculate (e.g., **Sum of Sales**).

### The Resulting Pivot View:

<table>
  <thead>
    <tr>
      <th>Region</th>
      <th>Electronics</th>
      <th>Furniture</th>
      <th>Grand Total</th>
    </tr>
  </thead>
  <tbody>
    <tr><td><strong>North</strong></td><td>$950</td><td>$1,200</td><td><strong>$2,150</strong></td></tr>
    <tr><td><strong>South</strong></td><td>$300</td><td>$0</td><td><strong>$300</strong></td></tr>
    <tr><td><strong>Grand Total</strong></td><td><strong>$1,250</strong></td><td><strong>$1,200</strong></td><td><strong>$2,450</strong></td></tr>
  </tbody>
</table>

## Core Axes of a Pivot

To work with Pivot, you need to think in terms of three primary axes:

### 1. Rows (The Hierarchy)
Rows define the vertical structure. If you add multiple fields to rows (e.g., `['Region', 'Manager']`), Pivot creates a nested hierarchy. Users can "drill down" from Region to see the individual Managers within that region.

### 2. Columns (The Breakdown)
Columns define the horizontal structure. Unlike normal grid columns, Pivot columns are often **generated** based on the data. If you put `Quarter` in columns, Pivot will automatically create a column for every unique quarter found in your dataset.

### 3. Values (The Measures)
Values are the "meat" of the table. They are the numeric fields that get crunched using **Aggregators** (like `sum`, `avg`, `min`, `max`, or `count`). Every cell in a Pivot table is the result of an aggregation of all raw records that match that specific row and column intersection.

## Why Use RevoGrid Pivot?

-   **Massive Data**: RevoGrid's virtualization allows you to pivot millions of rows without crashing the browser.
-   **Dynamic Discovery**: Users can drag and drop fields to explore data from different angles.
-   **Advanced analysis**: Subtotals, Grand Totals, and Drill-down are built in and optimized.
-   **Server-Side Scaling**: For datasets too large for the browser, RevoGrid can connect to an [OLAP Backend](/guides/pivot/connect-olap-backend/) to perform the heavy lifting on the server while maintaining a smooth UI.

## Next Steps

To understand how these concepts map to actual code, read about [Dimensions](/guides/pivot/dimensions/) or explore the [Mental Model](/guides/pivot/#mental-model) in the Overview.

---

# Server-Side

URL: https://pro.rv-grid.com/guides/pivot/server-side/
Source: src/content/docs/guides/pivot/server-side/index.mdx

---

# Caching And Cache Keys

URL: https://pro.rv-grid.com/guides/pivot/server-side/caching/
Source: src/content/docs/guides/pivot/server-side/caching.mdx
Description: Understand how RevoGrid Pivot generates deterministic cache keys for safe and efficient remote analytical execution.

In server-side Pivot, caching is critical for performance and cost management. Analytical queries can be expensive and slow; deduplicating identical requests ensures that the backend only performs the work once.

RevoGrid Pivot uses **deterministic cache keys** to identify identical analytical windows.

## What Is A Cache Key?

A cache key is a unique string that represents the exact state of an analytical request. If any part of the request changes (filters, grouping, viewport, or data version), a new key is generated.

This allows both the client-side `HttpPivotRemoteStore` and your backend analytical engine to:

1. **Deduplicate**: Prevent multiple identical requests from hitting the database simultaneously.
2. **Memoize**: Return previously computed results for the same analytical window.
3. **Invalidate Safely**: Ensure that if the underlying data or field definitions change, old cached results are never shown.

## Key Components

A stable Pivot cache key is composed of several semantic layers:

| Component | Description | Why It Matters |
| :--- | :--- | :--- |
| `tenantId` | Identifies the client or organization scope. | Prevents data leakage between different users/tenants. |
| `viewId` | Identifies the specific analytical view or dashboard. | Keeps caches separate for different reports using the same fields. |
| `fieldsVersion` | A checksum or version of the field registry. | If you change a field's calculation or data type, old summaries must be invalidated. |
| `datasetWatermark` | A timestamp or batch ID representing data freshness. | Automatically invalidates the cache when new data is loaded into the warehouse. |
| `request` | A stable stringification of filters, rows, columns, and windows. | Ensures that changing a single filter or scrolling the viewport yields a specific key. |

## How Keys Are Generated

RevoGrid provides a standard `createPivotCacheKey` utility that builds these keys. It uses a **stable stringification** algorithm, meaning that the order of keys in a JSON object does not change the resulting string.

```ts
// Internal logic simplified
const cacheKey = `pivot:${tenantId}:${viewId}:${fieldsVersion}:${datasetWatermark}:${stableStringify(request)}`;
```

### Stable Stringification Example

Even if the UI sends filters in a different order, the cache key remains the same:

```ts
// Request A
{ filter: { region: 'US', category: 'Tech' } }

// Request B
{ filter: { category: 'Tech', region: 'US' } }

// Both result in the same stable key:
// "...:{"category":"Tech","region":"US"}"
```

## Observing Cache Status

When using `HttpPivotRemoteStore` or the recommended backend response format, the grid receives cache metadata in the `meta` object:

```ts
{
  "data": [...],
  "meta": {
    "cacheKey": "pivot:tenant-1:sales:v1:20240424:...",
    "cacheStatus": "hit", // or 'miss', 'warm', 'bypass'
    "elapsedMs": 12
  }
}
```

This is useful for UI diagnostics and understanding whether your analytical engine is performing efficiently.

## Best Practices

- **Keep `viewId` Stable**: Do not use random IDs for views if you want users to benefit from shared caching across sessions.
- **Update `datasetWatermark`**: Your backend should provide a watermark (like a `max(updated_at)` or a batch ID) to the client so the cache key updates automatically when data changes.
- **Normalize Requests**: If you are implementing a custom `PivotRemoteStore`, ensure you normalize filters and descriptors before generating keys to maximize cache hits.

## Next

- [Server-Side Pivot](/guides/pivot/server-side/)
- [Remote API Reference](/guides/pivot/remote-api-reference/)
- [OLAP Best Practices](/guides/pivot/olap-best-practices/)

---

# Connect An OLAP Backend

URL: https://pro.rv-grid.com/guides/pivot/server-side/connect-olap-backend/
Source: src/content/docs/guides/pivot/server-side/connect-olap-backend.mdx
Description: Wire RevoGrid Pivot to an OLAP-capable backend through HttpPivotRemoteStore and an application API.

This guide shows the practical wiring pattern for connecting RevoGrid Pivot to an OLAP-capable backend. The important rule is simple: the browser talks to your application API, and your application API talks to the cube, warehouse, or semantic layer.

For the conceptual background, read [Server-Side Pivot](/guides/pivot/server-side/) first. For the transport contract, see [Remote API Reference](/guides/pivot/remote-api-reference/).

## Live Simulated Server Example

The example below uses the real `HttpPivotRemoteStore` API with a simulated in-memory `/api/pivot/*` server. The Request Log panel on the right shows the actual client and server events as they happen — `load:started`, `load:received`, `load:responded`, and `load:succeeded`.

## Architecture

The recommended production boundary looks like this:

```txt
RevoGrid + PivotPlugin
  -> HttpPivotRemoteStore
  -> your /api/pivot/* endpoints
  -> field registry + validation + planner/adapter
  -> OLAP engine / warehouse / cube API
```

Do not connect the browser directly to the OLAP database. Your backend layer must own:

- authentication
- tenant isolation
- selector whitelisting
- request normalization
- query translation
- caching and observability

## Minimum Pieces You Need

1. A client `PivotConfig` with `engine.mode = 'server'`
2. An `HttpPivotRemoteStore`
3. Backend `POST /api/pivot/load`
4. Backend `POST /api/pivot/drilldown`
5. A field registry for safe public field ids
6. A planner or adapter that translates Pivot requests into your backend’s OLAP query shape

## Client Setup

The client stays small. It only needs to describe the Pivot layout and point the plugin at your application API.

```ts
import {
  HttpPivotRemoteStore,
  PivotPlugin,
  commonAggregators,
  type PivotConfig,
} from '@revolist/pivot';
import { PaginationPlugin } from '@revolist/revogrid-pro';

const remoteStore = new HttpPivotRemoteStore({
  baseUrl: '/api',
  tenantId: 'tenant-a',
  datasetWatermark: 'sales-cube-v42',
  authProvider: async () => ({
    Authorization: `Bearer ${await getAccessToken()}`,
  }),
});

const pivot: PivotConfig = {
  dimensions: [
    { prop: 'Region', name: 'Region' },
    { prop: 'Category', name: 'Category' },
    { prop: 'Date', name: 'Date' },
    {
      prop: 'SalesAmount',
      name: 'Sales',
      aggregators: commonAggregators,
    },
  ],
  rows: ['Region', 'Category'],
  columns: ['Date'],
  values: [{ prop: 'SalesAmount', aggregator: 'sum' }],
  totals: { grandTotal: true, subtotals: true },
  engine: {
    mode: 'server',
    remoteStore,
    viewId: 'sales-by-region',
    fieldsVersion: 'sha256:fields-v1',
    rowAxis: { offset: 0 },       // limit driven by pagination.itemsPerPage
    columnAxis: { offset: 0, limit: 24 },
  },
};

// Add PaginationPlugin to enable server-side row paging.
// PivotPlugin will read itemsPerPage as the rowAxis limit and keep
// pagination.total in sync with response.rowAxis.totalCount.
grid.plugins = [PivotPlugin, PaginationPlugin];
grid.pivot = pivot;
grid.additionalData = {
  pagination: {
    itemsPerPage: 50,
    initialPage: 0,
    total: 0,
  },
};
```

## What The Client Sends

At runtime, `PivotPlugin` converts the visible Pivot state into a `PivotLoadRequest` and sends it through `HttpPivotRemoteStore`.

That request includes:

- `rows`, `columns`, and `values`
- filters and sort directives
- `rowAxis` and `columnAxis` windows
- expansion state represented as analytical paths

The client does not build SQL and it does not know how your cube works internally.

## Backend Load Endpoint

This example uses a lightweight Node/Express style handler for readability. The contract itself is framework-agnostic.

```ts
import type { Request, Response } from 'express';
import {
  createFieldRegistry,
  normalizePivotLoadRequest,
  type PivotLoadRequest,
  type PivotLoadResponse,
} from '@revolist/pivot';

const registry = createFieldRegistry([
  {
    id: 'Region',
    label: 'Region',
    dataType: 'string',
    expression: { kind: 'column', value: 'sales.region' },
    allowedOperations: ['=', '<>', 'in'],
  },
  {
    id: 'Category',
    label: 'Category',
    dataType: 'string',
    expression: { kind: 'column', value: 'sales.category' },
    allowedOperations: ['=', '<>', 'in'],
  },
  {
    id: 'Date',
    label: 'Date',
    dataType: 'date',
    expression: { kind: 'column', value: 'sales.order_date' },
    allowedOperations: ['=', '>=', '<='],
    allowedGroupIntervals: ['year', 'quarter', 'month', 'day'],
  },
  {
    id: 'SalesAmount',
    label: 'Sales Amount',
    dataType: 'number',
    expression: { kind: 'column', value: 'sales.amount' },
    allowedOperations: ['=', '>', '>=', '<', '<='],
    allowedSummaries: ['sum', 'avg', 'min', 'max', 'count'],
    drilldownVisible: true,
  },
]);

export async function postPivotLoad(req: Request, res: Response) {
  const tenantId = await requireTenant(req);
  const request = req.body as PivotLoadRequest;

  const normalized = normalizePivotLoadRequest(request, registry);
  const cubeResult = await runCubeLoad({
    tenantId,
    viewId: normalized.viewId,
    fieldsVersion: normalized.fieldsVersion,
    request: normalized,
  });

  const response: PivotLoadResponse = {
    requestId: request.requestId,
    version: 1,
    data: cubeResult.data,
    summary: cubeResult.summary,
    rowAxis: cubeResult.rowAxis,
    columnAxis: cubeResult.columnAxis,
    meta: cubeResult.meta,
  };

  res.json(response);
}
```

## Translating The Pivot Request Into An OLAP Query

Your adapter layer is where Pivot concepts become backend-native OLAP concepts.

Recommended mapping:

- Pivot `rows` -> cube row dimensions
- Pivot `columns` -> cube column dimensions
- Pivot `totalSummary` and `groupSummary` -> cube measures
- Pivot `filter` -> cube filter tree
- `expandedPaths` / `collapsedPaths` -> hierarchy frontier exceptions
- `uiState.columnGroupsCollapsedByDefault` -> column hierarchy default state
- `rowAxis` / `columnAxis` -> returned analytical windows

Example adapter:

```ts
type RunCubeLoadArgs = {
  tenantId: string;
  viewId: string;
  fieldsVersion: string;
  request: ReturnType<typeof normalizePivotLoadRequest>;
};

async function runCubeLoad(args: RunCubeLoadArgs) {
  const { request } = args;

  const cubeQuery = {
    dimensions: {
      rows: (request.loadOptions.rows ?? []).map((item) => ({
        id: item.selector,
        interval: item.groupInterval,
        desc: item.desc,
      })),
      columns: (request.loadOptions.columns ?? []).map((item) => ({
        id: item.selector,
        interval: item.groupInterval,
        desc: item.desc,
      })),
    },
    measures: (request.loadOptions.totalSummary ?? []).map((summary) => ({
      id: summary.selector,
      aggregate: summary.summaryType,
    })),
    filters: request.loadOptions.filter,
    sort: request.loadOptions.sort ?? [],
    window: request.viewport,
    uiState: request.uiState,
  };

  const result = await cubeClient.loadPivotWindow(cubeQuery);

  return {
    data: result.cells,
    summary: result.summaryRows,
    rowAxis: {
      totalCount: result.rowAxis.totalCount,
      returned: result.rowAxis.returned,
      offset: request.viewport.rowAxis.offset,
      limit: request.viewport.rowAxis.limit,
      expandedPaths: request.viewport.rowAxis.expandedPaths,
      paths: result.rowAxis.paths,
      nodes: result.rowAxis.nodes,
    },
    columnAxis: {
      totalCount: result.columnAxis.totalCount,
      returned: result.columnAxis.returned,
      offset: request.viewport.columnAxis.offset,
      limit: request.viewport.columnAxis.limit,
      expandedPaths: request.viewport.columnAxis.expandedPaths,
      collapsedPaths: request.viewport.columnAxis.collapsedPaths,
      paths: result.columnAxis.paths,
      nodes: result.columnAxis.nodes,
    },
    meta: {
      cacheKey: result.cacheKey,
      generatedAt: result.generatedAt,
      elapsedMs: result.elapsedMs,
      cacheStatus: result.cacheStatus,
      warnings: result.warnings ?? [],
    },
  };
}
```

## Drilldown Endpoint

Drilldown should return the underlying facts for a visible summary cell, not a second aggregated result.

```ts
import type { Request, Response } from 'express';
import {
  createFieldRegistry,
  normalizePivotDrilldownRequest,
  type PivotDrilldownRequest,
} from '@revolist/pivot';

export async function postPivotDrilldown(req: Request, res: Response) {
  await requireTenant(req);
  const request = req.body as PivotDrilldownRequest;
  const normalized = normalizePivotDrilldownRequest(request, registry);

  const facts = await cubeClient.drilldown({
    rowPath: normalized.cell.rowPath,
    columnPath: normalized.cell.columnPath,
    dataIndex: normalized.cell.dataIndex,
    fields: normalized.customColumns ?? ['Region', 'Category', 'Date', 'SalesAmount'],
    offset: normalized.offset,
    limit: normalized.limit,
  });

  res.json({
    requestId: request.requestId,
    data: facts.rows,
    totalCount: facts.totalCount,
    meta: {
      cacheStatus: facts.cacheStatus ?? 'bypass',
    },
  });
}
```

## Request Lifecycle

1. The grid shows a Pivot layout with row and column windows.
2. `PivotPlugin` builds a `PivotLoadRequest`.
3. `HttpPivotRemoteStore` sends the request to your application API.
4. Your backend authenticates, validates selectors, and normalizes the request.
5. Your planner or cube adapter translates the normalized request into backend-native OLAP calls.
6. The cube or warehouse returns only the visible analytical block.
7. Your backend maps that result into `PivotLoadResponse`.
8. RevoGrid materializes the returned window into visible columns and rows.

## What Changes For A True OLAP Cube

If your backend already exposes dimensions, measures, and drilldown concepts, the frontend setup stays the same. Only the backend adapter changes.

Typical differences:

- date grouping may map directly to cube hierarchy levels
- drilldown may map to cube “drill through” APIs
- row and column windows may map to axis slicing instead of SQL paging
- `avg` and derived measures may already be modeled by the cube

That is why the recommended contract stays generic HTTP. The transport is stable even when the backend engine changes.

## Do Not Do This

- Do not connect the browser directly to the OLAP database.
- Do not trust selectors from the client.
- Do not return the full cube by default.
- Do not compute totals from rendered UI values.

## Related Guides

- [Server-Side Pivot](/guides/pivot/server-side/)
- [Remote API Reference](/guides/pivot/remote-api-reference/)
- [OLAP Best Practices](/guides/pivot/olap-best-practices/)

---

# OLAP Best Practices

URL: https://pro.rv-grid.com/guides/pivot/server-side/olap-best-practices/
Source: src/content/docs/guides/pivot/server-side/olap-best-practices.mdx
Description: Design Pivot-friendly analytical models with stable dimensions, secure field registries, and viewport-aware execution.

RevoGrid Pivot is not itself an OLAP database, but the server-side foundation is designed to work well with OLAP-style engines, semantic layers, and warehouse-backed pivot services. This page explains the practices that keep that integration correct and maintainable.

## Start With Facts And Dimensions

The best Pivot source model is:

- a fact table with additive events or transactions
- dimensions that describe those facts

Examples:

- facts: orders, sales lines, support incidents, page views
- dimensions: region, product, customer segment, time

This model keeps grouping and drilldown semantics predictable.

## Treat The Field Registry As A Semantic Layer

Your client should use public field ids. Your backend should map them through a field registry.

Good registry properties:

- stable field ids
- business-friendly labels
- safe backend expressions
- explicit allowed operations
- explicit allowed summaries
- explicit allowed grouping intervals

This prevents raw selector leakage and becomes the trust boundary for every analytical request.

## Design Hierarchies Intentionally

Rows and columns should represent real analytical hierarchies, not arbitrary field lists.

Good examples:

- `['Region', 'Rep']`
- `['Year', 'Quarter', 'Month']`
- `['Category', 'Subcategory']`

Poor examples:

- mixing unrelated dimensions only because the UI allows it
- saving unstable intermediate fields that are likely to change name or meaning

## Prefer Additive Measures

`sum` and `count` are easiest to reason about across subtotals and grand totals.

Be careful with:

- `avg`
- ratios
- percentages
- any metric derived from already-aggregated cells

For those, totals should come from base facts or planner-managed derived summaries, not by averaging visible children.

## Separate UI State From Analytical State

Keep these concerns separate:

- analytical definition: fields, filters, summaries, sort
- UI state: expanded paths, collapsed columns, viewport windows

This separation makes saved state more stable and keeps backends from mixing presentation-only state with semantic query meaning.

## Return Windows, Not The Whole Cube

For large datasets, the backend should return:

- only the visible row-axis window
- only the visible column-axis window
- only the summaries needed for the visible analytical block

Returning the full cube defeats the whole purpose of server-side Pivot.

## Drilldown Should Mean Facts

When users drill into a summary cell, the backend should return the underlying facts scoped by:

- the current filters
- the row path
- the column path
- the selected measure if needed

That keeps drilldown trustworthy and consistent with visible summaries.

## Keep Cache Keys Semantic

Stable, semantic cache keys are the difference between a useful analytical cache and an unsafe one. Because Pivot requests are complex, your backend must identify identical windows deterministically.

Good Pivot cache keys should include:

- tenant and view identifiers
- field registry versions
- dataset watermarks (freshness)
- normalized filters, groupings, and summaries
- viewport windows

See [Caching and Cache Keys](/guides/pivot/caching/) for the full breakdown of how these keys are constructed and why they matter for safety and performance.

## Recommended Implementation Pattern

The most reliable production wiring is:

```txt
browser Pivot UI
  -> HttpPivotRemoteStore
  -> application API
  -> field registry + normalization + planner/adapter
  -> OLAP cube / warehouse
```

This keeps the public Pivot model stable while allowing your backend to translate the same request into SQL, a semantic-layer API, or a cube-native query format.

Use [Connect An OLAP Backend](/guides/pivot/connect-olap-backend/) for a practical client + backend example.

## What To Avoid

- exposing backend column names to the client
- concatenating raw selectors into SQL
- computing totals from already-rendered UI cells
- using row indexes as expansion identifiers
- coupling the grid to a specific backend framework

## Current Product Position

Today, RevoGrid Pivot already provides:

- a shared client/server config model
- a field registry and normalization layer
- a planner abstraction
- a transport-agnostic remote store
- visible-window materialization into RevoGrid

What it does not claim to be:

- a full OLAP engine
- a warehouse execution service
- a finished large-scale remote virtualization system on its own

That distinction is important. RevoGrid should remain the UI and viewport layer, while the analytical engine remains replaceable.

## Related Guides

- [Server-Side Pivot](/guides/pivot/server-side/)
- [Connect An OLAP Backend](/guides/pivot/connect-olap-backend/)
- [Remote API Reference](/guides/pivot/remote-api-reference/)
- [Configuration Reference](/guides/pivot/configuration-reference/)

---

# Remote API Reference

URL: https://pro.rv-grid.com/guides/pivot/server-side/remote-api-reference/
Source: src/content/docs/guides/pivot/server-side/remote-api-reference.mdx
Description: Technical specification for the RevoGrid Pivot remote analytical contract.

The Remote Pivot API is a transport-agnostic JSON contract that allows RevoGrid to communicate with analytical backends, OLAP cubes, or custom SQL planners.

## Load Request

The `PivotLoadRequest` is sent whenever the grid needs to materialize a visible window of analytical data.

### Root Properties

- `viewId`: Semantic identifier for the dataset (e.g., `sales_cube`).
- `fieldsVersion`: Version of the field registry used to resolve selectors.
- `loadOptions`: The analytical query definition.
- `viewport`: Request windows for row and column axes.
- `uiState`: Optional hints for engine-side formatting.

### Load Options

The `loadOptions` object defines the shape of the analytical query:

- `rows`: Array of group descriptors for the row axis.
- `columns`: Array of group descriptors for the column axis.
- `values`: Measures to aggregate.
- `filter`: Complex filter expression tree.
- `sort`: Sorting directives (can include sort-by-summary).
- `groupSummary`: Measures to calculate at every group level.

### Viewport

The `viewport` defines independent analytical windows:

- `rowAxis`: Contains `offset`, `limit`, and `expandedPaths`.
- `columnAxis`: Contains `offset`, `limit`, `expandedPaths`, and
  `collapsedPaths`.

Use typed analytical paths for expansion state, not visible column indexes.
`expandedPaths` and `collapsedPaths` describe exceptions to
`uiState.columnGroupsCollapsedByDefault`. This lets the backend calculate and
return only the visible column frontier in either default mode.

### Normalization Limits

Before planning/execution, requests are typically normalized against backend limits (`PivotLimits`) to keep payloads and query complexity bounded.

Common limits include:

- `maxRowWindowSize`: Maximum allowed `rowAxis.limit`.
- `maxColumnWindowSize`: Maximum allowed `columnAxis.limit`.
- `maxExpandedPaths`: Maximum combined number of expanded and collapsed
  frontier paths per axis.
- `maxExpansionDepth`: Maximum hierarchy depth of a single expansion path.
- `maxDrilldownLimit`: Maximum page size for drilldown requests.

For `maxExpansionDepth`, depth is the number of path segments. Example: `['Region', 'Country', 'City']` has depth `3`.

## Load Response

`PivotLoadResponse` returns only the data needed for the current visible window.

### Root Properties

- `data`: Array of row records (expected to have `__rowPath` and `__columnPath`).
- `summary`: Optional grand-total or pinned rows.
- `rowAxis`: Window metadata for the row axis.
- `columnAxis`: Window metadata for the column axis.
- `groupAggregates`: Optional grouped-row measures.
- `meta`: Diagnostic metadata.

Important response metadata:

- `cacheStatus`: 'hit', 'miss', 'warm', or 'bypass'.

## Axis Metadata

Both `rowAxis` and `columnAxis` use the same metadata structure.

| Field | Role | Description |
| :--- | :---: | :--- |
| `paths` | Required (Columns) | Array of analytical paths used to generate headers. |
| `totalCount` | Required (Rows) | Total members on server. Required for row-axis scrollbars and pagination. |
| `expandedPaths` | Optional | Expanded analytical paths echoed by the engine. |
| `collapsedPaths` | Optional | Collapsed analytical paths echoed by the engine. |

## Drilldown

Drilldown uses `PivotDrilldownRequest` and `PivotDrilldownResponse`.

The request identifies a visible summary cell by:

- `rowPath`
- `columnPath`
- optional `dataIndex`

The backend should reuse the same analytical filter context as the Pivot request, then return matching fact rows with pagination.

## UI State Hints

`uiState` hints allow the backend to optimize its output format:

- `rowHeaderLayout`: 'tree' or 'flat'.
- `showTotalsPrior`: Placement of subtotals.
- `collapsedByDefault`: Initial hierarchy state.
- `columnGroupsCollapsedByDefault`: Default state for generated column groups.

---

# Remote Tools

URL: https://pro.rv-grid.com/guides/pivot/server-side/remote-tools/
Source: src/content/docs/guides/pivot/server-side/remote-tools.mdx
Description: Add diagnostics, source-row drilldown, and saved views to a server-side Pivot screen.

Remote tools are small UI and application-layer helpers for server-side Pivot. They help you show request diagnostics, load source rows for a summarized cell, track remote activity, and manage saved Pivot layouts that can be restored into the grid.

These helpers are not a required backend. They sit around a `PivotRemoteStore` or `PivotEngineAdapter` that your app already uses for remote Pivot loading. In the demo, the remote tools panel is outside the dedicated RevoGrid wrapper so Pivot-owned UI such as the field panel can mount directly beside the grid.

## What This Page Covers

- Diagnostics model: converts remote response metadata into rows and chips your UI can render.
- Drilldown controller: turns a summarized Pivot cell into table-ready source rows.
- Field panel: lets users reorder and move row, column, value, and filter fields before saving a layout. The demo keeps unused fields in the Filters area so they can be moved into the active layout.
- Saved-view helpers: serialize, load, rename, duplicate, and delete user-owned Pivot configs that can be written back to `grid.pivot`.
- Remote store hooks: expose request activity such as `load`, `drilldown`, `saveState`, and `loadState` for support panels or audit trails.

The grid loads aggregated data through the remote store. Your surrounding app UI can reuse the same store to ask follow-up questions: "How fast was that request?", "Which source rows produced this number?", "Which saved layout should this user load?", or "What remote operation just ran?".

## Import The Helpers

All helpers below are exported from `@revolist/pivot`.

```ts
import {
  PivotDrilldownController,
  createPivotDiagnosticsModel,
  deletePivotSavedView,
  duplicatePivotSavedView,
  loadPivotView,
  renamePivotSavedView,
  savePivotView,
  type PivotConfig,
  type PivotLoadRequest,
  type PivotRemoteStoreHooks,
  type PivotSavedViewRecord,
} from '@revolist/pivot';
```

## Diagnostics Model

Remote Pivot responses can include `meta` data such as elapsed time, cache status, generated timestamp, and warnings. `createPivotDiagnosticsModel` converts that raw response into a simple display model.

Use it when you want a side panel, footer, debug drawer, or support view that explains what the last remote request did.

```ts
const response = await remoteStore.load({
  requestId: `pivot-diagnostics-${Date.now()}`,
  viewId: 'sales',
  fieldsVersion: 'sha256:fields-v1',
  loadOptions: {
    rows: [{ selector: 'region' }],
    columns: [{ selector: 'quarter' }],
    totalSummary: [{ selector: 'sales', summaryType: 'sum' }],
    groupSummary: [{ selector: 'sales', summaryType: 'sum' }],
  },
  viewport: {
    rowAxis: { offset: 0, limit: 50 },
    columnAxis: { offset: 0, limit: 12 },
  },
  uiState: {
    collapsedByDefault: true,
    rowHeaderLayout: 'tree',
  },
} satisfies PivotLoadRequest);

const diagnostics = createPivotDiagnosticsModel(response, {
  formatGeneratedAt: (value) => new Date(value).toLocaleString(),
});

for (const row of diagnostics.rows) {
  console.log(row.label, row.value);
}

for (const chip of diagnostics.chips) {
  console.log(chip.label, chip.tone);
}
```

The returned model has:

- `rows`: stable rows such as elapsed time, generated time, visible rows, and visible columns.
- `chips`: compact status items such as cache status or warnings.
- `warnings`: warning strings from the response metadata.
- `hasWarnings`: a boolean for showing warning states in your UI.

The helper does not make network requests. It only formats a `PivotLoadResponse` that your remote store already returned. In the live demo, the diagnostics panel refreshes against the currently selected layout so the visible rows and columns reflect that saved view.

## Drilldown Controller And Table State

Aggregated Pivot cells often need a "show source rows" action. `PivotDrilldownController` wraps the remote drilldown contract and keeps table state for you.

The controller owns:

- current status: `idle`, `loading`, `success`, or `error`
- table columns inferred from returned rows or `customColumns`
- source rows for the selected summary cell
- total matching row count
- request cancellation when a newer drilldown request starts

```ts
const drilldown = new PivotDrilldownController(remoteStore, {
  defaultLimit: 100,
});

const unsubscribe = drilldown.subscribe((state) => {
  renderDrilldownTable({
    loading: state.loading,
    columns: state.columns,
    rows: state.rows,
    totalCount: state.totalCount,
    error: state.error,
  });
});

await drilldown.load({
  viewId: 'sales',
  fieldsVersion: 'sha256:fields-v1',
  cell: {
    rowPath: ['North', 'Jane'],
    columnPath: [2024, 'Q1'],
  },
  customColumns: ['region', 'rep', 'year', 'quarter', 'sales'],
  offset: 0,
  limit: 25,
});

const state = drilldown.getState();
console.log(state.status, state.rows.length, state.totalCount);

unsubscribe();
drilldown.abort();
```

The `cell` value should identify the analytical cell, not the visible DOM cell. Use Pivot paths like `rowPath` and `columnPath` so your backend can apply the same grouping context and return matching fact rows. The controller state is table-ready: render `state.columns`, `state.rows`, `state.totalCount`, and `state.status` directly in your surrounding UI.

## Saved-View Helpers

Saved views are user-owned Pivot configurations. They are useful when users build several layouts, such as "Revenue by Region" and "Quarterly Margin".

The helpers use `store.saveState()` and `store.loadState()` for persistence. Rename, duplicate, and delete operate on your app's list of saved-view records, so you can combine them with your own sync logic, menus, permissions, or undo UI. In an interactive screen, listen for `pivot-config-update` from the field panel and save that latest config. Loading a view should apply the returned config back to the direct Pivot binding (`grid.pivot`, `pivot`, or framework equivalent) so the report changes immediately.

```ts
const USER_ID = 'user-123';
let views: PivotSavedViewRecord[] = [];

const config: Partial<PivotConfig> = {
  dimensions: [
    { prop: 'region' },
    { prop: 'rep' },
    { prop: 'quarter' },
    { prop: 'sales' },
  ],
  rows: ['region', 'rep'],
  columns: ['quarter'],
  values: [{ prop: 'sales', aggregator: 'sum' }],
  totals: { grandTotal: true, subtotals: true },
};

const saved = await savePivotView(remoteStore, {
  userId: USER_ID,
  viewId: 'north-sales',
  name: 'North Sales',
  config,
});

views = [...views.filter((view) => view.viewId !== saved.viewId), saved];

const loaded = await loadPivotView(remoteStore, {
  userId: USER_ID,
  viewId: 'north-sales',
});

grid.pivot = {
  ...loaded.config,
  engine: {
    mode: 'server',
    remoteStore,
    viewId: 'sales',
    fieldsVersion: 'sha256:fields-v1',
  },
};

views = renamePivotSavedView(views, {
  userId: USER_ID,
  viewId: 'north-sales',
  name: 'North Sales by Quarter',
});

views = duplicatePivotSavedView(views, {
  userId: USER_ID,
  viewId: 'north-sales',
  newViewId: 'north-sales-copy',
  name: 'North Sales Copy',
});

views = deletePivotSavedView(views, {
  userId: USER_ID,
  viewId: 'north-sales',
});
```

`savePivotView` stores a JSON-serializable Pivot config. It validates common Pivot fields before sending state to the store, which helps catch accidental functions, class instances, or invalid axis values before they become a saved view.

## Remote Store Activity

`HttpPivotRemoteStore` accepts lifecycle hooks for telemetry. They are useful for request logs, support drawers, cache badges, and lightweight audit trails near the grid.

```ts
const hooks: PivotRemoteStoreHooks = {
  requestStarted: ({ type }) => {
    activity.unshift(`${type}: started`);
  },
  requestSucceeded: ({ type, cacheStatus }) => {
    activity.unshift(`${type}: succeeded${cacheStatus ? ` (${cacheStatus})` : ''}`);
  },
  requestFailed: ({ type }) => {
    activity.unshift(`${type}: failed`);
  },
  cacheStatusChanged: ({ cacheStatus }) => {
    activity.unshift(`cache: ${cacheStatus}`);
  },
};
```

The live example uses those hooks with the same mocked `HttpPivotRemoteStore` that powers the grid. Running diagnostics, loading source rows, saving a view, and loading a view all update the activity log.

## Backend Expectations

These helpers assume the remote store supports the operation you call:

- Diagnostics needs `load()` responses with useful `meta`, `rowAxis`, and `columnAxis` data.
- Drilldown needs an adapter or store with a `drilldown()` method.
- Saved views need `saveState()` and `loadState()`.
- Activity logs need store hooks or equivalent instrumentation around your request layer.

You can implement those methods against any backend: REST, GraphQL, local storage for a demo, or an internal state service. RevoGrid does not require a specific saved-view backend.

## Recommended Reading

- [Server-Side Pivot](/guides/pivot/server-side/) - How remote Pivot loading works.
- [Remote API Reference](/guides/pivot/remote-api-reference/) - Request, response, and drilldown contracts.
- [Caching And Cache Keys](/guides/pivot/caching/) - Cache metadata used by diagnostics.

---

# Server-Side Pivot

URL: https://pro.rv-grid.com/guides/pivot/server-side/server-side/
Source: src/content/docs/guides/pivot/server-side/server-side.mdx
Description: Connect RevoGrid Pivot to a remote analytical engine without changing the public Pivot configuration model.

Server-side Pivot is for datasets that are too large, too sensitive, or too analytically expensive to fully materialize on the client. RevoGrid still owns the viewport and interaction model, but the analytical engine owns aggregation, windowing, drilldown facts, and cache-aware execution.

For raw type signatures, see [Pivot API](/api/pivot/). For the full request and store contract, continue with [Remote API Reference](/guides/pivot/remote-api-reference/).

## Architecture

The key boundary is:

```txt
Pivot UI / RevoGrid Plugin
        ->
  Pivot engine adapter
        ->
  remote store or analytical backend
```

In practical terms:

- `PivotPlugin` receives the direct `pivot` config
- `pivot.engine.mode = 'server'` switches the plugin to remote loading
- `PivotEngineAdapter` or `PivotRemoteStore` handles the analytical request
- the grid only receives the visible block to render

## Why The Public Config Stays The Same

The core Pivot model does not change:

- `rows`
- `columns`
- `values`
- `totals`
- drill-down related UI state

That is deliberate. The UI should not need one config model for client Pivot and another for server Pivot.

## Basic Setup

```ts
import {
  PivotPlugin,
  HttpPivotRemoteStore,
  type PivotConfig,
} from '@revolist/pivot';
import { PaginationPlugin } from '@revolist/revogrid-pro';

const remoteStore = new HttpPivotRemoteStore({
  baseUrl: 'https://example.internal',
  tenantId: 'tenant-a',
  datasetWatermark: 'sales-v42',
  authProvider: async () => ({
    Authorization: `Bearer ${await getToken()}`,
  }),
});

const pivot: PivotConfig = {
  dimensions: [...],
  rows: ['Category', 'Subcategory'],
  columns: ['Date'],
  values: [{ prop: 'SalesAmount', aggregator: 'sum' }],
  totals: { grandTotal: true, subtotals: true },
  collapsed: true,
  engine: {
    mode: 'server',
    remoteStore,
    viewId: 'sales-by-region',
    fieldsVersion: 'sha256:fields-v1',
    rowAxis: { },
    columnAxis: { },
  },
};

// PaginationPlugin drives row-axis paging automatically.
// PivotPlugin reads itemsPerPage as rowAxis.limit and writes
// response.rowAxis.totalCount back to pagination.total after each load.
grid.plugins = [PivotPlugin, PaginationPlugin];
grid.pivot = pivot;
grid.additionalData = {
  pagination: {
    itemsPerPage: 50,
    initialPage: 0,
    total: 0,         // auto-populated from the first server response
  },
};
```

## Pagination With Remote Pivot

`PivotPlugin` integrates directly with `PaginationPlugin`. When both plugins are active:

- `pagination.itemsPerPage` becomes the row-axis page size (`rowAxis.limit`).
- When the user changes page, `PivotPlugin` reloads the server window at the new `rowAxis.offset`.
- After each successful load, `response.rowAxis.totalCount` is written back to `pagination.total` so the pagination panel shows the correct count.
- Changing the pivot structure (rows, columns, values) resets the offset to 0 automatically.

You do not need to handle page-change events yourself. Drop both plugins into `grid.plugins`, bind the Pivot config to `grid.pivot`, and add `pagination` to `additionalData`.

## What RevoGrid Owns vs What The Engine Owns

RevoGrid and `PivotPlugin` own:

- visible grid rendering
- generated RevoGrid columns
- visible row block
- grouped-row metadata used by current drill-down UI
- cancellation and last-response-wins behavior in the plugin lifecycle

The remote engine or backend owns:

- selector validation
- filter execution
- analytical grouping
- summary execution
- row-axis and column-axis windows
- drilldown fact pages
- cache policy and invalidation

## Request Flow

1. `PivotPlugin` sees `engine.mode = 'server'`.
2. It builds a `PivotLoadRequest` from the public Pivot config and current window hints.
3. The adapter or remote store executes the request.
4. The response is materialized into generated columns, visible rows, and pinned totals.
5. RevoGrid renders only the visible analytical window.

## Field Registry And Planner

- Public selectors must be resolved through a field registry.
- Backend expressions must come from the registry, never from client strings.
- Query planning belongs behind a planner abstraction so SQL, OLAP, or warehouse backends can share the same request model.

This repository already includes:

- a field registry model
- request normalization and limit enforcement
- a typed error model
- an SQL-oriented logical planner shape
- a framework-agnostic `HttpPivotRemoteStore`

## Complete Backend Implementation

A production Pivot backend needs to translate the analytical request into your engine's native query format. This example demonstrates a TypeScript handler using the core request and response types.

```ts
import {
  type PivotLoadRequest,
  type PivotLoadResponse,
} from '@revolist/pivot';

/**
 * Handle POST /api/pivot/load
 */
export async function handlePivotLoad(req: Request): Promise<PivotLoadResponse> {
  const request = req.body as PivotLoadRequest;
  const { loadOptions, viewport, viewId, fieldsVersion, uiState } = request;

  // 1. Authenticate and resolve tenant
  const tenantId = await getTenant(req);

  // 2. Extract analytical parameters
  const {
    rows = [],           // Group descriptors for rows
    columns = [],        // Group descriptors for columns
    filter,              // Complex filter expression tree
    sort = [],           // Sorting directives
    totalSummary = [],   // Grand-total measures
    groupSummary = [],   // Group-level measures (for groupAggregations)
  } = loadOptions;

  // 3. Extract viewport windows
  const { rowAxis, columnAxis } = viewport;

  // 4. Execute analytical query (e.g., against SQL or OLAP)
  const result = await myAnalyticalEngine.execute({
    tenantId,
    viewId,
    fieldsVersion,
    rows,
    columns,
    filter,
    sort,
    measures: [...totalSummary, ...groupSummary],
    rowWindow: rowAxis,
    columnWindow: columnAxis,
    // uiState.rowHeaderLayout, uiState.showTotalsPrior, etc.
  });

  // 5. Build the response
  return {
    data: result.cells,           // REQUIRED: Visible analytical payload
    summary: result.totals,       // OPTIONAL: Grand-total or pinned rows
    rowAxis: {
      totalCount: result.rowCount, // REQUIRED: Drives scrollbars/pagination
    },
    columnAxis: {
      paths: result.colPaths,      // REQUIRED: Defines the generated headers
    },
    // Optional: Grouped-row aggregate payloads (if groupSummary requested)
    groupAggregates: result.groupSummaries,
    meta: {
      cacheStatus: result.fromCache ? 'hit' : 'miss', // Used for telemetry
    },
  };
}
```

## Current Scope

Server-side Pivot is a powerful but complex feature. The standard `PivotPlugin` implements the core windowing and materialization logic, but some advanced scenarios require custom engine adapters:

- **Implemented**: Row-axis windowing, generated columns from `paths`, tree-mode row headers, grouped aggregations, and grand totals.
- **Custom Adapters**: Complex sorting-by-summary or calculated measures typically require a custom `PivotEngineAdapter` to map your specific backend capabilities to the Pivot contract.
- **Not implemented here**: Infinite horizontal scrolling (past the requested column window) or full server-side column grouping collapse (currently managed on client).

## Recommended Reading

- [Remote API Reference](/guides/pivot/remote-api-reference/) — Detailed JSON schema for requests and responses.
- [Caching And Cache Keys](/guides/pivot/caching/) — How to ensure deterministic and efficient analytical execution.
- [OLAP Best Practices](/guides/pivot/olap-best-practices/) — Performance and security tips for backend implementations.

---

# Financial Pivot Showcase

URL: https://pro.rv-grid.com/guides/pivot/showcase/
Source: src/content/docs/guides/pivot/showcase.mdx
Description: Explore sales, profit, and units by country, segment, year, and month using realistic synthetic financial data.

This showcase uses 3,600 original synthetic records shaped like a familiar financial sales model. The schema is inspired by Microsoft's [Financial Sample workbook](https://learn.microsoft.com/en-gb/power-bi/create-reports/sample-financial-download), but the bundled values and product names are generated specifically for this demo.

## What This Example Demonstrates

- multiple row levels
- generated column groups
- sales, profit, and units-sold measures
- product and discount-band filters
- totals and subtotals
- interactive configurator updates
- `pivot-config-update` for external state sync
- instant Sales Overview, Profitability, and Product Performance presets
- responsive configuration, reset, and expanded-grid controls

## How To Read It

Watch how the layout changes as you:

- move fields between rows, columns, and values
- change aggregators
- expand or collapse grouped rows
- enable or disable totals

The initial layout uses `Country → Segment` for rows and `Year → Month` for columns, so you can compare markets and segments while following monthly performance.

The example is useful because it shows that Pivot is not a separate reporting component. It is still RevoGrid, with generated analytical rows and columns layered on top.

## Related Guides

- [Configuration Reference](/guides/pivot/configuration-reference/)
- [Plugin Lifecycle](/guides/pivot/plugin-lifecycle/)
- [Configurator API](/guides/pivot/configurator-api/)
- [Field Panel](/guides/pivot/field-panel/)
- [Server-Side Pivot](/guides/pivot/server-side/)

---

# Comprehensive Guide to Using RevoGrid Plugins

URL: https://pro.rv-grid.com/guides/plugin/
Source: src/content/docs/guides/plugin.mdx

RevoGrid is a highly flexible and extensible grid component that supports a powerful plugin system. This guide will walk you through everything you need to know about using RevoGrid plugins, from understanding the basics to creating and integrating your custom plugins.

#### 1. **Understanding RevoGrid Plugins**

RevoGrid plugins are modular pieces of code that extend the functionality of the RevoGrid component. These plugins can:
- Add new features.
- Modify existing behavior.
- Integrate with other libraries or frameworks.

All RevoGrid plugins extend from the `BasePlugin` class, which provides a minimal core and utility methods for interacting with the RevoGrid component.

#### 2. **Setting Up Your Development Environment**

Before you can start working with RevoGrid plugins, ensure you have a development environment set up with the following:
- **Node.js** and **npm** (Node Package Manager) installed.
- A code editor (such as **Visual Studio Code**).
- A basic understanding of TypeScript, as RevoGrid and its plugins are TypeScript-based.

To get started, you need to install RevoGrid in your project:

```bash
npm install @revolist/revogrid
```

#### 3. **Creating a Simple Plugin**

Let's start by creating a simple plugin that add class to odd rows.

1. **Create a New Plugin Class**: Your plugin should extend the `BasePlugin` class provided by RevoGrid.

```typescript
import { BasePlugin, type PluginProviders } from '@revolist/revogrid';

export class RowOddPlugin extends BasePlugin {
  constructor(revogrid: HTMLRevoGridElement, providers: PluginProviders) {
    super(revogrid, providers);

    this.addEventListener(
      'beforerowrender',
      ({
        detail,
      }: CustomEvent<HTMLRevogrDataElementEventMap['beforerowrender']>) => {
        detail.node.$attrs$ = {
          ...detail.node.$attrs$,
          odd: detail.item.itemIndex % 2 !== 0,
        };
      }
    );
  }
}
```

2. **Integrate the Plugin**: Once your plugin is created, integrate it with your RevoGrid instance.

```typescript
const gridElement = document.querySelector('revo-grid');
gridElement.plugins.push(new RowOddPlugin(gridElement, providers));
```

#### 4. **Exploring Core Plugin Methods**

When creating more complex plugins, you'll likely use several core methods provided by the `BasePlugin` class:

- **`addEventListener(eventName: string, callback: (e: CustomEvent) => void): void`**: Subscribes to a RevoGrid event.

  Example:
  ```typescript
  this.addEventListener('beforecellrender', this.handleCellRender);
  ```

- **`watch(prop: string, callback: (arg: T) => boolean | void, config?: Partial): void`**: Watches a property on the RevoGrid component for changes.

  Example:
  ```typescript
  this.watch('rowSelection', (newValue) => {
    console.log('Row selection changed:', newValue);
  });
  ```

- **`emit(eventName: string, detail?: any): CustomEvent`**: Emits a custom event from the RevoGrid component.

  Example:
  ```typescript
  this.emit('customEvent', { data: 'someData' });
  ```

- **`clearSubscriptions(): void`**: Clears all event listeners subscribed by the plugin.

- **`destroy(): void`**: Cleans up the plugin by removing all subscriptions and performing any necessary teardown.

#### 5. **Advanced Plugin Development**

RevoGrid provides a set of providers that you can use to interact with its internal state. These providers include:

- **Data Provider**: Manipulate the grid's data.
- **Dimension Provider**: Manage row and column dimensions.
- **Selection Provider**: Handle cell and row selections.
- **Column Provider**: Manage column data and properties.
- **Viewport Provider**: Handle scrolling and viewport rendering.

Here's how you might use these providers in a more advanced plugin:

```typescript
class HighlightSelectionPlugin extends BasePlugin {
  constructor(revogrid: HTMLRevoGridElement, providers: PluginProviders) {
    super(revogrid, providers);

    this.addEventListener('afterselectionchange', this.highlightSelectedCells);
  }

  private highlightSelectedCells = () => {
    const selectedCells = this.providers.selection.getSelectedCells();
    selectedCells.forEach(cell => {
      const model = this.providers.data.getModel(cell.rowIndex, cell.type);
      model.cellProperties = {
        style: {
          backgroundColor: 'yellow'
        }
      };
    });
  };
}
```

#### 6. **Styling with Plugins**

Plugins can also be used to dynamically style the grid. For example, using a plugin to flash cells after they are edited:

```typescript
import './cell-flash.style.css';

class CellFlashPlugin extends BasePlugin {
  constructor(revogrid: HTMLRevoGridElement, providers: PluginProviders) {
    super(revogrid, providers);
    this.addEventListener('onEdit', this.handleEdit);
  }

  private handleEdit = (e: CustomEvent) => {
    const { rowIndex, prop } = e.detail;
    const cell = this.revogrid.getCell(rowIndex, prop);
    cell.classList.add('flash');
    setTimeout(() => cell.classList.remove('flash'), 1000);
  };
}

// cell-flash.style.css
.flash {
  animation: flash 1s ease;
}

@keyframes flash {
  from { background-color: yellow; }
  to { background-color: transparent; }
}
```

#### 7. **Best Practices for Plugin Development**

- **Keep Plugins Modular**: Each plugin should have a single responsibility and be as modular as possible.
- **Manage Subscriptions**: Always clear subscriptions when they are no longer needed to avoid memory leaks.
- **Utilize Providers Wisely**: Only use the necessary providers to keep your plugin efficient.
- **Ensure Compatibility**: Test your plugins thoroughly to ensure they work well with other plugins and configurations.

#### 8. **Deploying and Sharing Plugins**

Once you've created a plugin, you can package it as an npm module and share it with the community. Here's a basic setup for packaging your plugin:

1. **Create a `package.json` file**:

```json
{
  "name": "revogrid-cell-logger",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc"
  },
  "dependencies": {
    "@revolist/revogrid": "^4.0.0"
  }
}
```

2. **Build your plugin**:

```bash
npm run build
```

3. **Publish to npm**:

```bash
npm publish
```

#### 9. **Conclusion**

RevoGrid's plugin system is a powerful way to extend its functionality and adapt it to your needs. Whether you're creating simple event listeners or complex data manipulation tools, the flexibility provided by the `BasePlugin` class and the various providers make it easy to build, deploy, and share custom plugins.
By following this guide, you should now be equipped to start creating your own plugins, enhancing the capabilities of RevoGrid, and contributing to a richer ecosystem for all users.

---

# Drag and Drop (Advanced)

URL: https://pro.rv-grid.com/guides/rows/row-advanced-drag-drop/
Source: src/content/docs/guides/rows/row-advanced-drag-drop.mdx
Description: Custom drag-and-drop behavior and interactions.

Implement sophisticated drag-and-drop functionality within your grid

Reorder plugin in RevoGrid may appear simple at first glance, but it’s quite a complex and powerful feature.
It supports **multi-item reordering**, allowing users to move multiple rows or columns at once while preserving the integrity of the dataset.
Leveraging **`proxyItems`** for efficient handling of the full dataset, the plugin ensures that **filter positioning remains correct** even after reordering, maintaining a seamless user experience.

Beyond its core functionality, plugin plays a **crucial role in supporting other plugins** within RevoGrid.
It facilitates **data transfer** across different operations and plugins, extending the overall capabilities of the grid.

This makes it an essential component for managing dynamic datasets in RevoGrid Pro.

- **Custom Drag-and-Drop Behavior**:
  Tailor the drag-and-drop interactions to fit your application’s specific needs. You can configure how rows are moved, allowing for both simple and complex drag-and-drop operations.

- **Enhanced Interactivity**:
  Improve the overall usability of your grid. With responsive drag-and-drop functionality, users can quickly reorganize data, making it easier to manage and visualize information.

- **Multi-Row Dragging**:
  Users can drag and drop multiple rows at once, simplifying bulk operations. This is particularly useful for scenarios where users need to rearrange large datasets quickly.

- **Flexible Dimensions**:
  Allow dragging in any direction—vertically or horizontally—supporting both pinned and classic rows. This flexibility enables users to interact with the grid in a way that feels natural to them.

- **Custom Classes During Dragging**:
  Apply custom styles during drag operations to provide visual feedback. This feature helps users understand what they are dragging and where they can drop it, enhancing the overall experience.

- **Drag Handle Customization**:
  Implement your own drag handles and apply them to custom cells without limitations. This means you can design specific elements within your rows to serve as drag handles, making it clear to users which parts of the UI are draggable.

- **Extendable Event Source**:
  Enhance functionality by extending the drag event source. You can create custom events and interactions that suit your application’s specific requirements, allowing for a more tailored user experience.

### How to use

To enable drag and drop functionality for specific columns, first, import the `RowOrderPlugin` from `@revolist/revogrid-pro` and then simply add the `rowDrag` property to the column configuration:
```ts
import { RowOrderPlugin } from '@revolist/revogrid-pro';
grid.columns = [
  { name: '🆔 ID', prop: 'id', rowDrag: true },
];

// or in row headers
grid.rowHeaders = { rowDrag: true };

// don't forget to add the plugin
grid.plugins = [RowOrderPlugin];
```

### Row Order Preview

Use `grid.rowOrder` to customize what appears in the drag preview. `prop` keeps the existing compact label behavior, and `previewProp` can be a column prop or callback when the preview label needs application-specific text:

```ts
grid.rowOrder = {
  prop: 'name',
  preview: 'compact',
  previewProp: ({ firstItem, itemCount }) => {
    const label = firstItem?.name ?? 'Rows';
    return itemCount > 1 ? `${label} and ${itemCount - 1} more` : label;
  },
};
```

`additionalData.rowOrder` is still supported for compatibility, but direct `grid.rowOrder` configuration is preferred.

### Flash Moved Rows

If `CellFlashPlugin` is installed with `RowOrderPlugin`, successfully moved rows flash automatically after the reorder is committed. The flash applies only to the dragged row or dragged selection block at its new visible position:

```ts
import { CellFlashPlugin, RowOrderPlugin } from '@revolist/revogrid-pro';

grid.plugins = [RowOrderPlugin, CellFlashPlugin];
grid.cellFlash = {
  rowDuration: 1200,
};
```

Invalid, canceled, or no-op drops do not flash. Existing `cellFlash` options control the row flash duration, CSS class, reduced-motion behavior, and whether flashing is enabled.

To keep `CellFlashPlugin` active for edits or manual flash calls but disable row-order drop flashes, set `rowOrder.flashOnDrop` to `false`:

```ts
grid.rowOrder = {
  prop: 'name',
  flashOnDrop: false,
};
```

### Live Drop Validation

Use `validateDrop` when some positions should be blocked while the user is dragging. Invalid targets are highlighted immediately and are not committed on mouseup:

```ts
grid.rowOrder = {
  prop: 'name',
  validateDrop: ({ targetIndex }) => {
    if (targetIndex === 0) {
      return {
        valid: false,
        reason: 'The first row is locked.',
      };
    }
    return { valid: true };
  },
};
```

You can also validate with events when a plugin or application controller owns the rule:

```ts
grid.addEventListener('beforerowdropvalidate', (event) => {
  if (event.detail.targetIndex === 0) {
    event.detail.result = {
      valid: false,
      reason: 'The first row is locked.',
    };
  }
});

grid.addEventListener('rowdropstatechange', (event) => {
  if (!event.detail.result.valid) {
    console.info(event.detail.result.reason);
  };
});
```

### Grouped Row Drops

When row grouping is active, row order keeps data rows inside their current group by default. This also applies when rows are selected through `RowSelectPlugin`: synthetic group rows are ignored, and only real data rows are validated. For multi-level grouping, the full configured `grouping.props` path must match before the drop is committed.

If your workflow should let users move rows between groups, enable `applyTargetGroupOnDrop`. The row-order plugin will apply the target group values to every moved row and emit normal `beforeedit` and `afteredit` events for each changed group field. Calling `event.preventDefault()` in `beforeedit` cancels the drop.

```ts
grid.grouping = {
  props: ['team', 'status'],
  expandedAll: true,
};

grid.rowOrder = {
  prop: 'name',
  preview: 'compact',
  applyTargetGroupOnDrop: true,
};

grid.addEventListener('beforeedit', (event) => {
  if (event.detail.prop === 'team' && event.detail.val === 'Archived') {
    event.preventDefault();
  }
});
```

### User-Centric Benefits

By leveraging the advanced drag-and-drop capabilities, users will experience:

- **Increased Efficiency**: Streamline workflows by allowing users to quickly rearrange rows, making data management less cumbersome.
- **Improved Data Visualization**: Users can reorganize data in a way that makes the most sense to them, leading to better insights and understanding.
- **Intuitive Interface**: A well-implemented drag-and-drop feature provides an intuitive interface, reducing the learning curve for new users.
- **Customization Flexibility**: Allowing for custom drag handles and styles gives users the ability to tailor their experience according to their preferences.

Advanced drag-and-drop functionality empowers users to interact with their data in a more dynamic and intuitive way. By customizing the behavior and appearance of drag-and-drop actions, you can significantly enhance the user experience within your grid application. Embrace these capabilities to create a more engaging and efficient interface that meets your users' needs.

---

# Header (Advanced)

URL: https://pro.rv-grid.com/guides/rows/row-advanced-header/
Source: src/content/docs/guides/rows/row-advanced-header.mdx
Description: Custom Row Header

Sophisticated Row Header example based on `RowHeaderPlugin`. The demo uses a task pipeline layout so the row header has a clear job: it anchors each row, opens row-level actions, and keeps row focus visible while the cells provide richer operational context.

- Use `rowHeaders({ showHeaderFocusBtn: true })` for a dedicated row action rail
- Open a row `ContextMenuPlugin` menu directly from the row-header click
- Combine row headers with custom column templates for status, priority, owner, due date, and progress
- Focus the whole row from the row header while preserving readable business data in the grid body
- Style the row-header rail and content cells together so the row action area feels intentional

---

<div hidden>

```javascript
// fixing render for multiframework
```

</div>

---

# Auto Size Row

URL: https://pro.rv-grid.com/guides/rows/row-autosize/
Source: src/content/docs/guides/rows/row-autosize.mdx
Description: Automatically adjust row heights based on content

The **Row Auto Size Plugin** enhances RevoGrid by automatically calculating and adjusting row heights based on their content. This ensures optimal display of data, particularly useful for cells containing multi-line text, rich content, or varying amounts of information.

When the plugin is enabled, normal grid cells wrap text so the rendered content matches the height calculation. Row heights are recalculated from the wrapped content after source changes, edits, scrolling into new virtual rows, configuration changes, and manual column resizing.

It is a **sophisticated feature** that significantly improves data presentation and user experience:

1. **Dynamic Content Adaptation**: Automatically adjusts row heights to accommodate varying content lengths, ensuring all data is visible without truncation.

2. **Performance Optimization**: Uses efficient caching and virtualization to maintain smooth scrolling even with large datasets and dynamic heights.

3. **Precise Calculations**: Offers both approximate and precise height calculations, allowing you to balance between performance and accuracy.

4. **Event-Driven Updates**: Intelligently recalculates heights only when necessary, such as after edits or viewport changes.

5. **Memory Management**: Implements cleanup strategies to prevent memory leaks and maintain optimal performance during long sessions.

- **Automatic Height Calculation**: Dynamically adjusts row heights based on content.
- **Content-Aware**: Considers line breaks, text wrapping, and column widths.
- **Resize-Aware**: Recalculates visible row heights after manual column resizing.
- **Configurable Limits**: Set minimum and maximum heights to maintain consistency.
- **Custom Calculator Support**: Implement your own height calculation logic.
- **Efficient Caching**: Caches calculated heights to optimize performance.
- **Precise Mode**: Optional precise calculations using DOM measurements.

## Basic Setup

To enable the Row Auto Size Plugin in your RevoGrid setup:

```typescript
import { RowAutoSizePlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [RowAutoSizePlugin];

grid.rowAutoSize = {
  minHeight: 24,
  maxHeight: 200,
  preciseSize: true, // Use DOM-based precise calculations
  precalculate: true, // Warm approximate row sizes ahead of scroll
  precalculateBatchSize: 500, // Rows processed per frame during warmup
};
grid.resize = true; // Optional: row heights adapt after user column resizing
```

## Configuration Options

The plugin supports several configuration options to customize its behavior:

```typescript
type RowAutoSizeConfig = {
  // Minimum row height in pixels (default: 24)
  minHeight?: number;

  // Maximum row height in pixels (default: 200)
  maxHeight?: number;

  // Use precise DOM-based calculations (slower but more accurate)
  preciseSize?: boolean;

  // Warm all approximate row heights in chunks before they are scrolled into view (default: true)
  precalculate?: boolean;

  // Rows processed per animation frame during non-precise warmup (default: 500)
  precalculateBatchSize?: number;

  // Custom height calculator function
  calculateHeight?: (rowData: DataType, columns: ColumnRegular[]) => number | Promise<number>;
};
```

### Custom Height Calculator

You can provide your own height calculation logic through the `calculateHeight` function:

```typescript
grid.rowAutoSize = {
  calculateHeight: (rowData, columns) => {
    // Custom logic to determine row height
    const maxLines = columns.reduce((max, col) => {
      const content = rowData[col.prop]?.toString() || '';
      const lines = content.split('\n').length;
      return Math.max(max, lines);
    }, 1);

    return maxLines * 24; // 24px per line
  }
};
```

## Events and Updates

The plugin automatically responds to various grid events to maintain accurate row heights:

- **Data Changes**: Recalculates heights when the source data is updated
- **Cell Edits**: Updates heights for edited rows
- **Viewport Changes**: Calculates heights for newly visible rows
- **Configuration Changes**: Recomputes all heights when plugin settings change
- **Column Resizing**: Recomputes visible row heights after resized widths are rendered

## Performance Considerations

The plugin is designed with performance in mind, but there are some considerations:

1. **Precise Mode**: Using `preciseSize: true` provides more accurate calculations but is slower as it requires DOM operations.
2. **Precalculation**: In non-precise mode, `precalculate` is enabled by default. The plugin warms row height cache in chunks so rows already have a height when they are scrolled into view.
3. **Batch Size**: `precalculateBatchSize` controls how many rows are processed per animation frame. Larger values warm the cache faster but make each frame heavier.
4. **Large Datasets**: For very large datasets, set `precalculate: false` to calculate only visible rows and preserve demand-driven behavior.
5. **Custom Calculators**: When implementing a custom calculator, ensure it's efficient as it will be called frequently during scrolling.

To disable background warmup:

```typescript
grid.rowAutoSize = {
  minHeight: 24,
  maxHeight: 200,
  precalculate: false,
};
```

## Best Practices

1. **Default Mode for Large Datasets**: Use the default approximate calculation mode for large datasets to maintain performance.
2. **Custom Height Logic**: Use `calculateHeight` when your data needs application-specific sizing.
3. **Reasonable Limits**: Set appropriate `minHeight` and `maxHeight` to prevent extreme row sizes.
4. **Cache Management**: The plugin automatically manages its cache, but consider clearing it when making major data changes.

## Example Use Cases

1. **Multi-line Text**:
```typescript
grid.columns = [{
  prop: 'description',
  name: 'Description',
  size: 200,
}];
grid.source = [{
  description: 'This is a long description\nthat spans multiple lines\nand needs appropriate height'
}];
```

2. **Rich Content**:
```typescript
grid.rowAutoSize = {
  calculateHeight: (rowData) => {
    if (rowData.hasImage) {
      return 100; // Taller rows for rows with images
    }
    return 24; // Default height for other rows
  }
};
```

## Conclusion

The Row Auto Size Plugin provides a powerful solution for handling varying content heights in RevoGrid. By automatically adjusting row heights while maintaining performance, it significantly improves the presentation and usability of your grid, especially when dealing with dynamic or rich content.

---

# Rows and Columns Context Menu

URL: https://pro.rv-grid.com/guides/rows/row-context-menu/
Source: src/content/docs/guides/rows/row-context-menu.mdx
Description: Custom context menu for rows and columns

This example demonstrates how to create separate context menus with interactive actions for grid rows and columns. Use the same `ContextMenuPlugin`, but pass row actions through `rowContextMenu` and column-header actions through `columnContextMenu`.

**Key Features**:
- Separate row and column context menu configurations
- Actions with visual indicators
- Styled menu buttons with hover effects

---

---

# Auto-Focus on Next Row WCAG

URL: https://pro.rv-grid.com/guides/rows/row-next-line/
Source: src/content/docs/guides/rows/row-next-line.mdx
Description: Enhances user navigation within the grid by automatically moving the focus to the next row

The plugin enhances user navigation within the grid by automatically moving the focus to the next row when the user reaches the last cell of the current row. This feature streamlines data entry and editing processes by eliminating the need for manual navigation between rows.

**Key Features**:
- **Automatic Navigation**: Focus shifts seamlessly to the next row once the user navigates to the last cell in the current row.
- **Enhanced Efficiency**: Improves data entry and editing efficiency by reducing the need for manual row transitions.
- **Configurable Behavior**: Allows customization of focus behavior to fit specific user needs and grid configurations.

**Benefits:**
- **Improved User Experience**: Simplifies navigation within the grid, making data handling more intuitive.
- **Increased Productivity**: Accelerates data entry tasks by automating row transitions.

**Usage:**
Integrate this plugin into your setup to enable automatic focus shifting, enhancing navigation and overall grid interaction.

<div hidden>

```javascript
// fixing render for multiframework
```

</div>

---

# Row Odd

URL: https://pro.rv-grid.com/guides/rows/row-odd/
Source: src/content/docs/guides/rows/row-odd.mdx
Description: Configurable row striping

Apply configurable row striping for better readability and data distinction with the help of the `RowOddPlugin`.

```ts
import { RowOddPlugin } from '@revolist/revogrid-pro';

grid.plugins = [RowOddPlugin];
grid.rowOdd = {
  mode: 'custom',
  interval: 3,
  offset: 1,
  className: 'priority-band',
};
```

`RowOddPlugin` is still a small rendering plugin, but it now covers production theming needs: odd/even striping, custom intervals, runtime updates, and predicate-based row bands.

---

# Row Status

URL: https://pro.rv-grid.com/guides/rows/row-status/
Source: src/content/docs/guides/rows/row-status.mdx
Description: Source-backed todo checkboxes, row attributes, strike-through styling, and hierarchy propagation.

`RowStatusPlugin` turns boolean columns into status checkboxes. The boolean remains in your source model, while the plugin adds semantic attributes to rendered rows and provides a default strike-through treatment.

- Status values are ordinary source booleans, so they can be saved, filtered, exported, and sorted.
- Every status column defines its own row attribute.
- Multiple status columns work independently.
- Tree parents cascade changes to descendants and reflect partial completion with an indeterminate checkbox.
- Completed-row sorting is application policy and stays outside the plugin.

## Basic setup

Register the plugin and add `rowStatus` to a boolean column. Only the strict value `true` activates the status.

```ts
import { RowStatusPlugin } from '@revolist/revogrid-pro';

grid.plugins = [RowStatusPlugin];
grid.columns = [
  {
    prop: 'done',
    name: 'Done',
    rowStatus: { attribute: 'data-done' },
  },
  { prop: 'task', name: 'Task' },
];
grid.source = [
  { task: 'Write release notes', done: false },
  { task: 'Publish the build', done: true },
];
```

An active row receives both `[data-done]` and the common `[row-status]` attribute. The common attribute drives the built-in strike-through style.

Use safe semantic names such as `data-done`, `data-archived`, or an appropriate `aria-*` attribute. Structural and event attributes such as `class`, `style`, and `onclick` are rejected so status configuration cannot overwrite renderer-owned row properties. Invalid names are ignored and reported once in development output.

## Styling

The checkbox cell stays interactive while normal row cells receive the status treatment. Override the CSS variables on the grid when a different presentation is needed:

```css
revo-grid.my-todos {
  --revo-row-status-color: #64748b;
  --revo-row-status-opacity: 0.7;
  --revo-row-status-text-decoration: line-through;
  --revo-row-status-checkbox-size: 20px;
  --revo-row-status-checkbox-radius: 50%;
}

revo-grid.my-todos .rgRow[data-archived] .rgCell:not(.row-status-cell) {
  --revo-row-status-text-decoration: line-through double;
}
```

Row-status controls are circular by default so they remain visually distinct from regular checkbox editors and row-selection checkboxes. Set `--revo-row-status-checkbox-radius` to another value if a different treatment is preferred.

## Multiple status columns

Each column uses its own source prop and attribute. A row keeps `[row-status]` while any configured status is active.

```ts
grid.columns = [
  {
    prop: 'done',
    name: 'Done',
    rowStatus: { attribute: 'data-done' },
  },
  {
    prop: 'archived',
    name: 'Archived',
    rowStatus: { attribute: 'data-archived' },
  },
  { prop: 'task', name: 'Task' },
];
```

## Tree todo lists

Add `TreeDataPlugin` and normal tree configuration. Propagation is isolated per status column.

```ts
import { RowStatusPlugin, TreeDataPlugin } from '@revolist/revogrid-pro';

grid.plugins = [TreeDataPlugin, RowStatusPlugin];
grid.tree = {
  idField: 'id',
  parentIdField: 'parentId',
  rootParentId: null,
  expandAll: true,
};
grid.columns = [
  { prop: 'done', name: 'Done', rowStatus: { attribute: 'data-done' } },
  { prop: 'task', name: 'Task', tree: true },
];
```

| Action | Result |
| --- | --- |
| Check a parent | The parent and every descendant become complete, including collapsed or filtered descendants. |
| Clear a parent | The parent and every descendant become incomplete. |
| Complete every child | Ancestors become complete from the deepest parent to the root. |
| Complete only some children | The parent value remains false and its checkbox renders indeterminate. |
| Load inconsistent initial values | The source is not rewritten; subtree state is displayed and affected ancestors reconcile on the next edit. |

## Classic row grouping

Classic grouping works automatically when `grid.grouping` is configured. Every synthetic group label renders one checkbox for each row-status column; no extra plugin option is required.

```ts
grid.plugins = [RowStatusPlugin];
grid.grouping = {
  props: ['department', 'team'],
  expandedAll: true,
};
grid.columns = [
  { prop: 'done', name: 'Done', rowStatus: { attribute: 'data-done' } },
  { prop: 'archived', name: 'Archived', rowStatus: { attribute: 'data-archived' } },
  { prop: 'task', name: 'Task' },
  { prop: 'department', name: 'Department' },
  { prop: 'team', name: 'Team' },
];
```

| Grouping action | Result |
| --- | --- |
| Check a group status | Every real descendant receives that boolean value, including descendants hidden by collapsed groups or filters. |
| Edit one child | Ancestor group checkboxes recompute as checked, unchecked, or indeterminate. |
| Use multiple statuses | Each group checkbox and source prop remains independent. |
| Sort, filter, or regroup | Status remains attached to the real source model through its original physical index. |
| Listen for `rowstatuschange` | Only real models and application-source indexes are included; synthetic group rows are excluded. |

Normal data rows receive the configured attribute directly. Because core grouping headers are synthetic rows rendered through the group-label template, their derived attributes are placed on `.row-status-group-label` instead. The same `[row-status]` styling is applied when every descendant is complete for at least one status.

## Complete batch event

The directly clicked checkbox uses the regular `beforeedit` and `afteredit` events. Listen for `rowstatuschange` when you need the complete hierarchy batch:

```ts
grid.addEventListener('rowstatuschange', event => {
  const {
    prop,
    value,
    physicalIndexes,
    models,
  } = event.detail;

  persistStatusChanges({ prop, value, physicalIndexes, models });
});
```

## Move completed items down

Sorting is intentionally configured by the application. Set ascending boolean sorting (`false` before `true`) and reapply it after a completed-status batch:

```ts
grid.columns = [
  {
    prop: 'done',
    name: 'Done',
    sortable: true,
    order: 'asc',
    rowStatus: { attribute: 'data-done' },
  },
  { prop: 'task', name: 'Task', tree: true },
];

grid.addEventListener('rowstatuschange', event => {
  if (event.detail.prop === 'done') {
    void grid.updateColumnSorting({ prop: 'done' }, 'asc', false);
  }
});
```

See the generated [`RowStatusPlugin` API reference](/api/row-status/) for exported types, constants, and the full JSDoc example.

---

# Row Transpose

URL: https://pro.rv-grid.com/guides/rows/row-transpose/
Source: src/content/docs/guides/rows/row-transpose.mdx
Description: Learn how to use the Row Transpose Plugin in RevoGrid Pro to switch rows and columns dynamically.

The Row Transpose Plugin modifies the grid by transposing its data, meaning that the original rows are converted into columns and vice versa.
This can be especially useful when dealing with datasets that require pivoting or when users need to explore data from different perspectives.

- **Toggle Transpose**: Switch between the original view and the transposed view.
- **Dynamic Headers**: Customizable transposed headers for better data representation.
- **Custom Transpose Configuration**: Define how the columns and rows should be transformed, including whether to transpose column headers into rows.

## How Transposing Works

The plugin offers two primary functionalities:

- **Original View**: Displays rows and columns as defined in your data model.
- **Transposed View**: When activated, this feature converts rows into columns and columns into rows.

The `RowTransposePlugin` listens for the `row-transpose`.
When triggered, it switches between the original view and the transposed view while preserving the original structure, allowing you to revert to the standard view at any time.

Alternatively, you can access the plugin directly using the following JavaScript code:

```javascript
document.querySelector('revo-grid').getPlugins().then(plugins => {
    const plugin = plugins.find(p => p instanceof RowTransposePlugin);
    plugin?.transpose();
});
```

When the rows are transposed, RevoGrid enters a virtual transposed mode. This means that events related to row and column edits will return instances of the `TransposedRow` class, which represent the transposed data model. If you wish to retrieve the original model, you can use the `TransposedRow.getOriginalModels` method. This method takes transposed column properties as input and converts the corresponding transposed cell back to the original model.

For example:

```javascript
document.querySelector('revo-grid').addEventListener('beforeedit', async (e) => {
    const model = e.detail.model;
    console.log('beforeedit', model.getOriginalModels([e.detail.prop])); // returns original row model
});
```

### Customizing the Transpose

The plugin configuration allows you to fine-tune the transposing process. For example, you can choose to transpose the column headers into rows, or leave them unchanged.

```javascript
document.querySelector('revo-grid').additionalData = {
  transpose: {
    transposedRowHeader: { cellTemplate: () => '', columnTemplate: () => '' }, // defined row/header template
    transposedColumnHeader: { columnTemplate: () => '' }, // template for transposed columns
  }
};
```

## Conclusion

The **Row Transpose Plugin** is a powerful tool for displaying data in different formats within RevoGrid.
Whether you're working with complex datasets that require pivoting or simply need to view your data from a different perspective, this plugin provides the flexibility to switch between views seamlessly. With customizable options for how rows and columns are transposed, you can easily tailor the grid to your needs.

---

# Selection & Focus

URL: https://pro.rv-grid.com/guides/selection/
Source: src/content/docs/guides/selection/index.mdx
Description: Install the complete RevoGrid Pro selection suite with one plugin.

`SelectionPlugin` is the master entry point for spreadsheet-style selection in
RevoGrid Pro. It composes the compatible cell, row, and column selection
runtimes while keeping their existing events, configuration, and public methods
available.

## Quick setup

```ts
import {
  SelectionPlugin,
  rowHeaders,
} from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');

grid.range = true;
grid.rowHeaders = rowHeaders({ showHeaderFocusBtn: false });
grid.columns = [
  { prop: 'selected', name: '', size: 52, rowSelect: true },
  { prop: 'name', name: 'Name' },
  { prop: 'team', name: 'Team' },
];
grid.plugins = [SelectionPlugin];
```

One registration enables Ctrl/Cmd multi-range selection, whole-row selection
from row headers, whole-column selection from column headers, checkbox row
selection for `rowSelect` columns, and optional range constraints.

## Included plugins

| Runtime | Responsibility | Activation/configuration |
| --- | --- | --- |
| `MultiRangeSelectionPlugin` | Disjoint cell ranges, shared range rendering, clipboard operations, and range edits | Set `grid.range = true` for range gestures; configure `grid.multiRangeSelection` when needed |
| `RowHeaderPlugin` | Excel-style whole-row selection and full-width row ranges | Configure `grid.rowHeaders` |
| `ColumnSelectionPlugin` | Whole-column selection from headers and keyboard shortcuts | Active when the suite is installed |
| `RowSelectPlugin` | Independent checkbox/programmatic row selection | Add `rowSelect: true` to a column; configure `grid.rowSelect` when needed |
| `RangeSelectionLimitPlugin` | Optional row-only or column-only interactive ranges | Disabled until `grid.rangeSelectionLimit` is set |

The suite installs these runtimes in dependency order and reuses any instance
that is already present. This is safe, although redundant:

```ts
grid.plugins = [SelectionPlugin, RowSelectPlugin];
// There is still only one RowSelectPlugin runtime.
```

Use individual plugins instead of `SelectionPlugin` when the application needs
only a smaller subset.

## Interaction ownership

The master plugin does not introduce another selection store. Each included
plugin remains the sole owner of its existing state:

- A plain cell click drops interactive row-header or column-header selection
  and focuses the clicked cell.
- Row-header and column-header selection hand off to each other, so both do not
  compete for the active full-width/full-height range.
- Ctrl/Cmd and Shift gestures continue to use the multi-range engine.
- Checkbox row selection stays independent from row-header selection. It keeps
  its own selected rows and `rowselected` events.
- Existing plugin methods are retrieved from the child runtime as before:

```ts
const plugins = await grid.getPlugins();
const ranges = plugins
  .find(plugin => plugin instanceof MultiRangeSelectionPlugin)
  ?.getSelectedRanges();
```

`AutoFillPlugin`, `AutoFillPreviewPlugin`, and `RangeCopyPreviewPlugin` are not
installed by `SelectionPlugin`. They own fill/copy editing previews rather than
selection state, and smart AutoFill preview versus exact-copy preview is an
intentional one-of choice. Add the preview behavior that matches the grid.

## Selection guides

    Select, edit, clear, and copy disjoint cell ranges.
    [Read the guide](./multi-range-selection/)

    Select, extend, and toggle complete columns.
    [Read the guide](./column-selection/)

    Configure checkbox rows and Excel-style row-header gestures.
    [Read the guide](./row-select/)

    Restrict interactive ranges to one row or one column.
    [Read the guide](./range-selection-limit/)

    Add the optional exact-copy drag preview.
    [Read the guide](./range-copy-preview/)

See the [`SelectionPlugin` API reference](/api/selection/) for the exported
class and dependency metadata.

---

# Column Selection

URL: https://pro.rv-grid.com/guides/selection/column-selection/
Source: src/content/docs/guides/selection/column-selection.mdx
Description: Column selection functionality.

Enable spreadsheet-style selection for complete visible columns. Header labels
select columns, while the dedicated sort and filter affordances keep their
normal behavior.

## User behavior

| Gesture | Result |
| --- | --- |
| Click a header | Replace the selection with that column |
| Shift-click | Select the contiguous span from the anchor column |
| Ctrl/Cmd-click | Toggle a disjoint column |
| Ctrl/Cmd+Shift-click | Add an anchored column span |
| Drag across headers | Select the dragged contiguous span |
| Ctrl/Cmd-drag | Add the dragged span |
| Ctrl+Space | Select the focused cell's entire column |
| Ctrl+Shift+Space | Extend from the column anchor to the focused column |
| Click a sort icon | Sort without changing the column selection |

The plugin reuses RevoGrid's multi-range selection engine, so copying, clearing,
and editing disjoint selected columns follow the same rules as ordinary
multi-range selections. Selections follow column `prop` values through sorting
and reordering and update to the current visible row extent after source or
filter changes.

## Events and programmatic access

`beforecolumnselection` is cancelable. Its detail describes the gesture source,
selection mode, target column, resulting column props, anchor, and original
pointer or keyboard event. Canceling it leaves the normal header action, such as
sorting a sortable column, available.

Use the plugin instance to read selected column props in visual order:

```ts
const plugin = (await grid.getPlugins())
  .find(plugin => plugin instanceof ColumnSelectionPlugin);

const selectedColumns = plugin?.getSelectedColumns();
```

<div hidden>

```javascript
// fixing render for multiframework
```

</div>

---

# Multi-Range Selection

URL: https://pro.rv-grid.com/guides/selection/multi-range-selection/
Source: src/content/docs/guides/selection/multi-range-selection.mdx
Description: Select, clear, and copy multiple disjoint RevoGrid ranges.

`MultiRangeSelectionPlugin` adds spreadsheet-style disjoint range selection while
leaving the native RevoGrid active range in charge of focus, Shift extension, and
editing.

Use it when users need to compare, clear, or copy multiple non-contiguous regions from the
same grid.

  Select a range, Ctrl/Cmd+click another cell, Shift+click to extend the new
  range, then copy. Plain-text clipboard output includes selected cells only, so
  paste does not clear gap cells between disjoint ranges.

## Usage

```ts
import { MultiRangeSelectionPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.range = true;
grid.plugins = [MultiRangeSelectionPlugin];
```

Cross-viewport autofill is enabled by default when this plugin is installed.
Users can drag the autofill handle between pinned and main row or column
viewports, and the committed result is stored as multiple selected ranges.
Disable only that drag integration with:

```ts
grid.multiRangeSelection = { crossViewportAutofill: false };
```

## User Behavior

1. Select a cell or range normally.
2. Ctrl/Cmd+click another cell to keep the previous range and start a new active range.
3. Shift+click or Shift+Arrow extends only the active range.
4. Tab and Enter move the focused cell inside the active range.
5. Delete and Backspace clear inactive ranges plus the active range.
6. Copy includes inactive ranges plus the active range.
7. Dragging the autofill handle across pinned/main viewport boundaries fills the visible target segments.
8. Plain click clears inactive ranges and starts a normal selection.

## Clipboard Shape

Multi-range copy preserves relative shape for nearby ranges in `text/plain`.
For example, diagonal selected cells are copied with blank cells between them so
external spreadsheets can keep the diagonal layout instead of stacking values
one after another. RevoGrid also writes a custom multi-range clipboard payload;
when the payload is pasted back into RevoGrid, only the selected cells are
edited, so the blank gaps do not clear existing destination values. Very large
sparse selections fall back to selected rectangular blocks to avoid huge
clipboard payloads. Rich `text/html` output mirrors the selected clipboard
shape.

Pinned and regular viewport coordinates are normalized into whole-grid visual
order before copy, so a pinned-left cell followed by the first regular cell is
copied as adjacent clipboard columns.

If only one range is selected, RevoGrid keeps its default copy behavior.

## Programmatic API

Call the public methods on the plugin instance:

```ts
const plugin = (await grid.getPlugins())
  .find(plugin => plugin instanceof MultiRangeSelectionPlugin);

plugin?.setSelectedRanges([
  { rowType: 'rgRow', colType: 'rgCol', range: { x: 0, y: 0, x1: 1, y1: 1 } },
  { rowType: 'rgRow', colType: 'rgCol', range: { x: 3, y: 0, x1: 3, y1: 1 } },
]);

const ranges = plugin?.getSelectedRanges();
plugin?.clearSelectedRanges();
```

The grid also dispatches `multirangeselectionchange` whenever the selected ranges
change.

## Rendering

Inactive cells receive:

- attribute: `multi-range-selection`
- class: `multi-range-selection-cell`
- edge classes for the range perimeter

The active range remains the native RevoGrid selection overlay.

---

# Range Copy Preview

URL: https://pro.rv-grid.com/guides/selection/range-copy-preview/
Source: src/content/docs/guides/selection/range-copy-preview.mdx
Description: Shows ghost values for the exact range copy that will be applied on drop.

`RangeCopyPreviewPlugin` shows the copied values that will be applied when a user
drags a selected range with the fill handle. It is a view-only companion plugin:
the data store is not changed until the existing drop-time range copy flow runs.

Use it when users need confidence that a drag will repeat the selected source
range exactly, without AutoFill sequence inference.

  Select the first two or three populated rows in the demo, drag the fill handle
  downward, and the empty target cells show ghost copied values before mouseup.

## Usage

```ts
import { RangeCopyPreviewPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.range = true;
grid.plugins = [RangeCopyPreviewPlugin];
```

The plugin uses the same core drag signal as range copy. It does not need
configuration for the default behavior.

## User Behavior

1. Select a source cell or range.
2. Drag the fill handle to a larger target range.
3. Target cells show the exact copied values in a ghost style.
4. Source cells remain visually unchanged.
5. Release the mouse to apply the core range copy.

If the temporary range is cleared, the source changes, or the plugin is destroyed,
the preview is removed immediately.

## Difference From AutoFill Preview

`AutoFillPreviewPlugin` previews smart sequence output from `AutoFillPlugin`, such
as `1, 2` becoming `3, 4` or `Mon, Tue` becoming `Wed`.

`RangeCopyPreviewPlugin` previews exact range copy output:

```txt
Draft, Approved -> Draft, Approved, Draft, Approved
North, West -> North, West, North, West
```

Use one preview plugin at a time for this drag surface:

| Plugin | Preview intent |
| --- | --- |
| `AutoFillPreviewPlugin` | Show predicted smart AutoFill sequence values. |
| `RangeCopyPreviewPlugin` | Show exact copied source values. |

## Rendering

Preview cells receive:

- attribute: `range-copy-preview`
- class: `range-copy-preview-cell`

Default styling uses reduced opacity and italic text so users can distinguish
preview values from committed data.

```css
.range-copy-preview-cell {
  opacity: 0.45;
  font-style: italic;
}
```

## Notes

The plugin does not mutate `source`, `newData`, or provider stores. It only
overrides the render model during `beforecellrender`, then refreshes affected row
types in a frame batch.

---

# Range Selection Limit

URL: https://pro.rv-grid.com/guides/selection/range-selection-limit/
Source: src/content/docs/guides/selection/range-selection-limit.mdx
Description: Restrict interactive range selection to a single row or column.

`RangeSelectionLimitPlugin` keeps user-created range selections in one dimension.
Use it when a workflow accepts row-only or column-only bulk actions and should not
allow rectangular selections.

The plugin does not replace RevoGrid selection. It intercepts the pending range
at the `beforeapplyrange` lifecycle point, constrains the shape, and then lets the
normal `setrange` flow continue.

## Usage

```ts
import { RangeSelectionLimitPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.range = true;
grid.plugins = [RangeSelectionLimitPlugin];
grid.rangeSelectionLimit = { mode: 'column' };
```

`grid.range = true` is still required because this plugin only constrains range
selection after core range selection is enabled.

## Modes

| Mode | Behavior | Typical use |
| --- | --- | --- |
| `column` | Keeps the focused column fixed and expands only across rows. | Select multiple rows for one field. |
| `row` | Keeps the focused row fixed and expands only across columns. | Select multiple fields for one row. |

### Column Mode

`column` keeps the focused column fixed and allows the selection to expand
vertically:

```ts
grid.rangeSelectionLimit = { mode: 'column' };
```

If the user starts on column `status` and drags diagonally, the selected range
stays inside `status` while the row bounds change.

### Row Mode

`row` keeps the focused row fixed and allows the selection to expand
horizontally:

```ts
grid.rangeSelectionLimit = { mode: 'row' };
```

If the user starts on row `12` and drags diagonally, the selected range stays on
row `12` while the column bounds change.

## Configuration Forms

Boolean shorthand is supported:

```ts
grid.rangeSelectionLimit = true;  // same as { mode: 'column' }
grid.rangeSelectionLimit = false; // disabled
```

String shorthand is also supported:

```ts
grid.rangeSelectionLimit = 'column';
grid.rangeSelectionLimit = 'row';
```

The object form is preferred for new code because it leaves room for future
options:

```ts
grid.rangeSelectionLimit = {
  mode: 'column',
};
```

For legacy integrations, the plugin also reads `additionalData.rangeSelectionLimit`,
but direct `grid.rangeSelectionLimit` configuration is preferred.

```ts
grid.additionalData = {
  rangeSelectionLimit: {
    mode: 'row',
  },
};
```

## Lifecycle

The plugin uses the existing RevoGrid range lifecycle:

1. RevoGrid computes the pending range from focus and drag/keyboard input.
2. `beforeapplyrange` is emitted by the overlay selection component.
3. `RangeSelectionLimitPlugin` replaces `event.detail.range` with the constrained range.
4. RevoGrid transforms that range to row/column data and emits `beforesetrange`.
5. RevoGrid emits `setrange`, and the selection store receives the constrained range.

The plugin does not add render layers, change data, or override single-cell
focus. If there is no focused cell, it uses the pending range start as the anchor.

## API

```ts
export type RangeSelectionLimitMode = 'column' | 'row';

export type RangeSelectionLimitOptions = {
  mode: RangeSelectionLimitMode;
};

export type RangeSelectionLimitConfig =
  | boolean
  | RangeSelectionLimitMode
  | RangeSelectionLimitOptions;
```

## Future Shape Validation

Arbitrary shape validation should be added as a separate mode or validator API so
the existing `row` and `column` modes keep their current behavior.

---

# Row Selection

URL: https://pro.rv-grid.com/guides/selection/row-select/
Source: src/content/docs/guides/selection/row-select.mdx
Description: Row selection in grid

Apply selection to rows in grid.

This is an advanced feature that allows users to select multiple rows in grid and explains how to implement this with the help of the `RowSelectPlugin`.

It is an extremely **powerful and flexible feature**, despite its straightforward functionality.

1. **Handles Complex Edge Cases**: The selection plugin is built to support **extreme edge case scenarios**, ensuring it remains reliable and performant in even the most challenging use cases.

2. **Efficient Redraw Management**: Plugin provides **better control** over the selection updates, boosting **performance** and responsiveness for large datasets. Also it doesn't modify original data set.

3. **Visual Feedback with Highlighted Rows**: The plugin highlights **selected rows** and applies relevant CSS classes, providing **instant visual feedback** to users, making the grid more interactive and intuitive.

4. **Bulk Selection Support**: The plugin simplifies bulk operations by enabling **select all** functionality, allowing users to select and manipulate **multiple rows** at once.

5. **Event-Driven Row Selection**: The plugin emits a `rowselected` event whenever a row is selected, enabling easy collection of **selected rows** and providing flexibility for further actions.

6. **Interaction with Other Features**: The plugin works smoothly with **filtering, sorting, grouping, tree data, and drag-and-drop**, allowing users to **select rows** while still interacting with other grid features without interference.

7. **Advanced Plugin Example**: The `RowSelectPlugin` serves as an **advanced example** of how to create sophisticated, flexible grid plugins, demonstrating how to implement custom solutions for specific needs.

8. **Foundation for Future Plugins**: The plugin sets a strong **foundation** for building more advanced system features, providing a **reusable and extensible pattern** for other interactive grid-based plugins.

- **Row Selection**: Allows users to select multiple rows in the grid.
- **Column Selection**: Enables users to select entire columns.
- **Grouped Row Selection**: Can render optional group-level checkboxes that select all descendant data rows.
- **Checkbox-Based Row Reorder**: Can hand checkbox-selected rows to `RowOrderPlugin` so checked rows drag as one compact block.
- **Automatic Theme Support**: The plugin adapts to light or dark themes based on user settings.
- **Flexible and Extensible**: This plugin demonstrates the potential for creating custom plugins, encouraging developers to expand the grid's functionality further.

To enable the `RowSelectPlugin` in your RevoGrid setup, you have two options:
1. **Using `rowSelect` Prop in Columns**
2. **Using `columnType` with `RowSelectColumnType`**

## Option 1: Using `rowSelect` Prop in Columns
In this approach, the rowSelect property in the column definition enables checkbox-based row selection for the specific column.

```typescript
  grid.columns = [
    {
      prop: '_check',
      rowSelect: true,
    },
    ...
  ];
  // Define plugin
  grid.plugins = [RowSelectPlugin];
```

## Option 2: Using columnType with RowSelectColumnType
Alternatively, you can use a custom columnType and the RowSelectColumnType to enable row selection.

```typescript
import { RowSelectColumnType, RowSelectPlugin, DEFAULT_SEL_PROP } from '@revolist/revogrid-pro';

grid.source = [];
// Define columns
grid.columns = [{
    prop: DEFAULT_SEL_PROP,
    columnType: 'select' // Use columnType 'select'
}, ...];
// Define plugin
grid.plugins = [RowSelectPlugin];
// Define the custom column type for selection
grid.columnTypes = { select: new RowSelectColumnType()};
```

## Pointer And Keyboard Gestures

Checkboxes and row headers are independent selection modes. Checkbox state,
anchors, programmatic selection, and `rowselected` events remain owned by
`RowSelectPlugin`. Spreadsheet-style row-header state and anchors remain owned
by `RowHeaderPlugin`, so using one mode never replaces or toggles the other.
Row-header selections are also exposed as full-width multi-ranges, allowing
copy, Delete, and other range operations to act on every selected row. Delete
and Backspace clear editable cells across pinned and regular column sections;
readonly cells and values rejected by strict column validation remain unchanged:

| Gesture | Result |
| --- | --- |
| Click a row checkbox | Toggle that row without clearing other checked rows |
| Click the row-header number, surrounding area, or drag handle | Replace selection and focus the whole row |
| Click an ordinary cell after row-header or row-header drag-handle selection | Clear the row selection and focus the cell |
| Ctrl-click / Cmd-click an ordinary cell after row-header selection | Keep the row selection and add the cell selection |
| Shift-click an ordinary cell after row-header selection | Keep the row selection while extending the active cell range |
| Ctrl-click / Cmd-click a row header | Toggle one row and preserve the other selected rows |
| Shift-click a row header | Select the visible range from the selection anchor |
| Ctrl/Cmd+Shift-click a row header | Add the anchored visible range |
| Space on a focused row-selection checkbox | Toggle that row |

Selections are stored against source rows. Sorting, filtering, and virtual
scrolling do not convert them into rendered viewport positions. A selected row
therefore remains selected while it is outside the viewport or temporarily
hidden by a filter.

## Grouped Row Selection

Grouped row checkboxes are opt-in so existing grouped grids keep their current rendering.

```typescript
grid.columns = [
  { prop: 'selected', rowSelect: true },
  { prop: 'name', name: 'Name' },
  { prop: 'department', name: 'Department' },
];

grid.grouping = { props: ['department'], expandedAll: true };
grid.rowSelect = {
  grouping: true,
};
grid.plugins = [RowSelectPlugin];
```

You can also use the future-compatible object form:

```typescript
grid.rowSelect = {
  grouping: {
    enabled: true,
  },
};
```

When enabled, selecting a group checkbox selects all descendant data rows. Selecting only part of a group reflects an indeterminate state on the group checkbox. Synthetic grouping rows are not included in selected row counts.

## Checkbox-Based Row Reorder

`RowSelectPlugin` can opt into `RowOrderPlugin` integration. When enabled, dragging a checked row moves all visible checked data rows in the current row viewport as a compact block.

This feature is disabled by default. Existing row-order behavior is unchanged unless `rowSelect.rowOrder` is enabled.

```typescript
import { RowOrderPlugin, RowSelectPlugin } from '@revolist/revogrid-pro';

grid.columns = [
  { prop: 'drag', name: '', rowDrag: true, size: 42 },
  { prop: 'selected', name: '', rowSelect: true, size: 56 },
  { prop: 'name', name: 'Name' },
  { prop: 'team', name: 'Team' },
];

grid.rowSelect = {
  rowOrder: true,
};
grid.rowOrder = {
  prop: 'name',
  preview: 'compact',
};
grid.plugins = [RowSelectPlugin, RowOrderPlugin];
```

You can also use the object form:

```typescript
grid.rowSelect = {
  rowOrder: {
    enabled: true,
  },
};
```

Checkbox selection takes priority over range selection only when the dragged row is checked. If the dragged row is not checked, `RowOrderPlugin` falls back to its current range-selection or single-row behavior.

Only visible checked data rows move during the drag. Rows hidden by filtering, collapsed grouping, or collapsed tree branches remain selected but are not part of that drag operation. Synthetic grouping rows are never moved as selected data rows.

## Grouping And Row Reorder Together

Grouped row checkboxes and checkbox-based row reorder can be enabled together:

```typescript
grid.grouping = { props: ['team'], expandedAll: true };
grid.rowSelect = {
  grouping: true,
  rowOrder: true,
};
grid.rowOrder = {
  prop: 'name',
  preview: 'compact',
};
grid.plugins = [RowSelectPlugin, RowOrderPlugin];
```

With this setup:

- Group checkboxes select or clear all descendant data rows.
- Dragging a checked child row moves visible checked child rows as a compact block.
- Parent and ancestor group checkboxes reflect child selection with checked or indeterminate state.
- Group headers are excluded from select-all counts and row-order moved items.
- Row-order grouping validation still applies, so invalid cross-group drops remain blocked unless your row-order configuration explicitly allows applying target group values.

## Filtering, Sorting, Row Drag, And Tree Data

Row selection is stored against real data row indexes, not the rendered row position. This keeps checkbox state stable when the visible row topology changes.

| Case | Behavior |
| --- | --- |
| Filtering | Selected hidden rows remain selected. The `rowselected` event is re-emitted so `visibleCount` and `visibleRowsCount` reflect the filtered view. |
| Sorting | Checkbox state follows the same data rows after sort order changes. |
| Row drag | Checkbox state follows moved data rows after row order changes. |
| Checkbox row-order | When `rowSelect.rowOrder` is enabled, visible checked rows are moved as a compact block before range selection is considered. |
| Grouping | Group checkboxes are opt-in through `rowSelect.grouping`; synthetic group rows are not counted as selected rows. |
| Tree data | When `TreeDataPlugin` is registered, selecting a tree parent toggles the parent and descendants. Dragging a checkbox-selected tree parent with descendants preserves the subtree relationship. |

## API Quick Reference

| API | Default | Meaning |
| --- | --- | --- |
| `ColumnRegular.rowSelect` | `false` | Renders row-selection checkboxes in normal data cells for that column. A predicate can hide checkboxes for specific cells. |
| `grid.rowSelect.grouping` | `false` | Enables group-level row-selection checkboxes. Accepts `true` or `{ enabled: true }`. |
| `grid.rowSelect.rowOrder` | `false` | Enables checkbox-selected row drag integration with `RowOrderPlugin`. Accepts `true` or `{ enabled: true }`. |
| `additionalData.rowSelect` | none | Legacy alias for `grid.rowSelect`. Prefer direct `grid.rowSelect`. |

The `rowselected` event exposes totals for both all selectable rows and the currently visible selectable rows:

| Event field | Meaning |
| --- | --- |
| `count` | Selected real data rows across the full dataset. |
| `allRowsCount` | Selectable real data rows across the full dataset. |
| `visibleCount` | Selected real data rows currently visible. |
| `visibleRowsCount` | Selectable real data rows currently visible. |

## Bulk Row Selection Demo

The live demo on this page is the common **Bulk Row Selection** example. It includes flat, grouped, and tree modes, a row checkbox column, row drag handles, group checkbox selection, filtering, sorting, selected/visible totals, and opt-in checkbox-based row reorder.

---

# Server-side Row Grouping

URL: https://pro.rv-grid.com/guides/server-side-grouping/
Source: src/content/docs/guides/server-side-grouping.mdx
Description: Group, expand, and lazy-load millions of rows without loading the full dataset into the browser.

Server-side row grouping for large datasets lets RevoGrid render grouped data from a backend route API. The browser keeps only visible grouped blocks and cached route blocks, while your server owns grouping, sorting, filtering, quick filtering, counts, and aggregates.

Use it for ERP, financial analytics, logs, operations, and reporting tools where a complete client-side dataset is too large.

- Group by one or multiple columns.
- Lazy-load group children on expand.
- Works with server-side Infinity Scroll semantics.
- Supports unknown row counts.
- Keeps browser memory low with block caching.
- Sends sort, filter, quick-filter, and group state to your backend.

## Setup

```ts
import { ServerSideGroupingPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');

grid.serverSideGrouping = {
  groupBy: ['country', 'sport'],
  loadRows: async (request, signal) => {
    const response = await fetch('/api/grid/grouping', {
      method: 'POST',
      signal,
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(request),
    });
    return response.json();
  },
};

grid.plugins = [ServerSideGroupingPlugin];
```

`groupBy` and `loadRows` are the only required options. The full configuration can add request tuning, a quick-filter payload, an imperative plugin controller, and an optimized expand-all datasource:

```ts
let groupingPluginControllerApi;

grid.serverSideGrouping = {
  groupBy: ['country', 'sport'],
  blockSize: 100,
  purgeClosedGroups: false,
  maxConcurrentRequests: 4,
  blockLoadDebounceMs: 25,
  quickFilter: { text: '' },
  api: api => {
    groupingPluginControllerApi = api;
  },
  loadRows,
  loadExpandedGroups: async (request, signal) => {
    const response = await fetch('/api/grid/grouping/expand-all', {
      method: 'POST',
      signal,
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(request),
    });
    return response.json();
  },
};
```

`api` is not a server endpoint. It is a callback that gives the application an imperative controller after the plugin is initialized. Use it from toolbar buttons, route changes, or refresh actions:

```ts
groupingPluginControllerApi?.refreshServerSide();
groupingPluginControllerApi?.expandGroup(['Germany']);
groupingPluginControllerApi?.purgeServerSideCache();
```

`loadRows` is the required server datasource. It loads one route block at a time: root groups, child groups, or final leaf rows. `loadExpandedGroups` is optional and only optimizes `expandAllGroups()` by letting the backend return a flattened group tree in one request.

When `AdvanceFilterPlugin` is active, assigning `grid.quickFilter` refreshes the grouped datasource and forwards normalized `{ text, columns? }` data in every request. An explicitly assigned grid-level quick filter takes precedence over `serverSideGrouping.quickFilter`, including an explicit empty value used to clear search. The config value remains the fallback until the grid-level property is assigned.

The plugin owns the main row source while active. `InfinityScrollPlugin` is complementary in behavior and request shape, but should not also own the same `rgRow` source. If both plugins are registered and `serverSideGrouping` is configured, Infinity Scroll no-ops with a warning.

When combining server-side grouping with selection filters, provide `filter.selection.getItems` from the same backing datasource used by your server loader. The grid source contains generated group rows and only the currently loaded route blocks, so deriving selection options from the visible grid source can produce incomplete values such as only `Empty`.

## Request Contract

`loadRows(request, signal)` receives:

```ts
{
  route: ['Germany'],
  level: 1,
  groupBy: ['country', 'sport'],
  start: 0,
  limit: 100,
  sort: { revenue: 'desc' },
  filter: { country: { type: 'contains', value: 'Ger' } },
  quickFilter: { text: 'premium' },
  parent: { key: 'Germany', count: 12450 },
  levelParams: { tenantId: 'acme' }
}
```

Return group rows before the final grouping level:

```ts
{
  groups: [
    { key: 'Swimming', count: 2100, aggregates: { Revenue: 'EUR 9.2M' } },
    { key: 'Cycling', count: 1540 }
  ],
  rowCount: 2,
  grandTotals: { Revenue: 'EUR 18.7M' }
}
```

Return leaf rows at the final level:

```ts
{
  rows: [
    { id: 1, country: 'Germany', sport: 'Swimming', city: 'Berlin', revenue: 1200 }
  ],
  rowCount: 2100,
  hasMore: true
}
```

When `rowCount` is omitted, RevoGrid treats the count as unknown and keeps a loading tail while `hasMore` is true.

## Runtime API

The API is exposed through the config callback, not by mutating the grid instance.

```ts
grid.serverSideGrouping = {
  groupBy: ['country'],
  loadRows,
  api: api => {
    groupingPluginControllerApi = api;
    groupingPluginControllerApi?.expandGroup(['Germany']);
    groupingPluginControllerApi?.expandAllGroups();
    groupingPluginControllerApi?.refreshRoute(['Germany']);
    groupingPluginControllerApi?.purgeServerSideCache();
    console.log(groupingPluginControllerApi?.getServerSideCacheState());
  },
};
```

Available methods:

| Method | Description |
|---|---|
| `expandGroup(id)` | Expands and lazy-loads a group route. |
| `expandAllGroups()` | Loads group blocks recursively and expands every server group route. Leaf-row blocks still load from the viewport. |
| `collapseGroup(id)` | Collapses a group route. |
| `collapseAllGroups()` | Collapses all group routes currently known by the cache. |
| `refreshServerSide()` | Invalidates all route blocks and reloads root. |
| `refreshRoute(route)` | Invalidates only one route branch when possible. |
| `purgeServerSideCache(route?)` | Clears all cache or one route branch. |
| `getServerSideCacheState()` | Returns debug route, block, loading, and queue state. |

`expandAllGroups()` opens every group route. It does not load every leaf row, so large final groups stay virtualized and fetch visible row blocks through the normal server-side scroll path.

When `loadExpandedGroups` is configured, `expandAllGroups()` uses that single endpoint instead of recursively loading route blocks:

```ts
grid.serverSideGrouping = {
  groupBy: ['country', 'sport'],
  loadRows,
  loadExpandedGroups: async request => ({
    groups: [
      { route: ['Germany'], key: 'Germany', count: 12450 },
      { route: ['Germany', 'Swimming'], key: 'Swimming', count: 2100 },
      { route: ['Germany', 'Cycling'], key: 'Cycling', count: 1540 },
    ],
  }),
};
```

Each returned group row must include its full `route`. The plugin rebuilds group route blocks from this flattened tree and keeps leaf-row blocks unloaded until they enter the viewport.

## Configuration

| Option | Default | Description |
|---|---:|---|
| `groupBy` | required | Grouping column props in server route order. |
| `blockSize` | `100` | Direct children requested per block. |
| `purgeClosedGroups` | `false` | Purge child route cache on collapse. |
| `maxConcurrentRequests` | `4` | Limits simultaneous route block requests. |
| `blockLoadDebounceMs` | `0` | Delays block load dispatch after scroll/materialization. |
| `quickFilter` | `undefined` | Global filter payload forwarded to the server. |
| `api` | `undefined` | Receives the client-side plugin controller. This is not a server request callback. |
| `loadRows` | required | Server datasource for root groups, nested group routes, and final leaf rows. |
| `loadExpandedGroups` | `undefined` | Optional one-request expand-all endpoint that returns flattened group rows with routes. |

---

# Cell Validation with Renderers

URL: https://pro.rv-grid.com/guides/validate-basic/
Source: src/content/docs/guides/validate-basic.mdx
Description: Explore different methods for validating cell data in RevoGrid and ensuring data integrity.

One straightforward way to validate cell data is by combining `validate`, `validationTooltip`, and `validationRenderer`.
This marks invalid cells during rendering without changing edit behavior, which is useful for audits, imported data review, and soft warnings.

```ts
import { validationRenderer } from '@revolist/revogrid-pro';

const columns = [
  {
    prop: 'price',
    name: 'Price',
    validate: (value, row) => value >= row.floor && value <= row.ceiling,
    validationTooltip: (value, row) =>
      `Price ${value} must stay between ${row.floor} and ${row.ceiling}`,
    ...validationRenderer({
      severity: 'error',
      indicatorPlacement: 'corner',
      messagePlacement: 'tooltip',
    }),
  },
];
```

`validationRenderer` returns `cellProperties` and `cellTemplate`, so it can wrap your existing cell renderer while keeping validation styling in one place.
The helper supports:

- `severity`: `error`, `warning`, or `info`.
- `indicatorPlacement`: `corner`, `start`, `end`, or `none`.
- `messagePlacement`: `tooltip`, `inline`, `both`, or `none`.
- `message`: a custom message resolver when `validationTooltip` is not enough.
- `invalidProperties`: extra cell properties for invalid cells.

`messagePlacement` controls where the validation message is exposed:

- `tooltip` adds `title` and tooltip data attributes.
- `inline` renders the message inside the cell without tooltip attributes.
- `both` renders inline text and tooltip attributes.
- `none` keeps the visual indicator but hides the message text.

:::note
This renderer-only approach shows invalid data already present in the grid. To prevent invalid edits from being committed, use `CellValidatePlugin` from the input validation guide.
:::

---

# Validate user data input

URL: https://pro.rv-grid.com/guides/validate-input/
Source: src/content/docs/guides/validate-input.mdx
Description: Explore strict and soft cell validation for spreadsheet-style data entry.

This demo exposes the rules as controls. Try strict mode to reject invalid edits, soft mode to save invalid data with markers, and the seed/reset actions to simulate cleanup workflows.

The **CellValidatePlugin** validates edits before they are written to the grid source. Use it when the grid should enforce spreadsheet-style rules such as required fields, numeric ranges, enum membership, cross-field limits, and approval gates.

Install it together with **EventManagerPlugin** so edit events are collected through the Pro event pipeline:

```ts
import {
  CellValidatePlugin,
  EventManagerPlugin,
} from '@revolist/revogrid-pro';

grid.plugins = [
  EventManagerPlugin,
  CellValidatePlugin,
];

grid.eventManager = {
  applyEventsToSource: true,
};
```

:::note
`EventManagerPlugin` should be registered before `CellValidatePlugin`. Validation resolves inside the event manager's pre-commit phase, so normal `gridedit` consumers such as history, audit, flash, and collaboration observe only the accepted patch.
:::

## Clipboard validation resolution

Clipboard paste is atomic by default: one strict validation failure rejects the complete paste. Opt into `valid-cells` when valid destinations should be applied while invalid destinations keep their previous values and validation feedback:

```ts
grid.useClipboard = {
  validationResolution: 'valid-cells',
};
```

The policy applies to standard keyboard paste, multi-range/cross-viewport paste, and context-menu paste. It does not change ordinary edits, autofill, readonly filtering, or soft validation. The accepted cells remain one edit transaction, so Undo restores them together without touching rejected destinations.

## Strict and soft validation

By default validation is strict. If `validate(value, model)` returns `false`, the edit is rejected and the source keeps the previous value.

```ts
const columns: ColumnRegular[] = [
  {
    name: 'Price',
    prop: 'price',
    validate: (value, model) => {
      const price = Number(value);
      return Number.isFinite(price) && price >= 50 && price <= 1200;
    },
    validationTooltip: (value) =>
      `Price ${value} must be between 50 and 1200`,
  },
];
```

Set `softValidation: true` when invalid values should still be saved and marked visually. This is useful for imported data cleanup flows where users need to see and fix invalid rows in place. Pair it with `validationRenderer` when you want saved invalid values to stay visible after the edit.

```ts
{
  prop: 'discount',
  softValidation: true,
  ...validationRenderer(),
  validate: (value, model) => Number(value) <= Number(model.price) * 0.3,
  validationTooltip: (value, model) =>
    `Discount cannot exceed 30% of price (${Math.round(Number(model.price) * 0.3)})`,
}
```

## Candidate row model

Both `validate(value, model)` and `validationTooltip(value, model)` receive the row model. During strict edit validation, the model includes the pending row patch, so cross-field validation works for single edits and pasted batches. If the edit is rejected, the tooltip renderer receives the rejected value and candidate model, which lets the message explain what failed even though the source was not changed.

```ts
{
  name: 'Approved',
  prop: 'approved',
  validate: (value, model) => {
    const netPrice = Number(model.price) - Number(model.discount ?? 0);
    return netPrice <= 900 || value === true;
  },
  validationTooltip: () => 'High-value rows require approval',
}
```

`validationTooltip` also receives the column as a third argument: `validationTooltip(value, model, column)`. Use that when one shared message resolver needs column metadata.

## Cross-column example

The validation function can also block a cell based on another column in the same row. This example prevents fees on expired services.

---

# Aggregations

URL: https://pro.rv-grid.com/api/aggregations/
Source: src/content/docs/api/aggregations.md

### `commonAggregators`

Defines a collection of common aggregation functions used for table calculations.
These aggregators transform an array of numerical values into meaningful statistical summaries.

```ts
commonAggregators: {
  sum: (values: any[]) => any;
  count: (values: any[]) => number;
  avg: (values: any[]) => number;
  min: (values: any[]) => number;
  max: (values: any[]) => number;
  median: (values: any[]) => number;
  mode: (values: any[]) => string | 0;
  range: (values: any[]) => number;
  variance: (values: any[]) => number;
  stdDev: (values: any[]) => number;
  first: (values: any[]) => any;
  last: (values: any[]) => any;
  distinct: (values: any[]) => number;
};
```

---

### `advancedAggregators`

```ts
advancedAggregators: {
  '%oftotal': (values: any[]) => number[];
  accSum: (values: any[]) => any;
};
```

---

### `Aggregations`

```ts
export type Aggregations = Record<AggregationType, (values: any[]) => any>;
```

---

# Array Renderer

URL: https://pro.rv-grid.com/api/array-renderer/
Source: src/content/docs/api/array-renderer.md

### `arrayRenderer`

The `arrayRenderer` is a custom cell renderer for RevoGrid that can handle both single values
and arrays of values. It applies different renderers based on the value type.

**Features**:
- Detects if the value is an array or a single value
- For arrays, renders multiple elements using the provided renderer
- For single values, renders a single element using the provided renderer
- Supports custom separator between array items
- Supports custom wrapper for array items

**Usage**:
- Import `arrayRenderer` and use it as a wrapper around your existing renderer
- Configure the renderer with options like separator and wrapper

### Example
```typescript
import { arrayRenderer } from '@revolist/revogrid-pro';
import { linkRenderer } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'links',
    name: 'Links',
    cellTemplate: arrayRenderer(linkRenderer, {
      separator: ', ',
      wrapper: 'div',
    }),
  },
];
```

Example of using multiRenderer to handle different types of values

  prop: 'data',
  name: 'Data',
  cellTemplate: multiRenderer({
    default: progressLineRenderer,
    renderers: [
      {
        // Use linkRenderer for URLs
        condition: (value) => typeof value === 'string' &&
          (value.startsWith('http://') || value.startsWith('https://')),
        renderer: linkRenderer,
      },
      {
        // Use progressLineRenderer for numbers
        condition: (value) => typeof value === 'number',
        renderer: progressLineRenderer,
      },
    ],
    separator: ' | ',
    wrapper: 'div',
    wrapperClass: 'multi-data-container',
  }),
};

```ts
export function arrayRenderer(
  renderer: ColumnRegular['cellTemplate'],
  options: ArrayRendererOptions = {}): Required<ColumnRegular>['cellTemplate'];
```

---

### `multiRenderer`

The `multiRenderer` is a custom cell renderer for RevoGrid that can apply different renderers
based on the value type. It's similar to `arrayRenderer` but allows for more complex rendering logic.

**Features**:
- Detects if the value is an array or a single value
- For arrays, applies a different renderer for each item based on a condition
- For single values, applies a default renderer
- Supports custom separator between array items
- Supports custom wrapper for array items

**Usage**:
- Import `multiRenderer` and use it to define different renderers for different value types
- Configure the renderer with options like separator and wrapper

### Example
```typescript
import { multiRenderer } from '@revolist/revogrid-pro';
import { linkRenderer } from '@revolist/revogrid-pro';
import { progressLineRenderer } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'data',
    name: 'Data',
    cellTemplate: multiRenderer({
      default: progressLineRenderer,
      renderers: [
        {
          condition: (value) => typeof value === 'string' && value.startsWith('http'),
          renderer: linkRenderer,
        },
      ],
    }),
  },
];
```

```ts
export function multiRenderer(config: {
  /**
   * Default renderer to use if no condition matches
   */
  default: ColumnRegular['cellTemplate'];

  /**
   * Array of renderers with conditions
   */
  renderers: Array<{
    /**
     * Condition function that returns true if the renderer should be used
     */
    condition: (value: any) => boolean;

    /**
     * Renderer to use if the condition is true
     */
    renderer: ColumnRegular['cellTemplate'];
  }>;

  /**
   * Separator between array items
   * @default ', '
   */
  separator?: string;

  /**
   * Wrapper element for array items
   * @default 'div'
   */
  wrapper?: string;

  /**
   * CSS class for the wrapper element
   */
  wrapperClass?: string;

  /**
   * CSS style for the wrapper element
   */
  wrapperStyle?: Record<string, string>;
}): ColumnRegular['cellTemplate'];
```

---

### `ArrayRendererOptions`

```ts
export type ArrayRendererOptions = {
  /**
   * Separator between array items
   * @default ', '
   */
  separator?: string;

  /**
   * Wrapper element for array items
   * @default 'div'
   */
  wrapper?: string;

  /**
   * CSS class for the wrapper element
   */
  wrapperClass?: string;

  /**
   * CSS style for the wrapper element
   */
  wrapperStyle?: Record<string, string>;
};
```

---

# Audit History

URL: https://pro.rv-grid.com/api/audit-history/
Source: src/content/docs/api/audit-history.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  auditHistory?: AuditHistoryConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * @deprecated Use the direct `grid.auditHistory` property instead.
       */
      auditHistory?: AuditHistoryConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  auditrecord: AuditRecord;
  auditrecordsloaded: AuditRecord[];
  auditerror: AuditHistoryError;
  beforeauditrestore: AuditRestoreEvent;
  auditrestore: AuditRestoreEvent
}
```

## Plugin API

### `createLocalStorageAuditHistoryAdapter`

```ts
export function createLocalStorageAuditHistoryAdapter(storageKey = DEFAULT_STORAGE_KEY): AuditHistoryStorageAdapter;
```

---

### `AuditHistoryPlugin`

#### Dependencies

- **Required** `EventManagerPlugin`: Requires EventManagerPlugin to receive normalized edit and paste events.
- **Auto-installed** `HistoryPlugin`: Auto-installs or reuses HistoryPlugin for undo/redo shortcuts and replay integration.

```ts
class AuditHistoryPlugin {
  getRecords(filter?: AuditHistoryFilter): AuditRecord[];

  getCellHistory(rowId: string | number, column: ColumnProp): AuditRecord[];

  getRowHistory(rowId: string | number): AuditRecord[];

  getRecord(id: string): AuditRecord | undefined;

  getTransaction(transactionId: string): AuditRecord[];

  getLastChange(rowId: string | number, column?: ColumnProp): AuditChange | undefined;

  getStats(filter?: AuditHistoryFilter): AuditHistoryStats;

  getRowIdentity(row: DataType | undefined, rowIndex: number, rowType: DimensionRows): string | undefined;

  clear(): boolean;

  replaceRecords(records: AuditRecord[], options: { merge?: boolean; persist?: boolean } = {}): AuditRecord[];

  recordEvent(input: AuditRecordEventInput): AuditRecord | undefined;

  createSnapshot(label: string, options: AuditSnapshotOptions = {}): AuditRecord | undefined;

  restoreSnapshot(recordOrId: AuditRecord | string): boolean;

  async refreshRecords(options: { merge?: boolean } = { merge: true }): Promise<AuditRecord[]>;

  exportRecords(options: AuditHistoryExportOptions = {}): string;

  canRestoreRecord(context: AuditHistoryRestoreContext): boolean;

  restoreCell(change: AuditChange): boolean;

  restoreRow(recordOrRowId: AuditRecord | string | number): boolean;

  restoreTransaction(transactionId: string): boolean;
}
```

---

### `AuditUser`

```ts
export type AuditUser = {
  id: string;
  name?: string;
  email?: string;
};
```

---

### `BuiltInAuditActionType`

```ts
export type BuiltInAuditActionType =
  | 'cell-change'
  | 'bulk-paste'
  | 'row-added'
  | 'row-deleted'
  | 'row-restored'
  | 'undo'
  | 'redo'
  | 'restore-cell'
  | 'restore-row'
  | 'restore-transaction'
  | 'api-sync'
  | 'formula-update'
  | 'snapshot-created'
  | 'snapshot-restored';
```

---

### `AuditActionType`

```ts
export type AuditActionType = BuiltInAuditActionType | (string & {});
```

---

### `AuditHistorySource`

```ts
export type AuditHistorySource =
  | 'manual'
  | 'paste'
  | 'api'
  | 'formula'
  | 'restore'
  | 'snapshot'
  | 'system';
```

---

### `AuditRecordPresentation`

```ts
export type AuditRecordPresentation = {
  source?: AuditHistorySource;
  verb?: string;
  targetLabel?: string;
  detailLabel?: string;
  rangeLabel?: string;
  avatarLabel?: string;
  avatarIndex?: number;
  avatarColor?: string;
  accent?: boolean;
};
```

---

### `AuditChangePresentation`

```ts
export type AuditChangePresentation = {
  cellLabel?: string;
  columnLabel?: string;
};
```

---

### `AuditChange`

```ts
export type AuditChange = {
  id: string;
  rowId?: string;
  rowIndex?: number;
  rowType: DimensionRows;
  column?: ColumnProp;
  oldValue?: unknown;
  newValue?: unknown;
  oldRow?: DataType;
  newRow?: DataType;
  metadata?: Record<string, unknown>;
  presentation?: AuditChangePresentation;
};
```

---

### `AuditRecord`

```ts
export type AuditRecord = {
  id: string;
  transactionId: string;
  type: AuditActionType;
  changedAt: string;
  changedBy: AuditUser;
  changes: AuditChange[];
  metadata?: Record<string, unknown>;
  presentation?: AuditRecordPresentation;
};
```

---

### `AuditHistoryFilter`

```ts
export type AuditHistoryFilter = {
  rowId?: string | number;
  column?: ColumnProp;
  userId?: string;
  userEmail?: string;
  actionType?: AuditActionType;
  transactionId?: string;
  dateFrom?: string | Date;
  dateTo?: string | Date;
};
```

---

### `AuditHistoryStorageAdapter`

```ts
export type AuditHistoryStorageAdapter = {
  load?: () => AuditRecord[] | Promise<AuditRecord[]>;
  save?: (records: AuditRecord[]) => void | Promise<void>;
  append?: (record: AuditRecord, records: AuditRecord[]) => void | Promise<void>;
  clear?: () => void | Promise<void>;
};
```

---

### `AuditHistoryError`

```ts
export type AuditHistoryError = {
  phase:
    | 'get-current-user'
    | 'metadata'
    | 'sanitize'
    | 'storage-load'
    | 'storage-save'
    | 'storage-append'
    | 'storage-clear'
    | 'on-record'
    | 'restore'
    | 'export'
    | 'replace-records'
    | 'record-event'
    | 'track-record'
    | 'snapshot';
  error: unknown;
  record?: AuditRecord;
};
```

---

### `AuditHistoryRestoreContext`

```ts
export type AuditHistoryRestoreContext = {
  type: AuditRestoreType;
  record?: AuditRecord;
  change?: AuditChange;
  transactionId?: string;
};
```

---

### `AuditHistoryStats`

```ts
export type AuditHistoryStats = {
  totalRecords: number;
  totalChanges: number;
  firstChangedAt?: string;
  lastChangedAt?: string;
  byType: Partial<Record<AuditActionType, number>>;
  byUser: Record<string, number>;
};
```

---

### `AuditHistoryExportFormat`

```ts
export type AuditHistoryExportFormat = 'json' | 'csv';
```

---

### `AuditHistoryExportOptions`

```ts
export type AuditHistoryExportOptions = {
  format?: AuditHistoryExportFormat;
  filter?: AuditHistoryFilter;
  includeMetadata?: boolean;
};
```

---

### `AuditRecordTrackContext`

```ts
export type AuditRecordTrackContext = {
  type: AuditActionType;
  changes: AuditChange[];
  source?: AuditHistorySource;
  metadata?: Record<string, unknown>;
  record: AuditRecord;
  event?: unknown;
};
```

---

### `AuditHistoryConfig`

```ts
export type AuditHistoryConfig = {
  getCurrentUser?: () => AuditUser;
  getMetadata?: (context: { type: AuditActionType; changes: AuditChange[] }) => Record<string, unknown> | undefined;
  rowIdProp?: string;
  getRowId?: (
    row: DataType,
    context: { rowIndex: number; rowType: DimensionRows },
  ) => string | number | undefined;
  sanitizeValue?: (
    value: unknown,
    context: {
      rowId?: string;
      rowIndex?: number;
      rowType: DimensionRows;
      column?: ColumnProp;
      direction: 'old' | 'new';
    },
  ) => unknown;
  shouldTrackChange?: (
    change: Omit<AuditChange, 'id'>,
    context: { type: AuditActionType },
  ) => boolean;
  shouldTrackRecord?: (context: AuditRecordTrackContext) => boolean;
  trackedActionTypes?: AuditActionType[];
  ignoredActionTypes?: AuditActionType[];
  ignoredColumns?: ColumnProp[] | ((context: { column?: ColumnProp; rowType: DimensionRows; rowId?: string }) => boolean);
  captureSourceUpdates?: boolean;
  immutable?: boolean;
  canRestore?: (context: AuditHistoryRestoreContext) => boolean;
  storage?: 'memory' | 'localStorage' | 'custom';
  storageKey?: string;
  storageAdapter?: AuditHistoryStorageAdapter;
  storageProviders?: AuditHistoryStorageAdapter[];
  mergeStorageProviders?: boolean;
  records?: AuditRecord[];
  maxRecords?: number;
  disabled?: boolean;
  onAuditRecord?: (record: AuditRecord) => void | Promise<void>;
  onAuditError?: (error: AuditHistoryError) => void;
  onRecordsLoaded?: (records: AuditRecord[]) => void;
};
```

---

### `AuditEventChangeInput` (Extended from `index.ts`)

```ts
export type AuditEventChangeInput = Omit<AuditChange, 'id'> & { id?: string };
```

---

### `AuditRecordEventInput`

```ts
export type AuditRecordEventInput = {
  type: AuditActionType;
  changes?: AuditEventChangeInput[];
  changedAt?: string;
  changedBy?: AuditUser;
  transactionId?: string;
  metadata?: Record<string, unknown>;
  presentation?: AuditRecordPresentation;
  allowEmpty?: boolean;
};
```

---

### `AuditSnapshotOptions`

```ts
export type AuditSnapshotOptions = {
  rowType?: DimensionRows;
  rows?: DataType[];
  metadata?: Record<string, unknown>;
  presentation?: AuditRecordPresentation;
};
```

---

### `AuditRestoreType`

```ts
export type AuditRestoreType = 'cell' | 'row' | 'transaction' | 'snapshot';
```

---

### `AuditRestoreEvent`

```ts
export type AuditRestoreEvent = {
  type: AuditRestoreType;
  record?: AuditRecord;
  change?: AuditChange;
  transactionId?: string;
};
```

---

### `defineAuditHistoryPanel`

Renders the Audit History panel into `el` for the given RevoGrid element.

The grid must have `AuditHistoryPlugin` installed.

```ts
export function defineAuditHistoryPanel(el: HTMLElement, grid: HTMLRevoGridElement, options: AuditHistoryPanelOptions = {}): AuditHistoryPanelHandle;
```

---

### `AuditHistoryPanelDateFormatContext`

```ts
export type AuditHistoryPanelDateFormatContext = {
  mode: 'time' | 'day' | 'filter';
  record?: AuditRecord;
};
```

---

### `AuditHistoryPanelEvents`

```ts
export type AuditHistoryPanelEvents = {
  beforeRecordSelect?: (context: AuditHistoryPanelRecordContext) => boolean | void;
  beforeCompareOpen?: (context: AuditHistoryPanelRecordContext) => boolean | void;
  beforeJumpToCell?: (context: AuditHistoryPanelJumpContext) => boolean | void;
  beforeRestore?: (context: AuditHistoryPanelRestoreContext) => boolean | void;
  beforeExport?: (context: AuditHistoryPanelExportContext) => boolean | void;
};
```

---

### `AuditHistoryPanelExportContext`

```ts
export type AuditHistoryPanelExportContext = {
  format: AuditHistoryExportFormat;
};
```

---

### `AuditHistoryPanelJumpContext`

```ts
export type AuditHistoryPanelJumpContext = {
  record: AuditRecord;
  change: AuditChange;
};
```

---

### `AuditHistoryPanelLabels`

```ts
export type AuditHistoryPanelLabels = {
  title: string;
  liveStatus: string;
  recordsSummary: (count: number) => string;
  changesSummary: (count: number) => string;
  allTab: string;
  rowTab: string;
  cellTab: string;
  tableTab: string;
  selectedCell: (rowId: string, column: ColumnProp) => string;
  selectedRow: (rowId: string) => string;
  export: string;
  exportCsv: string;
  exportJson: string;
  exportCsvTitle: string;
  exportJsonTitle: string;
  close: string;
  openPanel: string;
  searchPlaceholder: string;
  searchAriaLabel: string;
  searchShortcut: string;
  userPlaceholder: string;
  userAriaLabel: string;
  columnAriaLabel: string;
  actionAriaLabel: string;
  dateFromAriaLabel: string;
  dateToAriaLabel: string;
  allColumns: string;
  allActions: string;
  clearFilters: string;
  addFilter: string;
  removeFilter: (label: string) => string;
  noRecords: string;
  noComparableRecord: string;
  scopedRecordCount: (visibleChanges: number, totalChanges: number) => string;
  changedBy: (changedAt: string, user: string) => string;
  rowTarget: (rowId: string | undefined, column: ColumnProp | undefined) => string;
  cellValues: (oldValue: string, newValue: string) => string;
  rowSnapshotAvailable: string;
  rowRemoved: string;
  restoreCell: string;
  restoreRow: string;
  restoreTransaction: string;
  restoreSnapshot: string;
  jumpToCell: string;
  revertAll: string;
  moreActions: string;
  compare: string;
  compareTitle: string;
  compareBefore: string;
  compareAfter: string;
  closeCompare: string;
  compareEmpty: string;
  viewChanges: (count: number) => string;
  previousPage: string;
  nextPage: string;
  pageStatus: (currentPage: number, pageCount: number) => string;
  dayToday: string;
  dayYesterday: string;
  sourceLabels: Record<AuditHistorySource, string>;
  actions: Partial<Record<AuditActionType, string>>;
  actionVerbs: Partial<Record<AuditActionType, string>>;
};
```

---

### `AuditHistoryPanelLabelsOptions` (Extended from `index.ts`)

```ts
export type AuditHistoryPanelLabelsOptions = Partial<Omit<AuditHistoryPanelLabels, 'actions' | 'actionVerbs' | 'sourceLabels'>> & {
  actions?: Partial<Record<AuditActionType, string>>;
  actionVerbs?: Partial<Record<AuditActionType, string>>;
  sourceLabels?: Partial<Record<AuditHistorySource, string>>;
};
```

---

### `AuditHistoryPanelHandle`

```ts
export type AuditHistoryPanelHandle = {
  destroy: () => void;
  setPlacement: (placement: AuditHistoryPanelPlacement) => void;
  refresh: () => Promise<void>;
};
```

---

### `AuditHistoryPanelOptions`

```ts
export type AuditHistoryPanelOptions = {
  pageSize?: number;
  allowExport?: boolean;
  allowCompare?: boolean | ((context: AuditHistoryPanelRecordContext) => boolean);
  allowClose?: boolean;
  miniOnClose?: boolean;
  restoreActions?: false | AuditRestoreType[] | ((context: AuditHistoryPanelRestoreContext) => boolean);
  formatDate?: (value: string, context: AuditHistoryPanelDateFormatContext) => string;
  events?: AuditHistoryPanelEvents;
  placement?: AuditHistoryPanelPlacement;
  tooltips?: false | Partial<Record<AuditHistoryPanelTooltipKey, string | false>>;
  labels?: AuditHistoryPanelLabelsOptions;
};
```

---

### `AuditHistoryPanelRecordContext`

```ts
export type AuditHistoryPanelRecordContext = {
  record: AuditRecord;
  changes: AuditChange[];
};
```

---

### `AuditHistoryPanelRestoreContext`

```ts
export type AuditHistoryPanelRestoreContext = {
  type: AuditRestoreType;
  record?: AuditRecord;
  change?: AuditChange;
  transactionId?: string;
};
```

---

### `AuditHistoryPanelPlacement`

```ts
export type AuditHistoryPanelPlacement = 'right' | 'left' | 'top' | 'bottom' | 'none';
```

---

### `AuditHistoryPanelTooltipKey`

```ts
export type AuditHistoryPanelTooltipKey =
  | 'totalRecords'
  | 'totalChanges'
  | 'selectedScope'
  | 'searchFilter'
  | 'userFilter'
  | 'columnFilter'
  | 'actionFilter'
  | 'dateFromFilter'
  | 'dateToFilter'
  | 'clearFilters';
```

---

### `AUDIT_HISTORY_STORAGE_KEY`

```ts
AUDIT_HISTORY_STORAGE_KEY: string;
```

---

### `cloneValue`

```ts
export function cloneValue<T>(value: T): T;
```

---

### `cloneChange`

```ts
export function cloneChange(change: AuditChange): AuditChange;
```

---

### `cloneRecord`

```ts
export function cloneRecord(record: AuditRecord): AuditRecord;
```

---

### `normalizeRowId`

```ts
export function normalizeRowId(rowId: string | number | undefined): string | undefined;
```

---

### `toTime`

```ts
export function toTime(value: string | Date | undefined, fallback: number);
```

---

### `shouldIncludeRecord`

```ts
export function shouldIncludeRecord(record: AuditRecord, filter?: AuditHistoryFilter);
```

---

### `trimRecords`

```ts
export function trimRecords(records: AuditRecord[], maxRecords: number): AuditRecord[];
```

---

### `mergeRecords`

```ts
export function mergeRecords(current: AuditRecord[], next: AuditRecord[]): AuditRecord[];
```

---

### `createAuditStats`

```ts
export function createAuditStats(records: AuditRecord[], filter?: AuditHistoryFilter): AuditHistoryStats;
```

---

### `stringifyExportValue`

```ts
export function stringifyExportValue(value: unknown): string;
```

---

### `exportAuditRecords`

```ts
export function exportAuditRecords(records: AuditRecord[], options: AuditHistoryExportOptions = {}): string;
```

---

# Audit History Panel

URL: https://pro.rv-grid.com/api/audit-history-panel/
Source: src/content/docs/api/audit-history-panel.md

### `createAuditHistoryPanelDock`

```ts
export function createAuditHistoryPanelDock(
  panel: HTMLElement,
  grid: HTMLRevoGridElement,
  placement: AuditHistoryPanelPlacement,
);
```

---

### `defineAuditHistoryPanel`

Renders the Audit History panel into `el` for the given RevoGrid element.

The grid must have `AuditHistoryPlugin` installed.

```ts
export function defineAuditHistoryPanel(el: HTMLElement, grid: HTMLRevoGridElement, options: AuditHistoryPanelOptions = {}): AuditHistoryPanelHandle;
```

---

### `AuditHistoryPanelDateFormatContext`

```ts
export type AuditHistoryPanelDateFormatContext = {
  mode: 'time' | 'day' | 'filter';
  record?: AuditRecord;
};
```

---

### `AuditHistoryPanelEvents`

```ts
export type AuditHistoryPanelEvents = {
  beforeRecordSelect?: (context: AuditHistoryPanelRecordContext) => boolean | void;
  beforeCompareOpen?: (context: AuditHistoryPanelRecordContext) => boolean | void;
  beforeJumpToCell?: (context: AuditHistoryPanelJumpContext) => boolean | void;
  beforeRestore?: (context: AuditHistoryPanelRestoreContext) => boolean | void;
  beforeExport?: (context: AuditHistoryPanelExportContext) => boolean | void;
};
```

---

### `AuditHistoryPanelExportContext`

```ts
export type AuditHistoryPanelExportContext = {
  format: AuditHistoryExportFormat;
};
```

---

### `AuditHistoryPanelJumpContext`

```ts
export type AuditHistoryPanelJumpContext = {
  record: AuditRecord;
  change: AuditChange;
};
```

---

### `AuditHistoryPanelLabels`

```ts
export type AuditHistoryPanelLabels = {
  title: string;
  liveStatus: string;
  recordsSummary: (count: number) => string;
  changesSummary: (count: number) => string;
  allTab: string;
  rowTab: string;
  cellTab: string;
  tableTab: string;
  selectedCell: (rowId: string, column: ColumnProp) => string;
  selectedRow: (rowId: string) => string;
  export: string;
  exportCsv: string;
  exportJson: string;
  exportCsvTitle: string;
  exportJsonTitle: string;
  close: string;
  openPanel: string;
  searchPlaceholder: string;
  searchAriaLabel: string;
  searchShortcut: string;
  userPlaceholder: string;
  userAriaLabel: string;
  columnAriaLabel: string;
  actionAriaLabel: string;
  dateFromAriaLabel: string;
  dateToAriaLabel: string;
  allColumns: string;
  allActions: string;
  clearFilters: string;
  addFilter: string;
  removeFilter: (label: string) => string;
  noRecords: string;
  noComparableRecord: string;
  scopedRecordCount: (visibleChanges: number, totalChanges: number) => string;
  changedBy: (changedAt: string, user: string) => string;
  rowTarget: (rowId: string | undefined, column: ColumnProp | undefined) => string;
  cellValues: (oldValue: string, newValue: string) => string;
  rowSnapshotAvailable: string;
  rowRemoved: string;
  restoreCell: string;
  restoreRow: string;
  restoreTransaction: string;
  restoreSnapshot: string;
  jumpToCell: string;
  revertAll: string;
  moreActions: string;
  compare: string;
  compareTitle: string;
  compareBefore: string;
  compareAfter: string;
  closeCompare: string;
  compareEmpty: string;
  viewChanges: (count: number) => string;
  previousPage: string;
  nextPage: string;
  pageStatus: (currentPage: number, pageCount: number) => string;
  dayToday: string;
  dayYesterday: string;
  sourceLabels: Record<AuditHistorySource, string>;
  actions: Partial<Record<AuditActionType, string>>;
  actionVerbs: Partial<Record<AuditActionType, string>>;
};
```

---

### `AuditHistoryPanelLabelsOptions` (Extended from `index.tsx`)

```ts
export type AuditHistoryPanelLabelsOptions = Partial<Omit<AuditHistoryPanelLabels, 'actions' | 'actionVerbs' | 'sourceLabels'>> & {
  actions?: Partial<Record<AuditActionType, string>>;
  actionVerbs?: Partial<Record<AuditActionType, string>>;
  sourceLabels?: Partial<Record<AuditHistorySource, string>>;
};
```

---

### `AuditHistoryPanelHandle`

```ts
export type AuditHistoryPanelHandle = {
  destroy: () => void;
  setPlacement: (placement: AuditHistoryPanelPlacement) => void;
  refresh: () => Promise<void>;
};
```

---

### `AuditHistoryPanelOptions`

```ts
export type AuditHistoryPanelOptions = {
  pageSize?: number;
  allowExport?: boolean;
  allowCompare?: boolean | ((context: AuditHistoryPanelRecordContext) => boolean);
  allowClose?: boolean;
  miniOnClose?: boolean;
  restoreActions?: false | AuditRestoreType[] | ((context: AuditHistoryPanelRestoreContext) => boolean);
  formatDate?: (value: string, context: AuditHistoryPanelDateFormatContext) => string;
  events?: AuditHistoryPanelEvents;
  placement?: AuditHistoryPanelPlacement;
  tooltips?: false | Partial<Record<AuditHistoryPanelTooltipKey, string | false>>;
  labels?: AuditHistoryPanelLabelsOptions;
};
```

---

### `AuditHistoryPanelRecordContext`

```ts
export type AuditHistoryPanelRecordContext = {
  record: AuditRecord;
  changes: AuditChange[];
};
```

---

### `AuditHistoryPanelRestoreContext`

```ts
export type AuditHistoryPanelRestoreContext = {
  type: AuditRestoreType;
  record?: AuditRecord;
  change?: AuditChange;
  transactionId?: string;
};
```

---

### `AuditHistoryPanelPlacement`

```ts
export type AuditHistoryPanelPlacement = 'right' | 'left' | 'top' | 'bottom' | 'none';
```

---

### `AuditHistoryPanelTooltipKey`

```ts
export type AuditHistoryPanelTooltipKey =
  | 'totalRecords'
  | 'totalChanges'
  | 'selectedScope'
  | 'searchFilter'
  | 'userFilter'
  | 'columnFilter'
  | 'actionFilter'
  | 'dateFromFilter'
  | 'dateToFilter'
  | 'clearFilters';
```

---

### `resolveLabels`

```ts
export function resolveLabels(labels?: AuditHistoryPanelLabelsOptions): AuditHistoryPanelLabels;
```

---

### `getAuditActionLabel`

```ts
export function getAuditActionLabel(labels: AuditHistoryPanelLabels, actionType: AuditActionType): string;
```

---

### `getAuditActionVerb`

```ts
export function getAuditActionVerb(labels: AuditHistoryPanelLabels, actionType: AuditActionType): string;
```

---

### `actionTypes`

```ts
actionTypes: AuditActionType[];
```

---

### `titleizeActionType`

```ts
titleizeActionType: (value: string) => string;
```

---

### `createInitialFilters`

```ts
export function createInitialFilters(): AuditPanelFilters;
```

---

### `stringifyValue`

```ts
export function stringifyValue(value: unknown): string;
```

---

### `formatTime`

```ts
export function formatTime(value: string, mode: 'compact' | 'day' = 'compact');
```

---

### `formatPanelDate`

```ts
export function formatPanelDate(
  value: string,
  options: AuditHistoryPanelOptions,
  context: { mode: 'time' | 'day' | 'filter'; record?: AuditRecord },
);
```

---

### `getUserLabel`

```ts
export function getUserLabel(record: AuditRecord);
```

---

### `getAvatarLabel`

```ts
export function getAvatarLabel(record: AuditRecord);
```

---

### `matchesFilters`

```ts
export function matchesFilters(record: AuditRecord, filters: AuditPanelFilters);
```

---

### `getScopedChanges`

```ts
export function getScopedChanges(record: AuditRecord, tab: AuditPanelTab, selected: SelectedAuditTarget): AuditChange[];
```

---

### `getRecordSource`

```ts
export function getRecordSource(type: AuditActionType, record?: AuditRecord): AuditHistorySource;
```

---

### `getTargetLabel`

```ts
export function getTargetLabel(record: AuditRecord, changes: AuditChange[], labels: AuditHistoryPanelLabels);
```

---

### `getDetailLabel`

```ts
export function getDetailLabel(record: AuditRecord, changes: AuditChange[]);
```

---

### `isComparable`

```ts
export function isComparable(record: AuditRecord, changes: AuditChange[]);
```

---

### `toTimelineRecord`

```ts
export function toTimelineRecord(
  record: AuditRecord,
  changes: AuditChange[],
  labels: AuditHistoryPanelLabels,
  options: AuditHistoryPanelOptions = {},
): TimelineRecord;
```

---

### `groupTimelineRecords`

```ts
export function groupTimelineRecords(records: TimelineRecord[]): TimelineGroup[];
```

---

### `getPlugin`

```ts
export async function getPlugin(grid: HTMLRevoGridElement): Promise<AuditHistoryPluginRuntime | undefined>;
```

---

### `panelRefreshEvents`

```ts
panelRefreshEvents: readonly ["auditrecord", "auditrecordsloaded", "auditrestore"];
```

---

### `canSelectRecord`

```ts
export function canSelectRecord(options: AuditHistoryPanelOptions, context: AuditHistoryPanelRecordContext);
```

---

### `canOpenCompare`

```ts
export function canOpenCompare(options: AuditHistoryPanelOptions, context: AuditHistoryPanelRecordContext);
```

---

### `canJumpToCell`

```ts
export function canJumpToCell(options: AuditHistoryPanelOptions, context: AuditHistoryPanelJumpContext);
```

---

### `canUseRestoreAction`

```ts
export function canUseRestoreAction(options: AuditHistoryPanelOptions, context: AuditHistoryPanelRestoreContext);
```

---

### `canExportAuditHistory`

```ts
export function canExportAuditHistory(options: AuditHistoryPanelOptions, format: AuditHistoryExportFormat);
```

---

### `AuditHistoryTooltip`

```ts
export function AuditHistoryTooltip({ options, tooltipKey }: { options: AuditHistoryPanelOptions; tooltipKey: AuditHistoryPanelTooltipKey });
```

---

### `AuditPanelTab`

```ts
export type AuditPanelTab = 'cell' | 'row' | 'table';
```

---

### `SelectedAuditTarget`

```ts
export type SelectedAuditTarget = {
  rowId?: string;
  column?: ColumnProp;
  columnLabel?: ColumnProp;
  rowIndex?: number;
  rowType?: DimensionRows;
};
```

---

### `AuditPanelFilters`

```ts
export type AuditPanelFilters = {
  search: string;
  user: string;
  column: string;
  actionType: '' | AuditActionType;
  dateFrom: string;
  dateTo: string;
};
```

---

### `AuditHistoryPluginRuntime`

```ts
export type AuditHistoryPluginRuntime = {
  getRecords: () => AuditRecord[];
  getCellHistory: (rowId: string, column: ColumnProp) => AuditRecord[];
  getRowHistory: (rowId: string) => AuditRecord[];
  getStats: () => AuditHistoryStats;
  exportRecords: (options?: AuditHistoryExportOptions) => string;
  getRowIdentity: (row: DataType | undefined, rowIndex: number, rowType: DimensionRows) => string | undefined;
  canRestoreRecord: (context: { type: AuditRestoreType; record?: AuditRecord; change?: AuditChange; transactionId?: string }) => boolean;
  restoreCell: (change: AuditChange) => boolean;
  restoreRow: (record: AuditRecord) => boolean;
  restoreTransaction: (transactionId: string) => boolean;
  restoreSnapshot?: (recordOrId: AuditRecord | string) => boolean;
  recordEvent?: (input: AuditRecordEventInput) => AuditRecord | undefined;
  createSnapshot?: (label: string, options?: AuditSnapshotOptions) => AuditRecord | undefined;
};
```

---

### `VisibleAuditRecord`

```ts
export type VisibleAuditRecord = {
  record: AuditRecord;
  changes: AuditChange[];
};
```

---

### `TimelineRecord` (Extended from `types.ts`)

```ts
export type TimelineRecord = VisibleAuditRecord & {
  id: string;
  source: AuditHistorySource;
  verb: string;
  userLabel: string;
  avatarLabel: string;
  avatarIndex?: number;
  avatarColor?: string;
  targetLabel: string;
  detailLabel?: string;
  rangeLabel?: string;
  changedAtLabel: string;
  dayKey: string;
  dayLabel: string;
  daySubLabel?: string;
  accent: boolean;
  comparable: boolean;
};
```

---

### `TimelineGroup`

```ts
export type TimelineGroup = {
  key: string;
  label: string;
  subLabel?: string;
  records: TimelineRecord[];
};
```

---

### `AuditHistoryPanel`

```ts
export function AuditHistoryPanel({
  grid,
  options = {},
  refreshSignal = 0,
  onClose,
}: {
  grid: HTMLRevoGridElement;
  options?: AuditHistoryPanelOptions;
  refreshSignal?: number;
  onClose?: () => void;
});
```

---

### `CompareDrawer`

```ts
export function CompareDrawer({ record, labels, onClose }: CompareDrawerProps);
```

---

### `Filters`

```ts
export function Filters({ filters, columns, actionTypes, labels, options, searchInputRef, onFiltersChange, onClearFilters }: FiltersProps);
```

---

### `MiniAuditHistoryPanel`

```ts
export function MiniAuditHistoryPanel({
  grid,
  options,
  onOpen,
}: {
  grid: HTMLRevoGridElement;
  options: AuditHistoryPanelOptions;
  onOpen: () => void;
});
```

---

### `Pagination`

```ts
export function Pagination({
  visibleRecordCount,
  pageSize,
  currentPage,
  pageCount,
  labels,
  onPageChange,
}: PaginationProps);
```

---

### `RecordsList`

```ts
export function RecordsList({
  groups,
  labels,
  plugin,
  selectedRecordId,
  collapsingRecordId,
  onSelectRecord,
  onRestoreCell,
  onRestoreRow,
  onRestoreTransaction,
  onRestoreSnapshot,
  onJumpToChange,
  canUseRestoreAction,
  canJumpToChange,
}: RecordsListProps);
```

---

### `Toolbar`

```ts
export function Toolbar({
  records,
  stats,
  selected,
  tab,
  tabCounts,
  labels,
  options,
  onTabChange,
  onExport,
  onClose,
}: ToolbarProps);
```

---

# Autofill

URL: https://pro.rv-grid.com/api/autofill/
Source: src/content/docs/api/autofill.md

### `createDefaultAutoFillStrategies`

Creates the default AutoFill strategy list in evaluation order.

Strategies are ordered from specific to general, with copy fallback last. The
same list is used by AutoFillPlugin and AutoFillPreviewPlugin when no active
AutoFillPlugin instance can be resolved.

**@returns** Default AutoFill strategies.

```ts
export function createDefaultAutoFillStrategies(): AutoFillStrategy[];
```

---

### `AutoFillPlugin`

The `AutoFillPlugin` enhances RevoGrid with advanced autofill capabilities,
allowing users to automatically fill cell ranges based on various sequence
strategies. This plugin supports numeric, date, and text sequences, making it
versatile for different data types and user needs.

 **Features**:
- Utilizes multiple pre-defined strategies for numbers, dates, time values,
  text-number labels, weekday/month names, boolean cycles, and copy fallback.
- Listens for the `beforeautofill` to trigger autofill actions based on user
  interactions.
- Allows registration of additional custom autofill strategies.
- Applies autofilled data directly to the grid, updating the data store efficiently.

**Usage**:
- Import `AutoFillPlugin` and add it to the RevoGrid's plugin list.
- The grid will automatically handle range selection and autofilling based on the
  registered strategies.

### Example
```typescript
import { AutoFillPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [AutoFillPlugin]; // Add autofill functionality to the grid
```

This plugin is ideal for enhancing user productivity in data entry tasks by
providing intelligent filling of repetitive or sequential data patterns, commonly
used in spreadsheets and data management applications.

```ts
class AutoFillPlugin {
  /**
     * Registers a custom autofill strategy.
     *
     * Custom strategies are inserted before the copy fallback strategy so they can
     * override generic copy behavior.
     *
     * @param strategy Strategy function to register.
     */
  registerStrategy(strategy: AutoFillStrategy);

  /**
     * Returns the active strategy list.
     *
     * The preview plugin reads this list from the active AutoFillPlugin instance so
     * preview and final commit use identical strategy order.
     *
     * @returns Registered strategy list in evaluation order.
     */
  getStrategies();

  /**
     * Register a post-processor shared by autofill preview and commit.
     *
     * The returned disposer removes only this registration, allowing integration
     * plugins to detach without affecting host strategies or other transformers.
     */
  registerResultTransformer(transformer: AutoFillResultTransformer): () => void;

  /** Return active result transformers in registration order. */
  getResultTransformers(): readonly AutoFillResultTransformer[];
}
```

---

### `computeAutoFillData`

```ts
export function computeAutoFillData({
  oldRange,
  newRange,
  type,
  colType,
  providers,
  strategies,
  transformers = [],
}: AutoFillComputeOptions): AutoFillComputedData | null;
```

---

### `mapAutoFillMatrixToData`

```ts
export function mapAutoFillMatrixToData(
  matrix: any[][],
  target: RangeArea,
  providers: Pick<PluginProviders, 'column'>,
  colType: DimensionCols,
): Record<number, DataType>;
```

---

### `AutoFillComputedData`

```ts
export type AutoFillComputedData = {
  matrix: any[][];
  data: Record<number, DataType>;
};
```

---

### `AutoFillComputeOptions` (Extended from `index.ts`)

```ts
export type AutoFillComputeOptions = Pick<ChangedRange, 'oldRange' | 'newRange'> & {
  type: DimensionRows;
  colType: DimensionCols;
  providers: PluginProviders;
  strategies: AutoFillStrategy[];
  transformers?: readonly AutoFillResultTransformer[];
};
```

---

### `createAutoFillCellLocationMatrix`

Build provider-backed locations for a normalized single-viewport range.

```ts
export function createAutoFillCellLocationMatrix(
  range: RangeArea,
  rowType: DimensionRows,
  colType: DimensionCols,
): AutoFillCellLocation[][];
```

---

### `AutoFillCellLocation`

Provider-backed location of one cell participating in an autofill operation.

```ts
/** Provider-backed location of one cell participating in an autofill operation. */
export type AutoFillCellLocation = {
  readonly rowType: DimensionRows;
  readonly colType: DimensionCols;
  readonly rowIndex: number;
  readonly colIndex: number;
};
```

---

### `AutoFillResultTransformerContext` (Extended from `index.ts`)

Context supplied after a strategy has produced its base autofill matrix.

```ts
/** Context supplied after a strategy has produced its base autofill matrix. */
export type AutoFillResultTransformerContext = AutoFillStrategyContext & {
  selectedData: any[][];
  sourceCells: readonly (readonly AutoFillCellLocation[])[];
  targetCells: readonly (readonly (AutoFillCellLocation | undefined)[])[];
};
```

---

### `AutoFillResultTransformer`

Post-processes a strategy result without replacing strategy selection.

```ts
/** Post-processes a strategy result without replacing strategy selection. */
export type AutoFillResultTransformer = (
  matrix: any[][],
  context: AutoFillResultTransformerContext,
) => any[][];
```

---

### `AutoFillPreviewPlugin`

```ts
class AutoFillPreviewPlugin {
  destroy();
}
```

---

### `AutoFillDirection`

Direction in which the autofill drag expands from the selected source range.

`both` is used when the source and target ranges cannot be reduced to a single
horizontal or vertical direction.

```ts
/**
 * Direction in which the autofill drag expands from the selected source range.
 *
 * `both` is used when the source and target ranges cannot be reduced to a single
 * horizontal or vertical direction.
 */
export type AutoFillDirection = 'up' | 'down' | 'left' | 'right' | 'both';
```

---

### `AutoFillStrategyContext`

Rich context passed to autofill strategies.

Existing custom strategies can keep using the legacy three-argument signature.
New strategies can read this object when they need selection metadata, drag
direction, dimension types, or plugin providers.

```ts
/**
 * Rich context passed to autofill strategies.
 *
 * Existing custom strategies can keep using the legacy three-argument signature.
 * New strategies can read this object when they need selection metadata, drag
 * direction, dimension types, or plugin providers.
 */
export type AutoFillStrategyContext = {
  /** Original selected/source range used as the autofill seed. */
  oldRange: RangeArea;

  /** Target range that will be previewed or committed. */
  newRange: RangeArea;

  /** Direction in which the target range expands from the source range. */
  direction: AutoFillDirection;

  /** Row dimension type for the active autofill operation. */
  rowType: DimensionRows;

  /** Column dimension type for the active autofill operation. */
  colType: DimensionCols;

  /** Plugin providers available to advanced strategy implementations. */
  providers: PluginProviders;

  /**
   * Cross-viewport autofill metadata when a plugin maps one visual gesture to
   * several viewport-scoped target ranges.
   */
  crossViewport?: {
    source: {
      rowType: DimensionRows;
      colType: DimensionCols;
      range: RangeArea;
    };
    targets: {
      rowType: DimensionRows;
      colType: DimensionCols;
      range: RangeArea;
    }[];
  };
};
```

---

### `AutoFillStrategy`

Autofill strategy function.

**@param** selectedData Matrix of selected source values, ordered row-major.

**@param** direction Direction in which the autofill drag expands.

**@param** newRange Target range that should be generated.

**@param** context Optional rich strategy context for advanced strategies.

**@returns** Generated target matrix, or `null` when the strategy does not support
the selected values.

**Example:**
```typescript
const copyStrategy: AutoFillStrategy = selectedData => selectedData;
AutoFillPlugin.registerStrategy(copyStrategy);
```

```ts
/**
 * Autofill strategy function.
 *
 * @param selectedData Matrix of selected source values, ordered row-major.
 * @param direction Direction in which the autofill drag expands.
 * @param newRange Target range that should be generated.
 * @param context Optional rich strategy context for advanced strategies.
 * @returns Generated target matrix, or `null` when the strategy does not support
 * the selected values.
 *
 * @example
 * ```typescript
 * const copyStrategy: AutoFillStrategy = selectedData => selectedData;
 * AutoFillPlugin.registerStrategy(copyStrategy);
 * ```
 */
export type AutoFillStrategy = (
  selectedData: any[][],
  direction: AutoFillDirection,
  newRange: RangeArea,
  context?: AutoFillStrategyContext,
) => any[][] | null;
```

---

### `getMatrixSize`

Calculates the row and column count for a RevoGrid range.

**@param** range Range to measure.

**@returns** Matrix size matching the inclusive range coordinates.

```ts
export function getMatrixSize(range: RangeArea): MatrixSize;
```

---

### `flattenMatrix`

Flattens a row-major matrix into a one-dimensional sequence.

**@param** data Matrix to flatten.

**@returns** Row-major sequence of values.

```ts
export function flattenMatrix<T = unknown>(data: T[][]): T[];
```

---

### `createMatrix`

Creates a matrix for a target range.

**@param** range Target range that defines output dimensions.

**@param** getValue Callback invoked for each cell position.

**@returns** Generated matrix in row-major order.

```ts
export function createMatrix<T>(
  range: RangeArea,
  getValue: (position: number, rowIndex: number, colIndex: number) => T,
): T[][];
```

---

### `repeatMatrix`

Tiles source values across the target range while preserving source rows and
columns.

**@param** selectedData Source matrix to repeat.

**@param** targetRange Target range that defines output dimensions.

**@returns** Generated matrix containing repeated source values.

```ts
export function repeatMatrix<T>(selectedData: T[][], targetRange: RangeArea): T[][];
```

---

### `isNil`

Checks whether a value is `null` or `undefined`.

**@param** value Value to check.

**@returns** `true` when the value is missing.

```ts
export function isNil(value: unknown): value is null | undefined;
```

---

### `isNumericValue`

Checks whether a value can be treated as a finite number.

**@param** value Value to check.

**@returns** `true` for finite numbers and numeric strings.

```ts
export function isNumericValue(value: unknown): value is number | string;
```

---

### `parseTextNumber`

Parses the first integer segment inside a text value.

**@param** value Value to parse.

**@returns** Prefix, numeric value, suffix, and zero-padding width, or `null`
when the value does not contain an integer segment.

```ts
export function parseTextNumber(value: unknown);
```

---

### `formatTextNumber`

Formats a text value with a numeric segment and preserved padding.

**@param** prefix Text before the number.

**@param** value Number to format.

**@param** suffix Text after the number.

**@param** width Minimum digit width for zero padding.

**@returns** Formatted text-number value.

```ts
export function formatTextNumber(prefix: string, value: number, suffix: string, width: number);
```

---

### `parseDateValue`

Parses a Date object or supported date string.

**@param** value Value to parse.

**@returns** Parsed date and original format, or `null` for unsupported values.

```ts
export function parseDateValue(value: unknown): ParsedDateValue | null;
```

---

### `formatDateValue`

Formats a date using the preserved input format.

**@param** date Date to format.

**@param** format Output format captured from the selected source value.

**@returns** Date object copy or formatted date string.

```ts
export function formatDateValue(date: Date, format: ParsedDateValue['format']);
```

---

### `addUtcDays`

Adds a number of days using UTC date math.

**@param** date Source date.

**@param** days Number of days to add.

**@returns** New Date instance.

```ts
export function addUtcDays(date: Date, days: number);
```

---

### `addUtcMonths`

Adds a number of months using UTC date math.

**@param** date Source date.

**@param** months Number of months to add.

**@returns** New Date instance.

```ts
export function addUtcMonths(date: Date, months: number);
```

---

### `monthDiff`

Calculates whole-month distance between two UTC dates.

**@param** a Start date.

**@param** b End date.

**@returns** Number of calendar months from `a` to `b`.

```ts
export function monthDiff(a: Date, b: Date);
```

---

### `parseTimeValue`

Parses a supported clock-time string.

**@param** value Value to parse.

**@returns** Parsed seconds and original format, or `null` for unsupported values.

```ts
export function parseTimeValue(value: unknown): ParsedTimeValue | null;
```

---

### `formatTimeValue`

Formats seconds since midnight as a clock-time string.

**@param** totalSeconds Seconds since midnight. Values wrap around 24 hours.

**@param** format Output format captured from the selected source value.

**@returns** Formatted clock-time string.

```ts
export function formatTimeValue(totalSeconds: number, format: ParsedTimeValue['format']);
```

---

### `MatrixSize`

Size of a two-dimensional autofill matrix.

```ts
/**
 * Size of a two-dimensional autofill matrix.
 */
export type MatrixSize = {
  /** Number of rows in the target matrix. */
  rows: number;

  /** Number of columns in the target matrix. */
  cols: number;
};
```

---

### `ParsedDateValue`

Parsed date value with the visible input format needed for output.

```ts
/**
 * Parsed date value with the visible input format needed for output.
 */
export type ParsedDateValue = {
  /** Parsed date normalized to a Date object. */
  date: Date;

  /** Original visible input format. */
  format: 'date-object' | 'yyyy-mm-dd' | 'yyyy/mm/dd' | 'mm/dd/yyyy';
};
```

---

### `ParsedTimeValue`

Parsed clock-time value with the visible input format needed for output.

```ts
/**
 * Parsed clock-time value with the visible input format needed for output.
 */
export type ParsedTimeValue = {
  /** Seconds elapsed since midnight. */
  seconds: number;

  /** Original visible input format. */
  format: 'hh:mm' | 'hh:mm:ss';
};
```

---

### `linearNumericSequenceStrategy`

The `linearNumericSequenceStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin designed to generate numeric sequences with a constant interval.
This strategy is ideal for filling grid cells with linear numeric progressions.

 **Features**:
- Validates that all selected data elements are numeric, filtering out non-numeric
  sequences to prevent errors.
- Computes the common difference between numbers in the sequence to establish a
  consistent interval.
- Extends the numeric sequence across the specified range, maintaining the calculated
  interval throughout the grid.
- Supports dynamic autofill in both horizontal and vertical directions.

**Usage**:
- Import `linearNumericSequenceStrategy` and register it with the AutoFillPlugin
  for use in RevoGrid to enable linear numeric autofill functionality.

### Example
```typescript
import { linearNumericSequenceStrategy } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [AutoFillPlugin];
AutoFillPlugin.registerStrategy(linearNumericSequenceStrategy); // Register strategy
```

This strategy is particularly suited for applications requiring predictable numeric
data entry, such as financial models, inventory lists, or any scenario where
arithmetic progression is needed.

```ts
linearNumericSequenceStrategy: AutoFillStrategy;
```

---

### `dateSequenceStrategy`

The `dateSequenceStrategy` is an autofill strategy designed for RevoGrid's
AutoFillPlugin, which facilitates the automatic generation of consistent date
sequences within grid cells. This strategy is used to extend a selected range
of date values either as Date objects or ISO date strings.

 **Features**:
- Validates that all selected data elements are either Date objects or valid
  ISO date strings, ensuring consistency in input types.
- Computes the common difference between consecutive dates to determine the
  sequence's interval.
- Generates a new date sequence extending the original, maintaining the identified
  interval across the target range specified.
- Supports output as either Date objects or 'YYYY-MM-DD' formatted strings,
  depending on the input type.

**Usage**:
- Import `dateSequenceStrategy` and register it with the AutoFillPlugin for use
  in RevoGrid to enable date autofill functionality.

### Example
```typescript
import { dateSequenceStrategy } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [AutoFillPlugin];
AutoFillPlugin.registerStrategy(dateSequenceStrategy); // Register date sequence strategy
```

This strategy is ideal for applications dealing with chronological data entry,
where users benefit from automatic date progression, such as scheduling tools
or timeline management systems.

```ts
dateSequenceStrategy: AutoFillStrategy;
```

---

### `dateSequenceWithIntervalStrategy`

The `dateSequenceWithIntervalStrategy` is an advanced autofill strategy for
RevoGrid's AutoFillPlugin that facilitates filling grids with date sequences
that maintain a consistent interval. It extends upon basic date sequence
strategies by using a defined interval between consecutive dates.

 **Features**:
- Validates that input data consists of either Date objects or ISO date strings.
- Ensures consistency in date intervals across the sequence, filtering out
  inconsistent sequences.
- Generates a date sequence extending beyond the initial selection, maintaining
  the calculated interval throughout the target range.
- Supports output in both Date objects and 'YYYY-MM-DD' strings, based on input type.

**Usage**:
- Import `dateSequenceWithIntervalStrategy` and register it with the AutoFillPlugin
  to enable interval-based date autofill in RevoGrid.

### Example
```typescript
import { dateSequenceWithIntervalStrategy } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [AutoFillPlugin];
AutoFillPlugin.registerStrategy(dateSequenceWithIntervalStrategy); // Register strategy
```

This strategy is particularly useful for applications that require consistent
scheduling or timeline management, where maintaining a regular interval between
dates is essential for data accuracy and usability.

```ts
dateSequenceWithIntervalStrategy: AutoFillStrategy;
```

---

### `textSequenceStrategy`

```ts
textSequenceStrategy: AutoFillStrategy;
```

---

### `copyFallbackStrategy`

The `copyFallbackStrategy` is the final default autofill strategy for
RevoGrid's AutoFillPlugin. It repeats the selected source values when no
sequence-specific strategy can safely infer a smarter progression.

**Features**:
- Repeats the selected matrix in row-major order across the target range.
- Supports plain text, numbers, dates, booleans, objects, and mixed values.
- Avoids surprising inferred sequences for ambiguous input.
- Provides deterministic preview and final apply data for every non-empty
  selection.

**Usage**:
- Included by default as the last built-in strategy.
- Custom strategies registered through AutoFillPlugin are inserted before this
  fallback so they can override copy behavior.

### Example
```typescript
import { copyFallbackStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(copyFallbackStrategy);
```

```ts
copyFallbackStrategy: AutoFillStrategy;
```

---

### `singleNumericStepStrategy`

The `singleNumericStepStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that expands a single numeric source value into a simple
incrementing numeric sequence.

**Features**:
- Activates only when exactly one selected value is numeric.
- Uses a default step of `+1`.
- Supports numeric strings and number values.
- Falls through for mixed, empty, or multi-value selections so more specific
  strategies or the copy fallback can handle them.

**Usage**:
- Included by default before the copy fallback.
- Useful for spreadsheet-like fills such as `1` -> `1, 2, 3`.

### Example
```typescript
import { singleNumericStepStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(singleNumericStepStrategy);
```

```ts
singleNumericStepStrategy: AutoFillStrategy;
```

---

### `textNumberSequenceStrategy`

The `textNumberSequenceStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that continues strings containing an embedded number.

**Features**:
- Supports numeric suffixes, prefixes, and middle-number patterns.
- Preserves leading zero width, for example `INV-099` -> `INV-100`.
- Supports ordinal text such as `1st Floor`, `2nd Floor`, `3rd Floor`.
- Requires a consistent prefix/suffix shape and numeric interval.
- Falls through for ambiguous mixed text patterns.

**Usage**:
- Included by default before the legacy text suffix strategy.
- Use it for identifiers, labels, invoice numbers, and numbered locations.

### Example
```typescript
import { textNumberSequenceStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(textNumberSequenceStrategy);
```

```ts
textNumberSequenceStrategy: AutoFillStrategy;
```

---

### `weekdayMonthNameStrategy`

The `weekdayMonthNameStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that continues English weekday and month name sequences.

**Features**:
- Supports full names such as `Monday` and `January`.
- Supports three-letter names such as `Mon` and `Jan`.
- Preserves the selected full-name or short-name format.
- Wraps around calendar boundaries, for example `Sat, Sun` -> `Mon`.
- Falls through when weekday and month labels are mixed or ambiguous.

**Usage**:
- Included by default before generic text and copy strategies.
- Use it for spreadsheet-like calendar labels in planning grids.

### Example
```typescript
import { weekdayMonthNameStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(weekdayMonthNameStrategy);
```

```ts
weekdayMonthNameStrategy: AutoFillStrategy;
```

---

### `dateUnitSequenceStrategy`

The `dateUnitSequenceStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that continues date sequences using calendar-aware day and
month units.

**Features**:
- Supports Date objects and common date strings: `YYYY-MM-DD`, `YYYY/MM/DD`,
  and `MM/DD/YYYY`.
- Preserves the selected input format in generated values.
- Infers daily, weekly, monthly, quarterly, and yearly progressions through
  consistent day or month steps.
- Uses a one-day step for a single selected date.
- Falls through for invalid, mixed-format, or irregular date selections.

**Usage**:
- Included by default before legacy date strategies.
- Use it for scheduling, planning, and timeline grids where visible date
  formatting should remain stable.

### Example
```typescript
import { dateUnitSequenceStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(dateUnitSequenceStrategy);
```

```ts
dateUnitSequenceStrategy: AutoFillStrategy;
```

---

### `timeSequenceStrategy`

The `timeSequenceStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that continues clock-time strings.

**Features**:
- Supports `HH:mm` and `HH:mm:ss` formats.
- Preserves the selected time format in generated values.
- Infers a consistent interval from multiple selected times.
- Uses a one-hour step for a single selected time.
- Wraps around 24-hour boundaries.

**Usage**:
- Included by default before generic text and copy strategies.
- Use it for scheduling grids, time slots, and recurring interval data.

### Example
```typescript
import { timeSequenceStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(timeSequenceStrategy);
```

```ts
timeSequenceStrategy: AutoFillStrategy;
```

---

### `booleanCycleStrategy`

The `booleanCycleStrategy` is an autofill strategy for RevoGrid's
AutoFillPlugin that repeats boolean-like toggle values.

**Features**:
- Supports boolean values: `true` and `false`.
- Supports common string pairs: `true/false`, `yes/no`, and `on/off`.
- Preserves the original selected values while repeating the selected cycle.
- Requires both string pair values to be present before string cycling.
- Falls through for single string values so plain copy fallback can handle them.

**Usage**:
- Included by default before the generic copy fallback.
- Use it for toggles, status columns, and simple alternating flags.

### Example
```typescript
import { booleanCycleStrategy } from '@revolist/revogrid-pro';

AutoFillPlugin.registerStrategy(booleanCycleStrategy);
```

```ts
booleanCycleStrategy: AutoFillStrategy;
```

---

# Avatar

URL: https://pro.rv-grid.com/api/avatar/
Source: src/content/docs/api/avatar.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  avatarIndexProp?: ColumnProp;
  avatarLabelProp?: ColumnProp;
  avatarProp?: ColumnProp;
  avatarSize?: number;
  rectangular?: boolean
}
```

## Plugin API

### `createAvatarElement`

Creates the shared avatar presentation for DOM-based overlays and plugins.

```ts
export function createAvatarElement(
  document: Document,
  options: AvatarTemplateOptions = {},
): HTMLSpanElement;
```

---

### `getAvatarCellBackground`

```ts
export function getAvatarCellBackground(index = 0);
```

---

### `getAvatarInitials`

```ts
export function getAvatarInitials(value: unknown);
```

---

### `getAvatarIndex`

```ts
export function getAvatarIndex(value: unknown);
```

---

### `avatarTemplate`

```ts
export function avatarTemplate(h: any, options: AvatarTemplateOptions = {});
```

---

### `AvatarTemplateOptions`

```ts
export type AvatarTemplateOptions = {
  ariaLabel?: string;
  className?: string;
  index?: number;
  initials?: string;
  key?: string | number;
  label?: string;
  rectangular?: boolean;
  size?: number;
  style?: Record<string, string | number | null | undefined>;
  value?: unknown;
};
```

---

### `AVATAR_CELL_BACKGROUNDS`

```ts
AVATAR_CELL_BACKGROUNDS: readonly ["linear-gradient(135deg, #7dd3fc, #2563eb)", "linear-gradient(135deg, #facc15, #b45309)", "linear-gradient(135deg, #f9a8d4, #be185d)", "linear-gradient(135deg, #a5b4fc, #4f46e5)", "linear-gradient(135deg, #86efac, #15803d)", "linear-gradient(135deg, #fda4af, #be123c)", "linear-gradient(135deg, #c4b5fd, #7c3aed)", "linear-gradient(135deg, #fdba74, #c2410c)"];
```

---

### `avatarRenderer`

```ts
avatarRenderer: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `avatarWithTextRenderer`

```ts
avatarWithTextRenderer: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

# Buttons

URL: https://pro.rv-grid.com/api/buttons/
Source: src/content/docs/api/buttons.md

### `DeleteButton`

```ts
DeleteButton: ({ onClick, locale, }: { onClick: (e: MouseEvent) => void; locale?: { title?: string | undefined; ariaLabel?: string | undefined; } | undefined; }) => any;
```

---

# Calendar

URL: https://pro.rv-grid.com/api/calendar/
Source: src/content/docs/api/calendar.md

### `CalendarWeekStart`

```ts
export type CalendarWeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
```

---

### `CalendarView`

```ts
export type CalendarView = 'month' | 'year';
```

---

### `CalendarDateRange`

```ts
interface CalendarDateRange {
  readonly from: ISODateString;
  readonly to: ISODateString
}
```

---

### `CalendarTranslations`

All non-date text rendered by the shared calendar.

```ts
interface CalendarTranslations {
  readonly previousMonth: string;
  readonly nextMonth: string;
  readonly previousYear: string;
  readonly nextYear: string;
  readonly chooseMonth: string;
  readonly calendar: string;
  readonly today: string;
  readonly invalidSelection: string
}
```

---

### `CalendarDayContext`

```ts
interface CalendarDayContext {
  readonly outside: boolean;
  readonly disabled: boolean;
  readonly selected: boolean;
  readonly previewed: boolean;
  readonly today: boolean
}
```

---

### `CalendarSelectionValidationContext`

```ts
interface CalendarSelectionValidationContext {
  readonly month: ISODateString;
  readonly view: CalendarView;
  readonly selection?: CalendarDateRange;
  readonly preview?: CalendarDateRange;
  readonly referenceDate?: ISODateString
}
```

---

### `CalendarSelectionValidationResult`

```ts
export type CalendarSelectionValidationResult = boolean | string;
```

---

### `CalendarProps`

```ts
interface CalendarProps {
  readonly month: ISODateString;
  readonly focusedDate: ISODateString;
  readonly referenceDate?: ISODateString;
  readonly selection?: CalendarDateRange;
  readonly preview?: CalendarDateRange;
  readonly locale?: string;
  readonly weekStartsOn?: CalendarWeekStart;
  readonly minDate?: ISODateString;
  readonly maxDate?: ISODateString;
  readonly isDateDisabled?: (date: ISODateString) => boolean;
  readonly showOutsideDays?: boolean;
  readonly allowOutsideMonthSelection?: boolean;
  readonly fixedWeeks?: boolean;
  readonly showTodayButton?: boolean;
  /** Hides the complete month/year heading and navigation row. */
    readonly showHeader?: boolean;
  /** Convenience switch for both previous and next actions. */
    readonly showNavigation?: boolean;
  readonly showPreviousButton?: boolean;
  readonly showNextButton?: boolean;
  readonly showMonthLabel?: boolean;
  readonly showWeekdays?: boolean;
  /** Allows the month/year heading to open a twelve-month overview. Defaults to true. */
    readonly enableYearView?: boolean;
  /** Available views. Defaults to month and year; supersedes `enableYearView`. */
    readonly views?: readonly CalendarView[];
  readonly defaultView?: CalendarView;
  readonly isMonthDisabled?: (month: ISODateString) => boolean;
  /** Overrides any subset of the exported English calendar translations. */
    readonly translations?: Partial<CalendarTranslations>;
  readonly className?: string;
  readonly dayClassName?: string | ((date: ISODateString, context: CalendarDayContext) => string | undefined);
  readonly renderDay?: (date: ISODateString, context: CalendarDayContext) => ComponentChildren;
  readonly formatMonth?: (month: ISODateString, locale: string) => string;
  readonly formatWeekday?: (date: ISODateString, locale: string) => string;
  readonly formatDayLabel?: (date: ISODateString, locale: string) => string;
  readonly onMonthChange: (month: ISODateString) => void;
  readonly onFocusedDateChange: (date: ISODateString) => void;
  readonly onSelect: (date: ISODateString) => void;
  readonly onPreviewDateChange?: (date?: ISODateString) => void;
  readonly validateSelection?: (
      date: ISODateString,
      context: CalendarSelectionValidationContext,
    ) => CalendarSelectionValidationResult;
  readonly onInvalidSelection?: (reason: string, date: ISODateString) => void;
  readonly onViewChange?: (view: CalendarView) => void
}
```

---

### `MoveCalendarFocusOptions`

```ts
interface MoveCalendarFocusOptions {
  readonly date: ISODateString;
  readonly key: string;
  readonly shiftKey?: boolean;
  readonly weekStartsOn: CalendarWeekStart;
  readonly minDate?: ISODateString;
  readonly maxDate?: ISODateString;
  readonly isDisabled?: (date: ISODateString) => boolean
}
```

---

### `DEFAULT_CALENDAR_TRANSLATIONS`

Complete English fallback used when a consumer does not override independent calendar text.

```ts
DEFAULT_CALENDAR_TRANSLATIONS: Readonly<CalendarTranslations>;
```

---

### `createCalendarMonth`

```ts
export function createCalendarMonth(
  month: ISODateString,
  weekStartsOn: CalendarWeekStart,
  fixedWeeks = true,
): readonly ISODateString[];
```

---

### `orderCalendarRange`

```ts
export function orderCalendarRange(from: ISODateString, to: ISODateString): CalendarDateRange;
```

---

### `isDateInCalendarRange`

```ts
export function isDateInCalendarRange(date: ISODateString, range?: CalendarDateRange): boolean;
```

---

### `isCalendarDateDisabled`

```ts
export function isCalendarDateDisabled(
  date: ISODateString,
  options: Pick<MoveCalendarFocusOptions, 'minDate' | 'maxDate' | 'isDisabled'>,
): boolean;
```

---

### `isCalendarMonthDisabled`

```ts
export function isCalendarMonthDisabled(
  month: ISODateString,
  options: Pick<MoveCalendarFocusOptions, 'minDate' | 'maxDate'> & {
    readonly isMonthDisabled?: (month: ISODateString) => boolean;
  },
): boolean;
```

---

### `moveCalendarFocus`

```ts
export function moveCalendarFocus(options: MoveCalendarFocusOptions): ISODateString | undefined;
```

---

### `Calendar`

```ts
export function Calendar({
  locale = 'en-US',
  weekStartsOn = 1,
  showOutsideDays = false,
  allowOutsideMonthSelection = false,
  fixedWeeks = true,
  showTodayButton = false,
  showHeader = true,
  showNavigation = true,
  showPreviousButton = showNavigation,
  showNextButton = showNavigation,
  showMonthLabel = true,
  showWeekdays = true,
  enableYearView = true,
  translations = {},
  formatMonth = defaultMonthFormat,
  formatWeekday = defaultWeekdayFormat,
  formatDayLabel = defaultDayLabel,
  ...props
}: CalendarProps);
```

---

### `CalendarHeader`

```ts
export function CalendarHeader({
  label,
  previousLabel,
  nextLabel,
  labelAction,
  showLabel = true,
  showPrevious = true,
  showNext = true,
  previousDisabled = false,
  nextDisabled = false,
  onPrevious,
  onNext,
}: {
  label: string;
  previousLabel: string;
  nextLabel: string;
  labelAction?: { ariaLabel: string; onClick: () => void };
  showLabel?: boolean;
  showPrevious?: boolean;
  showNext?: boolean;
  previousDisabled?: boolean;
  nextDisabled?: boolean;
  onPrevious: () => void;
  onNext: () => void;
});
```

---

### `CalendarWeekdays`

```ts
export function CalendarWeekdays({
  dates,
  locale,
  format,
}: {
  dates: readonly ISODateString[];
  locale: string;
  format: (date: ISODateString, locale: string) => string;
});
```

---

### `CalendarDay`

```ts
export function CalendarDay(props: CalendarDayProps);
```

---

### `CalendarDayProps`

```ts
interface CalendarDayProps {
  readonly date: ISODateString;
  readonly label: string;
  readonly className?: string;
  readonly outside: boolean;
  readonly hidden: boolean;
  readonly disabled: boolean;
  readonly focused: boolean;
  readonly selected: boolean;
  readonly previewed: boolean;
  readonly rangeStart: boolean;
  readonly rangeEnd: boolean;
  readonly previewStart: boolean;
  readonly previewEnd: boolean;
  readonly today: boolean;
  readonly content?: ComponentChildren;
  readonly setRef: (date: ISODateString, element: HTMLButtonElement | null) => void;
  readonly onFocus: (date: ISODateString) => void;
  readonly onPreview: (date?: ISODateString) => void;
  readonly onKeyDown: (event: h.JSX.TargetedKeyboardEvent<HTMLButtonElement>, date: ISODateString) => void;
  readonly onSelect: (date: ISODateString) => void
}
```

---

### `CalendarMonthGrid`

```ts
export function CalendarMonthGrid({
  dates,
  month,
  focusedDate,
  referenceDate,
  selection,
  preview,
  showOutsideDays,
  allowOutsideMonthSelection,
  dayClassName,
  renderDay,
  isDisabled,
  formatDayLabel,
  setDayRef,
  onFocus,
  onPreview,
  onKeyDown,
  onSelect,
}: {
  dates: readonly ISODateString[];
  month: ISODateString;
  focusedDate: ISODateString;
  referenceDate?: ISODateString;
  selection?: CalendarDateRange;
  preview?: CalendarDateRange;
  showOutsideDays: boolean;
  allowOutsideMonthSelection: boolean;
  dayClassName?: string | ((date: ISODateString, context: CalendarDayContext) => string | undefined);
  renderDay?: (date: ISODateString, context: CalendarDayContext) => ComponentChildren;
  isDisabled: (date: ISODateString) => boolean;
  formatDayLabel: (date: ISODateString) => string;
  setDayRef: (date: ISODateString, element: HTMLButtonElement | null) => void;
  onFocus: (date: ISODateString) => void;
  onPreview: (date?: ISODateString) => void;
  onKeyDown: (event: h.JSX.TargetedKeyboardEvent<HTMLButtonElement>, date: ISODateString) => void;
  onSelect: (date: ISODateString) => void;
});
```

---

### `CalendarYearGrid`

```ts
export function CalendarYearGrid({
  month,
  referenceDate,
  minDate,
  maxDate,
  isMonthDisabled,
  locale,
  ariaLabel,
  onSelect,
  onEscape,
}: {
  month: ISODateString;
  referenceDate?: ISODateString;
  minDate?: ISODateString;
  maxDate?: ISODateString;
  isMonthDisabled?: (month: ISODateString) => boolean;
  locale: string;
  ariaLabel: string;
  onSelect: (month: ISODateString) => void;
  onEscape: () => void;
});
```

---

# Calendars

URL: https://pro.rv-grid.com/api/calendars/
Source: src/content/docs/api/calendars.md

### `calendarKey`

```ts
export function calendarKey(calendarId: CalendarId): string;
```

---

### `normalizeIsoWorkingDays`

```ts
export function normalizeIsoWorkingDays(
  days: readonly number[] | undefined,
  fallback: readonly number[] = DEFAULT_CALENDAR.workingDays,
): readonly number[];
```

---

### `jsWeekdayFromIsoWeekday`

```ts
export function jsWeekdayFromIsoWeekday(day: number): number;
```

---

### `jsWeekdaysFromIsoWeekdays`

```ts
export function jsWeekdaysFromIsoWeekdays(days: readonly number[]): readonly number[];
```

---

### `normalizeCalendarHolidaySet`

```ts
export function normalizeCalendarHolidaySet(holidays: readonly ISODateString[] | undefined): ReadonlySet<string>;
```

---

### `normalizeCalendarWorkingHours`

```ts
export function normalizeCalendarWorkingHours(
  workingHours: CalendarWorkingTimeRange | readonly CalendarWorkingTimeRange[] | undefined,
  options: { readonly errorPrefix?: string } = {},
): readonly CalendarResolvedWorkingTimeRange[];
```

---

### `normalizeCalendar`

```ts
export function normalizeCalendar(
  calendar: CalendarEntity,
  options: { readonly workingHoursErrorPrefix?: string } = {},
): ResolvedCalendarEntity;
```

---

### `createResolvedCalendarMap`

```ts
export function createResolvedCalendarMap(
  calendars: readonly CalendarEntity[] | undefined,
  options: { readonly workingHoursErrorPrefix?: string } = {},
): Map<string, ResolvedCalendarEntity>;
```

---

### `createCalendarMap`

```ts
export function createCalendarMap(calendars: readonly CalendarEntity[] | undefined): Map<CalendarId, CalendarEntity>;
```

---

### `resolveCalendarFromMap`

```ts
export function resolveCalendarFromMap(
  target: CalendarLookupTarget,
  calendarsById: ReadonlyMap<CalendarId, CalendarEntity>,
  primaryCalendar: CalendarEntity | null,
): CalendarEntity | null;
```

---

### `resolveCalendarFromList`

```ts
export function resolveCalendarFromList(
  context: CalendarListLookupContext,
  target?: CalendarLookupTarget,
): CalendarEntity | null;
```

---

### `resolveCalendarItemFromMap`

```ts
export function resolveCalendarItemFromMap<T>(
  target: CalendarLookupTarget,
  items: ReadonlyMap<string, T>,
): T | null;
```

---

### `isCalendarHoliday`

```ts
export function isCalendarHoliday(
  date: ISODateString | string,
  calendar: Pick<CalendarEntity, 'holidays'> | Pick<ResolvedCalendarEntity, 'holidays'> | null | undefined,
): boolean;
```

---

### `isCalendarWorkingWeekday`

```ts
export function isCalendarWorkingWeekday(
  weekday: number,
  calendar: Pick<CalendarEntity, 'workingDays'> | Pick<ResolvedCalendarEntity, 'workingDays'> | null | undefined,
): boolean;
```

---

### `isWorkingCalendarDate`

```ts
export function isWorkingCalendarDate(
  date: ISODateString | string,
  weekday: number,
  calendar: (
    Pick<CalendarEntity, 'workingDays' | 'holidays'>
    | Pick<ResolvedCalendarEntity, 'workingDays' | 'holidays'>
    | null
    | undefined
  ),
): boolean;
```

---

### `isCalendarWorkingHour`

```ts
export function isCalendarWorkingHour(
  date: ISODateString | string,
  calendar: CalendarEntity | ResolvedCalendarEntity | null | undefined,
): boolean;
```

---

### `CalendarId`

Unique identifier for a working calendar.

```ts
/** Unique identifier for a working calendar. */
export type CalendarId = string | number;
```

---

### `CalendarWorkingTimeRange`

Time-of-day working window for calendar-aware schedulers.

```ts
interface CalendarWorkingTimeRange {
  /** Start time in `HH:mm` or AM/PM format. */
    readonly start: string;
  /** End time in `HH:mm` or AM/PM format. */
    readonly end: string
}
```

---

### `CalendarResolvedWorkingTimeRange`

Parsed working time window expressed as minutes from midnight.

```ts
interface CalendarResolvedWorkingTimeRange {
  readonly startMinutes: number;
  readonly endMinutes: number
}
```

---

### `CalendarEntity`

Defines the working schedule for tasks, events, and resources.
Working days use ISO weekday numbers: 1 = Monday ... 7 = Sunday.

```ts
interface CalendarEntity {
  /** Unique calendar identifier. */
    readonly id: CalendarId;
  /** Display name, for example `"Standard"` or `"Night Shift"`. */
    readonly name: string;
  /** IANA time zone, for example `"America/New_York"`. */
    readonly timeZone: string;
  /** ISO weekday numbers that are working days. */
    readonly workingDays: readonly number[];
  /** Specific dates that are non-working regardless of weekday. */
    readonly holidays: readonly ISODateString[];
  /** Optional working time windows inside a working day. */
    readonly workingHours?: CalendarWorkingTimeRange | readonly CalendarWorkingTimeRange[];
  /** Number of working hours per day, used for effort/capacity calculations. */
    readonly hoursPerDay: number
}
```

---

### `DEFAULT_CALENDAR`

Default Monday-Friday calendar shared by Gantt and Event Scheduler.

```ts
DEFAULT_CALENDAR: {
  id: string;
  name: string;
  timeZone: string;
  workingDays: number[];
  holidays: never[];
  workingHours: { start: string; end: string; };
  hoursPerDay: number;
};
```

---

### `ResolvedCalendarEntity`

Calendar with derived lookup-friendly fields used by schedulers.

```ts
interface ResolvedCalendarEntity {
  readonly calendar: CalendarEntity;
  readonly workingDays: readonly number[];
  readonly workingHours: readonly CalendarResolvedWorkingTimeRange[];
  readonly holidays: ReadonlySet<string>
}
```

---

### `CalendarListLookupContext`

```ts
interface CalendarListLookupContext {
  readonly calendars: readonly CalendarEntity[];
  readonly primaryCalendarId?: CalendarId
}
```

---

### `CalendarLookupTarget`

```ts
export type CalendarLookupTarget = CalendarId | { readonly calendarId?: CalendarId } | undefined;
```

---

# Cell Flash

URL: https://pro.rv-grid.com/api/cell-flash/
Source: src/content/docs/api/cell-flash.md

## Module Extensions

### `CellTemplateProp` (Extended from `@revolist/revogrid`)

```ts
interface CellTemplateProp {
  /**
       * Previous value captured when the flash was requested.
       */
      previousValue?: any;
  /**
       * Direction resolved by the flash plugin.
       */
      flashDirection?: CellFlashDirection;
  /**
       * Active flash state for the rendered cell.
       */
      flashState?: any
}
```

---

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Enables flash feedback for this column.
       *
       * Legacy `(value) => boolean` predicates are supported. Context-aware
       * predicates can inspect the previous value, row model, row type, and edit
       * event metadata, and can return a decision object to customize a flash.
       *
       * @example
       * ```ts
       * const columns = [
       *   { prop: 'name', name: 'Name', flash: value => Boolean(value) },
       *   {
       *     prop: 'price',
       *     name: 'Price',
       *     flash: (value, context) => ({
       *       flash: value !== context.previousValue,
       *       rowFlash: true,
       *       direction: Number(value) > Number(context.previousValue) ? 'up' : 'down',
       *     }),
       *   },
       * ];
       * ```
       */
      flash?: CellFlashPredicate
}
```

---

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  /**
       * Cell flash plugin configuration.
       *
       * @example
       * ```ts
       * const grid = document.querySelector('revo-grid');
       * grid.plugins = [CellFlashPlugin, EventManagerPlugin];
       * grid.cellFlash = {
       *   duration: 1200,
       *   mode: 'cell-and-row',
       *   queue: 'merge',
       * };
       * ```
       */
      cellFlash?: CellFlashConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data property for cell flash configuration.
       *
       * Useful for framework wrappers where all plugin options are passed through
       * one memoized or computed `additionalData` object.
       *
       * @example
       * ```tsx
       * const additionalData = useMemo(() => ({
       *   cellFlash: {
       *     duration: 900,
       *     mode: 'cell-and-row',
       *   },
       * }), []);
       * ```
       */
      cellFlash?: CellFlashConfig
}
```

## Plugin API

### `CellFlashPlugin`

Highlights recently changed cells and rows.

Existing usage with `flash: (value) => true`, `FLASH_CELL_EVENT`, and
`cellFlashArrowTemplate()` remains supported. Configure richer behavior
through `grid.cellFlash` or call the instance methods for manual dashboard
updates.

**Example:**
```typescript
import { CellFlashPlugin, EventManagerPlugin } from '@revolist/revogrid-pro';

const grid = document.querySelector('revo-grid');
grid.plugins = [CellFlashPlugin, EventManagerPlugin];
grid.columns = [
  { prop: 'name', name: 'Name' },
  { prop: 'price', name: 'Price', flash: value => value !== undefined },
];
```

**Example:**
```typescript
grid.cellFlash = {
  mode: 'cell-and-row',
  queue: 'merge',
  duration: 900,
  rowDuration: 1400,
  aria: { enabled: true },
};
```

**Example:**
```typescript
grid.columns = [
  {
    prop: 'inventory',
    name: 'Inventory',
    flash: (value, context) => ({
      flash: value !== context.previousValue,
      rowFlash: Number(value) === 0,
      direction: Number(value) > Number(context.previousValue) ? 'up' : 'down',
      ariaLabel: `Inventory changed to ${value}`,
    }),
  },
];
```

#### Dependencies

- **Event integration** `EventManagerPlugin`: Integrates with EventManagerPlugin edit events for automatic edit flashes.
- **Event integration** `HistoryPlugin`: Integrates with HistoryPlugin undo and redo replay edit events when present.
- **Config integration** `additionalData.cellFlash`: Reads cell flash configuration from additionalData.cellFlash.

```ts
class CellFlashPlugin {
  /**
     * Flashes one cell manually.
     *
     * Use this for live-feed updates or external actions that do not come through
     * RevoGrid edit events. The method keeps the old event-driven behavior intact
     * and only applies an additional manual flash state.
     *
     * @param target Cell coordinates and optional flash metadata.
     *
     * @example
     * ```ts
     * const plugin = grid.getPlugins?.().find(p => p instanceof CellFlashPlugin);
     * plugin?.flashCell({
     *   rowIndex: 3,
     *   prop: 'price',
     *   previousValue: 42,
     *   value: 45,
     *   direction: 'up',
     *   duration: 800,
     * });
     * ```
     */
  flashCell(target: CellFlashCellTarget);

  /**
     * Flashes a batch of changed cells using the same detail shape as the
     * `flashcell` event.
     *
     * Column `flash` predicates are evaluated for each changed prop. Queue and
     * mode options override the configured defaults for this call only.
     *
     * @param detail Batch detail containing changed values, row type, and optional previous values.
     * @param options Optional queue, mode, and duration overrides for this batch.
     *
     * @example
     * ```ts
     * plugin.flashCells(
     *   {
     *     type: 'rgRow',
     *     data: { 0: { price: 45, status: 'Updated' } },
     *     previousData: { 0: { price: 42, status: 'Draft' } },
     *     eventTypes: ['live-feed'],
     *   },
     *   { queue: 'merge', mode: 'cell-and-row' },
     * );
     * ```
     *
     * @example
     * ```ts
     * grid.dispatchEvent(new CustomEvent('flashcell', {
     *   detail: {
     *     type: 'rgRow',
     *     data: { 1: { price: 50 } },
     *     previousData: { 1: { price: 48 } },
     *   },
     * }));
     * ```
     */
  flashCells(detail: FlashBatchDetail, options?: CellFlashApplyOptions);

  /**
     * Flashes one or more rows manually.
     *
     * Row flashes are rendered through `beforerowrender`, so virtualized rows keep
     * the correct visual state when they re-enter the viewport before expiry.
     *
     * @param targets One row target or an array of row targets.
     * @param options Optional queue, mode, and row duration overrides.
     *
     * @example
     * ```ts
     * plugin.flashRows(
     *   [
     *     { rowIndex: 0, direction: 'changed' },
     *     { rowIndex: 4, direction: 'down', rowClassName: 'risk-row-flash' },
     *   ],
     *   { queue: 'merge', rowDuration: 1200 },
     * );
     * ```
     */
  flashRows(targets: CellFlashRowTarget | CellFlashRowTarget[], options?: CellFlashApplyOptions);

  /**
     * Clears active flash state.
     *
     * Without a target, all active cell and row flashes are cleared. Passing a
     * row target clears the row plus all active cell flashes in that row. Passing
     * both `rowIndex` and `prop` clears one cell.
     *
     * @param target Optional cell or row target to clear.
     *
     * @example
     * ```ts
     * plugin.clearFlash(); // clear all flashes
     * plugin.clearFlash({ rowIndex: 2 }); // clear row 2 and its cell flashes
     * plugin.clearFlash({ rowIndex: 2, prop: 'price' }); // clear one cell
     * ```
     */
  clearFlash(target?: Partial<CellFlashCellTarget & CellFlashRowTarget>);

  destroy();
}
```

---

### `cellFlashArrowTemplate`

```ts
cellFlashArrowTemplate: (templateOrOptions?: CellTemplate<DataType<any, ColumnProp>> | CellFlashArrowTemplateOptions | undefined, templateOptions?: CellFlashArrowTemplateOptions | undefined) => CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `resolveCellFlashConfig`

Resolves partial public configuration into the plugin's internal defaults.

**Example:**
```typescript
const config = resolveCellFlashConfig({ duration: 1500, queue: 'merge' });
console.log(config.mode); // "cell"
```

```ts
export function resolveCellFlashConfig(
  config?: CellFlashConfig,
): ResolvedCellFlashConfig;
```

---

### `CellFlashDirection`

Direction metadata attached to an active cell or row flash.

The default resolver returns `up` or `down` for numeric changes,
`changed` for non-numeric value changes, and `none` when no previous value
is available.

**Example:**
```typescript
const columns = [
  {
    prop: 'price',
    name: 'Price',
    flash: (value, context) => ({
      flash: true,
      direction: Number(value) > Number(context.previousValue) ? 'up' : 'down',
    }),
  },
];
```

```ts
/**
 * Direction metadata attached to an active cell or row flash.
 *
 * The default resolver returns `up` or `down` for numeric changes,
 * `changed` for non-numeric value changes, and `none` when no previous value
 * is available.
 *
 * @example
 * ```ts
 * const columns = [
 *   {
 *     prop: 'price',
 *     name: 'Price',
 *     flash: (value, context) => ({
 *       flash: true,
 *       direction: Number(value) > Number(context.previousValue) ? 'up' : 'down',
 *     }),
 *   },
 * ];
 * ```
 */
export type CellFlashDirection = 'up' | 'down' | 'changed' | 'none';
```

---

### `CellFlashMode`

Defines whether flash requests affect cells, rows, or both.

**Example:**
```typescript
grid.cellFlash = {
  mode: 'cell-and-row',
  rowDuration: 1400,
};
```

```ts
/**
 * Defines whether flash requests affect cells, rows, or both.
 *
 * @example
 * ```ts
 * grid.cellFlash = {
 *   mode: 'cell-and-row',
 *   rowDuration: 1400,
 * };
 * ```
 */
export type CellFlashMode = 'cell' | 'row' | 'cell-and-row';
```

---

### `CellFlashQueueMode`

Controls how new flash requests interact with active flashes.

`replace` preserves the legacy behavior by clearing existing flashes before
applying a new batch. `merge` keeps existing flashes active until their own
timers expire.

**Example:**
```typescript
grid.cellFlash = {
  queue: 'merge',
  maxActive: 300,
};
```

```ts
/**
 * Controls how new flash requests interact with active flashes.
 *
 * `replace` preserves the legacy behavior by clearing existing flashes before
 * applying a new batch. `merge` keeps existing flashes active until their own
 * timers expire.
 *
 * @example
 * ```ts
 * grid.cellFlash = {
 *   queue: 'merge',
 *   maxActive: 300,
 * };
 * ```
 */
export type CellFlashQueueMode = 'replace' | 'merge';
```

---

### `CellFlashContext`

Runtime information passed to context-aware column flash predicates and
direction resolvers.

**Example:**
```typescript
const columns = [
  {
    prop: 'status',
    name: 'Status',
    flash: (value, context) => {
      return context.previousValue !== value && context.eventTypes?.includes('edit');
    },
  },
];
```

```ts
interface CellFlashContext {
  /** New value from the edit/manual flash batch. */
    value: unknown;
  /** Previous value captured from the event detail or current row model. */
    previousValue: unknown;
  /** Row index in the target row type. */
    rowIndex: number;
  /** Column property for the changed cell. */
    prop: ColumnProp;
  /** Column definition for the changed cell. */
    column: ColumnRegular;
  /** Current row model, when available from the data provider. */
    model?: DataType;
  /** RevoGrid row bucket, for example `rgRow`, `rowPinStart`, or `rowPinEnd`. */
    type: DimensionRows;
  /** Edit/history event type metadata when emitted by EventManagerPlugin. */
    eventTypes?: string[];
  /** Original flash/edit event detail for advanced consumers. */
    detail?: Partial<BeforeRangeSaveDataDetails>
}
```

---

### `CellFlashDecision`

Per-change decision returned from a context-aware column `flash` predicate.

Returning `true` is equivalent to `{ flash: true }`. Return a decision object
to customize duration, direction, classes, row flashing, or accessibility
text for a specific value change.

**Example:**
```typescript
const columns = [
  {
    prop: 'inventory',
    name: 'Inventory',
    flash: (value, context) => ({
      flash: true,
      rowFlash: Number(value) === 0,
      direction: Number(value) > Number(context.previousValue) ? 'up' : 'down',
      className: Number(value) === 0 ? 'cell-flash-danger' : undefined,
      ariaLabel: `Inventory changed to ${value}`,
    }),
  },
];
```

```ts
interface CellFlashDecision {
  /** Whether the changed cell should flash. Defaults to true for decision objects. */
    flash?: boolean;
  /** Whether the containing row should flash for this change. */
    rowFlash?: boolean;
  /** Cell flash duration in milliseconds for this change. */
    duration?: number;
  /** Row flash duration in milliseconds for this change. */
    rowDuration?: number;
  /** Direction metadata for templates, attributes, and CSS selectors. */
    direction?: CellFlashDirection;
  /** Additional class applied to the flashing cell. */
    className?: string;
  /** Additional class applied to the flashing row. */
    rowClassName?: string;
  /** Message announced through the plugin aria-live region when enabled. */
    ariaLabel?: string
}
```

---

### `CellFlashPredicate`

Column flash configuration.

Legacy predicates that only accept `(value) => boolean` still work. New
predicates may accept the second `CellFlashContext` argument and return a
`CellFlashDecision`.

**Example:**
```typescript
const columns = [
  { prop: 'name', name: 'Name', flash: true },
  {
    prop: 'price',
    name: 'Price',
    flash: (value, context) => ({
      flash: value !== context.previousValue,
      direction: Number(value) > Number(context.previousValue) ? 'up' : 'down',
    }),
  },
];
```

```ts
/**
 * Column flash configuration.
 *
 * Legacy predicates that only accept `(value) = > boolean` still work. New
 * predicates may accept the second `CellFlashContext` argument and return a
 * `CellFlashDecision`.
 *
 * @example
 * ```ts
 * const columns = [
 *   { prop: 'name', name: 'Name', flash: true },
 *   {
 *     prop: 'price',
 *     name: 'Price',
 *     flash: (value, context) => ({
 *       flash: value !== context.previousValue,
 *       direction: Number(value) > Number(context.previousValue) ? 'up' : 'down',
 *     }),
 *   },
 * ];
 * ```
 */
export type CellFlashPredicate =
  | boolean
  | ((value: unknown, context: CellFlashContext) => boolean | CellFlashDecision);
```

---

### `CellFlashAriaConfig`

Accessibility announcement configuration for cell and row flashes.

**Example:**
```typescript
grid.cellFlash = {
  aria: {
    enabled: true,
    label: state => `Row ${state.rowIndex + 1} changed`,
  },
};
```

```ts
interface CellFlashAriaConfig {
  /** Enables aria-live announcements for flash requests. */
    enabled?: boolean;
  /** Live-region politeness. Defaults to `polite`. */
    live?: 'off' | 'polite' | 'assertive';
  /** Controls the `aria-atomic` attribute on the live region. Defaults to true. */
    atomic?: boolean;
  /** CSS class applied to the generated live region. */
    liveRegionClassName?: string;
  /** Static label or callback that returns the announcement text. */
    label?: string | ((state: CellFlashState) => string)
}
```

---

### `CellFlashLabels`

User-facing labels used by the plugin.

These labels are used for default accessibility announcements. A decision or
manual target `ariaLabel` still has highest priority, followed by
`aria.label`, then these per-kind labels.

**Example:**
```typescript
grid.cellFlash = {
  aria: true,
  labels: {
    cellUpdated: state => `Updated ${String(state.prop)} on row ${state.rowIndex + 1}`,
    rowUpdated: state => `Updated row ${state.rowIndex + 1}`,
  },
};
```

```ts
interface CellFlashLabels {
  /** Default announcement for cell flashes. */
    cellUpdated?: string | ((state: CellFlashState) => string);
  /** Default announcement for row flashes. */
    rowUpdated?: string | ((state: CellFlashState) => string)
}
```

---

### `CellFlashConfig`

Public plugin configuration accepted by `grid.cellFlash` and
`additionalData.cellFlash`.

Defaults preserve the original plugin behavior: flashing is enabled,
cell-only, lasts 1000ms, replaces active flashes on each event, and clears on
source reset.

**Example:**
```typescript
grid.plugins = [CellFlashPlugin, EventManagerPlugin];
grid.cellFlash = {
  duration: 1200,
  mode: 'cell-and-row',
  queue: 'merge',
  rowClassName: 'price-row-flash',
  aria: { enabled: true },
  labels: {
    cellUpdated: state => `Price cell changed on row ${state.rowIndex + 1}`,
    rowUpdated: state => `Market row ${state.rowIndex + 1} changed`,
  },
  directionResolver: ({ value, previousValue }) => {
    if (Number(value) > Number(previousValue)) return 'up';
    if (Number(value) < Number(previousValue)) return 'down';
    return 'changed';
  },
};
```

```ts
interface CellFlashConfig {
  /** Enables or disables new flash requests. */
    enabled?: boolean;
  /** Default cell flash duration in milliseconds. */
    duration?: number;
  /** Default row flash duration in milliseconds. */
    rowDuration?: number;
  /** Default flash target mode. */
    mode?: CellFlashMode;
  /** Default active flash queue behavior. */
    queue?: CellFlashQueueMode;
  /** Maximum number of active cell and row flashes retained at once. */
    maxActive?: number;
  /** Clears active flash state when the grid source changes. */
    clearOnSourceChange?: boolean;
  /** Disables animation when the user prefers reduced motion. */
    respectReducedMotion?: boolean;
  /** Enables or configures aria-live announcements. */
    aria?: boolean | CellFlashAriaConfig;
  /** User-facing labels used by default plugin announcements. */
    labels?: CellFlashLabels;
  /** Base class applied to flashing cells. */
    className?: string;
  /** Base class applied to flashing rows. */
    rowClassName?: string;
  /** Optional custom direction resolver used before the default resolver. */
    directionResolver?: (context: CellFlashContext) => CellFlashDirection
}
```

---

### `ResolvedCellFlashConfig`

```ts
interface ResolvedCellFlashConfig {
  enabled: boolean;
  duration: number;
  rowDuration: number;
  mode: CellFlashMode;
  queue: CellFlashQueueMode;
  maxActive: number;
  clearOnSourceChange: boolean;
  respectReducedMotion: boolean;
  aria: Required<Pick<CellFlashAriaConfig, 'enabled' | 'live' | 'atomic' | 'liveRegionClassName'>>
      & Pick<CellFlashAriaConfig, 'label'>;
  labels: Required<CellFlashLabels>;
  className: string;
  rowClassName: string;
  directionResolver?: (context: CellFlashContext) => CellFlashDirection
}
```

---

### `CellFlashState`

```ts
interface CellFlashState {
  rowIndex: number;
  prop?: ColumnProp;
  type: DimensionRows;
  value?: unknown;
  previousValue?: unknown;
  direction: CellFlashDirection;
  className?: string;
  rowClassName?: string;
  ariaLabel?: string;
  startedAt: number;
  duration: number
}
```

---

### `CellFlashCellTarget`

Target accepted by `CellFlashPlugin.flashCell()`.

**Example:**
```typescript
const plugin = grid.getPlugins?.().find(p => p instanceof CellFlashPlugin);
plugin?.flashCell({
  rowIndex: 0,
  prop: 'price',
  previousValue: 42,
  value: 47,
  direction: 'up',
});
```

```ts
interface CellFlashCellTarget {
  rowIndex: number;
  prop: ColumnProp;
  type?: DimensionRows;
  value?: unknown;
  previousValue?: unknown;
  duration?: number;
  direction?: CellFlashDirection;
  className?: string;
  ariaLabel?: string
}
```

---

### `CellFlashRowTarget`

Target accepted by `CellFlashPlugin.flashRows()`.

**Example:**
```typescript
const plugin = grid.getPlugins?.().find(p => p instanceof CellFlashPlugin);
plugin?.flashRows([
  { rowIndex: 2, direction: 'changed', rowClassName: 'row-flash-warning' },
  { rowIndex: 5, direction: 'down' },
]);
```

```ts
interface CellFlashRowTarget {
  rowIndex: number;
  type?: DimensionRows;
  duration?: number;
  direction?: CellFlashDirection;
  rowClassName?: string;
  ariaLabel?: string
}
```

---

### `CellFlashApplyOptions`

Per-call options for manual and event-driven flash batches.

**Example:**
```typescript
plugin.flashCells(
  { type: 'rgRow', data: { 0: { price: 12 } }, previousData: { 0: { price: 10 } } },
  { queue: 'merge', mode: 'cell-and-row', duration: 800 },
);
```

```ts
interface CellFlashApplyOptions {
  queue?: CellFlashQueueMode;
  mode?: CellFlashMode;
  duration?: number;
  rowDuration?: number
}
```

---

### `CellFlashTemplatePropExtension`

```ts
interface CellFlashTemplatePropExtension {
  previousValue?: any;
  flashDirection?: CellFlashDirection;
  flashState?: any
}
```

---

### `CellFlashArrowTemplateOptions`

Options for `cellFlashArrowTemplate()`.

Defaults preserve the original helper output: wrapper class `cell-flash`,
arrow class `cell-flash-arrow`, `up`/`down`/`changed` direction classes,
and `↑` / `↓` symbols.

**Example:**
```typescript
cellTemplate: cellFlashArrowTemplate({
  symbols: { up: '+', down: '-', changed: '~' },
  className: 'market-flash',
  arrowClassName: 'market-flash-icon',
  directionClassNames: { up: 'positive', down: 'negative' },
})
```

```ts
interface CellFlashArrowTemplateOptions {
  /** Direction symbols rendered before the cell content. */
    symbols?: Partial<Record<CellFlashDirection, string>>;
  /** Wrapper class applied around the arrow and cell content. */
    className?: string;
  /** Class applied to the symbol element. */
    arrowClassName?: string;
  /** Direction-specific wrapper classes. */
    directionClassNames?: Partial<Record<CellFlashDirection, string>>
}
```

---

### `CellFlashTemplateParams` (Extended from `index.ts`)

```ts
export type CellFlashTemplateParams = CellTemplateProp & CellFlashTemplatePropExtension;
```

---

# Cell Focus

URL: https://pro.rv-grid.com/api/cell-focus/
Source: src/content/docs/api/cell-focus.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * The focus function for the column.
       */
      focus?: (detail: BeforeSaveDataDetails) => boolean
}
```

## Plugin API

### `CellColumnFocusVerifyPlugin`

The CellColumnFocusVerifyPlugin is a RevoGrid plugin that enables custom focus
verification logic for cells based on their column configurations. This plugin
intercepts the cell focus initialization event to apply additional validation rules
defined at the column level, ensuring that only cells meeting specific criteria
can receive focus.

**Key Features**:
- Listens to the `beforecellfocusinit` event, allowing for pre-focus validation.
- Utilizes column-level focus functions to determine whether a cell can be focused.
- Prevents default focus behavior if the column's focus condition is not satisfied,
  enabling dynamic user interaction control based on custom logic.

**Usage**:
- Integrate this plugin into RevoGrid by adding it to the grid's plugin array.
- Define custom focus validation logic within the column definition using the `focus`
  property, which should be a function that returns a boolean based on the event detail.

### Example
```ts
import { CellColumnFocusVerifyPlugin } from './cell-column-focus-verify';

const grid = document.createElement('revo-grid');
grid.plugins = [CellColumnFocusVerifyPlugin];

grid.columns = [
  {
    prop: 'num',
    name: 'Numeric Column',
    focus: (detail) => detail.value > 10, // Custom focus validation logic
  },
];
```

```ts
class CellColumnFocusVerifyPlugin {}
```

---

# Cell Link

URL: https://pro.rv-grid.com/api/cell-link/
Source: src/content/docs/api/cell-link.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  link?: LinkConfig | any
}
```

## Plugin API

### `linkRenderer`

The `linkRenderer` is a custom cell editor for RevoGrid that provides a link input
to edit URL values directly within the grid cells.

**Features**:
- Renders a link element for cells, allowing users to click and navigate to URLs
- Supports different link configurations (target, styling, etc.)
- Extracts protocols from displayed text while preserving the full URL for navigation
- Automatically dispatches a `celledit` event upon change, updating the grid's data model

**Usage**:
- Import `linkRenderer` and assign it to the `cellTemplate` property of a column in the RevoGrid.
- Configure link behavior using the `linkConfig` property.
- Ideal for columns that contain URLs or links to external resources.

### Example
```typescript
import { linkRenderer } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'website',
    name: 'Website',
    cellTemplate: linkRenderer,
    link: {
      target: '_blank',
      showProtocol: false,
      className: 'custom-link',
    },
  },
];
```

**Event Handling**:
- The `linkRenderer` dispatches a `celledit` event whenever the link value changes.
- The event detail contains:
  - `rgCol`: The column index of the edited cell.
  - `rgRow`: The row index of the edited cell.
  - `type`: The type of the cell.
  - `prop`: The property of the cell being edited.
  - `val`: The new URL value.
  - `preventFocus`: A flag to control grid focus behavior (default: `false`).

This editor is particularly useful in scenarios where users need to view and interact with
URLs directly from the grid, providing a quick and user-friendly interface for link data.

```ts
linkRenderer: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

# Cell Merge

URL: https://pro.rv-grid.com/api/cell-merge/
Source: src/content/docs/api/cell-merge.md

## Module Extensions

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
      * Additional data property for cell merge configuration.
      *
      * @deprecated Use `grid.cellMerge` instead.
      * @example
      * grid.additionalData = {
      *   cellMerge: [
      *     {
      *       row: 0,
      *       column: 0,
      *       rowSpan: 2,
      *       colSpan: 2,
      *       rowType: 'rgRow',
      *       colType: 'rgCol',
      *     }
      *   ]
      * }
      */
      cellMerge?: MergeData[]
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  cellMerge?: MergeData[];
  'cell-merge'?: MergeData[]
}
```

## Plugin API

### `CellMergePlugin`

The `CellMergePlugin` is a RevoGrid plugin designed to manage and render merged cells within a grid.
It allows users to visually and functionally combine multiple adjacent cells into a single larger cell,
offering a more cohesive data presentation within the grid interface.

**Key Features**:
- Merging Logic: Extends the size of specified cells and hides cells covered by the merged area.
- Event Management: Overrides grid events and focus behavior to accommodate hidden cells due to merging.
- Dynamic Updates: Listens for data changes and adjusts merged configurations accordingly.
- UI Rendering: Adjusts cell sizes and parameters for merged cells during rendering.

**Usage**:
- This plugin should be included in the grid's plugin array to enable cell merging functionality.
- Configure the merge data through the grid's `cellMerge` property to define which cells should be merged.

### Example
```typescript
import { CellMergePlugin } from './cell-merge-plugin';

const grid = document.createElement('revo-grid');
grid.plugins = [CellMergePlugin]; // Add merge plugin
grid.cellMerge = [
  { row: 1, column: 1, rowSpan: 2, colSpan: 2 },
];
```

Events:
- Listens to a variety of events like `APPLY_RANGE_EVENT`, `FOCUS_APPLY_EVENT`, etc., to handle merge configurations and rendering.

#### Dependencies

- **Event integration** `APPLY_RANGE_EVENT`, `FOCUS_APPLY_EVENT`, `EDIT_RENDER_EVENT`: Integrates with range, focus, and edit overlay events to preserve merged-cell behavior.
- **Config integration** `grid.cellMerge`: Reads merge configuration from the grid cellMerge DOM property.

```ts
class CellMergePlugin {
  destroy(): void;
}
```

---

### `MergeData`

Represents a range of cells that should be merged.
The coordinates are relative to the top-left cell of the range.

```ts
/**
 * Represents a range of cells that should be merged.
 * The coordinates are relative to the top-left cell of the range.
 */
export type MergeData = {
  /**
   * The row index of the top-left cell of the range.
   */
  row: number;

  /**
   * The column index of the top-left cell of the range.
   */
  column: number;

  /**
   * The number of rows to span. If not specified, the range will span only one row.
   */
  rowSpan?: number;

  /**
   * The type of the row dimension. If not specified, it will default to 'rgRow'.
   */
  rowType?: DimensionRows;

  /**
   * The number of columns to span. If not specified, the range will span only one column.
   */
  colSpan?: number;

  /**
   * The type of the column dimension. If not specified, it will default to 'rgCol'.
   */
  colType?: DimensionCols;
};
```

---

### `MergeRowCache`

```ts
export type MergeRowCache = Partial<Record<MultiDimensionType, CellCache>>;
```

---

### `MergeCache`

```ts
export type MergeCache = Partial<Record<MultiDimensionType, { [key: number]: MergeRowCache }>>;
```

---

### `getCellMergeExcelRanges`

```ts
export function getCellMergeExcelRanges(
  context: CellMergeExcelExportContext = {},
): CellMergeExcelRange[];
```

---

### `getCellMergeExcelProviderOptions`

```ts
export function getCellMergeExcelProviderOptions(
  context: CellMergeExcelExportContext = {},
): CellMergeExcelProviderOptions;
```

---

### `applyCellMergeWriteExcelFileSpans`

```ts
export function applyCellMergeWriteExcelFileSpans<TCell extends CellMergeWriteExcelFileCell>({
  cellRows,
  inPlace,
  ...context
}: ApplyCellMergeWriteExcelFileSpansOptions<TCell>): TCell[][];
```

---

### `CellMergeExcelSegment`

```ts
export type CellMergeExcelSegment = {
  /**
   * Segment start in the export matrix before the generated header offset is
   * applied. Omit when segment lengths are supplied in grid order.
   */
  start?: number;
  /** Number of rows or columns in the segment. */
  length?: number;
};
```

---

### `CellMergeExcelSegments`

```ts
export type CellMergeExcelSegments<T extends string> = Partial<Record<T, number | CellMergeExcelSegment>>;
```

---

### `CellMergeExcelExportContext`

```ts
export type CellMergeExcelExportContext = {
  /** Explicit merge data. Wins over merge data read from `revogrid`. */
  cellMerge?: MergeData[];
  /** Optional grid element source for `cellMerge` or legacy `cell-merge`. */
  revogrid?: Pick<HTMLRevoGridElement, 'cellMerge'> & Partial<Record<'cell-merge', MergeData[]>>;
  /**
   * Generated header rows before data rows. ExportExcel currently generates one
   * header row, so this defaults to 1.
   */
  headerRows?: number;
  /**
   * Row segment lengths or starts in export data-row order. Starts are counted
   * after generated header rows; the helper adds `headerRows`.
   */
  rowSegments?: CellMergeExcelSegments<DimensionRows>;
  /**
   * Column segment lengths or starts in export column order.
   */
  columnSegments?: CellMergeExcelSegments<DimensionCols>;
};
```

---

### `CellMergeExcelRange`

```ts
export type CellMergeExcelRange = {
  /** Zero-based start row in the provider matrix, including generated headers. */
  startRow: number;
  /** Zero-based start column in the provider matrix. */
  startColumn: number;
  /** Zero-based end row in the provider matrix, including generated headers. */
  endRow: number;
  /** Zero-based end column in the provider matrix. */
  endColumn: number;
  rowSpan: number;
  columnSpan: number;
  rowType: DimensionRows;
  colType: DimensionCols;
  source: MergeData;
};
```

---

### `CellMergeExcelProviderOptions`

```ts
export type CellMergeExcelProviderOptions = {
  /** Generic provider merge ranges in zero-based export matrix coordinates. */
  mergeRanges: CellMergeExcelRange[];
};
```

---

### `CellMergeWriteExcelFileCell`

```ts
export type CellMergeWriteExcelFileCell = Record<string, unknown> | null | undefined;
```

---

### `ApplyCellMergeWriteExcelFileSpansOptions` (Extended from `index.ts`)

```ts
export type ApplyCellMergeWriteExcelFileSpansOptions<TCell extends CellMergeWriteExcelFileCell> =
  CellMergeExcelExportContext & {
    cellRows: TCell[][];
    /** Mutate the supplied `cellRows` matrix instead of returning a patched copy. */
    inPlace?: boolean;
  };
```

---

### `MergeCacheService`

Service responsible for managing the cell merge cache.
This service handles all operations related to storing, retrieving, and manipulating
the cache of merged cells, separating these concerns from the main plugin logic.

```ts
class MergeCacheService {
  /**
     * Clears the entire merge cache
     */
  public clearCache(): void;

  /**
     * Gets the current merge cache
     */
  public getCache(): MergeCache;

  /**
     * Check cache for merged cells and return spans
     */
  public getSpans(types: AllDimensionType, startX: number, startY: number);

  /**
     * High level mapping start
     */
  public setMerge(data: MergeData[] | undefined);
}
```

---

# Cell Validate

URL: https://pro.rv-grid.com/api/cell-validate/
Source: src/content/docs/api/cell-validate.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

Adds validation properties to ColumnRegular.

```ts
interface ColumnRegular {
  /**
       * Optional property to enable soft validation, when set to true, the cell will be saved if it is invalid.
       */
      softValidation?: boolean;
  /**
       * Optional function to provide validation message text for invalid cells.
       * @param cellValue - The value of the cell.
       * @param model - The full row model. During CellValidatePlugin edit validation,
       * this includes the pending row patch for the edit being validated.
       * @param column - The column definition that owns the validator.
       * @returns The validation message for the cell.
       */
      validationTooltip?(cellValue?: any, model?: any, column?: ColumnRegular): any;
  /**
       * Optional severity used by validation renderers for invalid cell styling.
       * @param cellValue - The value of the cell.
       * @param model - The full row model for the cell.
       * @param column - The column definition that owns the validator.
       * Defaults to `error`.
       */
      validationSeverity?(cellValue?: any, model?: any, column?: ColumnRegular): ValidationSeverity;
  /**
       * Optional properties applied by validationRenderer when a cell is invalid.
       */
      invalidProperties?: ColumnRegular['cellProperties'];
  /**
       * Optional function to validate the cell value.
       * @param cellValue - The value of the cell.
       * @param model - The full row model containing all column values. During
       * CellValidatePlugin edit validation, this includes the pending row patch.
       * @returns `true` if the value is valid, otherwise `false`.
       */
      validate?(cellValue?: any, model?: any): boolean
}
```

## Plugin API

### `CellValidatePlugin`

The `CellValidatePlugin` is a RevoGrid plugin designed to enforce cell validation within
the grid, ensuring data integrity by preventing invalid data entries from being saved.
It integrates seamlessly with RevoGrid's event system and requires the `EventManagerPlugin`
for full functionality.

 **Features**:
- Resolves validation before unified grid edits are published to normal edit consumers.
  For row-header-owned batches and clipboard `valid-cells` mode, invalid cells are
  removed and highlighted while valid cells continue. Other edit origins retain their
  existing validation behavior.
  The validator receives a candidate row model that includes the pending row patch, so
  cross-column validation works for single-cell edits and pasted row batches.
- Adds visual indicators to invalid cells by tagging them during the `BEFORE_CELL_RENDER_EVENT`,
  providing immediate feedback to users about validation errors.
- Integrates custom validation logic through column definitions, supporting both strict
  and soft validation modes.
- Utilizes `validationRenderer` for rendering cells with validation feedback, allowing
  customization of how invalid cells are displayed using tooltips or other UI elements.

**Usage**:
- Implement this plugin in a RevoGrid instance to enable cell validation logic and improve
  data quality by preventing erroneous entries.

### Example
```ts
import { CellValidatePlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [CellValidatePlugin];
```

#### Dependencies

- **Required** `EventManagerPlugin`: Requires EventManagerPlugin to receive edit events for validation.

```ts
class CellValidatePlugin {}
```

---

### `isValidationRendererFunction`

```ts
export function isValidationRendererFunction<T extends RendererFunction>(
  fn: T | undefined,
): fn is ValidationRendererFunction<T>;
```

---

### `invalidCellProps`

```ts
export function invalidCellProps(invalid = false);
```

---

### `ValidationSeverity`

Visual severity used by `validationRenderer` for invalid-cell styling and tooltip type.

```ts
/** Visual severity used by `validationRenderer` for invalid-cell styling and tooltip type. */
export type ValidationSeverity = 'error' | 'warning' | 'info';
```

---

### `ValidationIndicatorPlacement`

Position of the invalid-cell indicator rendered by `validationRenderer`.

```ts
/** Position of the invalid-cell indicator rendered by `validationRenderer`. */
export type ValidationIndicatorPlacement = 'corner' | 'start' | 'end' | 'none';
```

---

### `ValidationMessagePlacement`

Controls whether validation messages are exposed as tooltip text, inline text, both, or hidden.

```ts
/** Controls whether validation messages are exposed as tooltip text, inline text, both, or hidden. */
export type ValidationMessagePlacement = 'tooltip' | 'inline' | 'both' | 'none';
```

---

### `ValidationRendererContext`

Runtime context passed to advanced validation renderer callbacks.

```ts
interface ValidationRendererContext {
  /** Cell value passed by RevoGrid into the cell renderer. */
    value: any;
  /** Full row model for the rendered cell. */
    model?: any;
  /** Column definition being rendered. */
    column: ColumnRegular;
  /** Whether `column.validate(value, model)` failed for this cell. */
    invalid: boolean;
  /** Resolved severity for the invalid cell. */
    severity: ValidationSeverity
}
```

---

### `ValidationRendererOptions`

Options for `validationRenderer`.

Existing `template` and `invalidProperties` usage remains supported. New options let
applications choose severity-aware styling, move the validation indicator, and render
messages as tooltips, inline text, both, or neither.

```ts
interface ValidationRendererOptions {
  /** Existing cell template to wrap with validation feedback. */
    template?: ColumnRegular['cellTemplate'];
  /** Extra cell properties applied only when the cell is invalid. */
    invalidProperties?: ColumnRegular['cellProperties'];
  /** Static or callback-driven severity for invalid cell styling. */
    severity?: ValidationSeverity | ((context: Omit<ValidationRendererContext, 'severity'>) => ValidationSeverity);
  /** Where to render the validation indicator. Defaults to `corner`. */
    indicatorPlacement?: ValidationIndicatorPlacement;
  /** Where to expose the validation message. Defaults to `tooltip`. */
    messagePlacement?: ValidationMessagePlacement;
  /** Optional message resolver. Falls back to `column.validationTooltip`. */
    message?: (context: ValidationRendererContext) => any
}
```

---

### `validationRenderer`

Extends the `ColumnRegular` interface from the RevoGrid framework to include
properties and functions for validating cell data and rendering validation feedback.
It facilitates cell validation and provides visual indicators for invalid cells.

 **Features**:
- Extends `ColumnRegular` with:
  - `softValidation`: An optional boolean indicating if a cell should be saved even when invalid.
  - `validationTooltip`: A function to provide validation message text for invalid cells.
  - `validationSeverity`: A function to choose `error`, `warning`, or `info` styling per invalid cell.
  - `validate`: A function to determine if a cell's value is valid.
- The `invalidCellProps` function returns cell properties indicating whether a cell is invalid.
- The `validationRenderer` function returns a renderer with:
  - `cellProperties`: Adds validation styles and properties to cells, highlighting them when invalid.
  - `cellTemplate`: Renders invalid-cell indicators and optional tooltip or inline messages.

**Usage**:
- Integrate these extensions into the RevoGrid column configuration to enable cell validation.
- Customize cell templates and properties using `validationRenderer` to enhance the grid's UI.

### Example
```typescript
import { validationRenderer } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'num',
    name: 'Linear',
    validate: (value) => value >= 0 && value <= 40,
    validationTooltip: (value) => `Value ${value} is out of range`,
    ...validationRenderer({
      severity: 'error',
      indicatorPlacement: 'corner',
      messagePlacement: 'tooltip',
    }),
  },
];
```

This module is crucial for applications requiring data validation, improving user experience
by providing immediate feedback for data entry errors within the RevoGrid framework.

```ts
validationRenderer: ({ template, invalidProperties, severity, indicatorPlacement, messagePlacement, message, }?: ValidationRendererOptions) => Pick<Required<ColumnRegular<ColumnProp, DataType<any, ColumnProp>>>, "cellTemplate" | "cellProperties">;
```

---

### `validateNumber`

Validates if the value is a number.

**@param** value - The value to validate.

**@returns** `true` if the value is a number, otherwise `false`.

```ts
export function validateNumber(value: any): boolean;
```

---

### `validateBoolean`

Validates if the value is a boolean.

**@param** value - The value to validate.

**@returns** `true` if the value is a boolean, otherwise `false`.

```ts
export function validateBoolean(value: any): boolean;
```

---

### `validateString`

Validates if the value is a string.

**@param** value - The value to validate.

**@returns** `true` if the value is a string, otherwise `false`.

```ts
export function validateString(value: any): boolean;
```

---

### `validateInteger`

Validates if the value is an integer.

**@param** value - The value to validate.

**@returns** `true` if the value is an integer, otherwise `false`.

```ts
export function validateInteger(value: any): boolean;
```

---

### `validateDecimal`

Validates if the value is a decimal.

**@param** value - The value to validate.

**@returns** `true` if the value is a decimal, otherwise `false`.

```ts
export function validateDecimal(value: any): boolean;
```

---

### `validateRange`

Validates if the value is within a specific range.

**@param** value - The value to validate.

**@param** min - The minimum value.

**@param** max - The maximum value.

**@returns** `true` if the value is within the range, otherwise `false`.

```ts
export function validateRange(value: any, min: number, max: number): boolean;
```

---

### `validateArray`

Validates if the value is an array.

**@param** value - The value to validate.

**@returns** `true` if the value is an array, otherwise `false`.

```ts
export function validateArray(value: any): boolean;
```

---

### `validateObject`

Validates if the value is an object.

**@param** value - The value to validate.

**@returns** `true` if the value is an object, otherwise `false`.

```ts
export function validateObject(value: any): boolean;
```

---

### `validateNull`

Validates if the value is null.

**@param** value - The value to validate.

**@returns** `true` if the value is null, otherwise `false`.

```ts
export function validateNull(value: any): boolean;
```

---

### `validateUndefined`

Validates if the value is undefined.

**@param** value - The value to validate.

**@returns** `true` if the value is undefined, otherwise `false`.

```ts
export function validateUndefined(value: any): boolean;
```

---

### `validateDate`

Validates if the value is a date.

**@param** value - The value to validate.

**@returns** `true` if the value is a date, otherwise `false`.

```ts
export function validateDate(value: any): boolean;
```

---

### `validateRegex`

Validates if the value matches the provided regular expression.

**@param** value - The value to validate.

**@param** regex - The regular expression to test against.

**@returns** `true` if the value matches the regular expression, otherwise `false`.

```ts
export function validateRegex(value: any, regex: RegExp): boolean;
```

---

### `validateEnum`

Validates if the value is one of the allowed values.

**@param** value - The value to validate.

**@param** allowedValues - The array of allowed values.

**@returns** `true` if the value is one of the allowed values, otherwise `false`.

```ts
export function validateEnum(value: any, allowedValues: any[]): boolean;
```

---

### `validatePositive`

Validates if the value is a positive number.

**@param** value - The value to validate.

**@returns** `true` if the value is a positive number, otherwise `false`.

```ts
export function validatePositive(value: any): boolean;
```

---

### `validateNegative`

Validates if the value is a negative number.

**@param** value - The value to validate.

**@returns** `true` if the value is a negative number, otherwise `false`.

```ts
export function validateNegative(value: any): boolean;
```

---

### `validateFinite`

Validates if the value is a finite number.

**@param** value - The value to validate.

**@returns** `true` if the value is a finite number, otherwise `false`.

```ts
export function validateFinite(value: any): boolean;
```

---

### `validateEmptyString`

Validates if the value is an empty string.

**@param** value - The value to validate.

**@returns** `true` if the value is an empty string, otherwise `false`.

```ts
export function validateEmptyString(value: any): boolean;
```

---

### `validateNonEmptyString`

Validates if the value is a non-empty string.

**@param** value - The value to validate.

**@returns** `true` if the value is a non-empty string, otherwise `false`.

```ts
export function validateNonEmptyString(value: any): boolean;
```

---

### `validateInstance`

Validates if the value is an instance of a class.

**@param** value - The value to validate.

**@param** cls - The class to test against.

**@returns** `true` if the value is an instance of the class, otherwise `false`.

```ts
export function validateInstance(value: any, cls: any): boolean;
```

---

### `parseBoolean`

Utilities used in the RevoGrid project to assist in converting
various data types to a boolean value. This function is essential for data processing
tasks where boolean values may be represented in different formats.

 **Features**:
- Accepts inputs of type boolean, number, or string, and attempts to convert them to
  a boolean value.
- For numbers, returns `true` if the value is `1`, otherwise `false`.
- For strings, it normalizes the input to lowercase and trims whitespace, returning
  `true` for common affirmative representations ('true', 'yes', '1') and `false` for
  negative representations ('false', 'no', '0').
- Returns `undefined` if the input cannot be reliably converted to a boolean, allowing
  for error handling or default value assignment in calling code.

**Usage**:
- Call `parseBoolean` when you need a flexible utility to standardize various input
  representations into a boolean format, particularly useful in grid configuration
  or data validation scenarios.

### Example
```typescript
const isEnabled = parseBoolean('yes'); // Returns true
const isDisabled = parseBoolean(0); // Returns false
```

```ts
export function parseBoolean(value: any): boolean | undefined;
```

---

# Charts

URL: https://pro.rv-grid.com/api/charts/
Source: src/content/docs/api/charts.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
      * The position of the bars in the chart.
      */
      barPosition?: 'top' | 'bottom';
  /**
       * Define badge styles for the cell.
       */
      badgeStyles?: Record<string, {
        backgroundColor: string;
        /** Optional authored text color. Explicit Data Grid Formatting text color overrides it. */
        color?: string;
      }>;
  /**
       * Whether to render the shape as a rectangular.
       */
      rectangular?: boolean;
  /**
       * Maximum number of stars in the rating. Default is 5.
       */
      maxStars?: number;
  /**
       * Minimum value for the progress line. Default is 0.
       */
      minValue?: number;
  /**
       * Maximum value for the progress line. Default is 100.
       */
      maxValue?: number;
  /** Midpoint threshold used by custom three-stop heatmaps. */
      midValue?: number;
  /** Custom color at the heatmap minimum threshold. */
      lowColor?: string;
  /** Custom color at the heatmap midpoint threshold. */
      midColor?: string;
  /** Custom color at the heatmap maximum threshold. */
      highColor?: string;
  /** Legacy built-in heatmap palette used when custom colors are absent. */
      colorMap?: 'heatmap' | 'coldmap';
  /**
       * Define thresholds for the cell.
       */
      thresholds?: ThresholdConfig[];
  /**
       * Format the value of the cell.
       */
      formatValue?: (value: number, column: ColumnRegular) => string;
  /**
       * Function to calculate progress based on row data.
       * This allows connecting multiple fields to determine progress.
       * @param config Configuration object containing model, data, and prop
       * @returns A number between 0 and 100 representing progress
       */
      progress?: (config: { model: DataType; data: DataType[]; prop: ColumnProp }) => number;
  /** Visible timeline range. Invalid or inverted ranges fall back to 0–100. */
      timelineRange?: { start: number; end: number };
  /** Localized accessible name for a rendered timeline. */
      timelineAriaLabel?: string | ((events: readonly TimelineEvent[]) => string);
  /** Localized accessible name for a sparkline. */
      sparklineAriaLabel?: string | ((values: readonly number[]) => string);
  /** Localized accessible name for a rating visualization. */
      ratingAriaLabel?: string | ((value: number, maximum: number) => string)
}
```

## Plugin API

### `progressLineRenderer`

The `progressLineRenderer` is a custom cell renderer for RevoGrid that provides a visual
representation of progress as a horizontal line within grid cells. This renderer effectively
communicates the completion level of a numeric value relative to a defined range.

 **Features**:
- Displays a progress line that visually indicates the percentage completion within specified
  minimum and maximum values.
- Shows a percentage label beside the progress bar, formatted to one decimal place for precision.
- Automatically normalizes values to ensure accurate representation within the defined range.
- Configurable through column properties such as `minValue` and `maxValue`.
- Supports a custom progress function to calculate progress based on row data.

**Usage**:
- Import `progressLineRenderer` and use it as the `cellTemplate` in your RevoGrid's column configuration.
- Specify `minValue` and `maxValue` for each column to define the range for progress calculation.
- Optionally provide a `progress` function to calculate progress based on row data.

### Example
```typescript
import { progressLineRenderer } from './charts/progress-line.renderer';

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'score',
    name: 'Completion Rate',
    minValue: 0,
    maxValue: 100,
    cellTemplate: progressLineRenderer,
    // Optional: Custom progress calculation
    progress: (config) => {
      // Calculate progress based on multiple fields
      const completed = config.model.completedTasks || 0;
      const total = config.model.totalTasks || 1;
      return (completed / total) * 100;
    }
  },
];
```

This renderer is suitable for applications where tracking progression or percentage completion
is necessary, such as performance dashboards, goal tracking systems, or any scenario where a
visual progress indicator is beneficial.

```ts
progressLineRenderer: CellTemplate<DataType<any, ColumnProp>>;
```

---

### `renderProgressBar`

Shared framework-neutral progress primitive used by chart cell renderers.

```ts
export function renderProgressBar(h: ProgressHyperFunc, {
  value,
  min = 0,
  max = 100,
  ariaLabel,
  className,
  fillClass,
}: ProgressBarProps);
```

---

### `ProgressBarProps`

```ts
interface ProgressBarProps {
  value: number;
  min?: number;
  max?: number;
  ariaLabel?: string;
  className?: string;
  fillClass?: string | Record<string, boolean>
}
```

---

### `progressBarRenderer`

Compact progress-only RevoGrid cell renderer.

```ts
progressBarRenderer: CellTemplate<DataType<any, ColumnProp>>;
```

---

### `progressLineWithValueRenderer`

```ts
progressLineWithValueRenderer: CellTemplate<DataType<any, ColumnProp>>;
```

---

### `sparklineRenderer`

```ts
sparklineRenderer: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `barChartRenderer`

RevoGrid Renderer
Generates a bar chart visualization based on the provided data
values and column configuration.

```ts
barChartRenderer: (h: HyperFunc<VNode>, { value, column, }: { value?: any; column: Partial<ColumnRegular<ColumnProp, DataType<any, ColumnProp>>>; }) => VNode;
```

---

### `heatmapRenderer`

```ts
heatmapRenderer: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `badgeRenderer`

RevoGrid Renderer
Renderers a badge cell with custom background color, text
Supports both badgeStyles and thresholds for styling

```ts
badgeRenderer: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `ratingStarRenderer`

```ts
ratingStarRenderer: CellTemplate<DataType<any, ColumnProp>>;
```

---

### `formatTimelineEvents`

Converts valid Timeline events to the same readable text used by tooltips
and accessibility labels.

**@param** value Timeline event array; invalid entries are ignored.

**@param** separator Text inserted between valid event descriptions.

**@returns** A human-readable schedule, or an empty string when no event is valid.

**Example:**
```typescript
formatTimelineEvents([
  { start: 8, end: 12, label: 'Build' },
  { start: 14, end: 18, label: 'Review' },
], '; ');
// "Build: 8–12; Review: 14–18"
```

```ts
export function formatTimelineEvents(value: unknown, separator = ', '): string;
```

---

### `TimelineEvent`

```ts
interface TimelineEvent {
  readonly start: number;
  readonly end: number;
  readonly label?: string
}
```

---

### `timelineRenderer`

```ts
timelineRenderer: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `changeRenderer`

RevoGrid Renderer
Formats a numeric cell value with corresponding styles and icons based on whether the value
is positive, negative, or zero,
and exports a cell template renderer for a grid that utilizes this formatting.

```ts
changeRenderer: CellTemplate<DataType<any, ColumnProp>>;
```

---

### `thumbsRenderer`

```ts
thumbsRenderer: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `renderColumnTypeIcon`

Helper to render icons based on the columnType.

**@param** h Hyperscript function.

**@param** columnType The column type to determine the icon.

**@returns** A VNode containing the corresponding SVG icon.

```ts
export function renderColumnTypeIcon(
  h: HyperFunc<VNode>,
  columnType: string
);
```

---

### `columnTypeRenderer`

```ts
columnTypeRenderer: ColumnTemplateFunc | undefined;
```

---

### `PieData`

```ts
interface PieData {
  value: number;
  color?: string;
  name?: string
}
```

---

### `pieChartRenderer`

```ts
pieChartRenderer: (h: HyperFunc<VNode>, { value, column, }: { value?: number[] | PieData[] | undefined; column?: Partial<ColumnDataSchemaModel<DataType<any, ColumnProp>, ColumnRegular<ColumnProp, DataType<any, ColumnProp>>, ColumnProp>> | undefined; }) => VNode;
```

---

### `summaryHeaderRenderer`

```ts
summaryHeaderRenderer: (h: HyperFunc<VNode>, summary: Record<string, number>, column?: { maxItems?: number | undefined; }) => VNode;
```

---

### `summaryAggregateRenderer`

```ts
summaryAggregateRenderer: (h: HyperFunc<VNode>, summary: Record<string, number>, column?: { showSum?: boolean | undefined; showAvg?: boolean | undefined; }) => VNode;
```

---

### `avatarRenderer`

```ts
avatarRenderer: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `avatarTemplate`

```ts
export function avatarTemplate(h: any, options: AvatarTemplateOptions = {});
```

---

### `avatarWithTextRenderer`

```ts
avatarWithTextRenderer: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `thresholdRenderer`

The `thresholdRenderer` is a custom cell renderer for RevoGrid that applies CSS classes based on defined thresholds.
It uses the existing threshold system to apply classes to cells based on their values.

**Features**:
- Supports multiple thresholds with custom CSS classes
- Simple and straightforward threshold-based styling
- Works with the existing threshold system

**Usage**:
```typescript
import { thresholdRenderer } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'score',
    name: 'Score',
    thresholds: [
      { value: 0, className: 'high' },    // Red for negative values
      { value: 50, className: 'medium' },     // Yellow for values 0-50
      { value: 100, className: 'low' },      // Green for values 50-100
    ],
    cellProperties: thresholdRenderer,
  },
];
```

```ts
thresholdRenderer: PropertiesFunc<DataType<any, ColumnProp>>;
```

---

### `circularProgressRenderer`

```ts
circularProgressRenderer: CellTemplate<DataType<any, ColumnProp>>;
```

---

### `normalizeProgressRange`

Normalize a numeric value into a finite, clamped 0–100 progress range.

```ts
export function normalizeProgressRange(
  value: unknown,
  configuredMin: unknown = 0,
  configuredMax: unknown = 100,
): NormalizedProgressRange;
```

---

### `NormalizedProgressRange`

```ts
interface NormalizedProgressRange {
  readonly min: number;
  readonly max: number;
  readonly percent: number
}
```

---

### `getThresholdClasses`

Get the threshold classes for a given value and column.

### Example
```typescript
const columns: ColumnRegular[] = [
  {
    name: 'Avg Rating',
    prop: 'Average Rating',
    filter: ['number', 'slider'],
    sortable: true,
    maxStars: 5,
    maxValue: 5,
    thresholds: [
      { value: 4, className: 'high' },
      { value: 3, className: 'medium' },
      { value: 0, className: 'low' },
    ],
  },
];
```

```ts
export function getThresholdClasses(
  value: number,
  column: Partial<ColumnRegular>,
);
```

---

### `ThresholdConfig`

The `ThresholdConfig` interface defines the structure of a threshold configuration object.
It specifies the value and the class name to be applied when the value exceeds or equals the threshold.

```ts
interface ThresholdConfig {
  /**
     * The value of the threshold.
     */
    value: number;
  /**
     * The class name to be applied when the value exceeds or equals the threshold.
     */
    className: string
}
```

---

# Checkbox

URL: https://pro.rv-grid.com/api/checkbox/
Source: src/content/docs/api/checkbox.md

### `renderCheckbox`

Render the shared native checkbox while keeping the caller's renderer and
event semantics. This works with both RevoGrid/Stencil templates and Preact.

```ts
export function renderCheckbox(h: PreactH, attributes?: SharedCheckboxAttributes): PreactVNode;;
```

---

### `Checkbox`

Preact adapter for the shared checkbox presentation. The native input stays
the interaction owner; the adapter only normalizes indeterminate state and
optional label/description composition.

```ts
export function Checkbox({
  checked,
  indeterminate = false,
  label,
  description,
  ariaLabel,
  controlClassName = '',
  inputRef,
  onChange,
  ...attributes
}: CheckboxProps): any;
```

---

### `SHARED_CHECKBOX_CLASS`

```ts
SHARED_CHECKBOX_CLASS: string;
```

---

### `SharedCheckboxAttributes` (Extended from `index.ts`)

```ts
export type SharedCheckboxAttributes = Record<string, unknown> & {
  class?: string;
  className?: string;
};
```

---

### `CheckboxProps` (Extended from `index.ts`)

```ts
export type CheckboxProps = Omit<SharedCheckboxAttributes, 'onChange'> & {
  checked?: boolean;
  indeterminate?: boolean;
  label?: any;
  description?: any;
  ariaLabel?: string;
  controlClassName?: string;
  inputRef?: (input: HTMLInputElement | null) => void;
  onChange?: (checked: boolean, event: Event & { currentTarget: HTMLInputElement }) => void;
};
```

---

# Choice Chips

URL: https://pro.rv-grid.com/api/choice-chips/
Source: src/content/docs/api/choice-chips.md

### `ChoiceChips`

Shared wrapping choice control for compact presets and granularities.

```ts
export function ChoiceChips<T extends ChoiceChipValue = ChoiceChipValue>({
  value,
  options,
  onChange,
  ariaLabel,
  appearance = 'soft',
  size = 'medium',
  className = '',
  itemClassName = '',
  disabled = false,
  testId,
}: ChoiceChipsProps<T>): any;
```

---

### `ChoiceChipValue`

```ts
export type ChoiceChipValue = string | number;
```

---

### `ChoiceChipOption`

```ts
export type ChoiceChipOption<T extends ChoiceChipValue = ChoiceChipValue> = {
  value: T;
  label: any;
  ariaLabel?: string;
  title?: string;
  disabled?: boolean;
  className?: string;
  style?: any;
  testId?: string;
};
```

---

### `ChoiceChipsProps`

```ts
export type ChoiceChipsProps<T extends ChoiceChipValue = ChoiceChipValue> = {
  value?: T | readonly T[];
  options: readonly ChoiceChipOption<T>[];
  onChange: (value: T, option: ChoiceChipOption<T>) => void;
  ariaLabel: string;
  appearance?: 'soft' | 'outlined';
  size?: 'small' | 'medium';
  className?: string;
  itemClassName?: string;
  disabled?: boolean;
  testId?: string;
};
```

---

# Clipboard

URL: https://pro.rv-grid.com/api/clipboard/
Source: src/content/docs/api/clipboard.md

## Module Extensions

### `ClipboardConfig` (Extended from `@revolist/revogrid`)

```ts
interface ClipboardConfig {
  /** Additional rich clipboard formats used by ClipboardPlugin. */
      formats?: readonly ClipboardFormatHandler[];
  /** Maximum decoded cells. Defaults to 1,000,000. */
      maxCells?: number;
  /** Maximum bytes inspected in one text representation. Defaults to 16 MiB. */
      maxBytes?: number
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  clipboardformaterror: ClipboardFormatDiagnostic
}
```

## Plugin API

### `ClipboardPlugin`

Browser-rich, Excel-compatible clipboard orchestration for RevoGrid Pro.

#### Dependencies

- **Optional** `DataGridFormattingPlugin`: Uses DataGridFormattingPlugin when available to import and apply rich formatting.

```ts
class ClipboardPlugin {
  registerFormat(handler: ClipboardFormatHandler): () => void;

  registerMetadataContributor(contributor: ClipboardMetadataContributor): () => void;
}
```

---

### `matrixToClipboardDocument`

Converts a value matrix into one dense clipboard-document range.

```ts
export function matrixToClipboardDocument(
  matrix: readonly (readonly DataFormat[])[],
  source = 'revogrid',
): ClipboardDocument;
```

---

### `clipboardDocumentToMatrix`

Materializes positioned clipboard ranges as one dense value matrix.

```ts
export function clipboardDocumentToMatrix(document: ClipboardDocument): DataFormat[][];
```

---

### `countClipboardCells`

Counts the rectangular cell capacity declared by a clipboard document.

```ts
export function countClipboardCells(document: ClipboardDocument);
```

---

### `isClipboardDocument`

Validates the supported clipboard document wire shape.

```ts
export function isClipboardDocument(value: unknown): value is ClipboardDocument;
```

---

### `createExcelHtmlClipboardFormat`

```ts
export function createExcelHtmlClipboardFormat(
  formatting?: ClipboardExcelFormattingAdapter,
): ClipboardFormatHandler;
```

---

### `createGenericHtmlClipboardFormat`

```ts
export function createGenericHtmlClipboardFormat(
  formatting?: ClipboardExcelFormattingAdapter,
): ClipboardFormatHandler;
```

---

### `extractCfHtml`

```ts
export function extractCfHtml(value: string): string;
```

---

### `parseHtmlClipboard`

```ts
export function parseHtmlClipboard(
  raw: string,
  options: {
    source: string;
    maxBytes: number;
    maxCells: number;
    formatting?: ClipboardExcelFormattingAdapter;
  },
): ClipboardDocument | null;
```

---

### `serializeExcelHtml`

```ts
export function serializeExcelHtml(
  document: ClipboardDocument,
  formatting?: ClipboardExcelFormattingAdapter,
): string;
```

---

### `ClipboardExcelFormattingAdapter`

```ts
interface ClipboardExcelFormattingAdapter {
  importFormat(declarations: readonly string[]): ClipboardCell['format'];
  importValue(displayText: string, format?: ClipboardCell['format']): unknown;
  exportFormat(format: NonNullable<ClipboardCell['format']>): string | undefined;
  exportValue(
      value: unknown,
      format: NonNullable<ClipboardCell['format']>,
    ): { readonly value: unknown; readonly displayText: string }
}
```

---

### `excelHtmlClipboardFormat`

Value-only default. ClipboardPlugin supplies the formatting runtime adapter.

```ts
excelHtmlClipboardFormat: ClipboardFormatHandler<any>;
```

---

### `genericHtmlClipboardFormat`

Value-only default. ClipboardPlugin supplies the formatting runtime adapter.

```ts
genericHtmlClipboardFormat: ClipboardFormatHandler<any>;
```

---

### `parseDelimitedText`

```ts
export function parseDelimitedText(value: string, delimiter: string): string[][];
```

---

### `serializeDelimitedText`

```ts
export function serializeDelimitedText(
  matrix: readonly (readonly unknown[])[],
  delimiter: string,
): string;
```

---

### `plainTextClipboardFormat`

```ts
plainTextClipboardFormat: {
  id: string;
  mimeTypes: string[];
  priority: number;
  read: ({ transfer, maxBytes, maxCells }: ClipboardFormatReadContext) => ClipboardDocument<any>;
  write: ({ document }: ClipboardFormatWriteContext<any>) => { type: string; data: string; }[];
};
```

---

### `ClipboardFormatRegistry`

```ts
class ClipboardFormatRegistry {
  register(handler: ClipboardFormatHandler): () => void;

  read(transfer: ClipboardDataReader, limits: { maxCells: number; maxBytes: number });

  write(document: ClipboardDocument, transfer: ClipboardDataWriter): void;
}
```

---

### `resolveClipboardPluginConfig`

Resolves clipboard limits and custom formats from the grid configuration.

```ts
export function resolveClipboardPluginConfig(
  useClipboard: boolean | ClipboardConfig | undefined,
): ResolvedClipboardPluginConfig;
```

---

### `REVOGRID_CLIPBOARD_MIME`

```ts
REVOGRID_CLIPBOARD_MIME: string;
```

---

### `REVOGRID_CLIPBOARD_VERSION`

```ts
REVOGRID_CLIPBOARD_VERSION: 2;
```

---

### `ClipboardCell`

```ts
interface ClipboardCell {
  readonly value: T;
  readonly displayText?: string;
  readonly formula?: string;
  /** `null` explicitly copies an ordinary RevoGrid cell with no effective format. */
    readonly format?: DataGridCellFormat | null;
  readonly metadata?: Readonly<Record<string, unknown>>
}
```

---

### `ClipboardRange`

```ts
interface ClipboardRange {
  readonly row: number;
  readonly col: number;
  readonly width: number;
  readonly height: number;
  readonly cells: readonly ClipboardCell<T>[];
  readonly merges?: readonly MergeData[];
  readonly columnWidths?: readonly (number | undefined)[];
  readonly rowHeights?: readonly (number | undefined)[];
  readonly rowType?: DimensionRows;
  readonly colType?: DimensionCols;
  readonly metadata?: Readonly<Record<string, unknown>>
}
```

---

### `ClipboardDocument`

```ts
interface ClipboardDocument {
  readonly version: typeof REVOGRID_CLIPBOARD_VERSION;
  readonly source: string;
  readonly ranges: readonly ClipboardRange<T>[];
  readonly metadata?: Readonly<Record<string, unknown>>
}
```

---

### `ClipboardDataReader`

```ts
interface ClipboardDataReader {
  readonly types: readonly string[];
  getData(type: string): string
}
```

---

### `ClipboardDataWriter`

```ts
interface ClipboardDataWriter {
  setData(type: string, value: string): void
}
```

---

### `ClipboardFormatReadContext`

```ts
interface ClipboardFormatReadContext {
  readonly transfer: ClipboardDataReader;
  readonly maxCells: number;
  readonly maxBytes: number
}
```

---

### `ClipboardFormatWriteContext`

```ts
interface ClipboardFormatWriteContext {
  readonly document: ClipboardDocument<T>
}
```

---

### `ClipboardRepresentation`

```ts
interface ClipboardRepresentation {
  readonly type: string;
  readonly data: string
}
```

---

### `ClipboardFormatHandler`

```ts
interface ClipboardFormatHandler {
  readonly id: string;
  readonly mimeTypes: readonly string[];
  readonly priority?: number;
  canRead?(context: ClipboardFormatReadContext): boolean;
  read(context: ClipboardFormatReadContext): ClipboardDocument<T> | null;
  write?(context: ClipboardFormatWriteContext<T>): readonly ClipboardRepresentation[]
}
```

---

### `ClipboardMetadataCaptureContext`

```ts
interface ClipboardMetadataCaptureContext {
  readonly document: ClipboardDocument<T>;
  readonly providers: PluginProviders
}
```

---

### `ClipboardMetadataApplyContext`

```ts
interface ClipboardMetadataApplyContext {
  readonly document: ClipboardDocument<T>;
  readonly providers: PluginProviders
}
```

---

### `ClipboardMetadataContributor`

```ts
interface ClipboardMetadataContributor {
  readonly id: string;
  capture?(context: ClipboardMetadataCaptureContext<T>): unknown;
  apply?(metadata: unknown, context: ClipboardMetadataApplyContext<T>): void
}
```

---

### `ClipboardFormatDiagnostic`

```ts
interface ClipboardFormatDiagnostic {
  readonly phase: 'read' | 'write' | 'metadata';
  readonly handlerId: string;
  readonly error: unknown
}
```

---

### `ClipboardPluginConfig`

```ts
interface ClipboardPluginConfig {
  readonly formats?: readonly ClipboardFormatHandler[];
  readonly maxCells?: number;
  readonly maxBytes?: number
}
```

---

### `ResolvedClipboardPluginConfig`

```ts
interface ResolvedClipboardPluginConfig {
  readonly formats: readonly ClipboardFormatHandler[];
  readonly maxCells: number;
  readonly maxBytes: number
}
```

---

### `captureClipboardSelection`

Captures current grid selections as a rich clipboard document.

```ts
export function captureClipboardSelection(
  context: ClipboardCaptureContext,
  matrix?: DataFormat[][],
): ClipboardDocument | null;
```

---

### `getActiveClipboardSelection`

Reads the active provider-backed selection as normalized clipboard coordinates.

```ts
export function getActiveClipboardSelection(
  providers: PluginProviders,
): ClipboardSelection[] | null;
```

---

### `getClipboardPasteStart`

Returns the focused viewport cell used as the paste origin.

```ts
export function getClipboardPasteStart(
  providers: PluginProviders,
): ClipboardPasteStart | null;
```

---

### `getClipboardSelectionOffsets`

Converts viewport selections into offsets from their shared whole-grid origin.

```ts
export function getClipboardSelectionOffsets(
  selections: readonly ClipboardSelection[],
  providers: PluginProviders,
);
```

---

### `createClipboardCoordinateResolver`

Creates a cached coordinate resolver for one copy or paste operation.

```ts
export function createClipboardCoordinateResolver(
  providers: PluginProviders,
  start: ClipboardPasteStart,
): ClipboardCoordinateResolver;
```

---

### `forEachClipboardDocumentCell`

Visits every valid cell stored in a clipboard document without an intermediate array.

```ts
export function forEachClipboardDocumentCell(
  document: ClipboardDocument,
  visit: (entry: ClipboardDocumentCell) => boolean | void,
): boolean;
```

---

### `getSingleClipboardDocumentCell`

Returns the only stored document cell, or null when the count is not one.

```ts
export function getSingleClipboardDocumentCell(document: ClipboardDocument);
```

---

### `getClipboardRangeCellOffset`

Resolves one row-major range cell into its document-relative offset.

```ts
export function getClipboardRangeCellOffset(
  range: ClipboardRange,
  index: number,
): ClipboardCellOffset | null;
```

---

### `getClipboardDocumentBounds`

Computes clipboard-document bounds in one pass.

```ts
export function getClipboardDocumentBounds(document: ClipboardDocument);
```

---

### `getClipboardCellCount`

Counts the rectangular capacity declared by all clipboard ranges.

```ts
export function getClipboardCellCount(document: ClipboardDocument);
```

---

### `getClipboardMatrixData`

Flattens a matrix into a dense row-major clipboard range.

```ts
export function getClipboardMatrixData(
  matrix: readonly (readonly DataFormat[])[],
);
```

---

### `createClipboardMatrix`

Builds a dense value matrix from positioned clipboard ranges.

```ts
export function createClipboardMatrix(document: ClipboardDocument): DataFormat[][];
```

---

### `getClipboardFormulaDestination`

Resolves the absolute destination used to restore an Excel formula.

```ts
export function getClipboardFormulaDestination(
  resolver: ClipboardCoordinateResolver,
  range: ClipboardRange,
  cellIndex: number,
);
```

---

### `forEachClipboardRangeFillCell`

Visits every projected destination for a one-cell range-fill paste.

```ts
export function forEachClipboardRangeFillCell(
  selection: ClipboardSelection,
  start: ClipboardPasteStart,
  cell: ClipboardCell,
  visit: (entry: ClipboardDocumentCell) => boolean | void,
): boolean;
```

---

### `clipboardOutcomeIncludesTarget`

Checks whether a managed paste outcome includes one resolved target.

```ts
export function clipboardOutcomeIncludesTarget(
  detail: {
    type?: DimensionRows;
    data?: Record<number, Record<string, unknown>>;
  } | undefined,
  target: ClipboardResolvedPasteTarget,
);
```

---

### `createClipboardTargetMerge`

Repositions clipboard merge metadata at a resolved viewport target.

```ts
export function createClipboardTargetMerge(
  merge: MergeData,
  target: ClipboardPasteStart,
): MergeData;
```

---

### `captureClipboardMerge`

Converts an in-selection merge into clipboard-relative coordinates.

```ts
export function captureClipboardMerge(
  merge: MergeData,
  area: RangeArea,
  rowType: DimensionRows,
  colType: DimensionCols,
): MergeData | null;
```

---

### `getClipboardMergeOffsets`

Returns the inclusive paste bounds of a clipboard merge.

```ts
export function getClipboardMergeOffsets(
  range: ClipboardRange,
  merge: MergeData,
);
```

---

### `forEachClipboardMergeCell`

Visits every document-relative cell covered by a clipboard merge.

```ts
export function forEachClipboardMergeCell(
  range: ClipboardRange,
  merge: MergeData,
  visit: (offset: ClipboardCellOffset) => boolean | void,
): boolean;
```

---

### `clipboardMergesOverlap`

Checks whether two same-viewport merge rectangles overlap.

```ts
export function clipboardMergesOverlap(left: MergeData, right: MergeData);
```

---

### `ClipboardPasteStart`

```ts
export type ClipboardPasteStart = ViewportCellAddress;
```

---

### `ClipboardResolvedPasteTarget`

```ts
export type ClipboardResolvedPasteTarget = ResolvedViewportCell;
```

---

### `ClipboardMetadataTargetFilter`

```ts
export type ClipboardMetadataTargetFilter = (target: ClipboardResolvedPasteTarget) => boolean;
```

---

### `ClipboardSelection`

```ts
interface ClipboardSelection {
  readonly rowType: DimensionRows;
  readonly colType: DimensionCols;
  readonly range: RangeArea
}
```

---

### `ClipboardCellOffset`

```ts
interface ClipboardCellOffset {
  readonly rowOffset: number;
  readonly colOffset: number
}
```

---

### `ClipboardDocumentCell` (Extended from `coordinates.ts`)

```ts
interface ClipboardDocumentCell {
  readonly cell: ClipboardCell
}
```

---

### `ClipboardCoordinateResolver`

Resolves clipboard offsets through one cached provider-coordinate snapshot.

```ts
interface ClipboardCoordinateResolver {
  /** Converts a document offset into a whole-grid row and column. */
    getAbsoluteCell(offset: ClipboardCellOffset): { readonly row: number; readonly column: number };
  /** Reads cached source and item mappings for one viewport pair. */
    getViewportSources(rowType: DimensionRows, colType: DimensionCols): ClipboardViewportSources | null;
  /** Resolves a document offset to its model-backed grid cell. */
    resolveTarget(offset: ClipboardCellOffset): ClipboardResolvedPasteTarget | null;
  /** Resolves a document offset to its viewport-local address. */
    resolveTargetAddress(offset: ClipboardCellOffset): ClipboardPasteStart | null;
  /** Converts a resolved cell from visible indexes to physical source indexes. */
    getPhysicalCellAddress(target: ClipboardResolvedPasteTarget): {
      readonly row: number;
      readonly column: number;
      readonly rowType: DimensionRows;
      readonly colType: DimensionCols;
    };
  /** Converts a resolved column from its visible index to its physical source index. */
    getPhysicalColumnAddress(target: ClipboardResolvedPasteTarget): {
      readonly column: number;
      readonly colType: DimensionCols;
    };
  /** Returns the cached physical row source for readonly evaluation. */
    getTargetRowSource(target: ClipboardResolvedPasteTarget): DataType[]
}
```

---

### `resolveClipboardFormattingRuntime`

Finds the installed data-grid formatting runtime, when available.

```ts
export function resolveClipboardFormattingRuntime(
  providers: PluginProviders,
): DataGridFormattingRuntime | undefined;
```

---

### `applyClipboardFormatting`

Applies rich clipboard formats to every accepted destination cell.

```ts
export function applyClipboardFormatting(
  context: ClipboardFormattingContext,
  document: ClipboardDocument,
  start: ClipboardPasteStart,
  targetFilter?: ClipboardMetadataTargetFilter,
): void;
```

---

### `isClipboardPasteValueCompatible`

Checks that pasted values match every effective destination editor domain.

```ts
export function isClipboardPasteValueCompatible(
  context: ClipboardFormattingContext,
  document: ClipboardDocument,
  start: ClipboardPasteStart,
): boolean;
```

---

### `resolveClipboardPasteFormulas`

Rebases stored Excel R1C1 formulas against the current paste destination.

```ts
export function resolveClipboardPasteFormulas(
  providers: PluginProviders,
  document: ClipboardDocument,
  start: ClipboardPasteStart,
): ClipboardDocument;
```

---

### `isWritableClipboardTarget`

Checks provider readonly policy for one resolved clipboard destination.

```ts
export function isWritableClipboardTarget(
  resolver: ClipboardCoordinateResolver,
  target: ClipboardResolvedPasteTarget,
): boolean;
```

---

### `clipboardDocumentToSparsePayload`

Converts multi-range rich data into the legacy sparse clipboard payload.

```ts
export function clipboardDocumentToSparsePayload(
  document: ClipboardDocument,
): MultiRangeClipboardPayload | null;
```

---

### `captureClipboardMerges`

Captures merges fully contained by one copied viewport range.

```ts
export function captureClipboardMerges(
  revogrid: HTMLRevoGridElement,
  area: RangeArea,
  rowType: DimensionRows,
  colType: DimensionCols,
);
```

---

### `applyClipboardStructure`

Applies valid, writable clipboard merges at the paste destination.

```ts
export function applyClipboardStructure(
  context: ClipboardStructureContext,
  document: ClipboardDocument,
  start: ClipboardPasteStart,
  targetFilter?: ClipboardMetadataTargetFilter,
): void;
```

---

### `normalizeExcelClipboardFormula`

Convert browser-visible Excel R1C1 references into FormulaPlugin-compatible A1 references.

```ts
export function normalizeExcelClipboardFormula(
  value: string,
  rowIndex: number,
  columnIndex: number,
): string;
```

---

### `toExcelClipboardFormula`

Convert FormulaPlugin-compatible A1 references into Excel HTML R1C1 references.

```ts
export function toExcelClipboardFormula(
  value: string,
  rowIndex: number,
  columnIndex: number,
): string;
```

---

### `cloneClipboardDocument`

```ts
export function cloneClipboardDocument(document: ClipboardDocument): ClipboardDocument;
```

---

### `revogridJsonClipboardFormat`

```ts
revogridJsonClipboardFormat: {
  id: string;
  mimeTypes: string[];
  priority: number;
  read: ({ transfer, maxBytes, maxCells }: ClipboardFormatReadContext) => ClipboardDocument<any> | null;
  write: ({ document }: ClipboardFormatWriteContext<any>) => { type: string; data: string; }[];
};
```

---

# Clipboard Validation

URL: https://pro.rv-grid.com/api/clipboard-validation/
Source: src/content/docs/api/clipboard-validation.md

## Module Extensions

### `ClipboardConfig` (Extended from `@revolist/revogrid`)

```ts
interface ClipboardConfig {
  /**
       * Resolves strict validation failures during paste.
       *
       * `atomic` rejects the complete paste when any destination is invalid.
       * `valid-cells` applies accepted destinations and preserves rejected cells.
       *
       * @default 'atomic'
       */
      validationResolution?: ClipboardValidationResolution
}
```

## Plugin API

### `ClipboardValidationResolution`

Validation policy used when clipboard data contains strict validation failures.

```ts
/** Validation policy used when clipboard data contains strict validation failures. */
export type ClipboardValidationResolution = 'atomic' | 'valid-cells';
```

---

# Collaborative Presence

URL: https://pro.rv-grid.com/api/collaborative-presence/
Source: src/content/docs/api/collaborative-presence.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  collaborativePresence?: CollaborativePresenceConfig;
  'collaborative-presence'?: CollaborativePresenceConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  collaborativePresence?: CollaborativePresenceConfig
}
```

## Plugin API

### `CollaborativePresencePlugin`

Renders remote collaborator focus and range presence without mutating local
grid focus, selection, data, or history.

#### Dependencies

- **Config integration** `additionalData.collaborativePresence`: Reads remote collaborator presence from grid.collaborativePresence or additionalData.collaborativePresence.
- **Event integration** `afterrender`: Refreshes visible remote focus and range markers after grid render updates.

```ts
class CollaborativePresencePlugin {
  destroy();
}
```

---

### `CollaborativePresenceActivity`

```ts
export type CollaborativePresenceActivity = 'viewing' | 'editing' | 'idle';
```

---

### `CollaborativePresenceCellRef`

```ts
interface CollaborativePresenceCellRef {
  x: number;
  y: number;
  colType?: DimensionCols;
  rowType?: DimensionRows
}
```

---

### `CollaborativePresenceRangeRef` (Extended from `index.ts`)

```ts
interface CollaborativePresenceRangeRef {
  colType?: DimensionCols;
  rowType?: DimensionRows
}
```

---

### `CollaborativePresenceUser`

```ts
interface CollaborativePresenceUser {
  id: string;
  name: string;
  initials?: string;
  color?: string;
  activity?: CollaborativePresenceActivity;
  focus?: CollaborativePresenceCellRef | null;
  range?: CollaborativePresenceRangeRef | null;
  lastActiveAt?: number | string | Date
}
```

---

### `CollaborativePresenceRowPatch`

```ts
interface CollaborativePresenceRowPatch {
  rowIndex: number;
  data: Record<string, unknown>;
  rowType?: DimensionRows
}
```

---

### `CollaborativePresenceConfig`

```ts
interface CollaborativePresenceConfig {
  enabled?: boolean;
  showLabels?: boolean;
  staleAfterMs?: number;
  users?: CollaborativePresenceUser[];
  remoteEdits?: CollaborativePresenceRowPatch[]
}
```

---

### `ResolvedCollaborativePresenceConfig`

```ts
interface ResolvedCollaborativePresenceConfig {
  enabled: boolean;
  showLabels: boolean;
  staleAfterMs?: number;
  users: CollaborativePresenceUser[];
  remoteEdits: CollaborativePresenceRowPatch[]
}
```

---

### `CollaborativePresenceRect`

```ts
interface CollaborativePresenceRect {
  left: number;
  top: number;
  width: number;
  height: number
}
```

---

### `CollaborativePresenceMarker`

```ts
interface CollaborativePresenceMarker {
  kind: 'focus' | 'range';
  user: CollaborativePresenceUser;
  rect: CollaborativePresenceRect;
  colType: DimensionCols;
  rowType: DimensionRows
}
```

---

### `normalizeCollaborativePresenceCell`

```ts
export function normalizeCollaborativePresenceCell(
  cell: CollaborativePresenceCellRef,
): Required<CollaborativePresenceCellRef>;
```

---

### `normalizeCollaborativePresenceRange`

```ts
export function normalizeCollaborativePresenceRange(
  range: CollaborativePresenceRangeRef,
): Required<CollaborativePresenceRangeRef>;
```

---

### `resolveCollaborativePresenceConfig`

```ts
export function resolveCollaborativePresenceConfig(
  config?: CollaborativePresenceConfig,
): ResolvedCollaborativePresenceConfig;
```

---

### `getVisibleCollaborativePresenceUsers`

```ts
export function getVisibleCollaborativePresenceUsers(
  config: ResolvedCollaborativePresenceConfig,
  now = Date.now(),
): CollaborativePresenceUser[];
```

---

### `resolveCollaborativePresenceMarkers`

```ts
export function resolveCollaborativePresenceMarkers(
  _grid: HTMLElement,
  users: CollaborativePresenceUser[],
  providers?: PluginProviders,
): CollaborativePresenceMarker[];
```

---

### `applyCollaborativePresenceRowPatches`

Applies row patches directly into the RevoGrid data store without triggering
a full source reset or plugin re-initialization.

`rowIndex` is treated as a **source (physical) index** — the position in the
original data array — so patches always target the correct row regardless of
the current sort or reorder state.

Per rowType:
  1. Mutate source[rowIndex] directly for each patch
  2. store.set('source', [...]) once — triggers a single targeted reactive update

Mirrors the low-level write pattern in spreadsheet.simulation.ts.

```ts
export function applyCollaborativePresenceRowPatches(
  providers: PluginProviders,
  patches: CollaborativePresenceRowPatch[],
): void;
```

---

### `CollaborativePresenceLayer`

Manages per-viewport slot overlay elements and draws presence markers into them.
Each viewport type combination (colType × rowType) gets its own slot div so markers
clip and scroll correctly within their viewport.

```ts
class CollaborativePresenceLayer {
  render(markers: CollaborativePresenceMarker[], showLabels: boolean): void;

  destroy(): void;
}
```

---

### `getCollaborativePresenceViewportOffset`

```ts
export function getCollaborativePresenceViewportOffset(
  rect: CollaborativePresenceRect,
): { left: number; top: number } | undefined;
```

---

### `resolveCollaborativePresenceCellRect`

```ts
export function resolveCollaborativePresenceCellRect(
  providers: PluginProviders | undefined,
  cell: PresenceCell,
): CollaborativePresenceRect | undefined;
```

---

### `resolveCollaborativePresenceRangeRect`

```ts
export function resolveCollaborativePresenceRangeRect(
  providers: PluginProviders | undefined,
  range: PresenceRange,
): CollaborativePresenceRect | undefined;
```

---

# Color Palette

URL: https://pro.rv-grid.com/api/color-palette/
Source: src/content/docs/api/color-palette.md

### `ColorPalette`

```ts
export function ColorPalette({
  value,
  options = DEFAULT_COLOR_PALETTE_OPTIONS,
  ariaLabel,
  defaultLabel,
  colorAriaLabel,
  disabled = false,
  includeDefault = true,
  defaultDisabled = false,
  onChange,
}: ColorPaletteProps);
```

---

### `createColorPaletteMenuItems`

```ts
export function createColorPaletteMenuItems(options: {
  /** `undefined` represents a mixed multi-selection with no checked choice. */
  readonly value: ColorPaletteValue | undefined;
  readonly options?: readonly ColorPaletteOption[];
  readonly defaultLabel: string;
  readonly colorAriaLabel: (option: ColorPaletteOption) => string;
  readonly disabled?: boolean;
  readonly includeDefault?: boolean;
  readonly defaultDisabled?: boolean;
  readonly onChange: (value: ColorPaletteValue) => void;
}): ContextMenuItem[];
```

---

### `ColorPaletteProps`

```ts
interface ColorPaletteProps {
  readonly value: ColorPaletteValue;
  readonly options?: readonly ColorPaletteOption[];
  readonly ariaLabel: string;
  readonly defaultLabel: string;
  readonly colorAriaLabel: (option: ColorPaletteOption) => string;
  readonly disabled?: boolean;
  readonly includeDefault?: boolean;
  readonly defaultDisabled?: boolean;
  readonly onChange: (value: ColorPaletteValue) => void
}
```

---

### `ColorPaletteOption`

```ts
interface ColorPaletteOption {
  readonly value: string;
  readonly label: string;
  readonly disabled?: boolean
}
```

---

### `ColorPaletteValue`

```ts
export type ColorPaletteValue = string | null;
```

---

### `DEFAULT_COLOR_PALETTE_OPTIONS`

```ts
DEFAULT_COLOR_PALETTE_OPTIONS: readonly ColorPaletteOption[];
```

---

# Column Add Popup

URL: https://pro.rv-grid.com/api/column-add-popup/
Source: src/content/docs/api/column-add-popup.md

## Module Extensions

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Column add popup plugin configuration.
       *
       * @deprecated Prefer the direct `grid.columnAddPopup` property.
       */
      columnAddPopup?: ColumnAddPopupConfig
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /**
       * Column add popup plugin configuration.
       */
      columnAddPopup?: ColumnAddPopupConfig
}
```

## Plugin API

### `ColumnAddPopupPlugin`

```ts
class ColumnAddPopupPlugin {
  open(trigger: HTMLElement, originalEvent: MouseEvent);

  destroy();
}
```

---

### `ColumnAddPopupTone`

```ts
export type ColumnAddPopupTone =
  | 'green'
  | 'blue'
  | 'cyan'
  | 'red'
  | 'orange'
  | 'yellow'
  | 'violet'
  | 'pink'
  | 'gray';
```

---

### `ColumnAddPopupItem`

```ts
interface ColumnAddPopupItem {
  id: string;
  label: string;
  description?: string;
  icon?: string;
  tone?: ColumnAddPopupTone;
  disabled?: boolean;
  selected?: boolean
}
```

---

### `ColumnAddPopupSection`

```ts
interface ColumnAddPopupSection {
  title: string;
  items: ColumnAddPopupItem[]
}
```

---

### `ColumnAddPopupSelectContext`

```ts
interface ColumnAddPopupSelectContext {
  item: ColumnAddPopupItem;
  selected: boolean;
  grid: HTMLRevoGridElement;
  originalEvent: MouseEvent;
  close: () => void
}
```

---

### `ColumnAddPopupItemStateContext`

```ts
interface ColumnAddPopupItemStateContext {
  item: ColumnAddPopupItem;
  grid: HTMLRevoGridElement
}
```

---

### `ColumnAddPopupFooterContext`

```ts
interface ColumnAddPopupFooterContext {
  grid: HTMLRevoGridElement;
  originalEvent: MouseEvent;
  close: () => void
}
```

---

### `ColumnAddPopupConfig`

```ts
interface ColumnAddPopupConfig {
  sections?: ColumnAddPopupSection[];
  title?: string;
  footerLabel?: string;
  className?: string;
  isSelected?: (context: ColumnAddPopupItemStateContext) => boolean;
  onSelect?: (context: ColumnAddPopupSelectContext) => void;
  onFooterClick?: (context: ColumnAddPopupFooterContext) => void
}
```

---

# Column Autosize

URL: https://pro.rv-grid.com/api/column-autosize/
Source: src/content/docs/api/column-autosize.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /**
       * Kebab-case alias for framework bindings.
       */
      'auto-size-column'?: AutoSizeColumnProp
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

Add autoSizeColumnConfig property to AdditionalData interface

```ts
interface AdditionalData {
  /**
       * @deprecated Use `grid.autoSizeColumn` instead.
       */
      autoSizeColumnConfig?: AutoSizeColumnConfig
}
```

---

### `ColumnRegular` (Extended from `@revolist/revogrid`)

Add autoSize property to ColumnRegular interface

```ts
interface ColumnRegular {
  autoSize?: boolean
}
```

## Plugin API

### `AutoSizeColumnConfig`

```ts
export type AutoSizeColumnConfig = {
  // ui behavior mode
  mode?: ColumnAutoSizeMode;
  /**
   * autoSize for all columns
   * if allColumnes true all columns treated as autoSize, worse for performance
   * false by default
   */
  allColumns?: boolean;
  /**
   * assumption per characted size
   * by default defined as 8, can be changed in this config
   */
  letterBlockSize?: number;
  /** make size calculation exact
   * by default it based on assumption each character takes some space defined in letterBlockSize */
  preciseSize?: boolean;
};
```

---

### `ColumnAutoSizeMode`

```ts
enum ColumnAutoSizeMode {
  // increases column width on header click according the largest text value
    headerClickAutosize = 'headerClickAutoSize',
  // increases column width on data set and text edit, decreases performance
    autoSizeOnTextOverlap = 'autoSizeOnTextOverlap',
  // increases and decreases column width based on all items sizes, worst for performance
    autoSizeAll = 'autoSizeAll'
}
```

---

### `AutoSizeColumnPlugin`

The `AutoSizeColumnPlugin` is a plugin for the RevoGrid framework that provides automatic column resizing
functionality. It allows users to resize columns based on the content of the cells, providing a flexible
and user-friendly interface for data presentation.

 **Features**:
- Automatically resizes columns based on the content of the cells.
- Supports different modes of automatic resizing:
  - Header click autosize: Resizes columns when the header is clicked.
  - Text overlap autosize: Resizes columns when text is edited.
  - All columns autosize: Resizes all columns based on the content of the cells.

**Usage**:
- Add the `AutoSizeColumnPlugin` to the grid's plugins array.
- Configure the plugin using the `additionalData` property with the `autoSizeColumnConfig` key.

### Example
```typescript
import { AutoSizeColumnPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [AutoSizeColumnPlugin]; // Add the plugin to the grid
grid.additionalData = {
  autoSizeColumnConfig: {
    mode: ColumnAutoSizeMode.autoSizeOnTextOverlap,
  },
};
```

#### Dependencies

- **Event integration** `aftersourceset`, `afteredit`, `headerdblclick`: Integrates with grid lifecycle events to recalculate column widths.
- **Config integration** `additionalData.autoSizeColumnConfig`: Reads legacy auto-size configuration from additionalData.autoSizeColumnConfig.

```ts
class AutoSizeColumnPlugin {
  async setSource(source: DataType[]): Promise<void>;

  getLength(len?: any): number;

  afteredit(e: EditEvent);

  afterEditAll(e: EditEvent);

  getColumnSize(index: number, type: DimensionCols): number;

  /** Measure a column on demand without enabling continuous auto-size. */
  getColumnContentSize(column: ColumnRegular): number;

  columnSet(columns: Record<DimensionCols, ColumnRegular[]>);

  clearPromise();

  isRangeEdit(e: EditEvent): e is BeforeRangeSaveDataDetails;

  initiatePresizeElement(): HTMLElement;

  destroy();
}
```

---

# Column Collapse

URL: https://pro.rv-grid.com/api/column-collapse/
Source: src/content/docs/api/column-collapse.md

## Module Extensions

### `Group` (Extended from `@revolist/revogrid`)

Add collapsible property to Group interface

```ts
interface Group {
  /**
       * Whether the group is collapsible
       */
      collapsible?: boolean;
  /**
       * Whether the group is collapsed
       */
      collapsed?: boolean;
  /**
       * Custom placeholder configuration used when a collapsed group has no sealed columns.
       */
      placeholder?: string | ColumnTemplateFunc | ColumnCollapsePlaceholder;
  /**
       * Render collapsed top-level groups through their carrier leaf header when
       * every marked sibling is collapsed.
       */
      compactCollapsedHeader?: boolean
}
```

---

### `ColumnGrouping` (Extended from `@revolist/revogrid`)

```ts
interface ColumnGrouping {
  /**
       * Opt this group into compact single-row collapsed header projection.
       */
      compactCollapsedHeader?: boolean
}
```

---

### `ColumnRegular` (Extended from `@revolist/revogrid`)

Add sealed property to ColumnRegular interface

```ts
interface ColumnRegular {
  /**
       * Whether the column is sealed, if true the column will not be trimmed/collapsed
       */
      sealed?: boolean
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

Add column collapse event to HTMLRevoGridElementEventMap

```ts
interface HTMLRevoGridElementEventMap {
  /**
       * Column collapse event
       */
      [COLUMN_COLLAPSE_EVENT]: { group: Group };
  /**
       * Column expand event
       */
      [COLUMN_EXPAND_EVENT]: { group: Group }
}
```

## Plugin API

### `ColumnCollapsePlaceholder`

```ts
interface ColumnCollapsePlaceholder {
  header?: string | ColumnTemplateFunc;
  value?: (schema: CellTemplateProp, state: CollapsedGroupState) => unknown;
  cellTemplate?: NonNullable<CellTemplateProp['column']['cellTemplate']>;
  cellProperties?: PropertiesFunc;
  /**
     * Preserve the carrier column's filter configuration and filter-header UI.
     * Disabled by default because a generic placeholder may not represent the
     * carrier field's value.
     */
    preserveFilter?: boolean;
  /**
     * Preserve the carrier column's sortable state and active sort indicator.
     * Disabled by default because a generic placeholder may not represent the
     * carrier field's value.
     */
    preserveSorting?: boolean;
  /**
     * Optional filter proxy rendered on the group header while the group is
     * expanded. Its prop must identify the same aggregate represented by the
     * collapsed carrier.
     */
    filterColumn?: ColumnRegular
}
```

---

### `ColumnCollapsePlugin`

The `ColumnCollapsePlugin` is a plugin for the RevoGrid framework that enables collapsible columns
with content trimming functionality. It allows users to collapse and expand columns, reducing the
visual clutter and improving the overall user experience when dealing with large datasets.

 **Features**:
- Enables collapsible columns with content trimming
- Provides a visual indicator (▼) in the header to collapse and expand columns

**Usage**:
- Add the `ColumnCollapsePlugin` to the grid's plugins array.
- Add the `collapsible` property to the column configuration to enable collapsible columns.
- Add the `collapsed` property to the column configuration to set the initial collapsed state.
- Add the `children` property to the column configuration to define the columns to be collapsed.
- Add the `sealed` property to the column configuration to prevent the column from being trimmed.

### Example
```typescript
import { ColumnCollapsePlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    collapsible: true,
    collapsed: true,
    children: [
      {
        prop: 'age',
        sealed: true,
      },
    ],
  },
];
grid.plugins = [ColumnCollapsePlugin];
```

```ts
class ColumnCollapsePlugin {
  /** Returns whether a collapsible authored column group is currently collapsed. */
  isGroupCollapsed(group: Group, type: DimensionCols): boolean;

  /**
     * Applies an explicit collapsed state to an authored column group.
     * No-op when the group cannot be collapsed or already has the requested state.
     */
  setGroupCollapsed(group: Group, type: DimensionCols, collapsed: boolean): void;

  /** Toggles an authored collapsible column group. */
  toggleGroupCollapsed(group: Group, type: DimensionCols): void;

  destroy();
}
```

---

### `CollapsedGroupMode`

```ts
export type CollapsedGroupMode = 'sealed' | 'placeholder';
```

---

### `CollapsedGroupState`

```ts
interface CollapsedGroupState {
  key: string;
  mode: CollapsedGroupMode;
  group: Group;
  indexes: number[];
  visibleIndexes: number[];
  carrierIndex?: number;
  hiddenCount: number
}
```

---

# Column Dialog

URL: https://pro.rv-grid.com/api/column-dialog/
Source: src/content/docs/api/column-dialog.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  columnDialog?: ColumnDialogConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [COLUMN_DIALOG_OPEN_EVENT]: undefined;
  [COLUMN_DIALOG_CLOSE_EVENT]: undefined;
  [COLUMN_DIALOG_TOGGLE_EVENT]: undefined;
  [COLUMN_DIALOG_CHANGE_EVENT]: ColumnDialogChangeDetail
}
```

## Plugin API

### `buildColumnDialogRows`

```ts
export function buildColumnDialogRows({
  columnOrderByType,
  columnsByType,
  hiddenColumns,
  groupsByType,
}: BuildTreeOptions): ColumnDialogRow[];
```

---

### `buildColumnDialogRowsFromProviders`

```ts
export function buildColumnDialogRowsFromProviders(
  providers: PluginProviders,
  hiddenColumns: ReadonlySet<ColumnProp>,
): ColumnDialogRow[];
```

---

### `filterColumnDialogRows`

```ts
export function filterColumnDialogRows(
  rows: readonly ColumnDialogRow[],
  query: string,
): ColumnDialogRow[];
```

---

### `getDialogRowDescendantProps`

```ts
export function getDialogRowDescendantProps(
  rows: readonly ColumnDialogRow[],
  rowId: string,
): ColumnProp[];
```

---

### `resolveNextHiddenColumns`

```ts
export function resolveNextHiddenColumns(
  rows: readonly ColumnDialogRow[],
  hiddenColumns: ReadonlySet<ColumnProp>,
  rowId: string,
  visible: boolean,
): ColumnProp[];
```

---

### `resolveColumnDialogReorder`

```ts
export function resolveColumnDialogReorder({
  draggedRowId,
  position,
  rows,
  targetRowId,
}: ColumnDialogReorderRequest): ColumnDialogReorderResult;
```

---

### `normalizeHiddenColumns`

```ts
export function normalizeHiddenColumns(value: unknown): ColumnProp[];
```

---

### `ColumnCollection`

Column collection definition.
Used to access indexed data for columns.
Can be accessed via different events.

```ts
/**
 * Column collection definition.
 * Used to access indexed data for columns.
 * Can be accessed via different events.
 */
export type ColumnCollection = {
    /**
     * Columns as they are in stores
     */
    columns: Record<DimensionCols, ColumnRegular[]>;
    /**
     * Columns indexed by prop for quick access, it's possible to have multiple columns with same prop but not recommended
     */
    columnByProp: Record<ColumnProp, ColumnRegular[]>;
    /**
     * Grouped columns
     */
    columnGrouping: ColumnGroupingCollection;
    /**
     * Max level of grouping
     */
    maxLevel: number;
    /**
     * Sorting
     */
    sort: Record<ColumnProp, ColumnRegular>;
};
```

---

### `resolveColumnDialogGridTheme`

```ts
export function resolveColumnDialogGridTheme(theme: ColumnDialogTheme | undefined): 'compact' | 'darkCompact';
```

---

### `createDialogColumns`

```ts
export function createDialogColumns(
  onToggle: (rowId: string, visible: boolean) => void,
  disableDrag = false,
): ColumnRegular[];
```

---

### `ColumnDialog`

```ts
export function ColumnDialog({
  config,
  hiddenColumns,
  open,
  rows,
  onClose,
  onHiddenColumnsChange,
  onReorder,
}: ColumnDialogProps);
```

---

### `COLUMN_DIALOG_OPEN_EVENT`

```ts
COLUMN_DIALOG_OPEN_EVENT: string;
```

---

### `COLUMN_DIALOG_CLOSE_EVENT`

```ts
COLUMN_DIALOG_CLOSE_EVENT: string;
```

---

### `COLUMN_DIALOG_TOGGLE_EVENT`

```ts
COLUMN_DIALOG_TOGGLE_EVENT: string;
```

---

### `COLUMN_DIALOG_CHANGE_EVENT`

```ts
COLUMN_DIALOG_CHANGE_EVENT: string;
```

---

### `ColumnDialogApplyMode`

```ts
export type ColumnDialogApplyMode = 'immediate';
```

---

### `ColumnDialogTheme`

```ts
export type ColumnDialogTheme = 'light' | 'dark';
```

---

### `ColumnDialogConfig`

```ts
interface ColumnDialogConfig {
  title?: string;
  searchPlaceholder?: string;
  closeLabel?: string;
  width?: number | string;
  height?: number | string;
  /** Omits drag handles and disables column reordering. Defaults to `false`. */
    disableDrag?: boolean;
  /** Color mode for the compact dialog grid and surface. Defaults to `light`. */
    theme?: ColumnDialogTheme;
  /**
     * @deprecated The Pro dialog always hides its internal grid attribution.
     * This option is retained as a no-op for source compatibility.
     */
    hideAttribution?: boolean
}
```

---

### `ColumnDialogRowKind`

```ts
export type ColumnDialogRowKind = 'group' | 'column';
```

---

### `ColumnDialogVisibilityState`

```ts
export type ColumnDialogVisibilityState = 'checked' | 'unchecked' | 'indeterminate';
```

---

### `ColumnDialogRow`

```ts
interface ColumnDialogRow {
  id: string;
  parentId: string | null;
  name: string;
  prop: ColumnProp | null;
  kind: ColumnDialogRowKind;
  type: DimensionCols;
  physicalIndex: number | null;
  sourceIndexes: number[];
  order: number;
  depth: number;
  visible: boolean;
  visibilityState: ColumnDialogVisibilityState;
  rowDrag: boolean
}
```

---

### `ColumnDialogChangeDetail`

```ts
interface ColumnDialogChangeDetail {
  hiddenColumns: ColumnProp[]
}
```

---

### `ColumnDialogReorderRequest`

```ts
interface ColumnDialogReorderRequest {
  rows: readonly ColumnDialogRow[];
  draggedRowId: string;
  targetRowId: string;
  position: 'before' | 'after'
}
```

---

### `ColumnDialogReorderResult`

```ts
interface ColumnDialogReorderResult {
  valid: boolean;
  reason?: string;
  type?: DimensionCols;
  proxyItems?: number[]
}
```

---

### `ColumnDialogPlugin`

Column manager dialog for RevoGrid Pro.

`ColumnDialogPlugin` renders a modal column-management dialog backed by an
internal RevoGrid tree. It lists all host grid columns, including columns
currently hidden by `ColumnHidePlugin`, and lets users search, toggle
visibility, and reorder columns or column groups inside their current
parent/pin section. Set `columnDialog.disableDrag` to use visibility-only
mode without drag handles or row-order behavior. The internal grid always
uses compact density, hides its implementation-detail attribution, and
`columnDialog.theme` selects light or dark mode.

Visibility is intentionally delegated to `ColumnHidePlugin`; this plugin
auto-installs it when it is not already registered and writes changes through
`grid.hideColumns`.

### Usage

```ts
import { ColumnDialogPlugin } from '@revolist/revogrid-pro';

const grid = document.querySelector('revo-grid')!;

grid.plugins = [ColumnDialogPlugin];
grid.columnDialog = {
  title: 'Columns',
  searchPlaceholder: 'Search columns...',
};

// Open with a grid event.
grid.dispatchEvent(new CustomEvent('revocolumndialogopen'));

// Or open through the plugin instance.
const plugins = await grid.getPlugins();
plugins.getByClass(ColumnDialogPlugin)?.open();

grid.addEventListener('revocolumndialogchange', (event) => {
  console.log(event.detail.hiddenColumns);
});
```

Public events:
- `revocolumndialogopen` opens the dialog.
- `revocolumndialogclose` closes the dialog.
- `revocolumndialogtoggle` toggles open state.
- `revocolumndialogchange` emits after visibility or ordering changes.

#### Dependencies

- **Auto-installed** `ColumnHidePlugin`: Uses ColumnHidePlugin as the only host visibility engine.
- **Event integration** `COLUMN_UPDATED_EVENT`, `HIDDEN_COLUMNS_UPDATED_EVENT`, `COLUMN_DRAG_END_EVENT`: Tracks host column definitions, hidden-column state, and host column reorder.

```ts
class ColumnDialogPlugin {
  open(): void;

  close(): void;

  toggle(): void;

  destroy(): void;
}
```

---

# Column Group Panel

URL: https://pro.rv-grid.com/api/column-group-panel/
Source: src/content/docs/api/column-group-panel.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /** Configuration for the column group panel. */
      columnGroupPanel?: ColumnGroupPanelConfig;
  /** Kebab-case alias for framework bindings. */
      'column-group-panel'?: ColumnGroupPanelConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  columngroupingchange: ColumnGroupPanelChangeDetail
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /** @deprecated Use `grid.columnGroupPanel` instead. */
      columnGroupPanel?: ColumnGroupPanelConfig;
  /** @deprecated Use `grid.columnGroupPanel` instead. */
      columnGroupingPanel?: ColumnGroupPanelConfig
}
```

## Plugin API

### `ColumnGroupPanelChangeDetail`

```ts
interface ColumnGroupPanelChangeDetail {
  props: ColumnProp[];
  grouping: GroupingOptions
}
```

---

### `ColumnGroupPanelConfig`

```ts
interface ColumnGroupPanelConfig {
  /**
     * Text to display in the group panel when no columns are grouped.
     * @default 'Drag columns here to group by row.'
     */
    emptyPanelText?: string;
  /** Show the grouping position before each key. @default true */
    showOrder?: boolean
}
```

---

### `ColumnGroupPanelPlugin`

Adds a header panel for creating, removing, and reordering row groupings.

**Example:**
```typescript
const grid = document.createElement('revo-grid');
grid.plugins = [ColumnGroupPanelPlugin];
grid.columnGroupPanel = { emptyPanelText: 'Drop columns here' };
```

#### Dependencies

- **Config integration** `core-grouping`: Writes grid grouping props through the core grouping API.
- **Event integration** `columndragstart`, `columndragmousemove`, `beforecolumndragend`, `columndragend`: Shares the column-move gesture lifecycle for header-to-panel grouping.

```ts
class ColumnGroupPanelPlugin {
  addGrouping(columnProp: ColumnProp);

  removeGrouping(indexOrProp: number | ColumnProp);

  reorderGrouping(draggedProp: ColumnProp, targetIndex: number);

  setGroupings(props: ColumnProp[]);

  getGroupings(): ColumnProp[];

  destroy();
}
```

---

### `ColumnGroupPanelDragController`

```ts
class ColumnGroupPanelDragController {
  destroy();
}
```

---

### `normalizeColumnGroupings`

```ts
export function normalizeColumnGroupings(props?: ColumnProp[]): ColumnProp[];
```

---

### `moveColumnGrouping`

```ts
export function moveColumnGrouping(
  groupings: ColumnProp[],
  draggedProp: ColumnProp,
  rawTargetIndex: number,
): ColumnProp[];
```

---

### `resolveColumnGroupingDropIndex`

```ts
export function resolveColumnGroupingDropIndex(
  currentIndex: number,
  measuredTargetIndex: number,
): number;
```

---

### `withColumnGroupings`

```ts
export function withColumnGroupings(
  grouping: GroupingOptions | undefined,
  props: ColumnProp[],
): GroupingOptions;
```

---

### `ColumnGroupPanelView`

```ts
class ColumnGroupPanelView {
  setConfig(config: ColumnGroupPanelConfig);

  render(groupings: ColumnProp[]);

  showDropPreview(index: number, label: string);

  clearDropPreview();

  getDropIndex(clientX: number): number;

  getPanelDropIndex(clientX: number, clientY: number): number | null;

  destroy();
}
```

---

# Column Group Render Sync

URL: https://pro.rv-grid.com/api/column-group-render-sync/
Source: src/content/docs/api/column-group-render-sync.md

### `ensureColumnGroupRenderSyncPlugin`

```ts
export function ensureColumnGroupRenderSyncPlugin(
  revogrid: HTMLRevoGridElement,
  providers: PluginProviders,
): ColumnGroupRenderSyncPlugin;
```

---

### `ColumnGroupRenderSyncPlugin`

#### Dependencies

- **Event integration** `BEFORE_GROUP_HEADER_RENDER_EVENT`: Projects source-indexed column groups to visible render indexes during grouped header rendering.
- **Event integration** `COLUMN_UPDATED_EVENT`: Refreshes source-indexed group snapshots when columns are replaced.

```ts
class ColumnGroupRenderSyncPlugin {
  refreshSourceGroups(type?: DimensionCols): void;
}
```

---

# Column Hide

URL: https://pro.rv-grid.com/api/column-hide/
Source: src/content/docs/api/column-hide.md

## Module Extensions

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /**
       * Event triggered when hidden columns are updated
       */
      hiddencolumnsupdated: { hiddenColumns: Set<ColumnProp> }
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /**
       * Columns to hide by prop.
       */
      hideColumns?: ColumnHideConfig;
  /**
       * Kebab-case alias for framework bindings.
       */
      'hide-columns'?: ColumnHideConfig;
  /**
       * Columns to hide by prop.
       * @deprecated Use `grid.hideColumns` instead.
       */
      columnHide?: ColumnHideConfig;
  /**
       * Kebab-case alias for the legacy `columnHide` property.
       * @deprecated Use `grid.hideColumns` or `hide-columns` instead.
       */
      'column-hide'?: ColumnHideConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

Additional data property for column hide configuration

```ts
interface AdditionalData {
  /**
       * Additional data property for column hide configuration
       * @deprecated Use `grid.hideColumns` instead.
       * @example
       * grid.additionalData = {
       *   // Hide columns with indices 1, 2, and 3
       *   hiddenColumns: [1, 2, 3],
       * }
       */
      hiddenColumns?: HiddenColumnsConfig
}
```

## Plugin API

### `ColumnHidePlugin`

The `ColumnHidePlugin` is a plugin for the RevoGrid framework that enables column hiding functionality
based on the `hide-columns` attribute, `hideColumns` property, or
`additionalData.hiddenColumns`. It allows users to hide specific columns
by providing their column `prop` values.

**Features**:
- Enables column hiding through the `hide-columns` attribute
- Supports runtime updates through the `hideColumns` property
- Supports legacy runtime updates through the `columnHide` property
- Supports hiding columns through `additionalData.hiddenColumns`
- Automatically updates when the attribute, property, or additionalData changes
- Preserves column state when columns are updated
- Supports multiple framework attribute formats:
  - Web component: `hide-columns="name,age"`
  - React: `hideColumns={['name', 'age']}`
  - Angular/Vue/Svelte: bind `hideColumns` as an array

**Usage**:
```html
<!-- Web component attribute -->
<revo-grid hide-columns="name,age"></revo-grid>

<!-- React -->
<RevoGrid hideColumns={['name', 'age']} />

<!-- Property update -->
grid.hideColumns = ['name', 'age'];

<!-- Legacy property update -->
grid.columnHide = ['name', 'age'];

<!-- Using additionalData -->
<revo-grid></revo-grid>
<script>
  const grid = document.querySelector('revo-grid');
  grid.additionalData = {
    hiddenColumns: [1, 2, 3]
  };
</script>
```

#### Dependencies

- **Event integration** `COLUMN_UPDATED_EVENT`: Integrates with column update events to preserve hidden-column state.
- **Event integration** `COLUMN_DRAG_END_EVENT`: Keeps hidden-column trim order aligned after visible columns are moved.
- **Config integration** `grid.hideColumns`, `additionalData.hiddenColumns`: Reads direct hidden-column configuration from grid.hideColumns or legacy additionalData.hiddenColumns.

```ts
class ColumnHidePlugin {}
```

---

### `HiddenColumnsConfig`

The `HiddenColumnsConfig` type
specifies which columns should be hidden in the grid.

**Usage**:
- Import the `HiddenColumnsConfig` type to define hidden columns in RevoGrid components.
- Assign the desired hidden columns configuration to `grid.hideColumns` to control which columns
  are hidden.

**Example:**
```typescript
:
```typescript

const grid = document.createElement('revo-grid');
grid.plugins = [ColumnHidePlugin];

grid.hideColumns = [1, 2, 3]; // Hide columns with indices 1, 2, and 3
```

This configuration type allows developers to programmatically control which columns
are hidden in the grid, enhancing the flexibility of the grid's display options.
```

```ts
/**
 * The `HiddenColumnsConfig` type
 * specifies which columns should be hidden in the grid.
 *
 * **Usage**:
 * - Import the `HiddenColumnsConfig` type to define hidden columns in RevoGrid components.
 * - Assign the desired hidden columns configuration to `grid.hideColumns` to control which columns
 *   are hidden.
 *
 * @example:
 * ```typescript
 * import { ColumnHidePlugin } from '@revolist/revogrid-pro';
 *
 * const grid = document.createElement('revo-grid');
 * grid.plugins = [ColumnHidePlugin];
 *
 * grid.hideColumns = [1, 2, 3]; // Hide columns with indices 1, 2, and 3
 * ```
 *
 * This configuration type allows developers to programmatically control which columns
 * are hidden in the grid, enhancing the flexibility of the grid's display options.
 */

export type HiddenColumnsConfig = ColumnProp[];
```

---

### `ColumnHideConfig`

```ts
export type ColumnHideConfig = HiddenColumnsConfig | string;
```

---

# Column Move With Groups

URL: https://pro.rv-grid.com/api/column-move-with-groups/
Source: src/content/docs/api/column-move-with-groups.md

### `ColumnMoveAdvancedPlugin`

```ts
class ColumnMoveAdvancedPlugin {
  dragStart({ event, data }: DragStartEventDetails);

  doMove(e: MouseEvent);

  clearOrder();

  clearSubscriptions();

  onMouseUp(e: MouseEvent);
}
```

---

# Column Selection

URL: https://pro.rv-grid.com/api/column-selection/
Source: src/content/docs/api/column-selection.md

## Module Extensions

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /** Fires before a pointer or keyboard column-selection intent is applied. */
      beforecolumnselection: ColumnSelectionIntent
}
```

## Plugin API

### `ColumnSelectionPlugin`

Adds spreadsheet-style whole-column selection to RevoGrid.

Header clicks select columns, Shift extends an anchored span, Ctrl/Cmd
toggles disjoint columns, pointer drag selects a span, and Ctrl+Space selects
the focused cell's column. Sort/filter/resize affordances keep their native
behavior and do not change the column selection.

#### Dependencies

- **Auto-installed** `MultiRangeSelectionPlugin`: Uses MultiRangeSelectionPlugin for disjoint range rendering and clipboard behavior.
- **Event integration** `column-selection-handoff`: Clears mutually exclusive interactive row-header selection before selecting columns.
- **Event integration** `COLUMN_DRAG_START_EVENT`, `COLUMN_DRAG_MOVE_EVENT`, `COLUMN_DRAG_END_EVENT`: Keeps whole-column selection isolated from and aligned after column-move gestures.

```ts
class ColumnSelectionPlugin {
  /** Returns selected column props in current visual order. */
  getSelectedColumns(): ColumnProp[];

  /** Clears private column state before row-header selection takes ownership. */
  clearFromRowHeader();

  /** Clears private column state before select-all takes ownership. */
  clearFromSelectAll();

  destroy(): void;
}
```

---

### `resolveColumnSelection`

```ts
export function resolveColumnSelection({
  ordered,
  selected,
  anchor,
  target,
  shift,
  additive,
}: ResolveColumnSelectionOptions): ResolvedColumnSelection;
```

---

### `reconcileSelectedColumns`

```ts
export function reconcileSelectedColumns(
  ordered: ColumnSelectionAddress[],
  selected: Iterable<string>,
);
```

---

### `buildColumnSelectionRanges`

```ts
export function buildColumnSelectionRanges(
  ordered: ColumnSelectionAddress[],
  selected: Iterable<string>,
  rowLengths: Partial<Record<DimensionRows, number>>,
): MultiRangeSelectionRange[];
```

---

### `findActiveRangeIndex`

```ts
export function findActiveRangeIndex(
  ranges: MultiRangeSelectionRange[],
  ordered: ColumnSelectionAddress[],
  activeId: string | null,
);
```

---

### `ColumnSelectionAddress`

```ts
export type ColumnSelectionAddress = {
  id: string;
  prop: ColumnProp;
  index: number;
  type: DimensionCols;
};
```

---

### `ColumnSelectionMode`

```ts
export type ColumnSelectionMode = 'replace' | 'extend' | 'toggle' | 'add';
```

---

### `ResolveColumnSelectionOptions`

```ts
export type ResolveColumnSelectionOptions = {
  ordered: ColumnSelectionAddress[];
  selected: Iterable<string>;
  anchor: string | null;
  target: string;
  shift: boolean;
  additive: boolean;
};
```

---

### `ResolvedColumnSelection`

```ts
export type ResolvedColumnSelection = {
  selected: Set<string>;
  anchor: string;
  mode: ColumnSelectionMode;
};
```

---

### `ColumnSelectionSource`

```ts
export type ColumnSelectionSource = 'header' | 'drag' | 'keyboard';
```

---

### `ColumnSelectionIntent`

```ts
export type ColumnSelectionIntent = {
  source: ColumnSelectionSource;
  mode: ColumnSelectionMode;
  column: ColumnRegular;
  selectedColumns: ColumnProp[];
  anchor: ColumnProp;
  originalEvent: MouseEvent | PointerEvent | KeyboardEvent;
};
```

---

### `ColumnSelectionHandoffProvider`

Runtime contract used to clear mutually exclusive row-header state.

```ts
interface ColumnSelectionHandoffProvider {
  clearFromColumnHeader(): void
}
```

---

# Column Stretch

URL: https://pro.rv-grid.com/api/column-stretch/
Source: src/content/docs/api/column-stretch.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  /**
       * Direct column stretch configuration.
       */
      stretch?: StretchConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

Additional data property for column stretch configuration

```ts
interface AdditionalData {
  /**
       *
       * Additional data property for column stretch configuration
       * @deprecated Use `grid.stretch` instead.
       * @example
       * grid.additionalData = {
       *   // Stretch all columns to utilize available space
       *   stretch: 'all',
       *   // Stretch the first column to utilize available space
       *   stretch: 1,
       *   // Stretch the last column to utilize available space
       *   stretch: 'last',
       *   // Stretch the last column and preserve column sizes when columns are replaced
       *   stretch: {
       *     mode: 'last',
       *     preserveSizesOnColumnChange: true,
       *   },
       * }
       */
      stretch?: StretchConfig
}
```

## Plugin API

### `ColumnStretchPlugin`

The ColumnStretchPlugin is a RevoGrid plugin designed to dynamically adjust column
widths based on available space within the grid. It ensures that extra space is
efficiently utilized by increasing the width of specified columns, enhancing the
presentation of data without manual resizing.

**Key Features**:
- Automatically stretches the width of columns to fill any remaining space in the grid.
- Supports configurations for stretching all columns, a specific column by index,
  or only the last column.
- Observes direct `grid.stretch` and legacy `additionalData.stretch` config
  updates, then adjusts column sizes based on grid dimensions or configuration changes.
- Utilizes `ResizeObserver` and a debounced `applyStretch` function to efficiently
  manage size recalculations during viewport size changes.

**Usage**:
- Integrate the plugin into a RevoGrid instance by adding it to the grid's plugin array.
- Configure the stretching behavior through direct `grid.stretch` or legacy
  `additionalData.stretch`, specifying modes like 'none', 'all', or a specific index.

### Example
```typescript
import { ColumnStretchPlugin } from './column-stretch';

const grid = document.createElement('revo-grid');
grid.plugins = [ColumnStretchPlugin];

grid.stretch = 'last'; // Stretch the last column to fit available space
```

By using this plugin, developers can enhance the adaptability and visual layout
of their RevoGrid, ensuring optimal use of grid space and improving data display
without manual intervention.

#### Dependencies

- **Config integration** `auto-size-column`: Skips columns marked with autoSize when applying stretch sizing.
- **Config integration** `additionalData.stretch`: Reads legacy stretch configuration from additionalData.stretch.

```ts
class ColumnStretchPlugin {
  destroy(): void;
}
```

---

### `StretchMode`

The `StretchConfig` type
specifies how extra space in the grid should be utilized by adjusting the width
of columns.

**Usage**:
- Import the `StretchConfig` type to define stretching behavior in RevoGrid components.
- Assign the desired stretching configuration to the grid's `additionalData.stretch`
  property to control how columns adjust to available space.

**Example:**
```typescript
:
```typescript

const grid = document.createElement('revo-grid');
grid.plugins = [ColumnStretchPlugin];

grid.additionalData = {
  stretch: 'all', // Stretch all columns to utilize available space
};
```

This configuration type allows developers to customize how columns adapt to
changes in grid size, ensuring optimal data presentation and grid layout.
```

```ts
// column-stretch/stretch.types.ts

/**
 * The `StretchConfig` type
 * specifies how extra space in the grid should be utilized by adjusting the width
 * of columns.
 *
 * **Usage**:
 * - Import the `StretchConfig` type to define stretching behavior in RevoGrid components.
 * - Assign the desired stretching configuration to the grid's `additionalData.stretch`
 *   property to control how columns adjust to available space.
 *
 * @example:
 * ```typescript
 * import { ColumnStretchPlugin } from '@revolist/revogrid-pro';
 *
 * const grid = document.createElement('revo-grid');
 * grid.plugins = [ColumnStretchPlugin];
 *
 * grid.additionalData = {
 *   stretch: 'all', // Stretch all columns to utilize available space
 * };
 * ```
 *
 * This configuration type allows developers to customize how columns adapt to
 * changes in grid size, ensuring optimal data presentation and grid layout.
 */

export type StretchMode = 'none' | 'last' | 'all' | number;
```

---

### `StretchOptions`

```ts
export type StretchOptions = {
  /**
   * Stretch mode.
   */
  mode: StretchMode;
  /**
   * Preserve rendered column sizes for matching column props when columns are replaced.
   * Matching uses the column dimension type and `prop`, so reordered columns keep their
   * previous width while new columns use their configured/default width.
   */
  preserveSizesOnColumnChange?: boolean;
};
```

---

### `StretchConfig`

```ts
export type StretchConfig = false | StretchMode | StretchOptions;
```

---

### `ColumnStretchSizePreserve`

```ts
class ColumnStretchSizePreserve {
  snapshot();

  restore(columns: ColumnCollection['columns']);
}
```

---

# Column Type Boolean

URL: https://pro.rv-grid.com/api/column-type-boolean/
Source: src/content/docs/api/column-type-boolean.md

### `formatBooleanValue`

```ts
export function formatBooleanValue(
  value: unknown,
  localeText: Pick<BooleanColumnTypeLocaleText, 'yes' | 'no'> = BOOLEAN_COLUMN_TYPE_LOCALE_TEXT,
): string;
```

---

### `createBooleanDropdownOptions`

```ts
export function createBooleanDropdownOptions(
  localeText: BooleanColumnTypeLocaleText = BOOLEAN_COLUMN_TYPE_LOCALE_TEXT,
): DropdownOption<boolean | null>[];
```

---

### `createBooleanColumnType`

```ts
export function createBooleanColumnType(
  options: BooleanColumnTypeOptions = {},
): BooleanColumnType;
```

---

### `BooleanColumnValue`

```ts
export type BooleanColumnValue = boolean | null | undefined;
```

---

### `BooleanColumnTypeLocaleText`

```ts
interface BooleanColumnTypeLocaleText {
  yes: string;
  no: string;
  notSet: string;
  editorAriaLabel: string
}
```

---

### `BooleanColumnTypeOptions`

```ts
interface BooleanColumnTypeOptions {
  localeText?: Partial<BooleanColumnTypeLocaleText>
}
```

---

### `BOOLEAN_COLUMN_TYPE_LOCALE_TEXT`

```ts
BOOLEAN_COLUMN_TYPE_LOCALE_TEXT: {
  yes: string;
  no: string;
  notSet: string;
  editorAriaLabel: string;
};
```

---

### `BooleanDropdownEditor`

Dropdown editor adapter that presents every nullish boolean as Not set.

```ts
class BooleanDropdownEditor {}
```

---

### `BooleanColumnType`

Tri-state boolean column type backed by the Pro dropdown editor.

Values remain `true`, `false`, or `null`; locale text affects display only.
Missing and null values render as empty cells while the editor exposes the
localized Not set option.

```ts
class BooleanColumnType {}
```

---

# Column Type Progress

URL: https://pro.rv-grid.com/api/column-type-progress/
Source: src/content/docs/api/column-type-progress.md

### `ProgressColumnType`

The `ProgressColumnType` class implements a custom column type for the RevoGrid, designed
to visually display numeric values as progress bars within grid cells. It extends the
functionality of the standard `ColumnType` by providing validation and rendering logic
specific to progress indicators.

 **Features**:
- Validation: Ensures the value is a number between 0 and 100, representing a valid
  percentage for progress visualization.
- Custom cell rendering: Uses a `cellTemplate` function to render the progress bar,
  adapting the visual fill based on the cell value.

How to use:
- Integrate `ProgressColumnType` into your grid's column configuration to enable
  progress bar visualization.
- Assign the `cellTemplate` of this class to the corresponding column definition to
  render the progress bars.

### Example
```typescript
import { ProgressColumnType } from './progress-column-type';

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'progress',
    name: 'Progress',
    cellTemplate: ProgressColumnType.prototype.cellTemplate, // Use progress bar template
  },
];
```

This class enhances user experience by providing a clear visual representation of
progress data directly within the grid interface, making data interpretation more
intuitive and visually appealing.

```ts
class ProgressColumnType {}
```

---

# Column Type Rate

URL: https://pro.rv-grid.com/api/column-type-rate/
Source: src/content/docs/api/column-type-rate.md

### `RatingColumnType`

The RatingColumnType class defines a custom column type for the RevoGrid, specifically
designed to handle and render rating values as a series of star icons. This custom type
includes a validation method to ensure rating values are within an acceptable range (0 to 5)
and a `cellTemplate` method for rendering the visual representation of these ratings.

**Key Features**:
- Validation: Ensures rating values are between 0 and 5, inclusive.
- Custom cell rendering: Displays rating as stars, using a `cellTemplate` function to map
  numeric values to visual elements.

**Usage**:
- Implement the RatingColumnType in the grid's column configuration to apply this rating
  visualization logic.
- Utilize the `cellTemplate` function provided by this class within your column definitions
  to render ratings.

### Example
```typescript
import { RatingColumnType } from './rating-column-type';

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'rating',
    name: 'User Rating',
    cellTemplate: RatingColumnType.prototype.cellTemplate, // Apply custom rating cell template
  },
];
```

This class enhances the grid's capability to visually represent rating data, facilitating
a more intuitive user experience for reviewing rating values.

```ts
class RatingColumnType {}
```

---

# Conditional Formatting

URL: https://pro.rv-grid.com/api/conditional-formatting/
Source: src/content/docs/api/conditional-formatting.md

### `ConditionalFormattingDialogPlugin`

#### Dependencies

- **Auto-installed** `DialogPlugin`: Uses the shared Pro dialog runtime for conditional-formatting editors.

```ts
class ConditionalFormattingDialogPlugin {
  open(options: ConditionalFormattingDialogOpenOptions): void;

  close(): void;
}
```

---

### `createConditionalFormattingEditor`

```ts
export function createConditionalFormattingEditor({
  document,
  localeText,
  operators,
  initialValue,
}: ConditionalFormattingEditorOptions): ConditionalFormattingEditor;
```

---

### `ConditionalFormattingEditor`

```ts
interface ConditionalFormattingEditor {
  readonly element: HTMLElement;
  readonly secondValueField: HTMLLabelElement;
  readonly preview: HTMLElement;
  getDraft(): ConditionalFormattingDialogDraft;
  isValid(): boolean
}
```

---

### `ConditionalFormattingOperatorOption`

```ts
interface ConditionalFormattingOperatorOption {
  readonly value: string;
  readonly label: string;
  readonly usesSecondValue?: boolean
}
```

---

### `ConditionalFormattingDialogDraft`

```ts
interface ConditionalFormattingDialogDraft {
  readonly operator: string;
  readonly value: string;
  readonly secondValue: string;
  readonly backgroundColor: string;
  readonly textColor: string
}
```

---

### `ConditionalFormattingDialogLocaleText`

```ts
interface ConditionalFormattingDialogLocaleText {
  readonly description: string;
  readonly rule: string;
  readonly condition: string;
  readonly value: string;
  readonly secondValue: string;
  readonly valuePlaceholder: string;
  readonly secondValuePlaceholder: string;
  readonly appearance: string;
  readonly background: string;
  readonly text: string;
  readonly preview: string;
  readonly sampleValue: string;
  readonly clearRules: string;
  readonly cancel: string;
  readonly apply: string
}
```

---

### `ConditionalFormattingDialogOpenOptions`

```ts
interface ConditionalFormattingDialogOpenOptions {
  readonly title: string;
  readonly closeLabel: string;
  readonly localeText: ConditionalFormattingDialogLocaleText;
  readonly operators: readonly ConditionalFormattingOperatorOption[];
  readonly initialValue?: Partial<ConditionalFormattingDialogDraft>;
  readonly onApply: (draft: ConditionalFormattingDialogDraft) => void;
  readonly onClear: () => void
}
```

---

# Context Menu

URL: https://pro.rv-grid.com/api/context-menu/
Source: src/content/docs/api/context-menu.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /**
       * Context menu configuration for row and body-cell targets.
       */
      rowContextMenu?: ContextMenuConfig;
  /**
       * Context menu configuration for column-header targets.
       */
      columnContextMenu?: ContextMenuConfig;
  /**
       * Legacy/shared context menu configuration. Used as a fallback when target-specific
       * row/column configs are not provided.
       */
      contextMenu?: ContextMenuConfig;
  /** Kebab-case alias for framework/native custom element bindings. */
      'row-context-menu'?: ContextMenuConfig;
  /** Kebab-case alias for framework/native custom element bindings. */
      'column-context-menu'?: ContextMenuConfig;
  /** Kebab-case alias for framework/native custom element bindings. */
      'context-menu'?: ContextMenuConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * The context menu configuration for row and body-cell targets.
       *
       * @example
       * ```typescript
       * grid.additionalData = {
       *   rowContextMenu: { items: [{ name: 'Edit', action: () => console.log('Edit action') }] },
       * };
       * ```
       *
       * Prefer the direct `grid.rowContextMenu` property when the framework wrapper supports it.
       */
      rowContextMenu?: ContextMenuConfig;
  /**
       * The context menu configuration for column-header targets.
       *
       * @example
       * ```typescript
       * grid.additionalData = {
       *   columnContextMenu: { items: [{ name: 'Autosize', action: () => console.log('Autosize') }] },
       * };
       * ```
       *
       * Prefer the direct `grid.columnContextMenu` property when the framework wrapper supports it.
       */
      columnContextMenu?: ContextMenuConfig
}
```

## Plugin API

### `getContextMenuPrimaryShortcut`

```ts
export function getContextMenuPrimaryShortcut(
  key: string,
  platform = globalThis.navigator?.platform,
): string;
```

---

### `getContextMenuFilterPlugin`

Locate the active Core or Pro filter runtime without forcing filter setup.

```ts
export function getContextMenuFilterPlugin(
  context: ContextMenuActionContext,
): ContextMenuFilterPlugin | undefined;
```

---

### `openContextMenuColumnFilter`

Open the existing filter popup while preserving the original synchronous API.

```ts
export function openContextMenuColumnFilter(
  context: ContextMenuActionContext,
  column: ColumnRegular,
): boolean;
```

---

### `openContextMenuColumnFilterAsync`

Open the existing filter popup and await its full async lifecycle.

```ts
export async function openContextMenuColumnFilterAsync(
  context: ContextMenuActionContext,
  column: ColumnRegular,
): Promise<boolean>;
```

---

### `createContextMenuCellFilterItems`

Build the standard value-filter submenu used by the Data Grid preset.
Returns no items when the focused column or active filter runtime cannot
apply a filter.

```ts
export function createContextMenuCellFilterItems(
  options: ContextMenuCellFilterOptions,
): ContextMenuItem[];
```

---

### `applyContextMenuCellValueFilter`

Apply the standard keep/exclude predicate used by context-menu filtering.

```ts
export async function applyContextMenuCellValueFilter(
  filter: ContextMenuCellFilterRuntime,
  column: ColumnRegular,
  model: DataType,
  exclude: boolean,
): Promise<void>;
```

---

### `ContextMenuCellFilterRuntime`

```ts
export type ContextMenuCellFilterRuntime = {
  multiFilterItems: Record<ColumnProp, Array<{
    id: number;
    type: string;
    value?: unknown;
    relation?: string;
  }>>;
  onFilterChange(detail: unknown): void | Promise<void>;
  onFilterReset(prop?: ColumnProp): void | Promise<void>;
};
```

---

### `ContextMenuCellFilterLabels`

```ts
interface ContextMenuCellFilterLabels {
  readonly keepOnly?: string;
  readonly exclude?: string;
  readonly open?: string;
  readonly clear?: string
}
```

---

### `ContextMenuCellFilterOptions`

```ts
interface ContextMenuCellFilterOptions {
  readonly actionContext: ContextMenuActionContext;
  readonly column: ColumnRegular;
  readonly model: DataType;
  readonly labels?: ContextMenuCellFilterLabels
}
```

---

### `ContextMenuPlugin`

Adds configurable context menus to RevoGrid.

The plugin supports separate `rowContextMenu` and `columnContextMenu`
configurations while keeping `contextMenu` as a legacy fallback. Column menus
receive the current column, virtual column index, and column section, so a
single `columnContextMenu` can resolve different menu items for regular,
left-pinned, right-pinned, or specific columns.

**Example:**
```typescript
import { ContextMenuPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [ContextMenuPlugin];
grid.rowContextMenu = { items: [{ name: 'Delete row' }] };
grid.columnContextMenu = {
  items: [{ name: 'Autosize column' }],
  resolve(context) {
    if (context.target === 'column' && context.columnType === 'colPinStart') {
      return { items: [{ name: 'Unpin left column' }] };
    }
  },
};
```

#### Dependencies

- **Event integration** `RowHeaderPlugin`: Integrates with RowHeaderPlugin row menu events when present.

```ts
class ContextMenuPlugin {
  /**
     * Registers additive items that are resolved whenever a context menu opens.
     *
     * The application config and its `resolve` callback run first. Contributions
     * are then appended in ascending `order`, with registration order breaking
     * ties. The returned disposer is safe to call more than once.
     */
  registerContribution(contribution: ContextMenuContribution): () => void;

  /**
     * Applies defaults to a partial context menu config.
     *
     * @param config - User-provided menu config.
     * @param targetSelectors - Default selectors for the target-specific config.
     */
  getConfig(config: Partial<ContextMenuConfig> = {}, targetSelectors: string[] = ['.rgCell']);

  /**
     * Resolves a rendered header target to the same semantic column context used
     * by the shared context menu.
     */
  resolveColumnContext(
    target: HTMLElement,
    event?: MouseEvent,
  ): ColumnContextMenuOpenContext;

  /**
     * Hides the context menu popup without clearing the active config.
     */
  close(restoreFocus = true);

  /**
     * Opens the context menu for a DOM target.
     *
     * If `menuTarget` is provided, that target config is used directly. Otherwise
     * the plugin inspects the DOM target and chooses the column menu before the row
     * menu. The selected config is passed through `resolve` before rendering.
     *
     * @param target - Element that should anchor or identify the menu target.
     * @param event - Pointer event used for positioning and resolver context.
     * @param menuTarget - Optional explicit target used by row-header menu events.
     */
  async open(
    target: EventTarget | null,
    event?: MouseEvent,
    menuTarget?: ContextMenuTarget,
    cell?: ContextMenuCellContext,
  );

  clearSubscriptions();

  destroy();
}
```

---

### `ContextMenuTarget`

Supported high-level targets for the context menu.

`row` covers body cells and row-menu buttons. `column` covers column header
cells, including pinned column sections.

```ts
/**
 * Supported high-level targets for the context menu.
 *
 * `row` covers body cells and row-menu buttons. `column` covers column header
 * cells, including pinned column sections.
 */
export type ContextMenuTarget = 'row' | 'column';
```

---

### `ContextMenuOpenContextBase`

Shared context passed to dynamic menu resolvers and menu item actions.

```ts
/**
 * Shared context passed to dynamic menu resolvers and menu item actions.
 */
export type ContextMenuOpenContextBase = {
  /** The active menu target type. */
  target: ContextMenuTarget;
  /** Element that caused the menu to open. */
  triggerElement: HTMLElement;
  /** Mouse event that opened the menu, when opened from pointer interaction. */
  triggerEvent?: MouseEvent;
  /** Grid element that owns the plugin instance. */
  revogrid: HTMLRevoGridElement;
  /** Core plugin providers for data, dimensions, selection, columns, viewport, and plugins. */
  providers: PluginProviders;
};
```

---

### `ContextMenuColumnGroup` (Extended from `index.ts`)

```ts
export type ContextMenuColumnGroup = Group & {
  /** Grouping row depth in the header. */
  depth?: number;
};
```

---

### `ColumnContextMenuOpenContext` (Extended from `index.ts`)

Context available when a menu opens from a column header target.

```ts
/**
 * Context available when a menu opens from a column header target.
 */
export type ColumnContextMenuOpenContext = ContextMenuOpenContextBase & {
  target: 'column';
  /** Column model resolved from the header section and virtual column index. */
  column?: ColumnRegular;
  /** Column group model resolved when opening from a grouped header cell. */
  columnGroup?: ContextMenuColumnGroup;
  /** Physical column indexes covered by this menu target when it is a grouped header cell. */
  columnIndexes?: number[];
  /** Grouping row depth when opening from a grouped header cell. */
  columnGroupDepth?: number;
  /** Virtual column index inside the current column section. */
  columnIndex?: number;
  /** Column section that opened the menu: regular, left-pinned, or right-pinned. */
  columnType?: DimensionCols;
};
```

---

### `RowContextMenuOpenContext` (Extended from `index.ts`)

Context available when a menu opens from a row/body target.

```ts
/**
 * Context available when a menu opens from a row/body target.
 */
export type RowContextMenuOpenContext = ContextMenuOpenContextBase & {
  target: 'row';
  /**
   * Exact body cell that opened the menu. This remains distinct from the
   * current selection focus when a secondary click intentionally preserves an
   * existing range.
   */
  cell?: ContextMenuCellContext;
};
```

---

### `ContextMenuCellContext`

```ts
export type ContextMenuCellContext = Readonly<
  Omit<Pick<
    ColumnDataSchemaModel,
    | 'prop'
    | 'model'
    | 'column'
    | 'rowIndex'
    | 'colIndex'
    | 'colType'
    | 'type'
    | 'value'
  >, 'colType'> & {
    /** Data-column section or Core's dedicated row-header section. */
    colType: DimensionCols | 'rowHeaders';
  }
>;
```

---

### `ContextMenuOpenContext`

Union of all target-specific open contexts.

```ts
/**
 * Union of all target-specific open contexts.
 */
export type ContextMenuOpenContext = ColumnContextMenuOpenContext | RowContextMenuOpenContext;
```

---

### `ContextMenuConfigResolver`

Dynamic menu resolver.

Return `undefined` to keep the base config, return a partial config to override
settings/items for this invocation, or return `null` to suppress the menu.

**Example:**
```typescript
const columnContextMenu = {
  items: defaultItems,
  resolve(context) {
    if (context.target === 'column' && context.columnType === 'colPinStart') {
      return { items: pinnedColumnItems };
    }
  },
};
```

```ts
/**
 * Dynamic menu resolver.
 *
 * Return `undefined` to keep the base config, return a partial config to override
 * settings/items for this invocation, or return `null` to suppress the menu.
 *
 * @example
 * ```ts
 * const columnContextMenu = {
 *   items: defaultItems,
 *   resolve(context) {
 *     if (context.target === 'column' && context.columnType === 'colPinStart') {
 *       return { items: pinnedColumnItems };
 *     }
 *   },
 * };
 * ```
 */
export type ContextMenuConfigResolver = (
  context: ContextMenuOpenContext,
) => Partial<ContextMenuConfig> | null | undefined;
```

---

### `ContextMenuContribution`

Additive context-menu items owned by an independent plugin or feature.

Contributions are resolved alongside the active application config and are
composed before or after it without mutating that config.

```ts
/**
 * Additive context-menu items owned by an independent plugin or feature.
 *
 * Contributions are resolved alongside the active application config and are
 * composed before or after it without mutating that config.
 */
export type ContextMenuContribution = {
  /** Identifier unique within one `ContextMenuPlugin` instance. */
  readonly id: string;
  /** Ascending contribution order. Registration order breaks ties. */
  readonly order?: number;
  /**
   * Extra DOM selectors owned by this contribution. They are merged with the
   * active row or column menu config without changing application settings.
   */
  readonly targets?: Partial<Record<ContextMenuTarget, readonly string[]>>
    | (() => Partial<Record<ContextMenuTarget, readonly string[]>>);
  /**
   * Places the contribution before or after the resolved application items.
   * Defaults to `append` for backward compatibility.
   */
  readonly placement?: 'prepend' | 'append';
  /**
   * Optional application-item filter for contexts owned by this contribution.
   * Return `false` to suppress a base item without mutating its source config.
   */
  readonly filterBaseItem?: (
    item: ContextMenuItem,
    context: ContextMenuOpenContext,
  ) => boolean;
  /** Optional policy applied to the complete menu after all contributions compose. */
  readonly filterItem?: (
    item: ContextMenuItem,
    context: ContextMenuOpenContext,
  ) => boolean;
  /**
   * Accessible popup name used when the application config does not provide
   * one. A later, more specific contribution overrides an earlier label.
   */
  readonly ariaLabel?: string | ((context: ContextMenuOpenContext) => string | undefined);
  /** Resolves items for the current row or column menu invocation. */
  readonly resolve: (context: ContextMenuOpenContext) => ContextMenuItem[];
};
```

---

### `ContextMenuActionContext`

Context passed as the fifth argument to `ContextMenuItem.action`.

```ts
/**
 * Context passed as the fifth argument to `ContextMenuItem.action`.
 */
export type ContextMenuActionContext = {
  /** Grid element that owns the plugin instance. */
  revogrid: HTMLRevoGridElement,
  /** Core plugin providers for data, dimensions, selection, columns, viewport, and plugins. */
  providers: PluginProviders,
  /** Context captured when this menu was opened. */
  menu?: ContextMenuOpenContext,
};
```

---

### `ContextMenuItemStateResolver`

```ts
export type ContextMenuItemStateResolver = (
  item: ContextMenuItem,
  focused?: Cell | null,
  range?: RangeArea | null,
) => boolean;
```

---

### `ContextMenuChildrenResolver`

```ts
export type ContextMenuChildrenResolver = (
  focused?: Cell | null,
  range?: RangeArea | null,
  context?: ContextMenuActionContext,
) => ContextMenuItem[];
```

---

### `ContextMenuItem`

Single menu item definition.

```ts
/**
 * Single menu item definition.
 */
export type ContextMenuItem = {
  /** Stable identifier used by consumers and renderers. */
  id?: string;
  /**
   * Item semantics. `separator` items ignore action, icon, checked, and
   * children. `heading` items are non-interactive menu context. `control`
   * items host interactive form content supplied by `template` without menu
   * activation or automatic closing. Omitted kind renders a standard menu
   * item.
   */
  kind?: 'item' | 'checkbox' | 'radio' | 'separator' | 'heading' | 'control';
  /** Text or dynamic text rendered inside the item. */
  name: string | ((focused?: Cell | null, range?: RangeArea | null) => string);
  /** Secondary text rendered below a heading label. */
  subtitle?: string;
  /** Accessible label when visible text is insufficient. */
  ariaLabel?: string;
  /** Keyboard shortcut hint rendered at the trailing edge. */
  shortcut?: string;
  /** Inline SVG rendered inside the trailing shortcut keycap. */
  shortcutIcon?: string;
  /** Native tooltip text, useful for explaining a disabled action. */
  title?: string;
  /** CSS class added to the `<li>` item. */
  class?: string;
  /** Icon rendered before the item name. Accepts CSS classes or inline SVG markup. */
  icon?: string;
  /** Apply the shared destructive-action presentation. */
  danger?: boolean;
  /** CSS class added to the `<li>` item, optionally calculated from selection state. */
  rowClass?: string | ((item: ContextMenuItem, focused?: Cell | null, range?: RangeArea | null) => string);
  /** Hide the item statically or from current selection state. */
  hidden?: boolean | ContextMenuItemStateResolver;
  /** Disable the item statically or from current selection state while keeping it visible. */
  disabled?: boolean | ContextMenuItemStateResolver;
  /** Checked state for checkbox and radio items. */
  checked?: boolean | ContextMenuItemStateResolver;
  /** Logical group for radio items. */
  radioGroup?: string;
  /** Nested submenu items or a resolver evaluated for the current menu context. */
  children?: ContextMenuItem[] | ContextMenuChildrenResolver;
  /** Called when the item is selected. */
  action?: (event: MouseEvent, focused?: Cell | null, range?: RangeArea | null, close?: () => void, context?: ContextMenuActionContext) => void;
  /** Keep the popup open after this item action runs. */
  keepOpen?: boolean;
  /** Custom item renderer. */
  template?: (h: HyperFunc<VNode>, item: ContextMenuItem, focused?: Cell | null, range?: RangeArea | null, close?: () => void) => any;
};
```

---

### `ContextMenuConfig`

Context menu configuration.

Use `rowContextMenu` for row/body targets and `columnContextMenu` for header
targets. `resolve` can refine either menu at open time for column sections,
individual columns, or any other target-specific condition.

```ts
/**
 * Context menu configuration.
 *
 * Use `rowContextMenu` for row/body targets and `columnContextMenu` for header
 * targets. `resolve` can refine either menu at open time for column sections,
 * individual columns, or any other target-specific condition.
 */
export type ContextMenuConfig = {
  /** Items rendered in the popup. */
  items: ContextMenuItem[];
  /** Accessible name for the root menu. */
  ariaLabel?: string;
  /** Open the menu on the native `contextmenu` event. Defaults to `true`. */
  rightClick?: boolean;
  /** Open the menu on left click. Defaults to `false`. */
  leftClick?: boolean;
  /** CSS selectors that can trigger this menu. */
  targetSelectors?: string[];
  /** Position the popup relative to the target element instead of pointer coordinates. */
  anchorToTarget?: boolean;
  /**
   * Resolves a menu override for the current target before the menu opens.
   * Return `null` to suppress the menu for that target, `undefined` to use the base config,
   * or a partial config to override items/settings for this invocation.
   */
  resolve?: ContextMenuConfigResolver;
};
```

---

### `resolveColumnGroupContext`

Resolve a rendered grouped-header cell to its source-backed group model.

```ts
export function resolveColumnGroupContext({
  columnType,
  header,
  headerCell,
  providers,
}: ResolveColumnGroupContextOptions): ColumnGroupContext;
```

---

### `HeaderWithColumnGroups` (Extended from `context-menu.column-group-target.ts`)

```ts
export type HeaderWithColumnGroups = HTMLElement & {
  type?: DimensionCols | 'rowHeaders';
  colData?: ReturnType<PluginProviders['column']['getColumns']>;
  groups?: Record<number, ContextMenuColumnGroup[]>;
};
```

---

### `resolveColumnContext`

Resolve ordinary and grouped column-header targets into one public context.

```ts
export function resolveColumnContext({
  event,
  providers,
  revogrid,
  target,
}: ResolveColumnContextOptions): ColumnContextMenuOpenContext;
```

---

### `createContextMenuConfig`

Apply stable defaults to application and target-specific menu configs.

```ts
export function createContextMenuConfig(
  config: Partial<ContextMenuConfig> = {},
  targetSelectors: string[] = ['.rgCell'],
): ContextMenuConfig;
```

---

### `resolveContextMenuConfig`

Compose application items and contributions into the final visible menu.

```ts
export function resolveContextMenuConfig({
  config,
  context,
  contributions,
  providers,
  revogrid,
}: {
  config: ContextMenuConfig;
  context: ContextMenuOpenContext;
  contributions: ContextMenuContributionRegistry;
  providers: PluginProviders;
  revogrid: HTMLRevoGridElement;
}): ContextMenuConfig | undefined;
```

---

### `ContextMenuContributionRegistry`

Instance-owned contribution registration, ordering, and resolution.

```ts
class ContextMenuContributionRegistry {
  register(contribution: ContextMenuContribution): () => void;

  clear(): void;

  getTargetSelectors(target: ContextMenuTarget): string[];

  resolve(context: ContextMenuOpenContext): ResolvedContributionItems;
}
```

---

### `ContextMenuPointerIntent`

Keeps each open submenu stable while the pointer crosses its sibling rows.
It does no continuous pointer tracking: decisions happen only on item entry.

```ts
class ContextMenuPointerIntent {
  enter(
    item: HTMLElement,
    event: Pick<MouseEvent, 'clientX' | 'clientY'>,
    activate: () => void,
  ): void;

  enterSubmenu(item: HTMLElement): void;

  reset(): void;
}
```

---

### `showContextMenuPopup`

Opens a context-menu element in the browser top layer when available.
Browsers without the Popover API retain the existing display-based popup.

```ts
export function showContextMenuPopup(element: TopLayerPopupElement): ContextMenuPopupMode;
```

---

### `hideContextMenuPopup`

Hides a popup opened by `showContextMenuPopup`; safe to call repeatedly.

```ts
export function hideContextMenuPopup(
  element: TopLayerPopupElement,
  mode?: ContextMenuPopupMode,
): void;
```

---

### `calculateContextMenuPosition`

Resolves menu coordinates in the coordinate space of the supplied boundary.
The caller converts the result to grid-local coordinates for the fallback.

```ts
export function calculateContextMenuPosition({
  anchorRect,
  menuRect,
  boundary,
  anchorToTarget,
  pointer,
  inset = 0,
}: ContextMenuPositionOptions): { top: number; left: number };
```

---

### `ContextMenuPopupMode`

```ts
export type ContextMenuPopupMode = TopLayerPopupMode;
```

---

### `ContextMenuBoundary`

```ts
export type ContextMenuBoundary = Pick<
  DOMRect,
  'top' | 'right' | 'bottom' | 'left' | 'width' | 'height'
>;
```

---

### `ContextMenuPositionOptions`

```ts
export type ContextMenuPositionOptions = {
  anchorRect: Pick<DOMRect, 'top' | 'right' | 'bottom' | 'left' | 'width' | 'height'>;
  menuRect: Pick<DOMRect, 'width' | 'height'>;
  boundary: ContextMenuBoundary;
  anchorToTarget: boolean;
  pointer?: Pick<MouseEvent, 'clientX' | 'clientY'>;
  inset?: number;
};
```

---

### `shouldPreserveRowFocus`

Preserve an existing selected row range for a secondary-click menu.

```ts
export function shouldPreserveRowFocus({
  detail,
  selectedRange,
}: {
  detail?: BeforeSaveDataDetails;
  selectedRange?: RangeArea | null;
}): boolean;
```

---

### `shouldPreserveAppliedRange`

Preserve an existing selected range while Core applies pointer selection.

```ts
export function shouldPreserveAppliedRange({
  nextRange,
  selectedRange,
}: {
  nextRange?: RangeArea;
  selectedRange?: RangeArea | null;
}): boolean;
```

---

### `isSecondaryMouseEvent`

```ts
export function isSecondaryMouseEvent(event: unknown): event is MouseEvent;
```

---

### `getPendingPointerCell`

```ts
export function getPendingPointerCell(
  pending: PendingPointerCell | undefined,
  target: HTMLElement,
): ContextMenuCellContext | undefined;
```

---

### `resolveRowContext`

Resolve ordinary, row-header, grouping-row, and focused row contexts.

```ts
export function resolveRowContext({
  cell,
  event,
  pendingCell,
  providers,
  revogrid,
  target,
}: ResolveRowContextOptions): RowContextMenuOpenContext;
```

---

### `isResolvedGroupingRowContext`

```ts
export function isResolvedGroupingRowContext(
  context: ContextMenuOpenContext,
): boolean;
```

---

### `toContextMenuCell`

```ts
export function toContextMenuCell(
  detail: Pick<
    BeforeSaveDataDetails,
    | 'prop'
    | 'model'
    | 'column'
    | 'rowIndex'
    | 'colIndex'
    | 'colType'
    | 'type'
    | 'value'
  >,
): ContextMenuCellContext;
```

---

### `resolveFocusedCell`

Resolve the currently focused body cell when Core emits no pointer payload.

```ts
export function resolveFocusedCell(
  providers: PluginProviders,
): ContextMenuCellContext | undefined;
```

---

### `PendingPointerCell`

```ts
export type PendingPointerCell = {
  cell: ContextMenuCellContext;
  target: EventTarget | null;
};
```

---

### `resolveGroupingRowCellContext`

Resolves Core's full-width synthetic group renderer to a semantic cell-like
context. Group rows are intentionally not focusable and therefore do not
emit the normal `beforecellfocus` payload used by ordinary body cells.

```ts
export function resolveGroupingRowCellContext(
  target: HTMLElement,
  providers: PluginProviders,
): ContextMenuCellContext | undefined;
```

---

### `resolveRowHeaderCellContext`

Resolves a rendered row-header cell when Core does not emit the ordinary
`beforecellfocus` payload. Row headers share the row data store but live in
their own column viewport, so their context must be reconstructed from the
rendered virtual row index.

```ts
export function resolveRowHeaderCellContext(
  target: HTMLElement,
  providers: PluginProviders,
): ContextMenuCellContext | undefined;
```

---

### `isRowHeaderCellTarget`

Whether a target belongs to Core's dedicated row-header viewport.

```ts
export function isRowHeaderCellTarget(target: HTMLElement): boolean;
```

---

### `DEFAULT_ROW_CONTEXT_MENU_TARGET_SELECTORS`

Core body targets that have row context-menu semantics.

```ts
DEFAULT_ROW_CONTEXT_MENU_TARGET_SELECTORS: string[];
```

---

### `resetContextMenuPointerIntent`

```ts
export function resetContextMenuPointerIntent(element?: HTMLElement): void;
```

---

### `resetContextMenuInteractionState`

```ts
export function resetContextMenuInteractionState(element?: HTMLElement): void;
```

---

### `renderMenuItemIcon`

```ts
export function renderMenuItemIcon(icon?: string);
```

---

### `normalizeContextMenuItems`

Resolves dynamic children and removes hidden, empty, leading, trailing, and
consecutive separators without mutating application-owned menu items.

```ts
export function normalizeContextMenuItems(
  items: ContextMenuItem[],
  focused?: Cell | null,
  range?: RangeArea | null,
  context?: ContextMenuActionContext,
): ContextMenuItem[];
```

---

### `calculateContextSubmenuPosition`

```ts
export function calculateContextSubmenuPosition(input: {
  itemRect: Pick<DOMRect, 'top' | 'right' | 'left'>;
  menuRect: Pick<DOMRect, 'width' | 'height'>;
  viewportWidth: number;
  viewportHeight: number;
  inset?: number;
});
```

---

### `handleContextMenuKeyDown`

```ts
export function handleContextMenuKeyDown(event: KeyboardEvent, close: () => void): void;
```

---

### `contextPopUp`

Extra VNode renderer registered by `ContextMenuPlugin`.

It reads the plugin instance state (`config`, `activeContext`, selection, and
close handler) and renders the current popup items. Menu item actions receive
the latest `activeContext`, which lets column menu actions know the exact
pinned section and column that opened the menu.

```ts
export function contextPopUp(this: {
  contextMenu?: HTMLElement | undefined;
  providers: PluginProviders;
  revogrid: HTMLRevoGridElement;
  config?: ContextMenuConfig;
  activeContext?: ContextMenuOpenContext;
  close: () => void;
});
```

---

### `POP_EL`

Registered extra VNode name for the context-menu popup.

The plugin uses this value to replace any previous popup renderer when the
plugin is re-created, preventing duplicate popup nodes.

```ts
POP_EL: string;
```

---

# Core

URL: https://pro.rv-grid.com/api/core/
Source: src/content/docs/api/core.md

### `CorePlugin`

```ts
class CorePlugin {
  /**
     * Observe attribute changes on the grid element
     * @param attrName - The attribute name to observe (supports both kebab-case and camelCase)
     * @param callback - Callback function when attribute changes
     *
     * Note:
     * This observer tracks DOM attribute mutations only (e.g. setAttribute).
     * It does not react to direct property assignments like grid.someProp = value.
     */
  observeAttribute(attrName: string, callback: (value: string | null) => void);

  /**
     * Stop observing an attribute
     * @param attrName - The attribute name to stop observing
     */
  unobserveAttribute(attrName: string);

  /**
     * Set the trimmed state for a column
     */
  setColumnTrimmed(trimmed: Record<string, Record<string, boolean | undefined>>, type: DimensionCols);

  /**
     * Destroy plugin and clean up all observers
     */
  destroy();
}
```

---

### `announcePopupOpen`

Announces a transient popup opening within one grid.
Popup owners subscribed to the same grid close unless they sent the event.

```ts
export function announcePopupOpen(
  revogrid: HTMLRevoGridElement,
  source: PopupOwner,
);
```

---

### `subscribeToPopupOpen`

Subscribes a transient popup owner to other popup openings in the same grid.

```ts
export function subscribeToPopupOpen(
  revogrid: HTMLRevoGridElement,
  source: PopupOwner,
  close: () => void,
);
```

---

### `PopupOwner`

```ts
export type PopupOwner = object;
```

---

### `findDataGridRowSourceOwner`

Returns the first active row-source owner other than the requesting plugin.

```ts
export function findDataGridRowSourceOwner(
  plugins: readonly unknown[],
  requester?: unknown,
): string | undefined;
```

---

### `DATA_GRID_ROW_SOURCE_OWNER`

Shared runtime contract for plugins that replace the primary `rgRow` source.

```ts
DATA_GRID_ROW_SOURCE_OWNER: typeof DATA_GRID_ROW_SOURCE_OWNER;
```

---

### `DataGridRowSourceOwner`

```ts
interface DataGridRowSourceOwner {
  readonly [DATA_GRID_ROW_SOURCE_OWNER]?: string
}
```

---

### `hasCellTemplateContent`

Returns whether a cell template produced visible content.

```ts
export function hasCellTemplateContent(rendered: unknown): boolean;
```

---

### `renderSyncedCellTemplate`

Render a cell template against a synthetic option row.

Object option metadata is merged into the row model, while the target prop is
always set from `option.value` so metadata cannot shadow the selected value.

```ts
export function renderSyncedCellTemplate<T = unknown>({
  createElement,
  cellTemplate,
  data,
  option,
  additionalData,
  fallback = option.label,
}: RenderSyncedCellTemplateOptions<T>);
```

---

### `CellTemplateSyncOption`

```ts
export type CellTemplateSyncOption<T = unknown> = {
  value: T;
  label: string;
  [key: string]: unknown;
};
```

---

### `RenderSyncedCellTemplateOptions`

```ts
export type RenderSyncedCellTemplateOptions<T = unknown> = {
  createElement: HyperFunc<VNode>;
  cellTemplate: NonNullable<ColumnRegular['cellTemplate']>;
  data: ColumnDataSchemaModel;
  option: CellTemplateSyncOption<T>;
  additionalData?: unknown;
  fallback?: unknown;
};
```

---

### `isEditableKeyboardTarget`

Returns whether a keyboard event originated from an editable control.

```ts
export function isEditableKeyboardTarget(
  event: KeyboardEvent,
  revogrid: HTMLRevoGridElement,
): boolean;
```

---

### `isGridKeyboardEvent`

Checks whether a document-level keyboard event belongs to this grid.

Core overlays listen on `document`, so a grid can receive a proxy
`beforekeydown` after an input or other control outside the grid has taken
focus. DOM ownership wins over stale provider focus in that case.

```ts
export function isGridKeyboardEvent(
  event: KeyboardEvent,
  revogrid: HTMLRevoGridElement,
  providers: Pick<PluginProviders, 'selection'>,
  options: GridKeyboardOwnershipOptions = {},
);
```

---

### `retainGridKeyboardOwnershipGuard`

Retains one shared `beforekeydown` ownership guard for a Pro-enabled grid.

Core emits this cancelable proxy from each document-listening overlay. The
proxy is the safe boundary to stop stale grid keyboard handling without
canceling the original event's native behavior in an outside control.

```ts
export function retainGridKeyboardOwnershipGuard(
  revogrid: HTMLRevoGridElement,
  providers: Pick<PluginProviders, 'selection'>,
): () => void;
```

---

### `GridKeyboardOwnershipOptions`

```ts
export type GridKeyboardOwnershipOptions = {
  /**
   * Allows detached or document-targeted integrations to invoke a shortcut
   * without a focused selection store. Events from an actual outside control
   * are always rejected.
   */
  allowDetached?: boolean;
};
```

---

### `calculateAnchoredPopoverPosition`

Pure positioning helper shared by portalled grid popups.

```ts
export function calculateAnchoredPopoverPosition(
  anchor: Pick<DOMRect, 'left' | 'right' | 'top' | 'bottom'>,
  popup: Pick<DOMRect, 'width' | 'height'>,
  viewport: { width: number; height: number },
  gap = 4,
  inset = 8,
): AnchoredPopoverPosition;
```

---

### `AnchoredPopoverPosition`

```ts
interface AnchoredPopoverPosition {
  left: number;
  top: number;
  placementX: 'left' | 'right';
  placementY: 'above' | 'below'
}
```

---

### `preactTemplateH`

Render a RevoGrid cell template inside a Preact-owned UI.

Cell templates receive RevoGrid's Stencil-style hyperscript function and may
use class maps such as `class: { badge: true, disabled: false }`. Preact does
not interpret that convention and would render the object as an invalid class
value. This adapter converts the class map to `class: 'badge'` before
delegating to Preact's `h`, allowing existing cell templates to be reused in
dropdowns, previews, and other Preact trees.

This is only a renderer compatibility bridge. It does not apply formatting
or couple its consumers to the Data Grid Formatting plugin.

```ts
export function preactTemplateH(
  tag: Parameters<typeof h>[0],
  properties?: Record<string, unknown> | null,
  ...children: ComponentChildren[]
);
```

---

### `showTopLayerPopup`

Opens an overlay in the browser top layer when supported.

```ts
export function showTopLayerPopup(
  element: TopLayerPopupElement,
  visibleDisplay = 'flex',
): TopLayerPopupMode;
```

---

### `hideTopLayerPopup`

Hides an overlay opened by `showTopLayerPopup`; safe to call repeatedly.

```ts
export function hideTopLayerPopup(
  element: TopLayerPopupElement,
  mode?: TopLayerPopupMode,
): void;
```

---

### `TopLayerPopupMode`

```ts
export type TopLayerPopupMode = 'popover' | 'fallback';
```

---

### `TopLayerPopupElement` (Extended from `top-layer-popup.ts`)

```ts
export type TopLayerPopupElement = HTMLElement & {
  showPopover?: () => void;
  hidePopover?: () => void;
};
```

---

# Data Grid Cell Inspector

URL: https://pro.rv-grid.com/api/data-grid-cell-inspector/
Source: src/content/docs/api/data-grid-cell-inspector.md

### `DataGridCellInspectorPlugin`

Read-only dialog for inspecting exact cell values and resolved column definitions.

#### Dependencies

- **Auto-installed** `DialogPlugin`: Uses the shared Pro dialog runtime for cell and column inspection.

```ts
class DataGridCellInspectorPlugin {
  open(options: DataGridCellInspectorOpenOptions<T>): void;

  openColumn(options: DataGridColumnInspectorOpenOptions<T>): void;

  close(): void;
}
```

---

### `createDataGridCellInspectorLocale`

```ts
export function createDataGridCellInspectorLocale(
  overrides?: Partial<DataGridCellInspectorLocaleText>,
): DataGridCellInspectorLocaleText;
```

---

### `DATA_GRID_CELL_INSPECTOR_LOCALE`

```ts
DATA_GRID_CELL_INSPECTOR_LOCALE: {
  title: string;
  close: string;
  closeButton: string;
  column: string;
  property: string;
  rowDimension: string;
  sourceIndex: string;
  valueType: string;
  rawValue: string;
  rowData: string;
  unavailable: string;
  columnTitle: string;
  closeColumn: string;
  columnDimension: string;
  columnIndex: string;
  physicalIndex: string;
  columnType: string;
  readonlyMode: string;
  sortOrder: string;
  filter: string;
  pin: string;
  width: string;
  minimumWidth: string;
  maximumWidth: string;
  columnData: string;
  enabled: string;
  disabled: string;
  dynamic: string;
  automatic: string;
  unpinned: string;
  pinStart: string;
  pinEnd: string;
};
```

---

### `getDataGridCellValueType`

Human-readable value type that preserves useful JavaScript distinctions.

```ts
export function getDataGridCellValueType(value: unknown): string;
```

---

### `serializeDataGridCellInspectorValue`

JSON-like inspection output that never throws for common non-JSON values or
circular row models. It is display text only and is not a round-trip format.

```ts
export function serializeDataGridCellInspectorValue(
  value: unknown,
  options: DataGridCellInspectorSerializationOptions = {},
): string;
```

---

### `limitDataGridCellInspectorOutput`

```ts
export function limitDataGridCellInspectorOutput(
  value: string,
  options: DataGridCellInspectorSerializationOptions = {},
): string;
```

---

### `DataGridCellInspectorContext`

```ts
interface DataGridCellInspectorContext {
  readonly column: ColumnRegular<ColumnProp, T>;
  readonly model: T;
  readonly value: unknown;
  readonly rowType: DimensionRows;
  /** Visible row index at invocation time. */
    readonly rowIndex: number;
  /** Index in the authored source, when it can be resolved. */
    readonly sourceIndex?: number
}
```

---

### `DataGridColumnInspectorContext`

```ts
interface DataGridColumnInspectorContext {
  readonly column: ColumnRegular<ColumnProp, T>;
  readonly columnType: DimensionCols;
  /** Visible column index inside its pinned or unpinned section. */
    readonly columnIndex: number;
  /** Index in the resolved column store before visibility projection. */
    readonly physicalIndex?: number;
  /** Rendered width captured when the context menu opened. */
    readonly width?: number
}
```

---

### `DataGridCellInspectorLocaleText`

```ts
interface DataGridCellInspectorLocaleText {
  readonly title: string;
  readonly close: string;
  readonly closeButton: string;
  readonly column: string;
  readonly property: string;
  readonly rowDimension: string;
  readonly sourceIndex: string;
  readonly valueType: string;
  readonly rawValue: string;
  readonly rowData: string;
  readonly unavailable: string;
  readonly columnTitle: string;
  readonly closeColumn: string;
  readonly columnDimension: string;
  readonly columnIndex: string;
  readonly physicalIndex: string;
  readonly columnType: string;
  readonly readonlyMode: string;
  readonly sortOrder: string;
  readonly filter: string;
  readonly pin: string;
  readonly width: string;
  readonly minimumWidth: string;
  readonly maximumWidth: string;
  readonly columnData: string;
  readonly enabled: string;
  readonly disabled: string;
  readonly dynamic: string;
  readonly automatic: string;
  readonly unpinned: string;
  readonly pinStart: string;
  readonly pinEnd: string
}
```

---

### `DataGridCellInspectorSerializationOptions`

```ts
interface DataGridCellInspectorSerializationOptions {
  readonly maxDepth?: number;
  readonly maxEntries?: number;
  readonly maxStringLength?: number;
  readonly maxOutputLength?: number
}
```

---

### `DataGridCellInspectorSerializeContext`

```ts
export type DataGridCellInspectorSerializeContext<T extends DataType = DataType> =
  | {
      readonly kind: 'cell' | 'row';
      readonly context: DataGridCellInspectorContext<T>;
    }
  | {
      readonly kind: 'column';
      readonly context: DataGridColumnInspectorContext<T>;
    };
```

---

### `DataGridCellInspectorConfig`

```ts
interface DataGridCellInspectorConfig {
  /** Includes enumerable row fields. Off by default to avoid exposing hidden model data. */
    readonly includeRowData?: boolean;
  /** Includes the resolved column definition. Off by default because it can contain application metadata. */
    readonly includeColumnData?: boolean;
  readonly localeText?: Partial<DataGridCellInspectorLocaleText>;
  readonly serialization?: DataGridCellInspectorSerializationOptions;
  /** Application-owned redaction hook applied before bounded serialization. */
    readonly redact?: (
      value: unknown,
      context: DataGridCellInspectorSerializeContext<T>,
    ) => unknown
}
```

---

### `DataGridCellInspectorOpenOptions` (Extended from `index.ts`)

```ts
interface DataGridCellInspectorOpenOptions {
  readonly context: DataGridCellInspectorContext<T>;
  readonly returnFocus?: HTMLElement
}
```

---

### `DataGridColumnInspectorOpenOptions` (Extended from `index.ts`)

```ts
interface DataGridColumnInspectorOpenOptions {
  readonly context: DataGridColumnInspectorContext<T>;
  readonly returnFocus?: HTMLElement
}
```

---

### `createDataGridCellInspectorView`

```ts
export function createDataGridCellInspectorView<T extends DataType = DataType>(
  document: Document,
  options: DataGridCellInspectorOpenOptions<T>,
  locale: DataGridCellInspectorLocaleText,
): HTMLElement;
```

---

### `createDataGridColumnInspectorView`

```ts
export function createDataGridColumnInspectorView<T extends DataType = DataType>(
  document: Document,
  options: DataGridColumnInspectorOpenOptions<T>,
  locale: DataGridCellInspectorLocaleText,
): HTMLElement;
```

---

### `createInspectorContent`

```ts
export function createInspectorContent(document: Document): HTMLElement;
```

---

### `createInspectorDetails`

```ts
export function createInspectorDetails(document: Document): HTMLDListElement;
```

---

### `appendInspectorDetail`

```ts
export function appendInspectorDetail(
  parent: HTMLDListElement,
  label: string,
  value: string,
): void;
```

---

### `createInspectorValueSection`

```ts
export function createInspectorValueSection(
  document: Document,
  label: string,
  value: unknown,
  serialization?: DataGridCellInspectorSerializationOptions,
): HTMLElement;
```

---

### `displayInspectorColumnName`

```ts
export function displayInspectorColumnName(column: { name?: unknown; prop: PropertyKey }): string;
```

---

### `displayInspectorProperty`

```ts
export function displayInspectorProperty(prop: PropertyKey): string;
```

---

### `readInspectorDataProperty`

```ts
export function readInspectorDataProperty(
  target: object,
  property: PropertyKey,
): unknown;
```

---

# Data Grid Context Menu

URL: https://pro.rv-grid.com/api/data-grid-context-menu/
Source: src/content/docs/api/data-grid-context-menu.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  dataGridContextMenu?: false | DataGridContextMenuConfig;
  'data-grid-context-menu'?: false | DataGridContextMenuConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [DATA_GRID_CONTEXT_MENU_COMMAND_EVENT]: DataGridContextMenuCommandDetail;
  [DATA_GRID_CONTEXT_MENU_ERROR_EVENT]: DataGridContextMenuErrorDetail
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /** Legacy configuration path. Prefer `grid.dataGridContextMenu`. */
      dataGridContextMenu?: false | DataGridContextMenuConfig
}
```

## Plugin API

### `DATA_GRID_CONTEXT_MENU_SURFACE_ITEM_IDS`

```ts
DATA_GRID_CONTEXT_MENU_SURFACE_ITEM_IDS: { readonly cell: readonly DataGridContextMenuItemId[]; readonly rowHeader: readonly DataGridContextMenuItemId[]; readonly rowGroup: readonly DataGridContextMenuItemId[]; readonly columnHeader: readonly DataGridContextMenuItemId[]; readonly columnGroupHeader: readonly DataGridContextMenuItemId[]; };
```

---

### `DataGridContextMenuPlugin`

Task-oriented context-menu defaults for cells, rows, row groups, columns,
and column groups. The preset is opt-in: add this plugin to `grid.plugins`.
It composes before application and other plugin menu contributions.

#### Dependencies

- **Auto-installed** `ContextMenuPlugin`: Uses ContextMenuPlugin for popup composition and interaction.
- **Auto-installed** `ColumnDialogPlugin`: Uses ColumnDialogPlugin and its ColumnHidePlugin dependency for column management.
- **Auto-installed** `DataGridFormattingPlugin`: Uses DataGridFormattingPlugin for spreadsheet-style formatting.
- **Auto-installed** `DataGridCellInspectorPlugin`: Uses DataGridCellInspectorPlugin for read-only cell and column inspection.
- **Config integration** `grid.dataGridContextMenu`, `additionalData.dataGridContextMenu`: Reads the direct dataGridContextMenu property and legacy additionalData fallback.

```ts
class DataGridContextMenuPlugin {
  /** Resolve the semantic context and current configured items without opening a popup. */
  getItems(menu: ContextMenuOpenContext);

  /** Resolve the task-oriented semantic surface for a low-level menu context. */
  getContext(menu: ContextMenuOpenContext): DataGridContextMenuContext<T>;

  /** Register a semantic menu transformation owned by another plugin. */
  registerContribution(contribution: DataGridContextMenuContribution<T>): () => void;

  destroy(): void;
}
```

---

### `DataGridContextMenuContribution`

A semantic transformation of the generated data-grid menu.

Contributions run in ascending `order` before the application's
`dataGridContextMenu.getItems` callback. Registration order breaks ties.

```ts
interface DataGridContextMenuContribution {
  /** Identifier unique within one DataGridContextMenuPlugin instance. */
    readonly id: string;
  /** Ascending contribution order. */
    readonly order?: number;
  /** Optional selectors to merge into row or column menu target detection. */
    readonly targets?: DataGridContextMenuContributionTargets
      | (() => DataGridContextMenuContributionTargets);
  /** Transforms the generated defaults for the active semantic surface. */
    readonly getItems: (
      context: DataGridContextMenuContext<T>,
      defaultItems: readonly ContextMenuItem[],
    ) => readonly ContextMenuItem[];
  /** Suppresses the entire menu, including host/application items, when true. */
    readonly suppress?: (context: DataGridContextMenuContext<T>) => boolean
}
```

---

### `DataGridContextMenuContributionTargets`

Selectors contributed for row and column menu target detection.

```ts
/** Selectors contributed for row and column menu target detection. */
export type DataGridContextMenuContributionTargets = Partial<Record<
  ContextMenuTarget,
  readonly string[]
>>;
```

---

### `DataGridContextMenuSurface`

```ts
export type DataGridContextMenuSurface =
  | 'cell'
  | 'rowHeader'
  | 'rowGroup'
  | 'columnHeader'
  | 'columnGroupHeader';
```

---

### `DataGridContextMenuItemId`

```ts
export type DataGridContextMenuItemId =
  | 'menu.copy'
  | 'menu.rows'
  | 'menu.filter'
  | 'menu.export'
  | 'menu.sort'
  | 'menu.grouping'
  | 'menu.pin'
  | 'menu.move'
  | 'menu.size'
  | 'menu.schema'
  | 'menu.format'
  | 'menu.tree'
  | 'cell.edit'
  | 'cell.inspect'
  | 'cell.clear'
  | 'clipboard.cut'
  | 'clipboard.copy'
  | 'clipboard.copyCell'
  | 'clipboard.copyWithHeaders'
  | 'clipboard.paste'
  | 'row.copy'
  | 'row.copyWithHeaders'
  | 'row.clear'
  | 'row.insertAbove'
  | 'row.insertBelow'
  | 'row.duplicate'
  | 'row.delete'
  | 'row.pinTop'
  | 'row.pinBottom'
  | 'row.unpin'
  | 'tree.toggle'
  | 'tree.expandAll'
  | 'tree.collapseAll'
  | 'tree.addChild'
  | 'tree.moveUp'
  | 'tree.moveDown'
  | 'tree.indent'
  | 'tree.outdent'
  | 'rowGroup.toggle'
  | 'rowGroup.expandAll'
  | 'rowGroup.collapseAll'
  | 'rowGroup.selectDescendants'
  | 'rowGroup.copy'
  | 'rowGroup.copyWithHeaders'
  | 'rowGroup.exportCsv'
  | 'rowGroup.removeField'
  | 'rowGroup.clearGrouping'
  | 'filter.keepOnly'
  | 'filter.exclude'
  | 'filter.open'
  | 'filter.clear'
  | 'column.copy'
  | 'column.copyWithHeader'
  | 'column.inspect'
  | 'column.sortAscending'
  | 'column.sortDescending'
  | 'column.clearSort'
  | 'column.filterOpen'
  | 'column.filterClear'
  | 'column.groupBy'
  | 'column.ungroup'
  | 'column.pinLeft'
  | 'column.pinRight'
  | 'column.unpin'
  | 'column.moveLeft'
  | 'column.moveRight'
  | 'column.moveStart'
  | 'column.moveEnd'
  | 'column.autoSize'
  | 'column.autoSizeAll'
  | 'column.resetWidth'
  | 'column.hide'
  | 'column.manage'
  | 'column.insertLeft'
  | 'column.insertRight'
  | 'column.duplicate'
  | 'column.delete'
  | 'column.exportCsv'
  | 'columnGroup.toggle'
  | 'columnGroup.autoSize'
  | 'columnGroup.hide'
  | 'format.automatic'
  | 'format.number'
  | 'format.currency'
  | 'format.accounting'
  | 'format.percent'
  | 'format.scientific'
  | 'format.date'
  | 'format.datetime'
  | 'format.time'
  | 'format.more'
  | 'format.clear'
  | 'export.selectionCsv'
  | 'export.rowsCsv'
  | 'export.allCsv'
  | 'export.allExcel';
```

---

### `DataGridContextMenuCommandId`

Stable ids for actionable built-in leaves. Submenu containers never execute.

```ts
/** Stable ids for actionable built-in leaves. Submenu containers never execute. */
export type DataGridContextMenuCommandId = Exclude<
  DataGridContextMenuItemId,
  `menu.${string}`
>;
```

---

### `HistoryTransactionCommandId`

Commands that can group multiple value/metadata edits into one history unit.

```ts
/** Commands that can group multiple value/metadata edits into one history unit. */
export type HistoryTransactionCommandId = DataGridContextMenuCommandId | 'format.autofill';
```

---

### `DataGridContextMenuRow`

```ts
interface DataGridContextMenuRow {
  readonly type: DimensionRows;
  /** Visible viewport index. Undefined when a selected source row is filtered or collapsed. */
    readonly virtualIndex?: number;
  readonly physicalIndex: number;
  /** Index in the authored source before grouping rows were projected. */
    readonly sourceIndex: number;
  readonly model: T
}
```

---

### `DataGridContextMenuContext`

```ts
interface DataGridContextMenuContext {
  readonly surface: DataGridContextMenuSurface;
  readonly menu: ContextMenuOpenContext;
  readonly rows: readonly DataGridContextMenuRow<T>[];
  readonly range?: RangeArea;
  readonly rowType?: DimensionRows;
  readonly columnType?: DimensionCols;
  /** Invocation-time index in the resolved column store before visibility projection. */
    readonly columnPhysicalIndex?: number;
  /** Invocation-time rendered width from the active column dimension. */
    readonly columnSize?: number;
  readonly column?: ColumnRegular;
  readonly columns: readonly ColumnRegular[];
  readonly columnGroup?: ContextMenuColumnGroup;
  /** Grid-level readonly state. Per-cell readonly is resolved from column schema. */
    readonly readonly: boolean
}
```

---

### `DataGridContextMenuStateResolver`

```ts
export type DataGridContextMenuStateResolver<T extends DataType = DataType> =
  | boolean
  | ((context: DataGridContextMenuContext<T>) => boolean);
```

---

### `DataGridContextMenuItemsFactory`

```ts
export type DataGridContextMenuItemsFactory<T extends DataType = DataType> = (
  context: DataGridContextMenuContext<T>,
) => readonly ContextMenuItem[];
```

---

### `DataGridContextMenuItemsResolver`

```ts
export type DataGridContextMenuItemsResolver<T extends DataType = DataType> = (
  context: DataGridContextMenuContext<T>,
  defaultItems: readonly ContextMenuItem[],
) => readonly ContextMenuItem[];
```

---

### `DataGridContextMenuCommandHandler`

```ts
export type DataGridContextMenuCommandHandler<T extends DataType = DataType> = (
  context: DataGridContextMenuContext<T>,
) => void | Promise<void>;
```

---

### `DataGridCreateRowAction`

```ts
export type DataGridCreateRowAction =
  | 'insertAbove'
  | 'insertBelow'
  | 'duplicate';
```

---

### `DataGridCreateRowContext`

```ts
interface DataGridCreateRowContext {
  readonly action: DataGridCreateRowAction;
  /** The authored row being duplicated. Omitted for insert actions. */
    readonly sourceRow?: T;
  readonly context: DataGridContextMenuContext<T>
}
```

---

### `DataGridTreeCreateRowContext` (Extended from `index.ts`)

```ts
interface DataGridTreeCreateRowContext {
  readonly context: DataGridContextMenuContext<T>
}
```

---

### `DataGridTreeContextMenuConfig`

```ts
interface DataGridTreeContextMenuConfig {
  /**
     * Creates rows for hierarchy-aware insertion and duplication. The active
     * TreeDataPlugin validates the returned id and owns parent remapping.
     */
    createRow(
      context: DataGridTreeCreateRowContext<T>,
    ): T | null | undefined | Promise<T | null | undefined>
}
```

---

### `DataGridColumnSchemaAction`

```ts
export type DataGridColumnSchemaAction =
  | 'insertLeft'
  | 'insertRight'
  | 'duplicate';
```

---

### `DataGridColumnSchemaContext`

```ts
interface DataGridColumnSchemaContext {
  readonly action: DataGridColumnSchemaAction;
  readonly sourceColumn: ColumnRegular;
  readonly context: DataGridContextMenuContext<T>
}
```

---

### `DataGridColumnSchemaConfig`

```ts
interface DataGridColumnSchemaConfig {
  /** Must return a column with an application-owned, unique `prop`. */
    createColumn(
      context: DataGridColumnSchemaContext<T>,
    ): ColumnRegular | null | undefined
}
```

---

### `DataGridContextMenuLocaleText`

```ts
interface DataGridContextMenuLocaleText {
  readonly ariaLabel: string;
  readonly unavailable: string;
  readonly labels: Record<DataGridContextMenuItemId, string>;
  readonly states: {
      readonly rowGroupExpand: string;
      readonly rowGroupCollapse: string;
      readonly rowGroupDeselectDescendants: string;
      readonly columnGroupExpand: string;
      readonly columnGroupCollapse: string;
      readonly treeExpand: string;
      readonly treeCollapse: string;
      readonly treeInsertAbove: string;
      readonly treeInsertBelow: string;
      readonly treeDuplicate: string;
      readonly treeDelete: string;
    }
}
```

---

### `DataGridContextMenuConfig`

```ts
interface DataGridContextMenuConfig {
  /** Enable or disable complete semantic surfaces. */
    readonly areas?: Partial<Record<DataGridContextMenuSurface, boolean>>;
  /** Keep application-provided row/column context-menu items. Defaults to true. */
    readonly includeHostItems?: boolean;
  /** Hide individual generated items by stable id. */
    readonly hiddenItems?: Partial<Record<
      DataGridContextMenuItemId,
      DataGridContextMenuStateResolver<T>
    >>;
  /** Disable individual generated items by stable id. */
    readonly disabledItems?: Partial<Record<
      DataGridContextMenuItemId,
      DataGridContextMenuStateResolver<T>
    >>;
  /** Extra items appended after the resolved generated defaults. */
    readonly items?: readonly ContextMenuItem[] | DataGridContextMenuItemsFactory<T>;
  /** Replace or transform the generated defaults for the current surface. */
    readonly getItems?: DataGridContextMenuItemsResolver<T>;
  /** Label and accessible-name overrides. */
    readonly localeText?: Partial<Omit<DataGridContextMenuLocaleText, 'labels' | 'states'>> & {
      readonly labels?: Partial<Record<DataGridContextMenuItemId, string>>;
      readonly states?: Partial<DataGridContextMenuLocaleText['states']>;
    };
  /** Defaults to hiding capability-dependent items. */
    readonly unavailableItems?: 'hide' | 'disable';
  /** Replace the default implementation for individual built-in commands. */
    readonly commandHandlers?: Partial<Record<
      DataGridContextMenuCommandId,
      DataGridContextMenuCommandHandler<T>
    >>;
  /** Creates blank inserted rows or application-defined duplicates. */
    readonly createRow?: (context: DataGridCreateRowContext<T>) => T;
  /** Tree-aware row creation used by TreeDataPlugin-backed menu commands. */
    readonly tree?: false | DataGridTreeContextMenuConfig<T>;
  /** Enables local row pin/unpin commands. Defaults to false. */
    readonly rowPinning?: boolean;
  /** Enables application-owned column schema commands. Defaults to false. */
    readonly columnSchema?: false | DataGridColumnSchemaConfig<T>;
  /** Spreadsheet-style cell and column formatting. Set to false to hide it. */
    readonly formatting?: false | DataGridFormattingConfig<T>;
  /** Read-only cell and column inspection. Full row and column data are opt-in. */
    readonly inspection?: false | DataGridCellInspectorConfig<T>
}
```

---

### `DataGridContextMenuColumnProp`

```ts
export type DataGridContextMenuColumnProp = ColumnProp;
```

---

### `DataGridContextMenuCommandDetail`

```ts
interface DataGridContextMenuCommandDetail {
  readonly id: DataGridContextMenuCommandId;
  readonly context: DataGridContextMenuContext<T>
}
```

---

### `DataGridContextMenuErrorDetail` (Extended from `index.ts`)

```ts
interface DataGridContextMenuErrorDetail {
  readonly error: unknown
}
```

---

### `DATA_GRID_CONTEXT_MENU_COMMAND_EVENT`

```ts
DATA_GRID_CONTEXT_MENU_COMMAND_EVENT: string;
```

---

### `DATA_GRID_CONTEXT_MENU_ERROR_EVENT`

```ts
DATA_GRID_CONTEXT_MENU_ERROR_EVENT: string;
```

---

### `ownsDataGridProjectedRows`

```ts
export function ownsDataGridProjectedRows(
  plugin: unknown,
): plugin is DataGridContextMenuExternalRowOwner;
```

---

### `DATA_GRID_CONTEXT_MENU_EXTERNAL_ROW_OWNER`

Cross-package marker for plugins that own a projected row lifecycle.

The universal menu may still contribute copy, export, and view commands, but
local cell/row mutations require an application command handler while a
marked owner is active.

```ts
DATA_GRID_CONTEXT_MENU_EXTERNAL_ROW_OWNER: typeof DATA_GRID_CONTEXT_MENU_EXTERNAL_ROW_OWNER;
```

---

### `DataGridContextMenuExternalRowOwner`

```ts
interface DataGridContextMenuExternalRowOwner {
  readonly [DATA_GRID_CONTEXT_MENU_EXTERNAL_ROW_OWNER]: true
}
```

---

### `createDataGridContextMenuLocale`

```ts
export function createDataGridContextMenuLocale(
  config?: DataGridContextMenuConfig['localeText'],
): DataGridContextMenuLocaleText;
```

---

### `DATA_GRID_CONTEXT_MENU_LOCALE`

```ts
DATA_GRID_CONTEXT_MENU_LOCALE: {
  ariaLabel: string;
  unavailable: string;
  labels: { 'menu.copy': string; 'menu.rows': string; 'menu.filter': string; 'menu.export': string; 'menu.sort': string; 'menu.grouping': string; 'menu.pin': string; 'menu.move': string; 'menu.size': string; 'menu.schema': string; 'menu.format': string; 'menu.tree': string; 'cell.edit': string; 'cell.inspect': string; 'cell.clear': string; 'clipboard.cut': string; 'clipboard.copy': string; 'clipboard.copyCell': string; 'clipboard.copyWithHeaders': string; 'clipboard.paste': string; 'row.copy': string; 'row.copyWithHeaders': string; 'row.clear': string; 'row.insertAbove': string; 'row.insertBelow': string; 'row.duplicate': string; 'row.delete': string; 'row.pinTop': string; 'row.pinBottom': string; 'row.unpin': string; 'tree.toggle': string; 'tree.expandAll': string; 'tree.collapseAll': string; 'tree.addChild': string; 'tree.moveUp': string; 'tree.moveDown': string; 'tree.indent': string; 'tree.outdent': string; 'rowGroup.toggle': string; 'rowGroup.expandAll': string; 'rowGroup.collapseAll': string; 'rowGroup.selectDescendants': string; 'rowGroup.copy': string; 'rowGroup.copyWithHeaders': string; 'rowGroup.exportCsv': string; 'rowGroup.removeField': string; 'rowGroup.clearGrouping': string; 'filter.keepOnly': string; 'filter.exclude': string; 'filter.open': string; 'filter.clear': string; 'column.copy': string; 'column.copyWithHeader': string; 'column.inspect': string; 'column.sortAscending': string; 'column.sortDescending': string; 'column.clearSort': string; 'column.filterOpen': string; 'column.filterClear': string; 'column.groupBy': string; 'column.ungroup': string; 'column.pinLeft': string; 'column.pinRight': string; 'column.unpin': string; 'column.moveLeft': string; 'column.moveRight': string; 'column.moveStart': string; 'column.moveEnd': string; 'column.autoSize': string; 'column.autoSizeAll': string; 'column.resetWidth': string; 'column.hide': string; 'column.manage': string; 'column.insertLeft': string; 'column.insertRight': string; 'column.duplicate': string; 'column.delete': string; 'column.exportCsv': string; 'columnGroup.toggle': string; 'columnGroup.autoSize': string; 'columnGroup.hide': string; 'format.automatic': string; 'format.number': string; 'format.currency': string; 'format.accounting': string; 'format.percent': string; 'format.scientific': string; 'format.date': string; 'format.datetime': string; 'format.time': string; 'format.more': string; 'format.clear': string; 'export.selectionCsv': string; 'export.rowsCsv': string; 'export.allCsv': string; 'export.allExcel': string; };
  states: { rowGroupExpand: string; rowGroupCollapse: string; rowGroupDeselectDescendants: string; columnGroupExpand: string; columnGroupCollapse: string; treeExpand: string; treeCollapse: string; treeInsertAbove: string; treeInsertBelow: string; treeDuplicate: string; treeDelete: string; };
};
```

---

### `resolveDataGridContextMenuContext`

Compose independently resolved surface, selection, row, and column targets.

```ts
export function resolveDataGridContextMenuContext(
  menu: ContextMenuOpenContext,
): DataGridContextMenuContext;
```

---

### `isDataGridContextMenuGroupExpanded`

```ts
export function isDataGridContextMenuGroupExpanded(
  context: DataGridContextMenuContext,
): boolean;
```

---

### `getVisibleColumns`

```ts
export function getVisibleColumns(providers: PluginProviders): ColumnRegular[];
```

---

### `resolveDataGridContextMenuSurface`

```ts
export function resolveDataGridContextMenuSurface(
  menu: ContextMenuOpenContext,
): DataGridContextMenuSurface;
```

---

### `beginContextMenuHistoryTransaction`

Begin one built-in context-menu mutation as an atomic history transaction.

```ts
export function beginContextMenuHistoryTransaction<T extends DataType>(
  runtime: DataGridContextMenuCommandRuntime<T>,
  commandId: DataGridContextMenuCommandId,
  context?: DataGridContextMenuContext<T>,
): { complete(): void } | undefined;
```

---

### `createHistoryTransactionId`

**@internal** Allocate an id shared by every producer of an atomic history transaction.

```ts
export function createHistoryTransactionId(): number;
```

---

### `dispatchHistoryTransaction`

**@internal** Dispatch an atomic history transaction boundary.

```ts
export function dispatchHistoryTransaction(
  revogrid: HTMLRevoGridElement,
  detail: ContextMenuHistoryTransactionDetail,
): void;
```

---

### `CONTEXT_MENU_HISTORY_TRANSACTION_EVENT`

```ts
CONTEXT_MENU_HISTORY_TRANSACTION_EVENT: string;
```

---

### `ContextMenuRowPartitionMoveOperation`

```ts
interface ContextMenuRowPartitionMoveOperation {
  readonly kind: 'row-partition-move';
  readonly from: DimensionRows;
  readonly to: DimensionRows
}
```

---

### `ContextMenuHistoryTransactionDetail`

```ts
interface ContextMenuHistoryTransactionDetail {
  readonly phase: 'start' | 'complete';
  readonly transactionId: number;
  readonly commandId: HistoryTransactionCommandId;
  /** Structural axis whose coordinate-owned plugin state must join this transaction. */
    readonly formattingAxis?: 'rows' | 'columns';
  readonly operation?: ContextMenuRowPartitionMoveOperation;
  readonly structure?: ContextMenuStructuralHistoryChange
}
```

---

### `DataGridContextMenuCommands`

Owns the command lifecycle only. Individual command behavior and capability
checks live in the focused modules under `commands/`.

```ts
class DataGridContextMenuCommands {
  isAvailable(
    id: DataGridContextMenuCommandId,
    context: DataGridContextMenuContext<T>,
  ): boolean;

  getAvailability(
    id: DataGridContextMenuCommandId,
    context: DataGridContextMenuContext<T>,
  ): DataGridContextMenuCommandAvailability;

  isColumnGroupCollapsed(context: DataGridContextMenuContext<T>): boolean;

  areRowGroupDescendantsSelected(context: DataGridContextMenuContext<T>): boolean;

  isTreeContext(context: DataGridContextMenuContext<T>): boolean;

  isTreeNodeExpanded(context: DataGridContextMenuContext<T>): boolean;

  async execute(
    id: DataGridContextMenuCommandId,
    context: DataGridContextMenuContext<T>,
  ): Promise<void>;
}
```

---

### `DataGridContextMenuContributionRegistry`

**@internal** Instance-owned data-grid contribution registry.

```ts
class DataGridContextMenuContributionRegistry {
  register(contribution: DataGridContextMenuContribution<T>): () => void;

  resolve(
    context: DataGridContextMenuContext<T>,
    defaultItems: readonly ContextMenuItem[],
  ): ContextMenuItem[];

  shouldSuppress(context: DataGridContextMenuContext<T>): boolean;

  getTargets(): DataGridContextMenuContributionTargets;
}
```

---

### `buildDataGridContextMenuItems`

Apply configuration around the generated items for one semantic surface.

```ts
export function buildDataGridContextMenuItems<T extends DataType = DataType>(
  context: DataGridContextMenuContext<T>,
  config: DataGridContextMenuConfig<T>,
  commands: DataGridContextMenuCommands<T>,
  contributions?: DataGridMenuContributionResolver<T>,
): ContextMenuItem[];
```

---

### `createCellCommands`

```ts
export function createCellCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `serializeTsv`

```ts
export function serializeTsv(
  matrix: readonly (readonly DataFormat[])[],
): string;
```

---

### `parseTsv`

```ts
export function parseTsv(value: string): string[][];
```

---

### `parseHtmlTable`

```ts
export function parseHtmlTable(value: string): string[][] | null;
```

---

### `canWriteClipboard`

```ts
export function canWriteClipboard(): boolean;
```

---

### `canReadClipboard`

```ts
export function canReadClipboard(): boolean;
```

---

### `writeClipboardTransfer`

```ts
export async function writeClipboardTransfer(
  transfer: DataTransfer,
  fallbackText: string,
): Promise<void>;
```

---

### `readClipboardTransfer`

```ts
export async function readClipboardTransfer(): Promise<DataTransfer>;
```

---

### `createClipboardEvent`

```ts
export function createClipboardEvent(transfer: DataTransfer): ClipboardEvent;
```

---

### `createClipboardCommands`

```ts
export function createClipboardCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `createColumnGroupCommands`

```ts
export function createColumnGroupCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `isColumnGroupCollapsed`

```ts
export function isColumnGroupCollapsed<T extends DataType>(
  context: DataGridContextMenuContext<T>,
  runtime: DataGridContextMenuCommandRuntime<T>,
): boolean;
```

---

### `createColumnPositionCommands`

```ts
export function createColumnPositionCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `createColumnSchemaCommands`

```ts
export function createColumnSchemaCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `createColumnSizingCommands`

```ts
export function createColumnSizingCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `createColumnStateCommands`

```ts
export function createColumnStateCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `cloneColumnTree`

```ts
export function cloneColumnTree(
  columns: readonly AuthoredColumn[],
): AuthoredColumn[];
```

---

### `flattenColumnTree`

```ts
export function flattenColumnTree(
  columns: readonly AuthoredColumn[],
): ColumnRegular[];
```

---

### `findColumn`

```ts
export function findColumn(
  columns: AuthoredColumn[],
  prop: ColumnProp,
): FoundColumn | undefined;
```

---

### `removeColumn`

```ts
export function removeColumn(
  columns: AuthoredColumn[],
  prop: ColumnProp,
): boolean;
```

---

### `AuthoredColumn`

```ts
export type AuthoredColumn = ColumnGrouping | ColumnRegular;
```

---

### `FoundColumn`

```ts
interface FoundColumn {
  parent: AuthoredColumn[];
  index: number;
  column: ColumnRegular
}
```

---

### `createColumnVisibilityCommands`

```ts
export function createColumnVisibilityCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `createCommandRegistry`

The only place where independent built-in command domains are composed.

```ts
export function createCommandRegistry<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `VisibleColumnLocation`

```ts
interface VisibleColumnLocation {
  type: DimensionCols;
  index: number;
  physicalIndex: number
}
```

---

### `DataGridContextMenuCommandRuntime`

Shared access to grid-owned state used by independent command domains.

```ts
class DataGridContextMenuCommandRuntime {
  getPlugin<C>(plugin: new (...args: any[]) => C): C | undefined;

  hasHandler(id: DataGridContextMenuCommandId): boolean;

  /** Retain the latest command-owned payload and typed values for in-grid paste. */
  rememberClipboardTransfer(
    transfer: DataTransfer,
    matrix?: DataFormat[][],
  ): void;

  /** Recreate the latest command-owned clipboard payload without sharing mutable DataTransfer state. */
  restoreClipboardTransfer(): DataTransfer | undefined;

  /** Return typed values only while the current clipboard still matches this command-owned copy. */
  restoreClipboardMatrix(transfer: DataTransfer): DataFormat[][] | undefined;

  hasRemoteRows(): boolean;

  actionContext(context: DataGridContextMenuContext<T>): ContextMenuActionContext;

  sourceFor(type: DimensionRows): T[];

  visibleSourceFor(type: DimensionRows): T[];

  projectedSourceFor(type: DimensionRows): T[];

  setSource(type: DimensionRows, source: T[]): void;

  /** Resolve a projected/grouped target back to the application-authored row. */
  authoredRow(row: DataGridContextMenuRow<T>): T | undefined;

  authoredColumns(): AuthoredColumn[];

  setColumns(columns: AuthoredColumn[]): void;

  allVisibleColumns(): ColumnRegular[];

  findVisibleColumn(prop: ColumnProp): VisibleColumnLocation | undefined;

  removeCustomSizes(
    type: DimensionRows | DimensionCols,
    indexes: readonly number[],
  ): void;

  hasCustomSize(type: DimensionRows | DimensionCols, index: number): boolean;
}
```

---

### `mergeCommandDefinitions`

```ts
export function mergeCommandDefinitions<T extends DataType>(
  ...groups: DataGridContextMenuCommandDefinitions<T>[]
): DataGridContextMenuCommandDefinitions<T>;
```

---

### `DataGridContextMenuCommandAvailability`

```ts
export type DataGridContextMenuCommandAvailability =
  | 'available'
  | 'disabled'
  | 'hidden'
  | 'unavailable';
```

---

### `DataGridContextMenuCommandDefinition`

```ts
interface DataGridContextMenuCommandDefinition {
  isAvailable(
      context: DataGridContextMenuContext<T>,
      runtime: DataGridContextMenuCommandRuntime<T>,
    ): boolean;
  getState?(
      context: DataGridContextMenuContext<T>,
      runtime: DataGridContextMenuCommandRuntime<T>,
    ): Exclude<DataGridContextMenuCommandAvailability, 'unavailable'>;
  execute(
      context: DataGridContextMenuContext<T>,
      runtime: DataGridContextMenuCommandRuntime<T>,
    ): void | Promise<void>
}
```

---

### `DataGridContextMenuCommandDefinitions`

```ts
export type DataGridContextMenuCommandDefinitions<T extends DataType = DataType> =
  Partial<Record<DataGridContextMenuCommandId, DataGridContextMenuCommandDefinition<T>>>;
```

---

### `createCellMatrix`

```ts
export function createCellMatrix<T extends DataType>(
  runtime: DataGridContextMenuCommandRuntime<T>,
  context: DataGridContextMenuContext<T>,
  headers: boolean,
): DataFormat[][];
```

---

### `createRowMatrix`

```ts
export function createRowMatrix<T extends DataType>(
  runtime: DataGridContextMenuCommandRuntime<T>,
  context: DataGridContextMenuContext<T>,
  headers: boolean,
): DataFormat[][];
```

---

### `createColumnMatrix`

```ts
export function createColumnMatrix<T extends DataType>(
  runtime: DataGridContextMenuCommandRuntime<T>,
  context: DataGridContextMenuContext<T>,
  headers: boolean,
): DataFormat[][];
```

---

### `clearContext`

```ts
export function clearContext<T extends DataType>(
  runtime: DataGridContextMenuCommandRuntime<T>,
  context: DataGridContextMenuContext<T>,
): void;
```

---

### `clearRows`

Clear full visible rows while retaining the row span resolved from selection.

```ts
export function clearRows<T extends DataType>(
  runtime: DataGridContextMenuCommandRuntime<T>,
  context: DataGridContextMenuContext<T>,
): void;
```

---

### `applyPasteMatrix`

```ts
export function applyPasteMatrix<T extends DataType>(
  runtime: DataGridContextMenuCommandRuntime<T>,
  context: DataGridContextMenuContext<T>,
  matrix: DataFormat[][],
): void;
```

---

### `dispatchRangeEdit`

```ts
export function dispatchRangeEdit(
  revogrid: HTMLRevoGridElement,
  detail: BeforeRangeSaveDataDetails,
): void;
```

---

### `createExportCommands`

```ts
export function createExportCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `createFilterCommands`

```ts
export function createFilterCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `resolveFormattingTarget`

Resolve spreadsheet selection semantics independently from command dispatch.

```ts
export function resolveFormattingTarget<T extends DataType>(
  context: DataGridContextMenuContext<T>,
  runtime: DataGridContextMenuCommandRuntime<T>,
): ResolvedFormattingTarget<T> | undefined;
```

---

### `getFormattingConfig`

```ts
export function getFormattingConfig<T extends DataType>(
  runtime: DataGridContextMenuCommandRuntime<T>,
): DataGridFormattingConfig<T> | undefined;
```

---

### `ResolvedFormattingTarget`

```ts
interface ResolvedFormattingTarget {
  readonly selection: DataGridFormattingResolvedSelection<T>;
  readonly coordinates: DataGridFormattingTarget;
  readonly valueKind: DataGridFormattingValueKind;
  readonly canFormatValue: boolean
}
```

---

### `createFormattingCommands`

```ts
export function createFormattingCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `createInspectionCommands`

```ts
export function createInspectionCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `isInvokedCellReadOnly`

Evaluate the invoked cell with the same schema contract used by core editing.

```ts
export function isInvokedCellReadOnly<T extends DataType>(
  context: DataGridContextMenuContext<T>,
  runtime: DataGridContextMenuCommandRuntime<T>,
): boolean;
```

---

### `hasWritableContextCell`

True when at least one resolved cell target can accept an edit.

```ts
export function hasWritableContextCell<T extends DataType>(
  context: DataGridContextMenuContext<T>,
  runtime: DataGridContextMenuCommandRuntime<T>,
): boolean;
```

---

### `isTreeStructuralColumn`

```ts
export function isTreeStructuralColumn<T extends DataType>(
  column: ColumnRegular,
  runtime: DataGridContextMenuCommandRuntime<T>,
): boolean;
```

---

### `isGridReadOnly`

```ts
export function isGridReadOnly<T extends DataType>(
  context: DataGridContextMenuContext<T>,
  runtime: DataGridContextMenuCommandRuntime<T>,
): boolean;
```

---

### `isResolvedCellReadOnly`

```ts
export function isResolvedCellReadOnly<T extends DataType>(
  row: DataGridContextMenuRow<T>,
  column: ColumnRegular,
  runtime: DataGridContextMenuCommandRuntime<T>,
): boolean;
```

---

### `createRowGroupCommands`

```ts
export function createRowGroupCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `areAllRowGroupDescendantsSelected`

```ts
export function areAllRowGroupDescendantsSelected<T extends DataType>(
  context: DataGridContextMenuContext<T>,
  runtime: DataGridContextMenuCommandRuntime<T>,
): boolean;
```

---

### `createRowLayoutCommands`

```ts
export function createRowLayoutCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `createRowMutationCommands`

```ts
export function createRowMutationCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `createTreeCommands`

```ts
export function createTreeCommands<T extends DataType>(): DataGridContextMenuCommandDefinitions<T>;
```

---

### `isTreeContext`

```ts
export function isTreeContext<T extends DataType>(
  context: DataGridContextMenuContext<T>,
  runtime: DataGridContextMenuCommandRuntime<T>,
): boolean;
```

---

### `isTreeNodeExpanded`

```ts
export function isTreeNodeExpanded<T extends DataType>(
  context: DataGridContextMenuContext<T>,
  runtime: DataGridContextMenuCommandRuntime<T>,
): boolean;
```

---

### `createTreeRowFactory`

```ts
export function createTreeRowFactory<T extends DataType>(
  context: DataGridContextMenuContext<T>,
  runtime: DataGridContextMenuCommandRuntime<T>,
);
```

---

### `resolveDataGridContextMenuColumns`

```ts
export function resolveDataGridContextMenuColumns(
  menu: ContextMenuOpenContext,
  surface: DataGridContextMenuSurface,
  columnType?: DimensionCols,
  range?: RangeArea,
): ColumnRegular[];
```

---

### `resolveColumnPhysicalIndex`

```ts
export function resolveColumnPhysicalIndex(
  menu: ContextMenuOpenContext,
  columnType?: DimensionCols,
): number | undefined;
```

---

### `resolveColumnSize`

```ts
export function resolveColumnSize(
  menu: ContextMenuOpenContext,
  columnType?: DimensionCols,
): number | undefined;
```

---

### `resolveDataGridContextMenuRows`

```ts
export function resolveDataGridContextMenuRows(
  menu: Extract<ContextMenuOpenContext, { target: 'row' }>,
  surface: DataGridContextMenuSurface,
  rowType: DimensionRows,
  range?: RangeArea,
): DataGridContextMenuRow[];
```

---

### `resolveInvokedSelectionRange`

```ts
export function resolveInvokedSelectionRange(
  menu: Extract<ContextMenuOpenContext, { target: 'row' }>,
  columnType?: DimensionCols,
): RangeArea | undefined;
```

---

### `normalizeDataColumnType`

```ts
export function normalizeDataColumnType(
  type: unknown,
): DimensionCols | undefined;
```

---

### `CELL_CLIPBOARD_ICONS`

```ts
CELL_CLIPBOARD_ICONS: {
  'cell.edit': string;
  'cell.inspect': string;
  'cell.clear': string;
  'clipboard.cut': string;
  'clipboard.copy': string;
  'clipboard.copyCell': string;
  'clipboard.copyWithHeaders': string;
  'clipboard.paste': string;
};
```

---

### `getColumnGroupToggleIcon`

```ts
export function getColumnGroupToggleIcon(
  state: DataGridContextMenuIconState,
): string;
```

---

### `COLUMN_GROUP_ICONS`

```ts
COLUMN_GROUP_ICONS: {
  'columnGroup.autoSize': string;
  'columnGroup.hide': string;
};
```

---

### `COLUMN_ICONS`

```ts
COLUMN_ICONS: {
  'column.copy': string;
  'column.copyWithHeader': string;
  'column.inspect': string;
  'column.sortAscending': string;
  'column.sortDescending': string;
  'column.clearSort': string;
  'column.groupBy': string;
  'column.ungroup': string;
  'column.pinLeft': string;
  'column.pinRight': string;
  'column.unpin': string;
  'column.moveLeft': string;
  'column.moveRight': string;
  'column.moveStart': string;
  'column.moveEnd': string;
  'column.autoSize': string;
  'column.autoSizeAll': string;
  'column.resetWidth': string;
  'column.hide': string;
  'column.manage': string;
  'column.insertLeft': string;
  'column.insertRight': string;
  'column.duplicate': string;
  'column.delete': string;
};
```

---

### `EXPORT_ICONS`

```ts
EXPORT_ICONS: {
  'column.exportCsv': string;
  'export.selectionCsv': string;
  'export.rowsCsv': string;
  'export.allCsv': string;
  'export.allExcel': string;
};
```

---

### `FILTER_ICONS`

```ts
FILTER_ICONS: {
  'filter.keepOnly': string;
  'filter.exclude': string;
  'filter.open': string;
  'filter.clear': string;
  'column.filterOpen': string;
  'column.filterClear': string;
};
```

---

### `FORMATTING_ICONS`

```ts
FORMATTING_ICONS: {
  'menu.format': string;
  'format.automatic': string;
  'format.number': string;
  'format.currency': string;
  'format.accounting': string;
  'format.percent': string;
  'format.scientific': string;
  'format.date': string;
  'format.datetime': string;
  'format.time': string;
  'format.more': string;
  'format.clear': string;
};
```

---

### `resolveDataGridContextMenuIcon`

```ts
export function resolveDataGridContextMenuIcon(
  id: DataGridContextMenuItemId,
  state: DataGridContextMenuIconState,
): string | undefined;
```

---

### `DataGridContextMenuIconMap`

```ts
export type DataGridContextMenuIconMap = Partial<Record<
  DataGridContextMenuItemId,
  string
>>;
```

---

### `DataGridContextMenuIconState`

```ts
interface DataGridContextMenuIconState {
  readonly rowGroupExpanded: boolean;
  readonly columnGroupCollapsed: boolean;
  readonly treeNodeExpanded?: boolean
}
```

---

### `MENU_ICONS`

```ts
MENU_ICONS: {
  'menu.copy': string;
  'menu.rows': string;
  'menu.filter': string;
  'menu.export': string;
  'menu.sort': string;
  'menu.grouping': string;
  'menu.pin': string;
  'menu.move': string;
  'menu.size': string;
  'menu.schema': string;
  'menu.tree': string;
};
```

---

### `getRowGroupToggleIcon`

```ts
export function getRowGroupToggleIcon(
  state: DataGridContextMenuIconState,
): string;
```

---

### `ROW_GROUP_ICONS`

```ts
ROW_GROUP_ICONS: {
  'rowGroup.expandAll': string;
  'rowGroup.collapseAll': string;
  'rowGroup.selectDescendants': string;
  'rowGroup.copy': string;
  'rowGroup.copyWithHeaders': string;
  'rowGroup.exportCsv': string;
  'rowGroup.removeField': string;
  'rowGroup.clearGrouping': string;
};
```

---

### `ROW_ICONS`

```ts
ROW_ICONS: {
  'row.copy': string;
  'row.copyWithHeaders': string;
  'row.clear': string;
  'row.insertAbove': string;
  'row.insertBelow': string;
  'row.duplicate': string;
  'row.delete': string;
  'row.pinTop': string;
  'row.pinBottom': string;
  'row.unpin': string;
};
```

---

### `getTreeToggleIcon`

```ts
export function getTreeToggleIcon(state: DataGridContextMenuIconState): string;
```

---

### `TREE_ICONS`

```ts
TREE_ICONS: {
  'tree.expandAll': string;
  'tree.collapseAll': string;
  'tree.addChild': string;
  'tree.moveUp': string;
  'tree.moveDown': string;
  'tree.indent': string;
  'tree.outdent': string;
};
```

---

### `buildMenuItem`

```ts
export function buildMenuItem<T extends DataType>(
  spec: DataGridMenuItemSpec,
  context: DataGridContextMenuContext<T>,
  config: DataGridContextMenuConfig<T>,
  commands: DataGridContextMenuCommands<T>,
  locale: DataGridContextMenuLocaleText,
  iconState: DataGridContextMenuIconState,
): ContextMenuItem[];
```

---

### `createMenuSections`

Flattens named task sections into menu specs separated by the shared Context
Menu divider primitive. Runtime normalization removes dividers around hidden
or unavailable sections.

```ts
export function createMenuSections(
  sections: readonly DataGridMenuSection[],
): DataGridMenuItemSpec[];
```

---

### `DataGridMenuSection`

```ts
export type DataGridMenuSection = {
  /** Semantic section name used only to identify its internal divider. */
  readonly id: string;
  readonly items: readonly DataGridMenuItemSpec[];
};
```

---

### `isMenuSeparatorSpec`

```ts
export function isMenuSeparatorSpec(
  spec: DataGridMenuItemSpec,
): spec is DataGridMenuSeparatorSpec;
```

---

### `collectMenuItemIds`

```ts
export function collectMenuItemIds(
  specs: readonly DataGridMenuItemSpec[],
): readonly DataGridContextMenuItemId[];
```

---

### `DataGridMenuCommandSpec`

```ts
export type DataGridMenuCommandSpec = {
  id: DataGridContextMenuItemId;
  children: readonly DataGridMenuItemSpec[];
};
```

---

### `DataGridMenuSeparatorSpec`

```ts
export type DataGridMenuSeparatorSpec = {
  kind: 'separator';
  id: string;
};
```

---

### `DataGridMenuItemSpec`

```ts
export type DataGridMenuItemSpec =
  | DataGridContextMenuItemId
  | DataGridMenuCommandSpec
  | DataGridMenuSeparatorSpec;
```

---

### `getSurfaceItemSpecs`

```ts
export function getSurfaceItemSpecs(
  surface: DataGridContextMenuSurface,
): readonly DataGridMenuItemSpec[];
```

---

### `CELL_CLIPBOARD_ITEMS`

```ts
CELL_CLIPBOARD_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_CLIPBOARD_ITEMS`

```ts
COLUMN_CLIPBOARD_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_SORT_ITEMS`

```ts
COLUMN_SORT_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_GROUPING_ITEMS`

```ts
COLUMN_GROUPING_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_PIN_ITEMS`

```ts
COLUMN_PIN_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_MOVE_ITEMS`

```ts
COLUMN_MOVE_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_SIZE_ITEMS`

```ts
COLUMN_SIZE_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_SCHEMA_ITEMS`

```ts
COLUMN_SCHEMA_ITEMS: DataGridMenuItemSpec[];
```

---

### `CELL_EXPORT_ITEMS`

```ts
CELL_EXPORT_ITEMS: DataGridMenuItemSpec[];
```

---

### `ROW_HEADER_EXPORT_ITEMS`

```ts
ROW_HEADER_EXPORT_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_EXPORT_ITEMS`

```ts
COLUMN_EXPORT_ITEMS: DataGridMenuItemSpec[];
```

---

### `CELL_FILTER_ITEMS`

```ts
CELL_FILTER_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_FILTER_ITEMS`

```ts
COLUMN_FILTER_ITEMS: DataGridMenuItemSpec[];
```

---

### `FORMAT_CONTEXT_MENU_ITEMS`

```ts
FORMAT_CONTEXT_MENU_ITEMS: DataGridMenuItemSpec[];
```

---

### `CELL_ROW_ITEMS`

```ts
CELL_ROW_ITEMS: DataGridMenuItemSpec[];
```

---

### `ROW_HEADER_ROW_ITEMS`

```ts
ROW_HEADER_ROW_ITEMS: DataGridMenuItemSpec[];
```

---

### `ROW_PIN_ITEMS`

```ts
ROW_PIN_ITEMS: DataGridMenuItemSpec[];
```

---

### `TREE_CONTEXT_MENU_ITEMS`

```ts
TREE_CONTEXT_MENU_ITEMS: DataGridMenuItemSpec[];
```

---

### `CELL_CONTEXT_MENU_ITEMS`

```ts
CELL_CONTEXT_MENU_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_GROUP_HEADER_CONTEXT_MENU_ITEMS`

```ts
COLUMN_GROUP_HEADER_CONTEXT_MENU_ITEMS: DataGridMenuItemSpec[];
```

---

### `COLUMN_HEADER_CONTEXT_MENU_ITEMS`

```ts
COLUMN_HEADER_CONTEXT_MENU_ITEMS: DataGridMenuItemSpec[];
```

---

### `ROW_GROUP_CONTEXT_MENU_ITEMS`

```ts
ROW_GROUP_CONTEXT_MENU_ITEMS: DataGridMenuItemSpec[];
```

---

### `ROW_HEADER_CONTEXT_MENU_ITEMS`

```ts
ROW_HEADER_CONTEXT_MENU_ITEMS: DataGridMenuItemSpec[];
```

---

# Data Grid Formatting

URL: https://pro.rv-grid.com/api/data-grid-formatting/
Source: src/content/docs/api/data-grid-formatting.md

## Module Extensions

### `DataGridAdvancedFormatsConfig`

```ts
interface DataGridAdvancedFormatsConfig {
  /** Disable or override individual built-ins by stable id. */
    readonly formats?: Readonly<Record<
      string,
      false | DataGridAdvancedFormatOverride
    >>;
  /** Application formats appended to the built-in catalog. */
    readonly customFormats?: readonly DataGridAdvancedFormatDefinition[];
  /** Optional editors for ordinary value presets such as `date`. */
    readonly presetEditors?: Partial<Record<
      DataGridValueFormatPreset,
      false | EditorCtr | string
    >>;
  /** Allow presentations to replace application cell templates globally. */
    readonly replaceAuthoredTemplates?: boolean;
  /** Allow format-resolved editors to replace application editors globally. */
    readonly replaceAuthoredEditors?: boolean
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [DATA_GRID_FORMATTING_CONFIGURATION_CHANGE_EVENT]: Readonly<DataGridFormattingConfig>
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /** Reactive declarative formats consumed by DataGridFormattingPlugin. */
      dataGridFormatting?: DataGridFormattingPresetState;
  'data-grid-formatting'?: DataGridFormattingPresetState
}
```

---

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /** Static or cell-resolved declarative Format Cells configuration. */
      dataGridFormat?: DataGridFormatDefinition<TModel, P>
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /** @deprecated Prefer `grid.dataGridFormatting`. */
      dataGridFormatting?: DataGridFormattingPresetState
}
```

## Plugin API

### `DataGridFormattingPluginOptions`

**@internal** Coordinates reciprocal plugin installation.

```ts
interface DataGridFormattingPluginOptions {
  readonly installContextMenu?: boolean;
  readonly installPanel?: boolean
}
```

---

### `DataGridFormattingPlugin`

Spreadsheet-style value, visual presentation, appearance, and editor
configuration for RevoGrid cells, rows, and columns.

Register this plugin once in `grid.plugins`. It installs the task-oriented
data-grid context menu, Format Cells dialog, and visual-format tooltips automatically. It also installs
the formatting-panel runtime; set `grid.dataGridFormattingPanel = true` to
show the opt-in toolbar. Formatting can then be declared through `column.dataGridFormat` or
`grid.dataGridFormatting`, inferred from a registered renderer assigned to
`column.cellTemplate`, or changed at runtime through this plugin's API.
Source values are never modified.

Numeric values and numeric presets are right-aligned automatically. Set
`appearance.horizontal` to `left`, `center`, or `right` to override it.
Configure `autoAlignNumericValues: false` to disable this derived alignment.
Effective advanced presentations retain their own layout unless an explicit
horizontal alignment is authored.

**Example: Declarative column, row, and cell formatting**
```typescript
import type { ColumnRegular } from '@revolist/revogrid';
import {
  DataGridFormattingPlugin,
  type DataGridCellFormat,
} from '@revolist/revogrid-pro';

type InvoiceRow = { id: string; customer: string; amount: number };

const money: DataGridCellFormat = {
  value: {
    preset: 'currency',
    locale: 'en-GB',
    currency: 'GBP',
    decimalPlaces: 2,
  },
};

const columns: ColumnRegular<string, InvoiceRow>[] = [
  { prop: 'customer', name: 'Customer' },
  { prop: 'amount', name: 'Amount', dataGridFormat: money },
];

grid.plugins = [DataGridFormattingPlugin];
grid.columns = columns;
grid.dataGridFormatting = {
  rows: [{ row: 0, format: { appearance: { bold: true } } }],
  cells: [{ range: { start: { row: 1, column: 1 } }, format: {
    ...money,
    appearance: { ...money.appearance, bold: true, fillColor: '#fef3c7' },
  } }],
};
grid.source = [
  { id: 'invoice-1', customer: 'Acme Ltd', amount: 1200 },
  { id: 'invoice-2', customer: 'Northwind', amount: -350.5 },
];
```

**Example: Save and restore application-owned formatting state**
```typescript
const saved = loadFormatting();

grid.plugins = [DataGridFormattingPlugin];
grid.dataGridFormatting = {
  state: saved,
};
grid.addEventListener('datagridformattingchange', ({ detail }) => {
  saveFormatting(detail.state);
});
```

**Example: Configure advanced formats and application-owned editors**
```typescript
import DateColumnType from '@revolist/revogrid-column-date';
import {
  DataGridFormattingPlugin,
  type DataGridFormattingConfig,
} from '@revolist/revogrid-pro';

const dateType = new DateColumnType();
const formatting: DataGridFormattingConfig = {
  advancedFormats: {
    // Compatible built-ins are enabled unless explicitly disabled.
    formats: {
      pie: false,
      heatmap: { defaults: { minValue: 0, maxValue: 100 } },
    },
    // Editor packages stay optional and are supplied by the application.
    presetEditors: { date: dateType.editor },
  },
};

grid.plugins = [DataGridFormattingPlugin];
grid.dataGridContextMenu = { formatting };
grid.columns = [{
  prop: 'completion',
  name: 'Completion',
  dataGridFormat: {
    presentation: {
      id: 'progress-line',
      options: { minValue: 0, maxValue: 100 },
    },
  },
}];
```

#### Dependencies

- **Auto-installed** `EventManagerPlugin`: Normalizes edits and paste operations through the unified grid edit pipeline.
- **Auto-installed** `AutoFillPlugin`: Generates spreadsheet-style value sequences while formatting follows the filled range.
- **Auto-installed** `ClipboardPlugin`: Provides rich Excel-compatible clipboard formatting.
- **Auto-installed** `DataGridFormatDialogPlugin`: Uses the Format Cells dialog for advanced formatting.
- **Optional** `FormulaPlugin`: Formats evaluated formula results while preserving raw formula source values.
- **Auto-installed** `DataGridContextMenuPlugin`: Provides Format Cells commands through the task-oriented data-grid context menu.
- **Auto-installed** `TooltipPlugin`: Displays details for visual-format parts such as Timeline events.
- **Auto-installed** `DataGridFormattingPanelPlugin`: Provides the opt-in single-row formatting toolbar runtime.

```ts
class DataGridFormattingPlugin {
  /**
     * Replace the runtime options used by dialog and programmatic formatting.
     *
     * Context-menu applications can set the same options reactively through
     * `grid.dataGridContextMenu.formatting`.
     *
     * @param config Locale, dialog, value-kind, advanced-format,
     * and optional editor settings.
     */
  configure(config: DataGridFormattingConfig<T> = {}): void;

  /** Return the active formatting options used by the dialog and toolbar. */
  getConfiguration(): Readonly<DataGridFormattingConfig<T>>;

  /** Convert safe Excel HTML declarations into canonical formatting options. */
  importExcelClipboardFormat(
    declarations: readonly string[],
  ): DataGridCellFormat | undefined;

  /** Convert display-only Excel HTML text using its canonical imported format. */
  importExcelClipboardValue(displayText: string, format?: DataGridCellFormat): unknown;

  /** Convert canonical formatting options into Excel-compatible HTML declarations. */
  exportExcelClipboardFormat(format: DataGridCellFormat): string | undefined;

  /** Convert a source value into the typed/display pair written to Excel HTML. */
  exportExcelClipboardValue(value: unknown, format: DataGridCellFormat);

  /**
     * Apply a complete value, advanced-presentation, and appearance format to a
     * physical cell, complete-row, or complete-column selection. This runtime format takes precedence over
     * declarative presets.
     *
     * @param target Physical cell, complete-row, or complete-column source coordinates to format.
     * @param format Complete format to apply.
     */
  apply(target: DataGridFormattingTarget, format: DataGridCellFormat): void;

  /** @internal Applies one clipboard/import batch with a single refresh and change event. */
  applyBatch(entries: readonly {
    target: DataGridFormattingTarget;
    /** `null` records an explicit clipboard clear for the target. */
    format: DataGridCellFormat | null;
  }[]): void;

  /** @internal Applies accepted autofill formatting as one runtime mutation. */
  applyAutofillBatch(entries: readonly AutofillFormattingBatchEntry[]): void;

  /**
     * Select an ordinary value presentation while retaining font, fill,
     * alignment, and other appearance settings. A concrete value presentation
     * replaces any active advanced visualization for the same target.
     *
     * @param target Physical cell, complete-row, or complete-column source coordinates to format.
     * @param value Value-format layer to apply.
     */
  applyValueFormat(
    target: DataGridFormattingTarget,
    value: DataGridCellFormat['value'],
  ): void;

  /**
     * Patch selected formats without erasing unrelated value, appearance, or
     * presentation settings. A resolver can return a different patch per cell.
     */
  patch(
    target: DataGridFormattingTarget,
    patch: DataGridCellFormatPatch | DataGridFormattingPatchResolver<T>,
  ): void;

  /**
     * Clear runtime formatting for a physical cell selection without changing
     * source values. The explicit clear suppresses lower-priority declarative
     * formatting for that target.
     *
     * @param target Physical cell, complete-row, or complete-column source coordinates to clear.
     */
  clear(target: DataGridFormattingTarget): void;

  /**
     * Return the effective format for a cell after runtime and
     * declarative precedence has been resolved.
     *
     * @param address Physical source address of the cell.
     * @returns The effective format, or `undefined` when no format applies.
     */
  getFormat(address: PhysicalCellAddress): DataGridCellFormat | undefined;

  /** Return the effective coordinate-owned format for a complete column. */
  getColumnFormat(address: PhysicalColumnAddress): DataGridCellFormat | undefined;

  /** Return the coordinate-owned format for a complete row. */
  getRowFormat(address: PhysicalRowAddress): DataGridCellFormat | undefined;

  /**
     * Return the effective built-in, overridden, or application-defined advanced
     * format definition by its stable presentation id.
     *
     * Export integrations use this to apply presentation-owned scalar export
     * values without inspecting rendered cells.
     */
  getAdvancedFormatDefinition(id: string): DataGridAdvancedFormatDefinition | undefined;

  /**
     * Return a portable snapshot of coordinate-owned runtime operations.
     */
  getState(): DataGridFormattingRuntimeState;

  /**
     * Replace runtime Apply and Clear operations from a previous `getState()`
     * snapshot, refresh the grid, and emit `datagridformattingchange`.
     */
  setState(state: DataGridFormattingRuntimeState): void;

  /** @internal Replays a formatting state from HistoryPlugin. */
  applyHistoryState(state: DataGridFormattingRuntimeState): boolean;

  /** @internal Called by HistoryPlugin around an atomic structural snapshot replay. */
  beginHistoryStructureReplay(): void;

  /** @internal Called by HistoryPlugin after formatting and structure are both restored. */
  endHistoryStructureReplay(): void;

  /** @internal Keeps partial structural commands inside their History transaction. */
  flushPendingStructuralTransaction(transactionId: number): void;

  /**
     * Open the Format Cells dialog for a selection. Context-menu users do not
     * need to call this method directly.
     *
     * @param target Physical cells, complete rows, or complete columns to edit.
     * @param valueKind Value category used to choose available presets.
     * @param valueFormatting Set to `false` for appearance-only editing.
     */
  openDialog(
    target: DataGridFormattingTarget,
    valueKind: DataGridFormattingValueKind,
    valueFormatting = true,
  ): void;

  /** Return the effective value kind, including evaluated formula results. */
  inferValueKind(target: DataGridFormattingTarget): DataGridFormattingValueKind;

  resolveCellValue(
    model: T,
    column: ColumnRegular,
    rowType?: DimensionRows,
    value: unknown = model[column.prop],
  ): unknown;
}
```

---

### `isDataGridFormattingRuntime`

```ts
export function isDataGridFormattingRuntime(
  value: unknown,
): value is DataGridFormattingRuntime;
```

---

### `DATA_GRID_FORMATTING_PLUGIN`

```ts
DATA_GRID_FORMATTING_PLUGIN: string;
```

---

### `DATA_GRID_FORMATTING_CHANGE_EVENT`

```ts
DATA_GRID_FORMATTING_CHANGE_EVENT: string;
```

---

### `DATA_GRID_FORMATTING_CONFIGURATION_CHANGE_EVENT`

```ts
DATA_GRID_FORMATTING_CONFIGURATION_CHANGE_EVENT: string;
```

---

### `DataGridFormattingRuntime` (Extended from `index.ts`)

```ts
interface DataGridFormattingRuntime {
  readonly [DATA_GRID_FORMATTING_PLUGIN]: true;
  getFormat(address: PhysicalCellAddress): DataGridCellFormat | undefined;
  getColumnFormat(address: PhysicalColumnAddress): DataGridCellFormat | undefined;
  getRowFormat(address: PhysicalRowAddress): DataGridCellFormat | undefined;
  getAdvancedFormatDefinition(id: string): DataGridAdvancedFormatDefinition | undefined;
  getState(): DataGridFormattingRuntimeState;
  apply(target: DataGridFormattingTarget, format: DataGridCellFormat): void;
  applyBatch(entries: readonly {
      target: DataGridFormattingTarget;
      format: DataGridCellFormat | null;
    }[]): void;
  importExcelClipboardFormat(declarations: readonly string[]): DataGridCellFormat | undefined;
  importExcelClipboardValue(displayText: string, format?: DataGridCellFormat): unknown;
  exportExcelClipboardFormat(format: DataGridCellFormat): string | undefined;
  exportExcelClipboardValue(
      value: unknown,
      format: DataGridCellFormat,
    ): DataGridExcelClipboardValue;
  resolveCellValue(
      model: DataType,
      column: ColumnRegular,
      rowType?: DimensionRows,
      value?: unknown,
    ): unknown
}
```

---

### `DataGridExcelClipboardValue`

```ts
interface DataGridExcelClipboardValue {
  /** Typed value written to Excel HTML. Source data is never mutated. */
    readonly value: unknown;
  /** Canonically formatted text shown by Excel before/recalculation. */
    readonly displayText: string
}
```

---

### `resolveDataGridFormattingLocale`

```ts
export function resolveDataGridFormattingLocale(
  localeText?: DataGridFormattingDialogConfig['localeText'],
): DataGridFormattingLocaleText;
```

---

### `DATA_GRID_FORMATTING_LOCALE`

```ts
DATA_GRID_FORMATTING_LOCALE: {
  title: string;
  close: string;
  description: string;
  selectionSummary: string;
  selectionCells: string;
  selectionColumns: string;
  valueSection: string;
  automaticDescription: string;
  advancedSection: string;
  advancedNone: string;
  advancedDescription: string;
  numberSection: string;
  category: string;
  locale: string;
  browserDefault: string;
  decimals: string;
  grouping: string;
  currency: string;
  negativeNumbers: string;
  dateStyle: string;
  timeStyle: string;
  custom: string;
  formatCode: string;
  invalidFormatCode: string;
  fontSection: string;
  typographySection: string;
  colorsSection: string;
  fontFamily: string;
  defaultFont: string;
  fontSize: string;
  bold: string;
  italic: string;
  underline: string;
  strike: string;
  textColor: string;
  fillColor: string;
  useTextColor: string;
  useFillColor: string;
  defaultColor: string;
  noFill: string;
  customColor: string;
  customColorHex: string;
  invalidColor: string;
  colorLabels: { [k: string]: string; };
  advancedGroupLabels: { Advanced: string; Indicators: string; Charts: string; Values: string; Identity: string; Summaries: string; };
  advancedFormatLabels: { 'progress-line': string; 'progress-line-value': string; 'circular-progress': string; heatmap: string; rating: string; change: string; threshold: string; boolean: string; thumbs: string; badge: string; sparkline: string; bar: string; pie: string; timeline: string; avatar: string; 'avatar-with-text': string; 'summary-percentage': string; 'summary-aggregate': string; };
  advancedFormatDescriptions: { 'progress-line': string; 'progress-line-value': string; threshold: string; };
  advancedControlLabels: { 'progress-line.minValue': string; 'progress-line.maxValue': string; 'progress-line-value.minValue': string; 'progress-line-value.maxValue': string; 'circular-progress.minValue': string; 'circular-progress.maxValue': string; 'circular-progress.showValue': string; 'heatmap.minValue': string; 'heatmap.midValue': string; 'heatmap.maxValue': string; 'heatmap.lowColor': string; 'heatmap.midColor': string; 'heatmap.highColor': string; 'rating.maxStars': string; 'badge.rectangular': string; 'sparkline.minValue': string; 'sparkline.maxValue': string; 'bar.minValue': string; 'bar.maxValue': string; 'bar.barPosition': string; 'avatar.avatarSize': string; 'avatar.rectangular': string; 'avatar-with-text.avatarSize': string; 'avatar-with-text.rectangular': string; 'summary-percentage.maxItems': string; 'summary-aggregate.showSum': string; 'summary-aggregate.showAvg': string; };
  advancedOptionLabels: { 'bar.barPosition.bottom': string; 'bar.barPosition.top': string; };
  expandSection: string;
  collapseSection: string;
  alignmentSection: string;
  horizontal: string;
  vertical: string;
  wrap: string;
  borderSection: string;
  borderStyle: string;
  borderColor: string;
  preview: string;
  previewOriginal: string;
  previewFormatted: string;
  previewHint: string;
  clear: string;
  cancel: string;
  apply: string;
  textExample: string;
  presetLabels: { automatic: string; number: string; currency: string; accounting: string; percent: string; scientific: string; date: string; datetime: string; time: string; text: string; };
  optionLabels: { automatic: string; left: string; center: string; right: string; top: string; middle: string; bottom: string; none: string; solid: string; dashed: string; dotted: string; double: string; short: string; medium: string; long: string; full: string; negativeMinus: string; negativeRed: string; negativeParentheses: string; };
  dataEditor: { chartTitle: string; timelineTitle: string; close: string; preview: string; pointSummary: string; pointsSummary: string; eventSummary: string; eventsSummary: string; value: string; pointValue: string; label: string; start: string; end: string; eventLabel: string; eventStart: string; eventEnd: string; addPoint: string; addEvent: string; deletePoint: string; deleteEvent: string; reorderPoint: string; moveEvent: string; reorderEvent: string; pasteValues: string; pasteHint: string; replaceValues: string; appendValues: string; editRawJson: string; visualEditor: string; rawJsonHint: string; invalidNumber: string; invalidPaste: string; invalidTimeline: string; invalidJson: string; outsideRange: string; emptyPoints: string; emptyEvents: string; cancel: string; apply: string; validationSummary: string; resizeStart: string; resizeEnd: string; };
};
```

---

### `DataGridFormatDialogPlugin`

#### Dependencies

- **Auto-installed** `DialogPlugin`: Uses the shared Pro dialog runtime for Format Cells.

```ts
class DataGridFormatDialogPlugin {
  open(options: DataGridFormattingDialogOpenOptions<T>): void;

  close(): void;
}
```

---

### `createDataGridFormattingEditor`

```ts
export function createDataGridFormattingEditor(
  document: Document,
  options: DataGridFormattingDialogOpenOptions,
  locale: DataGridFormattingLocaleText,
): DataGridFormattingEditor;
```

---

### `DataGridFormattingEditor`

```ts
interface DataGridFormattingEditor {
  readonly element: HTMLElement;
  readonly preview: HTMLElement;
  readonly descriptionId: string;
  getDraft(): DataGridCellFormat;
  isValid(): boolean;
  onValidityChange(listener: (valid: boolean) => void): () => void;
  destroy(): void
}
```

---

### `importDataGridExcelClipboardFormat`

Convert raw Excel HTML declarations into the canonical formatting options.
Clipboard codecs deliberately do not interpret or render these declarations.

```ts
export function importDataGridExcelClipboardFormat(
  declarations: readonly string[],
): DataGridCellFormat | undefined;
```

---

### `exportDataGridExcelClipboardFormat`

Convert canonical formatting options into the Excel HTML representation.

```ts
export function exportDataGridExcelClipboardFormat(
  format: DataGridCellFormat,
): string | undefined;
```

---

### `exportDataGridExcelClipboardValue`

Convert a raw value into Excel HTML's typed value plus canonical display.

```ts
export function exportDataGridExcelClipboardValue(
  value: unknown,
  format: DataGridCellFormat,
);
```

---

### `createDataGridExcelNumberFormat`

Map canonical value-format options to one native Excel number-format code.

```ts
export function createDataGridExcelNumberFormat(
  format: import('../types').DataGridValueFormat,
): string | undefined;
```

---

### `importDataGridExcelClipboardValue`

Convert display-only Excel HTML text into a canonical typed value.

```ts
export function importDataGridExcelClipboardDisplayValue(
  displayText: string,
  format?: DataGridCellFormat,
): unknown;
```

---

### `resolveDataGridAdvancedFormats`

```ts
export function resolveDataGridAdvancedFormats(
  config?: false | DataGridAdvancedFormatsConfig,
): readonly DataGridAdvancedFormatDefinition[];
```

---

### `compatibleDataGridAdvancedFormats`

```ts
export function compatibleDataGridAdvancedFormats<T extends DataType>(
  definitions: readonly DataGridAdvancedFormatDefinition[],
  selection: DataGridFormattingResolvedSelection<T>,
  fallbackKind: DataGridFormattingValueKind = 'unknown',
  resolveValue?: (context: DataGridAdvancedFormatCompatibilityContext) => unknown,
): readonly DataGridAdvancedFormatDefinition[];
```

---

### `isDataGridAdvancedFormatCompatible`

```ts
export function isDataGridAdvancedFormatCompatible(
  definition: DataGridAdvancedFormatDefinition,
  context: DataGridAdvancedFormatCompatibilityContext,
): boolean;
```

---

### `findDataGridAdvancedFormat`

```ts
export function findDataGridAdvancedFormat(
  definitions: readonly DataGridAdvancedFormatDefinition[],
  id: string | undefined,
): DataGridAdvancedFormatDefinition | undefined;
```

---

### `resolveDataGridRendererFormat`

Resolve the authored advanced-format baseline advertised by a cell renderer.

```ts
export function resolveDataGridRendererFormat(
  definitions: readonly DataGridAdvancedFormatDefinition[],
  column: ColumnRegular | undefined,
): DataGridCellFormat | undefined;
```

---

### `dataGridAdvancedAppearanceColorStyle`

Map generic appearance colors either to the cell or renderer-owned variables.

```ts
export function dataGridAdvancedAppearanceColorStyle(
  appearance: DataGridCellFormat['appearance'],
  definition?: DataGridAdvancedFormatDefinition,
  textColor = appearance?.textColor,
): Record<string, string | undefined>;
```

---

### `DATA_GRID_BUILT_IN_ADVANCED_FORMATS`

Cell-capable visualizations shipped with RevoGrid Pro.

```ts
DATA_GRID_BUILT_IN_ADVANCED_FORMATS: readonly DataGridAdvancedFormatDefinition[];
```

---

### `createDataGridValueFormat`

```ts
export function createDataGridValueFormat(
  preset: DataGridValueFormatPreset,
  locale?: string,
  currency = 'USD',
): DataGridCellFormat;
```

---

### `createDataGridCodeFormat`

```ts
export function createDataGridCodeFormat(
  formatCode: string,
  locale?: string,
): DataGridCellFormat;
```

---

### `isDataGridPresetValueFormat`

```ts
export function isDataGridPresetValueFormat(
  format: DataGridValueFormat | undefined,
): format is DataGridPresetValueFormat;
```

---

### `isDataGridCodeValueFormat`

```ts
export function isDataGridCodeValueFormat(
  format: DataGridValueFormat | undefined,
): format is DataGridCodeValueFormat;
```

---

### `inferDataGridFormattingKind`

```ts
export function inferDataGridFormattingKind<T extends DataType>(
  selection: DataGridFormattingResolvedSelection<T>,
  columnTypeKinds: Readonly<Record<string, DataGridFormattingValueKind>> = {},
  resolveValue: DataGridFormattingValueResolver<T> = ({ model, column }) => model[column.prop],
): DataGridFormattingValueKind;
```

---

### `formatDataGridValue`

```ts
export function formatDataGridValue(
  value: unknown,
  format?: DataGridValueFormat,
): string;
```

---

### `formatDataGridExcelCode`

Formats the common Excel custom-number-code families used by HTML clipboard data.

```ts
export function formatDataGridExcelCode(value: unknown, code: string): string;
```

---

### `classifyDataGridValueFormat`

```ts
export function classifyDataGridValueFormat(format?: DataGridValueFormat);
```

---

### `formatDataGridAutomaticValue`

Readable default display for scalar and structured values.

```ts
export function formatDataGridAutomaticValue(value: unknown): string;
```

---

### `isDataGridNumberPreset`

```ts
export function isDataGridNumberPreset(preset: DataGridValueFormatPreset): boolean;
```

---

### `isDataGridDatePreset`

```ts
export function isDataGridDatePreset(preset: DataGridValueFormatPreset): boolean;
```

---

### `normalizeDataGridLocale`

```ts
export function normalizeDataGridLocale(locale?: string): string | undefined;
```

---

### `normalizeDataGridCurrency`

```ts
export function normalizeDataGridCurrency(currency?: string): string;
```

---

### `toDataGridDate`

```ts
export function toDataGridDate(value: unknown): Date | undefined;
```

---

### `DataGridFormattingValueResolver`

```ts
export type DataGridFormattingValueResolver<T extends DataType = DataType> = (
  cell: DataGridFormattingCell<T>,
) => unknown;
```

---

### `compileDataGridFormatCode`

```ts
export function compileDataGridFormatCode(code: string): ParsedDataGridFormatCode;
```

---

### `validateDataGridFormatCode`

```ts
export function validateDataGridFormatCode(code: string): readonly DataGridFormatCodeDiagnostic[];
```

---

### `formatDataGridCodeValue`

```ts
export function formatDataGridCodeValue(
  value: unknown,
  code: string,
  locale?: string,
): DataGridFormattedCodeValue;
```

---

### `classifyDataGridCodeValue`

```ts
export function classifyDataGridCodeValue(code: string);
```

---

### `getDataGridFormatCodeCacheSize`

**@internal** Test hook for proving bounded cache behavior.

```ts
export function getDataGridFormatCodeCacheSize();
```

---

### `MAX_DATA_GRID_FORMAT_CODE_LENGTH`

```ts
MAX_DATA_GRID_FORMAT_CODE_LENGTH: 4096;
```

---

### `DataGridFormatCodeValueKind`

```ts
export type DataGridFormatCodeValueKind = 'number' | 'date' | 'time' | 'text' | 'automatic';
```

---

### `DataGridFormatCodeDiagnostic`

```ts
interface DataGridFormatCodeDiagnostic {
  readonly index: number;
  readonly message: string
}
```

---

### `DataGridFormatCodeSegment`

```ts
export type DataGridFormatCodeSegment =
  | { readonly kind: 'text'; readonly value: string }
  | { readonly kind: 'space'; readonly character: string }
  | { readonly kind: 'fill'; readonly character: string };
```

---

### `DataGridFormattedCodeValue`

```ts
interface DataGridFormattedCodeValue {
  readonly text: string;
  readonly color?: string;
  readonly kind: DataGridFormatCodeValueKind;
  readonly segments: readonly DataGridFormatCodeSegment[]
}
```

---

### `DataGridFormatCodeConditionOperator`

```ts
export type DataGridFormatCodeConditionOperator = '<' | '<=' | '>' | '>=' | '=' | '<>';
```

---

### `DataGridFormatCodeCondition`

```ts
interface DataGridFormatCodeCondition {
  readonly operator: DataGridFormatCodeConditionOperator;
  readonly value: number
}
```

---

### `DataGridFormatCodeToken`

```ts
export type DataGridFormatCodeToken =
  | { readonly kind: 'literal'; readonly value: string }
  | { readonly kind: 'placeholder'; readonly value: string }
  | { readonly kind: 'decimal' }
  | { readonly kind: 'comma' }
  | { readonly kind: 'percent' }
  | { readonly kind: 'fraction' }
  | { readonly kind: 'exponent'; readonly value: string }
  | { readonly kind: 'date'; readonly symbol: 'y' | 'm' | 'd' | 'h' | 's'; readonly length: number }
  | { readonly kind: 'elapsed'; readonly symbol: 'h' | 'm' | 's'; readonly length: number }
  | { readonly kind: 'ampm'; readonly short: boolean }
  | { readonly kind: 'text' }
  | { readonly kind: 'general' }
  | { readonly kind: 'space'; readonly character: string }
  | { readonly kind: 'fill'; readonly character: string }
  | { readonly kind: 'currency'; readonly symbol: string; readonly localeId?: string };
```

---

### `ParsedDataGridFormatCodeSection`

```ts
interface ParsedDataGridFormatCodeSection {
  readonly tokens: readonly DataGridFormatCodeToken[];
  readonly condition?: DataGridFormatCodeCondition;
  readonly color?: string
}
```

---

### `ParsedDataGridFormatCode`

```ts
interface ParsedDataGridFormatCode {
  readonly code: string;
  readonly sections: readonly ParsedDataGridFormatCodeSection[];
  readonly diagnostics: readonly DataGridFormatCodeDiagnostic[]
}
```

---

### `resolveDataGridFormatCodeLocale`

```ts
export function resolveDataGridFormatCodeLocale(
  parsed: ParsedDataGridFormatCode,
): string | undefined;
```

---

### `resolveDataGridFormatSectionLocale`

```ts
export function resolveDataGridFormatSectionLocale(
  section: ParsedDataGridFormatCodeSection,
): string | undefined;
```

---

### `applyDataGridCellFormatPatch`

Merge one public format patch into an effective format.

```ts
export function applyDataGridCellFormatPatch(
  current: DataGridCellFormat | undefined,
  patch: DataGridCellFormatPatch,
): DataGridCellFormat;
```

---

### `formatWithValuePresentation`

Select a value presentation while retaining only the appearance layer.

```ts
export function formatWithValuePresentation(
  current: DataGridCellFormat | undefined,
  value: DataGridCellFormat['value'],
): DataGridCellFormat;
```

---

### `markDataGridFormatRenderer`

Mark a cell renderer as the authored baseline for an advanced format.

The marker is declarative metadata only. It never talks to a grid or plugin
while the renderer runs, so renderers remain pure and safe to reuse.

```ts
export function markDataGridFormatRenderer<T extends CellTemplate>(
  renderer: T,
  presentation: string | DataGridCellPresentation,
): T;
```

---

### `getDataGridFormatRendererPresentation`

Return the advanced-format presentation declared by a renderer, if any.

```ts
export function getDataGridFormatRendererPresentation(
  renderer: CellTemplate | undefined,
): DataGridCellPresentation | undefined;
```

---

### `DATA_GRID_FORMAT_RENDERER`

Public metadata key used by renderers that represent a Format Cells presentation.

```ts
DATA_GRID_FORMAT_RENDERER: typeof DATA_GRID_FORMAT_RENDERER;
```

---

### `isDataGridFormattingRuntimeState`

```ts
export function isDataGridFormattingRuntimeState(
  value: unknown,
): value is DataGridFormattingRuntimeState;
```

---

### `cloneDataGridFormattingRuntimeState`

```ts
export function cloneDataGridFormattingRuntimeState(
  state: DataGridFormattingRuntimeState,
): DataGridFormattingRuntimeState;
```

---

### `DataGridValueFormatPreset`

Public value-format categories supported by the formatting plugin.

```ts
/** Public value-format categories supported by the formatting plugin. */
export type DataGridValueFormatPreset =
  | 'automatic'
  | 'number'
  | 'currency'
  | 'accounting'
  | 'percent'
  | 'scientific'
  | 'date'
  | 'datetime'
  | 'time'
  | 'text';
```

---

### `DataGridFormattingValueKind`

```ts
export type DataGridFormattingValueKind =
  | 'number'
  | 'date'
  | 'text'
  | 'boolean'
  | 'mixed'
  | 'unknown';
```

---

### `DataGridPresetValueFormat`

```ts
interface DataGridPresetValueFormat {
  readonly kind: 'preset';
  readonly preset: DataGridValueFormatPreset;
  readonly locale?: string;
  readonly decimalPlaces?: number;
  readonly useGrouping?: boolean;
  readonly currency?: string;
  readonly dateStyle?: 'short' | 'medium' | 'long' | 'full';
  readonly timeStyle?: 'short' | 'medium' | 'long';
  readonly timeZone?: string;
  readonly negativeStyle?: 'minus' | 'red' | 'parentheses'
}
```

---

### `DataGridCodeValueFormat`

Exact spreadsheet number-format code used by Excel-compatible transports.

```ts
interface DataGridCodeValueFormat {
  readonly kind: 'code';
  readonly formatCode: string;
  /** Locale used when the code does not carry an explicit locale token. */
    readonly locale?: string
}
```

---

### `DataGridValueFormat`

One canonical value-format representation. Presets and exact codes cannot conflict.

```ts
/** One canonical value-format representation. Presets and exact codes cannot conflict. */
export type DataGridValueFormat = DataGridPresetValueFormat | DataGridCodeValueFormat;
```

---

### `DataGridCellBorder`

```ts
interface DataGridCellBorder {
  readonly style: 'none' | 'solid' | 'dashed' | 'dotted' | 'double';
  readonly color?: string;
  readonly width?: number
}
```

---

### `DataGridCellAppearance`

```ts
interface DataGridCellAppearance {
  readonly fontFamily?: string;
  readonly fontSize?: number;
  readonly bold?: boolean;
  readonly italic?: boolean;
  readonly underline?: boolean;
  readonly strike?: boolean;
  readonly textColor?: string;
  readonly fillColor?: string;
  readonly horizontal?: 'automatic' | 'left' | 'center' | 'right' | 'justify';
  readonly vertical?: 'top' | 'middle' | 'bottom';
  readonly wrap?: boolean;
  readonly borderStyle?: 'none' | 'solid' | 'dashed' | 'dotted' | 'double';
  readonly borderColor?: string;
  /** Per-edge borders take precedence over the legacy uniform border fields. */
    readonly borders?: Readonly<Partial<Record<'top' | 'right' | 'bottom' | 'left', DataGridCellBorder>>>;
  readonly indent?: number;
  readonly textRotation?: number;
  readonly shrinkToFit?: boolean
}
```

---

### `DataGridCellPresentation`

A registry-backed cell visualization selected by Format Cells.

```ts
interface DataGridCellPresentation {
  /** Stable built-in or application-defined format id. */
    readonly id: string;
  /** Serializable values consumed by the format definition. */
    readonly options?: Readonly<Record<string, unknown>>
}
```

---

### `DataGridCellFormat`

```ts
interface DataGridCellFormat {
  /** Controls how the raw value is rendered without changing source data. */
    readonly value?: DataGridValueFormat;
  /** Controls typography, colors, alignment, wrapping, and borders. */
    readonly appearance?: DataGridCellAppearance;
  /** Optional advanced visualization such as a progress bar or sparkline. */
    readonly presentation?: DataGridCellPresentation
}
```

---

### `DataGridCellFormatPatch`

A non-destructive update to one effective cell format.

```ts
interface DataGridCellFormatPatch {
  /** Replaces the value layer. `null` removes it. */
    readonly value?: DataGridValueFormat | null;
  /** Merges only the supplied appearance properties. `null` removes the layer. */
    readonly appearance?: Partial<DataGridCellAppearance> | null;
  /** Replaces the advanced presentation. `null` removes it. */
    readonly presentation?: DataGridCellPresentation | null
}
```

---

### `DataGridFormattingPatchTarget`

Per-target context supplied to a runtime format patch resolver.

```ts
interface DataGridFormattingPatchTarget {
  readonly current?: DataGridCellFormat;
  readonly model?: T;
  readonly column: ColumnRegular;
  readonly rowType?: DimensionRows
}
```

---

### `DataGridFormattingPatchResolver`

```ts
export type DataGridFormattingPatchResolver<T extends DataType = DataType> = (
  target: DataGridFormattingPatchTarget<T>,
) => DataGridCellFormatPatch;
```

---

### `DataGridAdvancedFormatValueKind`

```ts
export type DataGridAdvancedFormatValueKind =
  | 'number'
  | 'boolean'
  | 'text'
  | 'scalar'
  | 'numberArray'
  | 'pieArray'
  | 'timelineArray'
  | 'summaryRecord';
```

---

### `DataGridAdvancedFormatCompatibilityContext`

```ts
interface DataGridAdvancedFormatCompatibilityContext {
  readonly value: unknown;
  readonly model?: DataType;
  readonly column?: ColumnRegular;
  readonly rowType?: DimensionRows
}
```

---

### `DataGridAdvancedFormatControl`

```ts
export type DataGridAdvancedFormatControl =
  | {
      readonly type: 'number';
      readonly key: string;
      readonly label: string;
      readonly min?: number;
      readonly max?: number;
      readonly step?: number;
    }
  | {
      readonly type: 'boolean';
      readonly key: string;
      readonly label: string;
    }
  | {
      readonly type: 'select';
      readonly key: string;
      readonly label: string;
      readonly options: readonly { readonly value: string; readonly label: string }[];
    }
  | {
      readonly type: 'color';
      readonly key: string;
      readonly label: string;
    };
```

---

### `DataGridAdvancedFormatAppearanceSections`

```ts
interface DataGridAdvancedFormatAppearanceSections {
  /** Whether generic text/fill color controls apply to this renderer. */
    readonly colors?: boolean;
  /**
     * Routes generic appearance colors into renderer-owned CSS custom properties
     * instead of painting the complete cell.
     */
    readonly colorVariables?: {
      readonly text?: `--${string}`;
      readonly fill?: `--${string}`;
    }
}
```

---

### `DataGridAdvancedFormatEditorContext`

Runtime context available to advanced-format structured editor factories.

```ts
interface DataGridAdvancedFormatEditorContext {
  readonly schema: ColumnDataSchemaModel;
  readonly format?: DataGridCellFormat;
  readonly presentation: DataGridAdvancedFormatDefinition;
  readonly localeText: DataGridFormattingLocaleText;
  readonly revogrid: HTMLRevoGridElement;
  readonly providers: PluginProviders;
  readonly save: (value?: unknown, preventFocus?: boolean) => void;
  readonly close: (focusNext?: boolean) => void
}
```

---

### `DataGridAdvancedFormatEditorFactory`

```ts
export type DataGridAdvancedFormatEditorFactory = (
  context: DataGridAdvancedFormatEditorContext,
) => EditorBase;
```

---

### `DataGridAdvancedFormatExportContext`

Context passed to an advanced presentation's workbook export formatter.

```ts
interface DataGridAdvancedFormatExportContext {
  /** Raw source value rendered by the presentation. */
    readonly value: unknown;
  /** Source row that owns the exported cell. */
    readonly model: DataType;
  /** Column that owns the exported cell. */
    readonly column: ColumnRegular;
  /** Body or pinned-row segment containing the source row. */
    readonly rowType: DimensionRows;
  /** Complete effective cell format. */
    readonly format: DataGridCellFormat;
  /** Definition defaults merged with the selected presentation options. */
    readonly options: Readonly<Record<string, unknown>>
}
```

---

### `DataGridAdvancedFormatExportValue`

```ts
export type DataGridAdvancedFormatExportValue =
  | string
  | number
  | boolean
  | Date
  | null
  | undefined;
```

---

### `DataGridAdvancedFormatExportFormatter`

Produces a workbook-safe scalar value for an advanced presentation.

```ts
/** Produces a workbook-safe scalar value for an advanced presentation. */
export type DataGridAdvancedFormatExportFormatter = (
  context: DataGridAdvancedFormatExportContext,
) => DataGridAdvancedFormatExportValue;
```

---

### `DataGridAdvancedFormatDefinition`

Public registry entry for a built-in override or custom advanced format.

```ts
interface DataGridAdvancedFormatDefinition {
  readonly id: string;
  readonly label: string;
  readonly description?: string;
  readonly group?: string;
  readonly order?: number;
  readonly icon?: string;
  /**
     * Renderer applied by this presentation. Use `markDataGridFormatRenderer`
     * when the same renderer is also authored directly on columns and should be
     * recognized as their Format Cells baseline.
     */
    readonly cellTemplate: CellTemplate;
  /** Optional provider-free renderer used by the detached Format Cells preview. */
    readonly previewTemplate?: CellTemplate;
  /** Keeps intrinsic preview content from stretching to the preview cell height. */
    readonly previewLayout?: 'fill' | 'intrinsic';
  /** Shorthand compatibility used by the built-in catalog. */
    readonly valueKind?: DataGridAdvancedFormatValueKind;
  /** Custom compatibility predicate. It must be true for every selected value. */
    readonly isCompatible?: (
      context: DataGridAdvancedFormatCompatibilityContext,
    ) => boolean;
  readonly defaults?: Readonly<Record<string, unknown>>;
  readonly controls?: readonly DataGridAdvancedFormatControl[];
  /** Generic appearance sections supported by this presentation. */
    readonly appearanceSections?: DataGridAdvancedFormatAppearanceSections;
  /** Optional editor used only when this presentation is effective for a cell. */
    readonly editor?: EditorCtr | string;
  /** Context-aware editor factory. Preferred over `editor` when supplied. */
    readonly editorFactory?: DataGridAdvancedFormatEditorFactory;
  /**
     * Converts structured presentation data to a workbook-safe scalar value.
     * Source data is not modified.
     */
    readonly exportValue?: DataGridAdvancedFormatExportFormatter;
  /** Native Excel number format applied when this presentation is effective. */
    readonly excelNumberFormat?: string;
  /** Allows this definition to replace an authored cell template. */
    readonly replaceAuthoredTemplate?: boolean;
  /** Allows this definition to replace an authored editor. */
    readonly replaceAuthoredEditor?: boolean
}
```

---

### `DataGridAdvancedFormatOverride`

```ts
interface DataGridAdvancedFormatOverride {
  readonly label?: string;
  readonly description?: string;
  readonly defaults?: Readonly<Record<string, unknown>>;
  readonly controls?: readonly DataGridAdvancedFormatControl[];
  readonly appearanceSections?: DataGridAdvancedFormatAppearanceSections;
  readonly previewTemplate?: CellTemplate;
  readonly editor?: EditorCtr | string;
  readonly editorFactory?: DataGridAdvancedFormatEditorFactory;
  readonly exportValue?: DataGridAdvancedFormatExportFormatter;
  readonly excelNumberFormat?: string;
  readonly replaceAuthoredTemplate?: boolean;
  readonly replaceAuthoredEditor?: boolean
}
```

---

### `DataGridFormatContext`

```ts
interface DataGridFormatContext {
  readonly model: T;
  readonly value: unknown;
  readonly prop: P;
  readonly rowType?: DimensionRows
}
```

---

### `DataGridFormatDefinition`

```ts
export type DataGridFormatDefinition<
  T extends DataType = DataType,
  P extends ColumnProp = ColumnProp,
> =
  | DataGridCellFormat
  | ((context: DataGridFormatContext<T, P>) => DataGridCellFormat | undefined);
```

---

### `CellCoordinate`

A zero-based cell coordinate in physical row and column source stores.

```ts
interface CellCoordinate {
  /** Physical index in the selected row type's `source` array. */
    readonly row: number;
  /** Physical index in the selected column type's `source` array. */
    readonly column: number
}
```

---

### `PhysicalCellAddress` (Extended from `index.ts`)

A physical cell coordinate qualified by its row and column source stores.

```ts
interface PhysicalCellAddress {
  /** Row source containing the cell. Defaults to `rgRow`. */
    readonly rowType?: DimensionRows;
  /** Column source containing the cell. Defaults to `rgCol`. */
    readonly colType?: DimensionCols
}
```

---

### `PhysicalColumnAddress`

A physical column coordinate qualified by its source store.

```ts
interface PhysicalColumnAddress {
  readonly column: number;
  /** Column source containing the column. Defaults to `rgCol`. */
    readonly colType?: DimensionCols
}
```

---

### `PhysicalRowAddress`

A physical row coordinate qualified by its source store.

```ts
interface PhysicalRowAddress {
  readonly row: number;
  /** Row source containing the row. Defaults to `rgRow`. */
    readonly rowType?: DimensionRows
}
```

---

### `PhysicalColumnRange`

An inclusive range of complete columns in one physical column source.

```ts
interface PhysicalColumnRange {
  /** First physical column index. */
    readonly start: number;
  /** Inclusive last physical column index. Defaults to `start`. */
    readonly end?: number;
  /** Column source containing the target. Defaults to `rgCol`. */
    readonly colType?: DimensionCols
}
```

---

### `PhysicalRowRange`

An inclusive range of complete rows in one physical row source.

```ts
interface PhysicalRowRange {
  /** First physical row index. */
    readonly start: number;
  /** Inclusive last physical row index. Defaults to `start`. */
    readonly end?: number;
  /** Row source containing the target. Defaults to `rgRow`. */
    readonly rowType?: DimensionRows
}
```

---

### `PhysicalCellRange`

A rectangular target expressed by inclusive physical source coordinates.

```ts
interface PhysicalCellRange {
  /** First physical source coordinate. */
    readonly start: CellCoordinate;
  /** Inclusive opposite corner. Defaults to `start`; reversed corners are normalized. */
    readonly end?: CellCoordinate;
  /** Row source containing the target. Defaults to `rgRow`. */
    readonly rowType?: DimensionRows;
  /** Column source containing the target. Defaults to `rgCol`. */
    readonly colType?: DimensionCols
}
```

---

### `DataGridFormattingSelection`

One physical range, or several independent/overlapping physical ranges.

```ts
/** One physical range, or several independent/overlapping physical ranges. */
export type DataGridFormattingSelection =
  | PhysicalCellRange
  | readonly PhysicalCellRange[];
```

---

### `DataGridFormattingColumnSelection`

Complete-column formatting target, including rows added in the future.

```ts
interface DataGridFormattingColumnSelection {
  readonly scope: 'columns';
  readonly ranges: PhysicalColumnRange | readonly PhysicalColumnRange[]
}
```

---

### `DataGridFormattingRowSelection`

Complete-row formatting target, including columns added in the future.

```ts
interface DataGridFormattingRowSelection {
  readonly scope: 'rows';
  readonly ranges: PhysicalRowRange | readonly PhysicalRowRange[]
}
```

---

### `DataGridFormattingTarget`

Coordinate-only target accepted by formatting mutation and dialog APIs.

```ts
/** Coordinate-only target accepted by formatting mutation and dialog APIs. */
export type DataGridFormattingTarget =
  | DataGridFormattingSelection
  | DataGridFormattingColumnSelection
  | DataGridFormattingRowSelection;
```

---

### `DataGridFormattingColumnPreset` (Extended from `index.ts`)

```ts
interface DataGridFormattingColumnPreset {
  /** Format applied to cells in the column. */
    readonly format: DataGridCellFormat
}
```

---

### `DataGridFormattingRowPreset` (Extended from `index.ts`)

```ts
interface DataGridFormattingRowPreset {
  /** Format applied to cells in the row. */
    readonly format: DataGridCellFormat
}
```

---

### `DataGridFormattingCellPreset`

```ts
interface DataGridFormattingCellPreset {
  /** Physical range receiving the declarative format. */
    readonly range: PhysicalCellRange;
  readonly format: DataGridCellFormat
}
```

---

### `DataGridFormattingRuntimeColumnState` (Extended from `index.ts`)

One persisted runtime formatting operation for a complete column.

```ts
interface DataGridFormattingRuntimeColumnState {
  /** `null` preserves an explicit Clear formatting operation. */
    readonly format: DataGridCellFormat | null;
  /** Monotonic operation order used for cell/row/column precedence. */
    readonly revision: number
}
```

---

### `DataGridFormattingRuntimeRowState` (Extended from `index.ts`)

One persisted runtime formatting operation for a complete row.

```ts
interface DataGridFormattingRuntimeRowState {
  /** `null` preserves an explicit Clear formatting operation. */
    readonly format: DataGridCellFormat | null;
  /** Monotonic operation order used for row/column/cell precedence. */
    readonly revision: number
}
```

---

### `DataGridFormattingRuntimeCellState` (Extended from `index.ts`)

One persisted runtime formatting operation for a physical cell.

```ts
interface DataGridFormattingRuntimeCellState {
  readonly rowType?: DimensionRows;
  readonly colType?: DimensionCols;
  /** `null` preserves an explicit Clear formatting operation. */
    readonly format: DataGridCellFormat | null;
  /** Monotonic operation order used for cell/row/column precedence. */
    readonly revision: number
}
```

---

### `DataGridFormattingRuntimeState`

Versioned coordinate state for formats created through the dialog or plugin API.

```ts
interface DataGridFormattingRuntimeState {
  readonly version: 3;
  readonly revision: number;
  readonly columns: readonly DataGridFormattingRuntimeColumnState[];
  readonly rows: readonly DataGridFormattingRuntimeRowState[];
  readonly cells: readonly DataGridFormattingRuntimeCellState[]
}
```

---

### `DataGridFormattingChangeSource`

Why a runtime formatting state changed.

```ts
/** Why a runtime formatting state changed. */
export type DataGridFormattingChangeSource =
  | 'apply'
  | 'clear'
  | 'set-state'
  | 'history'
  | 'autofill'
  | 'structure';
```

---

### `DataGridFormattingChangeEvent`

Complete application-facing payload emitted after a runtime formatting change.

```ts
interface DataGridFormattingChangeEvent {
  /** Complete state to persist. */
    readonly state: DataGridFormattingRuntimeState;
  /** Complete state before this operation, used by HistoryPlugin. */
    readonly previousState: DataGridFormattingRuntimeState;
  /** Operation that produced the state. */
    readonly source: DataGridFormattingChangeSource
}
```

---

### `DataGridFormattingHistoryRuntime`

Runtime contract used by HistoryPlugin to replay formatting entries.

```ts
interface DataGridFormattingHistoryRuntime {
  applyHistoryState(state: DataGridFormattingRuntimeState): boolean;
  /** @internal Prevent coordinate remapping while a structural snapshot is replayed. */
    beginHistoryStructureReplay?(): void;
  /** @internal Resume ordinary structural coordinate reconciliation. */
    endHistoryStructureReplay?(): void;
  /** @internal Flush a partially applied structural context-menu transaction. */
    flushPendingStructuralTransaction?(transactionId: number): void
}
```

---

### `DataGridFormattingPresetState`

Declarative formats and optional runtime state assigned through
`grid.dataGridFormatting`. Reassign the property to replace presets
reactively. Applications own persistence and can restore a state received
from `datagridformattingchange` through the `state` property.

Cell presets are physical ranges, so replacing source objects does not
require row identity configuration.

```ts
interface DataGridFormattingPresetState {
  readonly columns?: readonly DataGridFormattingColumnPreset[];
  readonly rows?: readonly DataGridFormattingRowPreset[];
  readonly cells?: readonly DataGridFormattingCellPreset[];
  /** Runtime Apply and Clear operations previously emitted by the plugin. */
    readonly state?: DataGridFormattingRuntimeState
}
```

---

### `DataGridFormattingResolvedSelection`

**@internal** Model-backed target resolved from coordinates or UI selection.

```ts
interface DataGridFormattingResolvedSelection {
  /** Whether the operation targets explicit cells, complete rows, or complete columns. */
    readonly scope: 'cells' | 'rows' | 'columns';
  /** Columns included in the operation. */
    readonly columns: readonly ColumnRegular[];
  /** Exact cell targets. Required when `scope` is `cells`. */
    readonly cells: readonly DataGridFormattingCell<T>[];
  /** Useful for type resolution and dialog preview in column scope. */
    readonly rows: readonly T[];
  /** Physical row addresses retained for complete-row storage operations. */
    readonly rowAddresses?: readonly Required<PhysicalRowAddress>[]
}
```

---

### `DataGridFormattingCell`

```ts
interface DataGridFormattingCell {
  /** Source row containing the cell. */
    readonly model: T;
  /** Column containing the cell. */
    readonly column: ColumnRegular;
  /** Body or pinned-row dimension containing the cell. */
    readonly rowType?: DimensionRows;
  /** Physical address resolved for coordinate-owned formatting storage. */
    readonly address?: PhysicalCellAddress
}
```

---

### `DataGridFormattingConfig` (Extended from `index.ts`)

```ts
interface DataGridFormattingConfig {
  /** Overrides automatic value-kind inference for the complete selection. */
    readonly resolveValueKind?: (
      selection: DataGridFormattingResolvedSelection<T>,
    ) => DataGridFormattingValueKind;
  /** Maps application column-type names to formatting value kinds. */
    readonly columnTypeKinds?: Readonly<Record<string, DataGridFormattingValueKind>>;
  /** Context-menu surfaces allowed to create formatting selections. */
    readonly scopes?: readonly ('cell' | 'columnHeader')[];
  /**
     * Column properties whose active column-owned format takes precedence over
     * cell and row formatting without removing that lower-level state.
     */
    readonly protectedColumnProps?: readonly ColumnProp[];
  /**
     * Stable application identity used to retain formatting when a
     * length-changing source update replaces row objects immutably.
     */
    readonly resolveStructuralRowIdentity?: (
      model: T,
      context: { readonly row: number; readonly rowType: DimensionRows },
    ) => unknown;
  /** Advanced visual formats and format-resolved editors. `false` disables them. */
    readonly advancedFormats?: false | DataGridAdvancedFormatsConfig
}
```

---

### `DataGridFormattingLocaleText`

```ts
interface DataGridFormattingLocaleText {
  readonly title: string;
  readonly close: string;
  readonly description: string;
  readonly selectionSummary: string;
  readonly selectionCells: string;
  readonly selectionColumns: string;
  readonly valueSection: string;
  readonly advancedSection: string;
  readonly advancedNone: string;
  readonly advancedDescription: string;
  readonly automaticDescription: string;
  readonly numberSection: string;
  readonly category: string;
  readonly locale: string;
  readonly browserDefault: string;
  readonly decimals: string;
  readonly grouping: string;
  readonly currency: string;
  readonly negativeNumbers: string;
  readonly dateStyle: string;
  readonly timeStyle: string;
  readonly custom: string;
  readonly formatCode: string;
  readonly invalidFormatCode: string;
  readonly fontSection: string;
  readonly typographySection: string;
  readonly colorsSection: string;
  readonly fontFamily: string;
  readonly defaultFont: string;
  readonly fontSize: string;
  readonly bold: string;
  readonly italic: string;
  readonly underline: string;
  readonly strike: string;
  readonly textColor: string;
  readonly fillColor: string;
  readonly useTextColor: string;
  readonly useFillColor: string;
  readonly defaultColor: string;
  readonly noFill: string;
  readonly customColor: string;
  readonly customColorHex: string;
  readonly invalidColor: string;
  readonly colorLabels: Readonly<Record<string, string>>;
  /** Labels for registry groups, keyed by the definition's `group` value. */
    readonly advancedGroupLabels: Readonly<Record<string, string>>;
  /** Advanced-format names keyed by stable format id. */
    readonly advancedFormatLabels: Readonly<Record<string, string>>;
  /** Advanced-format descriptions keyed by stable format id. */
    readonly advancedFormatDescriptions: Readonly<Record<string, string>>;
  /** Control labels keyed as `<format id>.<control key>`. */
    readonly advancedControlLabels: Readonly<Record<string, string>>;
  /** Select-option labels keyed as `<format id>.<control key>.<option value>`. */
    readonly advancedOptionLabels: Readonly<Record<string, string>>;
  readonly expandSection: string;
  readonly collapseSection: string;
  readonly alignmentSection: string;
  readonly horizontal: string;
  readonly vertical: string;
  readonly wrap: string;
  readonly borderSection: string;
  readonly borderStyle: string;
  readonly borderColor: string;
  readonly preview: string;
  readonly previewOriginal: string;
  readonly previewFormatted: string;
  readonly previewHint: string;
  readonly clear: string;
  readonly cancel: string;
  readonly apply: string;
  readonly textExample: string;
  readonly presetLabels: Record<DataGridValueFormatPreset, string>;
  readonly optionLabels: DataGridFormattingOptionLocaleText;
  readonly dataEditor: DataGridFormattingDataEditorLocaleText
}
```

---

### `DataGridFormattingDataEditorLocaleText`

```ts
export type DataGridFormattingDataEditorLocaleText = StructuredDataEditorLocaleText;
```

---

### `DataGridFormattingOptionLocaleText`

```ts
interface DataGridFormattingOptionLocaleText {
  readonly automatic: string;
  readonly left: string;
  readonly center: string;
  readonly right: string;
  readonly top: string;
  readonly middle: string;
  readonly bottom: string;
  readonly none: string;
  readonly solid: string;
  readonly dashed: string;
  readonly dotted: string;
  readonly double: string;
  readonly short: string;
  readonly medium: string;
  readonly long: string;
  readonly full: string;
  readonly negativeMinus: string;
  readonly negativeRed: string;
  readonly negativeParentheses: string
}
```

---

### `DataGridFormattingDialogConfig`

```ts
interface DataGridFormattingDialogConfig {
  /** Right-align numeric values and numeric presets when horizontal alignment is automatic. Defaults to true. */
    readonly autoAlignNumericValues?: boolean;
  readonly locale?: string;
  /** Locale choices shown in the Format Cells dialog. Common US and European locales are used by default. */
    readonly locales?: readonly string[];
  readonly currencies?: readonly string[];
  readonly fontFamilies?: readonly string[];
  readonly localeText?: Partial<Omit<
      DataGridFormattingLocaleText,
      | 'presetLabels'
      | 'optionLabels'
      | 'colorLabels'
      | 'advancedGroupLabels'
      | 'advancedFormatLabels'
      | 'advancedFormatDescriptions'
      | 'advancedControlLabels'
      | 'advancedOptionLabels'
      | 'dataEditor'
    >> & {
      readonly presetLabels?: Partial<DataGridFormattingLocaleText['presetLabels']>;
      readonly optionLabels?: Partial<DataGridFormattingOptionLocaleText>;
      readonly colorLabels?: Readonly<Record<string, string>>;
      readonly advancedGroupLabels?: Readonly<Record<string, string>>;
      readonly advancedFormatLabels?: Readonly<Record<string, string>>;
      readonly advancedFormatDescriptions?: Readonly<Record<string, string>>;
      readonly advancedControlLabels?: Readonly<Record<string, string>>;
      readonly advancedOptionLabels?: Readonly<Record<string, string>>;
      readonly dataEditor?: Partial<DataGridFormattingDataEditorLocaleText>;
    }
}
```

---

### `DataGridFormattingDialogOpenOptions` (Extended from `index.ts`)

```ts
interface DataGridFormattingDialogOpenOptions {
  readonly selection: DataGridFormattingResolvedSelection<T>;
  readonly initialValue?: DataGridCellFormat;
  readonly sampleValue?: unknown;
  readonly valueKind: DataGridFormattingValueKind;
  /** False when selected columns cannot safely replace their visual value presentation. */
    readonly valueFormatting?: boolean;
  /** Resolved compatible advanced-format catalog for this selection. */
    readonly advancedFormatDefinitions?: readonly DataGridAdvancedFormatDefinition[];
  readonly onApply: (format: DataGridCellFormat) => void;
  readonly onClear: () => void
}
```

---

### `createAutofillFormattingEntries`

```ts
export function createAutofillFormattingEntries({
  providers,
  owner,
  oldRange,
  newRange,
  rowType,
  colType,
}: {
  providers: PluginProviders;
  owner: Pick<AutofillFormattingOwner, 'getFormat'>;
  oldRange: RangeArea;
  newRange: RangeArea;
  rowType: DimensionRows;
  colType: DimensionCols;
}): AutofillFormattingBatchEntry[];
```

---

### `AutofillFormattingBatchEntry`

```ts
interface AutofillFormattingBatchEntry {
  readonly target: DataGridFormattingTarget;
  readonly format: DataGridCellFormat | undefined
}
```

---

### `AutofillFormattingController`

Couples accepted range edits to formatting without moving value generation
out of Core or AutoFillPlugin.

```ts
class AutofillFormattingController {
  destroy(): void;
}
```

---

### `applyDataGridFormattingRender`

Compose formatting into one core before-cell-render schema.

```ts
export function applyDataGridFormattingRender<T extends DataType>(
  event: CustomEvent<HTMLRevogrDataElementEventMap['beforecellrender']>,
  context: DataGridFormattingRenderContext<T>,
): void;
```

---

### `DataGridFormattingRenderContext`

```ts
interface DataGridFormattingRenderContext {
  readonly providers: PluginProviders;
  readonly config: Readonly<DataGridFormattingConfig<T>>;
  readonly advancedFormatDefinitions: readonly DataGridAdvancedFormatDefinition[];
  readonly resolveCellValue: (
      model: T,
      column: ColumnRegular,
      rowType?: DimensionRows,
      value?: unknown,
    ) => unknown;
  readonly resolveFormat: (
      address: PhysicalCellAddress,
      column?: ColumnRegular,
      model?: T,
      value?: unknown,
      includeRenderer?: boolean,
    ) => DataGridCellFormat | undefined;
  readonly resolveAuthoredFormat: (
      column: ColumnRegular,
      model?: T,
      value?: unknown,
      rowType?: DimensionRows,
      includeRenderer?: boolean,
    ) => DataGridCellFormat | undefined
}
```

---

### `StoredDataGridFormat`

```ts
interface StoredDataGridFormat {
  readonly revision: number;
  readonly value?: DataGridCellFormat
}
```

---

### `DataGridFormattingStructuralRemapResult`

```ts
interface DataGridFormattingStructuralRemapResult {
  readonly runtimeChanged: boolean;
  readonly presetsChanged: boolean
}
```

---

### `resolveDataGridFormattingSelection`

Resolve public physical coordinates into the plugin's model-backed target.

```ts
export function resolveDataGridFormattingSelection<T extends DataType>(
  target: DataGridFormattingTarget,
  providers: PluginProviders,
): DataGridFormattingResolvedSelection<T> | undefined;
```

---

### `expandPhysicalColumnSelection`

Expand and deduplicate complete-column coordinate ranges.

```ts
export function expandPhysicalColumnSelection(
  target: Extract<DataGridFormattingTarget, { scope: 'columns' }>,
): Required<PhysicalColumnAddress>[];
```

---

### `expandPhysicalRowSelection`

Expand and deduplicate complete-row coordinate ranges.

```ts
export function expandPhysicalRowSelection(
  target: Extract<DataGridFormattingTarget, { scope: 'rows' }>,
): Required<PhysicalRowAddress>[];
```

---

### `resolvedFormattingSelectionToTarget`

Convert an internal model-backed UI selection to the public coordinate target.

```ts
export function resolvedFormattingSelectionToTarget<T extends DataType>(
  selection: DataGridFormattingResolvedSelection<T>,
  providers: PluginProviders,
): DataGridFormattingTarget | undefined;
```

---

### `expandPhysicalFormattingSelection`

Expand and deduplicate physical ranges without consulting current grid data.

```ts
export function expandPhysicalFormattingSelection(
  target: DataGridFormattingSelection,
): Required<PhysicalCellAddress>[];
```

---

### `resolvePhysicalFormattingCell`

Resolve a physical address to its current model and column context.

```ts
export function resolvePhysicalFormattingCell<T extends DataType>(
  providers: PluginProviders,
  address: PhysicalCellAddress,
): DataGridFormattingCell<T> | undefined;
```

---

### `resolvePhysicalFormattingAddress`

Resolve transient render/editor models to their current physical source address.

```ts
export function resolvePhysicalFormattingAddress<T extends DataType>(
  providers: PluginProviders,
  model: T,
  column: ColumnRegular,
  rowType: DimensionRows = 'rgRow',
  colType?: DimensionCols,
): PhysicalCellAddress | undefined;
```

---

### `resolvePhysicalFormattingColumn`

Resolve a column object to its physical source address.

```ts
export function resolvePhysicalFormattingColumn(
  providers: PluginProviders,
  column: ColumnRegular,
  preferredType?: DimensionCols,
): PhysicalColumnAddress | undefined;
```

---

### `resolvePhysicalFormattingRow`

Resolve a row object to its physical source address.

```ts
export function resolvePhysicalFormattingRow<T extends DataType>(
  providers: PluginProviders,
  model: T,
  preferredType?: DimensionRows,
): PhysicalRowAddress | undefined;
```

---

### `visibleCellToPhysicalFormattingAddress`

Translate a rendered virtual cell into a physical address.

```ts
export function visibleCellToPhysicalFormattingAddress(
  providers: PluginProviders,
  {
    row,
    column,
    rowType = 'rgRow',
    colType = 'rgCol',
  }: PhysicalCellAddress,
): PhysicalCellAddress | undefined;
```

---

### `visibleRangeToPhysicalFormattingSelection`

Convert one visible range into physical formatting coordinates.

```ts
export function visibleRangeToPhysicalFormattingSelection(
  providers: PluginProviders,
  range: {
    readonly x: number;
    readonly y: number;
    readonly x1: number;
    readonly y1: number;
    readonly rowType?: DimensionRows;
    readonly colType?: DimensionCols;
  },
): DataGridFormattingSelection;
```

---

### `AdvancedFormatPanel`

```ts
export function AdvancedFormatPanel({
  definitions,
  presentation,
  locale,
  localeText,
  onChange,
}: {
  readonly definitions: readonly DataGridAdvancedFormatDefinition[];
  readonly presentation?: DataGridCellPresentation;
  readonly locale: DataGridFormattingLocaleText;
  readonly localeText?: DataGridFormattingDialogConfig['localeText'];
  readonly onChange: (value: DataGridCellPresentation | undefined) => void;
});
```

---

### `AlignmentSection`

```ts
export function AlignmentSection({ appearance, locale, onChange }: SectionProps);
```

---

### `AppearancePanel`

```ts
export function AppearancePanel({ appearance, sections, options, locale, onChange }: {
  readonly appearance: DataGridCellAppearance;
  readonly sections?: DataGridAdvancedFormatAppearanceSections;
  readonly options: DataGridFormattingDialogOpenOptions;
  readonly locale: DataGridFormattingLocaleText;
  readonly onChange: (value: DataGridCellAppearance) => void;
});
```

---

### `BordersSection`

```ts
export function BordersSection({ appearance, locale, onChange }: SectionProps);
```

---

### `FormattingColorPicker`

```ts
export function FormattingColorPicker({
  label,
  value,
  defaultLabel,
  customLabel,
  customHexLabel,
  invalidColor,
  colorLabels,
  optional = true,
  onChange,
}: {
  readonly label: string;
  readonly value?: string;
  readonly defaultLabel: string;
  readonly customLabel: string;
  readonly customHexLabel: string;
  readonly invalidColor: string;
  readonly colorLabels: Readonly<Record<string, string>>;
  readonly optional?: boolean;
  readonly onChange: (value: string | undefined) => void;
});
```

---

### `normalizeHexColor`

```ts
export function normalizeHexColor(value: string | undefined): string | undefined;
```

---

### `ColorsSection`

```ts
export function ColorsSection({ appearance, locale, onChange }: SectionProps);
```

---

### `useControlTooltip`

```ts
export function useControlTooltip(text: string);
```

---

### `ControlTooltip`

```ts
export function ControlTooltip({ id, text, visible }: {
  readonly id: string;
  readonly text: string;
  readonly visible: boolean;
});
```

---

### `FormatPreview`

```ts
export function FormatPreview({
  sampleValue,
  format,
  locale,
  advancedFormatDefinitions,
  autoAlignNumericValues,
}: {
  readonly sampleValue: unknown;
  readonly format: DataGridCellFormat;
  readonly locale: DataGridFormattingLocaleText;
  readonly advancedFormatDefinitions?: readonly DataGridAdvancedFormatDefinition[];
  readonly autoAlignNumericValues: boolean;
});
```

---

### `FormatIcon`

```ts
export function FormatIcon({ icon, className = 'rv-format-icon' }: {
  readonly icon: string;
  readonly className?: string;
});
```

---

### `FORMAT_ICONS`

```ts
FORMAT_ICONS: { readonly accounting: string; readonly alignCenter: string; readonly alignLeft: string; readonly alignRight: string; readonly arrowLeft: string; readonly arrowRight: string; readonly automatic: string; readonly ban: string; readonly bold: string; readonly border: string; readonly calendar: string; readonly chevronDown: string; readonly clock: string; readonly currency: string; readonly ellipsis: string; readonly eraser: string; readonly fill: string; readonly italic: string; readonly number: string; readonly palette: string; readonly percent: string; readonly scientific: string; readonly sliders: string; readonly strike: string; readonly text: string; readonly underline: string; readonly verticalBottom: string; readonly verticalMiddle: string; readonly verticalTop: string; readonly wrap: string; };
```

---

### `ADVANCED_FORMAT_ICONS`

```ts
ADVANCED_FORMAT_ICONS: { readonly progressLine: string; readonly progressWithValue: string; readonly circularProgress: string; readonly heatmap: string; readonly rating: string; readonly change: string; readonly threshold: string; readonly thumbs: string; readonly badge: string; readonly sparkline: string; readonly bar: string; readonly pie: string; readonly timeline: string; readonly avatar: string; readonly avatarWithText: string; readonly summaryPercentage: string; readonly summaryAggregate: string; };
```

---

### `InspectorSection`

```ts
export function InspectorSection({
  title,
  icon,
  locale,
  open = false,
  children,
}: {
  readonly title: string;
  readonly icon: string;
  readonly locale: DataGridFormattingLocaleText;
  readonly open?: boolean;
  readonly children: ComponentChildren;
});
```

---

### `resolveDataGridFormattingLocaleOptions`

```ts
export function resolveDataGridFormattingLocaleOptions(
  configuredLocales?: readonly string[],
  selectedLocale?: string,
): readonly DataGridFormattingLocaleOption[];
```

---

### `DataGridFormattingLocaleOption`

```ts
interface DataGridFormattingLocaleOption {
  readonly value: string;
  readonly label: string
}
```

---

### `DEFAULT_DATA_GRID_FORMATTING_LOCALES`

```ts
DEFAULT_DATA_GRID_FORMATTING_LOCALES: readonly string[];
```

---

### `formatLocaleTemplate`

```ts
export function formatLocaleTemplate(
  template: string,
  values: Readonly<Record<string, string>>,
): string;
```

---

### `DataGridFormattingEditorRuntime`

Owns editor proxy installation and effective editor construction.

```ts
class DataGridFormattingEditorRuntime {
  install(collection: ColumnCollection): void;

  installCurrent(): void;
}
```

---

### `SegmentedControl`

```ts
export function SegmentedControl<Value extends string>({
  value,
  options,
  ariaLabel,
  onChange,
}: {
  readonly value: Value;
  readonly options: readonly SegmentedOption<Value>[];
  readonly ariaLabel: string;
  readonly onChange: (value: Value) => void;
});
```

---

### `ToggleIconButton`

```ts
export function ToggleIconButton({
  value,
  label,
  icon,
  onChange,
}: {
  readonly value: boolean;
  readonly label: string;
  readonly icon: string;
  readonly onChange: (value: boolean) => void;
});
```

---

### `SegmentedOption`

```ts
interface SegmentedOption {
  readonly value: Value;
  readonly label: string;
  readonly icon: string
}
```

---

### `TypographySection`

```ts
export function TypographySection({ appearance, options, locale, onChange }: SectionProps);
```

---

### `SectionProps`

```ts
interface SectionProps {
  readonly appearance: DataGridCellAppearance;
  readonly options: DataGridFormattingDialogOpenOptions;
  readonly locale: DataGridFormattingLocaleText;
  readonly onChange: (value: Partial<DataGridCellAppearance>) => void
}
```

---

### `ValueFormatPanel`

```ts
export function ValueFormatPanel({
  value,
  presentation,
  options,
  locale,
  onChange,
  onValidityChange,
  onPresentationChange,
}: {
  readonly value: DataGridValueFormat;
  readonly presentation?: DataGridCellPresentation;
  readonly options: DataGridFormattingDialogOpenOptions;
  readonly locale: DataGridFormattingLocaleText;
  readonly onChange: (value: DataGridValueFormat) => void;
  readonly onValidityChange: (valid: boolean) => void;
  readonly onPresentationChange: (value: DataGridCellPresentation | undefined) => void;
});
```

---

### `ValueFormatPresets`

```ts
export function ValueFormatPresets({
  value,
  formatLocale,
  currency,
  locale,
  advancedAvailable,
  onChange,
}: {
  readonly value: FormatCategory;
  readonly formatLocale?: string;
  readonly currency?: string;
  readonly locale: DataGridFormattingLocaleText;
  readonly advancedAvailable: boolean;
  readonly onChange: (value: FormatCategory) => void;
});
```

---

### `FormatCategory`

```ts
export type FormatCategory = DataGridValueFormatPreset | 'custom' | 'advanced';
```

---

### `resolveDataGridHorizontalAlignment`

Chooses the horizontal alignment that a formatted cell should display.

Explicit `left`, `center`, and `right` appearance values always win. When
alignment is omitted or `automatic`, ordinary numeric values and numeric
presets resolve to `right`. An active advanced presentation keeps control of
its own layout unless the user explicitly selected an alignment.

This function only calculates the effective value. It does not modify the
cell format, source value, column, or persisted formatting state.

**@param** options Cell value and formatting context used to resolve alignment.

**@returns** The alignment to apply, or `undefined` when the existing cell or
presentation layout should remain unchanged.

```ts
export function resolveDataGridHorizontalAlignment(
  options: {
    /** Raw cell value before display formatting. */
    readonly value: unknown;
    /** Effective cell format, including value preset and authored appearance. */
    readonly format?: DataGridCellFormat;
    /** Whether omitted or Automatic alignment may be derived from numeric data. */
    readonly autoAlignNumericValues?: boolean;
    /** True when an active advanced renderer owns the cell's visual layout. */
    readonly hasEffectivePresentation?: boolean;
  },
): DataGridHorizontalAlignment | undefined;
```

---

### `isDataGridNumericValue`

Reports whether a raw cell value participates in automatic numeric alignment.

Finite JavaScript numbers and all bigint values are numeric. `NaN`, positive
or negative infinity, numeric strings, and boxed numbers are intentionally
excluded so their existing grid alignment is preserved.

**@param** value Raw source value to classify.

**@returns** `true` when automatic numeric alignment may apply to the value.

```ts
export function isDataGridNumericValue(value: unknown): boolean;
```

---

### `structuralAddressKey`

```ts
export function structuralAddressKey<T extends string>(type: T, index: number): string;
```

---

### `createRowStructuralMap`

Match retained records by identity, including duplicate references, then
preserve coordinates for a same-size immutable source replacement.

```ts
export function createRowStructuralMap(
  previous: Readonly<Record<DimensionRows, readonly DataType[]>>,
  next: Readonly<Record<DimensionRows, readonly DataType[]>>,
  fallbackIdentity?: (
    row: DataType,
    address: StructuralAddress<DimensionRows>,
  ) => unknown,
): StructuralAddressMap<DimensionRows>;
```

---

### `createColumnStructuralMap`

Match columns by identity and fall back to their stable data property.

```ts
export function createColumnStructuralMap(
  previous: Readonly<Record<DimensionCols, readonly ColumnRegular[]>>,
  next: Readonly<Record<DimensionCols, readonly ColumnRegular[]>>,
): StructuralAddressMap<DimensionCols>;
```

---

### `StructuralAddress`

```ts
interface StructuralAddress {
  readonly type: T;
  readonly index: number
}
```

---

### `StructuralAddressMap`

```ts
export type StructuralAddressMap<T extends string> = ReadonlyMap<
  string,
  StructuralAddress<T>
>;
```

---

### `FORMATTING_ROW_TYPES`

```ts
FORMATTING_ROW_TYPES: readonly DimensionRows[];
```

---

### `FORMATTING_COLUMN_TYPES`

```ts
FORMATTING_COLUMN_TYPES: readonly DimensionCols[];
```

---

### `normalizeFormattingCellAddress`

```ts
export function normalizeFormattingCellAddress(
  address: PhysicalCellAddress,
): Required<PhysicalCellAddress>;
```

---

### `normalizeFormattingColumnAddress`

```ts
export function normalizeFormattingColumnAddress(
  address: PhysicalColumnAddress,
): Required<PhysicalColumnAddress>;
```

---

### `normalizeFormattingRowAddress`

```ts
export function normalizeFormattingRowAddress(
  address: PhysicalRowAddress,
): Required<PhysicalRowAddress>;
```

---

### `formattingCellAddressKey`

```ts
export function formattingCellAddressKey(address: PhysicalCellAddress): string;
```

---

### `formattingColumnAddressKey`

```ts
export function formattingColumnAddressKey(address: PhysicalColumnAddress): string;
```

---

### `formattingRowAddressKey`

```ts
export function formattingRowAddressKey(address: PhysicalRowAddress): string;
```

---

### `DEFAULT_FORMATTING_ROW_TYPE`

```ts
DEFAULT_FORMATTING_ROW_TYPE: DimensionRows;
```

---

### `DEFAULT_FORMATTING_COLUMN_TYPE`

```ts
DEFAULT_FORMATTING_COLUMN_TYPE: DimensionCols;
```

---

### `evaluateDataGridFormatCode`

```ts
export function evaluateDataGridFormatCode(
  parsed: ParsedDataGridFormatCode,
  value: unknown,
  locale?: string,
): DataGridFormattedCodeValue;
```

---

### `classifyDataGridFormatCode`

```ts
export function classifyDataGridFormatCode(
  parsed: ParsedDataGridFormatCode,
): DataGridFormattedCodeValue['kind'];
```

---

### `parseDataGridFormatCode`

```ts
export function parseDataGridFormatCode(code: string): ParsedDataGridFormatCode;
```

---

### `importDataGridExcelClipboardDisplayValue`

Convert display-only Excel HTML text into a canonical typed value.

```ts
export function importDataGridExcelClipboardDisplayValue(
  displayText: string,
  format?: DataGridCellFormat,
): unknown;
```

---

### `normalizeExcelLanguage`

```ts
export function normalizeExcelLanguage(value?: string): string | undefined;
```

---

### `normalizeExcelNamedNumberFormat`

```ts
export function normalizeExcelNamedNumberFormat(
  value: string | undefined,
  language?: string,
): NormalizedExcelNumberFormat;
```

---

### `NormalizedExcelNumberFormat`

```ts
interface NormalizedExcelNumberFormat {
  readonly formatCode?: string;
  readonly locale?: string
}
```

---

# Data Grid Formatting Panel

URL: https://pro.rv-grid.com/api/data-grid-formatting-panel/
Source: src/content/docs/api/data-grid-formatting-panel.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /** Reactive opt-in single-row formatting toolbar configuration. */
      dataGridFormattingPanel?: DataGridFormattingPanelSetting;
  'data-grid-formatting-panel'?: DataGridFormattingPanelSetting
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /** @deprecated Prefer `grid.dataGridFormattingPanel`. */
      dataGridFormattingPanel?: DataGridFormattingPanelSetting
}
```

## Plugin API

### `resolveDataGridFormattingPanelSelection`

```ts
export function resolveDataGridFormattingPanelSelection<T extends DataType>(
  revogrid: HTMLRevoGridElement,
  providers: PluginProviders,
  headerColumn?: ColumnRegular,
): DataGridFormattingResolvedSelection<T> | undefined;
```

---

### `selectionFormats`

```ts
export function selectionFormats<T extends DataType>(
  formatting: DataGridFormattingPlugin<T>,
  providers: PluginProviders,
  selection?: DataGridFormattingResolvedSelection<T>,
): (DataGridCellFormat | undefined)[];
```

---

### `commonAppearance`

```ts
export function commonAppearance(
  formats: readonly (DataGridCellFormat | undefined)[],
): FormattingPanelAppearance;
```

---

### `commonValueFormat`

```ts
export function commonValueFormat(
  formats: readonly (DataGridCellFormat | undefined)[],
): FormattingPanelValueFormat;
```

---

### `common`

```ts
export function common<T>(values: readonly (T | undefined)[]): MixedValue<T>;
```

---

### `numericPreset`

```ts
export function numericPreset(value?: DataGridValueFormatPreset): DataGridValueFormatPreset;
```

---

### `stepNumericValueFormat`

```ts
export function stepNumericValueFormat(
  current: DataGridPresetValueFormat | undefined,
  base: DataGridPresetValueFormat,
  direction: -1 | 1,
): DataGridPresetValueFormat;
```

---

### `MixedValue`

```ts
export type MixedValue<T> = T | 'mixed' | undefined;
```

---

### `FormattingPanelValueCategory`

```ts
export type FormattingPanelValueCategory = DataGridValueFormatPreset | 'advanced';
```

---

### `FormattingPanelValueFormat`

```ts
interface FormattingPanelValueFormat {
  readonly category: MixedValue<FormattingPanelValueCategory>;
  readonly presentationId?: string
}
```

---

### `FormattingPanelAppearance`

```ts
interface FormattingPanelAppearance {
  readonly fontFamily: MixedValue<DataGridCellAppearance['fontFamily']>;
  readonly fontSize: MixedValue<DataGridCellAppearance['fontSize']>;
  readonly bold: MixedValue<DataGridCellAppearance['bold']>;
  readonly italic: MixedValue<DataGridCellAppearance['italic']>;
  readonly underline: MixedValue<DataGridCellAppearance['underline']>;
  readonly strike: MixedValue<DataGridCellAppearance['strike']>;
  readonly textColor: MixedValue<DataGridCellAppearance['textColor']>;
  readonly fillColor: MixedValue<DataGridCellAppearance['fillColor']>;
  readonly horizontal: MixedValue<DataGridCellAppearance['horizontal']>;
  readonly vertical: MixedValue<DataGridCellAppearance['vertical']>;
  readonly wrap: MixedValue<DataGridCellAppearance['wrap']>;
  readonly borderStyle: MixedValue<DataGridCellAppearance['borderStyle']>;
  readonly borderColor: MixedValue<DataGridCellAppearance['borderColor']>
}
```

---

### `DataGridFormattingPanel`

```ts
export function DataGridFormattingPanel<T extends DataType>({
  formatting,
  selection,
  target,
  providers,
  panelLocale,
  buttons,
}: DataGridFormattingPanelProps<T>);
```

---

### `resolveDataGridFormattingPanelLocale`

```ts
export function resolveDataGridFormattingPanelLocale(
  value?: Partial<DataGridFormattingPanelLocaleText>,
): DataGridFormattingPanelLocaleText;
```

---

### `DataGridFormattingPanelLocaleText`

```ts
interface DataGridFormattingPanelLocaleText {
  readonly toolbar: string;
  readonly mixed: string;
  readonly more: string;
  readonly decreaseDecimals: string;
  readonly increaseDecimals: string;
  readonly formatCells: string
}
```

---

### `DataGridFormattingPanelButtonContext`

Runtime state supplied to an application-owned formatting-panel button.

```ts
interface DataGridFormattingPanelButtonContext {
  readonly formatting: DataGridFormattingPlugin<T>;
  readonly providers: PluginProviders;
  readonly selection?: DataGridFormattingResolvedSelection<T>;
  readonly target?: DataGridFormattingTarget;
  /** True when the panel has no writable formatting target. */
    readonly disabled: boolean;
  /** Definition resolved from `presentationId`, when one is registered. */
    readonly presentation?: DataGridAdvancedFormatDefinition
}
```

---

### `DataGridFormattingPanelButtonState`

```ts
export type DataGridFormattingPanelButtonState<T extends DataType, TValue> =
  | TValue
  | ((context: DataGridFormattingPanelButtonContext<T>) => TValue);
```

---

### `DataGridFormattingPanelButton`

Application-owned action or registered-format shortcut shown in the toolbar.

```ts
interface DataGridFormattingPanelButton {
  /** Stable key used for rendering and application styling hooks. */
    readonly id: string;
  /** Accessible label. Falls back to the registered presentation label, then `id`. */
    readonly label?: string;
  /** Trusted raw SVG markup. Falls back to the registered presentation icon. */
    readonly icon?: string;
  /** Optional caption rendered beside the icon. */
    readonly visibleLabel?: string;
  readonly className?: string;
  /** Registered advanced-format shortcut applied when `onClick` is omitted. */
    readonly presentationId?: string;
  readonly presentationOptions?: Readonly<Record<string, unknown>>;
  /** Defaults to the panel's selection-disabled state. */
    readonly disabled?: DataGridFormattingPanelButtonState<T, boolean>;
  /** Presentation shortcuts infer pressed state from the active format. */
    readonly pressed?: DataGridFormattingPanelButtonState<T, boolean | 'mixed'>;
  /** Custom action. When supplied, it takes precedence over `presentationId`. */
    readonly onClick?: (context: DataGridFormattingPanelButtonContext<T>) => void
}
```

---

### `DataGridFormattingPanelConfig`

```ts
interface DataGridFormattingPanelConfig {
  readonly localeText?: Partial<DataGridFormattingPanelLocaleText>;
  /**
     * Application toolbar actions. Fonts and advanced-format definitions are
     * inherited from the shared `DataGridFormattingPlugin` configuration.
     */
    readonly buttons?: readonly DataGridFormattingPanelButton<T>[]
}
```

---

### `DataGridFormattingPanelSetting`

Reactive formatting-panel setting. Omitted and `false` are disabled.

```ts
/** Reactive formatting-panel setting. Omitted and `false` are disabled. */
export type DataGridFormattingPanelSetting<T extends DataType = DataType> =
  | boolean
  | DataGridFormattingPanelConfig<T>;
```

---

### `DATA_GRID_FORMATTING_PANEL_LOCALE`

```ts
DATA_GRID_FORMATTING_PANEL_LOCALE: {
  toolbar: string;
  mixed: string;
  more: string;
  decreaseDecimals: string;
  increaseDecimals: string;
  formatCells: string;
};
```

---

### `DataGridFormattingPanelPlugin`

One-line spreadsheet formatting toolbar for the active RevoGrid selection.
Its runtime is installed with `DataGridFormattingPlugin`, but the toolbar is
disabled until `grid.dataGridFormattingPanel` is set to `true` or a config.
Fonts and advanced formats come from the shared formatting configuration;
application buttons can run callbacks or reference a registered presentation.

**Example: Custom format shortcut using shared label and icon metadata**
```typescript
grid.dataGridContextMenu = { formatting: {
  fontFamilies: ['Inter', 'IBM Plex Mono'],
  advancedFormats: { customFormats: [riskFormat] },
} };
grid.dataGridFormattingPanel = {
  buttons: [{ id: 'risk', presentationId: riskFormat.id }],
};
```

#### Dependencies

- **Auto-installed** `DataGridFormattingPlugin`: Applies toolbar commands through DataGridFormattingPlugin.
- **Event integration** `focuscell`, `setrange`, `headerclick`: Tracks active cell ranges and whole-column header selections.

```ts
class DataGridFormattingPanelPlugin {}
```

---

### `AppearanceControls`

```ts
export function AppearanceControls({ appearance, locale, disabled, onAppearance }: {
  readonly appearance: FormattingPanelAppearance;
  readonly locale: DataGridFormattingLocaleText;
  readonly disabled: boolean;
  readonly onAppearance: (patch: Partial<DataGridCellAppearance>) => void;
});
```

---

### `horizontalOptions`

```ts
export function horizontalOptions(locale: DataGridFormattingLocaleText);
```

---

### `verticalOptions`

```ts
export function verticalOptions(locale: DataGridFormattingLocaleText);
```

---

### `borderOptions`

```ts
export function borderOptions(locale: DataGridFormattingLocaleText);
```

---

### `Divider`

```ts
export function Divider({ className = '' }: { readonly className?: string });
```

---

### `IconButton`

```ts
export function IconButton({
  label,
  icon,
  visibleLabel,
  className = '',
  disabled,
  pressed,
  expanded,
  onClick,
}: IconButtonProps);
```

---

### `TextIconButton`

```ts
export function TextIconButton({ label, text, icon, disabled, onClick }: {
  readonly label: string;
  readonly text: string;
  readonly icon: string;
  readonly disabled?: boolean;
  readonly onClick: () => void;
});
```

---

### `ToggleButton`

```ts
export function ToggleButton({ value, onChange, ...props }: Omit<IconButtonProps, 'pressed' | 'onClick'> & {
  readonly value: MixedValue<boolean>;
  readonly onChange: (value: boolean) => void;
});
```

---

### `IconSelect`

```ts
export function IconSelect({ label, value, options, icon, disabled, className = '', onChange }: {
  readonly label: string;
  readonly value: MixedValue<string>;
  readonly options: readonly (readonly string[])[];
  readonly icon: string;
  readonly disabled?: boolean;
  readonly className?: string;
  readonly onChange: (value: string) => void;
});
```

---

### `CompactColorPicker`

```ts
export function CompactColorPicker({ label, icon, value, locale, disabled, onChange }: {
  readonly label: string;
  readonly icon: string;
  readonly value: MixedValue<string>;
  readonly locale: DataGridFormattingLocaleText;
  readonly disabled?: boolean;
  readonly onChange: (value: string | undefined) => void;
});
```

---

### `horizontalIcon`

```ts
export function horizontalIcon(value: MixedValue<DataGridCellAppearance['horizontal']>): string;
```

---

### `verticalIcon`

```ts
export function verticalIcon(value: MixedValue<DataGridCellAppearance['vertical']>): string;
```

---

### `IconButtonProps`

```ts
interface IconButtonProps {
  readonly label: string;
  readonly icon: string;
  readonly visibleLabel?: string;
  readonly className?: string;
  readonly disabled?: boolean;
  readonly pressed?: boolean | 'mixed';
  readonly expanded?: boolean;
  readonly onClick: () => void
}
```

---

### `CustomFormattingButtons`

```ts
export function CustomFormattingButtons<T extends DataType>({
  buttons,
  formatting,
  selection,
  target,
  providers,
  disabled,
  activePresentationId,
}: {
  readonly buttons: readonly DataGridFormattingPanelButton<T>[];
  readonly formatting: DataGridFormattingPlugin<T>;
  readonly selection?: DataGridFormattingResolvedSelection<T>;
  readonly target?: DataGridFormattingTarget;
  readonly providers: PluginProviders;
  readonly disabled: boolean;
  readonly activePresentationId?: string;
});
```

---

### `FormattingPanelOverflow`

```ts
export function FormattingPanelOverflow({
  appearance,
  locale,
  panelLocale,
  fonts,
  disabled,
  onAppearance,
  onFormatCells,
}: {
  readonly appearance: FormattingPanelAppearance;
  readonly locale: DataGridFormattingLocaleText;
  readonly panelLocale: DataGridFormattingPanelLocaleText;
  readonly fonts: readonly string[];
  readonly disabled: boolean;
  readonly onAppearance: (patch: Partial<DataGridCellAppearance>) => void;
  readonly onFormatCells: () => void;
});
```

---

### `TypographyControls`

```ts
export function TypographyControls({
  appearance,
  locale,
  panelLocale,
  fonts,
  disabled,
  onAppearance,
}: {
  readonly appearance: FormattingPanelAppearance;
  readonly locale: DataGridFormattingLocaleText;
  readonly panelLocale: DataGridFormattingPanelLocaleText;
  readonly fonts: readonly string[];
  readonly disabled: boolean;
  readonly onAppearance: (patch: Partial<DataGridCellAppearance>) => void;
});
```

---

### `FontFamilyOptions`

```ts
export function FontFamilyOptions({ value, fonts, defaultLabel, mixedLabel }: {
  readonly value: FormattingPanelAppearance['fontFamily'];
  readonly fonts: readonly string[];
  readonly defaultLabel: string;
  readonly mixedLabel: string;
});
```

---

### `FontSizeInput`

```ts
export function FontSizeInput({ value, disabled, onChange }: {
  readonly value: FormattingPanelAppearance['fontSize'];
  readonly disabled: boolean;
  readonly onChange: (value: number | undefined) => void;
});
```

---

### `ValueFormatControls`

```ts
export function ValueFormatControls({
  category,
  advancedLabel,
  valueKind,
  locale,
  panelLocale,
  disabled,
  canFormatValue,
  onPreset,
  onAdjustDecimals,
}: {
  readonly category: MixedValue<FormattingPanelValueCategory>;
  readonly advancedLabel: string;
  readonly valueKind: DataGridFormattingValueKind;
  readonly locale: DataGridFormattingLocaleText;
  readonly panelLocale: DataGridFormattingPanelLocaleText;
  readonly disabled: boolean;
  readonly canFormatValue: boolean;
  readonly onPreset: (preset: DataGridValueFormatPreset) => void;
  readonly onAdjustDecimals: (direction: -1 | 1) => void;
});
```

---

# Dates

URL: https://pro.rv-grid.com/api/dates/
Source: src/content/docs/api/dates.md

### `parseIsoDate`

Parses date-only strings at UTC midnight instead of local midnight.
Datetime strings are delegated to the JavaScript `Date` parser.

```ts
export function parseIsoDate(date: string): Date;
```

---

### `parseLocalDateValue`

Parses grid-facing date values while preserving local calendar semantics for
date-only strings. JSON-quoted strings cover normalized selection keys for
Date-valued cells.

```ts
export function parseLocalDateValue(value: unknown): Date | undefined;
```

---

### `parseIsoDateOnly`

Parses the `YYYY-MM-DD` prefix of a date or datetime at UTC midnight.

```ts
export function parseIsoDateOnly(value: string): Date;
```

---

### `isIsoDateTimeInput`

```ts
export function isIsoDateTimeInput(value: string): boolean;
```

---

### `getIsoWeekdayUtc`

```ts
export function getIsoWeekdayUtc(date: Date): number;
```

---

### `getUtcWeekday`

```ts
export function getUtcWeekday(value: string | Date): number;
```

---

### `getIsoWeekday`

```ts
export function getIsoWeekday(value: string | Date): number;
```

---

### `isValidIsoWeekday`

```ts
export function isValidIsoWeekday(value: number): boolean;
```

---

### `formatIsoDate`

```ts
export function formatIsoDate(date: Date): ISODateString;
```

---

### `formatIsoDateInTimeZone`

Serializes the calendar date containing an instant in the requested IANA timezone.

```ts
export function formatIsoDateInTimeZone(date: Date, timeZone: string): ISODateString;
```

---

### `formatLocalIsoDateTimeInTimeZone`

Serializes an instant as a timezone-local value accepted by `datetime-local` controls.

```ts
export function formatLocalIsoDateTimeInTimeZone(date: Date, timeZone: string): string;
```

---

### `formatLocalIsoDate`

Serializes the local calendar fields of a valid `Date` as `YYYY-MM-DD`.

```ts
export function formatLocalIsoDate(value: Date): ISODateString;
```

---

### `toLocalIsoDate`

Returns local calendar fields as `YYYY-MM-DD`, or `null` for a missing/invalid date.

```ts
export function toLocalIsoDate(value: Date | undefined): ISODateString | null;
```

---

### `formatIsoDateTime`

```ts
export function formatIsoDateTime(date: Date): ISODateTimeString;
```

---

### `isValidIsoDate`

```ts
export function isValidIsoDate(value: string | undefined): value is ISODateString;
```

---

### `isValidIsoDateTime`

```ts
export function isValidIsoDateTime(value: string | undefined): value is ISODateTimeString;
```

---

### `isValidIsoDateValue`

Validates either a date-only ISO value or a UTC datetime value.
Date-only values must round-trip as `YYYY-MM-DD`; datetimes must round-trip
exactly through `toISOString()`.

```ts
export function isValidIsoDateValue(value: string | undefined): value is ISODateString;
```

---

### `normalizeIsoDate`

Returns a valid `YYYY-MM-DD` value or throws with a user-facing message.

```ts
export function normalizeIsoDate(value: string): ISODateString;
```

---

### `parseDateTime`

Parses scheduler datetime input as UTC.
Values without a trailing `Z` are treated as UTC, not local time.

```ts
export function parseDateTime(value: string): Date;
```

---

### `toISODate`

```ts
export function toISODate(date: Date): ISODateString;
```

---

### `toIsoDate`

```ts
export function toIsoDate(date: Date): ISODateString;
```

---

### `ISODateString`

```ts
export type ISODateString = `${number}-${number}-${number}` | `${number}-${number}-${number}T${string}`;
```

---

### `ISODateTimeString`

```ts
export type ISODateTimeString = `${number}-${number}-${number}T${string}`;
```

---

### `ISO_DATE_ONLY_PATTERN`

```ts
ISO_DATE_ONLY_PATTERN: RegExp;
```

---

### `ISO_DATE_PATTERN`

```ts
ISO_DATE_PATTERN: RegExp;
```

---

### `ISO_DATE_PREFIX_PATTERN`

```ts
ISO_DATE_PREFIX_PATTERN: RegExp;
```

---

### `ISO_DATETIME_PATTERN`

```ts
ISO_DATETIME_PATTERN: RegExp;
```

---

### `ISO_DATETIME_INPUT_PATTERN`

```ts
ISO_DATETIME_INPUT_PATTERN: RegExp;
```

---

### `ISO_LOCAL_DATETIME_INPUT_PATTERN`

```ts
ISO_LOCAL_DATETIME_INPUT_PATTERN: RegExp;
```

---

### `ISO_UTC_DATETIME_WITHOUT_ZONE_PATTERN`

```ts
ISO_UTC_DATETIME_WITHOUT_ZONE_PATTERN: RegExp;
```

---

### `coerceValidDate`

Converts a supported scalar into a cloned, valid `Date`.

```ts
export function coerceValidDate(value: unknown): Date | undefined;
```

---

### `formatLocalDateControlValue`

Formats local `Date` fields for native date, datetime-local, and time controls.

```ts
export function formatLocalDateControlValue(
  kind: LocalDateControlKind,
  date: Date,
): string;
```

---

### `parseLocalDateControlValue`

Parses native date, datetime-local, and time control values as local time.
Returns `undefined` when the syntax or calendar value is invalid.

```ts
export function parseLocalDateControlValue(
  kind: LocalDateControlKind,
  value: string,
  baseDate: Date = new Date(),
): Date | undefined;
```

---

### `LocalDateControlKind`

```ts
export type LocalDateControlKind = 'date' | 'datetime' | 'time';
```

---

### `resolveSpreadsheetDateOrder`

Resolve the conventional spreadsheet date order for a BCP 47 locale.

```ts
export function resolveSpreadsheetDateOrder(locale: string): SpreadsheetDateOrder;
```

---

### `usesSpreadsheetTwelveHourClock`

Resolve whether a locale conventionally displays spreadsheet times in 12-hour form.

```ts
export function usesSpreadsheetTwelveHourClock(locale: string): boolean;
```

---

### `coerceSpreadsheetDate`

Coerces spreadsheet date values into local calendar fields.
Numeric values use Excel's 1900 date system, including its skipped serial 60.

```ts
export function coerceSpreadsheetDate(value: unknown): Date | undefined;
```

---

### `excelSerialToSpreadsheetDate`

Converts an Excel 1900-system serial into a local spreadsheet date.

```ts
export function excelSerialToSpreadsheetDate(serial: number): Date | undefined;
```

---

### `excelSerialToSpreadsheetDateParts`

Resolves Excel 1900-system serial fields without losing serial 60. This is
intended for spreadsheet number-format evaluation where 1900-02-29 must be
displayed exactly even though JavaScript `Date` cannot represent it.

```ts
export function excelSerialToSpreadsheetDateParts(
  serial: number,
): SpreadsheetDateParts | undefined;
```

---

### `spreadsheetDateToExcelSerial`

Converts local spreadsheet calendar fields into an Excel 1900-system serial.

```ts
export function spreadsheetDateToExcelSerial(value: Date): number | undefined;
```

---

### `spreadsheetDateToExcelSerialInTimeZone`

Converts the calendar fields displayed in a timezone into an Excel serial.

```ts
export function spreadsheetDateToExcelSerialInTimeZone(
  value: Date,
  timeZone: string,
): number | undefined;
```

---

### `parseSpreadsheetDateDisplay`

Parses a locale-displayed spreadsheet date without relying on JavaScript's
implementation-defined non-ISO string parser.

```ts
export function parseSpreadsheetDateDisplay(
  value: string,
  order: SpreadsheetDateOrder,
  locale?: string,
): Date | undefined;
```

---

### `parseSpreadsheetDateTimeDisplay`

Parse browser-visible spreadsheet date/time text into an Excel day serial.

```ts
export function parseSpreadsheetDateTimeDisplay(
  value: string,
  options: SpreadsheetDisplayDateTimeOptions,
): number | undefined;
```

---

### `SpreadsheetDateOrder`

```ts
export type SpreadsheetDateOrder = 'mdy' | 'dmy' | 'ymd';
```

---

### `SpreadsheetDateParts`

```ts
interface SpreadsheetDateParts {
  readonly year: number;
  /** One-based calendar month. */
    readonly month: number;
  readonly day: number;
  /** Sunday is zero, matching `Date#getDay`. */
    readonly weekday: number;
  readonly hour: number;
  readonly minute: number;
  readonly second: number;
  readonly millisecond: number;
  readonly elapsedHours: number;
  readonly elapsedMinutes: number;
  readonly elapsedSeconds: number;
  /** Excel's intentionally fictional 1900-02-29. */
    readonly fictionalLeapDay: boolean
}
```

---

### `SpreadsheetDisplayDateTimeOptions`

```ts
interface SpreadsheetDisplayDateTimeOptions {
  readonly dateOrder?: SpreadsheetDateOrder;
  readonly locale?: string;
  readonly hasDate?: boolean;
  readonly hasTime?: boolean;
  /** Leading elapsed unit for formats such as `[h]:mm:ss`. */
    readonly elapsedUnit?: 'h' | 'm' | 's'
}
```

---

### `addDays`

Adds calendar days using UTC math.
Datetime inputs preserve datetime output; date-only inputs return date-only output.

```ts
export function addDays(date: string, days: number): ISODateString;
```

---

### `subtractDays`

```ts
export function subtractDays(date: string, days: number): ISODateString;
```

---

### `addHours`

```ts
export function addHours(date: string, hours: number): ISODateTimeString;
```

---

### `addMinutes`

```ts
export function addMinutes(date: string, minutes: number): ISODateTimeString;
```

---

### `addMonths`

```ts
export function addMonths(date: string, months: number): ISODateString;
```

---

### `addCalendarMonths`

Adds calendar months while preserving the day-of-month, clamped to the target month.

```ts
export function addCalendarMonths(date: string, months: number): ISODateString;
```

---

### `diffInDays`

```ts
export function diffInDays(startDate: string, endDate: string): number;
```

---

### `diffInCalendarDays`

```ts
export function diffInCalendarDays(startDate: string, endDate: string): number;
```

---

### `diffInTaskDuration`

Returns the Gantt duration between two task dates.
Date-only ranges are inclusive; datetime ranges use elapsed days and keep a
non-zero positive duration at one minute minimum.

```ts
export function diffInTaskDuration(startDate: string, endDate: string): number;
```

---

### `diffInHours`

```ts
export function diffInHours(startDate: string, endDate: string): number;
```

---

### `diffInMinutes`

```ts
export function diffInMinutes(startDate: string, endDate: string): number;
```

---

### `compareIsoDates`

```ts
export function compareIsoDates(left: string, right: string): number;
```

---

### `isBefore`

```ts
export function isBefore(left: string, right: string): boolean;
```

---

### `isAfter`

```ts
export function isAfter(left: string, right: string): boolean;
```

---

### `minDate`

```ts
export function minDate(left: string, right: string): ISODateString;
```

---

### `maxDate`

```ts
export function maxDate(left: string, right: string): ISODateString;
```

---

### `getOccupiedDateRange`

Resolves the calendar dates occupied by a half-open datetime range
`[startDateTime, endDateTime)`. A zero or inverted range remains on the
start date so callers can handle invalid duration separately.

```ts
export function getOccupiedDateRange(
  startDateTime: string,
  endDateTime: string,
): ISODateRange;
```

---

### `shiftDate`

```ts
export function shiftDate(date: string, deltaDays: number): ISODateString;
```

---

### `shiftDateRange`

```ts
export function shiftDateRange<T extends ISODateRange>(range: T, deltaDays: number): T;
```

---

### `shiftDateRanges`

```ts
export function shiftDateRanges<T extends ISODateRange>(
  ranges: readonly T[] | undefined,
  deltaDays: number,
): readonly T[] | undefined;
```

---

### `startOfWeek`

```ts
export function startOfWeek(date: string): ISODateString;
```

---

### `startOfMonth`

```ts
export function startOfMonth(date: string): ISODateString;
```

---

### `endOfMonth`

Returns the final UTC calendar date in the month containing `date`.

```ts
export function endOfMonth(date: string): ISODateString;
```

---

### `createCompletedMonthDateList`

Returns every date needed to render a natural four-to-six-week month grid,
including the leading and trailing dates from adjacent months.

```ts
export function createCompletedMonthDateList(
  date: string,
  weekStartsOn: number,
): readonly ISODateString[];
```

---

### `startOfQuarter`

```ts
export function startOfQuarter(date: string): ISODateString;
```

---

### `startOfYear`

```ts
export function startOfYear(date: string): ISODateString;
```

---

### `endOfYear`

```ts
export function endOfYear(date: string): ISODateString;
```

---

### `getWeekStartIsoDate`

Returns the UTC Monday for the week containing `date`.

```ts
export function getWeekStartIsoDate(date: Date): ISODateString;
```

---

### `getMonthStartIsoDate`

```ts
export function getMonthStartIsoDate(date: Date): ISODateString;
```

---

### `getIsoWeekNumber`

```ts
export function getIsoWeekNumber(date: Date): number;
```

---

### `todayIsoDate`

```ts
export function todayIsoDate(): ISODateString;
```

---

### `createDateList`

Returns an inclusive date list and throws when the range is invalid.

```ts
export function createDateList(
  startDate: string,
  endDate: string,
  options: { readonly maxDays?: number; readonly rangeLabel?: string } = {},
): readonly ISODateString[];
```

---

### `createSafeDateList`

Returns an inclusive date list or `[]` for invalid input.
Use this when remote/user data should not throw during projection.

```ts
export function createSafeDateList(startDate: string, endDate: string): readonly ISODateString[];
```

---

### `rangesOverlap`

Tests overlap for half-open numeric ranges: `[start, end)` and `[rangeStart, rangeEnd)`.

```ts
export function rangesOverlap(start: number, end: number, rangeStart: number, rangeEnd: number): boolean;
```

---

### `startOfUtcDayMs`

Returns the UTC midnight timestamp for the date containing `value`.

```ts
export function startOfUtcDayMs(value: string | number | Date): number;
```

---

### `getDateDayBounds`

Returns the half-open UTC day bounds `[startMs, endMs)` for a date.

```ts
export function getDateDayBounds(date: string): { readonly startMs: number; readonly endMs: number };
```

---

### `getDateRangeBounds`

Returns half-open UTC bounds for an inclusive date range.

```ts
export function getDateRangeBounds(range: ISODateBoundsRange): { readonly startMs: number; readonly endMs: number };
```

---

### `MINUTE_IN_MS`

```ts
MINUTE_IN_MS: number;
```

---

### `HOUR_IN_MS`

```ts
HOUR_IN_MS: number;
```

---

### `DAY_IN_MS`

```ts
DAY_IN_MS: number;
```

---

### `WEEK_IN_MS`

```ts
WEEK_IN_MS: number;
```

---

### `MINUTE_IN_DAYS`

```ts
MINUTE_IN_DAYS: number;
```

---

### `ISODateRange`

```ts
interface ISODateRange {
  readonly startDate: ISODateString;
  readonly endDate: ISODateString
}
```

---

### `ISODateBoundsRange`

```ts
interface ISODateBoundsRange {
  readonly start: string;
  readonly end: string
}
```

---

### `resolveDurationSettings`

```ts
export function resolveDurationSettings(
  settings: DurationSettings | undefined,
  calendar?: Pick<CalendarEntity, 'hoursPerDay' | 'workingDays'> | null,
): ResolvedDurationSettings;
```

---

### `parseDuration`

```ts
export function parseDuration(
  input: unknown,
  options?: ParseDurationOptions,
): ParsedDuration | null;
```

---

### `hasDurationUnitToken`

Returns true when text explicitly contains a unit rather than a bare number.

```ts
export function hasDurationUnitToken(input: unknown): boolean;
```

---

### `durationToWorkingDays`

```ts
export function durationToWorkingDays(
  value: number,
  unit: DurationUnit,
  settings: ResolvedDurationSettings,
): number;
```

---

### `durationToHours`

Converts a displayed duration magnitude into canonical stored working hours.

```ts
export function durationToHours(
  value: number,
  unit: DurationUnit,
  settings: ResolvedDurationSettings,
): number;
```

---

### `workingDaysToDuration`

```ts
export function workingDaysToDuration(
  workingDays: number,
  unit: DurationUnit,
  settings: ResolvedDurationSettings,
): number;
```

---

### `hoursToDuration`

Converts canonical stored working hours into a display magnitude.

```ts
export function hoursToDuration(
  hours: number,
  unit: DurationUnit,
  settings: ResolvedDurationSettings,
): number;
```

---

### `durationToElapsedDays`

Converts an elapsed duration to continuous 24-hour calendar days.

```ts
export function durationToElapsedDays(value: number, unit: DurationUnit): number;
```

---

### `durationToElapsedHours`

Converts an elapsed display magnitude into canonical stored continuous hours.

```ts
export function durationToElapsedHours(value: number, unit: DurationUnit): number;
```

---

### `elapsedDaysToDuration`

```ts
export function elapsedDaysToDuration(elapsedDays: number, unit: DurationUnit): number;
```

---

### `elapsedHoursToDuration`

Converts canonical stored continuous hours into an elapsed display magnitude.

```ts
export function elapsedHoursToDuration(elapsedHours: number, unit: DurationUnit): number;
```

---

### `resolveAutomaticDurationUnit`

```ts
export function resolveAutomaticDurationUnit(
  workingDays: number,
  settings: ResolvedDurationSettings,
): DurationUnit;
```

---

### `resolveAutomaticDurationUnitFromHours`

Selects the automatic display unit for a canonical working-hour value.

```ts
export function resolveAutomaticDurationUnitFromHours(
  hours: number,
  settings: ResolvedDurationSettings,
): DurationUnit;
```

---

### `formatDurationValue`

```ts
export function formatDurationValue(
  value: number,
  unit: DurationUnit,
  options?: FormatDurationValueOptions,
): string;
```

---

### `formatWorkingDuration`

```ts
export function formatWorkingDuration(
  workingDays: number,
  settings: ResolvedDurationSettings,
  options?: FormatWorkingDurationOptions,
): string;
```

---

### `DurationUnit`

Unit retained with an authored task duration.

```ts
/** Unit retained with an authored task duration. */
export type DurationUnit = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
```

---

### `DurationSettings`

Project-level duration display and working-time conversion settings.

```ts
interface DurationSettings {
  /** Unit used for bare input and display. `auto` chooses minutes, hours, or days by magnitude. */
    readonly defaultUnit?: DurationUnit | 'auto';
  /** Unit used for bare Work input and display. Defaults to `auto`, independently from task Duration. */
    readonly defaultWorkUnit?: DurationUnit | 'auto';
  /** Working hours represented by one duration day. Defaults to the effective calendar, then 8. */
    readonly hoursPerDay?: number;
  /** Working hours represented by one duration week. Defaults to the effective workweek, then 40. */
    readonly hoursPerWeek?: number;
  /** Working days represented by one duration month. Defaults to 20. */
    readonly daysPerMonth?: number;
  /** Maximum digits shown after the decimal separator. Defaults to 1. */
    readonly maximumFractionDigits?: number
}
```

---

### `ResolvedDurationSettings`

```ts
interface ResolvedDurationSettings {
  readonly defaultUnit: DurationUnit | 'auto';
  readonly defaultWorkUnit: DurationUnit | 'auto';
  readonly hoursPerDay: number;
  readonly hoursPerWeek: number;
  readonly daysPerMonth: number;
  readonly maximumFractionDigits: number
}
```

---

### `ParsedDuration`

```ts
interface ParsedDuration {
  readonly value: number;
  readonly unit: DurationUnit;
  readonly elapsed: boolean
}
```

---

### `ParseDurationOptions`

```ts
interface ParseDurationOptions {
  readonly defaultUnit?: DurationUnit;
  readonly allowElapsed?: boolean
}
```

---

### `FormatDurationValueOptions`

```ts
interface FormatDurationValueOptions {
  readonly elapsed?: boolean;
  /** Maximum digits shown after the decimal separator. Defaults to 1. */
    readonly maximumFractionDigits?: number
}
```

---

### `FormatWorkingDurationOptions` (Extended from `index.ts`)

```ts
interface FormatWorkingDurationOptions {
  readonly unit?: DurationUnit
}
```

---

### `parseTimeOfDay`

Parses `HH:mm` or `h:mm AM/PM` into minutes from midnight.
`24:00` is accepted only when `allowEndOfDay` is enabled.

```ts
export function parseTimeOfDay(value: string, options: { allowEndOfDay?: boolean } = {}): number;
```

---

### `formatTimeOfDay`

```ts
export function formatTimeOfDay(totalMinutes: number): string;
```

---

### `formatCompactTimeOfDay`

```ts
export function formatCompactTimeOfDay(totalMinutes: number): string;
```

---

### `formatAmPmTimeOfDay`

```ts
export function formatAmPmTimeOfDay(totalMinutes: number): string;
```

---

### `formatDisplayTimeOfDay`

```ts
export function formatDisplayTimeOfDay(
  totalMinutes: number,
  options: {
    readonly timeLabelFormatter?: (minutes: number, slotIndex: number) => string;
    readonly slotIndex?: number;
    readonly useAmPm?: boolean;
  } = {},
): string;
```

---

### `formatDurationMinutes`

```ts
export function formatDurationMinutes(totalMinutes: number): string;
```

---

### `formatDuration`

```ts
export function formatDuration(
  duration: number | undefined | null,
  options: { readonly hoursPerDay?: number } = {},
): string;
```

---

### `hasAmPmMarker`

```ts
export function hasAmPmMarker(value: string): boolean;
```

---

### `getDateMinutes`

```ts
export function getDateMinutes(date: Date): number;
```

---

### `createTimeZoneWeekdayHourReader`

Compiles timezone projection once and keeps a bounded minute-level result cache.

```ts
export function createTimeZoneWeekdayHourReader(timeZone: string): TimeZoneWeekdayHourReader;
```

---

### `isIanaTimeZone`

Returns whether a string names an Intl-supported IANA timezone.

```ts
export function isIanaTimeZone(timeZone: string): boolean;
```

---

### `assertIanaTimeZone`

Validates an IANA timezone at the shared date boundary.

```ts
export function assertIanaTimeZone(timeZone: string, label = 'timeZone'): void;
```

---

### `getTimeZoneWeekdayHour`

Extracts the civil weekday/hour containing an instant in an IANA timezone.

```ts
export function getTimeZoneWeekdayHour(
  instant: Date,
  timeZone: string,
): TimeZoneWeekdayHour | undefined;
```

---

### `createDateTime`

Creates a UTC datetime from a date-only value and minutes since midnight.

```ts
export function createDateTime(date: string, minutes: number): ISODateTimeString;
```

---

### `createDateTimeFromTimeOfDay`

```ts
export function createDateTimeFromTimeOfDay(date: string, time: string, dayOffset = 0): ISODateTimeString;
```

---

### `getLocalDateTimeAsUtcIsoDateTime`

Serializes a local `Date` clock value as a UTC ISO datetime.
This preserves the user's local wall-clock fields for scheduler form inputs.

```ts
export function getLocalDateTimeAsUtcIsoDateTime(date: Date): ISODateTimeString;
```

---

### `shiftDateTime`

```ts
export function shiftDateTime(value: string, deltaMinutes: number): ISODateTimeString;
```

---

### `replaceDateTimeDate`

Replaces only the UTC calendar date while preserving the exact authored time.

```ts
export function replaceDateTimeDate(value: string, date: string): ISODateTimeString;
```

---

### `isMidnightDateTime`

```ts
export function isMidnightDateTime(value: string): boolean;
```

---

### `getDateTimeDurationMinutes`

```ts
export function getDateTimeDurationMinutes(startDateTime: string, endDateTime: string): number;
```

---

### `getDurationMinutes`

```ts
export function getDurationMinutes(event: {
  readonly startDateTime: ISODateTimeString | string;
  readonly endDateTime: ISODateTimeString | string;
}): number;
```

---

### `getClampedDateTimeDurationMinutes`

Returns an event duration in minutes, clamped to zero for inverted ranges.

```ts
export function getClampedDateTimeDurationMinutes(startDateTime: string, endDateTime: string): number;
```

---

### `snapMinutes`

```ts
export function snapMinutes(minutes: number, snap: number): number;
```

---

### `snapDateTime`

Snaps a UTC datetime to the nearest minute interval within the same UTC day.

```ts
export function snapDateTime(value: string, snap: number): ISODateTimeString;
```

---

### `TimeZoneWeekdayHour`

```ts
interface TimeZoneWeekdayHour {
  /** Sunday is 0 and Saturday is 6, matching `Date#getUTCDay`. */
    readonly weekday: number;
  readonly hour: number
}
```

---

### `TimeZoneWeekdayHourReader`

```ts
export type TimeZoneWeekdayHourReader = (instant: Date) => TimeZoneWeekdayHour | undefined;
```

---

### `getBrowserTimeZone`

```ts
export function getBrowserTimeZone();
```

---

### `getCivilParts`

Projects an instant into Gregorian civil fields in an IANA timezone.

```ts
export function getCivilParts(instant: Date, timeZone: string): CivilDateTime;
```

---

### `parseIsoCivilDate`

Parses a valid ISO date-only string into timezone-independent civil fields.

```ts
export function parseIsoCivilDate(value: string): CivilDate | undefined;
```

---

### `parseIsoLocalCivilDateTime`

Parses a `datetime-local` value into civil fields without applying a timezone.

```ts
export function parseIsoLocalCivilDateTime(value: string): CivilDateTime | undefined;
```

---

### `getPossibleInstants`

Returns every instant represented by a civil second in an IANA timezone.

```ts
export function getPossibleInstants(value: CivilDateTime, timeZone: string): Date[];
```

---

### `resolveExactCivilInstant`

```ts
export function resolveExactCivilInstant(value: CivilDateTime, timeZone: string): Date | undefined;
```

---

### `resolveCivilBoundary`

Period boundaries advance through a timezone gap to its first valid civil instant.

```ts
export function resolveCivilBoundary(value: CivilDateTime, timeZone: string): Date;
```

---

### `CivilDateTime`

Calendar and clock fields interpreted in a specific IANA timezone.

```ts
interface CivilDateTime {
  readonly year: number;
  readonly month: number;
  readonly day: number;
  readonly hour: number;
  readonly minute: number;
  readonly second: number
}
```

---

### `CivilDate`

```ts
export type CivilDate = Pick<CivilDateTime, 'year' | 'month' | 'day'>;
```

---

### `normalizeTimelineWeekStartsOn`

```ts
export function normalizeTimelineWeekStartsOn(value: unknown): TimelineWeekStartsOn;
```

---

### `parseTimelineInstantValue`

Parses a timeline row value only when it identifies one unambiguous instant.

```ts
export function parseTimelineInstantValue(value: unknown): Date | undefined;
```

---

### `startOfTimelineWeek`

```ts
export function startOfTimelineWeek(date: string, weekStartsOn: TimelineWeekStartsOn): ISODateString;
```

---

### `parseTimelineDateValue`

Parses a timeline boundary as UTC for deterministic scale math.

```ts
export function parseTimelineDateValue(date: string): Date;
```

---

### `startOfTimelineUnit`

Returns the UTC-aligned start for a timeline unit.
Intraday units preserve datetime precision; day and larger units return date-only values.

```ts
export function startOfTimelineUnit(
  unit: TimelineUnit,
  date: string,
  weekStartsOn: TimelineWeekStartsOn = 0,
): ISODateString | ISODateTimeString;
```

---

### `addTimelineUnit`

Adds a timeline unit while preserving the timeline's UTC normalization rules.

```ts
export function addTimelineUnit(
  unit: TimelineUnit,
  date: string,
  amount: number,
): ISODateString | ISODateTimeString;
```

---

### `getTimelineEndExclusiveDate`

Converts an inclusive Gantt date boundary to an exclusive timeline boundary.
Datetime values already represent instants and are returned unchanged.

```ts
export function getTimelineEndExclusiveDate(date: string): ISODateString | ISODateTimeString;
```

---

### `getTimelineQuarter`

```ts
export function getTimelineQuarter(date: string): number;
```

---

### `formatTimelineDateLabel`

Formats timeline labels with a cached formatter; UTC remains the default timezone.

```ts
export function formatTimelineDateLabel(
  date: string | Date,
  locale: string,
  options: Intl.DateTimeFormatOptions,
  timeZone = 'UTC',
): string;
```

---

### `formatTimelineCompactWeekdayDayLabel`

Formats the compact weekday/day tier used below an enclosing month label.

```ts
export function formatTimelineCompactWeekdayDayLabel(
  date: string | Date,
  locale: string,
  timeZone = 'UTC',
): string;
```

---

### `startOfHour`

```ts
export function startOfHour(date: string): ISODateTimeString;
```

---

### `startOfMinute`

```ts
export function startOfMinute(date: string): ISODateTimeString;
```

---

### `TimelineUnit`

```ts
export type TimelineUnit = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
```

---

### `TimelineWeekStartsOn`

```ts
export type TimelineWeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
```

---

### `isWorkingDate`

Checks a date against calendar working weekdays and holiday exclusions.

```ts
export function isWorkingDate(
  date: ISODateString,
  calendar: WorkingCalendar | null | undefined,
): boolean;
```

---

### `moveToNextWorkingDate`

Moves forward until a working date is found.
Returns the original date when no working date is found before `iterationLimit`.

```ts
export function moveToNextWorkingDate(
  date: ISODateString,
  calendar: WorkingCalendar | null | undefined,
  iterationLimit = 3660,
): ISODateString;
```

---

### `moveToNextWorkingDateTime`

```ts
export function moveToNextWorkingDateTime(
  date: ISODateString,
  calendar: WorkingCalendar | null | undefined,
  iterationLimit = 3660,
): ISODateString;
```

---

### `moveToPreviousWorkingDate`

Moves backward until a working date is found.
Returns the original date when no working date is found before `iterationLimit`.

```ts
export function moveToPreviousWorkingDate(
  date: ISODateString,
  calendar: WorkingCalendar | null | undefined,
  iterationLimit = 3660,
): ISODateString;
```

---

### `addWorkingDays`

Adds working days, excluding the start date from the counted offset.

```ts
export function addWorkingDays(
  startDate: ISODateString,
  days: number,
  calendar: WorkingCalendar | null | undefined,
): ISODateString;
```

---

### `subtractWorkingDays`

Subtracts working days, excluding the start date from the counted offset.

```ts
export function subtractWorkingDays(
  startDate: ISODateString,
  days: number,
  calendar: WorkingCalendar | null | undefined,
): ISODateString;
```

---

### `offsetByLagCalendar`

Applies dependency lag using either calendar days or working days.

```ts
export function offsetByLagCalendar(
  date: ISODateString,
  days: number,
  calendar: WorkingCalendar | null | undefined,
  options: LagCalendarOptions,
): ISODateString;
```

---

### `resolveTaskEndDate`

Resolves a task end date from start and duration.
Date-only durations are inclusive; datetime durations support fractional days.

```ts
export function resolveTaskEndDate(
  startDate: ISODateString,
  duration: number,
  calendar: WorkingCalendar | null | undefined,
  options: WorkingDayOptions,
): ISODateString;
```

---

### `resolveTaskStartDateFromEnd`

Resolves a task start date from end and duration.
Date-only durations are inclusive; datetime durations support fractional days.

```ts
export function resolveTaskStartDateFromEnd(
  endDate: ISODateString,
  duration: number,
  calendar: WorkingCalendar | null | undefined,
  options: WorkingDayOptions,
): ISODateString;
```

---

### `countWorkingDaysInclusive`

Counts working dates inclusively between start and end.

```ts
export function countWorkingDaysInclusive(
  startDate: ISODateString,
  endDate: ISODateString,
  calendar: WorkingCalendar | null | undefined,
): number;
```

---

### `countWorkingDuration`

```ts
export function countWorkingDuration(
  startDate: ISODateString,
  endDate: ISODateString,
  calendar: WorkingCalendar | null | undefined,
): number;
```

---

### `snapToWorkingDate`

Snaps a date to the nearest working date in the requested direction.
Returns the original date when no working date is found before `iterationLimit`.

```ts
export function snapToWorkingDate(
  date: ISODateString,
  calendar: WorkingCalendar | null | undefined,
  direction: 'forward' | 'back' = 'forward',
  iterationLimit = 366,
): ISODateString;
```

---

### `WorkingTimeRange`

```ts
interface WorkingTimeRange {
  readonly start: string;
  readonly end: string
}
```

---

### `WorkingCalendar`

```ts
interface WorkingCalendar {
  readonly workingDays: readonly number[];
  readonly holidays: readonly string[];
  readonly workingHours?: WorkingTimeRange | readonly WorkingTimeRange[];
  readonly hoursPerDay?: number
}
```

---

### `WorkingDayOptions`

```ts
interface WorkingDayOptions {
  readonly excludeHolidaysFromDuration: boolean
}
```

---

### `LagCalendarOptions`

```ts
interface LagCalendarOptions {
  readonly lagCalendar: 'calendar-days' | 'working-days'
}
```

---

### `isRelativeDateWindowExpression`

```ts
export function isRelativeDateWindowExpression(value: unknown): value is RelativeDateWindowExpression;
```

---

### `startOfFiscalYear`

Returns the start of the fiscal year containing a civil date.

```ts
export function startOfFiscalYear(
  date: ISODateString,
  settings: Pick<RelativeDateWindowSettings, 'fiscalYearStart'>,
): ISODateString;
```

---

### `resolveRelativeDateWindow`

Resolves a relative expression to inclusive civil-date boundaries.

```ts
export function resolveRelativeDateWindow(
  today: string,
  expression: RelativeDateWindowExpression,
  settings: RelativeDateWindowSettings,
): RelativeDateWindowRange | undefined;
```

---

### `RelativeDateWindowPreset`

```ts
export type RelativeDateWindowPreset =
  | 'last7Days'
  | 'today'
  | 'thisMonth'
  | 'thisQuarter'
  | 'yearToDate'
  | 'overdue';
```

---

### `RelativeDateWindowDirection`

```ts
export type RelativeDateWindowDirection = 'last' | 'next';
```

---

### `RelativeDateWindowUnit`

```ts
export type RelativeDateWindowUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
```

---

### `RelativeDateWindowExpression`

```ts
export type RelativeDateWindowExpression = Readonly<
  | {
      version: 1;
      mode: 'preset';
      preset: RelativeDateWindowPreset;
    }
  | {
      version: 1;
      mode: 'custom';
      direction: RelativeDateWindowDirection;
      amount: number;
      unit: RelativeDateWindowUnit;
      rolling: boolean;
    }
>;
```

---

### `RelativeDateWindowSettings`

```ts
interface RelativeDateWindowSettings {
  /** Sunday is 0 and Saturday is 6. */
    readonly weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  readonly fiscalYearStart: { readonly month: number; readonly day: number }
}
```

---

### `RelativeDateWindowRange`

```ts
interface RelativeDateWindowRange {
  /** Inclusive lower calendar date. */
    readonly from?: ISODateString;
  /** Inclusive upper calendar date. */
    readonly to?: ISODateString
}
```

---

# Dialog

URL: https://pro.rv-grid.com/api/dialog/
Source: src/content/docs/api/dialog.md

### `copyDialogTheme`

Copies grid theme and writing-direction context to external popups.

```ts
export function copyDialogTheme(
  source: HTMLElement,
  target: HTMLElement,
  additionalVariables: readonly `--${string}`[] = [],
  additionalVariableSource = source,
): void;
```

---

### `createDialogButton`

```ts
export function createDialogButton(
  document: Document,
  label: string,
  action: () => void,
  variant: DialogButtonVariant = 'default',
): HTMLButtonElement;
```

---

### `getDialogFocusableElements`

```ts
export function getDialogFocusableElements(root: HTMLElement): HTMLElement[];
```

---

### `trapDialogFocus`

```ts
export function trapDialogFocus(
  root: HTMLElement,
  event: KeyboardEvent,
): void;
```

---

### `DialogPlugin`

```ts
class DialogPlugin {
  open(options: DialogOpenOptions): DialogHandle;

  close(root?: HTMLElement): void;
}
```

---

### `attachDialogDrag`

Makes a dialog movable from a dedicated header without owning its rendering.

```ts
export function attachDialogDrag({
  target,
  handle,
  margin = 8,
  ignoreSelector = DEFAULT_IGNORE_SELECTOR,
}: DialogDragOptions): () => void;
```

---

### `DialogDragOptions`

```ts
interface DialogDragOptions {
  readonly target: HTMLElement;
  readonly handle: HTMLElement;
  readonly margin?: number;
  readonly ignoreSelector?: string
}
```

---

### `useDialogDrag`

Connects Preact-rendered dialog refs to the framework-neutral drag owner.

```ts
export function useDialogDrag<
  Target extends HTMLElement,
  Handle extends HTMLElement,
>({
  targetRef,
  handleRef,
  enabled = true,
}: UseDialogDragOptions<Target, Handle>): void;
```

---

### `UseDialogDragOptions`

```ts
interface UseDialogDragOptions {
  readonly targetRef: RefObject<Target>;
  readonly handleRef: RefObject<Handle>;
  readonly enabled?: boolean
}
```

---

### `DialogOpenOptions`

```ts
interface DialogOpenOptions {
  readonly title: string;
  readonly closeLabel: string;
  /** ID of visible supporting copy that describes the dialog purpose. */
    readonly ariaDescribedBy?: string;
  readonly draggable?: boolean;
  readonly popupOwner?: object;
  readonly overlayClass?: string;
  readonly surfaceClass?: string;
  /** Explicit final focus target. Falls back to the previously focused live element. */
    readonly returnFocus?: HTMLElement;
  /** Called exactly once after the dialog is removed by any close mechanism. */
    readonly onClose?: () => void
}
```

---

### `DialogHandle`

```ts
interface DialogHandle {
  readonly root: HTMLElement;
  readonly surface: HTMLElement;
  readonly header: HTMLElement;
  readonly body: HTMLElement;
  readonly footer: HTMLElement;
  readonly actions: HTMLElement;
  close(): void
}
```

---

### `DialogButtonVariant`

```ts
export type DialogButtonVariant =
  | 'default'
  | 'primary'
  | 'secondary'
  | 'danger'
  | 'danger-outline'
  | 'ghost';
```

---

### `createDialogElements`

```ts
export function createDialogElements(
  document: Document,
  options: DialogOpenOptions,
  close: () => void,
): DialogElements;
```

---

### `DialogElements`

```ts
interface DialogElements {
  readonly root: HTMLElement;
  readonly surface: HTMLElement;
  readonly header: HTMLElement;
  readonly body: HTMLElement;
  readonly footer: HTMLElement;
  readonly actions: HTMLElement
}
```

---

# Dimension Animation

URL: https://pro.rv-grid.com/api/dimension-animation/
Source: src/content/docs/api/dimension-animation.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  dimensionAnimation?: DimensionAnimationConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data property dimensionAnimation
       * @deprecated Use `grid.dimensionAnimation` instead.
       */
      dimensionAnimation?: DimensionAnimationConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  dimensionanimate: DimensionAnimationEventDetail;
  beforedimensionanimate: DimensionAnimationEventDetail;
  afterdimensionanimate: DimensionAnimationEventDetail
}
```

## Plugin API

### `DimensionAnimationPlugin`

RevoGrid Pro plugin that animates dimension sizes without owning visibility state.

Rows and columns can be addressed by physical source index or by current
visual index. Callers own follow-up state changes such as applying trim or
mutating proxy order.

```ts
class DimensionAnimationPlugin {
  /** Collapse dimensions by animating their current size to zero. */
  collapse(indexes: DimensionAnimationIndexes, options: DimensionAnimationOptions = {});

  /** Expand dimensions from zero size to their cached/default size. */
  expand(indexes: DimensionAnimationIndexes, options: DimensionAnimationOptions = {});

  /** Animate explicit dimension-size frames. */
  animate(frames: DimensionAnimationFrameInput[], options: DimensionAnimationOptions = {});

  /** Cancels in-flight animations. Omit arguments to cancel all animations. */
  cancel(type?: MultiDimensionType, indexes?: DimensionAnimationIndexes);

  /** Cancels in-flight animations and restores their captured dimension sizes. */
  cancelAndRestore(type?: MultiDimensionType, indexes?: DimensionAnimationIndexes);

  destroy();
}
```

---

### `DimensionAnimationAction`

Supported dimension size animation operations for `DimensionAnimationPlugin`.

```ts
/** Supported dimension size animation operations for `DimensionAnimationPlugin`. */
export type DimensionAnimationAction = 'collapse' | 'expand' | 'animate';
```

---

### `DimensionAnimationEasing`

Animation easing used when interpolating dimension sizes.

- `linear`: direct progress mapping.
- `easeOutCubic`: default easing, fast start with soft finish.
- function: receives normalized progress from `0` to `1`.

```ts
/**
 * Animation easing used when interpolating dimension sizes.
 *
 * - `linear`: direct progress mapping.
 * - `easeOutCubic`: default easing, fast start with soft finish.
 * - function: receives normalized progress from `0` to `1`.
 */
export type DimensionAnimationEasing =
  | 'linear'
  | 'easeOutCubic'
  | ((progress: number) => number);
```

---

### `DimensionAnimationConfig`

Plugin-level configuration for dimension size animation behavior.

```ts
interface DimensionAnimationConfig {
  /** Animation duration in milliseconds. Use `0` to apply synchronously. */
    duration?: number;
  /** Easing function or named easing. Defaults to `easeOutCubic`. */
    easing?: DimensionAnimationEasing;
  /** Dimensions affected by requests that do not specify a single `type`. */
    types?: MultiDimensionType[]
}
```

---

### `DimensionAnimationOptions` (Extended from `index.ts`)

Per-call options for controller methods and event requests.

```ts
interface DimensionAnimationOptions {
  /** Single dimension to target for the request. */
    type?: MultiDimensionType;
  /** Whether `indexes` are source physical indexes or current visible indexes. */
    indexKind?: DimensionAnimationIndexKind
}
```

---

### `DimensionAnimationIndexes`

Dimension indexes accepted by the controller.

Iterables such as arrays are treated as indexes to affect. Records use
truthy values to mark affected indexes.

```ts
/**
 * Dimension indexes accepted by the controller.
 *
 * Iterables such as arrays are treated as indexes to affect. Records use
 * truthy values to mark affected indexes.
 */
export type DimensionAnimationIndexes = Iterable<number> | Record<number, boolean | undefined>;
```

---

### `DimensionAnimationIndexKind`

```ts
export type DimensionAnimationIndexKind = 'physical' | 'visual';
```

---

### `DimensionAnimationIndexesByType`

```ts
export type DimensionAnimationIndexesByType = Partial<Record<MultiDimensionType, DimensionAnimationIndexes>>;
```

---

### `DimensionAnimationFrameInput`

Explicit animation frame input used by callers that already know visual positions.

```ts
interface DimensionAnimationFrameInput {
  /** Dimension containing this frame. Defaults to request `type` or `rgRow`. */
    type?: MultiDimensionType;
  /** Current visual index in the dimension. */
    visualIndex: number;
  /** Optional physical index used for cancellation/cache identity. */
    physicalIndex?: number;
  /** Start size. If omitted, the current/cached size is used. */
    from?: number;
  /** End size. If omitted, the current/cached size is used. */
    to?: number
}
```

---

### `DimensionAnimationRequest` (Extended from `index.ts`)

Event/controller request payload for dimension animation operations.

```ts
interface DimensionAnimationRequest {
  /** Operation to perform. */
    action: DimensionAnimationAction;
  /** Indexes for `collapse` and `expand`. */
    indexes?: DimensionAnimationIndexes;
  /** Target indexes keyed by dimension. */
    byType?: DimensionAnimationIndexesByType;
  /** Explicit frame inputs for `animate`. */
    frames?: DimensionAnimationFrameInput[]
}
```

---

### `DimensionAnimationResult`

Result emitted for each dimension touched by a request.

```ts
interface DimensionAnimationResult {
  /** Operation that produced this result. */
    action: DimensionAnimationAction;
  /** Dimension affected by this result. */
    type: MultiDimensionType;
  /** Input indexes included in the operation. Empty for explicit frame requests. */
    indexes: number[];
  /** Whether the animation was cancelled before normal completion. */
    cancelled: boolean;
  /** Internal frames resolved and animated for this result. */
    frames: DimensionAnimationFrame[]
}
```

---

### `DimensionAnimationEventDetail` (Extended from `index.ts`)

Detail payload for dimension animation events.

```ts
interface DimensionAnimationEventDetail {
  /** Promise attached synchronously by the plugin for event-driven callers that need completion ordering. */
    done?: Promise<DimensionAnimationResult[]>;
  /** Filled by the plugin after a `dimensionanimate` event request completes. */
    results?: DimensionAnimationResult[]
}
```

---

### `DimensionAnimationController`

Public controller API implemented by `DimensionAnimationPlugin`.

```ts
interface DimensionAnimationController {
  /** Collapse dimensions with animation by animating their size to zero. */
    collapse(indexes: DimensionAnimationIndexes, options?: DimensionAnimationOptions): Promise<DimensionAnimationResult[]>;
  /** Expand dimensions by starting them at zero, then animating to their cached/default size. */
    expand(indexes: DimensionAnimationIndexes, options?: DimensionAnimationOptions): Promise<DimensionAnimationResult[]>;
  /** Animate explicit dimension-size frames. */
    animate(frames: DimensionAnimationFrameInput[], options?: DimensionAnimationOptions): Promise<DimensionAnimationResult[]>;
  /** Cancel matching in-flight animations. */
    cancel(type?: MultiDimensionType, indexes?: DimensionAnimationIndexes): void;
  /** Cancel matching animations and restore their captured geometry. */
    cancelAndRestore(type?: MultiDimensionType, indexes?: DimensionAnimationIndexes): void
}
```

---

### `DimensionAnimationFrame`

Internal dimension-size animation frame resolved from physical to visual index.

```ts
interface DimensionAnimationFrame {
  type: MultiDimensionType;
  physicalIndex: number;
  visualIndex: number;
  from: number;
  to: number
}
```

---

### `DimensionAnimationSizeCache`

Internal cache of sizes keyed by dimension and physical index.

```ts
/** Internal cache of sizes keyed by dimension and physical index. */
export type DimensionAnimationSizeCache = Partial<Record<MultiDimensionType, Record<number, number>>>;
```

---

### `DimensionAnimationSizePatch`

Internal patch of visual sizes passed to the dimension provider.

```ts
/** Internal patch of visual sizes passed to the dimension provider. */
export type DimensionAnimationSizePatch = ViewSettingSizeProp;
```

---

### `normalizeDimensionAnimationConfig`

Normalizes partial dimension-animation plugin config into the complete runtime shape.

```ts
export function normalizeDimensionAnimationConfig(
  config?: DimensionAnimationConfig,
): NormalizedDimensionAnimationConfig;
```

---

### `DEFAULT_DIMENSION_ANIMATION_DURATION`

Default dimension animation duration, in milliseconds.

```ts
DEFAULT_DIMENSION_ANIMATION_DURATION: 180;
```

---

### `DEFAULT_DIMENSION_ANIMATION_FALLBACK_ROW_SIZE`

Last-resort row size used when neither dimension nor grid defaults are configured.

```ts
DEFAULT_DIMENSION_ANIMATION_FALLBACK_ROW_SIZE: 24;
```

---

### `DEFAULT_DIMENSION_ANIMATION_FALLBACK_COLUMN_SIZE`

Last-resort column size used when neither dimension nor grid defaults are configured.

```ts
DEFAULT_DIMENSION_ANIMATION_FALLBACK_COLUMN_SIZE: 100;
```

---

### `DEFAULT_DIMENSION_ANIMATION_TYPES`

```ts
DEFAULT_DIMENSION_ANIMATION_TYPES: (DimensionRows | DimensionCols)[];
```

---

### `NormalizedDimensionAnimationConfig`

```ts
export type NormalizedDimensionAnimationConfig = Required<Pick<
  DimensionAnimationConfig,
  'duration' | 'easing' | 'types'
>>;
```

---

### `DEFAULT_DIMENSION_ANIMATION_CONFIG`

```ts
DEFAULT_DIMENSION_ANIMATION_CONFIG: {
  duration: number;
  easing: string;
  types: (DimensionRows | DimensionCols)[];
};
```

---

### `DIMENSION_ANIMATE_EVENT`

Event dispatched to request a dimension-size animation from the grid element.

The plugin attaches `detail.done` synchronously so event-driven integrations
can await completion before running follow-up logic such as trimming or reorder.

```ts
DIMENSION_ANIMATE_EVENT: string;
```

---

### `BEFORE_DIMENSION_ANIMATE_EVENT`

Cancelable event emitted before a dimension animation operation starts.

```ts
BEFORE_DIMENSION_ANIMATE_EVENT: string;
```

---

### `AFTER_DIMENSION_ANIMATE_EVENT`

Event emitted after a dimension animation operation finishes or is cancelled.

```ts
AFTER_DIMENSION_ANIMATE_EVENT: string;
```

---

### `DimensionAnimationAnimator`

Manages dimension size animation frames and cancellation.

```ts
class DimensionAnimationAnimator {
  /** Animates frame sizes and returns `false` if the run is cancelled. */
  animate(
    frames: DimensionAnimationFrame[],
    options: NormalizedDimensionAnimationConfig,
  ): Promise<boolean>;

  /** Cancels matching dimension animations. Omitted arguments cancel all animations. */
  cancel(type?: MultiDimensionType, indexes?: DimensionAnimationIndexes);

  /** Applies interpolated sizes for a group of animation frames. */
  applyFrameSizes(type: MultiDimensionType, frames: DimensionAnimationFrame[], progress: number);
}
```

---

### `DimensionAnimationContentOpacity`

Tracks transient content opacity for dimensions whose size reaches zero.

```ts
class DimensionAnimationContentOpacity {
  apply(frames: DimensionAnimationFrame[], progress: number);

  get(type: MultiDimensionType, physicalIndex: number): number | undefined;

  clear(type?: MultiDimensionType, indexes?: DimensionAnimationIndexes);

  clearExpanded(frames: DimensionAnimationFrame[]);
}
```

---

### `resolveDimensionAnimationEasing`

Resolves a named or custom easing into a normalized progress function.

```ts
export function resolveDimensionAnimationEasing(
  easing: DimensionAnimationEasing,
): (progress: number) => number;
```

---

### `normalizeDimensionAnimationIndexes`

Converts iterable or record input into a finite index array.

```ts
export function normalizeDimensionAnimationIndexes(
  indexes: DimensionAnimationIndexes | undefined,
): number[];
```

---

### `resolveDimensionAnimationRequestIndexes`

Resolves a request into dimension buckets with normalized indexes.

```ts
export function resolveDimensionAnimationRequestIndexes(
  request: DimensionAnimationRequest,
  defaultTypes: MultiDimensionType[],
): Partial<Record<MultiDimensionType, number[]>>;
```

---

# Distribution Chart

URL: https://pro.rv-grid.com/api/distribution-chart/
Source: src/content/docs/api/distribution-chart.md

### `DistributionChart`

Shared, presentation-only distribution chart. Domain filters own their data and labels;
this control owns chart geometry, tooltips, focus, and visual state.

```ts
export function DistributionChart({
  data,
  ariaLabel,
  type = 'bar',
  height = 72,
  showPoints = type !== 'bar',
  className = '',
  renderTooltip,
}: DistributionChartProps): any;
```

---

### `DistributionChartType`

```ts
export type DistributionChartType = 'bar' | 'line' | 'area';
```

---

### `DistributionChartTooltip`

```ts
interface DistributionChartTooltip {
  readonly title: string;
  readonly details?: readonly string[]
}
```

---

### `DistributionChartDatum`

```ts
interface DistributionChartDatum {
  readonly key: string;
  readonly value: number;
  readonly selected?: boolean;
  readonly tooltip: DistributionChartTooltip
}
```

---

### `DistributionChartProps`

```ts
interface DistributionChartProps {
  readonly data: readonly DistributionChartDatum[];
  readonly ariaLabel: string;
  readonly type?: DistributionChartType;
  readonly height?: number;
  readonly showPoints?: boolean;
  readonly className?: string;
  readonly renderTooltip?: (datum: DistributionChartDatum, index: number) => ComponentChildren
}
```

---

# Dropdown

URL: https://pro.rv-grid.com/api/dropdown/
Source: src/content/docs/api/dropdown.md

### `DropdownPopupContent`

```ts
export function DropdownPopupContent<T = any>({
  options,
  value,
  onChange,
  config,
  multiSelect,
  search,
  searchPlaceholder,
  listboxId,
  searchId,
  renderOption,
  renderNoResults,
  onClose,
  theme,
}: {
  options: DropdownOption<T>[];
  value: T | T[] | undefined;
  onChange: (value: T | T[]) => void;
  config: DropdownConfig<T>;
  multiSelect: boolean;
  search: boolean;
  searchPlaceholder: string;
  listboxId: string;
  searchId: string;
  renderOption?: (
    h: any,
    option: DropdownOption<T>,
    isSelected: boolean,
  ) => ComponentChildren;
  renderNoResults?: (h: any) => ComponentChildren;
  onClose: (focusNext?: boolean) => void;
  theme?: string | null;
});
```

---

### `DropdownContent`

```ts
export function DropdownContent<T = any>({
  options,
  filteredOptions,
  multiSelect,
  focusedIndex,
  selectedOptions,
  onKeyDown,
  onSelect,
  onFocusChange,
  renderOption,
  renderNoResults,
  dropdownListRef,
  theme,
  optionIdPrefix,
}: DropdownContentProps<T>);
```

---

### `useDropdownService`

```ts
export function useDropdownService<T = any>(
  options: DropdownOption<T>[],
  value: T | T[] | undefined,
  onChange: (value: T | T[]) => void,
  config: DropdownConfig<T> = {},
  onClose?: () => void
);
```

---

### `DropdownRenderable`

```ts
export type DropdownRenderable = any;
```

---

### `DropdownVNode`

```ts
export type DropdownVNode = any;
```

---

### `DropdownStyle`

```ts
export type DropdownStyle = string | Record<string, string | number | undefined>;
```

---

### `DropdownOption`

```ts
// Types
export type DropdownOption<T = any> = {
    value: T;
    label: string;
    disabled?: boolean;
    [key: string]: any;
  };
```

---

### `SortDirection`

```ts
export type SortDirection = 'asc' | 'desc' | 'none';
```

---

### `FilterFunction`

```ts
export type FilterFunction<T = any> = (
    option: DropdownOption<T>,
    searchValue: string,
  ) => boolean;
```

---

### `SortFunction`

```ts
export type SortFunction<T = any> = (
    a: DropdownOption<T>,
    b: DropdownOption<T>,
    direction: SortDirection,
  ) => number;
```

---

### `DropdownConfig`

```ts
export type DropdownConfig<T = any> = {
    // Search configuration
    search?: boolean;
    searchPlaceholder?: string;
    filterFunction?: FilterFunction<T>;

    // Sorting configuration
    sortDirection?: SortDirection;
    sortFunction?: SortFunction<T>;

    // Behavior configuration
    closeOnClickOutside?: boolean;
    autoFocus?: boolean;
    autoOpen?: boolean;
    multiSelect?: boolean;
    autocomplete?: boolean;
    /** Initial text for searchable dropdowns, used by grid quick-edit. */
    initialSearch?: string;
    /** Close the dropdown when Tab is pressed inside the open popup. */
    closeOnTab?: boolean;

    // Portal configuration
    portalTarget?: HTMLElement | null;

    // Accessibility
    ariaLabel?: string;
    ariaLabelledBy?: string;
    ariaDescribedBy?: string;

    // Layout configuration
    maxHeight?: number;
    theme?: string | null;

    // Custom class for popup
    popupClassName?: string;
  };
```

---

### `DropdownProps`

```ts
// Types
export type DropdownProps<T = any> = {
  // Core props
  source: DropdownOption<T>[];
  value?: T | T[];
  placeholder?: string;
  disabled?: boolean;
  name?: string;
  id?: string;
  className?: string;
  style?: DropdownStyle;

  // Configuration
  config?: DropdownConfig<T>;

  onChange?: (value: T | T[]) => void;
  onClose?: (focusNext?: boolean) => void;
  // Templates
  renderOption?: (
    h: HyperFunc<DropdownVNode>,
    option: DropdownOption<T>,
    isSelected: boolean,
  ) => DropdownRenderable;
  /**
   * Render the content of each selected value while preserving the built-in
   * single/multi-select wrappers, remove controls, and expand indicator.
   */
  renderValue?: (
    h: HyperFunc<DropdownVNode>,
    option: DropdownOption<T>,
  ) => DropdownRenderable;
  renderPlaceholder?: (
    h: HyperFunc<DropdownVNode>,
    placeholder: string,
    children: DropdownRenderable,
  ) => DropdownRenderable;
  /**
   * Render the selected value
   */
  renderSelectedValue?: (
    h: HyperFunc<DropdownVNode>,
    selectedOptions: DropdownOption<T>[],
    children: DropdownRenderable,
  ) => DropdownRenderable;
  renderNoResults?: (h: HyperFunc<DropdownVNode>) => DropdownRenderable;
};
```

---

### `Dropdown`

Dropdown component

```ts
export function Dropdown<T = any>({
  source,
  value,
  onChange,
  placeholder = 'Select an option',
  disabled = false,
  name,
  id,
  className = '',
  style,
  config = {},
  renderOption,
  renderValue,
  renderPlaceholder,
  renderSelectedValue,
  renderNoResults,
  onClose,
}: DropdownProps<T>): any;
```

---

### `DropdownPopup`

Dropdown popup component

**@param** triggerRef - The reference to the trigger element

**@param** children - The children of the dropdown

**@param** portalTarget - The target element to render the dropdown

**@param** theme - The theme of the dropdown

**@param** dropdownMenuId - The id of the dropdown menu

```ts
export function DropdownPopup({
  triggerRef,
  children,
  portalTarget,
  theme,
  dropdownMenuId,
  popupClassName,
  closeOnClickOutside = false,
  onClose,
  align = 'start',
  matchTriggerWidth = false,
  maxHeight,
  observePopupResize = true,
  topLayer = false,
}: DropdownPopupProps);
```

---

### `DropdownPopupProps`

```ts
// DropdownPopup component - Handles positioning and portal rendering
export type DropdownPopupProps = {
  triggerRef: RefObject<HTMLDivElement>;
  children: ComponentChildren;
  portalTarget?: HTMLElement | null;
  theme?: string | null;
  dropdownMenuId?: string;
  popupClassName?: string;
  closeOnClickOutside?: boolean;
  onClose?: () => void;
  align?: 'start' | 'end';
  matchTriggerWidth?: boolean;
  maxHeight?: number;
  observePopupResize?: boolean;
  /** Promotes the popup above modal dialogs without joining an ancestor's scroll context. */
  topLayer?: boolean;
};
```

---

### `defineDropdown`

Define the dropdown component

```ts
defineDropdown: (el: HTMLElement, props: DropdownProps) => void;
```

---

### `destroyDropdown`

```ts
destroyDropdown: (el: HTMLElement) => void;
```

---

# Editor Checkbox

URL: https://pro.rv-grid.com/api/editor-checkbox/
Source: src/content/docs/api/editor-checkbox.md

### `editorCheckbox`

The `editorCheckbox` is a custom cell editor for RevoGrid that provides a checkbox input
to edit boolean values directly within the grid cells.

 **Features**:
- Renders a checkbox input element for cells, allowing users to toggle boolean values (`true/false`)
  with a simple click.
- Automatically dispatches a `celledit` event upon change, updating the grid's data model with
  the new value.
- Ensures seamless integration with RevoGrid by providing row and column details in the event payload.

**Usage**:
- Import `editorCheckbox` and assign it to the `cellTemplate` property of a column in the RevoGrid.
- Ideal for columns that require quick boolean editing, such as toggling statuses or enabling/disabling options.

### Example
```typescript
import { editorCheckbox } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'enabled',
    name: 'Enabled',
    cellTemplate: editorCheckbox,
  },
];
```

**Event Handling**:
- The `editorCheckbox` dispatches a `celledit` event whenever the checkbox value changes.
- The event detail contains:
  - `rgCol`: The column index of the edited cell.
  - `rgRow`: The row index of the edited cell.
  - `type`: The type of the cell.
  - `prop`: The property of the cell being edited.
  - `val`: The new value (`true/false`) after the checkbox toggle.
  - `preventFocus`: A flag to control grid focus behavior (default: `false`).

This editor is particularly useful in scenarios where users need to enable or disable specific options
directly from the grid, providing a quick and user-friendly interface for boolean data editing.

```ts
editorCheckbox: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

# Editor Counter

URL: https://pro.rv-grid.com/api/editor-counter/
Source: src/content/docs/api/editor-counter.md

### `editorCounter`

The `editorCounter` is a custom cell editor for RevoGrid that provides plus/minus buttons
to increment/decrement numeric values within a specified range directly within the grid cells.

**Features**:
- Renders plus and minus buttons for easy value adjustment
- Supports customizable minimum and maximum values through column properties
- Configurable step size for increments/decrements
- Shows current value with optional display toggle
- Automatically dispatches a `celledit` event upon change
- Seamless integration with RevoGrid's data model
- Modern, responsive design with customizable theming

**Usage**:
```typescript
import { editorCounter } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'quantity',
    name: 'Quantity',
    cellTemplate: editorCounter,
    min: 0,
    max: 100,
    step: 1,
    hideValue: false, // Set to true to hide the value display
  },
];
```

**Event Handling**:
- Dispatches a `celledit` event on value change
- Event detail includes row, column, property, and new value information

**Theming**:
Customizable through CSS variables:
- `--counter-button-size`: Size of plus/minus buttons (default: 24px)
- `--counter-value-size`: Font size of the value display (default: 14px)
- `--counter-spacing`: Spacing between elements (default: 4px)
- `--counter-button-bg`: Background color of buttons
- `--counter-button-color`: Color of button icons
- `--counter-button-hover-bg`: Button background on hover
- `--counter-value-color`: Color of the value text
- `--counter-disabled-opacity`: Opacity for disabled buttons

```ts
editorCounter: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

# Editor Dropdown

URL: https://pro.rv-grid.com/api/editor-dropdown/
Source: src/content/docs/api/editor-dropdown.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Configuration for dropdown editor
       */
      dropdown?: DropdownColumnConfig;
  /**
       * Column-select compatible dropdown source.
       */
      source?: DropdownColumnSourceEntry[];
  /**
       * Object source label field used by dropdown columns.
       */
      labelKey?: string;
  /**
       * Object source value field used by dropdown columns.
       */
      valueKey?: string
}
```

## Plugin API

### `DropdownColumnSourceEntry`

```ts
export type DropdownColumnSourceEntry = string | Record<string, unknown>;
```

---

### `DropdownColumnProps` (Extended from `index.ts`)

```ts
export type DropdownColumnProps = DropdownProps & {
  /** Mirror a cell template in dropdown options and selected values. */
  syncCellTemplate?: boolean;
  /** Optional external template to mirror instead of the column cell template. */
  cellTemplate?: ColumnRegular['cellTemplate'];
};
```

---

### `DropdownColumnConfig` (Extended from `index.ts`)

Per-column dropdown overrides; the source may be inherited from a column type.

```ts
/** Per-column dropdown overrides; the source may be inherited from a column type. */
export type DropdownColumnConfig = Omit<DropdownColumnProps, 'source'> & {
  source?: DropdownColumnProps['source'];
};
```

---

### `normalizeDropdownOptions`

```ts
normalizeDropdownOptions: (source?: unknown[], labelKey?: string | undefined, valueKey?: string | undefined) => DropdownOption[];
```

---

### `normalizeColumnDropdown`

```ts
normalizeColumnDropdown: (column?: ColumnRegular<ColumnProp, DataType<any, ColumnProp>> | null | undefined) => DropdownColumnProps | undefined;
```

---

### `resolveColumnDropdownCellTemplate`

Resolve the authored value template behind a dropdown column adapter.

```ts
resolveColumnDropdownCellTemplate: (column?: ColumnRegular<ColumnProp, DataType<any, ColumnProp>> | null | undefined) => CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `findColumnDropdownOption`

Find normalized dropdown metadata for a stored column value.

```ts
findColumnDropdownOption: (column: ColumnRegular<ColumnProp, DataType<any, ColumnProp>> | null | undefined, value: unknown) => DropdownOption | undefined;
```

---

### `findColumnDropdownOptionByLabel`

Find normalized dropdown metadata by its authored display label.

```ts
findColumnDropdownOptionByLabel: (column: ColumnRegular<ColumnProp, DataType<any, ColumnProp>> | null | undefined, label: unknown) => DropdownOption | undefined;
```

---

### `resolveColumnDropdownProps`

Resolve the normalized dropdown contract for a grid cell context, including
the exact renderers generated by `syncCellTemplate`.

```ts
resolveColumnDropdownProps: (data: ColumnDataSchemaModel<DataType<any, ColumnProp>, ColumnRegular<ColumnProp, DataType<any, ColumnProp>>, ColumnProp>, additionalData?: unknown) => DropdownProps | undefined;
```

---

### `editorDropdown`

```ts
editorDropdown: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `DropdownEditor`

```ts
class DropdownEditor {
  async componentDidRender(): Promise<void>;

  getValue();

  beforeDisconnect();

  disconnectedCallback();

  render(h: HyperFunc<VNode>, additionalData?: unknown);
}
```

---

### `dropdownEditor`

```ts
dropdownEditor: typeof DropdownEditor;
```

---

### `ColumnDropdown`

Column type for dropdown editor

**Key Features**:
- **Cell Template**: Uses the `editorDropdown` template for rendering the dropdown editor.
- **Cell Properties**: Applies a small padding to the cell to prevent layout issues.
- **Readonly**: Ensures the dropdown is not editable by default.

```ts
ColumnDropdown: {
  beforeSetup: (column: ColumnRegular<ColumnProp, DataType<any, ColumnProp>>) => void;
  cellTemplate: CellTemplate<DataType<any, ColumnProp>>;
  editor: typeof DropdownEditor;
  cellProperties: () => { style: { padding: string; }; };
};
```

---

# Editor Numeric Array

URL: https://pro.rv-grid.com/api/editor-numeric-array/
Source: src/content/docs/api/editor-numeric-array.md

### `tryParseDataGridNumericArray`

```ts
export function tryParseDataGridNumericArray(value: unknown): number[] | undefined;
```

---

### `parseDataGridNumericArray`

```ts
export function parseDataGridNumericArray(
  value: unknown,
  fallback: readonly number[] = [],
): number[];
```

---

### `numericArrayBounds`

Derive finite array bounds without exceeding JavaScript's call argument limit.

```ts
export function numericArrayBounds(
  values: readonly number[],
): { readonly min: number; readonly max: number } | undefined;
```

---

### `NumericArrayEditorOptions`

```ts
interface NumericArrayEditorOptions {
  readonly runtime: StructuredEditorRuntime;
  readonly title: string;
  readonly presentationId: 'sparkline' | 'bar';
  readonly presentationOptions?: Readonly<Record<string, unknown>>
}
```

---

### `NumericArrayEditor`

Structured editor for the numeric-array contract used by inline charts.

```ts
class NumericArrayEditor {
  getValue(): number[];

  componentDidRender(): void | Promise<void>;

  beforeAutoSave(): boolean;

  beforeDisconnect(): void;

  render(...args: Parameters<TextEditor['render']>): ReturnType<TextEditor['render']>;
}
```

---

# Editor Row

URL: https://pro.rv-grid.com/api/editor-row/
Source: src/content/docs/api/editor-row.md

### `RowEditPlugin`

The `RowEditPlugin` is a custom plugin for RevoGrid that provides row-level editing capabilities,
allowing users to edit entire rows inline with dedicated action buttons for saving or canceling changes.

 **Features**:
- **Row Editing Mode:** Enables editing of entire rows by rendering editors for all cells in the selected row.
- **Inline Editors:** Supports inline editing of multiple cells in a row simultaneously.
- **Action Buttons:** Provides intuitive buttons for `Save` and `Cancel` actions:
  - `Save`: Dispatches `CELL_EDIT_SAVE_EVENT` to persist changes.
  - `Cancel`: Dispatches `CELL_EDIT_CANCEL_EVENT` to discard changes.
- **Event Handling:** Listens for key events to manage row editing:
  - `CELL_EDIT_EVENT`: Initiates row editing mode.
  - `CELL_EDIT_SAVE_EVENT`: Saves edited data and updates the grid model.
  - `CELL_EDIT_CANCEL_EVENT`: Cancels editing and restores original data.
  - `BEFORE_CELL_RENDER_EVENT`: Ensures cells in the editing row render with editors.

**Usage**:
1. **Import and Initialize the Plugin:**
   ```typescript
   import { RowEditPlugin } from '@revolist/revogrid-pro'

   const grid = document.createElement('revo-grid');
   grid.plugins = [RowEditPlugin];
   ```

2. **Define Action Column:**
   Use the `editorRowActionColumn` to render action buttons (`Edit`, `Save`, `Cancel`):
   ```typescript
   import { editorRowActionColumn } from '@revolist/revogrid-pro'

   grid.columns = [
     { prop: 'name', name: 'Name' },
     { prop: 'age', name: 'Age' },
     {
            prop: 'edit',
            ...editorRowActionColumn,
        }, // Action column for row editing
   ];
   ```

Action Buttons:
- **Edit Button:** Dispatches `CELL_EDIT_EVENT` to enable row editing.
- **Save Button:** Dispatches `CELL_EDIT_SAVE_EVENT` to save changes.
- **Cancel Button:** Dispatches `CELL_EDIT_CANCEL_EVENT` to cancel editing and reset the row.

**Icon Details**:
- **Save Icon:** Embedded SVG icon representing a "Save" action.
- **Cancel Icon:** Embedded SVG icon representing a "Cancel" action.
- **Edit Icon:** Embedded SVG icon representing an "Edit" action.

**Scenarios**:
This plugin is particularly useful for applications where users need to edit multiple cells in a row at once.
Typical use cases include updating tabular records or form-like data directly within a grid.

**Conclusion**:
The `RowEditPlugin` enhances RevoGrid’s editing capabilities by offering a flexible row editing solution
with intuitive controls, efficient event handling, and seamless data integration.

```ts
class RowEditPlugin {}
```

---

### `editorRowActionColumn`

The editorRowActionColumn is a partial implementation of the ColumnRegular interface.
It defines the cellTemplate and editor properties for a column that renders action buttons
for row editing.

```ts
editorRowActionColumn: {
  cellProperties: (props: CellTemplateProp<DataType<any, ColumnProp>, ColumnRegular<ColumnProp, DataType<any, ColumnProp>>, ColumnProp>) => { onDblClick: (event: MouseEvent) => void; providers: Providers<DimensionRows>; previousValue?: any; flashDirection?: CellFlashDirection | undefined; flashState?: any; prop: ColumnProp; model: DataType<any, ColumnProp>; column: ColumnRegular<ColumnProp, DataType<any, ColumnProp>>; rowIndex: number; colIndex: number; colType: DimensionCols; type: DimensionRows; data: DataType<any, ColumnProp>[]; value?: any; };
  cellTemplate: (h: HyperFunc<VNode>, props: CellTemplateProp<DataType<any, ColumnProp>, ColumnRegular<ColumnProp, DataType<any, ColumnProp>>, ColumnProp>) => VNode;
  editor: () => { render(h: HyperFunc<VNode>): VNode[]; };
};
```

---

# Editor Slider

URL: https://pro.rv-grid.com/api/editor-slider/
Source: src/content/docs/api/editor-slider.md

### `editorSlider`

The `editorSlider` is a custom cell editor for RevoGrid that provides a slider input
to edit numeric values within a specified range directly within the grid cells.

**Features**:
- Renders a slider input element for cells, allowing users to select numeric values
  by dragging a slider handle.
- Supports customizable minimum and maximum values through column properties.
- Supports visual thresholds with custom CSS classes for different value ranges.
- Automatically dispatches a `celledit` event upon change, updating the grid's data model
  with the new value.
- Ensures seamless integration with RevoGrid by providing row and column details in the event payload.
- Shows current value and visual fill indicator for better UX.
- Supports theming through CSS variables.
- Optional value display that can be hidden through column properties.

**Usage**:
- Import `editorSlider` and assign it to the `cellTemplate` property of a column in the RevoGrid.
- Specify `min` and `max` values in the column properties to define the slider range.
- Use `hideValue` property to hide the numeric value display.
- Add `thresholds` property to define custom CSS classes for different value ranges.

### Example
```typescript
import { editorSlider } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'rating',
    name: 'Rating',
    cellTemplate: editorSlider,
    min: 0,
    max: 100,
    hideValue: false,
    thresholds: [
      { value: 70, className: 'high' },
      { value: 30, className: 'medium' },
      { value: 0, className: 'low' }
    ]
  },
];
```

**Event Handling**:
- The `editorSlider` dispatches a `celledit` event whenever the slider value changes.
- The event detail contains:
  - `rgCol`: The column index of the edited cell.
  - `rgRow`: The row index of the edited cell.
  - `type`: The type of the cell.
  - `prop`: The property of the cell being edited.
  - `val`: The new numeric value after the slider change.
  - `preventFocus`: A flag to control grid focus behavior (default: `true`).

**Theming**:
The slider can be themed using CSS variables:
- `--slider-thumb-size`: Size of the slider handle (default: 12px)
- `--slider-track-height`: Height of the slider track (default: 4px)
- `--slider-value-size`: Font size of the value display (default: 12px)
- `--slider-spacing`: Spacing between elements (default: 8px)
- `--slider-thumb-bg`: Background color of the slider handle
- `--slider-thumb-border`: Border color of the slider handle
- `--slider-track-bg`: Background color of the unfilled track
- `--slider-fill-start`: Start color of the fill gradient
- `--slider-fill-end`: End color of the fill gradient
- `--slider-value-color`: Color of the value text

These variables inherit from RevoGrid theme variables when available:
- `--revo-primary`
- `--revo-primary-light`
- `--revo-background`
- `--revo-border-color`
- `--revo-text-color-secondary`

```ts
editorSlider: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

# Editor Structured

URL: https://pro.rv-grid.com/api/editor-structured/
Source: src/content/docs/api/editor-structured.md

### `interpolateEditorLabel`

```ts
export function interpolateEditorLabel(
  value: string,
  replacements: Readonly<Record<string, string | number>>,
): string;
```

---

### `StructuredDataEditorLocaleText`

```ts
interface StructuredDataEditorLocaleText {
  readonly chartTitle: string;
  readonly timelineTitle: string;
  readonly close: string;
  readonly preview: string;
  readonly pointSummary: string;
  readonly pointsSummary: string;
  readonly eventSummary: string;
  readonly eventsSummary: string;
  readonly value: string;
  readonly pointValue: string;
  readonly label: string;
  readonly start: string;
  readonly end: string;
  readonly eventLabel: string;
  readonly eventStart: string;
  readonly eventEnd: string;
  readonly addPoint: string;
  readonly addEvent: string;
  readonly deletePoint: string;
  readonly deleteEvent: string;
  readonly reorderPoint: string;
  readonly moveEvent: string;
  readonly reorderEvent: string;
  readonly pasteValues: string;
  readonly pasteHint: string;
  readonly replaceValues: string;
  readonly appendValues: string;
  readonly editRawJson: string;
  readonly visualEditor: string;
  readonly rawJsonHint: string;
  readonly invalidNumber: string;
  readonly invalidPaste: string;
  readonly invalidTimeline: string;
  readonly invalidJson: string;
  readonly outsideRange: string;
  readonly emptyPoints: string;
  readonly emptyEvents: string;
  readonly cancel: string;
  readonly apply: string;
  readonly validationSummary: string;
  readonly resizeStart: string;
  readonly resizeEnd: string
}
```

---

### `StructuredEditorRuntime`

```ts
interface StructuredEditorRuntime {
  readonly locale: StructuredDataEditorLocaleText;
  readonly revogrid: HTMLRevoGridElement;
  readonly providers: import('@revolist/revogrid').PluginProviders
}
```

---

### `StructuredEditorContentProps`

```ts
interface StructuredEditorContentProps {
  readonly value: T;
  readonly locale: StructuredDataEditorLocaleText;
  readonly onChange: (value: T) => void;
  readonly onValidityChange: (valid: boolean) => void
}
```

---

### `StructuredEditorHostOptions`

```ts
interface StructuredEditorHostOptions {
  readonly runtime: StructuredEditorRuntime;
  readonly save: (value?: unknown, preventFocus?: boolean) => void;
  readonly close: (focusNext?: boolean) => void;
  readonly initialValue: T;
  readonly title: string;
  readonly kind: 'chart' | 'timeline';
  /** Renderer-owned variables required by a body-level structured editor. */
    readonly themeVariables?: readonly `--${string}`[];
  readonly renderContent: (
      props: StructuredEditorContentProps<T>,
    ) => ComponentChildren
}
```

---

### `StructuredEditorHost`

Shared structured-value popup that commits only through the core editor callback.

```ts
class StructuredEditorHost {
  mount(anchor: HTMLElement): void;

  destroy(): void;
}
```

---

# Editor Textarea

URL: https://pro.rv-grid.com/api/editor-textarea/
Source: src/content/docs/api/editor-textarea.md

### `TextAreaEditor`

The `TextAreaEditor` is a custom external editor for RevoGrid that enables
multi-line text editing directly within grid cells using a `<textarea>` element.
This editor is particularly useful for scenarios where users need to input or edit
larger text content that spans multiple lines, such as comments, descriptions, or notes.

 **Features**:
- **Multi-line Text Support**: Renders a `<textarea>` element for multi-line input, allowing users to input detailed text content.
- **Automatic Focus & Selection**: Automatically focuses and selects the text content when the editor is rendered, ensuring a seamless user experience.
- **Keyboard Navigation**: Listens for `Enter` and `Tab` key events to save changes and move to the next cell, supporting efficient keyboard-based navigation.
- **Save on Blur**: Automatically saves the content and closes the editor when the user clicks outside the editor (`blur` event).
- **Scroll Glitch Prevention**: Ensures smooth user interaction by blurring the input before disconnecting the editor, preventing scroll glitches.

**Usage**:
- Import `TextAreaEditor` and assign it as an editor for specific columns in the RevoGrid instance.
- Ideal for columns that require detailed multi-line text input.

### Example
```typescript
import { TextAreaEditor } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'comments',
    name: 'Comments',
    editor: 'textarea',
  },
];

grid.editors = {
  textarea: TextAreaEditor,
};
```

This editor enhances RevoGrid by providing a user-friendly and efficient way
to handle multi-line text input, making it suitable for applications requiring
rich text editing capabilities within grid cells.

```ts
class TextAreaEditor {
  /**
     * Lifecycle method triggered after the editor is rendered.
     * Automatically focuses the textarea.
     */
  async componentDidRender(): Promise<void>;

  onKeyDown(e: KeyboardEvent);

  /**
     * IMPORTANT: Prevent scroll glitches when editor is closed and focus is on current input element.
     */
  beforeDisconnect();

  getValue();

  /**
     * Render method for the TextAreaEditor.
     * Creates a textarea element with initial cell value, handles input events, and saves changes on blur.
     */
  render(h: HyperFunc<VNode>);
}
```

---

# Editor Timeline

URL: https://pro.rv-grid.com/api/editor-timeline/
Source: src/content/docs/api/editor-timeline.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  // showWeekNumbers?: boolean;
      // dateFormat?: string;
      // hideWeekends?: boolean;
      milestoneMode?: boolean
}
```

## Plugin API

### `editorTimeline`

The `editorTimeline` is a custom cell editor for RevoGrid that provides a timeline input
to edit date ranges directly within the grid cells.

**Features**:
- Renders a timeline bar with start and end date inputs
- Supports date range selection with date pickers
- Shows progress based on current date
- Optional week numbers display
- Optional weekend hiding
- Milestone mode support
- Custom date format support
- Group summary support
- Threshold support for progress visualization

**Usage**:
```typescript
import { editorTimeline } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'timeline',
    name: 'Timeline',
    cellTemplate: editorTimeline,
    milestoneMode: false,
    thresholds: [
      { value: 25, className: 'low' },
      { value: 50, className: 'medium' },
      { value: 75, className: 'high' }
    ]
  },
];
```

```ts
editorTimeline: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

---

### `TimelineValue`

```ts
interface TimelineValue {
  from: string;
  to: string;
  progress?: number
}
```

---

### `DateRange`

```ts
interface DateRange {
  start: Date;
  end: Date
}
```

---

### `DateService`

```ts
class DateService {}
```

---

# Editor Timeline Array

URL: https://pro.rv-grid.com/api/editor-timeline-array/
Source: src/content/docs/api/editor-timeline-array.md

### `TimelineArrayEditorOptions`

```ts
interface TimelineArrayEditorOptions {
  readonly runtime: StructuredEditorRuntime;
  readonly title: string;
  readonly range?: DataGridTimelineRange
}
```

---

### `TimelineArrayEditor`

Structured editor for Timeline event arrays.

```ts
class TimelineArrayEditor {
  getValue(): DataGridTimelineEvent[];

  componentDidRender(): void | Promise<void>;

  beforeAutoSave(): boolean;

  beforeDisconnect(): void;

  render(...args: Parameters<TextEditor['render']>): ReturnType<TextEditor['render']>;
}
```

---

### `moveTimelineEvent`

```ts
export function moveTimelineEvent(
  event: DataGridTimelineEvent,
  delta: number,
  range: DataGridTimelineRange,
): DataGridTimelineEvent;
```

---

### `niceTimelineStep`

```ts
export function niceTimelineStep(range: DataGridTimelineRange): number;
```

---

### `normalizeDataGridTimelineArray`

```ts
export function normalizeDataGridTimelineArray(value: unknown): DataGridTimelineEvent[] | undefined;
```

---

### `parseDataGridTimelineArray`

```ts
export function parseDataGridTimelineArray(
  value: unknown,
  fallback: readonly DataGridTimelineEvent[] = [],
): DataGridTimelineEvent[];
```

---

### `resizeTimelineEvent`

```ts
export function resizeTimelineEvent(
  event: DataGridTimelineEvent,
  edge: 'start' | 'end',
  delta: number,
  range: DataGridTimelineRange,
): DataGridTimelineEvent;
```

---

### `DataGridTimelineEvent` (Extended from `index.tsx`)

```ts
interface DataGridTimelineEvent {
  readonly start: number;
  readonly end: number;
  readonly label?: string
}
```

---

### `DataGridTimelineRange`

```ts
interface DataGridTimelineRange {
  readonly start: number;
  readonly end: number
}
```

---

### `createTimelineRow`

```ts
export function createTimelineRow(event: DataGridTimelineEvent): TimelineRow;
```

---

### `updateTimelineEvent`

```ts
export function updateTimelineEvent(
  rows: readonly TimelineRow[],
  id: number,
  event: DataGridTimelineEvent,
): TimelineRow[];
```

---

### `updateTimelineLabel`

```ts
export function updateTimelineLabel(
  rows: readonly TimelineRow[],
  id: number,
  label: string,
): TimelineRow[];
```

---

### `updateTimelineNumber`

```ts
export function updateTimelineNumber(
  rows: readonly TimelineRow[],
  id: number,
  key: 'start' | 'end',
  text: string,
): TimelineRow[];
```

---

### `reorderTimelineRows`

```ts
export function reorderTimelineRows(
  rows: readonly TimelineRow[],
  from: number,
  to: number,
): TimelineRow[] | undefined;
```

---

### `serializeTimelineRows`

```ts
export function serializeTimelineRows(rows: readonly TimelineRow[]): string;
```

---

### `validTimelineRow`

```ts
export function validTimelineRow(row: TimelineRow): boolean;
```

---

### `eventOutsideRange`

```ts
export function eventOutsideRange(
  event: DataGridTimelineEvent,
  range: DataGridTimelineRange,
): boolean;
```

---

### `timelineGeometry`

```ts
export function timelineGeometry(
  event: DataGridTimelineEvent,
  range: DataGridTimelineRange,
): { readonly left: number; readonly width: number };
```

---

### `TimelineRow`

```ts
interface TimelineRow {
  readonly id: number;
  readonly event: DataGridTimelineEvent;
  readonly startText: string;
  readonly endText: string
}
```

---

### `TimelinePointerMode`

```ts
export type TimelinePointerMode = 'move' | 'start' | 'end';
```

---

### `TimelinePanelIds`

```ts
interface TimelinePanelIds {
  readonly visualTab: string;
  readonly visualPanel: string;
  readonly rawTab: string;
  readonly rawPanel: string
}
```

---

### `TimelineEditorContent`

```ts
export function TimelineEditorContent({
  value,
  locale,
  onChange,
  onValidityChange,
  range,
}: TimelineEditorContentProps);
```

---

### `TimelineEventList`

```ts
export function TimelineEventList({
  rows,
  selected,
  range,
  locale,
  onRowsChange,
  onSelect,
}: TimelineEventListProps);
```

---

### `TimelineModeTabs`

```ts
export function TimelineModeTabs({ mode, ids, locale, onModeChange }: TimelineModeTabsProps);
```

---

### `TimelineEditorMode`

```ts
export type TimelineEditorMode = 'visual' | 'raw';
```

---

### `TimelineRawPanel`

```ts
export function TimelineRawPanel({
  id,
  labelledBy,
  raw,
  invalid,
  locale,
  onChange,
}: TimelineRawPanelProps);
```

---

### `TimelineTrack`

```ts
export function TimelineTrack({
  rows,
  selected,
  range,
  locale,
  onSelect,
  onEventChange,
}: TimelineTrackProps);
```

---

# Event Manager

URL: https://pro.rv-grid.com/api/event-manager/
Source: src/content/docs/api/event-manager.md

## Module Extensions

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data property for event manager
       * @deprecated Use `grid.eventManager` instead.
       *
       * @example
       * ```typescript
       * const grid = document.createElement('revo-grid');
       * grid.additionalData = { eventManager: { collectEvents: true, collectEventsDelay: 1000 } };
       * ```
       */
      eventManager?: EventManagerConfig
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /**
       * Direct event manager configuration.
       */
      eventManager?: EventManagerConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /**
       * Event for event manager
       *
       * @example
       * ```typescript
       * grid.addEventListener(ON_EDIT_EVENT, (event) => {
       *   console.log(event);
       * });
       * ```
       */
      [ON_EDIT_EVENT]: EventManagerEvent;
  [BEFORE_GRID_EDIT_RESOLVE_EVENT]: EventManagerEvent
}
```

## Plugin API

### `EventManagerPlugin`

RevoGrid Plugin for Event Manager.
Whole purpose is to collect and dispatch edit events in one place.

```ts
class EventManagerPlugin {
  /**
     * Adds a normalized edit produced by another plugin to EventManager's
     * collection pipeline.
     */
  collectEdit(detail: EventManagerEvent): void;

  /** Publishes any currently batched edit before a source-schema boundary. */
  flushCollectedEdits(): void;
}
```

---

### `EventManagerDomainChange`

A producer-defined semantic change carried by the unified edit stream.

```ts
interface EventManagerDomainChange {
  readonly type: TType;
  readonly detail: TDetail
}
```

---

### `EventManagerSourceMutation`

Identifies which layer already owns applying the event payload to source.

```ts
/** Identifies which layer already owns applying the event payload to source. */
export type EventManagerSourceMutation = 'event-manager' | 'producer';
```

---

### `EventManagerHistorySnapshot`

Replay-only state kept outside the ordinary grid row/field payload.

```ts
interface EventManagerHistorySnapshot {
  readonly before: T;
  readonly after: T
}
```

---

### `EventManagerHistory`

Keyed snapshots let independent producers compose in one history entry.

```ts
/** Keyed snapshots let independent producers compose in one history entry. */
export type EventManagerHistory = Record<string, EventManagerHistorySnapshot>;
```

---

### `EventManagerEvent` (Extended from `index.ts`)

```ts
export type EventManagerEvent<
  TDomainChange extends EventManagerDomainChange = EventManagerDomainChange,
> = {
  eventTypes: string[];
  previousData: BeforeRangeSaveDataDetails['data'];
  /** Ordered semantic changes contributed by feature plugins. */
  domainChanges?: TDomainChange[];
  /** Defaults to `event-manager`; producer-owned edits are observation-only. */
  sourceMutation?: EventManagerSourceMutation;
  /** Defaults to `true`; set to `false` to publish without creating a History entry. */
  recordHistory?: boolean;
  /** Domain-owned replay state. This is not applied through the grid data provider. */
  history?: EventManagerHistory;
  /** @internal Collection metadata for coordinates invalidated by topology changes. */
  invalidatedRowIndexes?: number[];
} & Omit<BeforeRangeSaveDataDetails, 'newRange' | 'oldRange'>
  & ClipboardValidationEditMetadata;
```

---

### `DataGridFormattingEventManagerEvent` (Extended from `index.ts`)

Unified EventManager entry for one formatting state transition.

```ts
/** Unified EventManager entry for one formatting state transition. */
export type DataGridFormattingEventManagerEvent = EventManagerEvent & {
  historyType: 'data-grid-formatting';
  formatting: {
    before: DataGridFormattingRuntimeState;
    after: DataGridFormattingRuntimeState;
  };
};
```

---

### `EventManagerConfig`

The configuration object for the EventManagerPlugin.

```ts
/**
 * The configuration object for the EventManagerPlugin.
 */
export type EventManagerConfig = {
  /**
   * Whether to collect events and apply delay or send them immediately.
   * @default false
   */
  collectEvents?: boolean;

  /**
   * The delay in milliseconds to wait until the
   * collected events are applied to the grid.
   * Used only when `collectEvents` is true.
   * @default 0
   */
  collectEventsDelay?: number;

  /**
   * Whether to apply the collected events to the
   * original data source.
   * @default true
   */
  applyEventsToSource?: boolean;
};
```

---

### `createEventManagerGridData`

Creates ordinary row/field patches only where a canonical entity retains the
same source index. Creates, deletes, and reorders remain domain changes.

```ts
export function createEventManagerGridData<T extends DataType>(
  options: CreateEventManagerGridDataOptions<T>,
): EventManagerGridData<T>;
```

---

### `CreateEventManagerGridDataOptions`

```ts
interface CreateEventManagerGridDataOptions {
  readonly previousRows: readonly T[];
  readonly rows: readonly T[];
  readonly getRowId: (row: T) => string | number | undefined;
  /** Restricts comparison to canonical indexes already known to be touched. */
    readonly rowIndexes?: readonly number[]
}
```

---

### `EventManagerGridData` (Extended from `index.ts`)

```ts
export type EventManagerGridData<T extends DataType = DataType> = Pick<
  EventManagerEvent,
  'data' | 'previousData' | 'models' | 'invalidatedRowIndexes'
> & {
  readonly data: Record<number, Partial<T>>;
  readonly previousData: Record<number, Partial<T>>;
  readonly models: Record<number, T>;
};
```

---

### `markEventManagerHistoryReplayHandled`

Marks a history replay that was successfully applied by its source owner.

```ts
export function markEventManagerHistoryReplayHandled(
  detail: HistoryReplayDetail,
  historyKeys?: readonly string[],
): void;
```

---

### `isEventManagerHistoryReplayHandled`

Distinguishes successful source replay from an application replay veto.

```ts
export function isEventManagerHistoryReplayHandled(
  detail: HistoryReplayDetail,
): boolean;
```

---

### `onEventManagerHistoryReplayHandled`

Runs after every keyed producer snapshot in a replay has been applied.

```ts
export function onEventManagerHistoryReplayHandled(
  detail: HistoryReplayDetail,
  listener: () => void,
): void;
```

---

### `markEventManagerEditIntercepted`

Marks a beforeedit whose native application was taken over by EventManager.

```ts
export function markEventManagerEditIntercepted(
  event: CustomEvent<BeforeSaveDataDetails>,
  completeUnifiedEdit: () => void,
): void;
```

---

### `isEventManagerEditIntercepted`

Distinguishes EventManager interception from a plain beforeedit veto.

```ts
export function isEventManagerEditIntercepted(detail: BeforeSaveDataDetails): boolean;
```

---

### `markEventManagerUnifiedEditOutcome`

Records the cancelable unified-edit outcome for an intercepted beforeedit.

```ts
export function markEventManagerUnifiedEditOutcome(
  detail: BeforeSaveDataDetails,
  accepted: boolean,
): void;
```

---

### `completeEventManagerInterceptedEdits`

Completes and returns the cancelable unified-edit outcome for a transaction.

```ts
export function completeEventManagerInterceptedEdits(
  details: BeforeSaveDataDetails[],
): boolean;
```

---

### `eventManagerValuesEqual`

```ts
export function eventManagerValuesEqual(left: unknown, right: unknown): boolean;
```

---

# Event Scheduler

URL: https://pro.rv-grid.com/api/event-scheduler/
Source: src/content/docs/api/event-scheduler.md

## Module Extensions

### `EventSchedulerConfig`

```ts
interface EventSchedulerConfig {
  /** Scheduler view. Day/week use a vertical time grid, month/year use calendar layouts, and resourceTimeline uses horizontal time. */
    readonly view?: EventSchedulerView;
  /** ISO date that anchors week/date generation. */
    readonly weekStartDate: string;
  /** Explicit visible date range for timeline modes. Month/year periods are derived from `weekStartDate`. */
    readonly dateRange?: EventSchedulerDateRange;
  /** IANA time zone identifier used by built-in date labels and time-zone aware flows.
     *
     * @example
     * ```ts
     * timeZone: 'Europe/Lisbon'
     * ```
     */
    readonly timeZone?: string;
  /** Locale used by default date/time labels.
     *
     * @example
     * ```ts
     * locale: 'pt-PT'
     * ```
     */
    readonly locale?: string;
  /** First day of the week, where `0` is Sunday and `1` is Monday. */
    readonly weekStartsOn?: number;
  /** Visible weekday indexes.
     *
     * Use this for business-days-only schedules or custom operating calendars.
     *
     * @example
     * ```ts
     * visibleDays: [1, 2, 3, 4, 5]
     * ```
     */
    readonly visibleDays?: readonly number[];
  /** Timeline slot size in minutes. Values below `15` are normalized to `15`.
     *
     * Use `15` or `30` for detailed shifts and `60` or `1440` for higher-level planning.
     */
    readonly slotMinutes?: number;
  /** Drag, resize, create, paste, and keyboard snapping interval in minutes.
     *
     * When omitted, the effective snap follows the active `slotMinutes`, including
     * runtime zoom changes. Set an explicit value when editing precision should
     * remain fixed while the visible timescale zooms.
     *
     * @example
     * ```ts
     * slotMinutes: 60,
     * snapMinutes: 15
     * ```
     */
    readonly snapMinutes?: number;
  /** Visible time-of-day window in `HH:mm` or AM/PM format. `end` can be `24:00`.
     *
     * @example
     * ```ts
     * timeRange: { start: '06:00', end: '22:00' }
     * timeRange: { start: '6 AM', end: '10 PM' }
     * ```
     */
    readonly timeRange?: EventSchedulerTimeRange;
  /** Scheduler timescale zoom levels, or `false` to disable zoom actions and methods. */
    readonly zoom?: boolean | EventSchedulerZoomConfig;
  /** Master edit switch.
     *
     * Set to `false` for read-only browsing while keeping scrolling, selection,
     * tooltips, and custom renderers active.
     */
    readonly editable?: boolean;
  /** Allows creation from slot/range interaction or API helpers. */
    readonly allowCreate?: boolean | ((context: EventSchedulerSlotContext) => boolean);
  /** Allows drag/drop time changes and resource reassignment. */
    readonly allowMove?: boolean | ((context: EventSchedulerPermissionContext) => boolean);
  /** Allows start/end resizing. */
    readonly allowResize?: boolean | ((context: EventSchedulerPermissionContext) => boolean);
  /** Allows delete actions from editor, keyboard, context menu, or API helpers. */
    readonly allowDelete?: boolean | ((context: EventSchedulerPermissionContext) => boolean);
  /** Allows assigning one event to multiple resources in the built-in editor.
     *
     * Defaults to `true`. Set to `false` to make the resource picker exclusive.
     * Custom editors and host-provided event data remain application-owned.
     */
    readonly allowMultiResourceAssignment?: boolean;
  /** Product access rules layered on top of `editable` and `allow*`. */
    readonly permissions?: EventSchedulerPermissionsConfig;
  /** Grouped visual customization hooks for column sizes, headers, cells, event sections, and create previews. */
    readonly customization?: EventSchedulerCustomizationConfig;
  /** Scheduler row height in pixels. */
    readonly rowSize?: number;
  /** Pinned time-column width in day/week views. */
    readonly timeColumnSize?: number;
  /** Day-column width in day/week views and the initial calendar-month column width before viewport fill sizing. */
    readonly dayColumnSize?: number;
  /** Pinned resource-column width in resource-timeline views. */
    readonly resourceColumnSize?: number;
  /** Timeline slot-column width in resource-timeline day, week, and custom ranges. */
    readonly timelineColumnSize?: number;
  /** Enables grouped scheduler headers. Defaults to true. */
    readonly columnGrouping?: boolean;
  /** Ordered resource-timeline header rows, from coarse to fine.
     *
     * Configure one to three rows. Sub-day timelines must end in `time`;
     * day-granularity timelines must end in `day`. When omitted, Scheduler
     * combines date context when a day spans multiple leaf columns and retains
     * separate month/day tiers when each day owns one column.
     *
     * @example
     * ```ts
     * timelineHeaderRows: [
     *   { id: 'day', unit: 'day' },
     *   { id: 'time', unit: 'time' },
     * ]
     * ```
     */
    readonly timelineHeaderRows?: readonly EventSchedulerTimelineHeaderRowConfig[];
  /** Visual layout mode for overlapping event blocks. */
    readonly eventLayout?: EventSchedulerEventLayout;
  /** Maximum stacked lanes before compact rendering should take over. */
    readonly maxStackedEvents?: number;
  /** Lane-count threshold for compact event content. */
    readonly compactThreshold?: number;
  /** Conflict detection and policy settings. */
    readonly conflicts?: EventSchedulerConflictConfig;
  /** Current-time marker configuration or `true` for defaults. */
    readonly currentTimeMarker?: boolean | EventSchedulerCurrentTimeMarkerConfig;
  /** Simple show/hide alias for the current-time marker. `currentTimeMarker.enabled` takes precedence when provided. */
    readonly showCurrentTimeMarker?: boolean;
  /** Live current-time refresh interval in milliseconds. Defaults to 60000. Set `0` to disable automatic live refresh. */
    readonly currentTimeUpdateInterval?: number;
  /** Per-day shift/event count in day headers. Enabled by default. */
    readonly dayHeaderShiftCount?: boolean | EventSchedulerDayHeaderShiftCountConfig;
  /** Today header/cell highlighting. Enabled by default. */
    readonly todayHighlight?: boolean | EventSchedulerTodayHighlightConfig;
  /** Weekend header/cell highlighting. Enabled by default for Saturday/Sunday. */
    readonly weekendHighlight?: boolean | EventSchedulerWeekendHighlightConfig;
  /** Built-in Scheduler context menus for event bars and empty cells. Enabled by default. */
    readonly contextMenu?: boolean | EventSchedulerContextMenuConfig;
  /** Built-in Scheduler keyboard shortcuts and shortcuts panel. Enabled by default. */
    readonly keyboardShortcuts?: boolean | EventSchedulerKeyboardShortcutsConfig;
  /** Cross-day continuation labels on event bars. Enabled by default. */
    readonly continuationLabels?: boolean | EventSchedulerContinuationLabelsConfig;
  /** Non-working day/time background settings. */
    readonly nonWorkingTime?: EventSchedulerNonWorkingTimeConfig;
  /** Working-hour alias for scheduler body availability. Supports global, day-filtered, and per-weekday ranges. */
    readonly workingHours?: EventSchedulerTimeRange | readonly EventSchedulerTimeRange[] | EventSchedulerWorkingHoursConfig;
  /** Closed-hour ranges such as lunch, maintenance, holidays, or blocked planning windows. */
    readonly closedHours?: EventSchedulerClosedHoursConfig | readonly EventSchedulerClosedHoursConfig[];
  /** Product-specific availability rules layered on top of working/closed hours. */
    readonly availabilityRules?: EventSchedulerAvailabilityRule | readonly EventSchedulerAvailabilityRule[];
  /** Named working calendars for global or per-resource working days/hours. */
    readonly calendars?: EventSchedulerCalendarsConfig;
  /** Resource grouping and tree settings. */
    readonly resourceGrouping?: EventSchedulerResourceGroupingConfig;
  /** Active resource/event/conflict/unassigned filters. */
    readonly filters?: EventSchedulerFilterState;
  /** Saved view definitions for reusable filter/range presets. */
    readonly savedViews?: EventSchedulerSavedViewsConfig;
  /** Active saved-view id when controlled by the host product. */
    readonly activeSavedViewId?: EventSchedulerEntityId;
  /** Selection, bulk action, range selection, and clipboard settings. */
    readonly selection?: EventSchedulerSelectionConfig;
  /** Alias for `selection.mode`. */
    readonly selectionMode?: EventSchedulerSelectionConfig['mode'];
  /** External clipboard adapter for product-owned copy/paste state. */
    readonly clipboardAdapter?: EventSchedulerClipboardAdapter;
  /** Reusable event templates for quick creation and recurrence. */
    readonly templates?: readonly EventSchedulerEventTemplateEntity[];
  /** Coverage requirement calculations and summaries. */
    readonly coverage?: EventSchedulerCoverageConfig;
  /** Resource/group workload and utilization calculations. */
    readonly utilization?: EventSchedulerUtilizationConfig;
  /** Unassigned-event row and assignment behavior. */
    readonly unassigned?: EventSchedulerUnassignedConfig;
  /** Remote loading, optimistic update, validation, and rollback hooks. */
    readonly remote?: EventSchedulerRemoteConfig;
  /** Empty-state text when no scheduler rows can be shown. */
    readonly emptyStateText?: string;
  /** i18n labels and label formatter overrides. */
    readonly labels?: Partial<EventSchedulerLabels>;
  /** Formats week-view day headers. */
    readonly dayHeaderFormatter?: (date: Date, dayIndex: number) => string;
  /** Replaces week/day/month day header content. `customization.headers.dayTemplate` takes precedence when both are provided. */
    readonly dayHeaderTemplate?: EventSchedulerHeaderCustomizationConfig['dayTemplate'];
  /** Adds classes, styles, attributes, data fields, or event handlers to week/day/month day headers. */
    readonly dayHeaderProperties?: (context: EventSchedulerHeaderContext) => EventSchedulerElementProps | undefined;
  /** Formats week-view time labels. */
    readonly timeLabelFormatter?: (minutes: number, slotIndex: number) => string;
  /** Replaces week/day/month pinned time-label cell content. `customization.cells.timeTemplate` takes precedence when both are provided. */
    readonly timeLabelTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerTimeCellContext) => EventSchedulerTemplateResult;
  /** Adds classes, styles, attributes, data fields, or event handlers to week/day/month pinned time-label cells. */
    readonly timeRowProperties?: (context: EventSchedulerTimeCellContext) => EventSchedulerElementProps | undefined;
  /** Replaces current-time marker content in week/day/month and resource-timeline cells. */
    readonly currentTimeMarkerTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerCurrentTimeMarkerContext) => EventSchedulerTemplateResult;
  /** Adds classes, styles, attributes, data fields, or event handlers to current-time marker cells. */
    readonly currentTimeMarkerProperties?: (context: EventSchedulerCurrentTimeMarkerContext) => EventSchedulerElementProps | undefined;
  /** Formats the current-time marker label. */
    readonly currentTimeLabelFormatter?: (context: EventSchedulerCurrentTimeMarkerContext) => string;
  /** Replaces empty week/resource-timeline slot content. Event bars remain rendered for occupied slots. */
    readonly slotTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerSlotRenderContext) => EventSchedulerTemplateResult;
  /** Replaces closed-slot content while preserving scheduler-owned event bars. */
    readonly closedSlotTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerClosedSlotContext) => EventSchedulerTemplateResult;
  /** Adds classes, styles, attributes, data fields, or event handlers to scheduler slot cells. */
    readonly slotProperties?: (context: EventSchedulerSlotRenderContext) => EventSchedulerElementProps | undefined;
  /** Adds classes, styles, attributes, data fields, or event handlers to closed scheduler slot cells. */
    readonly closedSlotProperties?: (context: EventSchedulerClosedSlotContext) => EventSchedulerElementProps | undefined;
  /** Formats the native tooltip/title for scheduler slot cells. */
    readonly slotTooltip?: (context: EventSchedulerSlotRenderContext) => string | undefined;
  /** Formats the native tooltip/title for closed scheduler slot cells. */
    readonly closedSlotTooltip?: (context: EventSchedulerClosedSlotContext) => string | undefined;
  /** Called when an empty scheduler slot is clicked, before built-in editor-open behavior. */
    readonly onSlotClick?: (context: EventSchedulerSlotRenderContext, event: MouseEvent) => void;
  /** Called when an empty scheduler slot is double-clicked. */
    readonly onSlotDoubleClick?: (context: EventSchedulerSlotRenderContext, event: MouseEvent) => void;
  /** Called when an empty scheduler slot context menu opens. */
    readonly onSlotContextMenu?: (context: EventSchedulerSlotRenderContext | (EventSchedulerSlotContext & { readonly resourceId?: EventSchedulerEntityId }), event: MouseEvent | null) => void;
  /** Marks scheduler slots as disabled for selection/create UX. Disabled slots do not open the built-in create editor. */
    readonly isSlotDisabled?: (context: EventSchedulerSlotRenderContext | (EventSchedulerSlotContext & { readonly resourceId?: EventSchedulerEntityId })) => boolean;
  /** Marks scheduler slots as non-selectable for pointer create/selection UX. */
    readonly isSlotSelectable?: (context: EventSchedulerSlotRenderContext | (EventSchedulerSlotContext & { readonly resourceId?: EventSchedulerEntityId })) => boolean;
  /** Product availability gate. Return `false` to mark a slot unavailable and block built-in creation. */
    readonly isTimeSlotAvailable?: (context: EventSchedulerSlotRenderContext | (EventSchedulerSlotContext & { readonly resourceId?: EventSchedulerEntityId })) => boolean | EventSchedulerAvailabilityRuleResult;
  /** Formats resource names in the pinned resource column. */
    readonly resourceLabelFormatter?: (resource: EventSchedulerResourceEntity) => string;
  /** Formats secondary resource metadata in the pinned resource column. */
    readonly resourceMetaFormatter?: (resource: EventSchedulerResourceEntity) => string | undefined;
  /** Formats resource-timeline header cells. */
    readonly timelineHeaderFormatter?: (context: EventSchedulerTimelineHeaderContext) => string;
  /** Formats the hover label shown over empty slots. */
    readonly hoverTimeFormatter?: (minutes: number, slotIndex: number, date: string) => string;
  /** Formats the drag-create range ghost label. */
    readonly createRangeFormatter?: (context: EventSchedulerCreateRangeDisplayContext) => string;
  /** Replaces the drag-create range ghost preview content. */
    readonly createRangeTemplate?: EventSchedulerCreateRangeTemplate;
  /** Creates deterministic ids for range-created events. */
    readonly createEventId?: (context: EventSchedulerCreateRangeContext) => EventSchedulerEntityId;
  /** Creates deterministic ids for pasted or duplicated events. */
    readonly createCopiedEventId?: (event: EventSchedulerEventEntity, context: { index: number; action: 'paste' | 'duplicate' }) => EventSchedulerEntityId;
  /** Creates deterministic ids for template-created events. */
    readonly createTemplateEventId?: (template: EventSchedulerEventTemplateEntity, context: { startDateTime: string; resourceId?: EventSchedulerEntityId }) => EventSchedulerEntityId;
  /** Creates deterministic ids for recurring template events. */
    readonly createRecurringEventId?: (template: EventSchedulerEventTemplateEntity, context: { index: number; seriesId: EventSchedulerEntityId; startDateTime: string; resourceId?: EventSchedulerEntityId }) => EventSchedulerEntityId;
  /** Builds the draft event used by drag-create or slot-create flows. */
    readonly createEventDraft?: (context: EventSchedulerCreateRangeContext) => EventSchedulerEventEntity | null | undefined;
  /** Custom editor hook, or `false` to disable the default editor. */
    readonly eventEditor?: false | EventSchedulerEventEditorHook;
  /** Opens the editor when an empty slot is clicked. */
    readonly eventEditorOpenOnSlotClick?: boolean;
  /** Opens the editor when an event is double-clicked. */
    readonly eventEditorOpenOnEventDoubleClick?: boolean;
  /** Status options shown by the default editor. */
    readonly eventEditorStatusOptions?: readonly (string | EventSchedulerEventEditorStatusOption)[];
  /** Adds classes, styles, attributes, data fields, or event handlers to event blocks. */
    readonly eventProperties?: (context: EventSchedulerEventSectionContext) => EventSchedulerElementProps | undefined;
  /** Replaces the default event block content renderer. */
    readonly eventTemplate?: EventSchedulerEventTemplate;
  /** Replaces the default event content section. `customization.events.content` takes precedence when both are provided. */
    readonly eventContentTemplate?: EventSchedulerEventSectionTemplate;
  /** Replaces individual event badges. `customization.events.badge` takes precedence when both are provided. */
    readonly eventBadgeTemplate?: EventSchedulerEventSectionTemplate<EventSchedulerEventBadgeContext>;
  /** Replaces event resize handle content. `customization.events.resizeHandle` takes precedence when both are provided. */
    readonly eventResizeHandleTemplate?: EventSchedulerEventSectionTemplate<EventSchedulerEventResizeHandleContext>;
  /** Overrides event tooltip text. `customization.events.tooltip` takes precedence when both are provided. */
    readonly eventTooltipTemplate?: (context: EventSchedulerEventSectionContext) => string | undefined;
  /** Formats tooltip text for event blocks. */
    readonly tooltipFormatter?: (context: EventSchedulerEventSectionContext) => string | undefined;
  /** Resolves event accent colors from status/type/business data. */
    readonly statusColorResolver?: (event: EventSchedulerEventEntity) => string | undefined;
  /** Sorts events before lane placement and rendering. */
    readonly eventSort?: (left: EventSchedulerEventEntity, right: EventSchedulerEventEntity) => number;
  /** Filters resources before projection. */
    readonly resourceFilter?: (resource: EventSchedulerResourceEntity) => boolean;
  /** Label for the synthetic unassigned-demand row. */
    readonly unassignedResourceLabel?: string;
  /** Cancellable hook before event creation. Return `false` or a string message to cancel. */
    readonly beforeEventCreate?: (detail: EventSchedulerBeforeEventChangeDetail) => boolean | string | void;
  /** Cancellable hook before generic event updates from editor/API/status changes. */
    readonly beforeEventUpdate?: (detail: EventSchedulerBeforeEventChangeDetail) => boolean | string | void;
  /** Cancellable hook before event move. */
    readonly beforeEventMove?: (detail: EventSchedulerBeforeEventChangeDetail) => boolean | string | void;
  /** Cancellable hook before event resize. */
    readonly beforeEventResize?: (detail: EventSchedulerBeforeEventChangeDetail) => boolean | string | void;
  /** Cancellable hook before event delete. */
    readonly beforeEventDelete?: (detail: EventSchedulerBeforeEventChangeDetail) => boolean | string | void;
  /** Cancellable hook before event duplicate. */
    readonly beforeEventDuplicate?: (detail: EventSchedulerBeforeEventChangeDetail) => boolean | string | void;
  /** Cancellable hook before event lock/unlock. */
    readonly beforeEventLock?: (detail: EventSchedulerBeforeEventChangeDetail) => boolean | string | void;
  /** Cancellable hook before a slot is selected/click-selected. */
    readonly beforeSlotSelect?: (detail: EventSchedulerBeforeSlotSelectDetail) => boolean | string | void;
  /** Final callback after event creation. */
    readonly onEventCreate?: (detail: EventSchedulerEventChangedDetail) => void;
  /** Final callback after generic event update. */
    readonly onEventUpdate?: (detail: EventSchedulerEventChangedDetail) => void;
  /** Final callback after event move. */
    readonly onEventMove?: (detail: EventSchedulerEventChangedDetail) => void;
  /** Final callback after event resize. */
    readonly onEventResize?: (detail: EventSchedulerEventChangedDetail) => void;
  /** Final callback after event delete. */
    readonly onEventDelete?: (detail: EventSchedulerEventDeletedDetail) => void;
  /** Final callback after event duplicate. */
    readonly onEventDuplicate?: (detail: EventSchedulerEventChangedDetail) => void;
  /** Final callback after event copy. */
    readonly onEventCopy?: (detail: EventSchedulerEventCopiedDetail) => void;
  /** Alias for `onEventCopy`. */
    readonly onCopy?: (detail: EventSchedulerEventCopiedDetail) => void;
  /** Final callback after pasted events are created. */
    readonly onEventPaste?: (detail: EventSchedulerEventChangedDetail) => void;
  /** Alias for `onEventPaste`. */
    readonly onPaste?: (detail: EventSchedulerEventChangedDetail) => void;
  /** Alias for `onEventDuplicate`. */
    readonly onDuplicate?: (detail: EventSchedulerEventChangedDetail) => void;
  /** Final callback after event lock/unlock. */
    readonly onEventLock?: (detail: EventSchedulerEventChangedDetail) => void;
  /** Final callback after event selection changes. */
    readonly onSelectionChange?: (detail: EventSchedulerEventSelectedDetail) => void;
  /** Final callback after slot selection/click-selection. */
    readonly onSlotSelect?: (detail: EventSchedulerSlotSelectedDetail) => void;
  /** Final synchronous validation before local mutation commit. */
    readonly validateMutation?: (detail: EventSchedulerBeforeEventChangeDetail) => boolean | string | void
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [EVENT_SCHEDULER_BEFORE_EVENT_CHANGE_EVENT]: EventSchedulerBeforeEventChangeDetail;
  [EVENT_SCHEDULER_BEFORE_EVENT_SELECT_EVENT]: EventSchedulerEventSelectedDetail;
  [EVENT_SCHEDULER_BEFORE_SLOT_SELECT_EVENT]: EventSchedulerBeforeSlotSelectDetail;
  [EVENT_SCHEDULER_EVENT_CREATED_EVENT]: EventSchedulerEventChangedDetail;
  [EVENT_SCHEDULER_EVENT_CHANGED_EVENT]: EventSchedulerEventChangedDetail;
  [EVENT_SCHEDULER_EVENT_DELETED_EVENT]: EventSchedulerEventDeletedDetail;
  [EVENT_SCHEDULER_EVENT_SELECTED_EVENT]: EventSchedulerEventSelectedDetail;
  [EVENT_SCHEDULER_SLOT_CLICK_EVENT]: EventSchedulerSlotClickDetail;
  [EVENT_SCHEDULER_CONFLICTS_UPDATED_EVENT]: EventSchedulerConflictsUpdatedDetail;
  [EVENT_SCHEDULER_REMOTE_LOAD_START_EVENT]: EventSchedulerRemoteLoadDetail;
  [EVENT_SCHEDULER_REMOTE_LOAD_SUCCESS_EVENT]: EventSchedulerRemoteLoadDetail;
  [EVENT_SCHEDULER_REMOTE_LOAD_ERROR_EVENT]: EventSchedulerRemoteLoadDetail;
  [EVENT_SCHEDULER_REMOTE_MUTATION_PENDING_EVENT]: EventSchedulerRemoteMutationDetail;
  [EVENT_SCHEDULER_REMOTE_MUTATION_COMMITTED_EVENT]: EventSchedulerRemoteMutationDetail;
  [EVENT_SCHEDULER_REMOTE_MUTATION_REJECTED_EVENT]: EventSchedulerRemoteMutationDetail;
  [EVENT_SCHEDULER_REMOTE_STATE_CHANGE_EVENT]: EventSchedulerRemoteStateChangeDetail;
  [EVENT_SCHEDULER_NAVIGATE_REQUEST_EVENT]: EventSchedulerNavigateRequestDetail;
  [EVENT_SCHEDULER_VIEW_REQUEST_EVENT]: EventSchedulerViewRequestDetail;
  [EVENT_SCHEDULER_RESOURCE_REASSIGN_REQUEST_EVENT]: EventSchedulerResourceReassignRequestDetail;
  [EVENT_SCHEDULER_OPEN_SHIFT_ASSIGN_REQUEST_EVENT]: EventSchedulerOpenShiftAssignRequestDetail;
  [EVENT_SCHEDULER_SEARCH_FOCUS_REQUEST_EVENT]: EventSchedulerSearchFocusRequestDetail
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  eventScheduler?: EventSchedulerConfig;
  eventSchedulerResources?: readonly EventSchedulerResourceEntity[];
  eventSchedulerAssignments?: readonly EventSchedulerAssignmentEntity[];
  eventSchedulerAvailability?: readonly EventSchedulerAvailabilityEntity[];
  eventSchedulerTemplates?: readonly EventSchedulerEventTemplateEntity[];
  eventSchedulerCoverageRequirements?: readonly EventSchedulerCoverageRequirementEntity[]
}
```

## Plugin API

### `DEFAULT_EVENT_SCHEDULER_TIME_RANGE`

```ts
DEFAULT_EVENT_SCHEDULER_TIME_RANGE: {
  start: string;
  end: string;
};
```

---

### `normalizeSchedulerConfig`

```ts
export function normalizeSchedulerConfig(config: EventSchedulerConfig): EventSchedulerResolvedConfig;
```

---

### `EventSchedulerPlugin`

Scheduler plugin for week and resource-timeline planning.

Register it in `grid.plugins`, provide events through the standard grid `source`,
then drive related data through side-channel props: `eventSchedulerResources`,
`eventSchedulerAssignments`, `eventSchedulerAvailability`, and
`eventSchedulerCoverageRequirements`.

**Example:**
```typescript
const grid = document.querySelector('revo-grid');
grid.plugins = [EventSchedulerPlugin];
grid.eventScheduler = {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  allowCreate: true
};
grid.eventSchedulerResources = [{ id: 'room-a', name: 'Room A' }];
grid.source = [{
  id: 'booking-1',
  resourceId: 'room-a',
  title: 'Booking',
  startDateTime: '2026-06-08T09:00:00.000Z',
  endDateTime: '2026-06-08T10:00:00.000Z'
}];
```

#### Dependencies

- **Auto-installed** `EventManagerPlugin`, `HistoryPlugin`, `TooltipPlugin`, `ContextMenuPlugin`, `RowZIndexPlugin`: Installs shared Pro infrastructure for Event Scheduler edits, history, tooltips, menus, and row stacking when absent.
- **Auto-installed** `FilterPlugin`: Installs core filtering while Scheduler exposes the Resource column filter.
- **Event integration** `BEFORE_HEADER_RENDER_EVENT`: Keeps generated Scheduler time-axis columns at their configured widths.
- **Event integration** `BEFORE_GROUP_HEADER_RENDER_EVENT`: Keeps generated Scheduler time-axis header groups at their configured widths.

```ts
class EventSchedulerPlugin {
  /** Returns whether the Scheduler can move to a finer time-slot granularity. */
  canZoomIn(): boolean;

  /** Returns whether the Scheduler can move to a coarser time-slot granularity. */
  canZoomOut(): boolean;

  /** Moves to the next finer time-slot granularity. */
  zoomIn(): boolean;

  /** Moves to the next coarser time-slot granularity. */
  zoomOut(): boolean;

  /** Returns the active projected time-slot granularity. */
  getZoomSlotMinutes(): number | null;

  /** Creates an event through the scheduler mutation pipeline.
     *
     * The call respects `editable`, `allowCreate`, `permissions`, conflicts,
     * cancelable before-change events, and remote optimistic commit hooks.
     */
  createEvent(event: EventSchedulerEventEntity): EventSchedulerEventEntity;

  /** Updates an event by id and returns the updated entity. */
  editEvent(eventId: EventSchedulerEntityId, changes: EventSchedulerEventEditChanges): EventSchedulerEventEntity;

  /** Deletes an event by id when delete permissions and validation allow it. */
  deleteEvent(eventId: EventSchedulerEntityId): void;

  /** Returns the current event selection as stable event ids. */
  getSelectedEventIds(): readonly EventSchedulerEntityId[];

  /** Replaces the current event selection and returns the normalized selected ids. */
  setSelectedEventIds(eventIds: readonly EventSchedulerEntityId[]): readonly EventSchedulerEntityId[];

  /** Returns the currently selected slot, when an empty scheduler slot is selected. */
  getSelectedSlot(): (EventSchedulerSlotContext & { readonly resourceId?: EventSchedulerEntityId }) | null;

  /** Sets the selected slot from host-provided state. */
  setSelectedSlot(slot: (EventSchedulerSlotContext & { readonly resourceId?: EventSchedulerEntityId }) | null): void;

  /** Returns the currently selected time range, usually from drag-create or slot create context. */
  getSelectedRange(): EventSchedulerCreateRangeContext | null;

  /** Sets the selected time range from host-provided state. */
  setSelectedRange(range: EventSchedulerCreateRangeContext | null): void;

  /** Clears the current scheduler event selection. */
  clearSelectedEvents(): void;

  /** Copies selected events into the scheduler clipboard payload and browser clipboard when available. */
  copySelectedEvents(): EventSchedulerClipboardPayload | null;

  /**
     * Pastes copied events, optionally overriding target start/resource.
     *
     * The target base follows the active projection snap interval, including an
     * implicit snap interval changed by runtime Scheduler zoom.
     */
  pasteCopiedEvents(options: EventSchedulerPasteOptions = {}): readonly EventSchedulerEventEntity[];

  /** Duplicates selected events by an offset in days. */
  duplicateSelectedEvents(offsetDays?: number): readonly EventSchedulerEventEntity[];

  /** Copies every event in a source date range into a target date range. */
  duplicateScheduleRange(options: EventSchedulerDuplicateRangeOptions): readonly EventSchedulerEventEntity[];

  /** Returns configured scheduler templates. */
  getTemplates(): readonly EventSchedulerEventTemplateEntity[];

  /** Creates one event from a reusable template. */
  createEventFromTemplate(options: EventSchedulerTemplateCreateOptions): readonly EventSchedulerEventEntity[];

  /** Expands a template into daily or weekly recurring events. */
  createRecurringEvents(options: EventSchedulerRecurrenceCreateOptions): readonly EventSchedulerEventEntity[];

  /** Applies a change to all matching events in a recurrence series. */
  editRecurrenceSeries(options: EventSchedulerRecurrenceSeriesEditOptions): readonly EventSchedulerEventEntity[];

  /** Deletes all matching events in a recurrence series. */
  deleteRecurrenceSeries(options: EventSchedulerRecurrenceSeriesDeleteOptions): void;

  /** Deletes all selected events when bulk delete is permitted. */
  bulkDeleteSelectedEvents(): void;

  /** Updates the status of all selected events. */
  bulkUpdateSelectedEventStatus(status: string): readonly EventSchedulerEventEntity[];

  /** Returns the latest normalized projection used for rows, columns, segments, and summaries. */
  getProjection(): EventSchedulerProjection | null;

  /** Returns current remote loading, error, pending, and pagination state. */
  getRemoteState(): EventSchedulerRemoteState;

  /** Forces remote mode to reload the current visible date/resource range. */
  async refreshVisibleRange(): Promise<void>;

  /** Requests the next remote resource page when progressive resource loading is enabled. */
  async loadMoreResources(): Promise<void>;

  /** Exports currently visible/filtered scheduler events as CSV or JSON. */
  exportEvents(options: EventSchedulerExportOptions = {}): EventSchedulerExportResult;

  /** Exports resource workload and utilization rows for the current projection. */
  exportResourceWorkload(options: EventSchedulerExportOptions = {}): EventSchedulerExportResult;

  /** Exports current conflict rows as CSV or JSON. */
  exportConflicts(options: EventSchedulerExportOptions = {}): EventSchedulerExportResult;

  /** Exports coverage gaps by default, or all coverage requirements when `gapsOnly` is false. */
  exportCoverage(options: EventSchedulerCoverageExportOptions = {}): EventSchedulerExportResult;

  /** Exports visible event segments, including clipped/split schedule geometry. */
  exportVisibleSchedule(options: EventSchedulerExportOptions = {}): EventSchedulerExportResult;

  /** Creates a print-friendly scheduler HTML document without mutating the grid. */
  createPrintView(options: EventSchedulerPrintOptions = {}): EventSchedulerPrintResult;
}
```

---

### `EVENT_SCHEDULER_BEFORE_EVENT_CHANGE_EVENT`

```ts
EVENT_SCHEDULER_BEFORE_EVENT_CHANGE_EVENT: string;
```

---

### `EVENT_SCHEDULER_BEFORE_EVENT_SELECT_EVENT`

```ts
EVENT_SCHEDULER_BEFORE_EVENT_SELECT_EVENT: string;
```

---

### `EVENT_SCHEDULER_BEFORE_SLOT_SELECT_EVENT`

```ts
EVENT_SCHEDULER_BEFORE_SLOT_SELECT_EVENT: string;
```

---

### `EVENT_SCHEDULER_EVENT_CREATED_EVENT`

```ts
EVENT_SCHEDULER_EVENT_CREATED_EVENT: string;
```

---

### `EVENT_SCHEDULER_EVENT_CHANGED_EVENT`

```ts
EVENT_SCHEDULER_EVENT_CHANGED_EVENT: string;
```

---

### `EVENT_SCHEDULER_EVENT_DELETED_EVENT`

```ts
EVENT_SCHEDULER_EVENT_DELETED_EVENT: string;
```

---

### `EVENT_SCHEDULER_EVENT_SELECTED_EVENT`

```ts
EVENT_SCHEDULER_EVENT_SELECTED_EVENT: string;
```

---

### `EVENT_SCHEDULER_SLOT_CLICK_EVENT`

```ts
EVENT_SCHEDULER_SLOT_CLICK_EVENT: string;
```

---

### `EVENT_SCHEDULER_CONFLICTS_UPDATED_EVENT`

```ts
EVENT_SCHEDULER_CONFLICTS_UPDATED_EVENT: string;
```

---

### `EVENT_SCHEDULER_REMOTE_LOAD_START_EVENT`

```ts
EVENT_SCHEDULER_REMOTE_LOAD_START_EVENT: string;
```

---

### `EVENT_SCHEDULER_REMOTE_LOAD_SUCCESS_EVENT`

```ts
EVENT_SCHEDULER_REMOTE_LOAD_SUCCESS_EVENT: string;
```

---

### `EVENT_SCHEDULER_REMOTE_LOAD_ERROR_EVENT`

```ts
EVENT_SCHEDULER_REMOTE_LOAD_ERROR_EVENT: string;
```

---

### `EVENT_SCHEDULER_REMOTE_MUTATION_PENDING_EVENT`

```ts
EVENT_SCHEDULER_REMOTE_MUTATION_PENDING_EVENT: string;
```

---

### `EVENT_SCHEDULER_REMOTE_MUTATION_COMMITTED_EVENT`

```ts
EVENT_SCHEDULER_REMOTE_MUTATION_COMMITTED_EVENT: string;
```

---

### `EVENT_SCHEDULER_REMOTE_MUTATION_REJECTED_EVENT`

```ts
EVENT_SCHEDULER_REMOTE_MUTATION_REJECTED_EVENT: string;
```

---

### `EVENT_SCHEDULER_REMOTE_STATE_CHANGE_EVENT`

```ts
EVENT_SCHEDULER_REMOTE_STATE_CHANGE_EVENT: string;
```

---

### `EVENT_SCHEDULER_NAVIGATE_REQUEST_EVENT`

```ts
EVENT_SCHEDULER_NAVIGATE_REQUEST_EVENT: string;
```

---

### `EVENT_SCHEDULER_VIEW_REQUEST_EVENT`

```ts
EVENT_SCHEDULER_VIEW_REQUEST_EVENT: string;
```

---

### `EVENT_SCHEDULER_RESOURCE_REASSIGN_REQUEST_EVENT`

```ts
EVENT_SCHEDULER_RESOURCE_REASSIGN_REQUEST_EVENT: string;
```

---

### `EVENT_SCHEDULER_OPEN_SHIFT_ASSIGN_REQUEST_EVENT`

```ts
EVENT_SCHEDULER_OPEN_SHIFT_ASSIGN_REQUEST_EVENT: string;
```

---

### `EVENT_SCHEDULER_SEARCH_FOCUS_REQUEST_EVENT`

```ts
EVENT_SCHEDULER_SEARCH_FOCUS_REQUEST_EVENT: string;
```

---

### `EventSchedulerView`

```ts
export type EventSchedulerView = 'day' | 'week' | 'month' | 'year' | 'resourceTimeline';
```

---

### `EventSchedulerProjectionLayout`

```ts
export type EventSchedulerProjectionLayout = 'timeGrid' | 'resourceTimeline' | 'calendarMonth' | 'calendarYear';
```

---

### `EventSchedulerEventLayout`

```ts
export type EventSchedulerEventLayout = 'stack' | 'overlap' | 'compact';
```

---

### `EventSchedulerConflictPolicy`

```ts
export type EventSchedulerConflictPolicy = 'mark' | 'prevent' | 'allow';
```

---

### `EventSchedulerConflictScope`

```ts
export type EventSchedulerConflictScope = 'same-resource' | 'global';
```

---

### `EventSchedulerConflictType`

```ts
export type EventSchedulerConflictType =
  | 'overlap'
  | 'outside-availability'
  | 'blocked-time'
  | 'missing-resource'
  | 'invalid-duration'
  | 'locked-change'
  | 'resource-over-capacity'
  | 'duplicate-assignment';
```

---

### `EventSchedulerConflictSeverity`

```ts
export type EventSchedulerConflictSeverity = 'warning' | 'error' | 'confirm';
```

---

### `EventSchedulerConflictRulePolicy`

```ts
export type EventSchedulerConflictRulePolicy = EventSchedulerConflictSeverity | 'allow' | 'ignore';
```

---

### `EventSchedulerMutationAction`

```ts
export type EventSchedulerMutationAction =
  | 'create'
  | 'move'
  | 'resize'
  | 'edit'
  | 'delete'
  | 'bulk-move'
  | 'bulk-edit'
  | 'bulk-delete'
  | 'paste'
  | 'duplicate'
  | 'template-create'
  | 'recurrence-create'
  | 'recurrence-edit-series'
  | 'recurrence-delete-series';
```

---

### `EventSchedulerResizeEdge`

```ts
export type EventSchedulerResizeEdge = 'start' | 'end';
```

---

### `EventSchedulerStatus`

```ts
export type EventSchedulerStatus = 'draft' | 'planned' | 'confirmed' | 'completed' | 'cancelled' | 'blocked';
```

---

### `EventSchedulerAvailabilityKind`

```ts
export type EventSchedulerAvailabilityKind = 'working' | 'blocked' | 'holiday' | 'break';
```

---

### `EventSchedulerEntityId`

```ts
export type EventSchedulerEntityId = string | number;
```

---

### `EventSchedulerTimeRange`

Time-of-day range in `HH:mm` or AM/PM format. `24:00` is accepted for `end`.

```ts
interface EventSchedulerTimeRange {
  readonly start: string;
  readonly end: string
}
```

---

### `EventSchedulerDateRange`

Inclusive start and exclusive end date range used by timeline and remote loading APIs.

```ts
interface EventSchedulerDateRange {
  readonly start: string;
  readonly end: string
}
```

---

### `EventSchedulerCurrentTimeMarkerConfig`

```ts
interface EventSchedulerCurrentTimeMarkerConfig {
  readonly enabled?: boolean;
  readonly dateTime?: string;
  readonly className?: string
}
```

---

### `EventSchedulerResolvedCurrentTimeMarkerConfig`

```ts
interface EventSchedulerResolvedCurrentTimeMarkerConfig {
  readonly enabled: boolean;
  readonly dateTime?: string;
  readonly className?: string
}
```

---

### `EventSchedulerNonWorkingTimeConfig`

```ts
interface EventSchedulerNonWorkingTimeConfig {
  /** Enables non-working day/hour marking. Defaults to true. */
    readonly enabled?: boolean;
  /**
     * Working weekdays using JavaScript indexes, where Sunday is 0 and Saturday is 6.
     * Days outside this set are marked as closed when no calendar overrides the slot.
     */
    readonly workingDays?: readonly number[];
  /**
     * Working time windows inside visible scheduler days. Slots outside these windows
     * are marked as closed/outside working hours and receive non-working styling.
     */
    readonly workingHours?: EventSchedulerTimeRange | readonly EventSchedulerTimeRange[];
  /** Optional CSS class applied to non-working cells. */
    readonly className?: string
}
```

---

### `EventSchedulerCalendarsConfig`

```ts
interface EventSchedulerCalendarsConfig {
  /** Enables named calendar resolution. Defaults to true when calendars are provided. */
    readonly enabled?: boolean;
  /** Shared calendar id used when a resource has no calendar override. */
    readonly primaryCalendarId?: CalendarId;
  /** Shared Gantt/Scheduler calendars. Working days use ISO weekdays: 1 = Monday ... 7 = Sunday. */
    readonly calendars?: readonly CalendarEntity[];
  /** Optional resolver for resource-specific shared calendars. */
    readonly resourceCalendarId?: (resource: { readonly id: EventSchedulerEntityId; readonly calendarId?: CalendarId; readonly metadata?: Record<string, unknown> }) => CalendarId | undefined;
  readonly className?: string
}
```

---

### `EventSchedulerResolvedWorkingHoursRange`

```ts
export type EventSchedulerResolvedWorkingHoursRange = CalendarResolvedWorkingTimeRange;
```

---

### `EventSchedulerResolvedNonWorkingTimeConfig`

```ts
interface EventSchedulerResolvedNonWorkingTimeConfig {
  readonly enabled: boolean;
  readonly workingDays: readonly number[];
  readonly workingHours: readonly EventSchedulerResolvedWorkingHoursRange[];
  readonly className?: string
}
```

---

### `EventSchedulerResolvedCalendarEntity`

```ts
export type EventSchedulerResolvedCalendarEntity = ResolvedCalendarEntity;
```

---

### `EventSchedulerResolvedCalendarsConfig`

```ts
interface EventSchedulerResolvedCalendarsConfig {
  readonly enabled: boolean;
  readonly primaryCalendarId?: CalendarId;
  readonly items: ReadonlyMap<string, EventSchedulerResolvedCalendarEntity>;
  readonly resourceCalendarId?: EventSchedulerCalendarsConfig['resourceCalendarId'];
  readonly className?: string
}
```

---

### `EventSchedulerEventEntity`

```ts
interface EventSchedulerEventEntity {
  readonly id: EventSchedulerEntityId;
  readonly resourceId?: EventSchedulerEntityId;
  readonly resourceIds?: readonly EventSchedulerEntityId[];
  readonly assignmentIds?: readonly EventSchedulerEntityId[];
  readonly title?: string;
  readonly startDateTime: string;
  readonly endDateTime: string;
  readonly status?: EventSchedulerStatus | string;
  readonly type?: string;
  readonly category?: string;
  readonly locked?: boolean;
  readonly readonly?: boolean;
  readonly notes?: string;
  readonly color?: string;
  readonly className?: string;
  readonly recurrenceId?: EventSchedulerEntityId;
  readonly recurrenceSeriesId?: EventSchedulerEntityId;
  readonly recurrenceOccurrenceDate?: string;
  readonly recurrenceException?: 'edited' | 'deleted';
  readonly metadata?: Record<string, unknown>
}
```

---

### `EventSchedulerEventEditChanges` (Extended from `index.ts`)

```ts
export type EventSchedulerEventEditChanges =
  Partial<Omit<EventSchedulerEventEntity, 'resourceId' | 'resourceIds' | 'color'>> & {
    readonly resourceId?: EventSchedulerEntityId | null;
    readonly resourceIds?: readonly EventSchedulerEntityId[] | null;
    /** A palette color, or `null` to restore inherited/status coloring. */
    readonly color?: string | null;
  };
```

---

### `EventSchedulerRecurrenceFrequency`

```ts
export type EventSchedulerRecurrenceFrequency = 'daily' | 'weekly';
```

---

### `EventSchedulerRecurrenceRule`

```ts
interface EventSchedulerRecurrenceRule {
  readonly frequency: EventSchedulerRecurrenceFrequency;
  readonly interval?: number;
  readonly weekdays?: readonly number[];
  readonly count?: number;
  readonly untilDateTime?: string
}
```

---

### `EventSchedulerEventTemplateEntity`

Reusable event shape used by template and recurrence helpers.

```ts
interface EventSchedulerEventTemplateEntity {
  readonly id: EventSchedulerEntityId;
  readonly title: string;
  readonly durationMinutes: number;
  readonly resourceId?: EventSchedulerEntityId;
  readonly resourceIds?: readonly EventSchedulerEntityId[];
  readonly status?: EventSchedulerStatus | string;
  readonly type?: string;
  readonly category?: string;
  readonly locked?: boolean;
  readonly readonly?: boolean;
  readonly notes?: string;
  readonly color?: string;
  readonly className?: string;
  readonly metadata?: Record<string, unknown>
}
```

---

### `EventSchedulerTemplateCreateOptions`

```ts
interface EventSchedulerTemplateCreateOptions {
  readonly templateId: EventSchedulerEntityId;
  readonly startDateTime: string;
  readonly resourceId?: EventSchedulerEntityId;
  readonly title?: string;
  readonly status?: EventSchedulerStatus | string;
  readonly metadata?: Record<string, unknown>
}
```

---

### `EventSchedulerRecurrenceCreateOptions` (Extended from `index.ts`)

```ts
interface EventSchedulerRecurrenceCreateOptions {
  readonly recurrence: EventSchedulerRecurrenceRule;
  readonly seriesId?: EventSchedulerEntityId
}
```

---

### `EventSchedulerRecurrenceSeriesEditOptions`

```ts
interface EventSchedulerRecurrenceSeriesEditOptions {
  readonly seriesId: EventSchedulerEntityId;
  readonly changes: Partial<EventSchedulerEventEntity>;
  readonly includeExceptions?: boolean
}
```

---

### `EventSchedulerRecurrenceSeriesDeleteOptions`

```ts
interface EventSchedulerRecurrenceSeriesDeleteOptions {
  readonly seriesId: EventSchedulerEntityId;
  readonly includeExceptions?: boolean
}
```

---

### `EventSchedulerSelectionConfig`

```ts
interface EventSchedulerSelectionConfig {
  readonly mode?: 'single' | 'multiple' | 'range';
  readonly selectedEventIds?: readonly EventSchedulerEntityId[];
  readonly selectedSlot?: EventSchedulerSlotContext & { readonly resourceId?: EventSchedulerEntityId };
  readonly selectedRange?: EventSchedulerCreateRangeContext;
  readonly multi?: boolean;
  readonly range?: boolean;
  readonly bulkActions?: boolean;
  readonly clipboard?: boolean;
  readonly copyOffsetDays?: number;
  readonly onChange?: (detail: EventSchedulerEventSelectedDetail) => void
}
```

---

### `EventSchedulerClipboardAdapter`

```ts
interface EventSchedulerClipboardAdapter {
  readonly read?: () => EventSchedulerClipboardPayload | null | undefined | Promise<EventSchedulerClipboardPayload | null | undefined>;
  readonly write?: (payload: EventSchedulerClipboardPayload) => void | Promise<void>;
  readonly clear?: () => void | Promise<void>;
  readonly hasPayload?: () => boolean
}
```

---

### `EventSchedulerCopiedEvent`

```ts
interface EventSchedulerCopiedEvent {
  readonly event: EventSchedulerEventEntity;
  readonly offsetMinutes: number
}
```

---

### `EventSchedulerClipboardPayload`

```ts
interface EventSchedulerClipboardPayload {
  readonly type: 'event-scheduler-events';
  readonly version: 1;
  readonly copiedAt: string;
  readonly baseStartDateTime: string;
  readonly events: readonly EventSchedulerCopiedEvent[]
}
```

---

### `EventSchedulerPasteOptions`

```ts
interface EventSchedulerPasteOptions {
  /** Requested target base. Scheduler snaps it to the active edit interval. */
    readonly startDateTime?: string;
  /** Optional resource override applied to every pasted event. */
    readonly resourceId?: EventSchedulerEntityId;
  /** Optional suffix used while generating collision-free copied event ids. */
    readonly idSuffix?: string
}
```

---

### `EventSchedulerDuplicateRangeOptions`

```ts
interface EventSchedulerDuplicateRangeOptions {
  readonly sourceStartDateTime: string;
  readonly sourceEndDateTime: string;
  readonly targetStartDateTime: string;
  readonly resourceIds?: readonly EventSchedulerEntityId[]
}
```

---

### `EventSchedulerResourceEntity`

Resource row in resource-timeline mode.

A resource can represent a person, room, vehicle, machine, location, team, or any
other schedulable capacity. `locked`, `readonly`, or `disabled` resources reject
create/drop/reassign actions.

```ts
interface EventSchedulerResourceEntity {
  readonly id: EventSchedulerEntityId;
  readonly parentId?: EventSchedulerEntityId;
  readonly name: string;
  /** Optional profile image URL used by the built-in resource cell. */
    readonly avatarUrl?: string;
  readonly role?: string;
  readonly group?: string;
  readonly color?: string;
  readonly calendarId?: CalendarId;
  readonly capacity?: number;
  readonly disabled?: boolean;
  readonly locked?: boolean;
  readonly readonly?: boolean;
  readonly hidden?: boolean;
  readonly active?: boolean;
  readonly metadata?: Record<string, unknown>
}
```

---

### `EventSchedulerCoverageStatus`

```ts
export type EventSchedulerCoverageStatus = 'under' | 'met' | 'over';
```

---

### `EventSchedulerCoverageRequirementEntity`

Required capacity or headcount over a time range for coverage planning.

```ts
interface EventSchedulerCoverageRequirementEntity {
  readonly id: EventSchedulerEntityId;
  readonly startDateTime: string;
  readonly endDateTime: string;
  readonly required: number;
  readonly label?: string;
  readonly role?: string;
  readonly group?: string;
  readonly resourceId?: EventSchedulerEntityId;
  readonly resourceIds?: readonly EventSchedulerEntityId[];
  readonly className?: string;
  readonly metadata?: Record<string, unknown>
}
```

---

### `EventSchedulerCoverageRequirementContext`

```ts
interface EventSchedulerCoverageRequirementContext {
  readonly requirement: EventSchedulerCoverageRequirementEntity;
  readonly resource: EventSchedulerResourceEntity
}
```

---

### `EventSchedulerCoverageCountContext`

```ts
interface EventSchedulerCoverageCountContext {
  readonly requirement: EventSchedulerCoverageRequirementEntity;
  readonly event: EventSchedulerEventEntity;
  readonly segment: EventSchedulerEventSegment;
  readonly resource: EventSchedulerResourceEntity
}
```

---

### `EventSchedulerCoverageConfig`

```ts
interface EventSchedulerCoverageConfig {
  readonly enabled?: boolean;
  readonly capacityField?: keyof EventSchedulerResourceEntity | string;
  readonly resourceMatchesRequirement?: (context: EventSchedulerCoverageRequirementContext) => boolean;
  readonly countEvent?: (context: EventSchedulerCoverageCountContext) => number | boolean;
  readonly summaryFormatter?: (summary: EventSchedulerCoverageSummary) => string
}
```

---

### `EventSchedulerCoverageResult`

```ts
interface EventSchedulerCoverageResult {
  readonly id: string;
  readonly requirementId: EventSchedulerEntityId;
  readonly requirement: EventSchedulerCoverageRequirementEntity;
  readonly label: string;
  readonly date: string;
  readonly startDateTime: string;
  readonly endDateTime: string;
  readonly required: number;
  readonly assigned: number;
  readonly missing: number;
  readonly surplus: number;
  readonly status: EventSchedulerCoverageStatus;
  readonly resourceIds: readonly EventSchedulerEntityId[];
  readonly eventIds: readonly EventSchedulerEntityId[]
}
```

---

### `EventSchedulerCoverageSummary`

```ts
interface EventSchedulerCoverageSummary {
  readonly requirementCount: number;
  readonly underCount: number;
  readonly overCount: number;
  readonly metCount: number;
  readonly missingTotal: number;
  readonly surplusTotal: number
}
```

---

### `EventSchedulerUtilizationStatus`

```ts
export type EventSchedulerUtilizationStatus = 'under' | 'balanced' | 'over';
```

---

### `EventSchedulerUtilizationTargetContext`

```ts
interface EventSchedulerUtilizationTargetContext {
  readonly resource: EventSchedulerResourceEntity;
  readonly config: EventSchedulerResolvedConfig;
  readonly segments: readonly EventSchedulerEventSegment[];
  readonly dates: readonly string[]
}
```

---

### `EventSchedulerUtilizationCountContext`

```ts
interface EventSchedulerUtilizationCountContext {
  readonly event: EventSchedulerEventEntity;
  readonly segment: EventSchedulerEventSegment;
  readonly resource: EventSchedulerResourceEntity;
  readonly defaultMinutes: number
}
```

---

### `EventSchedulerUtilizationConfig`

```ts
interface EventSchedulerUtilizationConfig {
  readonly enabled?: boolean;
  readonly targetHours?: number | ((context: EventSchedulerUtilizationTargetContext) => number | undefined);
  readonly minHours?: number | ((context: EventSchedulerUtilizationTargetContext) => number | undefined);
  readonly maxHours?: number | ((context: EventSchedulerUtilizationTargetContext) => number | undefined);
  readonly targetHoursField?: keyof EventSchedulerResourceEntity | string;
  readonly minHoursField?: keyof EventSchedulerResourceEntity | string;
  readonly maxHoursField?: keyof EventSchedulerResourceEntity | string;
  readonly includeStatuses?: readonly string[];
  readonly excludeStatuses?: readonly string[];
  readonly countEvent?: (context: EventSchedulerUtilizationCountContext) => number | boolean;
  readonly summaryFormatter?: (summary: EventSchedulerUtilizationSummary) => string
}
```

---

### `EventSchedulerUtilizationResult`

```ts
interface EventSchedulerUtilizationResult {
  readonly resourceId: EventSchedulerEntityId;
  readonly resource: EventSchedulerResourceEntity;
  readonly eventCount: number;
  readonly totalMinutes: number;
  readonly totalHours: number;
  readonly targetHours?: number;
  readonly minHours?: number;
  readonly maxHours?: number;
  readonly utilizationPercent?: number;
  readonly status?: EventSchedulerUtilizationStatus;
  readonly eventIds: readonly EventSchedulerEntityId[]
}
```

---

### `EventSchedulerUtilizationSummary`

```ts
interface EventSchedulerUtilizationSummary {
  readonly resourceCount: number;
  readonly measuredResourceCount: number;
  readonly eventCount: number;
  readonly totalMinutes: number;
  readonly totalHours: number;
  readonly targetHours: number;
  readonly minHours: number;
  readonly maxHours: number;
  readonly utilizationPercent?: number;
  readonly underCount: number;
  readonly balancedCount: number;
  readonly overCount: number
}
```

---

### `EventSchedulerUnassignedFilterConfig`

```ts
interface EventSchedulerUnassignedFilterConfig {
  readonly dateRange?: EventSchedulerDateRange;
  readonly type?: string | readonly string[];
  readonly role?: string | readonly string[];
  readonly status?: string | readonly string[]
}
```

---

### `EventSchedulerUnassignedSummary`

```ts
interface EventSchedulerUnassignedSummary {
  readonly totalCount: number;
  readonly visibleCount: number;
  readonly hiddenCount: number;
  readonly totalMinutes: number;
  readonly totalHours: number;
  readonly requiredRoles: readonly string[];
  readonly eventIds: readonly EventSchedulerEntityId[];
  readonly filteredEventIds: readonly EventSchedulerEntityId[]
}
```

---

### `EventSchedulerUnassignedRoleContext`

```ts
interface EventSchedulerUnassignedRoleContext {
  readonly event: EventSchedulerEventEntity
}
```

---

### `EventSchedulerUnassignedRoleFormatterContext` (Extended from `index.ts`)

```ts
interface EventSchedulerUnassignedRoleFormatterContext {
  readonly role: string;
  readonly labels: EventSchedulerLabels
}
```

---

### `EventSchedulerUnassignedAssignmentContext`

```ts
interface EventSchedulerUnassignedAssignmentContext {
  readonly event: EventSchedulerEventEntity;
  readonly previousEvent: EventSchedulerEventEntity;
  readonly resource: EventSchedulerResourceEntity;
  readonly resourceId: EventSchedulerEntityId;
  readonly startDateTime: string;
  readonly endDateTime: string
}
```

---

### `EventSchedulerUnassignedConfig`

Unassigned-demand settings for events without `resourceId` or `resourceIds`.

```ts
interface EventSchedulerUnassignedConfig {
  readonly enabled?: boolean;
  readonly showCount?: boolean;
  readonly filter?: EventSchedulerUnassignedFilterConfig;
  readonly requiredRoleField?: keyof EventSchedulerEventEntity | string;
  readonly requiredRoleResolver?: (context: EventSchedulerUnassignedRoleContext) => string | undefined;
  readonly requiredRoleFormatter?: (context: EventSchedulerUnassignedRoleFormatterContext) => string;
  readonly counterFormatter?: (summary: EventSchedulerUnassignedSummary) => string;
  readonly assignmentValidator?: (context: EventSchedulerUnassignedAssignmentContext) => boolean | string | void
}
```

---

### `EventSchedulerFilterState`

```ts
interface EventSchedulerFilterState {
  readonly search?: string;
  readonly resourceIds?: readonly EventSchedulerEntityId[];
  readonly resourceRoles?: string | readonly string[];
  readonly resourceGroups?: string | readonly string[];
  readonly resourceLocations?: string | readonly string[];
  readonly eventTypes?: string | readonly string[];
  readonly eventStatuses?: string | readonly string[];
  readonly eventCategories?: string | readonly string[];
  readonly conflictTypes?: EventSchedulerConflictType | readonly EventSchedulerConflictType[];
  readonly conflictSeverities?: EventSchedulerConflictSeverity | readonly EventSchedulerConflictSeverity[];
  readonly conflictsOnly?: boolean;
  readonly unassignedOnly?: boolean;
  readonly dateRange?: EventSchedulerDateRange
}
```

---

### `EventSchedulerSavedView`

Named scheduler filter/range preset that products can expose as saved views.

```ts
interface EventSchedulerSavedView {
  readonly id: EventSchedulerEntityId;
  readonly label: string;
  readonly description?: string;
  readonly view?: EventSchedulerView;
  readonly weekStartDate?: string;
  readonly dateRange?: EventSchedulerDateRange;
  readonly visibleDays?: readonly number[];
  readonly slotMinutes?: number;
  readonly timeRange?: EventSchedulerTimeRange;
  readonly filters?: EventSchedulerFilterState;
  readonly metadata?: Record<string, unknown>
}
```

---

### `EventSchedulerSavedViewsConfig`

```ts
interface EventSchedulerSavedViewsConfig {
  readonly views?: readonly EventSchedulerSavedView[];
  readonly activeViewId?: EventSchedulerEntityId
}
```

---

### `EventSchedulerFilterSummary`

```ts
interface EventSchedulerFilterSummary {
  readonly activeSavedViewId?: EventSchedulerEntityId;
  readonly search: string;
  readonly resourcesTotal: number;
  readonly resourcesVisible: number;
  readonly resourcesHidden: number;
  readonly eventsTotal: number;
  readonly eventsVisible: number;
  readonly eventsHidden: number;
  readonly resourceIds: readonly EventSchedulerEntityId[];
  readonly eventIds: readonly EventSchedulerEntityId[];
  readonly filteredResourceIds: readonly EventSchedulerEntityId[];
  readonly filteredEventIds: readonly EventSchedulerEntityId[]
}
```

---

### `EventSchedulerResourceGroupBy`

```ts
export type EventSchedulerResourceGroupBy =
  | keyof EventSchedulerResourceEntity
  | string
  | ((resource: EventSchedulerResourceEntity) => EventSchedulerEntityId | readonly EventSchedulerEntityId[] | null | undefined);
```

---

### `EventSchedulerResourceGroupSummary`

```ts
interface EventSchedulerResourceGroupSummary {
  readonly eventCount: number;
  readonly totalMinutes: number;
  readonly totalHours: number;
  readonly resourceCount: number;
  readonly coverage?: EventSchedulerCoverageSummary;
  readonly utilization?: EventSchedulerUtilizationSummary
}
```

---

### `EventSchedulerResourceGroupContext`

```ts
interface EventSchedulerResourceGroupContext {
  readonly id: string;
  readonly key: EventSchedulerEntityId;
  readonly label: string;
  readonly depth: number;
  readonly path: readonly string[];
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly summary: EventSchedulerResourceGroupSummary
}
```

---

### `EventSchedulerResourceGroupingConfig`

```ts
interface EventSchedulerResourceGroupingConfig {
  readonly enabled?: boolean;
  readonly groupBy?: EventSchedulerResourceGroupBy | readonly EventSchedulerResourceGroupBy[];
  readonly tree?: boolean;
  readonly parentIdField?: keyof EventSchedulerResourceEntity | string;
  readonly collapsed?: boolean;
  readonly collapsedGroupIds?: readonly EventSchedulerEntityId[];
  readonly expandedGroupIds?: readonly EventSchedulerEntityId[];
  readonly sort?: (left: EventSchedulerResourceEntity, right: EventSchedulerResourceEntity) => number;
  readonly groupSort?: (left: EventSchedulerResourceGroupContext, right: EventSchedulerResourceGroupContext) => number;
  readonly groupLabelFormatter?: (context: EventSchedulerResourceGroupContext) => string;
  readonly groupSummaryFormatter?: (context: EventSchedulerResourceGroupContext) => string
}
```

---

### `EventSchedulerAssignmentEntity`

```ts
interface EventSchedulerAssignmentEntity {
  readonly id: EventSchedulerEntityId;
  readonly eventId: EventSchedulerEntityId;
  readonly resourceId: EventSchedulerEntityId;
  readonly status?: EventSchedulerStatus | string;
  readonly locked?: boolean;
  readonly metadata?: Record<string, unknown>
}
```

---

### `EventSchedulerAvailabilityEntity`

Working, blocked, holiday, or break interval used as timeline background and conflict input.

```ts
interface EventSchedulerAvailabilityEntity {
  readonly id: EventSchedulerEntityId;
  readonly resourceId?: EventSchedulerEntityId;
  readonly resourceIds?: readonly EventSchedulerEntityId[];
  readonly startDateTime: string;
  readonly endDateTime: string;
  readonly kind: EventSchedulerAvailabilityKind;
  readonly title?: string;
  readonly reason?: string;
  readonly status?: EventSchedulerStatus | string;
  readonly className?: string;
  readonly metadata?: Record<string, unknown>
}
```

---

### `EventSchedulerConflictConfig`

Conflict engine configuration for warning, blocking, confirm, allow, or ignore behavior.

```ts
interface EventSchedulerConflictConfig {
  readonly enabled?: boolean;
  readonly policy?: EventSchedulerConflictPolicy;
  readonly scope?: EventSchedulerConflictScope;
  readonly rules?: Partial<Record<EventSchedulerConflictType, EventSchedulerConflictRulePolicy>>;
  readonly minDurationMinutes?: number;
  readonly maxDurationMinutes?: number;
  readonly messages?: Partial<Record<EventSchedulerConflictType, string>>
}
```

---

### `EventSchedulerPermissionContext`

```ts
interface EventSchedulerPermissionContext {
  readonly event: EventSchedulerEventEntity;
  readonly resource?: EventSchedulerResourceEntity;
  readonly action: EventSchedulerMutationAction
}
```

---

### `EventSchedulerPermissionDecision`

```ts
export type EventSchedulerPermissionDecision =
  | boolean
  | string
  | void
  | {
      readonly allowed?: boolean;
      readonly message?: string;
    };
```

---

### `EventSchedulerCreatePermissionContext`

```ts
interface EventSchedulerCreatePermissionContext {
  readonly action: 'create' | 'paste' | 'duplicate' | 'template-create' | 'recurrence-create';
  readonly event?: EventSchedulerEventEntity;
  readonly resource?: EventSchedulerResourceEntity;
  readonly resourceId?: EventSchedulerEntityId;
  readonly startDateTime: string;
  readonly endDateTime: string
}
```

---

### `EventSchedulerMutationPermissionContext`

```ts
interface EventSchedulerMutationPermissionContext {
  readonly action: EventSchedulerMutationAction;
  readonly event: EventSchedulerEventEntity;
  readonly nextEvent?: EventSchedulerEventEntity;
  readonly resource?: EventSchedulerResourceEntity;
  readonly targetResource?: EventSchedulerResourceEntity;
  readonly changes?: Partial<EventSchedulerEventEntity>
}
```

---

### `EventSchedulerPermissionsConfig`

Access-control settings for embedded products.

This is evaluated in addition to legacy `editable` and `allow*` flags. It covers
read-only mode, resource locks, date locks, status locks, and product-specific checks.

**Example:**
```typescript
eventScheduler: {
  weekStartDate: '2026-06-08',
  permissions: {
    lockedStatuses: ['completed'],
    lockedBeforeDateTime: '2026-06-08T00:00:00.000Z',
    canMutate: ({ action, targetResource }) =>
      targetResource?.locked ? 'This resource is locked.' : action !== 'delete'
  }
}
```

```ts
interface EventSchedulerPermissionsConfig {
  /** Makes the whole scheduler non-editable while keeping selection, tooltips, and scrolling active. */
    readonly readOnly?: boolean;
  /** Event statuses that cannot be moved, resized, edited, or deleted. */
    readonly lockedStatuses?: readonly string[];
  /** Date-time ranges where create, move, resize, edit, and delete are rejected. */
    readonly lockedDateRanges?: readonly EventSchedulerDateRange[];
  /** Rejects edits whose start time is before this ISO date-time. */
    readonly lockedBeforeDateTime?: string;
  /** Product hook for create/paste/template/recurrence creation decisions. */
    readonly canCreate?: (context: EventSchedulerCreatePermissionContext) => EventSchedulerPermissionDecision;
  /** Product hook for move/resize/reassign/edit/delete/bulk/recurrence mutation decisions. */
    readonly canMutate?: (context: EventSchedulerMutationPermissionContext) => EventSchedulerPermissionDecision
}
```

---

### `EventSchedulerTemplateResult`

```ts
export type EventSchedulerTemplateResult = VNode | string | null | undefined;
```

---

### `EventSchedulerTemplateH`

```ts
export type EventSchedulerTemplateH = (
  tag: string,
  props?: Record<string, unknown>,
  children?: unknown,
) => VNode;
```

---

### `EventSchedulerElementProps`

```ts
export type EventSchedulerElementProps = Record<string, unknown>;
```

---

### `EventSchedulerRenderContext`

```ts
interface EventSchedulerRenderContext {
  readonly event: EventSchedulerEventEntity;
  readonly resource?: EventSchedulerResourceEntity;
  /** First real projected segment represented by this visual bar. */
    readonly segment: EventSchedulerEventSegment;
  /** Ordered projected segments represented by this visual bar. */
    readonly segments: readonly EventSchedulerEventSegment[]
}
```

---

### `EventSchedulerEventRenderMode`

```ts
export type EventSchedulerEventRenderMode = 'week' | 'timeline' | 'calendar';
```

---

### `EventSchedulerEventSectionContext` (Extended from `index.ts`)

```ts
interface EventSchedulerEventSectionContext {
  /** Event hooks run once for this visual assignment bar. */
    readonly mode: EventSchedulerEventRenderMode;
  /** @deprecated Event hooks now run once per bar, so this is always `true`. */
    readonly first: boolean;
  /** @deprecated Event hooks now run once per bar, so this is always `true`. */
    readonly last: boolean;
  /** @deprecated Use `segment.startSlot` or inspect `segments`. */
    readonly sliceSlot: number;
  readonly start: string;
  readonly end: string;
  readonly day: string;
  readonly duration: number;
  readonly status?: string;
  readonly type?: string;
  readonly isSelected: boolean;
  readonly isDragging: boolean;
  readonly isResizing: boolean;
  readonly isLocked: boolean;
  readonly hasConflict: boolean;
  readonly isReadonly: boolean;
  readonly isFromPreviousDay: boolean;
  readonly isContinuedToNextDay: boolean;
  readonly isShortEvent: boolean
}
```

---

### `EventSchedulerEventBadgeContext` (Extended from `index.ts`)

```ts
interface EventSchedulerEventBadgeContext {
  readonly kind: 'status' | 'type' | 'category' | 'requiredRole';
  readonly label: string
}
```

---

### `EventSchedulerEventResizeHandleContext` (Extended from `index.ts`)

```ts
interface EventSchedulerEventResizeHandleContext {
  readonly edge: 'start' | 'end'
}
```

---

### `EventSchedulerConflictDisplayContext` (Extended from `index.ts`)

```ts
interface EventSchedulerConflictDisplayContext {
  /** Highest conflict severity across the rendered event bar. */
    readonly severity: EventSchedulerConflictSeverity;
  /** Conflict rule types across the rendered event bar, such as `overlap` or `blocked-time`. */
    readonly conflictTypes: readonly EventSchedulerConflictType[];
  /** Stable conflict ids across the rendered event bar. */
    readonly conflictIds: readonly string[];
  /** Human-readable conflict label built from scheduler labels and conflict types. */
    readonly label: string
}
```

---

### `EventSchedulerEventSectionTemplate`

```ts
export type EventSchedulerEventSectionTemplate<TContext extends EventSchedulerEventSectionContext = EventSchedulerEventSectionContext> = (
  createElement: EventSchedulerTemplateH,
  context: TContext,
) => EventSchedulerTemplateResult;
```

---

### `EventSchedulerTimelineHeaderContext`

```ts
interface EventSchedulerTimelineHeaderContext {
  readonly date: string;
  readonly dayIndex: number;
  readonly slotIndex: number;
  readonly timelineSlotIndex: number;
  readonly startMinutes: number;
  readonly endMinutes: number;
  readonly startDateTime: string;
  readonly endDateTime: string
}
```

---

### `EventSchedulerHeaderKind`

```ts
export type EventSchedulerHeaderKind = 'time' | 'resource' | 'day' | 'timeline' | 'group';
```

---

### `EventSchedulerHeaderGroupKind`

```ts
export type EventSchedulerHeaderGroupKind = 'day' | 'range' | 'timeline';
```

---

### `EventSchedulerHeaderContext`

```ts
interface EventSchedulerHeaderContext {
  readonly kind: EventSchedulerHeaderKind;
  readonly view: EventSchedulerView;
  readonly defaultLabel: string;
  readonly date?: string;
  readonly dayIndex?: number;
  readonly slotIndex?: number;
  readonly timelineSlotIndex?: number;
  readonly startMinutes?: number;
  readonly endMinutes?: number;
  readonly startDateTime?: string;
  readonly endDateTime?: string;
  readonly eventCount?: number;
  readonly today?: boolean;
  readonly weekend?: boolean;
  readonly holiday?: boolean;
  readonly holidayLabel?: string;
  readonly groupKind?: EventSchedulerHeaderGroupKind
}
```

---

### `EventSchedulerCellContext`

```ts
interface EventSchedulerCellContext {
  readonly view: EventSchedulerView;
  readonly row: EventSchedulerGridRow
}
```

---

### `EventSchedulerTimeCellContext` (Extended from `index.ts`)

```ts
interface EventSchedulerTimeCellContext {
  readonly slotIndex: number;
  readonly startMinutes: number;
  readonly endMinutes: number;
  readonly timeLabel: string;
  readonly currentTimeLabel?: string
}
```

---

### `EventSchedulerCurrentTimeMarkerContext`

```ts
interface EventSchedulerCurrentTimeMarkerContext {
  readonly view: EventSchedulerView;
  readonly date: string;
  readonly dayIndex: number;
  readonly slotIndex: number;
  readonly startMinutes: number;
  readonly endMinutes: number;
  readonly dateTime: string;
  readonly label: string;
  readonly position: number;
  readonly orientation: 'horizontal' | 'vertical';
  readonly row?: EventSchedulerGridRow;
  readonly resourceId?: EventSchedulerEntityId;
  readonly resource?: EventSchedulerResourceEntity
}
```

---

### `EventSchedulerSlotContext`

```ts
interface EventSchedulerSlotContext {
  readonly date: string;
  readonly dayIndex: number;
  readonly slotIndex: number;
  readonly startDateTime: string;
  readonly endDateTime: string
}
```

---

### `EventSchedulerSlotRenderContext` (Extended from `index.ts`)

```ts
interface EventSchedulerSlotRenderContext {
  readonly view: EventSchedulerView;
  readonly row: EventSchedulerGridRow;
  readonly startMinutes: number;
  readonly endMinutes: number;
  readonly segmentCount: number;
  readonly today: boolean;
  readonly weekend: boolean;
  readonly resourceId?: EventSchedulerEntityId;
  readonly resource?: EventSchedulerResourceEntity;
  readonly disabled: boolean;
  readonly selectable: boolean
}
```

---

### `EventSchedulerDayCellContext` (Extended from `index.ts`)

```ts
interface EventSchedulerDayCellContext {

}
```

---

### `EventSchedulerClosedSlotContext` (Extended from `index.ts`)

```ts
interface EventSchedulerClosedSlotContext {
  readonly available: boolean;
  readonly availabilityKind: EventSchedulerAvailabilityKind | 'closed';
  readonly availabilityId?: EventSchedulerEntityId;
  readonly title?: string;
  readonly reason?: string
}
```

---

### `EventSchedulerResourceCellContext` (Extended from `index.ts`)

```ts
interface EventSchedulerResourceCellContext {
  readonly resource?: EventSchedulerResourceEntity;
  readonly resourceId?: EventSchedulerEntityId;
  readonly depth: number;
  readonly unassigned: boolean
}
```

---

### `EventSchedulerResourceGroupCellContext` (Extended from `index.ts`)

```ts
interface EventSchedulerResourceGroupCellContext {
  readonly groupId?: string;
  readonly groupLabel?: string;
  readonly depth: number;
  readonly expanded: boolean
}
```

---

### `EventSchedulerTimelineCellContext` (Extended from `index.ts`)

```ts
interface EventSchedulerTimelineCellContext {
  readonly column: EventSchedulerTimelineColumn;
  readonly date: string;
  readonly dayIndex: number;
  readonly slotIndex: number;
  readonly startMinutes: number;
  readonly endMinutes: number;
  readonly segmentCount: number
}
```

---

### `EventSchedulerCreateRangeContext` (Extended from `index.ts`)

```ts
interface EventSchedulerCreateRangeContext {
  readonly startSlot: number;
  readonly endSlot: number;
  readonly startMinutes: number;
  readonly endMinutes: number;
  readonly durationMinutes: number;
  readonly resourceId?: EventSchedulerEntityId;
  readonly resource?: EventSchedulerResourceEntity
}
```

---

### `EventSchedulerCreateRangeDisplayContext` (Extended from `index.ts`)

```ts
interface EventSchedulerCreateRangeDisplayContext {
  readonly title: string;
  readonly startLabel: string;
  readonly endLabel: string;
  readonly durationLabel: string;
  readonly label: string
}
```

---

### `EventSchedulerEmptyStateKind`

```ts
export type EventSchedulerEmptyStateKind = 'loading' | 'refreshing' | 'saving' | 'empty' | 'error';
```

---

### `EventSchedulerEmptyStateContext`

```ts
interface EventSchedulerEmptyStateContext {
  /** Current state rendered in the scheduler overlay. */
    readonly kind: EventSchedulerEmptyStateKind;
  /** Default text resolved from `labels` and `emptyStateText`. */
    readonly label: string;
  /** Remote or loading error message when `kind` is `error`. */
    readonly error?: string
}
```

---

### `EventSchedulerEmptyStateTemplate`

Replaces the scheduler loading, error, or empty overlay content.

**Example:**
```typescript
customization: {
  emptyState: {
    template: ({ kind, label }) => `${kind}: ${label}`,
  },
}
```

```ts
/** Replaces the scheduler loading, error, or empty overlay content.
 *
 * @example
 * ```ts
 * customization: {
 *   emptyState: {
 *     template: ({ kind, label }) = > `${kind}: ${label}`,
 *   },
 * }
 * ```
 */
export type EventSchedulerEmptyStateTemplate = (
  context: EventSchedulerEmptyStateContext,
) => string | Node | null | undefined;
```

---

### `EventSchedulerCreateRangeTemplate`

```ts
export type EventSchedulerCreateRangeTemplate = (
  context: EventSchedulerCreateRangeDisplayContext,
) => string | Node | null | undefined;
```

---

### `EventSchedulerColumnSizeConfig`

```ts
interface EventSchedulerColumnSizeConfig {
  readonly timeColumnSize?: number;
  readonly dayColumnSize?: number;
  readonly resourceColumnSize?: number;
  readonly timelineColumnSize?: number
}
```

---

### `EventSchedulerViewColumnSizeConfig`

```ts
export type EventSchedulerViewColumnSizeConfig = Partial<Record<EventSchedulerView, EventSchedulerColumnSizeConfig>>;
```

---

### `EventSchedulerHeaderCustomizationConfig`

```ts
interface EventSchedulerHeaderCustomizationConfig {
  readonly timeTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerHeaderContext) => EventSchedulerTemplateResult;
  readonly timeProperties?: (context: EventSchedulerHeaderContext) => EventSchedulerElementProps | undefined;
  readonly resourceTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerHeaderContext) => EventSchedulerTemplateResult;
  readonly resourceProperties?: (context: EventSchedulerHeaderContext) => EventSchedulerElementProps | undefined;
  readonly dayTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerHeaderContext) => EventSchedulerTemplateResult;
  readonly dayProperties?: (context: EventSchedulerHeaderContext) => EventSchedulerElementProps | undefined;
  readonly timelineTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerHeaderContext) => EventSchedulerTemplateResult;
  readonly timelineProperties?: (context: EventSchedulerHeaderContext) => EventSchedulerElementProps | undefined;
  readonly groupTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerHeaderContext) => EventSchedulerTemplateResult;
  readonly groupProperties?: (context: EventSchedulerHeaderContext) => EventSchedulerElementProps | undefined
}
```

---

### `EventSchedulerCellCustomizationConfig`

```ts
interface EventSchedulerCellCustomizationConfig {
  readonly timeTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerTimeCellContext) => EventSchedulerTemplateResult;
  readonly timeProperties?: (context: EventSchedulerTimeCellContext) => EventSchedulerElementProps | undefined;
  readonly dayTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerDayCellContext) => EventSchedulerTemplateResult;
  readonly dayProperties?: (context: EventSchedulerDayCellContext) => EventSchedulerElementProps | undefined;
  readonly resourceTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerResourceCellContext) => EventSchedulerTemplateResult;
  readonly resourceProperties?: (context: EventSchedulerResourceCellContext) => EventSchedulerElementProps | undefined;
  readonly resourceGroupTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerResourceGroupCellContext) => EventSchedulerTemplateResult;
  readonly resourceGroupProperties?: (context: EventSchedulerResourceGroupCellContext) => EventSchedulerElementProps | undefined;
  readonly timelineTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerTimelineCellContext) => EventSchedulerTemplateResult;
  readonly timelineProperties?: (context: EventSchedulerTimelineCellContext) => EventSchedulerElementProps | undefined
}
```

---

### `EventSchedulerEventCustomizationConfig`

```ts
interface EventSchedulerEventCustomizationConfig {
  readonly className?: string | ((context: EventSchedulerEventSectionContext) => string | undefined);
  readonly style?: (context: EventSchedulerEventSectionContext) => Record<string, string | number | undefined> | undefined;
  readonly properties?: (context: EventSchedulerEventSectionContext) => EventSchedulerElementProps | undefined;
  readonly content?: EventSchedulerEventSectionTemplate;
  readonly continuationLabels?: EventSchedulerEventSectionTemplate;
  readonly badgeTray?: EventSchedulerEventSectionTemplate;
  readonly badge?: EventSchedulerEventSectionTemplate<EventSchedulerEventBadgeContext>;
  readonly resizeHandle?: EventSchedulerEventSectionTemplate<EventSchedulerEventResizeHandleContext>;
  readonly tooltip?: (context: EventSchedulerEventSectionContext) => string | undefined;
  readonly ariaLabel?: (context: EventSchedulerEventSectionContext) => string | undefined
}
```

---

### `EventSchedulerCreatePreviewCustomizationConfig`

```ts
interface EventSchedulerCreatePreviewCustomizationConfig {
  readonly hoverTimeProperties?: (context: EventSchedulerSlotContext) => EventSchedulerElementProps | undefined;
  readonly createRangeTemplate?: (context: EventSchedulerCreateRangeDisplayContext) => string | Node | null | undefined;
  readonly createRangeProperties?: (context: EventSchedulerCreateRangeDisplayContext) => EventSchedulerElementProps | undefined
}
```

---

### `EventSchedulerConflictCustomizationConfig`

```ts
interface EventSchedulerConflictCustomizationConfig {
  /** Adds classes to conflicted event blocks.
     *
     * @example
     * ```ts
     * className: ({ severity }) => `booking-conflict--${severity}`
     * ```
     */
    readonly className?: string | ((context: EventSchedulerConflictDisplayContext) => string | undefined);
  /** Adds attributes, classes, styles, or data fields to conflicted event blocks. */
    readonly properties?: (context: EventSchedulerConflictDisplayContext) => EventSchedulerElementProps | undefined;
  /** Renders a custom conflict indicator inside the event block. */
    readonly indicator?: EventSchedulerEventSectionTemplate<EventSchedulerConflictDisplayContext>;
  /** Overrides the event tooltip when a segment has conflicts. */
    readonly tooltip?: (context: EventSchedulerConflictDisplayContext) => string | undefined
}
```

---

### `EventSchedulerEmptyStateCustomizationConfig`

```ts
interface EventSchedulerEmptyStateCustomizationConfig {
  /** Replaces the scheduler loading, empty, saving, refreshing, or error overlay content. */
    readonly template?: EventSchedulerEmptyStateTemplate;
  /** Adds classes, style variables, ARIA attributes, or data fields to the overlay element. */
    readonly properties?: (context: EventSchedulerEmptyStateContext) => EventSchedulerElementProps | undefined
}
```

---

### `EventSchedulerCalendarDayContext`

```ts
interface EventSchedulerCalendarDayContext {
  readonly view: 'month';
  readonly day: EventSchedulerCalendarDay;
  readonly row: EventSchedulerGridRow;
  readonly weekIndex: number
}
```

---

### `EventSchedulerCalendarMonthContext`

```ts
interface EventSchedulerCalendarMonthContext {
  readonly view: 'year';
  readonly month: EventSchedulerCalendarMonthSummary
}
```

---

### `EventSchedulerCalendarOverflowContext` (Extended from `index.ts`)

```ts
interface EventSchedulerCalendarOverflowContext {
  readonly overflowCount: number
}
```

---

### `EventSchedulerCalendarCustomizationConfig`

```ts
interface EventSchedulerCalendarCustomizationConfig {
  readonly dayTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerCalendarDayContext) => EventSchedulerTemplateResult;
  readonly dayProperties?: (context: EventSchedulerCalendarDayContext) => EventSchedulerElementProps | undefined;
  /** Overrides calendar-bar content; shared event templates remain the fallback. */
    readonly eventTemplate?: EventSchedulerEventSectionTemplate;
  readonly overflowTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerCalendarOverflowContext) => EventSchedulerTemplateResult;
  readonly overflowFormatter?: (count: number, context: EventSchedulerCalendarDayContext) => string;
  readonly yearMonthTemplate?: (createElement: EventSchedulerTemplateH, context: EventSchedulerCalendarMonthContext) => EventSchedulerTemplateResult
}
```

---

### `EventSchedulerCustomizationConfig`

```ts
interface EventSchedulerCustomizationConfig {
  /** Per-view generated column size overrides. */
    readonly columnSizes?: EventSchedulerViewColumnSizeConfig;
  /** Generated scheduler header templates and properties. */
    readonly headers?: EventSchedulerHeaderCustomizationConfig;
  /** Generated scheduler cell templates and properties. */
    readonly cells?: EventSchedulerCellCustomizationConfig;
  /** Event block content, badges, handles, classes, styles, tooltips, and ARIA hooks. */
    readonly events?: EventSchedulerEventCustomizationConfig;
  /** Empty-slot hover and drag-create range preview hooks. */
    readonly createPreview?: EventSchedulerCreatePreviewCustomizationConfig;
  /** Conflict-specific event block classes, attributes, indicators, and tooltips. */
    readonly conflicts?: EventSchedulerConflictCustomizationConfig;
  /** Loading, empty, saving, refreshing, and error overlay customization. */
    readonly emptyState?: EventSchedulerEmptyStateCustomizationConfig;
  /** Month/year calendar cell, overflow, and mini-month customization. */
    readonly calendar?: EventSchedulerCalendarCustomizationConfig
}
```

---

### `EventSchedulerEventEditorMode`

```ts
export type EventSchedulerEventEditorMode = 'create' | 'edit';
```

---

### `EventSchedulerEventEditorStatusOption`

```ts
interface EventSchedulerEventEditorStatusOption {
  readonly value: string;
  readonly label?: string
}
```

---

### `EventSchedulerShortcutLabel`

```ts
interface EventSchedulerShortcutLabel {
  readonly label: string;
  readonly keys: string
}
```

---

### `EventSchedulerShortcutGroupLabels`

```ts
interface EventSchedulerShortcutGroupLabels {
  readonly title: string;
  readonly items: readonly EventSchedulerShortcutLabel[]
}
```

---

### `EventSchedulerLabels`

```ts
interface EventSchedulerLabels {
  readonly resourceColumn: string;
  readonly noResources: string;
  readonly unassignedResource: string;
  readonly unassignedCountLabel: (count: number) => string;
  readonly moreEventsLabel: (count: number) => string;
  readonly eventCountLabel: (count: number) => string;
  readonly shiftCountLabel: (count: number) => string;
  readonly eventsOnDateLabel: (date: string) => string;
  readonly requiredRolePrefix: string;
  readonly today: string;
  readonly previousContinuation: string;
  readonly nextContinuation: string;
  readonly resourceGroup: string;
  readonly resourceAvatarAriaLabel: (resourceName: string) => string;
  readonly expandResourceGroupAriaLabel: (groupLabel: string) => string;
  readonly collapseResourceGroupAriaLabel: (groupLabel: string) => string;
  readonly coverageSummaryLabel: (summary: EventSchedulerCoverageSummary) => string;
  readonly utilizationSummaryLabel: (summary: EventSchedulerUtilizationSummary) => string;
  readonly resourceGroupSummaryLabel: (summary: EventSchedulerResourceGroupSummary) => string;
  readonly keyboardShortcutsTitle: string;
  readonly closeKeyboardShortcutsAriaLabel: string;
  readonly keyboardShortcutGroups: readonly EventSchedulerShortcutGroupLabels[];
  readonly newEvent: string;
  readonly createEvent: string;
  readonly editEvent: string;
  readonly closeEditor: string;
  readonly closeEditorAriaLabel: string;
  readonly titleField: string;
  readonly startField: string;
  readonly endField: string;
  readonly resourceField: string;
  readonly resourceSearchPlaceholder: string;
  readonly resourceSearchAriaLabel: string;
  readonly noMatchingResources: string;
  readonly statusField: string;
  readonly colorField: string;
  readonly colorAction: string;
  readonly colorPaletteAriaLabel: string;
  readonly defaultColorAction: string;
  readonly colorOptionAriaLabel: (color: string) => string;
  readonly notesField: string;
  readonly noStatus: string;
  readonly deleteAction: string;
  readonly copyAction: string;
  readonly pasteAction: string;
  readonly duplicateAction: string;
  readonly createEventHereAction: string;
  readonly assignOpenEventAction: string;
  readonly editEventAction: string;
  readonly confirmEventAction: string;
  readonly markPlannedAction: string;
  readonly reassignResourceAction: string;
  readonly lockAction: string;
  readonly unlockAction: string;
  readonly zoomInAction: string;
  readonly zoomOutAction: string;
  readonly emptyClipboard: string;
  readonly bulkStatusAction: string;
  readonly cancelAction: string;
  readonly saveAction: string;
  readonly lockedEditorMessage: string;
  readonly titleRequiredMessage: string;
  readonly dateTimeRequiredMessage: string;
  readonly endAfterStartMessage: string;
  readonly closed: string;
  readonly outsideWorkingHours: string;
  readonly closedDay: string;
  readonly statusPrefix: string;
  readonly typePrefix: string;
  readonly categoryPrefix: string;
  readonly conflict: string;
  readonly locked: string;
  readonly remoteLoading: string;
  readonly remoteRefreshing: string;
  readonly remoteSaving: string;
  readonly remoteEmpty: string;
  readonly remoteError: string;
  readonly remoteRetry: string;
  readonly remoteMutationRejected: string;
  readonly printTitle: string;
  readonly printEventsSection: string;
  readonly printResourceWorkloadSection: string;
  readonly printConflictsSection: string;
  readonly printCoverageGapsSection: string;
  readonly printGeneratedLabel: string;
  readonly printRangeSeparator: string;
  readonly printNoRecords: string;
  readonly reportColumnLabel: (column: string) => string;
  readonly statusLabel: (status: string) => string;
  readonly typeLabel: (type: string) => string;
  readonly categoryLabel: (category: string) => string
}
```

---

### `EventSchedulerEventEditorOpenContext`

Context passed to a custom event editor.

```ts
interface EventSchedulerEventEditorOpenContext {
  readonly mode: EventSchedulerEventEditorMode;
  readonly event: EventSchedulerEventEntity;
  readonly resource?: EventSchedulerResourceEntity;
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly labels: EventSchedulerLabels;
  readonly readonly: boolean;
  readonly validationMessage?: string;
  readonly submit: (changes: EventSchedulerEventEditChanges) => void;
  readonly delete: () => void;
  readonly close: () => void
}
```

---

### `EventSchedulerEventEditorHook`

```ts
export type EventSchedulerEventEditorHook = (context: EventSchedulerEventEditorOpenContext) => boolean | void;
```

---

### `EventSchedulerEventTemplate`

```ts
export type EventSchedulerEventTemplate = (
  createElement: (tag: string, props?: Record<string, unknown>, children?: unknown) => VNode,
  context: EventSchedulerEventSectionContext,
) => VNode | string | null | undefined;
```

---

### `EventSchedulerRemoteMode`

```ts
export type EventSchedulerRemoteMode = 'local' | 'remote' | 'hybrid';
```

---

### `EventSchedulerRemoteLoadTarget`

```ts
export type EventSchedulerRemoteLoadTarget = 'events' | 'resources' | 'availability' | 'coverage' | 'unassigned' | 'resource-children';
```

---

### `EventSchedulerRemoteMutationStatus`

```ts
export type EventSchedulerRemoteMutationStatus = 'pending' | 'committed' | 'rejected';
```

---

### `EventSchedulerRemoteRangeRequest`

```ts
interface EventSchedulerRemoteRangeRequest {
  readonly requestId: string;
  readonly dateRange: EventSchedulerDateRange;
  readonly timelineDates: readonly string[];
  readonly view: EventSchedulerView;
  readonly filters: EventSchedulerFilterState;
  readonly resourceIds?: readonly EventSchedulerEntityId[];
  readonly signal: AbortSignal
}
```

---

### `EventSchedulerRemoteResourceRequest` (Extended from `index.ts`)

```ts
interface EventSchedulerRemoteResourceRequest {
  readonly parentId?: EventSchedulerEntityId;
  readonly cursor?: string;
  readonly offset?: number;
  readonly limit?: number
}
```

---

### `EventSchedulerRemoteEventsResult`

```ts
interface EventSchedulerRemoteEventsResult {
  readonly events: readonly EventSchedulerEventEntity[];
  readonly assignments?: readonly EventSchedulerAssignmentEntity[];
  readonly rangeComplete?: boolean;
  readonly partial?: boolean
}
```

---

### `EventSchedulerRemoteResourcesResult`

```ts
interface EventSchedulerRemoteResourcesResult {
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly cursor?: string;
  readonly hasMore?: boolean;
  readonly rangeComplete?: boolean;
  readonly partial?: boolean
}
```

---

### `EventSchedulerRemoteAvailabilityResult`

```ts
interface EventSchedulerRemoteAvailabilityResult {
  readonly availability: readonly EventSchedulerAvailabilityEntity[];
  readonly rangeComplete?: boolean;
  readonly partial?: boolean
}
```

---

### `EventSchedulerRemoteCoverageResult`

```ts
interface EventSchedulerRemoteCoverageResult {
  readonly coverageRequirements: readonly EventSchedulerCoverageRequirementEntity[];
  readonly rangeComplete?: boolean;
  readonly partial?: boolean
}
```

---

### `EventSchedulerRemoteValidationResult`

```ts
interface EventSchedulerRemoteValidationResult {
  readonly accepted: boolean;
  readonly message?: string;
  readonly conflicts?: readonly EventSchedulerConflict[];
  readonly events?: readonly EventSchedulerEventEntity[];
  readonly assignments?: readonly EventSchedulerAssignmentEntity[]
}
```

---

### `EventSchedulerRemoteCommitResult` (Extended from `index.ts`)

```ts
interface EventSchedulerRemoteCommitResult {
  readonly event?: EventSchedulerEventEntity;
  readonly deletedEventId?: EventSchedulerEntityId
}
```

---

### `EventSchedulerRemoteMutationRequest`

```ts
interface EventSchedulerRemoteMutationRequest {
  readonly requestId: string;
  readonly action: EventSchedulerMutationAction;
  readonly eventId: EventSchedulerEntityId | null;
  readonly event: EventSchedulerEventEntity | null;
  readonly previousEvent?: EventSchedulerEventEntity;
  readonly previousEvents: readonly EventSchedulerEventEntity[];
  readonly events: readonly EventSchedulerEventEntity[];
  readonly changes: EventSchedulerEventEditChanges;
  readonly conflicts?: readonly EventSchedulerConflict[];
  readonly dateRange: EventSchedulerDateRange;
  readonly timelineDates: readonly string[];
  readonly signal: AbortSignal
}
```

---

### `EventSchedulerRemoteConfig`

Remote-data hooks for server-backed or partially-loaded scheduler datasets.

**Example:**
```typescript
eventScheduler: {
  view: 'resourceTimeline',
  weekStartDate: '2026-06-08',
  remote: {
    enabled: true,
    mode: 'remote',
    loadEvents: ({ dateRange, signal }) => api.loadEvents(dateRange, { signal }),
    commitMutation: ({ action, event, previousEvent }) => api.saveScheduleChange({ action, event, previousEvent })
  }
}
```

```ts
interface EventSchedulerRemoteConfig {
  readonly mode?: EventSchedulerRemoteMode;
  readonly enabled?: boolean;
  readonly debounceMs?: number;
  readonly overscanDays?: number;
  readonly resourcePageSize?: number;
  readonly loadEvents?: (request: EventSchedulerRemoteRangeRequest) => Promise<EventSchedulerRemoteEventsResult> | EventSchedulerRemoteEventsResult;
  readonly loadResources?: (request: EventSchedulerRemoteResourceRequest) => Promise<EventSchedulerRemoteResourcesResult> | EventSchedulerRemoteResourcesResult;
  readonly loadAvailability?: (request: EventSchedulerRemoteRangeRequest) => Promise<EventSchedulerRemoteAvailabilityResult> | EventSchedulerRemoteAvailabilityResult;
  readonly loadCoverage?: (request: EventSchedulerRemoteRangeRequest) => Promise<EventSchedulerRemoteCoverageResult> | EventSchedulerRemoteCoverageResult;
  readonly loadUnassignedEvents?: (request: EventSchedulerRemoteRangeRequest) => Promise<EventSchedulerRemoteEventsResult> | EventSchedulerRemoteEventsResult;
  readonly loadResourceChildren?: (request: EventSchedulerRemoteResourceRequest) => Promise<EventSchedulerRemoteResourcesResult> | EventSchedulerRemoteResourcesResult;
  readonly validateMutation?: (request: EventSchedulerRemoteMutationRequest) => Promise<EventSchedulerRemoteValidationResult> | EventSchedulerRemoteValidationResult;
  readonly commitMutation?: (request: EventSchedulerRemoteMutationRequest) => Promise<EventSchedulerRemoteCommitResult> | EventSchedulerRemoteCommitResult;
  readonly refreshPolicy?: 'visible-range' | 'changed-range' | 'none';
  readonly optimistic?: boolean;
  readonly rollbackOnError?: boolean
}
```

---

### `EventSchedulerRemoteState`

Current remote-data lifecycle state exposed through `plugin.getRemoteState()`.

```ts
interface EventSchedulerRemoteState {
  readonly enabled: boolean;
  readonly mode: EventSchedulerRemoteMode;
  readonly dateRange?: EventSchedulerDateRange;
  readonly loading: Readonly<Record<EventSchedulerRemoteLoadTarget | 'initial' | 'refresh' | 'mutation', boolean>>;
  readonly loaded: Readonly<Partial<Record<EventSchedulerRemoteLoadTarget, boolean>>>;
  readonly partial: boolean;
  readonly empty: boolean;
  readonly error?: string;
  readonly errorTarget?: EventSchedulerRemoteLoadTarget | 'mutation';
  readonly requestId?: string;
  readonly pendingEventIds: readonly EventSchedulerEntityId[];
  readonly failedEventIds: readonly EventSchedulerEntityId[];
  readonly resourceCursor?: string;
  readonly hasMoreResources: boolean
}
```

---

### `EventSchedulerDayHeaderShiftCountConfig`

```ts
interface EventSchedulerDayHeaderShiftCountConfig {
  /** Enables per-day event counts in week/day/month headers. Defaults to true. */
    readonly enabled?: boolean;
  /** Formats the count label shown under the day/date header. */
    readonly formatter?: (count: number, context: { readonly date: string; readonly dayIndex: number }) => string
}
```

---

### `EventSchedulerTodayHighlightConfig`

```ts
interface EventSchedulerTodayHighlightConfig {
  /** Enables today header/cell highlighting. Defaults to true. */
    readonly enabled?: boolean;
  /** Optional CSS class applied to today headers/cells. */
    readonly className?: string
}
```

---

### `EventSchedulerWeekendHighlightConfig`

```ts
interface EventSchedulerWeekendHighlightConfig {
  /** Enables weekend header/cell highlighting. Defaults to true. */
    readonly enabled?: boolean;
  /** Weekday indexes treated as weekends. Defaults to Saturday/Sunday. */
    readonly days?: readonly number[];
  /** Optional CSS class applied to weekend headers/cells. */
    readonly className?: string
}
```

---

### `EventSchedulerWorkingHoursConfig`

```ts
interface EventSchedulerWorkingHoursConfig {
  /** Weekdays where the ranges apply. Defaults to every visible day. */
    readonly days?: readonly number[];
  /** Working ranges for the configured days. */
    readonly ranges?: EventSchedulerTimeRange | readonly EventSchedulerTimeRange[];
  /** Per-weekday working ranges, where Sunday is 0 and Saturday is 6. Use `false` for a closed day. */
    readonly byDay?: Partial<Record<number, EventSchedulerTimeRange | readonly EventSchedulerTimeRange[] | false>>
}
```

---

### `EventSchedulerClosedHoursConfig`

```ts
interface EventSchedulerClosedHoursConfig {
  readonly id?: EventSchedulerEntityId;
  readonly days?: readonly number[];
  readonly dates?: readonly string[];
  readonly ranges?: EventSchedulerTimeRange | readonly EventSchedulerTimeRange[];
  readonly title?: string;
  readonly reason?: string;
  readonly className?: string
}
```

---

### `EventSchedulerAvailabilityRuleContext` (Extended from `index.ts`)

```ts
interface EventSchedulerAvailabilityRuleContext {
  readonly resourceId?: EventSchedulerEntityId
}
```

---

### `EventSchedulerAvailabilityRuleResult`

```ts
interface EventSchedulerAvailabilityRuleResult {
  readonly available?: boolean;
  readonly title?: string;
  readonly reason?: string;
  readonly className?: string
}
```

---

### `EventSchedulerAvailabilityRule`

```ts
export type EventSchedulerAvailabilityRule =
  | ((context: EventSchedulerAvailabilityRuleContext) => boolean | EventSchedulerAvailabilityRuleResult | null | undefined)
  | {
      readonly available?: boolean;
      readonly days?: readonly number[];
      readonly dates?: readonly string[];
      readonly ranges?: EventSchedulerTimeRange | readonly EventSchedulerTimeRange[];
      readonly title?: string;
      readonly reason?: string;
      readonly className?: string;
    };
```

---

### `EventSchedulerContextMenuTarget`

```ts
export type EventSchedulerContextMenuTarget = 'event' | 'slot' | 'dayHeader' | 'timeRow' | 'background';
```

---

### `EventSchedulerContextMenuItemId`

```ts
export type EventSchedulerContextMenuItemId =
  | 'event-title'
  | 'event-title-divider'
  | 'edit'
  | 'copy'
  | 'duplicate'
  | 'lock'
  | 'event-edit-divider'
  | 'confirm'
  | 'color'
  | 'event-status-divider'
  | 'delete'
  | 'slot-title'
  | 'slot-title-divider'
  | 'create'
  | 'slot-create-divider'
  | 'paste'
  | 'zoom-divider'
  | 'zoomIn'
  | 'zoomOut';
```

---

### `EventSchedulerContextMenuItemMap`

```ts
export type EventSchedulerContextMenuItemMap = Partial<Record<EventSchedulerContextMenuItemId, boolean>>;
```

---

### `EventSchedulerContextMenuItemsContext`

```ts
interface EventSchedulerContextMenuItemsContext {
  /** Which scheduler surface opened the menu. */
    readonly target: EventSchedulerContextMenuTarget;
  /** Active scheduler projection when the menu opens. */
    readonly projection: EventSchedulerProjection;
  /** Event segment for event-bar menus. */
    readonly segment?: EventSchedulerEventSegment;
  /** Slot context for empty-cell menus. */
    readonly slot?: EventSchedulerSlotContext & { readonly resourceId?: EventSchedulerEntityId };
  /** Resource id resolved from the clicked slot or event segment when available. */
    readonly resourceId?: EventSchedulerEntityId
}
```

---

### `EventSchedulerContextMenuActionContext` (Extended from `index.ts`)

```ts
interface EventSchedulerContextMenuActionContext {
  /** Scheduler item id selected by the user. */
    readonly itemId: string;
  /** Original scheduler menu item when the item was produced from the scheduler-specific item API. */
    readonly item?: EventSchedulerContextMenuItem
}
```

---

### `EventSchedulerContextMenuItemHidden`

```ts
export type EventSchedulerContextMenuItemHidden =
  | boolean
  | ((context: EventSchedulerContextMenuItemsContext) => boolean);
```

---

### `EventSchedulerContextMenuItemDisabled`

```ts
export type EventSchedulerContextMenuItemDisabled =
  | boolean
  | ((context: EventSchedulerContextMenuItemsContext) => boolean);
```

---

### `EventSchedulerContextMenuItemAction`

```ts
export type EventSchedulerContextMenuItemAction = (
  context: EventSchedulerContextMenuActionContext
) => void;
```

---

### `EventSchedulerContextMenuItem`

```ts
interface EventSchedulerContextMenuItem {
  /** Stable action id emitted through `onContextMenuAction`. */
    readonly id: string;
  /** Visible item label. */
    readonly label?: string;
  /** CSS icon classes or inline SVG markup. */
    readonly icon?: string;
  /** Keyboard shortcut text rendered at the trailing edge. */
    readonly shortcut?: string;
  /** Keep item visible but disabled. */
    readonly disabled?: EventSchedulerContextMenuItemDisabled;
  /** Hide item for the current scheduler context. */
    readonly hidden?: EventSchedulerContextMenuItemHidden;
  /** Apply destructive styling. */
    readonly danger?: boolean;
  /** Render item as a separator. */
    readonly separator?: boolean;
  /** Optional group name/class suffix for visual grouping. */
    readonly group?: string;
  /** Run when selected. `onContextMenuAction` is also emitted after this callback. */
    readonly action?: EventSchedulerContextMenuItemAction;
  /** Keep the menu open after the action runs. */
    readonly keepOpen?: boolean;
  /** Raw Pro context-menu escape hatch for advanced cases. */
    readonly item?: ContextMenuItem
}
```

---

### `EventSchedulerContextMenuItemLike`

```ts
export type EventSchedulerContextMenuItemLike = ContextMenuItem | EventSchedulerContextMenuItem;
```

---

### `EventSchedulerContextMenuItemContext` (Extended from `index.ts`)

```ts
interface EventSchedulerContextMenuItemContext {
  /** Built-in Scheduler context-menu item id being transformed. */
    readonly itemId: EventSchedulerContextMenuItemId
}
```

---

### `EventSchedulerContextMenuItemsFactory`

```ts
export type EventSchedulerContextMenuItemsFactory = (
  context: EventSchedulerContextMenuItemsContext
) => readonly EventSchedulerContextMenuItemLike[];
```

---

### `EventSchedulerContextMenuTemplate`

```ts
export type EventSchedulerContextMenuTemplate = (
  h: EventSchedulerTemplateH,
  item: EventSchedulerContextMenuItem,
  context: EventSchedulerContextMenuItemsContext
) => EventSchedulerTemplateResult;
```

---

### `EventSchedulerContextMenuItemFilter`

```ts
export type EventSchedulerContextMenuItemFilter = (
  item: ContextMenuItem,
  context: EventSchedulerContextMenuItemContext
) => ContextMenuItem | false | null | undefined;
```

---

### `EventSchedulerContextMenuConfig`

```ts
interface EventSchedulerContextMenuConfig {
  /** Enables built-in Scheduler context menus. Defaults to true. */
    readonly enabled?: boolean;
  /** Append host row and header context-menu items after built-in Scheduler items. Defaults to true. */
    readonly includeHostItems?: boolean;
  /** Hide specific built-in Scheduler context-menu items by id. */
    readonly hiddenItems?: EventSchedulerContextMenuItemMap;
  /** Keep specific built-in Scheduler context-menu items visible but disabled by id. */
    readonly disabledItems?: EventSchedulerContextMenuItemMap;
  /** Extra Scheduler context-menu items appended after built-in Scheduler items. */
    readonly items?: readonly EventSchedulerContextMenuItemLike[] | EventSchedulerContextMenuItemsFactory;
  /** Slot/empty-cell menu items. Return items to replace the default slot menu for that target. */
    readonly getSlotContextMenuItems?: EventSchedulerContextMenuItemsFactory;
  /** Event-bar menu items. Return items to replace the default event menu for that target. */
    readonly getEventContextMenuItems?: EventSchedulerContextMenuItemsFactory;
  /** Optional day-header menu items for products that expose header commands. */
    readonly getDayHeaderContextMenuItems?: EventSchedulerContextMenuItemsFactory;
  /** Background menu items for empty scheduler space or slot backgrounds. */
    readonly getBackgroundContextMenuItems?: EventSchedulerContextMenuItemsFactory;
  /** Replace the content renderer for scheduler-specific menu items. */
    readonly contextMenuTemplate?: EventSchedulerContextMenuTemplate;
  /** Called after a scheduler-specific menu item action is selected. */
    readonly onContextMenuAction?: (context: EventSchedulerContextMenuActionContext) => void;
  /** Advanced hook for transforming or removing generated built-in Scheduler items. */
    readonly itemFilter?: EventSchedulerContextMenuItemFilter;
  /** Optional base context-menu config merged into the generated row menu. */
    readonly row?: Partial<ContextMenuConfig>;
  /** Optional base context-menu config merged into the generated Scheduler header menu. */
    readonly column?: Partial<ContextMenuConfig>
}
```

---

### `EventSchedulerKeyboardShortcutsConfig`

```ts
interface EventSchedulerKeyboardShortcutsConfig {
  /** Enables built-in Scheduler keyboard shortcuts. Defaults to true. */
    readonly enabled?: boolean;
  /** Enables the built-in shortcuts help panel. Defaults to true. */
    readonly helpPanel?: boolean;
  /** Command-to-shortcut map. Set a command to `false` to disable it. */
    readonly shortcuts?: Partial<Record<EventSchedulerKeyboardCommand, string | readonly string[] | false>>
}
```

---

### `EventSchedulerKeyboardCommand`

```ts
export type EventSchedulerKeyboardCommand =
  | 'escape'
  | 'help'
  | 'today'
  | 'search'
  | 'previous'
  | 'next'
  | 'cyclePrevious'
  | 'cycleNext'
  | 'open'
  | 'create'
  | 'edit'
  | 'lock'
  | 'delete'
  | 'copy'
  | 'paste'
  | 'duplicate'
  | 'viewWeek'
  | 'viewMonth'
  | 'viewYear';
```

---

### `EventSchedulerContinuationLabelsConfig`

```ts
interface EventSchedulerContinuationLabelsConfig {
  /** Enables labels on cross-day event segments. Defaults to true. */
    readonly enabled?: boolean;
  /** Label shown when the visible segment continues from a previous day. */
    readonly previousLabel?: string;
  /** Label shown when the visible segment continues into the next day. */
    readonly nextLabel?: string;
  /** Optional CSS class applied to continuation labels. */
    readonly className?: string;
  /** Custom formatter for continuation labels. Return an empty string to hide a label. */
    readonly formatter?: (direction: 'previous' | 'next', context: EventSchedulerRenderContext) => string
}
```

---

### `EventSchedulerTimelineHeaderUnit`

Calendar unit rendered by one resource-timeline header row.

```ts
/** Calendar unit rendered by one resource-timeline header row. */
export type EventSchedulerTimelineHeaderUnit = 'year' | 'month' | 'day' | 'time';
```

---

### `EventSchedulerTimelineHeaderRowContext`

Values available while formatting a configurable resource-timeline header row.

```ts
interface EventSchedulerTimelineHeaderRowContext {
  readonly id: string;
  readonly unit: EventSchedulerTimelineHeaderUnit;
  readonly date: string;
  readonly rowIndex: number;
  readonly isLeafRow: boolean;
  readonly defaultLabel: string;
  readonly dayIndex?: number;
  readonly slotIndex?: number;
  readonly timelineSlotIndex?: number;
  readonly startMinutes?: number;
  readonly endMinutes?: number;
  readonly startDateTime?: string;
  readonly endDateTime?: string
}
```

---

### `EventSchedulerTimelineHeaderRowConfig`

One ordered resource-timeline header row, from the coarsest unit to the leaf unit.

```ts
interface EventSchedulerTimelineHeaderRowConfig {
  /** Stable row id used by formatters and future row-level customization. */
    readonly id: string;
  /** Calendar unit represented by this row. */
    readonly unit: EventSchedulerTimelineHeaderUnit;
  /** Overrides the built-in compact label for this row. */
    readonly formatter?: (context: EventSchedulerTimelineHeaderRowContext) => string
}
```

---

### `EventSchedulerZoomConfig`

```ts
interface EventSchedulerZoomConfig {
  /** Enables Scheduler timescale zoom. Defaults to true. */
    readonly enabled?: boolean;
  /** Ordered or unordered slot sizes, in minutes, available to zoom actions. */
    readonly levels?: readonly number[]
}
```

---

### `EventSchedulerResolvedConfig`

```ts
interface EventSchedulerResolvedConfig {
  readonly view: EventSchedulerView;
  readonly weekStartDate: string;
  readonly dateRange: EventSchedulerDateRange;
  readonly timelineDates: readonly string[];
  readonly timeZone?: string;
  readonly locale: string;
  readonly weekStartsOn: number;
  readonly visibleDays: readonly number[];
  readonly slotMinutes: number;
  readonly snapMinutes: number;
  readonly timeRange: EventSchedulerTimeRange;
  readonly zoom: Required<Pick<EventSchedulerZoomConfig, 'enabled'>> & {
      readonly levels?: readonly number[];
    };
  readonly editable: boolean;
  readonly allowCreate: EventSchedulerConfig['allowCreate'];
  readonly allowMove: EventSchedulerConfig['allowMove'];
  readonly allowResize: EventSchedulerConfig['allowResize'];
  readonly allowDelete: EventSchedulerConfig['allowDelete'];
  readonly allowMultiResourceAssignment: boolean;
  readonly rowSize: number;
  readonly timeColumnSize: number;
  readonly dayColumnSize: number;
  readonly resourceColumnSize: number;
  readonly timelineColumnSize: number;
  readonly customization?: EventSchedulerCustomizationConfig;
  readonly columnGrouping: boolean;
  readonly timelineHeaderRows: readonly EventSchedulerTimelineHeaderRowConfig[];
  readonly eventLayout: EventSchedulerEventLayout;
  readonly maxStackedEvents: number;
  readonly compactThreshold: number;
  readonly conflicts: Required<Omit<EventSchedulerConflictConfig, 'rules' | 'messages' | 'minDurationMinutes' | 'maxDurationMinutes'>> & {
      readonly rules: Readonly<Partial<Record<EventSchedulerConflictType, EventSchedulerConflictRulePolicy>>>;
      readonly minDurationMinutes?: number;
      readonly maxDurationMinutes?: number;
      readonly messages: Readonly<Partial<Record<EventSchedulerConflictType, string>>>;
    };
  readonly currentTimeMarker: EventSchedulerResolvedCurrentTimeMarkerConfig;
  readonly dayHeaderShiftCount: Required<Pick<EventSchedulerDayHeaderShiftCountConfig, 'enabled'>> & {
      readonly formatter?: EventSchedulerDayHeaderShiftCountConfig['formatter'];
    };
  readonly todayHighlight: Required<Pick<EventSchedulerTodayHighlightConfig, 'enabled'>> & {
      readonly className?: string;
    };
  readonly weekendHighlight: Required<Pick<EventSchedulerWeekendHighlightConfig, 'enabled' | 'days'>> & {
      readonly className?: string;
    };
  readonly contextMenu: Required<Pick<EventSchedulerContextMenuConfig, 'enabled' | 'includeHostItems'>>
      & Omit<EventSchedulerContextMenuConfig, 'enabled' | 'includeHostItems'>;
  readonly keyboardShortcuts: Required<Pick<EventSchedulerKeyboardShortcutsConfig, 'enabled' | 'helpPanel'>> & {
      readonly shortcuts: Readonly<Record<EventSchedulerKeyboardCommand, readonly string[] | false>>;
    };
  readonly continuationLabels: Required<Pick<EventSchedulerContinuationLabelsConfig, 'enabled' | 'previousLabel' | 'nextLabel'>> & {
      readonly className?: string;
      readonly formatter?: EventSchedulerContinuationLabelsConfig['formatter'];
    };
  readonly nonWorkingTime: EventSchedulerResolvedNonWorkingTimeConfig;
  readonly calendars: EventSchedulerResolvedCalendarsConfig;
  readonly resourceGrouping: EventSchedulerResourceGroupingConfig;
  readonly filters: EventSchedulerFilterState;
  readonly activeSavedViewId?: EventSchedulerEntityId;
  readonly selection: EventSchedulerSelectionConfig;
  readonly coverage: Required<Pick<EventSchedulerCoverageConfig, 'enabled'>>;
  readonly utilization: Required<Pick<EventSchedulerUtilizationConfig, 'enabled'>>;
  readonly unassigned: Required<Pick<EventSchedulerUnassignedConfig, 'enabled' | 'showCount'>>;
  readonly labels: EventSchedulerLabels;
  readonly source: EventSchedulerConfig
}
```

---

### `EventSchedulerGridRow` (Extended from `index.ts`)

```ts
interface EventSchedulerGridRow {
  readonly __eventSchedulerSlot?: true;
  readonly __eventSchedulerResource?: true;
  readonly __eventSchedulerResourceGroup?: true;
  readonly __eventSchedulerEmpty?: true;
  readonly __eventSchedulerCalendarWeek?: true;
  readonly __eventSchedulerCalendarYear?: true;
  readonly slotIndex: number;
  readonly startMinutes: number;
  readonly endMinutes: number;
  readonly timeLabel: string;
  readonly currentTimeLabel?: string;
  readonly currentTimeTop?: number;
  readonly resourceId?: EventSchedulerEntityId;
  readonly resource?: EventSchedulerResourceEntity;
  readonly resourceLabel?: string;
  readonly resourceDepth?: number;
  readonly resourceParentId?: EventSchedulerEntityId;
  readonly resourceGroupId?: string;
  readonly resourceGroupKey?: EventSchedulerEntityId;
  readonly resourceGroupLabel?: string;
  readonly resourceGroupPath?: readonly string[];
  readonly resourceGroupDepth?: number;
  readonly resourceGroupExpanded?: boolean;
  readonly resourceGroupSummary?: EventSchedulerResourceGroupSummary;
  readonly resourceGroupSummaryLabel?: string;
  readonly coverageSummary?: EventSchedulerCoverageSummary;
  readonly coverageSummaryLabel?: string;
  readonly utilization?: EventSchedulerUtilizationResult;
  readonly utilizationSummary?: EventSchedulerUtilizationSummary;
  readonly utilizationSummaryLabel?: string;
  readonly unassignedSummary?: EventSchedulerUnassignedSummary;
  readonly unassignedSummaryLabel?: string;
  readonly unassignedRequiredRolesLabel?: string;
  readonly calendarWeekIndex?: number;
  readonly calendarDays?: readonly EventSchedulerCalendarDay[];
  readonly calendarYearMonths?: readonly EventSchedulerCalendarMonthSummary[];
  readonly [key: string]: unknown
}
```

---

### `EventSchedulerCalendarDay`

```ts
interface EventSchedulerCalendarDay {
  readonly date: string;
  readonly dayIndex: number;
  readonly dayOfMonth: number;
  readonly weekday: number;
  readonly currentPeriod: boolean;
  readonly today: boolean;
  readonly weekend: boolean;
  readonly holiday: boolean;
  readonly nonWorking: boolean;
  readonly disabled: boolean;
  readonly conflict: boolean;
  readonly selected: boolean;
  readonly locked: boolean;
  readonly holidayLabel?: string;
  readonly className?: string;
  /** Filtered events occupying this date, with midnight-exclusive end semantics applied once. */
    readonly eventIds: readonly EventSchedulerEntityId[];
  readonly eventCount: number;
  readonly overflowCount: number
}
```

---

### `EventSchedulerCalendarBar`

```ts
interface EventSchedulerCalendarBar {
  readonly id: string;
  readonly event: EventSchedulerEventEntity;
  readonly segment: EventSchedulerEventSegment;
  readonly weekIndex: number;
  readonly startDay: number;
  readonly endDay: number;
  readonly laneIndex: number;
  readonly hidden: boolean;
  readonly continuesFromPreviousWeek: boolean;
  readonly continuesToNextWeek: boolean
}
```

---

### `EventSchedulerCalendarWeek`

```ts
interface EventSchedulerCalendarWeek {
  readonly index: number;
  readonly startDate: string;
  readonly endDate: string;
  readonly days: readonly EventSchedulerCalendarDay[];
  readonly bars: readonly EventSchedulerCalendarBar[]
}
```

---

### `EventSchedulerCalendarMonthSummary`

```ts
interface EventSchedulerCalendarMonthSummary {
  readonly monthIndex: number;
  readonly label: string;
  readonly startDate: string;
  readonly days: readonly EventSchedulerCalendarDay[]
}
```

---

### `EventSchedulerCalendarProjection`

```ts
interface EventSchedulerCalendarProjection {
  readonly periodStart: string;
  readonly periodEnd: string;
  readonly weekdayLabels: readonly string[];
  readonly weeks: readonly EventSchedulerCalendarWeek[];
  readonly months: readonly EventSchedulerCalendarMonthSummary[]
}
```

---

### `EventSchedulerCalendarColumn` (Extended from `index.ts`)

```ts
interface EventSchedulerCalendarColumn {
  readonly eventSchedulerCalendarDayPosition?: number;
  readonly eventSchedulerCalendarYear?: true
}
```

---

### `EventSchedulerDayColumn` (Extended from `index.ts`)

```ts
interface EventSchedulerDayColumn {
  readonly eventSchedulerDayIndex: number;
  readonly eventSchedulerDate: string;
  readonly eventSchedulerEventCount?: number;
  readonly eventSchedulerToday?: boolean;
  readonly eventSchedulerWeekend?: boolean;
  readonly eventSchedulerHoliday?: boolean;
  readonly eventSchedulerHolidayLabel?: string
}
```

---

### `EventSchedulerTimelineColumn` (Extended from `index.ts`)

```ts
interface EventSchedulerTimelineColumn {
  readonly eventSchedulerDayIndex: number;
  readonly eventSchedulerDate: string;
  readonly eventSchedulerSlotIndex: number;
  readonly eventSchedulerTimelineSlotIndex: number;
  readonly eventSchedulerStartMinutes: number;
  readonly eventSchedulerEndMinutes: number;
  readonly eventSchedulerStartDateTime: string;
  readonly eventSchedulerEndDateTime: string
}
```

---

### `EventSchedulerTimeSlot`

```ts
interface EventSchedulerTimeSlot {
  readonly index: number;
  readonly startMinutes: number;
  readonly endMinutes: number;
  readonly label: string
}
```

---

### `EventSchedulerDay`

```ts
interface EventSchedulerDay {
  readonly dayIndex: number;
  readonly date: string;
  readonly label: string;
  readonly columnProp: string;
  readonly eventCount: number;
  readonly today: boolean;
  readonly weekend: boolean;
  readonly holiday: boolean;
  readonly holidayLabel?: string
}
```

---

### `EventSchedulerEventSegment`

```ts
interface EventSchedulerEventSegment {
  readonly id: string;
  readonly eventId: EventSchedulerEntityId;
  readonly event: EventSchedulerEventEntity;
  readonly resource?: EventSchedulerResourceEntity;
  readonly dayIndex: number;
  readonly date: string;
  readonly columnProp: string;
  readonly resourceId?: EventSchedulerEntityId;
  readonly resourceIds: readonly EventSchedulerEntityId[];
  readonly assignmentIds: readonly EventSchedulerEntityId[];
  readonly unassigned: boolean;
  readonly startDateTime: string;
  readonly endDateTime: string;
  readonly startMinutes: number;
  readonly endMinutes: number;
  readonly startSlot: number;
  readonly endSlot: number;
  readonly laneIndex: number;
  readonly laneCount: number;
  readonly conflict: boolean;
  readonly conflictSeverity?: EventSchedulerConflictSeverity;
  readonly conflictTypes: readonly EventSchedulerConflictType[];
  readonly conflictIds: readonly string[];
  readonly clippedStart: boolean;
  readonly clippedEnd: boolean;
  readonly continuesFromPreviousDay: boolean;
  readonly continuesToNextDay: boolean
}
```

---

### `EventSchedulerConflict`

```ts
interface EventSchedulerConflict {
  readonly id: string;
  readonly type: EventSchedulerConflictType;
  readonly severity: EventSchedulerConflictSeverity;
  readonly policy: EventSchedulerConflictRulePolicy;
  readonly message: string;
  readonly eventIds: readonly EventSchedulerEntityId[];
  readonly segmentIds: readonly string[];
  readonly resourceId?: EventSchedulerEntityId;
  readonly availabilityId?: EventSchedulerEntityId;
  readonly date: string;
  readonly startDateTime?: string;
  readonly endDateTime?: string;
  readonly metadata?: Record<string, unknown>
}
```

---

### `EventSchedulerNormalizedAvailability`

```ts
interface EventSchedulerNormalizedAvailability {
  readonly id: EventSchedulerEntityId;
  readonly availability: EventSchedulerAvailabilityEntity;
  readonly resourceId?: EventSchedulerEntityId;
  readonly resourceIds: readonly EventSchedulerEntityId[];
  readonly unassigned: boolean;
  readonly startDateTime: string;
  readonly endDateTime: string;
  readonly kind: EventSchedulerAvailabilityKind;
  readonly date: string
}
```

---

### `EventSchedulerProjectionBase`

```ts
interface EventSchedulerProjectionBase {
  readonly config: EventSchedulerResolvedConfig;
  readonly days: readonly EventSchedulerDay[];
  readonly slots: readonly EventSchedulerTimeSlot[];
  readonly rows: readonly EventSchedulerGridRow[];
  readonly columns: ColumnData;
  readonly events: readonly EventSchedulerEventEntity[];
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly assignments: readonly EventSchedulerAssignmentEntity[];
  readonly availability: readonly EventSchedulerNormalizedAvailability[];
  readonly coverageRequirements: readonly EventSchedulerCoverageRequirementEntity[];
  readonly coverageResults: readonly EventSchedulerCoverageResult[];
  readonly utilizationResults: readonly EventSchedulerUtilizationResult[];
  readonly unassignedSummary: EventSchedulerUnassignedSummary;
  readonly filterSummary: EventSchedulerFilterSummary;
  readonly segments: readonly EventSchedulerEventSegment[];
  readonly conflicts: readonly EventSchedulerConflict[]
}
```

---

### `EventSchedulerTimeGridProjection` (Extended from `index.ts`)

```ts
export type EventSchedulerTimeGridProjection = EventSchedulerProjectionBase & {
  readonly layout: 'timeGrid';
  readonly calendar?: undefined;
};
```

---

### `EventSchedulerResourceTimelineProjection` (Extended from `index.ts`)

```ts
export type EventSchedulerResourceTimelineProjection = EventSchedulerProjectionBase & {
  readonly layout: 'resourceTimeline';
  readonly calendar?: undefined;
};
```

---

### `EventSchedulerMonthProjection` (Extended from `index.ts`)

```ts
export type EventSchedulerMonthProjection = EventSchedulerProjectionBase & {
  readonly layout: 'calendarMonth';
  readonly calendar: EventSchedulerCalendarProjection;
};
```

---

### `EventSchedulerYearProjection` (Extended from `index.ts`)

```ts
export type EventSchedulerYearProjection = EventSchedulerProjectionBase & {
  readonly layout: 'calendarYear';
  readonly calendar: EventSchedulerCalendarProjection;
};
```

---

### `EventSchedulerProjection`

```ts
export type EventSchedulerProjection =
  | EventSchedulerTimeGridProjection
  | EventSchedulerResourceTimelineProjection
  | EventSchedulerMonthProjection
  | EventSchedulerYearProjection;
```

---

### `EventSchedulerBeforeEventChangeDetail`

```ts
interface EventSchedulerBeforeEventChangeDetail {
  readonly action: EventSchedulerMutationAction;
  readonly eventId: EventSchedulerEntityId | null;
  readonly event: EventSchedulerEventEntity | null;
  readonly changes: Partial<EventSchedulerEventEntity>;
  readonly previousValues: Partial<EventSchedulerEventEntity>;
  readonly conflicts?: readonly EventSchedulerConflict[];
  readonly reason?: string
}
```

---

### `EventSchedulerEventChangedDetail`

```ts
interface EventSchedulerEventChangedDetail {
  readonly action: EventSchedulerMutationAction;
  readonly eventId: EventSchedulerEntityId;
  readonly event: EventSchedulerEventEntity;
  readonly previousEvent?: EventSchedulerEventEntity;
  readonly events: readonly EventSchedulerEventEntity[];
  readonly conflicts?: readonly EventSchedulerConflict[]
}
```

---

### `EventSchedulerEventDeletedDetail`

```ts
interface EventSchedulerEventDeletedDetail {
  readonly eventId: EventSchedulerEntityId;
  readonly event: EventSchedulerEventEntity;
  readonly events: readonly EventSchedulerEventEntity[];
  readonly conflicts?: readonly EventSchedulerConflict[]
}
```

---

### `EventSchedulerEventCopiedDetail`

```ts
interface EventSchedulerEventCopiedDetail {
  readonly eventIds: readonly EventSchedulerEntityId[];
  readonly events: readonly EventSchedulerEventEntity[]
}
```

---

### `EventSchedulerEventSelectedDetail`

```ts
interface EventSchedulerEventSelectedDetail {
  readonly eventId: EventSchedulerEntityId | null;
  readonly event: EventSchedulerEventEntity | null;
  readonly eventIds: readonly EventSchedulerEntityId[];
  readonly events: readonly EventSchedulerEventEntity[];
  readonly selectionMode: 'replace' | 'toggle' | 'range' | 'clear' | 'api'
}
```

---

### `EventSchedulerSlotSelectedDetail` (Extended from `index.ts`)

```ts
interface EventSchedulerSlotSelectedDetail {
  readonly resourceId?: EventSchedulerEntityId;
  readonly selectionMode: 'replace' | 'toggle' | 'range' | 'clear' | 'api'
}
```

---

### `EventSchedulerBeforeSlotSelectDetail` (Extended from `index.ts`)

```ts
interface EventSchedulerBeforeSlotSelectDetail {
  readonly resourceId?: EventSchedulerEntityId;
  readonly selectionMode: EventSchedulerSlotSelectedDetail['selectionMode']
}
```

---

### `EventSchedulerSlotClickDetail` (Extended from `index.ts`)

```ts
interface EventSchedulerSlotClickDetail {
  readonly resourceId?: EventSchedulerEntityId
}
```

---

### `EventSchedulerConflictsUpdatedDetail`

```ts
interface EventSchedulerConflictsUpdatedDetail {
  readonly conflicts: readonly EventSchedulerConflict[]
}
```

---

### `EventSchedulerRemoteLoadDetail`

```ts
interface EventSchedulerRemoteLoadDetail {
  readonly target: EventSchedulerRemoteLoadTarget;
  readonly requestId: string;
  readonly dateRange?: EventSchedulerDateRange;
  readonly state: EventSchedulerRemoteState;
  readonly error?: string
}
```

---

### `EventSchedulerRemoteMutationDetail`

```ts
interface EventSchedulerRemoteMutationDetail {
  readonly status: EventSchedulerRemoteMutationStatus;
  readonly requestId: string;
  readonly action: EventSchedulerMutationAction;
  readonly eventId: EventSchedulerEntityId | null;
  readonly event: EventSchedulerEventEntity | null;
  readonly previousEvent?: EventSchedulerEventEntity;
  /** Event collection before the optimistic mutation, used by domain history and rollback integrations. */
    readonly previousEvents: readonly EventSchedulerEventEntity[];
  readonly events: readonly EventSchedulerEventEntity[];
  readonly conflicts?: readonly EventSchedulerConflict[];
  readonly message?: string;
  readonly state: EventSchedulerRemoteState
}
```

---

### `EventSchedulerRemoteStateChangeDetail`

```ts
interface EventSchedulerRemoteStateChangeDetail {
  readonly state: EventSchedulerRemoteState
}
```

---

### `EventSchedulerNavigateRequestDetail`

```ts
interface EventSchedulerNavigateRequestDetail {
  readonly action: 'previous' | 'next' | 'today'
}
```

---

### `EventSchedulerViewRequestDetail`

```ts
interface EventSchedulerViewRequestDetail {
  readonly view: EventSchedulerView;
  /** Optional date to anchor the requested view, used by calendar drill-down. */
    readonly date?: string
}
```

---

### `EventSchedulerResourceReassignRequestDetail`

```ts
interface EventSchedulerResourceReassignRequestDetail {
  readonly eventId: EventSchedulerEntityId;
  readonly event: EventSchedulerEventEntity
}
```

---

### `EventSchedulerOpenShiftAssignRequestDetail` (Extended from `index.ts`)

```ts
interface EventSchedulerOpenShiftAssignRequestDetail {
  readonly resourceId?: EventSchedulerEntityId
}
```

---

### `EventSchedulerSearchFocusRequestDetail`

```ts
interface EventSchedulerSearchFocusRequestDetail {
  readonly reason: 'keyboard'
}
```

---

### `EventSchedulerColumnTypeMap`

```ts
interface EventSchedulerColumnTypeMap {
  readonly eventSchedulerTime: ColumnType;
  readonly eventSchedulerDay: ColumnType;
  readonly eventSchedulerResource: ColumnType;
  readonly eventSchedulerTimeline: ColumnType
}
```

---

### `createEventSchedulerProjection`

```ts
export function createEventSchedulerProjection(
  config: EventSchedulerConfig,
  events: readonly EventSchedulerEventEntity[] = [],
  resources: readonly EventSchedulerResourceEntity[] = [],
  assignments: readonly EventSchedulerAssignmentEntity[] = [],
  availability: readonly EventSchedulerAvailabilityEntity[] = [],
  coverageRequirements: readonly EventSchedulerCoverageRequirementEntity[] = [],
): EventSchedulerProjection;
```

---

### `createSlotContext`

```ts
export function createSlotContext(
  projection: EventSchedulerProjection,
  dayIndex: number,
  slotIndex: number,
);
```

---

### `createRangeContext`

```ts
export function createRangeContext(
  projection: EventSchedulerProjection,
  dayIndex: number,
  startSlot: number,
  endSlot: number,
  resourceId?: EventSchedulerEntityId,
  options: {
    readonly startMinutes?: number;
    readonly endMinutes?: number;
  } = {},
): EventSchedulerCreateRangeContext | null;
```

---

### `formatSchedulerDisplayTime`

```ts
export function formatSchedulerDisplayTime(config: EventSchedulerResolvedConfig, minutes: number, slotIndex?: number): string;
```

---

### `EVENT_SCHEDULER_UNASSIGNED_RESOURCE_ID`

```ts
EVENT_SCHEDULER_UNASSIGNED_RESOURCE_ID: string;
```

---

### `resolveUnassignedRequiredRole`

```ts
export function resolveUnassignedRequiredRole(
  config: EventSchedulerResolvedConfig,
  event: EventSchedulerEventEntity,
): string | undefined;
```

---

### `moveEvent`

Moves an event while preserving duration and optionally reassigning its resource.

```ts
export function moveEvent(
  context: EventSchedulerMutationContext,
  eventId: EventSchedulerEntityId,
  nextStartDateTime: string,
  nextResourceId?: EventSchedulerEntityId,
  options: EventSchedulerMoveMutationOptions = {},
): EventSchedulerMutationResult;
```

---

### `resizeEvent`

Resizes one event boundary while preserving the opposite boundary.

```ts
export function resizeEvent(
  context: EventSchedulerMutationContext,
  eventId: EventSchedulerEntityId,
  edge: EventSchedulerResizeEdge,
  nextDateTime: string,
  options: EventSchedulerResizeMutationOptions = {},
): EventSchedulerMutationResult;
```

---

### `editEvent`

Applies editable event fields such as title, time, resource, status, and notes.

```ts
export function editEvent(
  context: EventSchedulerMutationContext,
  eventId: EventSchedulerEntityId,
  changes: EventSchedulerEventEditChanges,
): EventSchedulerMutationResult;
```

---

### `createEvent`

Adds one event after permission, conflict, and before-change validation.

```ts
export function createEvent(
  context: EventSchedulerMutationContext,
  event: EventSchedulerEventEntity,
): EventSchedulerMutationResult;
```

---

### `deleteEvent`

Removes one event after permission and before-change validation.

```ts
export function deleteEvent(
  context: EventSchedulerMutationContext,
  eventId: EventSchedulerEntityId,
): EventSchedulerMutationResult;
```

---

### `createEventFromSlot`

Creates an event draft from a single scheduler slot.

```ts
export function createEventFromSlot(
  context: EventSchedulerMutationContext,
  options: {
    readonly id: EventSchedulerEntityId;
    readonly resourceId?: EventSchedulerEntityId;
    readonly title: string;
    readonly date: string;
    readonly startMinutes: number;
    readonly durationMinutes?: number;
  },
): EventSchedulerMutationResult;
```

---

### `createEventFromRange`

Creates an event from a selected scheduler range.

```ts
export function createEventFromRange(
  context: EventSchedulerMutationContext,
  range: EventSchedulerCreateRangeContext,
): EventSchedulerMutationResult;
```

---

### `EventSchedulerMutationContext`

```ts
interface EventSchedulerMutationContext {
  readonly config: EventSchedulerConfig;
  readonly events: readonly EventSchedulerEventEntity[];
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly assignments?: readonly EventSchedulerAssignmentEntity[];
  readonly availability?: readonly EventSchedulerAvailabilityEntity[];
  readonly emitCancelable?: (detail: EventSchedulerBeforeEventChangeDetail) => boolean
}
```

---

### `EventSchedulerMutationResult`

Result of one scheduler event mutation.

```ts
interface EventSchedulerMutationResult {
  readonly events: readonly EventSchedulerEventEntity[];
  readonly event: EventSchedulerEventEntity;
  readonly previousEvent?: EventSchedulerEventEntity;
  readonly action: EventSchedulerMutationAction;
  readonly conflicts: NonNullable<EventSchedulerBeforeEventChangeDetail['conflicts']>
}
```

---

### `EventSchedulerResizeMutationOptions`

```ts
interface EventSchedulerResizeMutationOptions {
  /**
     * Whether to snap the supplied boundary to the configured interval.
     *
     * Public API calls snap by default. Pointer interactions pass `false`
     * because their preview boundary was already snapped and range-clamped.
     */
    readonly snap?: boolean
}
```

---

### `EventSchedulerMoveMutationOptions`

```ts
interface EventSchedulerMoveMutationOptions {
  /** Public/API moves snap by default; calendar-date moves preserve authored wall-clock fields. */
    readonly snap?: boolean
}
```

---

### `uniqueEventIds`

Returns unique event ids while preserving input order.

```ts
export function uniqueEventIds(ids: Iterable<EventSchedulerEntityId>): EventSchedulerEntityId[];
```

---

### `updateSelectedEventIds`

Computes the next selected event ids for replace, toggle, range, or API selection modes.

```ts
export function updateSelectedEventIds(
  currentIds: readonly EventSchedulerEntityId[],
  eventId: EventSchedulerEntityId,
  mode: 'replace' | 'toggle' | 'range' | 'api',
  orderedEventIds: readonly EventSchedulerEntityId[],
  anchorId?: EventSchedulerEntityId,
): readonly EventSchedulerEntityId[];
```

---

### `buildEventSchedulerClipboardPayload`

Builds the internal clipboard payload from selected events.

```ts
export function buildEventSchedulerClipboardPayload(
  events: readonly EventSchedulerEventEntity[],
  copiedAt = new Date().toISOString(),
): EventSchedulerClipboardPayload | null;
```

---

### `bulkMoveEvents`

Moves selected events together while preserving their relative offsets.

```ts
export function bulkMoveEvents(
  context: EventSchedulerBulkContext,
  eventIds: readonly EventSchedulerEntityId[],
  anchorEventId: EventSchedulerEntityId,
  nextAnchorStartDateTime: string,
  nextResourceId?: EventSchedulerEntityId,
): EventSchedulerBulkResult;
```

---

### `bulkDeleteEvents`

Deletes selected events atomically.

```ts
export function bulkDeleteEvents(
  context: EventSchedulerBulkContext,
  eventIds: readonly EventSchedulerEntityId[],
): EventSchedulerBulkResult;
```

---

### `bulkUpdateEventStatus`

Updates status for selected events atomically.

```ts
export function bulkUpdateEventStatus(
  context: EventSchedulerBulkContext,
  eventIds: readonly EventSchedulerEntityId[],
  status: string,
): EventSchedulerBulkResult;
```

---

### `pasteCopiedEvents`

Pastes copied events at a target start/resource when provided.

The requested target base is snapped once to the context's effective edit
interval; relative offsets within a multi-event clipboard payload are kept.

```ts
export function pasteCopiedEvents(
  context: EventSchedulerBulkContext,
  payload: EventSchedulerClipboardPayload,
  options: EventSchedulerPasteOptions = {},
): EventSchedulerBulkResult;
```

---

### `duplicateEvents`

Duplicates selected events by an offset in days.

```ts
export function duplicateEvents(
  context: EventSchedulerBulkContext,
  eventIds: readonly EventSchedulerEntityId[],
  offsetDays = context.config.selection?.copyOffsetDays ?? 1,
): EventSchedulerBulkResult;
```

---

### `duplicateScheduleRange`

Copies all events from one date range into another date range.

```ts
export function duplicateScheduleRange(
  context: EventSchedulerBulkContext,
  options: EventSchedulerDuplicateRangeOptions,
): EventSchedulerBulkResult;
```

---

### `EventSchedulerBulkContext`

```ts
interface EventSchedulerBulkContext {
  readonly config: EventSchedulerConfig;
  readonly events: readonly EventSchedulerEventEntity[];
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly assignments?: readonly EventSchedulerAssignmentEntity[];
  readonly availability?: readonly EventSchedulerAvailabilityEntity[];
  readonly emitCancelable?: (detail: EventSchedulerBeforeEventChangeDetail) => boolean
}
```

---

### `EventSchedulerBulkResult`

Result of a bulk scheduler operation.

```ts
interface EventSchedulerBulkResult {
  readonly action: EventSchedulerMutationAction;
  readonly events: readonly EventSchedulerEventEntity[];
  readonly changedEvents: readonly EventSchedulerEventEntity[];
  readonly previousEvents: readonly EventSchedulerEventEntity[];
  readonly conflicts: NonNullable<EventSchedulerBeforeEventChangeDetail['conflicts']>
}
```

---

### `idKey`

```ts
export function idKey(id: EventSchedulerEntityId | null | undefined): string;
```

---

### `createEventFromTemplate`

Creates one event from a configured scheduler template.

```ts
export function createEventFromTemplate(
  context: EventSchedulerTemplateContext,
  options: EventSchedulerTemplateCreateOptions,
): EventSchedulerBulkResult;
```

---

### `createRecurringEvents`

Expands a template into daily or weekly recurring events.

```ts
export function createRecurringEvents(
  context: EventSchedulerTemplateContext,
  options: EventSchedulerRecurrenceCreateOptions,
): EventSchedulerBulkResult;
```

---

### `editRecurrenceSeries`

Applies changes to every matching event in a recurrence series.

```ts
export function editRecurrenceSeries(
  context: EventSchedulerTemplateContext,
  options: EventSchedulerRecurrenceSeriesEditOptions,
): EventSchedulerBulkResult;
```

---

### `deleteRecurrenceSeries`

Deletes every matching event in a recurrence series.

```ts
export function deleteRecurrenceSeries(
  context: EventSchedulerTemplateContext,
  options: EventSchedulerRecurrenceSeriesDeleteOptions,
): EventSchedulerBulkResult;
```

---

### `expandRecurrenceStartDateTimes`

Expands a simple recurrence rule into ISO start date-times.

```ts
export function expandRecurrenceStartDateTimes(
  startDateTime: string,
  recurrence: EventSchedulerRecurrenceRule,
): readonly string[];
```

---

### `EventSchedulerTemplateContext` (Extended from `index.ts`)

Context used by template and recurrence helper functions.

```ts
interface EventSchedulerTemplateContext {
  readonly templates: readonly EventSchedulerEventTemplateEntity[]
}
```

---

### `resolveEventSchedulerLabels`

```ts
export function resolveEventSchedulerLabels(
  labels: Partial<EventSchedulerLabels> | undefined,
): EventSchedulerLabels;
```

---

### `DEFAULT_EVENT_SCHEDULER_LABELS`

```ts
DEFAULT_EVENT_SCHEDULER_LABELS: {
  resourceColumn: string;
  noResources: string;
  unassignedResource: string;
  unassignedCountLabel: (count: number) => string;
  moreEventsLabel: (count: number) => string;
  eventCountLabel: (count: number) => string;
  shiftCountLabel: (count: number) => string;
  eventsOnDateLabel: (date: string) => string;
  requiredRolePrefix: string;
  today: string;
  previousContinuation: string;
  nextContinuation: string;
  resourceGroup: string;
  resourceAvatarAriaLabel: (resourceName: string) => string;
  expandResourceGroupAriaLabel: (groupLabel: string) => string;
  collapseResourceGroupAriaLabel: (groupLabel: string) => string;
  coverageSummaryLabel: typeof formatCoverageSummary;
  utilizationSummaryLabel: typeof formatUtilizationSummary;
  resourceGroupSummaryLabel: (summary: EventSchedulerResourceGroupSummary) => string;
  keyboardShortcutsTitle: string;
  closeKeyboardShortcutsAriaLabel: string;
  keyboardShortcutGroups: readonly EventSchedulerShortcutGroupLabels[];
  newEvent: string;
  createEvent: string;
  editEvent: string;
  closeEditor: string;
  closeEditorAriaLabel: string;
  titleField: string;
  startField: string;
  endField: string;
  resourceField: string;
  resourceSearchPlaceholder: string;
  resourceSearchAriaLabel: string;
  noMatchingResources: string;
  statusField: string;
  colorField: string;
  colorAction: string;
  colorPaletteAriaLabel: string;
  defaultColorAction: string;
  colorOptionAriaLabel: (color: string) => string;
  notesField: string;
  noStatus: string;
  deleteAction: string;
  copyAction: string;
  pasteAction: string;
  duplicateAction: string;
  createEventHereAction: string;
  assignOpenEventAction: string;
  editEventAction: string;
  confirmEventAction: string;
  markPlannedAction: string;
  reassignResourceAction: string;
  lockAction: string;
  unlockAction: string;
  zoomInAction: string;
  zoomOutAction: string;
  emptyClipboard: string;
  bulkStatusAction: string;
  cancelAction: string;
  saveAction: string;
  lockedEditorMessage: string;
  titleRequiredMessage: string;
  dateTimeRequiredMessage: string;
  endAfterStartMessage: string;
  closed: string;
  outsideWorkingHours: string;
  closedDay: string;
  statusPrefix: string;
  typePrefix: string;
  categoryPrefix: string;
  conflict: string;
  locked: string;
  remoteLoading: string;
  remoteRefreshing: string;
  remoteSaving: string;
  remoteEmpty: string;
  remoteError: string;
  remoteRetry: string;
  remoteMutationRejected: string;
  printTitle: string;
  printEventsSection: string;
  printResourceWorkloadSection: string;
  printConflictsSection: string;
  printCoverageGapsSection: string;
  printGeneratedLabel: string;
  printRangeSeparator: string;
  printNoRecords: string;
  reportColumnLabel: (column: string) => string;
  statusLabel: typeof toDisplayLabel;
  typeLabel: typeof toDisplayLabel;
  categoryLabel: typeof toDisplayLabel;
};
```

---

### `resolveEventSchedulerSavedViewConfig`

```ts
export function resolveEventSchedulerSavedViewConfig(config: EventSchedulerConfig): EventSchedulerConfig;
```

---

### `applyEventSchedulerFilters`

```ts
export function applyEventSchedulerFilters(options: {
  readonly config: EventSchedulerResolvedConfig;
  readonly events: readonly EventSchedulerEventEntity[];
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly assignments: readonly EventSchedulerAssignmentEntity[];
  readonly conflicts: readonly EventSchedulerConflict[];
}): EventSchedulerFilterResult;
```

---

### `EventSchedulerFilterResult`

```ts
interface EventSchedulerFilterResult {
  readonly events: readonly EventSchedulerEventEntity[];
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly summary: EventSchedulerFilterSummary
}
```

---

### `createEventSchedulerConflicts`

```ts
export function createEventSchedulerConflicts(input: EventSchedulerConflictEngineInput): EventSchedulerConflictEngineResult;
```

---

### `hasBlockingConflictsForEvent`

```ts
export function hasBlockingConflictsForEvent(
  conflicts: readonly EventSchedulerConflict[],
  eventId: EventSchedulerEntityId,
): boolean;
```

---

### `EventSchedulerConflictEngineInput`

```ts
interface EventSchedulerConflictEngineInput {
  readonly config: EventSchedulerResolvedConfig;
  readonly events: readonly EventSchedulerEventEntity[];
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly assignments: readonly EventSchedulerAssignmentEntity[];
  readonly availability: readonly EventSchedulerNormalizedAvailability[];
  readonly segments: readonly EventSchedulerEventSegment[]
}
```

---

### `EventSchedulerConflictEngineResult`

```ts
interface EventSchedulerConflictEngineResult {
  readonly conflicts: readonly EventSchedulerConflict[];
  readonly conflictsBySegmentId: ReadonlyMap<string, readonly EventSchedulerConflict[]>
}
```

---

### `normalizeCoverageRequirements`

```ts
export function normalizeCoverageRequirements(
  requirements: readonly EventSchedulerCoverageRequirementEntity[],
  resources: readonly EventSchedulerResourceEntity[],
): readonly EventSchedulerCoverageRequirementEntity[];
```

---

### `createEventSchedulerCoverageResults`

```ts
export function createEventSchedulerCoverageResults(input: EventSchedulerCoverageInput): readonly EventSchedulerCoverageResult[];
```

---

### `summarizeCoverageResults`

```ts
export function summarizeCoverageResults(results: readonly EventSchedulerCoverageResult[]): EventSchedulerCoverageSummary;
```

---

### `getTimelineCoverageState`

```ts
export function getTimelineCoverageState(
  column: EventSchedulerTimelineColumn,
  row: EventSchedulerGridRow,
  projection: EventSchedulerProjection,
): EventSchedulerTimelineCoverageState | null;
```

---

### `formatCoverageSummary`

```ts
export function formatCoverageSummary(summary: EventSchedulerCoverageSummary): string;
```

---

### `EventSchedulerCoverageInput`

```ts
interface EventSchedulerCoverageInput {
  readonly config: EventSchedulerResolvedConfig;
  readonly requirements: readonly EventSchedulerCoverageRequirementEntity[];
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly segments: readonly EventSchedulerEventSegment[]
}
```

---

### `EventSchedulerTimelineCoverageState`

```ts
interface EventSchedulerTimelineCoverageState {
  readonly status: EventSchedulerCoverageStatus;
  readonly results: readonly EventSchedulerCoverageResult[];
  readonly required: number;
  readonly assigned: number;
  readonly missing: number;
  readonly surplus: number;
  readonly label: string
}
```

---

### `createEventSchedulerUtilizationResults`

```ts
export function createEventSchedulerUtilizationResults(input: EventSchedulerUtilizationInput): readonly EventSchedulerUtilizationResult[];
```

---

### `summarizeUtilizationResults`

```ts
export function summarizeUtilizationResults(results: readonly EventSchedulerUtilizationResult[]): EventSchedulerUtilizationSummary;
```

---

### `formatUtilizationResult`

```ts
export function formatUtilizationResult(result: EventSchedulerUtilizationResult): string;
```

---

### `formatUtilizationSummary`

```ts
export function formatUtilizationSummary(summary: EventSchedulerUtilizationSummary): string;
```

---

### `EventSchedulerUtilizationInput`

```ts
interface EventSchedulerUtilizationInput {
  readonly config: EventSchedulerResolvedConfig;
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly segments: readonly EventSchedulerEventSegment[]
}
```

---

### `createRemoteState`

```ts
export function createRemoteState(patch: Partial<EventSchedulerRemoteState> = {}): EventSchedulerRemoteState;
```

---

### `EventSchedulerRemoteDataSnapshot`

```ts
interface EventSchedulerRemoteDataSnapshot {
  readonly events: readonly EventSchedulerEventEntity[];
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly assignments: readonly EventSchedulerAssignmentEntity[];
  readonly availability: readonly EventSchedulerAvailabilityEntity[];
  readonly coverageRequirements: readonly EventSchedulerCoverageRequirementEntity[]
}
```

---

### `EventSchedulerRemoteLoadContext`

```ts
interface EventSchedulerRemoteLoadContext {
  readonly config: EventSchedulerConfig;
  readonly snapshot: EventSchedulerRemoteDataSnapshot;
  readonly visibleResourceIds?: readonly EventSchedulerEntityId[]
}
```

---

### `EventSchedulerRemoteMutationContext` (Extended from `index.ts`)

```ts
interface EventSchedulerRemoteMutationContext {
  readonly action: EventSchedulerMutationAction;
  readonly eventId: EventSchedulerEntityId | null;
  readonly event: EventSchedulerEventEntity | null;
  readonly previousEvent?: EventSchedulerEventEntity;
  readonly previousEvents: readonly EventSchedulerEventEntity[];
  readonly events: readonly EventSchedulerEventEntity[];
  readonly changes?: EventSchedulerEventEditChanges;
  readonly conflicts?: EventSchedulerRemoteMutationRequest['conflicts']
}
```

---

### `EventSchedulerRemoteControllerCallbacks`

```ts
interface EventSchedulerRemoteControllerCallbacks {
  readonly applyData: (data: Partial<EventSchedulerRemoteDataSnapshot>) => void;
  readonly getMutationRejectedMessage?: () => string;
  readonly stateChanged?: (detail: EventSchedulerRemoteStateChangeDetail) => void;
  readonly loadStarted?: (detail: EventSchedulerRemoteLoadDetail) => void;
  readonly loadSucceeded?: (detail: EventSchedulerRemoteLoadDetail) => void;
  readonly loadFailed?: (detail: EventSchedulerRemoteLoadDetail) => void;
  readonly mutationChanged?: (detail: EventSchedulerRemoteMutationDetail) => void
}
```

---

### `EventSchedulerRemoteController`

```ts
class EventSchedulerRemoteController {
  getState(): EventSchedulerRemoteState;

  isEnabled(config: EventSchedulerConfig | null | undefined): boolean;

  updateConfig(config: EventSchedulerConfig | null | undefined): void;

  async loadVisibleRange(context: EventSchedulerRemoteLoadContext, options: { readonly force?: boolean } = {}): Promise<void>;

  async loadMoreResources(context: EventSchedulerRemoteLoadContext): Promise<void>;

  commitMutation(context: EventSchedulerRemoteMutationContext): void;

  resetRangeCache(): void;

  destroy(): void;
}
```

---

### `assertCanCreateEvent`

Throws when an event creation is not allowed by scheduler access rules.

**Example:**
```typescript
assertCanCreateEvent({ config, resources }, { event: draft, action: 'create' });
```

```ts
export function assertCanCreateEvent(
  context: EventSchedulerPermissionDataContext,
  options: EventSchedulerCreatePermissionOptions,
): void;
```

---

### `canCreateEvent`

Checks whether an event creation is allowed without throwing.

```ts
export function canCreateEvent(
  context: EventSchedulerPermissionDataContext,
  options: EventSchedulerCreatePermissionOptions,
): EventSchedulerPermissionCheckResult;
```

---

### `assertCanMutateEvent`

Throws when a mutation is not allowed by scheduler access rules.

```ts
export function assertCanMutateEvent(
  context: EventSchedulerPermissionDataContext,
  options: EventSchedulerMutationPermissionOptions,
): void;
```

---

### `canMutateEvent`

Checks whether move, resize, edit, delete, bulk, or recurrence mutation is allowed.

```ts
export function canMutateEvent(
  context: EventSchedulerPermissionDataContext,
  options: EventSchedulerMutationPermissionOptions,
): EventSchedulerPermissionCheckResult;
```

---

### `isEventReadonly`

Returns true when an existing event should be presented as read-only in UI.

```ts
export function isEventReadonly(
  context: EventSchedulerPermissionDataContext,
  event: EventSchedulerEventEntity,
): boolean;
```

---

### `isResourceLocked`

Returns true when a resource cannot accept create/drop/reassign actions.

```ts
export function isResourceLocked(resource: EventSchedulerResourceEntity): boolean;
```

---

### `EventSchedulerPermissionDataContext`

```ts
interface EventSchedulerPermissionDataContext {
  readonly config: EventSchedulerConfig;
  readonly resources: readonly EventSchedulerResourceEntity[]
}
```

---

### `EventSchedulerPermissionCheckResult`

Result returned by scheduler permission checks.

```ts
interface EventSchedulerPermissionCheckResult {
  readonly allowed: boolean;
  readonly message?: string
}
```

---

### `EventSchedulerCreatePermissionOptions`

Inputs for evaluating create permissions from slots, drafts, templates, or paste.

```ts
interface EventSchedulerCreatePermissionOptions {
  readonly event?: EventSchedulerEventEntity;
  readonly range?: EventSchedulerCreateRangeContext;
  readonly action?: EventSchedulerCreatePermissionContext['action'];
  readonly resourceId?: EventSchedulerEntityId;
  readonly startDateTime?: string;
  readonly endDateTime?: string
}
```

---

### `EventSchedulerMutationPermissionOptions`

Inputs for evaluating event mutation permissions.

```ts
interface EventSchedulerMutationPermissionOptions {
  readonly event: EventSchedulerEventEntity;
  readonly action: EventSchedulerMutationAction;
  readonly nextEvent?: EventSchedulerEventEntity;
  readonly changes?: Partial<EventSchedulerEventEntity>;
  readonly targetResourceId?: EventSchedulerEntityId
}
```

---

### `exportEventSchedulerEvents`

```ts
export function exportEventSchedulerEvents(
  projection: EventSchedulerProjection,
  options: EventSchedulerExportOptions = {},
): EventSchedulerExportResult;
```

---

### `exportEventSchedulerResourceWorkload`

```ts
export function exportEventSchedulerResourceWorkload(
  projection: EventSchedulerProjection,
  options: EventSchedulerExportOptions = {},
): EventSchedulerExportResult;
```

---

### `exportEventSchedulerConflicts`

```ts
export function exportEventSchedulerConflicts(
  projection: EventSchedulerProjection,
  options: EventSchedulerExportOptions = {},
): EventSchedulerExportResult;
```

---

### `exportEventSchedulerCoverage`

```ts
export function exportEventSchedulerCoverage(
  projection: EventSchedulerProjection,
  options: EventSchedulerCoverageExportOptions = {},
): EventSchedulerExportResult;
```

---

### `exportEventSchedulerVisibleSchedule`

```ts
export function exportEventSchedulerVisibleSchedule(
  projection: EventSchedulerProjection,
  options: EventSchedulerExportOptions = {},
): EventSchedulerExportResult;
```

---

### `createEventSchedulerPrintView`

```ts
export function createEventSchedulerPrintView(
  projection: EventSchedulerProjection,
  options: EventSchedulerPrintOptions = {},
): EventSchedulerPrintResult;
```

---

### `EventSchedulerExportFormat`

```ts
export type EventSchedulerExportFormat = 'csv' | 'json';
```

---

### `EventSchedulerExportScope`

```ts
export type EventSchedulerExportScope =
  | 'events'
  | 'resource-workload'
  | 'conflicts'
  | 'coverage'
  | 'visible-schedule';
```

---

### `EventSchedulerReportValue`

```ts
export type EventSchedulerReportValue = string | number | boolean | null;
```

---

### `EventSchedulerReportRow`

```ts
export type EventSchedulerReportRow = Record<string, EventSchedulerReportValue>;
```

---

### `EventSchedulerExportOptions`

Options shared by scheduler CSV/JSON export helpers.

**Example:**
```typescript
const report = plugin.exportEvents({ format: 'csv' });
download(report.content, report.fileName, report.mimeType);
```

```ts
interface EventSchedulerExportOptions {
  readonly format?: EventSchedulerExportFormat;
  readonly includeHeaders?: boolean;
  readonly delimiter?: string;
  readonly lineBreak?: string;
  readonly fileName?: string
}
```

---

### `EventSchedulerCoverageExportOptions` (Extended from `index.ts`)

Options for coverage reporting.

`gapsOnly` defaults to `true` because the public coverage export is intended
to share planning gaps first. Set it to `false` for a full requirement report.

```ts
interface EventSchedulerCoverageExportOptions {
  readonly gapsOnly?: boolean
}
```

---

### `EventSchedulerExportResult`

Result returned by scheduler export helpers.

```ts
interface EventSchedulerExportResult {
  readonly scope: EventSchedulerExportScope;
  readonly format: EventSchedulerExportFormat;
  readonly fileName: string;
  readonly mimeType: string;
  readonly rows: readonly Row[];
  readonly content: string
}
```

---

### `EventSchedulerPrintOptions`

Options for creating a print-friendly scheduler document.

**Example:**
```typescript
const print = plugin.createPrintView({ title: 'Security Scheduler JavaScript Calendar' });
printWindow.document.write(print.html);
printWindow.print();
```

```ts
interface EventSchedulerPrintOptions {
  readonly title?: string;
  readonly includeEvents?: boolean;
  readonly includeWorkload?: boolean;
  readonly includeConflicts?: boolean;
  readonly includeCoverage?: boolean;
  readonly generatedAt?: string
}
```

---

### `EventSchedulerPrintResult`

HTML document and source rows for a first-version print/share view.

```ts
interface EventSchedulerPrintResult {
  readonly title: string;
  readonly generatedAt: string;
  readonly html: string;
  readonly events: readonly EventSchedulerReportRow[];
  readonly workload: readonly EventSchedulerReportRow[];
  readonly conflicts: readonly EventSchedulerReportRow[];
  readonly coverage: readonly EventSchedulerReportRow[]
}
```

---

### `getEventSchedulerZoomLevels`

Returns the slot granularities that can represent the complete visible range.
A custom active slot size remains part of the sequence when it is valid.

```ts
export function getEventSchedulerZoomLevels(
  context: EventSchedulerZoomContext,
): readonly number[];
```

---

### `getNextEventSchedulerZoomLevel`

Returns the next finer/coarser slot size, or `null` at the zoom boundary.

```ts
export function getNextEventSchedulerZoomLevel(
  context: EventSchedulerZoomContext,
  direction: EventSchedulerZoomDirection,
): number | null;
```

---

### `resolveEventSchedulerZoomCoordinate`

Maps a timeline scroll coordinate to the same visible day/time after zoom.

```ts
export function resolveEventSchedulerZoomCoordinate(
  previous: EventSchedulerProjection,
  next: EventSchedulerProjection,
  coordinate: number,
): number;
```

---

### `DEFAULT_EVENT_SCHEDULER_ZOOM_LEVELS`

Built-in Scheduler slot granularities ordered from finest to coarsest.

```ts
DEFAULT_EVENT_SCHEDULER_ZOOM_LEVELS: readonly [15, 30, 60, 120, 240, 480, 720, 1440];
```

---

### `EventSchedulerZoomDirection`

```ts
export type EventSchedulerZoomDirection = 'in' | 'out';
```

---

### `EventSchedulerZoomContext`

```ts
interface EventSchedulerZoomContext {
  readonly slotMinutes: number;
  readonly timeRange: EventSchedulerTimeRange;
  readonly enabled?: boolean;
  readonly levels?: readonly number[]
}
```

---

### `availabilityRangeOverlapsSlot`

```ts
export function availabilityRangeOverlapsSlot(
  availability: EventSchedulerNormalizedAvailability,
  slotStart: number,
  slotEnd: number,
): boolean;
```

---

### `availabilityOverlapsDate`

```ts
export function availabilityOverlapsDate(
  availability: EventSchedulerNormalizedAvailability,
  date: string,
): boolean;
```

---

### `availabilityAppliesToResource`

```ts
export function availabilityAppliesToResource(
  availability: EventSchedulerNormalizedAvailability,
  resourceId: EventSchedulerGridRow['resourceId'] | EventSchedulerEntityId | undefined,
): boolean;
```

---

### `getTimelineAvailabilityState`

```ts
export function getTimelineAvailabilityState(
  column: EventSchedulerTimelineColumn,
  row: EventSchedulerGridRow,
  projection: EventSchedulerProjection,
): EventSchedulerAvailabilitySlotState | null;
```

---

### `getConfiguredAvailabilitySlotState`

```ts
export function getConfiguredAvailabilitySlotState(
  projection: EventSchedulerProjection,
  date: string,
  dayIndex: number,
  slotIndex: number,
  startMinutes: number,
  endMinutes: number,
  resourceId?: EventSchedulerEntityId,
): EventSchedulerAvailabilitySlotState | null;
```

---

### `getNonWorkingTimeSlotState`

```ts
export function getNonWorkingTimeSlotState(
  projection: EventSchedulerProjection,
  date: string,
  startMinutes: number,
  endMinutes: number,
  options: { readonly includeClosedDays?: boolean; readonly resourceId?: EventSchedulerEntityId } = {},
): EventSchedulerAvailabilitySlotState | null;
```

---

### `isCurrentTimelineDay`

```ts
export function isCurrentTimelineDay(
  column: EventSchedulerTimelineColumn,
  projection: EventSchedulerProjection,
): boolean;
```

---

### `EventSchedulerAvailabilitySlotKind`

```ts
export type EventSchedulerAvailabilitySlotKind = EventSchedulerAvailabilityKind | 'closed';
```

---

### `EventSchedulerAvailabilitySlotState`

```ts
interface EventSchedulerAvailabilitySlotState {
  readonly available: boolean;
  readonly kind: EventSchedulerAvailabilitySlotKind;
  readonly id?: EventSchedulerEntityId;
  readonly title?: string;
  readonly reason?: string;
  readonly className?: string
}
```

---

### `getCalendarLaneCapacity`

Resolves the visible event-lane budget for a measured week row. Space for
the overflow line is kept outside that budget, so maxStackedEvents keeps its
intuitive meaning: the maximum number of event bars a dense day can show.

```ts
export function getCalendarLaneCapacity(
  rowHeight: number,
  configuredMaximum: number,
): number;
```

---

### `EVENT_SCHEDULER_CALENDAR_BAR_TOP`

```ts
EVENT_SCHEDULER_CALENDAR_BAR_TOP: 34;
```

---

### `EVENT_SCHEDULER_CALENDAR_BAR_HEIGHT`

```ts
EVENT_SCHEDULER_CALENDAR_BAR_HEIGHT: 20;
```

---

### `EVENT_SCHEDULER_CALENDAR_BAR_GAP`

```ts
EVENT_SCHEDULER_CALENDAR_BAR_GAP: 4;
```

---

### `EVENT_SCHEDULER_CALENDAR_OVERFLOW_HEIGHT`

```ts
EVENT_SCHEDULER_CALENDAR_OVERFLOW_HEIGHT: 18;
```

---

### `EVENT_SCHEDULER_CALENDAR_MIN_MONTH_ROW_HEIGHT`

```ts
EVENT_SCHEDULER_CALENDAR_MIN_MONTH_ROW_HEIGHT: 128;
```

---

### `EVENT_SCHEDULER_CALENDAR_MAX_VISIBLE_LANES`

```ts
EVENT_SCHEDULER_CALENDAR_MAX_VISIBLE_LANES: 3;
```

---

### `resolveSchedulerTodayDate`

Resolves the scheduler's deterministic "today" marker in its configured timezone.

```ts
export function resolveSchedulerTodayDate(
  config: Pick<EventSchedulerResolvedConfig, 'currentTimeMarker' | 'timeZone'>,
): string;
```

---

### `getCalendarSlotState`

```ts
export function getCalendarSlotState(
  context: EventSchedulerCalendarResolveContext,
  date: string,
  startMinutes: number,
  endMinutes: number,
  resourceId?: EventSchedulerEntityId,
  options: { readonly includeClosedDays?: boolean } = {},
): EventSchedulerCalendarSlotState | null;
```

---

### `isCalendarDateSchedulable`

```ts
export function isCalendarDateSchedulable(
  context: EventSchedulerCalendarResolveContext,
  date: string,
  resourceId?: EventSchedulerEntityId,
): boolean | null;
```

---

### `isCalendarRangeWorking`

```ts
export function isCalendarRangeWorking(
  context: EventSchedulerCalendarResolveContext,
  date: string,
  startMinutes: number,
  endMinutes: number,
  resourceId?: EventSchedulerEntityId,
): boolean | null;
```

---

### `resolveCalendar`

```ts
export function resolveCalendar(
  context: EventSchedulerCalendarResolveContext,
  resourceId?: EventSchedulerEntityId,
): EventSchedulerResolvedCalendarEntity | null;
```

---

### `EventSchedulerCalendarResolveContext`

```ts
interface EventSchedulerCalendarResolveContext {
  readonly config: Pick<EventSchedulerResolvedConfig, 'calendars' | 'labels'>;
  readonly resources: readonly EventSchedulerResourceEntity[]
}
```

---

### `EventSchedulerCalendarSlotState`

```ts
interface EventSchedulerCalendarSlotState {
  readonly available: boolean;
  readonly kind: 'closed';
  readonly title?: string;
  readonly reason?: string;
  readonly className?: string;
  readonly calendarId?: EventSchedulerEntityId
}
```

---

### `EventSchedulerClipboardController`

Owns Scheduler clipboard state and browser/adapter integration.

Mutation and selection remain in the plugin; this class only translates
selected events to/from the stable Scheduler clipboard payload.

```ts
class EventSchedulerClipboardController {
  copy(
    events: readonly EventSchedulerEventEntity[],
    config: EventSchedulerConfig | null,
  ): EventSchedulerClipboardPayload | null;

  read(config: EventSchedulerConfig | null): EventSchedulerClipboardPayload | null;

  hasPayload(config: EventSchedulerConfig | null): boolean;
}
```

---

### `mergeSchedulerElementProps`

```ts
export function mergeSchedulerElementProps(
  builtIn: EventSchedulerElementProps,
  custom: EventSchedulerElementProps | null | undefined,
): EventSchedulerElementProps;
```

---

### `renderCustomSection`

```ts
export function renderCustomSection(
  h: EventSchedulerTemplateH,
  result: EventSchedulerTemplateResult,
  wrapperClass?: string,
): EventSchedulerTemplateResult;
```

---

### `mergeClassValues`

```ts
export function mergeClassValues(...values: readonly unknown[]): string;
```

---

### `MIN_EVENT_SCHEDULER_SLOT_MINUTES`

```ts
MIN_EVENT_SCHEDULER_SLOT_MINUTES: 15;
```

---

### `toEventSchedulerClassToken`

```ts
export function toEventSchedulerClassToken(value: string): string;
```

---

### `hasBuiltInEventSchedulerStatusColor`

```ts
export function hasBuiltInEventSchedulerStatusColor(
  status: EventSchedulerEventEntity['status'],
): boolean;
```

---

### `resolveEventSchedulerRenderColor`

```ts
export function resolveEventSchedulerRenderColor(options: {
  readonly event: EventSchedulerEventEntity;
  readonly resource?: EventSchedulerResourceEntity;
  readonly config?: EventSchedulerConfig;
}): string | undefined;
```

---

### `isEventSchedulerHistoryConfig`

```ts
export function isEventSchedulerHistoryConfig(history: HistoryConfig | undefined): boolean;
```

---

### `resolveEventSchedulerHistoryConfig`

```ts
export function resolveEventSchedulerHistoryConfig(
  history: HistoryConfig | undefined,
): HistoryConfig;
```

---

### `eventSchedulerSnapshotsEqual`

```ts
export function eventSchedulerSnapshotsEqual(
  previousEvents: readonly EventSchedulerEventEntity[],
  nextEvents: readonly EventSchedulerEventEntity[],
): boolean;
```

---

### `EVENT_SCHEDULER_HISTORY_RECORD_EVENT`

```ts
EVENT_SCHEDULER_HISTORY_RECORD_EVENT: string;
```

---

### `EventSchedulerHistoryTool`

Bridges scheduler-owned event snapshots into the shared Pro HistoryPlugin.

```ts
class EventSchedulerHistoryTool {
  collectMutation(
    previousEvents: readonly EventSchedulerEventEntity[],
    nextEvents: readonly EventSchedulerEventEntity[],
    action: EventSchedulerMutationAction,
  ): boolean;

  replaySnapshot(detail: HistoryReplayDetail): boolean;
}
```

---

### `EventSchedulerRemoteHistoryQueue`

Releases remote mutation results in initiation order while requests remain concurrent.

```ts
class EventSchedulerRemoteHistoryQueue {
  handle(detail: EventSchedulerRemoteMutationDetail): EventSchedulerRemoteMutationDetail[];

  handleOutcome(
    detail: EventSchedulerRemoteMutationDetail,
    currentEvents?: readonly EventSchedulerEventEntity[],
    options: { readonly rollbackRejected?: boolean } = {},
  ): {
    readonly committed: EventSchedulerRemoteMutationDetail[];
    readonly events?: EventSchedulerEventEntity[];
  };

  clear(): void;
}
```

---

### `normalizeKeyboardShortcuts`

```ts
export function normalizeKeyboardShortcuts(
  value: EventSchedulerConfig['keyboardShortcuts'],
): EventSchedulerResolvedConfig['keyboardShortcuts'];
```

---

### `normalizeKeyboardShortcutMap`

```ts
export function normalizeKeyboardShortcutMap(
  shortcuts: Partial<Record<string, string | readonly string[] | false>> = {},
): EventSchedulerResolvedConfig['keyboardShortcuts']['shortcuts'];
```

---

### `DEFAULT_KEYBOARD_SHORTCUTS`

```ts
DEFAULT_KEYBOARD_SHORTCUTS: {
  escape: string[];
  help: string[];
  today: string[];
  search: string[];
  previous: string[];
  next: string[];
  cyclePrevious: string[];
  cycleNext: string[];
  open: string[];
  create: string[];
  edit: string[];
  lock: string[];
  delete: string[];
  copy: string[];
  paste: string[];
  duplicate: string[];
  viewWeek: string[];
  viewMonth: string[];
  viewYear: string[];
};
```

---

### `installEventSchedulerDependencies`

Installs shared Pro services required by Event Scheduler.

Most dependencies are general grid services and follow the existing
auto-install lifetime. Filtering and row z-indexing change ordinary grid
behavior, so instances created specifically for Scheduler are tracked and
removed with it.

```ts
export function installEventSchedulerDependencies(
  grid: HTMLRevoGridElement,
  providers: PluginProviders,
): EventSchedulerInstalledDependencies;
```

---

### `EventSchedulerInstalledDependencies`

```ts
interface EventSchedulerInstalledDependencies {
  /** Activates helper plugins whose effects are Scheduler-specific. */
    activate(): void;
  /** Removes Scheduler-owned helpers while preserving host-owned instances. */
    deactivate(): void;
  /** Removes only helper plugins owned exclusively by this Scheduler instance. */
    destroy(): void
}
```

---

### `createCalendarProjection`

```ts
export function createCalendarProjection(options: {
  readonly config: EventSchedulerResolvedConfig;
  readonly events: readonly EventSchedulerEventEntity[];
  readonly segments: readonly EventSchedulerEventSegment[];
  readonly conflicts: readonly EventSchedulerConflict[];
  readonly availability: readonly EventSchedulerNormalizedAvailability[];
}): EventSchedulerCalendarProjectionResult;
```

---

### `EventSchedulerCalendarProjectionResult`

```ts
interface EventSchedulerCalendarProjectionResult {
  readonly rows: readonly EventSchedulerGridRow[];
  readonly columns: ColumnData;
  readonly calendar: EventSchedulerCalendarProjection
}
```

---

### `normalizeResources`

```ts
export function normalizeResources(
  resources: readonly EventSchedulerResourceEntity[],
  config: EventSchedulerConfig,
): readonly EventSchedulerResourceEntity[];
```

---

### `resolveTimelineResources`

```ts
export function resolveTimelineResources(
  resources: readonly EventSchedulerResourceEntity[],
  events: readonly EventSchedulerEventEntity[],
  assignmentsByEvent: ReadonlyMap<string, readonly EventSchedulerAssignmentEntity[]>,
  config: EventSchedulerResolvedConfig,
  unassignedSummary: EventSchedulerUnassignedSummary,
): readonly EventSchedulerResourceEntity[];
```

---

### `normalizeEvents`

```ts
export function normalizeEvents(
  events: readonly EventSchedulerEventEntity[],
  resources: readonly EventSchedulerResourceEntity[],
  assignmentsByEvent: ReadonlyMap<string, readonly EventSchedulerAssignmentEntity[]>,
): readonly EventSchedulerEventEntity[];
```

---

### `getEventTitle`

```ts
export function getEventTitle(event: EventSchedulerEventEntity, fallback?: string): string;
```

---

### `normalizeAssignments`

```ts
export function normalizeAssignments(
  assignments: readonly EventSchedulerAssignmentEntity[],
  events: readonly EventSchedulerEventEntity[],
  resources: readonly EventSchedulerResourceEntity[],
): readonly EventSchedulerAssignmentEntity[];
```

---

### `normalizeAvailability`

```ts
export function normalizeAvailability(
  availability: readonly EventSchedulerAvailabilityEntity[],
  resources: readonly EventSchedulerResourceEntity[],
): readonly EventSchedulerNormalizedAvailability[];
```

---

### `groupAssignmentsByEvent`

```ts
export function groupAssignmentsByEvent(
  assignments: readonly EventSchedulerAssignmentEntity[],
): ReadonlyMap<string, readonly EventSchedulerAssignmentEntity[]>;
```

---

### `getEventResourceIds`

```ts
export function getEventResourceIds(
  event: EventSchedulerEventEntity,
  assignmentsByEvent: ReadonlyMap<string, readonly EventSchedulerAssignmentEntity[]>,
): readonly EventSchedulerEntityId[];
```

---

### `createUnassignedSummary`

```ts
export function createUnassignedSummary(
  config: EventSchedulerResolvedConfig,
  events: readonly EventSchedulerEventEntity[],
  assignmentsByEvent: ReadonlyMap<string, readonly EventSchedulerAssignmentEntity[]>,
): EventSchedulerUnassignedSummary;
```

---

### `createEventSegments`

```ts
export function createEventSegments(
  config: EventSchedulerResolvedConfig,
  days: readonly EventSchedulerDay[],
  slots: readonly EventSchedulerTimeSlot[],
  events: readonly EventSchedulerEventEntity[],
  resources: readonly EventSchedulerResourceEntity[],
  assignments: readonly EventSchedulerAssignmentEntity[],
): readonly EventSchedulerEventSegment[];
```

---

### `isUnassignedResource`

```ts
export function isUnassignedResource(resource: EventSchedulerResourceEntity): boolean;
```

---

### `assignLanes`

```ts
export function assignLanes(
  segments: readonly EventSchedulerEventSegment[],
  conflictResult: EventSchedulerConflictEngineResult,
  config: EventSchedulerResolvedConfig,
): readonly EventSchedulerEventSegment[];
```

---

### `createResourceRows`

```ts
export function createResourceRows(
  config: EventSchedulerResolvedConfig,
  resources: readonly EventSchedulerResourceEntity[],
  segments: readonly EventSchedulerEventSegment[],
  coverageResults: readonly EventSchedulerCoverageResult[],
  utilizationResults: readonly EventSchedulerUtilizationResult[],
  unassignedSummary: EventSchedulerUnassignedSummary,
): readonly EventSchedulerGridRow[];
```

---

### `createTimeRows`

```ts
export function createTimeRows(
  config: EventSchedulerResolvedConfig,
  days: readonly EventSchedulerDay[],
  slots: readonly EventSchedulerTimeSlot[],
): readonly EventSchedulerGridRow[];
```

---

### `createWeekDays`

```ts
export function createWeekDays(
  config: EventSchedulerResolvedConfig,
  events: readonly EventSchedulerEventEntity[] = [],
  availability: readonly EventSchedulerNormalizedAvailability[] = [],
): readonly EventSchedulerDay[];
```

---

### `createTimeSlots`

```ts
export function createTimeSlots(config: EventSchedulerResolvedConfig): readonly EventSchedulerTimeSlot[];
```

---

### `createWeekColumns`

```ts
export function createWeekColumns(config: EventSchedulerResolvedConfig, days: readonly EventSchedulerDay[]): ColumnData;
```

---

### `createTimelineColumns`

```ts
export function createTimelineColumns(
  config: EventSchedulerResolvedConfig,
  days: readonly EventSchedulerDay[],
  slots: readonly EventSchedulerTimeSlot[],
): ColumnData;
```

---

### `isEmptyId`

```ts
export function isEmptyId(id: EventSchedulerEntityId | null | undefined): boolean;
```

---

### `uniqueIds`

```ts
export function uniqueIds(ids: readonly EventSchedulerEntityId[]): readonly EventSchedulerEntityId[];
```

---

### `matchesStringFilter`

```ts
export function matchesStringFilter(
  value: string | readonly string[] | undefined,
  filter: string | readonly string[] | undefined,
): boolean;
```

---

### `getPathValue`

```ts
export function getPathValue(source: unknown, path: string): unknown;
```

---

### `createResourceTree`

```ts
export function createResourceTree(
  resources: readonly EventSchedulerResourceEntity[],
  parentIdField: keyof EventSchedulerResourceEntity | string | undefined,
): readonly EventSchedulerResourceTreeNode[];
```

---

### `flattenResourceTree`

```ts
export function flattenResourceTree(
  node: EventSchedulerResourceTreeNode,
): readonly EventSchedulerResourceEntity[];
```

---

### `EventSchedulerResourceTreeNode`

```ts
interface EventSchedulerResourceTreeNode {
  readonly resource: EventSchedulerResourceEntity;
  readonly children: EventSchedulerResourceTreeNode[]
}
```

---

### `createCalendarDayCellTemplate`

```ts
export function createCalendarDayCellTemplate(
  options: EventSchedulerColumnTypeOptions,
): NonNullable<ColumnType<DataType>['cellTemplate']>;
```

---

### `createCalendarYearCellTemplate`

```ts
export function createCalendarYearCellTemplate(
  options: EventSchedulerColumnTypeOptions,
): NonNullable<ColumnType<DataType>['cellTemplate']>;
```

---

### `EventSchedulerCalendarOverflowController`

```ts
class EventSchedulerCalendarOverflowController {
  open(day: EventSchedulerCalendarDay, target: HTMLElement): void;

  close(): void;

  destroy(): void;
}
```

---

### `createCalendarRange`

```ts
export function createCalendarRange(
  projection: EventSchedulerProjection | null,
  anchorDate: string,
  currentDate: string,
): EventSchedulerCreateRangeContext | null;
```

---

### `shiftDateTimeByDays`

```ts
export function shiftDateTimeByDays(dateTime: string, days: number): string;
```

---

### `replaceDatePreservingTime`

```ts
export function replaceDatePreservingTime(
  dateTime: string,
  targetDate: string,
  options: { readonly exclusiveMidnightEnd?: boolean } = {},
): string;
```

---

### `EventSchedulerCalendarPointerController`

```ts
class EventSchedulerCalendarPointerController {
  handleDayPointerDown(event: PointerEvent, day: EventSchedulerCalendarDay): void;

  handleEventPointerDown(
    event: PointerEvent,
    segment: EventSchedulerEventSegment,
    action: 'move' | 'resize-start' | 'resize-end',
  ): boolean;

  stop(): void;
}
```

---

### `EventSchedulerCalendarRowEventRenderer`

```ts
class EventSchedulerCalendarRowEventRenderer {
  apply(detail: BeforeRowRenderEvent<EventSchedulerGridRow>): void;
}
```

---

### `EventSchedulerCellTemplateH`

```ts
export type EventSchedulerCellTemplateH = Parameters<NonNullable<ColumnType<DataType>['cellTemplate']>>[0];
```

---

### `EventSchedulerEventBarActions`

```ts
interface EventSchedulerEventBarActions {
  readonly isEventSelected: (eventId: EventSchedulerEventSegment['eventId']) => boolean;
  readonly onEventPointerDown: (
      event: PointerEvent,
      segment: EventSchedulerEventSegment,
      action: 'move' | 'resize-start' | 'resize-end',
    ) => void;
  readonly onEventClick: (
      event: MouseEvent,
      segment: EventSchedulerEventSegment,
    ) => void;
  readonly onEventDoubleClick: (
      event: MouseEvent,
      segment: EventSchedulerEventSegment,
    ) => void
}
```

---

### `EventSchedulerColumnTypeOptions`

```ts
interface EventSchedulerColumnTypeOptions {
  readonly getProjection: () => EventSchedulerProjection | null;
  readonly onResourceGroupToggle: (groupId: string) => void;
  readonly onSlotPointerDown: (
      event: PointerEvent,
      row: EventSchedulerGridRow,
      column: EventSchedulerDayColumn | EventSchedulerTimelineColumn,
      slotSegments: readonly EventSchedulerEventSegment[],
    ) => void;
  readonly onCalendarDayPointerDown?: (
      event: PointerEvent,
      day: EventSchedulerCalendarDay,
    ) => void;
  readonly onCalendarDayActivate?: (
      day: EventSchedulerCalendarDay,
    ) => void;
  readonly onCalendarYearDateActivate?: (date: string) => void
}
```

---

### `createEventSchedulerColumnTypes`

```ts
export function createEventSchedulerColumnTypes(options: EventSchedulerColumnTypeOptions): Record<string, ColumnType<DataType>>;
```

---

### `createEventSchedulerTimeRowHeader`

```ts
export function createEventSchedulerTimeRowHeader(projection: EventSchedulerProjection): RowHeaders;
```

---

### `createEventSchedulerTimeCellProperties`

```ts
export function createEventSchedulerTimeCellProperties(
  row: EventSchedulerGridRow,
  projection: EventSchedulerProjection | null | undefined,
): ReturnType<NonNullable<ColumnType<DataType>['cellProperties']>>;
```

---

### `createEventSchedulerTimeCellTemplate`

```ts
export function createEventSchedulerTimeCellTemplate(
  h: Parameters<NonNullable<ColumnType<DataType>['cellTemplate']>>[0],
  row: EventSchedulerGridRow,
  projection: EventSchedulerProjection | null | undefined,
);
```

---

### `createTimeCellContext`

```ts
export function createTimeCellContext(
  row: EventSchedulerGridRow,
  view: EventSchedulerTimeCellContext['view'],
): EventSchedulerTimeCellContext;
```

---

### `flattenSchedulerColumns`

```ts
export function flattenSchedulerColumns(columns: ColumnData): readonly ColumnRegular[];
```

---

### `isSchedulerColumnGrouping`

```ts
export function isSchedulerColumnGrouping(column: ColumnGrouping | ColumnRegular): column is ColumnGrouping;
```

---

### `EventSchedulerContextMenuControllerOptions`

```ts
interface EventSchedulerContextMenuControllerOptions {
  readonly grid: HTMLRevoGridElement;
  readonly domLayer: EventSchedulerDomLayer;
  readonly getProjection: () => EventSchedulerProjection | null;
  readonly getContextMenuConfig: () => EventSchedulerContextMenuConfig;
  readonly getResourceIdFromSlot: (resourceId: string | number | undefined) => EventSchedulerEntityId | undefined;
  readonly hasClipboardPayload: () => boolean;
  readonly openEventEditor: (segment: EventSchedulerEventSegment) => void;
  readonly copyEvent: (segment: EventSchedulerEventSegment) => void;
  readonly duplicateEvent: (segment: EventSchedulerEventSegment) => void;
  readonly toggleLock: (segment: EventSchedulerEventSegment) => void;
  readonly toggleConfirmation: (segment: EventSchedulerEventSegment) => void;
  readonly setEventColor?: (segment: EventSchedulerEventSegment, color: string | null) => void;
  readonly deleteEvent: (segment: EventSchedulerEventSegment) => void;
  readonly createShift: (slot: EventSchedulerSlotContext, resourceId?: EventSchedulerEntityId) => void;
  readonly paste: (slot: EventSchedulerSlotContext, options: EventSchedulerPasteOptions) => void;
  readonly isSlotAvailable?: (slot: EventSchedulerSlotContext, resourceId?: EventSchedulerEntityId) => boolean;
  readonly canZoomIn?: () => boolean;
  readonly canZoomOut?: () => boolean;
  readonly zoomIn?: () => void;
  readonly zoomOut?: () => void;
  readonly onSlotContextMenu: (slot: EventSchedulerSlotContext & { readonly resourceId?: EventSchedulerEntityId }, event: MouseEvent | null) => void
}
```

---

### `EventSchedulerContextMenuController`

```ts
class EventSchedulerContextMenuController {
  apply(): void;

  remove(): void;
}
```

---

### `createDayCellTemplate`

```ts
export function createDayCellTemplate(options: EventSchedulerColumnTypeOptions): NonNullable<ColumnType<DataType>['cellTemplate']>;
```

---

### `canCreateOverExistingSegments`

```ts
export function canCreateOverExistingSegments(config: EventSchedulerResolvedConfig): boolean;
```

---

### `EventSchedulerSlotPoint`

```ts
interface EventSchedulerSlotPoint {
  readonly dayIndex: number;
  readonly slotIndex: number;
  readonly resourceId?: string | number;
  readonly axis: 'week' | 'timeline';
  readonly offsetRatio?: number
}
```

---

### `EventSchedulerGhostRangeOptions`

```ts
interface EventSchedulerGhostRangeOptions {
  readonly slotCount: number;
  readonly mode?: 'event' | 'create';
  readonly label?: string | Node;
  readonly labelProps?: EventSchedulerElementProps;
  readonly color?: string;
  readonly conflict?: boolean;
  readonly laneIndex?: number;
  readonly laneCount?: number;
  readonly resourceId?: string | number;
  readonly axis?: 'week' | 'timeline';
  readonly startOffsetRatio?: number;
  readonly endOffsetRatio?: number;
  readonly compactLabel?: {
      readonly durationMinutes: number;
      readonly thresholdMinutes: number;
      readonly startTime: string;
    }
}
```

---

### `EventSchedulerRemoteStateViewModel`

```ts
interface EventSchedulerRemoteStateViewModel {
  readonly loading: boolean;
  readonly refreshing: boolean;
  readonly saving: boolean;
  readonly empty: boolean;
  readonly error?: string;
  readonly loadingLabel: string;
  readonly refreshingLabel: string;
  readonly savingLabel: string;
  readonly emptyLabel: string;
  readonly errorLabel: string;
  readonly template?: EventSchedulerEmptyStateTemplate;
  readonly properties?: (context: EventSchedulerEmptyStateContext) => EventSchedulerElementProps | undefined
}
```

---

### `EventSchedulerDomLayer`

Contains Scheduler DOM-only responsibilities that cannot live in RevoGrid
providers: pointer hit-testing beneath overlays, transient ghost styling,
hidden source bars, and the external remote-state host. Callers own semantic
state; this layer owns creation and deterministic cleanup of visual artifacts.

```ts
class EventSchedulerDomLayer {
  getSlotFromPoint(x: number, y: number): EventSchedulerSlotPoint | null;

  getNearestSlotFromPoint(x: number, y: number): EventSchedulerSlotPoint | null;

  getSlotFromTarget(target: EventTarget | null): EventSchedulerSlotPoint | null;

  isEventTarget(target: EventTarget | null): boolean;

  renderRemoteState(model: EventSchedulerRemoteStateViewModel): void;

  clearRemoteState(): void;

  hideEventSegment(eventId: string | number, resourceId?: string | number): void;

  clearHiddenEventSegments(): void;

  applyGhostRange(dayIndex: number, startSlot: number, endSlot: number, options: EventSchedulerGhostRangeOptions): void;

  clearGhostRange(): void;
}
```

---

### `EventSchedulerEditorResourceField`

Renders the built-in editor's bounded resource selector.

Assignment state stays as entity ids; resource indexes and DOM option values
are presentation details and never become Scheduler data.

```ts
export function EventSchedulerEditorResourceField({
  resources,
  selectedResourceIds,
  disabled,
  allowMultiResourceAssignment = true,
  labels,
  onChange,
}: EventSchedulerEditorResourceFieldProps);
```

---

### `getEditorResourceIds`

Resolves the singular/plural event assignment fields to one unique list.

```ts
export function getEditorResourceIds(
  event: EventSchedulerEventEntity | null,
  allowMultiResourceAssignment = true,
): readonly EventSchedulerEntityId[];
```

---

### `createEditorResourceChanges`

Serializes editor selection using the smallest compatible event shape.

A singular selection continues using `resourceId`; plural selection uses
`resourceIds`, and an empty selection explicitly clears both legacy fields.

```ts
export function createEditorResourceChanges(
  resourceIds: readonly EventSchedulerEntityId[],
): Pick<EventSchedulerEventEditChanges, 'resourceId' | 'resourceIds'>;
```

---

### `EventSchedulerEditorResourceFieldProps`

```ts
interface EventSchedulerEditorResourceFieldProps {
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly selectedResourceIds: readonly EventSchedulerEntityId[];
  readonly disabled: boolean;
  readonly allowMultiResourceAssignment?: boolean;
  readonly labels: EventSchedulerLabels;
  readonly onChange: (
      resourceIds: readonly EventSchedulerEntityId[],
    ) => void
}
```

---

### `renderEventSchedulerEditor`

```ts
export function renderEventSchedulerEditor(
  host: HTMLElement,
  state: EventSchedulerEditorState,
  callbacks: EventSchedulerEditorCallbacks,
): void;
```

---

### `unmountEventSchedulerEditor`

```ts
export function unmountEventSchedulerEditor(host: HTMLElement): void;
```

---

### `EventSchedulerEditorState`

```ts
interface EventSchedulerEditorState {
  readonly open: boolean;
  readonly mode: EventSchedulerEventEditorMode;
  readonly event: EventSchedulerEventEntity | null;
  readonly resources: readonly EventSchedulerResourceEntity[];
  readonly readonly: boolean;
  readonly theme?: string;
  readonly allowMultiResourceAssignment?: boolean;
  readonly validationMessage?: string;
  readonly statusOptions?: readonly (string | EventSchedulerEventEditorStatusOption)[];
  readonly labels: EventSchedulerLabels
}
```

---

### `EventSchedulerEditorCallbacks`

```ts
interface EventSchedulerEditorCallbacks {
  readonly onSubmit: (changes: EventSchedulerEventEditChanges) => void;
  readonly onDelete: () => void;
  readonly onClose: () => void
}
```

---

### `EventSchedulerEventBar`

```ts
interface EventSchedulerEventBar {
  readonly key: string;
  readonly eventId: EventSchedulerEntityId;
  readonly resourceId?: EventSchedulerEntityId;
  readonly segments: readonly EventSchedulerEventSegment[];
  readonly firstSegment: EventSchedulerEventSegment;
  readonly lastSegment: EventSchedulerEventSegment;
  readonly laneIndex: number;
  readonly laneCount: number;
  readonly conflict: boolean;
  readonly conflictSeverity?: EventSchedulerConflictSeverity;
  readonly conflictTypes: readonly EventSchedulerConflictType[];
  readonly conflictIds: readonly string[]
}
```

---

### `EventSchedulerBarIndexUpdate`

```ts
interface EventSchedulerBarIndexUpdate {
  readonly projection: EventSchedulerProjection;
  /** Physical column source owned by RevoGrid's regular-column store. */
    readonly columnSource: readonly ColumnRegular[];
  /** Visible/reordered physical indexes used by RevoGrid dimensions. */
    readonly columnItems: readonly number[]
}
```

---

### `EventSchedulerBarIndex`

Projection-backed scheduler bar lookup.

RevoGrid dimensions address the visible `items` order, not the physical
column source. Keeping that mapping here gives both renderers one consistent
geometry index and makes reorder/trim changes invalidate the lookup.

```ts
class EventSchedulerBarIndex {
  update(options: EventSchedulerBarIndexUpdate): void;

  getColumns(): readonly ColumnRegular[];

  getDayBars(columnProp: string): readonly EventSchedulerEventBar[];

  getResourceBars(row: EventSchedulerGridRow): readonly EventSchedulerEventBar[];

  getDayColumnIndex(columnProp: string): number | undefined;

  getTimelineColumnIndex(
    dayIndex: number,
    slotIndex: number,
  ): number | undefined;
}
```

---

### `createEventSchedulerBarGeometry`

Projects one logical Scheduler bar into its anchor cell or row coordinates.

Horizontal coordinates are adjusted by RevoGrid's render offset because the
row VNode moves with the virtual column pool. Vertical coordinates stay
relative to the first slot row, which remains mounted while Y virtualization
is disabled for vertical Scheduler views.

```ts
export function createEventSchedulerBarGeometry(options: {
  readonly projection: EventSchedulerProjection;
  readonly bar: EventSchedulerEventBar;
  readonly anchorRowIndex: number;
  readonly context: EventSchedulerBarLayoutContext;
}): EventSchedulerBarGeometry | null;
```

---

### `intersectsEventSchedulerVisibleColumns`

```ts
export function intersectsEventSchedulerVisibleColumns(
  geometry: Pick<
    EventSchedulerBarGeometry,
    'logicalColumnStart' | 'logicalColumnEnd'
  >,
  visibleRange: EventSchedulerVisibleColumnRange | null,
): boolean;
```

---

### `EventSchedulerBarOrientation`

```ts
export type EventSchedulerBarOrientation = 'vertical' | 'horizontal';
```

---

### `EventSchedulerBarGeometry`

```ts
interface EventSchedulerBarGeometry {
  readonly orientation: EventSchedulerBarOrientation;
  readonly left: number;
  readonly top: number;
  readonly width: number;
  readonly height: number;
  /** Event-local Y offset where the vertical current-time line crosses the bar. */
    readonly currentTimeLineOffset?: number;
  readonly logicalColumnStart: number;
  readonly logicalColumnEnd: number;
  readonly minimumVisualSize: boolean
}
```

---

### `EventSchedulerBarLayoutContext`

```ts
interface EventSchedulerBarLayoutContext {
  readonly columns: readonly ColumnRegular[];
  readonly columnDimension: DimensionSettingsState;
  readonly rowDimension: DimensionSettingsState;
  readonly columnRenderOffset: number;
  readonly getDayColumnIndex?: (columnProp: string) => number | undefined;
  readonly getTimelineColumnIndex?: (
      dayIndex: number,
      slotIndex: number,
    ) => number | undefined
}
```

---

### `EventSchedulerVisibleColumnRange`

```ts
interface EventSchedulerVisibleColumnRange {
  readonly start: number;
  readonly end: number
}
```

---

### `createEventSchedulerSegmentBar`

```ts
export function createEventSchedulerSegmentBar(options: {
  readonly segment: EventSchedulerEventSegment;
  readonly key?: string;
  readonly laneIndex?: number;
}): EventSchedulerEventBar;
```

---

### `createEventSchedulerBarRenderContexts`

Builds the public customization context for one continuous visual bar.

The primary `segment` is always a real projection segment; aggregate bar
boundaries live in `start`, `end`, and `duration`. This prevents impossible
hybrid segment ranges for multi-day bars.

```ts
export function createEventSchedulerBarRenderContexts(options: {
  readonly bar: EventSchedulerEventBar;
  readonly mode: EventSchedulerEventRenderMode;
  readonly selected: boolean;
}): EventSchedulerBarRenderContexts;
```

---

### `EventSchedulerBarRenderContexts`

```ts
interface EventSchedulerBarRenderContexts {
  readonly context: EventSchedulerRenderContext;
  readonly sectionContext: EventSchedulerEventSectionContext
}
```

---

### `renderEventSchedulerBar`

Renders one focusable DOM bar for an event assignment.

`bar.segments` retains day-level projection detail while customization hooks
execute once with aggregate start/end fields and a real primary segment.

```ts
export function renderEventSchedulerBar(
  h: EventSchedulerTemplateH,
  bar: EventSchedulerEventBar,
  geometry: EventSchedulerBarGeometry,
  projection: EventSchedulerProjection,
  actions: EventSchedulerEventBarActions,
);
```

---

### `renderEventSchedulerCalendarBar`

```ts
export function renderEventSchedulerCalendarBar(
  h: EventSchedulerTemplateH,
  calendarBar: EventSchedulerCalendarBar,
  projection: EventSchedulerProjection,
  actions: EventSchedulerEventBarActions,
  geometry: { readonly left: number; readonly top: number; readonly width: number; readonly height: number },
);
```

---

### `resolveEventSchedulerBarTooltip`

```ts
export function resolveEventSchedulerBarTooltip(options: {
  readonly projection: EventSchedulerProjection;
  readonly bar: EventSchedulerEventBar;
  readonly sectionContext: EventSchedulerEventSectionContext;
}): {
  readonly tooltip: string;
  readonly conflictContext: EventSchedulerConflictDisplayContext;
};
```

---

### `getWeekEventVisibleHeight`

```ts
export function getWeekEventVisibleHeight(options: {
  readonly row: EventSchedulerGridRow;
  readonly segment: EventSchedulerEventSegment;
  readonly projection: EventSchedulerProjection | null | undefined;
  readonly carryInBoundary: boolean;
}): number | undefined;
```

---

### `getWeekEventVisualLayout`

```ts
export function getWeekEventVisualLayout(options: {
  readonly row: EventSchedulerGridRow;
  readonly segment: EventSchedulerEventSegment;
  readonly projection: EventSchedulerProjection | null | undefined;
  readonly carryInBoundary: boolean;
}): EventSchedulerWeekEventVisualLayout | undefined;
```

---

### `getTimelineEventVisualLayout`

```ts
export function getTimelineEventVisualLayout(options: {
  readonly segment: EventSchedulerEventSegment;
  readonly projection: EventSchedulerProjection | null | undefined;
}): EventSchedulerTimelineEventVisualLayout | undefined;
```

---

### `EventSchedulerWeekEventVisualLayout`

```ts
interface EventSchedulerWeekEventVisualLayout {
  readonly height: number;
  readonly minimumSize: boolean
}
```

---

### `EventSchedulerTimelineEventVisualLayout`

```ts
interface EventSchedulerTimelineEventVisualLayout {
  readonly firstSegment: boolean;
  readonly lastSegment: boolean;
  readonly end: number;
  readonly width: number;
  readonly minimumSize: boolean
}
```

---

### `isCoarseEventSchedulerPointer`

```ts
export function isCoarseEventSchedulerPointer(event: Pick<PointerEvent, 'pointerType'>): boolean;
```

---

### `canStartEventSchedulerSlotPointerAction`

```ts
export function canStartEventSchedulerSlotPointerAction(event: EventSchedulerPointerStart): boolean;
```

---

### `canStartEventSchedulerEventPointerAction`

```ts
export function canStartEventSchedulerEventPointerAction(
  event: EventSchedulerPointerStart,
  selected: boolean,
  action: EventSchedulerEventPointerAction,
): boolean;
```

---

### `bindEventSchedulerPointerControl`

```ts
export function bindEventSchedulerPointerControl(
  options: EventSchedulerPointerControlOptions,
): EventSchedulerPointerControl | null;
```

---

### `EventSchedulerEventPointerAction`

```ts
export type EventSchedulerEventPointerAction = 'move' | 'resize-start' | 'resize-end';
```

---

### `EventSchedulerPointerControlOptions`

```ts
interface EventSchedulerPointerControlOptions {
  readonly event: PointerEvent;
  readonly onMove: (event: PointerEvent) => void;
  readonly onEnd: (event: PointerEvent) => void;
  readonly onCancel: (event: Event) => void;
  readonly listenerTarget?: EventSchedulerPointerListenerTarget;
  readonly captureTarget?: EventSchedulerPointerCaptureTarget | null
}
```

---

### `EventSchedulerPointerControl`

```ts
interface EventSchedulerPointerControl {
  readonly pointerId: number;
  destroy(): void
}
```

---

### `EventSchedulerGridSync`

Projects Scheduler rows, columns, and display policy into RevoGrid while
preserving the host grid snapshot for deactivation. Vertical views disable
Y virtualization because bars are anchored in the first slot row; resource
timelines retain the host policy because each bar is owned by its row.

```ts
class EventSchedulerGridSync {
  initialize(): void;

  applyProjection(
    projection: EventSchedulerProjection,
    options: { readonly applyColumns?: boolean } = {},
  ): void;

  restore(): void;

  isApplyingSource(): boolean;

  isApplyingColumns(): boolean;

  refreshTimelineViewport(): void;

  captureColumnResize(columns: Record<number, ColumnRegular>): void;

  getResourceColumnSize(): number | undefined;

  getDataViewportHeight(): number | undefined;
}
```

---

### `EventSchedulerKeyboardControllerOptions`

```ts
interface EventSchedulerKeyboardControllerOptions {
  readonly document: Document;
  readonly getProjection: () => EventSchedulerProjection | null;
  readonly isEditorOpen: () => boolean;
  readonly closeEditor: () => void;
  readonly stopPointerAction: () => void;
  readonly navigate: (action: 'previous' | 'next' | 'today') => void;
  readonly requestView: (view: EventSchedulerView) => void;
  readonly focusSearch: () => void;
  readonly cycleSelectedEvent: (direction: -1 | 1) => void;
  readonly openSelectedEventEditor: () => void;
  readonly createAtLastSlot: () => void;
  readonly toggleSelectedEventLock: () => void;
  readonly bulkDeleteSelectedEvents: () => void;
  readonly copySelectedEvents: () => void;
  readonly pasteCopiedEvents: () => void;
  readonly duplicateSelectedEvents: () => void;
  readonly getSelectedEventIds: () => readonly EventSchedulerEntityId[];
  readonly hasClipboardPayload: () => boolean
}
```

---

### `EventSchedulerKeyboardController`

```ts
class EventSchedulerKeyboardController {
  destroy(): void;

  handleKeyDown(event: KeyboardEvent): void;

  closeShortcutsPanel(): void;
}
```

---

### `EventSchedulerPointerControllerOptions`

```ts
interface EventSchedulerPointerControllerOptions {
  readonly domLayer: EventSchedulerDomLayer;
  readonly getConfig: () => EventSchedulerConfig | null;
  readonly getProjection: () => EventSchedulerProjection | null;
  readonly getEvents: () => readonly EventSchedulerEventEntity[];
  readonly getResources: () => readonly EventSchedulerResourceEntity[];
  readonly getAssignments: () => readonly EventSchedulerAssignmentEntity[];
  readonly getAvailability: () => readonly EventSchedulerAvailabilityEntity[];
  readonly isCreateAllowed: (context: EventSchedulerSlotContext & { readonly resourceId?: EventSchedulerEntityId }) => boolean;
  readonly isEventSelected: (eventId: EventSchedulerEntityId) => boolean;
  readonly selectEvent: (eventIds: readonly EventSchedulerEntityId[]) => void;
  readonly getResourceIdFromSlot: (resourceId?: string | number) => EventSchedulerEntityId | undefined;
  readonly createRangePreview: (range: EventSchedulerCreateRangeContext) => string | Node | undefined;
  readonly createRangePreviewProperties: (range: EventSchedulerCreateRangeContext) => EventSchedulerElementProps | undefined;
  readonly commitCreateRange: (range: EventSchedulerCreateRangeContext) => void;
  readonly commitMove: (eventId: EventSchedulerEntityId, dateTime: string, resourceId?: EventSchedulerEntityId) => void;
  readonly commitResize: (eventId: EventSchedulerEntityId, edge: EventSchedulerResizeEdge, dateTime: string) => void;
  readonly setInteractionPreview: (preview: EventSchedulerInteractionPreview | null) => void;
  readonly suppressNextSlotClick: () => void
}
```

---

### `EventSchedulerInteractionPreview`

```ts
interface EventSchedulerInteractionPreview {
  readonly action: 'create' | 'move' | 'resize';
  readonly eventId: EventSchedulerEntityId;
  readonly event: EventSchedulerEventEntity
}
```

---

### `EventSchedulerPointerController`

Owns the Scheduler pointer state machine from pointer-down through preview
and commit. It keeps transient move/resize/create state out of grid data,
delegates DOM-only feedback to `EventSchedulerDomLayer`, and guarantees that
`stop()` releases pointer bindings and clears every interaction artifact.

```ts
class EventSchedulerPointerController {
  handleSlotPointerDown(
    event: PointerEvent,
    row: EventSchedulerGridRow,
    column: EventSchedulerDayColumn | EventSchedulerTimelineColumn,
    slotSegments: readonly EventSchedulerEventSegment[],
  ): void;

  handleEventPointerDown(
    event: PointerEvent,
    segment: EventSchedulerEventSegment,
    type: EventSchedulerEventPointerAction,
  ): void;

  stop(): void;
}
```

---

### `getVerticalPointerMinuteDelta`

```ts
export function getVerticalPointerMinuteDelta(options: {
  readonly projection: EventSchedulerProjection;
  readonly slotIndex: number;
  readonly pointerDeltaY: number;
  readonly rowSize: number;
}): number;
```

---

### `getPointerMinutes`

```ts
export function getPointerMinutes(
  projection: EventSchedulerProjection,
  pointerSlot: EventSchedulerSlotPoint,
): number;
```

---

### `getTimelinePointerDelta`

Keeps compressed rendered-day movement separate from movement within a day.
Hidden dates and hours do not occupy pixels on the timeline axis.

```ts
export function getTimelinePointerDelta(
  projection: EventSchedulerProjection,
  pointerStartDayIndex: number,
  pointerStartMinutes: number,
  pointerSlot: EventSchedulerSlotPoint,
): EventSchedulerTimelinePointerDelta | null;
```

---

### `getEffectivePointerSnapMinutes`

```ts
export function getEffectivePointerSnapMinutes(
  projection: EventSchedulerProjection,
  slotIndex: number,
): number;
```

---

### `clampVisibleDayStartMinutes`

Keeps a pickup-aware move inside the visible time range of its pointed day.

The day itself is resolved separately from the pointer's column. Clamping
here prevents a grab offset near either bar edge from becoming an accidental
previous/next-day transition during calendar normalization.

```ts
export function clampVisibleDayStartMinutes(options: {
  readonly projection: EventSchedulerProjection;
  readonly startMinutes: number;
  readonly durationMinutes: number;
}): number;
```

---

### `getMoveClampDurationMinutes`

Returns the exact duration that must fit inside the pointed visible day.

Cross-date and full-day events may legitimately continue beyond that day,
so only one snap interval is required to remain visible. Same-day events use
their actual duration instead of rounded projection slots.

```ts
export function getMoveClampDurationMinutes(
  projection: EventSchedulerProjection,
  segment: EventSchedulerEventSegment,
): number;
```

---

### `getVisibleTimelineDuration`

```ts
export function getVisibleTimelineDuration(
  projection: EventSchedulerProjection,
): number;
```

---

### `EventSchedulerTimelinePointerDelta`

```ts
interface EventSchedulerTimelinePointerDelta {
  /** Difference between rendered Scheduler days, excluding hidden dates. */
    readonly renderedDayDelta: number;
  /** Pointer movement inside the visible time range of one rendered day. */
    readonly withinDayMinutes: number
}
```

---

### `normalizeSchedulerMoveTime`

Converts minutes on the compressed Scheduler axis back to a schedulable date.
Hidden weekdays, calendar closures, and non-working days are skipped without
changing the within-day time.

```ts
export function normalizeSchedulerMoveTime(
  projection: EventSchedulerProjection,
  baseDay: Pick<EventSchedulerDay, 'date' | 'dayIndex'>,
  rawStartMinutes: number,
  resourceId?: EventSchedulerEntityId,
): EventSchedulerNormalizedMoveTime | null;
```

---

### `EventSchedulerNormalizedMoveTime`

```ts
interface EventSchedulerNormalizedMoveTime {
  readonly date: string;
  readonly dayIndex: number;
  readonly slotIndex: number;
  readonly startMinutes: number
}
```

---

### `resolvePointerMoveTarget`

Resolves a drag pointer to an event start without losing the pickup offset.

Timeline days are a compressed axis: hidden dates and hidden hours do not
occupy pixels. The rendered-day delta must therefore stay separate from the
within-day delta. Inferring a day change from an underflowing minute value
makes a same-day clamp wrap to an adjacent date.

```ts
export function resolvePointerMoveTarget(options: {
  readonly projection: EventSchedulerProjection;
  readonly segment: EventSchedulerEventSegment;
  readonly pointerSlot: EventSchedulerSlotPoint;
  readonly pointerDeltaY: number;
  readonly rowSize: number;
  readonly durationSlots: number;
  readonly pointerStartDayIndex?: number;
  readonly pointerStartMinutes?: number;
  readonly resourceId?: EventSchedulerEntityId;
}): EventSchedulerPointerMoveTarget | null;
```

---

### `EventSchedulerPointerMoveTarget`

```ts
interface EventSchedulerPointerMoveTarget {
  readonly dayIndex: number;
  readonly date: string;
  readonly startSlot: number;
  readonly endSlot: number;
  readonly startDateTime: string;
  readonly eventStartDateTime: string;
  readonly visible: boolean;
  readonly resourceId?: EventSchedulerEntityId;
  readonly ghostResourceId?: EventSchedulerEntityId
}
```

---

### `getSegmentGhostColor`

```ts
export function getSegmentGhostColor(options: {
  readonly projection: EventSchedulerProjection | null;
  readonly segment: EventSchedulerEventSegment;
  readonly isDragging: boolean;
  readonly isResizing: boolean;
}): string | undefined;
```

---

### `createPreviewEventFromRange`

```ts
export function createPreviewEventFromRange(
  range: EventSchedulerCreateRangeContext,
  config: EventSchedulerConfig | null,
): EventSchedulerEventEntity | null;
```

---

### `createPreviewReassignmentPatch`

```ts
export function createPreviewReassignmentPatch(
  event: EventSchedulerEventEntity,
  nextResourceId: EventSchedulerEntityId | undefined,
): Partial<EventSchedulerEventEntity>;
```

---

### `PREVIEW_CREATE_EVENT_ID`

```ts
PREVIEW_CREATE_EVENT_ID: string;
```

---

### `getPointerCreateRange`

```ts
export function getPointerCreateRange(
  projection: EventSchedulerProjection,
  slot: {
    readonly dayIndex: number;
    readonly slotIndex: number;
    readonly axis: 'week' | 'timeline';
    readonly resourceId?: EventSchedulerEntityId;
    readonly offsetRatio?: number;
  },
): EventSchedulerCreateRangeContext | null;
```

---

### `getActiveCreateRange`

```ts
export function getActiveCreateRange(
  projection: EventSchedulerProjection,
  active: EventSchedulerCreatePointerActionState,
): EventSchedulerCreateRangeContext | null;
```

---

### `getSnappedSlotPoint`

```ts
export function getSnappedSlotPoint(
  projection: EventSchedulerProjection,
  slot: {
    readonly dayIndex: number;
    readonly slotIndex: number;
    readonly offsetRatio?: number;
  },
): EventSchedulerSnappedSlotPoint | null;
```

---

### `getSnappedResizeDateTime`

```ts
export function getSnappedResizeDateTime(
  projection: EventSchedulerProjection,
  slot: {
    readonly dayIndex: number;
    readonly slotIndex: number;
    readonly offsetRatio?: number;
  },
): string | null;
```

---

### `clampResizeDateTime`

```ts
export function clampResizeDateTime(
  projection: EventSchedulerProjection,
  event: EventSchedulerEventEntity,
  edge: EventSchedulerResizeEdge,
  dateTime: string,
  slotIndex: number,
): string;
```

---

### `getResizePreviewRange`

```ts
export function getResizePreviewRange(
  projection: EventSchedulerProjection,
  active: EventSchedulerEventPointerActionState,
  dayIndex: number,
  startDateTime: string,
  endDateTime: string,
): EventSchedulerResizePreviewRange | null;
```

---

### `getRangeSlotOffsets`

```ts
export function getRangeSlotOffsets(
  projection: EventSchedulerProjection,
  range: EventSchedulerCreateRangeContext,
): {
  readonly startOffsetRatio: number;
  readonly endOffsetRatio: number;
};
```

---

### `getPointerOffsetRatio`

```ts
export function getPointerOffsetRatio(
  event: PointerEvent,
  target: EventTarget | null,
  axis: 'week' | 'timeline',
): number;
```

---

### `EventSchedulerCreatePointerActionState`

```ts
interface EventSchedulerCreatePointerActionState {
  readonly type: 'create';
  readonly dayIndex: number;
  readonly currentDayIndex: number;
  readonly axis: 'week' | 'timeline';
  readonly resourceId?: EventSchedulerEntityId;
  readonly anchorSlot: number;
  readonly currentSlot: number;
  readonly anchorMinutes: number;
  readonly currentMinutes: number
}
```

---

### `EventSchedulerEventPointerActionState`

```ts
interface EventSchedulerEventPointerActionState {
  readonly type: 'move' | 'resize-start' | 'resize-end';
  readonly segment: EventSchedulerEventSegment
}
```

---

### `EventSchedulerSnappedSlotPoint`

```ts
interface EventSchedulerSnappedSlotPoint {
  readonly minutes: number;
  readonly startDateTime: string;
  readonly endDateTime: string
}
```

---

### `EventSchedulerResizePreviewRange`

```ts
interface EventSchedulerResizePreviewRange {
  readonly startSlot: number;
  readonly endSlot: number;
  readonly startOffsetRatio: number;
  readonly endOffsetRatio: number
}
```

---

### `createResourceCellTemplate`

```ts
export function createResourceCellTemplate(options: EventSchedulerColumnTypeOptions): NonNullable<ColumnType<DataType>['cellTemplate']>;
```

---

### `EventSchedulerRowEventBarRendererOptions`

```ts
interface EventSchedulerRowEventBarRendererOptions {
  readonly getProjection: () => EventSchedulerProjection | null;
  readonly actions: EventSchedulerEventBarActions
}
```

---

### `EventSchedulerRowEventBarRenderer`

Appends continuous timeline bars to resource row VNodes.

Row ownership keeps Y virtualization available. Column visibility is tested
against logical geometry so a bar remains mounted when its starting slot has
left the virtual column pool but another part of the bar is still visible.

```ts
class EventSchedulerRowEventBarRenderer {
  apply(detail: BeforeRowRenderEvent<EventSchedulerGridRow>): void;
}
```

---

### `EventSchedulerActivatedSlotContext` (Extended from `slot-activation-controller.ts`)

```ts
export type EventSchedulerActivatedSlotContext = EventSchedulerSlotContext & {
  readonly resourceId?: EventSchedulerEntityId;
};
```

---

### `EventSchedulerSlotActivationControllerOptions`

```ts
interface EventSchedulerSlotActivationControllerOptions {
  readonly grid: HTMLRevoGridElement;
  readonly domLayer: EventSchedulerDomLayer;
  readonly getConfig: () => EventSchedulerConfig | null;
  readonly getProjection: () => EventSchedulerProjection | null;
  readonly getResourceIdFromSlot: (
      resourceId: string | number | undefined,
    ) => EventSchedulerEntityId | undefined;
  readonly createSlotRenderContext: (
      slot: EventSchedulerSlotPoint,
      context: EventSchedulerSlotContext,
      resourceId?: EventSchedulerEntityId,
    ) => EventSchedulerSlotRenderContext | null;
  readonly clearSchedulerFocus: () => void;
  readonly setLastSlotContext: (
      context: EventSchedulerActivatedSlotContext,
    ) => void;
  readonly selectSlot: (
      context: EventSchedulerActivatedSlotContext,
    ) => boolean;
  readonly isCreateAllowed: (
      context: EventSchedulerActivatedSlotContext,
    ) => boolean;
  readonly openCreateEditor: (range: EventSchedulerCreateRangeContext) => void
}
```

---

### `EventSchedulerSlotActivationController`

Owns delegated grid activation for Scheduler slots while canonical selection
and editor state remain behind semantic plugin callbacks.

```ts
class EventSchedulerSlotActivationController {
  destroy(): void;

  suppressNextClick(): void;
}
```

---

### `createTimelineCellTemplate`

```ts
export function createTimelineCellTemplate(options: EventSchedulerColumnTypeOptions): NonNullable<ColumnType<DataType>['cellTemplate']>;
```

---

### `createTimelineCellTemplateState`

```ts
export function createTimelineCellTemplateState(options: {
  readonly column: EventSchedulerTimelineColumn;
  readonly row: EventSchedulerGridRow;
  readonly projection: EventSchedulerProjection | null;
  readonly currentTime: EventSchedulerCurrentTimeCellState | null;
}): EventSchedulerTimelineCellTemplateState;
```

---

### `getCurrentTimeMarker`

```ts
export function getCurrentTimeMarker(
  column: EventSchedulerTimelineColumn,
  projection: EventSchedulerProjection,
): EventSchedulerCurrentTimeCellState | null;
```

---

### `EventSchedulerCurrentTimeCellState`

```ts
interface EventSchedulerCurrentTimeCellState {
  readonly left: number;
  readonly label: string;
  readonly dateTime: string
}
```

---

### `EventSchedulerTimelineCellTemplateState`

```ts
interface EventSchedulerTimelineCellTemplateState {
  readonly slotSegments: readonly EventSchedulerEventSegment[];
  readonly props: Record<string, unknown>
}
```

---

### `EventSchedulerTimelineWheelControllerOptions`

```ts
interface EventSchedulerTimelineWheelControllerOptions {
  readonly grid: HTMLRevoGridElement;
  readonly providers: Pick<PluginProviders, 'dimension' | 'viewport'>;
  readonly getProjection: () => EventSchedulerProjection | null
}
```

---

### `EventSchedulerTimelineWheelController`

Delegates otherwise-unused vertical wheel input to an overflowing horizontal
resource timeline while preserving native row and trackpad scrolling.

```ts
class EventSchedulerTimelineWheelController {
  destroy(): void;
}
```

---

### `EventSchedulerVerticalEventBarRendererOptions`

```ts
interface EventSchedulerVerticalEventBarRendererOptions {
  readonly getProjection: () => EventSchedulerProjection | null;
  readonly actions: EventSchedulerEventBarActions
}
```

---

### `EventSchedulerVerticalEventBarRenderer`

Anchors vertical event bars in the first rendered slot cell of each day.
Vertical Scheduler views disable Y virtualization, so this cell remains
mounted while each bar spans the required time rows.

```ts
class EventSchedulerVerticalEventBarRenderer {
  apply(
    detail: BeforeCellRenderEvent<
      CellTemplateProp<EventSchedulerGridRow, EventSchedulerDayColumn>
    >,
  ): void;
}
```

---

### `resolveEventSchedulerViewAdapter`

```ts
export function resolveEventSchedulerViewAdapter(
  view: EventSchedulerView,
): EventSchedulerViewAdapter;
```

---

### `EventSchedulerViewRuntimeHooks`

```ts
interface EventSchedulerViewRuntimeHooks {
  readonly renderVerticalCell: (detail: unknown) => void;
  readonly renderResourceTimelineRow: (detail: unknown) => void;
  readonly renderCalendarRow: (detail: unknown) => void;
  readonly handleDefaultEventPointerDown: (
      event: PointerEvent,
      segment: EventSchedulerEventSegment,
      action: 'move' | 'resize-start' | 'resize-end',
    ) => void;
  readonly handleCalendarEventPointerDown: (
      event: PointerEvent,
      segment: EventSchedulerEventSegment,
      action: 'move' | 'resize-start' | 'resize-end',
    ) => void;
  readonly stopDefaultInteraction: () => void;
  readonly stopCalendarInteraction: () => void;
  readonly closeCalendarOverflow: () => void
}
```

---

### `EventSchedulerViewGridPolicy`

```ts
interface EventSchedulerViewGridPolicy {
  readonly disableVirtualY: boolean;
  readonly rowHeaders: HTMLRevoGridElement['rowHeaders'];
  readonly rowDefinitions: readonly RowDefinition[];
  readonly preserveRowsOnRefresh: boolean
}
```

---

### `EventSchedulerViewAdapter`

```ts
interface EventSchedulerViewAdapter {
  readonly id: 'timeGrid' | 'resourceTimeline' | 'calendar';
  readonly supportsZoom: boolean;
  readonly observesViewportResize: boolean;
  supports(view: EventSchedulerView): boolean;
  beforeRowRender(detail: unknown, hooks: EventSchedulerViewRuntimeHooks): void;
  beforeCellRender(detail: unknown, hooks: EventSchedulerViewRuntimeHooks): void;
  handleEventPointerDown(
      event: PointerEvent,
      segment: EventSchedulerEventSegment,
      action: 'move' | 'resize-start' | 'resize-end',
      hooks: EventSchedulerViewRuntimeHooks,
    ): void;
  deactivate(hooks: EventSchedulerViewRuntimeHooks): void;
  getRootClass(projection: EventSchedulerProjection): string;
  getColumnCount(projection: EventSchedulerProjection): number;
  getGridPolicy(
      projection: EventSchedulerProjection,
      context: {
        readonly hostDisableVirtualY: boolean;
        readonly viewportHeight?: number;
      },
    ): EventSchedulerViewGridPolicy
}
```

---

### `timeGridViewAdapter`

```ts
timeGridViewAdapter: {
  id: string;
  supportsZoom: true;
  observesViewportResize: false;
  supports: (view: EventSchedulerView) => view is "day" | "week";
  beforeRowRender: () => undefined;
  beforeCellRender: (detail: unknown, hooks: EventSchedulerViewRuntimeHooks) => void;
  handleEventPointerDown: (event: PointerEvent, segment: EventSchedulerEventSegment, action: "move" | "resize-start" | "resize-end", hooks: EventSchedulerViewRuntimeHooks) => void;
  deactivate: (hooks: EventSchedulerViewRuntimeHooks) => void;
  getRootClass: () => string;
  getColumnCount: (projection: EventSchedulerProjection) => number;
  getGridPolicy: (projection: EventSchedulerProjection) => { disableVirtualY: true; rowHeaders: true; rowDefinitions: { type: "rgRow"; index: number; size: number; }[]; preserveRowsOnRefresh: false; };
};
```

---

### `resourceTimelineViewAdapter`

```ts
resourceTimelineViewAdapter: {
  id: string;
  supportsZoom: true;
  observesViewportResize: false;
  supports: (view: EventSchedulerView) => view is "resourceTimeline";
  beforeRowRender: (detail: unknown, hooks: EventSchedulerViewRuntimeHooks) => void;
  beforeCellRender: () => undefined;
  handleEventPointerDown: (event: PointerEvent, segment: EventSchedulerEventSegment, action: "move" | "resize-start" | "resize-end", hooks: EventSchedulerViewRuntimeHooks) => void;
  deactivate: (hooks: EventSchedulerViewRuntimeHooks) => void;
  getRootClass: () => string;
  getColumnCount: (projection: EventSchedulerProjection) => number;
  getGridPolicy: (projection: EventSchedulerProjection, context: { readonly hostDisableVirtualY: boolean; readonly viewportHeight?: number | undefined; }) => { disableVirtualY: boolean; rowHeaders: false; rowDefinitions: { type: "rgRow"; index: number; size: number; }[]; preserveRowsOnRefresh: true; };
};
```

---

### `calendarViewAdapter`

```ts
calendarViewAdapter: {
  id: string;
  supportsZoom: false;
  observesViewportResize: true;
  supports: (view: EventSchedulerView) => view is "month" | "year";
  beforeRowRender: (detail: unknown, hooks: EventSchedulerViewRuntimeHooks) => void;
  beforeCellRender: () => undefined;
  handleEventPointerDown: (event: PointerEvent, segment: EventSchedulerEventSegment, action: "move" | "resize-start" | "resize-end", hooks: EventSchedulerViewRuntimeHooks) => void;
  deactivate: (hooks: EventSchedulerViewRuntimeHooks) => void;
  getRootClass: (projection: EventSchedulerProjection) => "event-scheduler-plugin--calendar-year" | "event-scheduler-plugin--calendar-month";
  getColumnCount: (projection: EventSchedulerProjection) => 1 | 7;
  getGridPolicy: (projection: EventSchedulerProjection, _context: { readonly hostDisableVirtualY: boolean; readonly viewportHeight?: number | undefined; }) => { disableVirtualY: true; rowHeaders: false; rowDefinitions: { type: "rgRow"; index: number; size: number; }[]; preserveRowsOnRefresh: false; };
};
```

---

# Export

URL: https://pro.rv-grid.com/api/export/
Source: src/content/docs/api/export.md

### `CSVFormatter`

```ts
export type CSVFormatter = (options: Partial<CSVFormat>, data: DataInput) => string;
```

---

### `ExportCsv`

```ts
class ExportCsv {
  doExport({ data, headers, props }: DataInput): string;;
}
```

---

### `ExportFormat`

```ts
export type ExportFormat = Partial<CSVFormat>;
```

---

### `ExportFilePlugin`

```ts
class ExportFilePlugin {
  /** Exports string */
  exportString(options?: ExportFormat, t?: ExportTypes): Promise<string | null>;;

  /** Exports Blob */
  exportBlob(options?: ExportFormat, t?: ExportTypes): Promise<Blob | null>;;

  /** Export file */
  exportFile(options?: ExportFormat, t?: ExportTypes): Promise<void>;;

  /** Blob object */
  getBlob(formatter: Formatter): Promise<Blob | null>;;
}
```

---

### `ColSource`

```ts
export type ColSource = {
    headers: string[][];
    props: any[];
};
```

---

### `DataInput` (Extended from `export.plugin.d.ts`)

```ts
export type DataInput = {
    data: DataType[];
} & ColSource;
```

---

### `FormatterOptions`

```ts
interface FormatterOptions {
  mime: string;
  encoding: string
}
```

---

### `Formatter`

```ts
interface Formatter {
  options: FormatterOptions;
  doExport(data: DataInput): string
}
```

---

### `CSVFormat` (Extended from `export.plugin.d.ts`)

```ts
interface CSVFormat {
  fileKind: 'csv';
  bom: boolean;
  columnDelimiter: string;
  rowDelimiter: string;
  filename?: string
}
```

---

# Export Excel

URL: https://pro.rv-grid.com/api/export-excel/
Source: src/content/docs/api/export-excel.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Excel export-only properties and formatting. This does not affect the
       * rendered grid cell renderer.
       */
      excelExport?: ExcelExportColumnOptions
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  exportExcel?: ExcelConfig;
  'export-excel'?: ExcelConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /**
       * Event for export excel
       *
       * @example
       * ```typescript
       * grid.addEventListener(EXCEL_EXPORT_EVENT, (event) => {
       *   console.log(event);
       * });
       */
      [EXCEL_EXPORT_EVENT]: ExportExcelEvent | undefined;
  [EXCEL_BEFORE_IMPORT_EVENT]: ExcelCsvBeforeImportEvent;
  [EXCEL_BEFORE_SET_EVENT]: ExcelCsvBeforeSetEvent
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data property for export excel
       *
       * @deprecated Use `grid.exportExcel` instead.
       *
       * @example
       * ```typescript
       * const grid = document.createElement('revo-grid');
       * grid.additionalData = { excel: { allowDrag: false } };
       * ```
       */
      excel?: ExcelConfig
}
```

## Plugin API

### `createExcelJsExcelExportProvider`

```ts
export function createExcelJsExcelExportProvider(excelJsModule: ExcelJsExcelExportModule): ExcelExportProvider;
```

---

### `createSheetJsExcelExportProvider`

```ts
export function createSheetJsExcelExportProvider(xlsxModule: SheetJsExcelExportModule): ExcelExportProvider;
```

---

### `createWorkbookModuleExcelExportProvider`

```ts
export function createWorkbookModuleExcelExportProvider(workbookModule: WorkbookExportModule): ExcelExportProvider;
```

---

### `ExportExcelPlugin`

The `ExportExcelPlugin` is a plugin for RevoGrid that enables XLSX export and CSV

```ts
class ExportExcelPlugin {
  /**
     * Imports a CSV file into the grid.
     */
  async importFile(
    file: File,
    config: ExcelConfig = this.config,
  );

  isCsv(file: File, allowedExtensions: string[] = ['.csv']);

  /**
     * @deprecated Import is CSV-only. Use `isCsv()` instead.
     */
  isExcel(file: File, allowedExtensions: string[] = ['.csv']);

  /** Register a transformer owned by another plugin. */
  registerExportTransformer(transformer: ExcelExportContextTransformer): () => void;

  async export(config?: ExportExcelEvent): Promise<void>;

  destroy();
}
```

---

### `ExcelCsvBeforeImportEvent`

Detail payload emitted before a CSV import is applied to the grid.

```ts
/**
 * Detail payload emitted before a CSV import is applied to the grid.
 */
export type ExcelCsvBeforeImportEvent = {
  file: File;
  sheetName: string;
  csv: string;
  rows: string[][];
};
```

---

### `ExcelCsvBeforeSetEvent` (Extended from `index.ts`)

Detail payload emitted after CSV rows are mapped to grid row objects and
before the grid source is replaced.

```ts
/**
 * Detail payload emitted after CSV rows are mapped to grid row objects and
 * before the grid source is replaced.
 */
export type ExcelCsvBeforeSetEvent = ExcelCsvBeforeImportEvent & {
  jsonData: DataType[];
};
```

---

### `ExportExcelEvent`

Example usage of the ExportExcelEvent type

**Example:**
```typescript
const exportConfig: ExportExcelEvent = {
  sheetName: 'Property Data', // Specify the name of the Excel sheet
  workbookName: 'Properties.xlsx', // Name of the workbook file
  writingOptions: {
    type: 'file', // Output type
    bookType: 'xlsx', // Workbook type
    compression: true, // Enable compression
    ignoreEC: true, // Ignore Excel compatibility
  },
};
```

```ts
/**
 * Example usage of the ExportExcelEvent type
 *
 * @example
 * const exportConfig: ExportExcelEvent = {
 *   sheetName: 'Property Data', // Specify the name of the Excel sheet
 *   workbookName: 'Properties.xlsx', // Name of the workbook file
 *   writingOptions: {
 *     type: 'file', // Output type
 *     bookType: 'xlsx', // Workbook type
 *     compression: true, // Enable compression
 *     ignoreEC: true, // Ignore Excel compatibility
 *   },
 * };
 */
export type ExportExcelEvent = {
  /** The name of the sheet within the workbook. */
  sheetName?: string;
  /** The name of the Excel workbook. Extensionless names receive `.xlsx`. */
  workbookName?: string;
  /** Export provider object or built-in provider id. */
  provider?: ExcelExportProviderRef;
  /**
   * Optional one-off export transforms for the final provider context.
   *
   * These run after built-in feature transforms and after grid-level
   * `grid.exportExcel.exportTransformers`. Use them for app-owned matrix
   * formatting, provider options, or metadata that applies only to this export
   * call and cannot live on a column definition.
   */
  exportTransformers?: ExcelExportContextTransformer[];
  /**
   * Infer provider options such as column widths and sticky row/column counts
   * from current grid state. Defaults to `true`.
   */
  deriveGridOptions?: boolean;
  /** Provider-specific options forwarded to the selected workbook provider. */
  providerOptions?: Record<string, unknown>;
  /** Options for how the selected provider writes the workbook file. */
  writingOptions?: ExcelExportWritingOptions;
};
```

---

### `ExcelExportCellValue`

Primitive value shape accepted by the Excel export cell formatting pipeline.

```ts
/**
 * Primitive value shape accepted by the Excel export cell formatting pipeline.
 */
export type ExcelExportCellValue = string | number | boolean | Date | null | undefined;
```

---

### `ExcelExportCellStyle`

Workbook-oriented cell style options shared by the bundled writer and optional
provider adapters.

Providers map this structural shape to their own workbook library. Unsupported
fields can be ignored by custom providers without changing the export context.

```ts
/**
 * Workbook-oriented cell style options shared by the bundled writer and optional
 * provider adapters.
 *
 * Providers map this structural shape to their own workbook library. Unsupported
 * fields can be ignored by custom providers without changing the export context.
 */
export type ExcelExportCellStyle = {
  fontFamily?: string;
  fontSize?: number;
  fontWeight?: 'bold';
  fontStyle?: 'italic';
  textDecoration?: {
    strikethrough?: boolean;
    underline?: true;
    doubleUnderline?: true;
  };
  textColor?: string;
  backgroundColor?: string;
  fillPatternStyle?: string;
  fillPatternColor?: string;
  borderColor?: string;
  borderStyle?: string;
  leftBorderColor?: string;
  leftBorderStyle?: string;
  rightBorderColor?: string;
  rightBorderStyle?: string;
  topBorderColor?: string;
  topBorderStyle?: string;
  bottomBorderColor?: string;
  bottomBorderStyle?: string;
  align?: 'left' | 'center' | 'right';
  alignVertical?: 'top' | 'center' | 'bottom';
  height?: number;
  columnSpan?: number;
  rowSpan?: number;
  indent?: number;
  wrap?: boolean;
  textRotation?: number;
  format?: string;
};
```

---

### `ExcelExportCell` (Extended from `index.ts`)

Provider-ready cell object used in `ExcelExportProviderContext.cellRows`.

Additional provider-specific fields are allowed so apps can add metadata for
custom providers through column callbacks or export transformers.

```ts
/**
 * Provider-ready cell object used in `ExcelExportProviderContext.cellRows`.
 *
 * Additional provider-specific fields are allowed so apps can add metadata for
 * custom providers through column callbacks or export transformers.
 */
export type ExcelExportCell = ExcelExportCellStyle & {
  value: ExcelExportCellValue;
  [option: string]: unknown;
};
```

---

### `ExcelExportCellData`

One matrix entry passed to workbook providers.

`null` and `undefined` are reserved for intentional blank cells or span
placeholders created by feature-owned export transforms.

```ts
/**
 * One matrix entry passed to workbook providers.
 *
 * `null` and `undefined` are reserved for intentional blank cells or span
 * placeholders created by feature-owned export transforms.
 */
export type ExcelExportCellData = ExcelExportCell | null | undefined;
```

---

### `ExcelExportCellPropertiesResult`

Return value accepted from column-level Excel export callbacks.

Return a primitive to replace the cell value, a partial cell object to apply
value/style options, or `undefined` to keep the prepared cell unchanged.

```ts
/**
 * Return value accepted from column-level Excel export callbacks.
 *
 * Return a primitive to replace the cell value, a partial cell object to apply
 * value/style options, or `undefined` to keep the prepared cell unchanged.
 */
export type ExcelExportCellPropertiesResult =
  | ExcelExportCellValue
  | (Partial<ExcelExportCell> & Record<string, unknown>)
  | void;
```

---

### `ExcelExportCellPropertiesContext`

Context passed to `column.excelExport.cellProperties` for body and pinned
rows during export preparation.

```ts
/**
 * Context passed to `column.excelExport.cellProperties` for body and pinned
 * rows during export preparation.
 */
export type ExcelExportCellPropertiesContext = {
  value: ExcelExportCellValue;
  rawValue: unknown;
  model: DataType;
  rowIndex: number;
  rowType: DimensionRows;
  column: ColumnRegular;
  columnIndex: number;
  revogrid: HTMLRevoGridElement;
  providers: PluginProviders;
};
```

---

### `ExcelExportColumnPropertiesContext`

Context passed to `column.excelExport.columnProperties` for the generated
column/header row.

```ts
/**
 * Context passed to `column.excelExport.columnProperties` for the generated
 * column/header row.
 */
export type ExcelExportColumnPropertiesContext = {
  value: string;
  column: ColumnRegular;
  columnIndex: number;
  revogrid: HTMLRevoGridElement;
  providers: PluginProviders;
};
```

---

### `ExcelExportCellProperties`

Column-level callback for formatting exported body or pinned-row cells.

```ts
/**
 * Column-level callback for formatting exported body or pinned-row cells.
 */
export type ExcelExportCellProperties = (
  context: ExcelExportCellPropertiesContext,
) => ExcelExportCellPropertiesResult;
```

---

### `ExcelExportColumnProperties`

Column-level callback for formatting the generated exported column/header
cell.

```ts
/**
 * Column-level callback for formatting the generated exported column/header
 * cell.
 */
export type ExcelExportColumnProperties = (
  context: ExcelExportColumnPropertiesContext,
) => ExcelExportCellPropertiesResult;
```

---

### `ExcelExportColumnOptions`

Excel export-only column options.

These options affect exported workbook cells only; rendered grid cells should
use the normal RevoGrid `cellTemplate` and `cellProperties` APIs.

```ts
/**
 * Excel export-only column options.
 *
 * These options affect exported workbook cells only; rendered grid cells should
 * use the normal RevoGrid `cellTemplate` and `cellProperties` APIs.
 */
export type ExcelExportColumnOptions = {
  /**
   * Format or replace an exported body/pinned cell. Returning a cell object
   * without `value` keeps the prepared value and applies the returned options.
   */
  cellProperties?: ExcelExportCellProperties;
  /**
   * Format or replace the generated column/header cell for this column.
   */
  columnProperties?: ExcelExportColumnProperties;
};
```

---

### `WRITE_EXCEL_FILE_PROVIDER_ID`

Built-in provider id for the bundled `write-excel-file` adapter.

```ts
WRITE_EXCEL_FILE_PROVIDER_ID: string;
```

---

### `BuiltInExcelExportProviderId`

```ts
export type BuiltInExcelExportProviderId = typeof WRITE_EXCEL_FILE_PROVIDER_ID;
```

---

### `ExcelExportSourceRow`

Original source-row metadata paired with each exported data row.

Providers and transformers can use this to distinguish body, pinned-top, and
pinned-bottom rows without reading rendered DOM state.

```ts
/**
 * Original source-row metadata paired with each exported data row.
 *
 * Providers and transformers can use this to distinguish body, pinned-top, and
 * pinned-bottom rows without reading rendered DOM state.
 */
export type ExcelExportSourceRow = {
  model: DataType;
  rowIndex: number;
  rowType: DimensionRows;
  /**
   * Zero-based authored A1 row coordinate retained across row pinning, sorting,
   * filtering, grouping, and row-order projections.
   *
   * Export transformers should prefer this identity over the compact position
   * in `sourceRows` when translating A1 references to worksheet rows.
   */
  physicalRowIndex?: number;
};
```

---

### `ExcelExportContextTransformResult`

Partial update returned by an `ExcelExportContextTransformer`.

Omitted fields leave the current export context unchanged. Returned
`cellRows` replace the matrix, while option and metadata objects are merged
with the existing context.

```ts
/**
 * Partial update returned by an `ExcelExportContextTransformer`.
 *
 * Omitted fields leave the current export context unchanged. Returned
 * `cellRows` replace the matrix, while option and metadata objects are merged
 * with the existing context.
 *
 * @public
 */
export type ExcelExportContextTransformResult = {
  /**
   * Replace the provider-ready matrix after export preparation.
   *
   * The matrix includes all generated header rows before source data rows.
   */
  cellRows?: ExcelExportCellData[][];
  /**
   * Merge additional provider options into the export context.
   *
   * Use this for options consumed by the selected workbook provider.
   */
  providerOptions?: Record<string, unknown>;
  /**
   * Merge derived grid options such as freeze panes or column widths.
   *
   * Provider implementations can combine these with explicit provider options.
   */
  gridDerivedOptions?: Record<string, unknown>;
  /**
   * Merge provider-agnostic metadata for custom workbook providers.
   *
   * Built-in transforms use this to expose details such as grouped headers and
   * cell merge ranges to providers that can map them natively.
   */
  exportMetadata?: Record<string, unknown>;
  /** Append feature-owned worksheets without changing the primary sheet fields. */
  additionalWorksheets?: ExcelExportWorksheetDescriptor[];
};
```

---

### `ExcelExportWorksheetDescriptor`

```ts
export type ExcelExportWorksheetDescriptor = {
  sheetName: string;
  /** Plain rows for object-oriented workbook adapters. */
  rows: DataType[];
  /** Provider-ready matrix for cell-oriented workbook adapters. */
  cellRows: ExcelExportCellData[][];
};
```

---

### `ExcelExportContextTransformer`

Synchronous hook for the final Excel export context before provider output.

Transformers run after RevoGrid data collection, column/header formatting,
and built-in Pro transforms. Grid-level transformers configured on
`grid.exportExcel.exportTransformers` run first; one-off transformers passed
to `plugin.export({ exportTransformers })` run after them.

A transformer can mutate `context` directly, return a partial
`ExcelExportContextTransformResult`, or do both. Use `context.cellRows` for
provider-ready formatted output and `context.rows` only when plain row data is
sufficient.

```ts
/**
 * Synchronous hook for the final Excel export context before provider output.
 *
 * Transformers run after RevoGrid data collection, column/header formatting,
 * and built-in Pro transforms. Grid-level transformers configured on
 * `grid.exportExcel.exportTransformers` run first; one-off transformers passed
 * to `plugin.export({ exportTransformers })` run after them.
 *
 * A transformer can mutate `context` directly, return a partial
 * `ExcelExportContextTransformResult`, or do both. Use `context.cellRows` for
 * provider-ready formatted output and `context.rows` only when plain row data is
 * sufficient.
 *
 * @public
 */
export type ExcelExportContextTransformer = (
  context: ExcelExportProviderContext,
) => void | ExcelExportContextTransformResult | Promise<void | ExcelExportContextTransformResult>;
```

---

### `ExcelExportProviderContext`

Full provider handoff context created by `ExportExcelPlugin`.

Custom providers should consume this data-source-based context instead of
reading rendered grid rows. Virtualized offscreen rows are included in
`rows`, `sourceRows`, and `cellRows`.

```ts
/**
 * Full provider handoff context created by `ExportExcelPlugin`.
 *
 * Custom providers should consume this data-source-based context instead of
 * reading rendered grid rows. Virtualized offscreen rows are included in
 * `rows`, `sourceRows`, and `cellRows`.
 */
export type ExcelExportProviderContext = {
  /** Grid element that initiated the export. */
  revogrid: HTMLRevoGridElement;
  /** Runtime providers for advanced integrations that need grid stores or column metadata. */
  providers: PluginProviders;
  /** Original export call configuration, if provided. */
  config?: ExportExcelEvent;
  /** Excel-safe worksheet name after defaulting and normalization. */
  sheetName: string;
  /** Workbook filename after defaulting and extension normalization. */
  workbookName: string;
  /** Requested workbook type. The bundled provider accepts only `xlsx`. */
  bookType: BookType;
  /** Export columns in provider order, including pinned/start/body/end column segments. */
  columns: ColumnRegular[];
  /** Human-readable first row generated from column names. */
  headerRow: string[];
  /**
   * Export data rows keyed by column prop.
   *
   * Rows are collected from the grid data stores in pinned-top, body,
   * pinned-bottom order. This is data-source based and includes virtualized
   * rows that may not be rendered in the DOM.
   *
   * Workbook providers that need formatting, spans, or grouped headers should
   * prefer `cellRows`, which contains the provider-ready matrix.
   */
  rows: DataType[];
  /** Source row metadata in the same order as `rows`. */
  sourceRows: ExcelExportSourceRow[];
  /** Number of generated header rows before data rows in `cellRows`. */
  headerRowsCount: number;
  /** Provider-ready cell matrix with generated headers before data rows. */
  cellRows: ExcelExportCellData[][];
  /** Provider-specific options passed through from `ExportExcelEvent.providerOptions`. */
  providerOptions?: Record<string, unknown>;
  /**
   * Provider options inferred from current grid state, such as column widths
   * and pinned row/column freeze counts. Explicit `providerOptions` may
   * override these in providers that support merging.
   */
  gridDerivedOptions?: Record<string, unknown>;
  /**
   * Feature-owned metadata for custom providers. Built-in providers consume the
   * prepared `cellRows`; optional providers may read metadata such as merge
   * ranges or grouped header details when they can map them natively.
   */
  exportMetadata?: Record<string, unknown>;
  /** Additional worksheets registered by independent export features. */
  additionalWorksheets?: ExcelExportWorksheetDescriptor[];
  /** Workbook-library writing options passed through for optional adapters. */
  writingOptions?: ExcelExportWritingOptions;
};
```

---

### `ExcelExportProvider`

Workbook provider contract used by `ExportExcelPlugin`.

Implement this interface directly for app-owned workbook libraries or use one
of the optional provider factories for common adapters.

```ts
/**
 * Workbook provider contract used by `ExportExcelPlugin`.
 *
 * Implement this interface directly for app-owned workbook libraries or use one
 * of the optional provider factories for common adapters.
 */
export type ExcelExportProvider = {
  id?: string;
  /**
   * Writes or downloads an exported workbook.
   *
   * Providers receive prepared rows, columns, names, and options. They should
   * not read rendered DOM rows because virtualization may omit offscreen data.
   */
  export(context: ExcelExportProviderContext): void | Promise<void>;
};
```

---

### `ExcelExportProviderRef`

Provider selection value accepted by `ExportExcelEvent.provider` and
`grid.exportExcel.exportProvider`.

```ts
/**
 * Provider selection value accepted by `ExportExcelEvent.provider` and
 * `grid.exportExcel.exportProvider`.
 */
export type ExcelExportProviderRef = BuiltInExcelExportProviderId | ExcelExportProvider;
```

---

### `BookType`

```ts
export type BookType = 'xlsx' | 'xlsm' | 'xlsb' | 'xls' | 'xla' | 'biff8' | 'biff5' | 'biff2' | 'xlml' | 'ods' | 'fods' | 'csv' | 'txt' | 'sylk' | 'slk' | 'html' | 'dif' | 'rtf' | 'prn' | 'eth' | 'dbf';
```

---

### `Properties`

Basic File Properties

```ts
interface Properties {
  /** Summary tab "Title" */
    Title?: string;
  /** Summary tab "Subject" */
    Subject?: string;
  /** Summary tab "Author" */
    Author?: string;
  /** Summary tab "Manager" */
    Manager?: string;
  /** Summary tab "Company" */
    Company?: string;
  /** Summary tab "Category" */
    Category?: string;
  /** Summary tab "Keywords" */
    Keywords?: string;
  /** Summary tab "Comments" */
    Comments?: string;
  /** Statistics tab "Last saved by" */
    LastAuthor?: string;
  /** Statistics tab "Created" */
    CreatedDate?: Date
}
```

---

### `ExcelExportWritingOptions`

```ts
export type ExcelExportWritingOptions = {
  /** Output data encoding */
  type?: 'base64' | 'binary' | 'buffer' | 'file' | 'array' | 'string';

  /**
   * Generate Shared String Table
   * @default false
   */
  bookSST?: boolean;

  /**
   * File format of generated workbook
   * @default 'xlsx'
   */
  bookType?: BookType;

  /**
   * Use ZIP compression for ZIP-based formats
   * @default false
   */
  compression?: boolean;

  /**
   * Suppress "number stored as text" errors in generated files
   * @default true
   */
  ignoreEC?: boolean;

  /** Override workbook properties on save */
  Props?: Properties;

  /** Base64 encoding of NUMBERS base for exports */
  numbers?: string;
};
```

---

### `ExcelJsExcelExportModule`

Structural subset of the ExcelJS module consumed by
`createExcelJsExcelExportProvider()`.

RevoGrid Pro keeps ExcelJS optional. Callers pass their installed module into
the provider factory so the Pro package does not add ExcelJS to every bundle.

```ts
/**
 * Structural subset of the ExcelJS module consumed by
 * `createExcelJsExcelExportProvider()`.
 *
 * RevoGrid Pro keeps ExcelJS optional. Callers pass their installed module into
 * the provider factory so the Pro package does not add ExcelJS to every bundle.
 */
export type ExcelJsExcelExportModule = {
  Workbook: new () => ExcelJsWorkbook;
};
```

---

### `ExcelJsWorkbook`

```ts
export type ExcelJsWorkbook = {
  addWorksheet(
    sheetName: string,
    options?: Record<string, unknown>,
  ): ExcelJsWorksheet;
  xlsx: {
    writeBuffer?(
      writingOptions?: ExcelExportWritingOptions,
    ): Promise<ArrayBuffer | BlobPart> | ArrayBuffer | BlobPart;
    writeFile?(
      workbookName: string,
      writingOptions?: ExcelExportWritingOptions,
    ): Promise<unknown> | unknown;
  };
};
```

---

### `ExcelJsWorksheet`

```ts
export type ExcelJsWorksheet = {
  addRow(values: unknown[]): ExcelJsRow;
  getColumn?(index: number): ExcelJsColumn;
  mergeCells?(
    startRow: number,
    startColumn: number,
    endRow: number,
    endColumn: number,
  ): void;
  views?: Record<string, unknown>[];
};
```

---

### `ExcelJsRow`

```ts
export type ExcelJsRow = {
  getCell(index: number): ExcelJsCell;
  height?: number;
};
```

---

### `ExcelJsCell`

```ts
export type ExcelJsCell = {
  value?: unknown;
  font?: Record<string, unknown>;
  fill?: Record<string, unknown>;
  alignment?: Record<string, unknown>;
  border?: Record<string, unknown>;
  numFmt?: string;
};
```

---

### `ExcelJsColumn`

```ts
export type ExcelJsColumn = {
  width?: number;
};
```

---

### `SheetJsExcelExportModule`

Structural subset of the SheetJS `xlsx` module consumed by
`createSheetJsExcelExportProvider()`.

RevoGrid Pro does not import or bundle SheetJS. Applications that need this
adapter install `xlsx` themselves and pass the module object into the factory.

```ts
/**
 * Structural subset of the SheetJS `xlsx` module consumed by
 * `createSheetJsExcelExportProvider()`.
 *
 * RevoGrid Pro does not import or bundle SheetJS. Applications that need this
 * adapter install `xlsx` themselves and pass the module object into the factory.
 */
export type SheetJsExcelExportModule = {
  utils: {
    book_new(): unknown;
    json_to_sheet(
      data: DataType[],
      options?: Record<string, unknown>,
    ): unknown;
    aoa_to_sheet?(data: unknown[][], options?: Record<string, unknown>): unknown;
    book_append_sheet(workbook: unknown, worksheet: unknown, sheetName: string): void;
  };
  writeFile(
    workbook: unknown,
    workbookName: string,
    writingOptions?: ExcelExportWritingOptions,
  ): void;
};
```

---

### `WorkbookExportModule`

Minimal workbook module adapter for libraries that can build a workbook from
plain row objects.

This is intentionally smaller than the provider context. Use a custom
`ExcelExportProvider` when a workbook library needs formatted `cellRows`,
merge metadata, grouped headers, or library-specific setup.

```ts
/**
 * Minimal workbook module adapter for libraries that can build a workbook from
 * plain row objects.
 *
 * This is intentionally smaller than the provider context. Use a custom
 * `ExcelExportProvider` when a workbook library needs formatted `cellRows`,
 * merge metadata, grouped headers, or library-specific setup.
 */
export type WorkbookExportModule = {
  createWorkbook(): unknown;
  createWorksheet(
    data: DataType[],
    options?: Record<string, unknown>,
  ): unknown;
  appendWorksheet(workbook: unknown, worksheet: unknown, sheetName: string): void;
  writeFile(
    workbook: unknown,
    workbookName: string,
    writingOptions?: ExcelExportWritingOptions,
  ): void;
};
```

---

### `createDateExcelExportCellProperties`

Create a reusable `excelExport.cellProperties` callback for date columns.

The callback converts valid date-like values into Excel date cells and keeps
empty, invalid, or unsupported values unchanged. Use this helper when you
want to compose the callback into a larger column export configuration.

```ts
export function createDateExcelExportCellProperties(
  options: DateColumnExcelExportOptions = {},
): ExcelExportCellProperties;
```

---

### `createDateExcelExportColumnOptions`

Create column-level Excel export options for date columns.

Valid `Date`, ISO date-only strings, parseable date strings, and numeric date
values are exported as workbook date cells with the configured `format`.
Unsupported values are returned unchanged so the export pipeline keeps the
source value instead of producing an invalid date.

```ts
export function createDateExcelExportColumnOptions(
  options: DateColumnExcelExportOptions = {},
): ExcelExportColumnOptions;
```

---

### `DateColumnExcelExportOptions`

Options for date-column Excel export helpers.

The helpers do not import `@revolist/revogrid-column-date`; callers pass
column metadata and the desired workbook date format explicitly.

```ts
/**
 * Options for date-column Excel export helpers.
 *
 * The helpers do not import `@revolist/revogrid-column-date`; callers pass
 * column metadata and the desired workbook date format explicitly.
 */
export type DateColumnExcelExportOptions = {
  /**
   * Column metadata from the date column.
   *
   * Reserved for future date-package metadata while keeping a consistent
   * options shape with other external column-type export helpers.
   */
  column?: ColumnRegular;
  /**
   * Excel date number format applied to converted date cells.
   *
   * Defaults to `yyyy-mm-dd`.
   */
  format?: string;
};
```

---

### `createNumeralExcelExportCellProperties`

Create a reusable `excelExport.cellProperties` callback for numeral columns.

The callback converts finite numbers and numeric strings into Excel number
cells, applies the inferred or explicit format, and right-aligns converted
values. Non-numeric values are returned unchanged so the export pipeline
preserves the original cell content.

```ts
export function createNumeralExcelExportCellProperties(
  options: NumeralColumnExcelExportOptions = {},
): ExcelExportCellProperties;
```

---

### `createNumeralExcelExportColumnOptions`

Create column-level Excel export options for numeral columns.

Use this when wiring an external numeral column type to Excel export through
`column.excelExport`. The returned options contain the same callback as
`createNumeralExcelExportCellProperties`.

```ts
export function createNumeralExcelExportColumnOptions(
  options: NumeralColumnExcelExportOptions = {},
): ExcelExportColumnOptions;
```

---

### `NumeralColumnExcelExportOptions`

Options for numeral-column Excel export helpers.

These helpers mirror the external numeral column type at export time without
importing the column-type package. Pass the grid column and active
`columnTypes` map when the export format should be inferred from runtime
column-type metadata.

```ts
/**
 * Options for numeral-column Excel export helpers.
 *
 * These helpers mirror the external numeral column type at export time without
 * importing the column-type package. Pass the grid column and active
 * `columnTypes` map when the export format should be inferred from runtime
 * column-type metadata.
 */
export type NumeralColumnExcelExportOptions = {
  /**
   * Column metadata for the exported numeral column.
   *
   * When `format` is not provided, the helper reads `column.columnType` and
   * looks for a matching `numberFormat` value in `columnTypes`.
   */
  column?: ColumnRegular;
  /**
   * Grid column type registry used to infer the Excel number format.
   *
   * Only the matching column type's `numberFormat` string is read. Other
   * metadata stays owned by the runtime column type.
   */
  columnTypes?: ColumnTypes;
  /**
   * Excel number format applied to converted numeric cells.
   *
   * Defaults to the external numeral column type format, `0,0[.]00`.
   */
  format?: string;
};
```

---

### `createSelectExcelExportCellProperties`

Create a reusable `excelExport.cellProperties` callback for select columns.

The callback exports the user-facing label for a stored select value. If no
lookup or source match is available, the original value is converted to a
supported Excel cell primitive and exported unchanged semantically.

```ts
export function createSelectExcelExportCellProperties({
  column,
}: SelectColumnExcelExportOptions): ExcelExportCellProperties;
```

---

### `createSelectExcelExportColumnOptions`

Create column-level Excel export options for select columns.

Use this when wiring an external select column type to Excel export through
`column.excelExport`. The returned options contain the same callback as
`createSelectExcelExportCellProperties`.

```ts
export function createSelectExcelExportColumnOptions(
  options: SelectColumnExcelExportOptions,
): ExcelExportColumnOptions;
```

---

### `SelectSourceEntry`

A select-column source entry that can be exported as either a direct label or
an object resolved through `labelKey` and `valueKey`.

```ts
/**
 * A select-column source entry that can be exported as either a direct label or
 * an object resolved through `labelKey` and `valueKey`.
 */
export type SelectSourceEntry = string | Record<string, unknown>;
```

---

### `SelectColumnMetadata` (Extended from `index.ts`)

Minimal select-column metadata required to resolve exported labels.

The type intentionally captures only the public metadata used by the
external select column type, allowing Excel export integrations to resolve
labels without importing the select package.

```ts
/**
 * Minimal select-column metadata required to resolve exported labels.
 *
 * The type intentionally captures only the public metadata used by the
 * external select column type, allowing Excel export integrations to resolve
 * labels without importing the select package.
 */
export type SelectColumnMetadata = ColumnRegular & {
  /**
   * Select options shown by the runtime column type.
   *
   * String entries are exported directly. Object entries are matched through
   * `valueKey` and exported through `labelKey`.
   */
  source?: SelectSourceEntry[];
  /**
   * Optional precomputed lookup by source value.
   *
   * When present, it is checked before scanning `source` and is useful for
   * large option lists.
   */
  sourceLookup?: Record<string, unknown>;
  /**
   * Object key that contains the human-readable export label.
   */
  labelKey?: string;
  /**
   * Object key that contains the stored cell value.
   */
  valueKey?: string;
};
```

---

### `SelectColumnExcelExportOptions`

Options for select-column Excel export helpers.

```ts
/**
 * Options for select-column Excel export helpers.
 */
export type SelectColumnExcelExportOptions = {
  /**
   * Select column metadata used to translate stored values into labels.
   */
  column: SelectColumnMetadata;
};
```

---

### `ExcelConfig`

```ts
export type ExcelConfig = {

  /** Allow CSV drag and drop files to the grid area. Default: `true`. */
  allowDrag?: boolean;

  /**
   * Grid-level default export provider.
   *
   * `plugin.export({ provider })` still wins for one-off exports. When omitted,
   * the bundled `write-excel-file` provider is used.
   */
  exportProvider?: ExcelExportProviderRef;

  /**
   * Grid-level Excel export transforms for every export call.
   *
   * These run after the plugin prepares the provider context and applies
   * built-in Pro transforms, but before one-off
   * `plugin.export({ exportTransformers })` transforms. Use them for
   * application-wide workbook formatting, provider-option defaults, or
   * provider metadata that should apply consistently to all Excel exports.
   */
  exportTransformers?: ExcelExportContextTransformer[];

  /**
   * Keep existing grid columns during CSV import instead of generating columns
   * from the first CSV row. Default: `false`.
   */
  skipColumnGeneration?: boolean;

  /** Allowed file extensions for CSV import. Default: `['.csv']`. */
  allowedExtensions?: string[];
};
```

---

# Filter

URL: https://pro.rv-grid.com/api/filter/
Source: src/content/docs/api/filter.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /** Global row search observed by AdvanceFilterPlugin. */
      quickFilter?: QuickFilterInput;
  /** Template-friendly alias for `quickFilter`. */
      'quick-filter'?: QuickFilterInput
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /** @deprecated Use `grid.quickFilter` instead. */
      quickFilter?: QuickFilterInput
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  beforefilteroptionsourcerow: FilterOptionSourceRowEventDetail;
  beforefilteroptionvalue: FilterOptionValueEventDetail;
  beforequickfilterapply: QuickFilterApplyEventDetail;
  afterquickfilterapply: QuickFilterApplyEventDetail;
  filterastchange: FilterAstChangeEventDetail;
  filterasterror: FilterAstErrorEventDetail
}
```

---

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Preferred value control for this column in canonical Filter AST editors.
       * Surface-specific `valueEditors` overrides take precedence.
       */
      filterAstValueEditor?: FilterAstEditorSliderValueEditor
}
```

---

### `FilterCaptions` (Extended from `@revolist/revogrid`)

```ts
interface FilterCaptions {
  /**
       * Label shown by an inactive selection control in the filter header.
       */
      selectionAll: string;
  /**
       * The title of the selection filter
       */
      selectionTitle: string;
  /**
       * Placeholder for the selection filter search input.
       */
      selectionSearchPlaceholder: string;
  /** Excel-mode primary action label. */
      selectionApply: string;
  /** Excel-mode dismissal label. */
      selectionCancel: string;
  /** Excel-mode all-values row label. */
      selectionSelectAll: string;
  /** Excel-mode search-results row label. */
      selectionSelectAllSearchResults: string;
  /** Excel-mode union-with-applied-selection label. */
      selectionAddCurrentSelection: string;
  /** Excel-mode action that flips only the currently visible values. */
      selectionInvertVisible: string;
  /** Accessible label for the Excel-mode invert-visible action. */
      selectionInvertVisibleAria: string;
  /** Excel-mode label for null and empty values. */
      selectionBlanks: string;
  /**
       * The title of the slider filter
       */
      sliderTitle: string;
  /**
       * The title of the date filter
       */
      dateTitle: string;
  /**
       * The popup header title before the column name.
       */
      popupHeaderTitle: string;
  /**
       * The popup header separator between title and column name.
       */
      popupHeaderSeparator: string;
  /**
       * Formats the popup header column name from the full column data.
       */
      popupHeaderColumnName: (column: ShowData) => string;
  /**
       * Accessible label for the popup header filter icon when the column has active filters.
       */
      popupHeaderActive: string;
  /**
       * The popup header close icon accessible label and title.
       */
      popupHeaderClose: string;
  /** Accessible label for a column's compact header-filter control. */
      filterHeaderLabel: (column: ColumnRegular) => string;
  /** Inactive compact-header placeholder for free-text filters. */
      filterHeaderSearch: string;
  /** Inactive compact-header placeholder for date filters. */
      filterHeaderAnyDate: string;
  /** Inactive compact-header placeholder for boolean filters. */
      filterHeaderEither: string;
  /** Inactive compact-header placeholder for array filters. */
      filterHeaderAnyItem: string;
  /** Inactive compact-header placeholder for numeric and generic value filters. */
      filterHeaderAnyValue: string;
  /** Inactive compact-header placeholder for application-defined structured filters. */
      structuredFilterHeaderPlaceholder: string;
  /** Inactive compact-header placeholders owned by the built-in structured filters. */
      tokenListHeaderPlaceholder: string;
  fuzzyHeaderPlaceholder: string;
  regexHeaderPlaceholder: string;
  chipBadgeHeaderPlaceholder: string;
  ratingProgressHeaderPlaceholder: string;
  ratingProgressHeaderProgressPlaceholder: string;
  ratingProgressHeaderScorePlaceholder: string;
  timeMatrixHeaderAnyTime: string;
  arrayTagsHeaderPlaceholder: string;
  /** Localized selection-count sentence used by header tooltips and assistive text. */
      filterHeaderSelectionSummary: (
        selected: number,
        total: number,
        details?: string,
      ) => string;
  /**
       * The button label for opening the Pro expression filter editor.
       */
      expressionButton: string;
  /**
       * The title shown above the expression editor.
       */
      expressionTitle: string;
  /**
       * Placeholder text for the expression editor.
       */
      expressionPlaceholder: string;
  /**
       * Accessible label for applying expression text immediately.
       */
      expressionApply: string;
  /** Status shown when an expression parses and validates successfully. */
      expressionValid: string;
  /** Accessible label for the expression autocomplete list. */
      expressionSuggestions: string;
  /**
       * Label shown before expression validation errors.
       * @deprecated Expression validation details are now shown in the expression tooltip.
       */
      expressionInvalid: string
}
```

---

### `ColumnFilterConfig` (Extended from `@revolist/revogrid`)

```ts
interface ColumnFilterConfig {
  /**
       * Delegates filter execution to an external data source while preserving
       * the advanced filter UI and transport events. When enabled, the plugin
       * emits `beforefilterapply` but skips local row trimming; the host is
       * responsible for loading and installing the filtered rows.
       */
      external?: boolean;
  /**
       * Shows the compact filter button in column headers. Set to `false` when
       * filtering is controlled by another surface such as a mounted AST editor.
       * Filtering itself remains enabled. Defaults to `true`.
       */
      columnFilterButton?: boolean;
  /** Enables and configures the grouped rule-builder. Omit to keep grouped view disabled. */
      groupedFilter?: GroupedFilterConfig;
  /** Registered Pro popup body types selected by a column's existing `filter` field. */
      structuredFilterTypes?: readonly StructuredFilterType[];
  /** Complete aggregate data supplied by a remote backend for structured popup bodies. */
      structuredFilterAggregates?: StructuredFilterAggregateProvider;
  /** Array/tag value extraction, globally or by column property. */
      arrayTags?: ArrayTagsOptions;
  /** Faceted-list display labels, globally or by column property. */
      facetedList?: FacetedListOptions;
  /** Canonical Pro filter tree. It wins over collection-based initial filter state. */
      filterAst?: FilterAst;
  /** Timezone, week, fiscal-calendar, and visible-operator policy for date/datetime filters. */
      date?: DateFilterConfig;
  /**
       * Whether the filter panel allows the same operator more than once per column.
       * Defaults to true. Set to false to make visible operators mutually exclusive.
       */
      allowDuplicateOperators?: boolean;
  /**
       * The configuration for the selection filter
       */
      selection?: SelectionConfig;
  /**
       * The configuration for the slider filter.
       *
       * @example
       * ```ts
       * grid.filter = {
       *   slider: {
       *     headerView: 'range',
       *     showRangeDisplay: true,
       *     showRangeInputs: true,
       *     formatInputValue: value => value.toFixed(2),
       *     parseInputValue: value => Number(value.replace(',', '.')),
       *   },
       * };
       * ```
       */
      slider?: SliderFilterConfig;
  /**
       * The configuration for the Pro advanced filter popup header.
       */
      popupHeader?: FilterPopupHeaderConfig;
  /**
       * Opt-in current-column expression editor for advanced filters.
       * When enabled, the popup appends an expandable expression panel below the regular filter controls.
       * Valid expressions compile into the existing `multiFilterItems` filter model.
       *
       * @example
       * ```ts
       * grid.filter = {
       *   expressions: {
       *     enabled: true,
       *     applyDebounceMs: 300,
       *     errorTooltipLabel: 'Expression validation details',
       *     formatDiagnostic: diagnostic => translateExpressionDiagnostic(diagnostic),
       *   },
       * };
       * ```
       */
      expressions?: boolean | ExpressionFilterConfig
}
```

## Plugin API

### `defineAdvancedFilterConfig`

```ts
export function defineAdvancedFilterConfig(
  config: AdvancedFilterConfig,
): ColumnFilterConfig;
```

---

### `AdvancedFilterConfig` (Extended from `index.ts`)

```ts
export type AdvancedFilterConfig = Omit<ColumnFilterConfig, 'localization'> & {
  localization?: AdvancedFilterLocalization;
};
```

---

### `AdvancedFilterLocalization` (Extended from `index.ts`)

```ts
export type AdvancedFilterLocalization = Partial<Omit<CoreFilterLocalization, 'captions' | 'filterNames'>> & {
  /** Partial core captions plus captions for Pro and application-defined filter bodies. */
  captions?: Partial<CoreFilterCaptions> & Record<string, AdvancedFilterCaptionValue>;
  /** Partial core names plus names for Pro and application-defined operators. */
  filterNames?: Partial<CoreFilterLocalization['filterNames']> & Record<string, string>;
};
```

---

### `SetFilterAstOptions`

```ts
interface SetFilterAstOptions {
  /** Keep the latest toolbar quick-filter query and compose it with the replacement AST. */
    preserveQuickFilter?: boolean
}
```

---

### `AdvanceFilterPlugin`

Plugins
The `AdvanceFilterPlugin` extends the filtering capabilities of a RevoGrid component by introducing
advanced, customizable filter options, such as selection and range-based filters. This plugin enhances
the grid's filter functionality, allowing users to interact with and manipulate data effectively.

**Key Features**:
- **Custom Filters**: Introduces custom filter types including `selection` and `slider` for more
  flexible data filtering. These filters allow users to select specific values or define a range
  for filtering data.
- **Event Integration**: Listens for `BEFORE_HEADER_RENDER_EVENT` to determine the applicability
  of filters for a given column, ensuring that only relevant filters are displayed.
- **Dynamic Content Rendering**: Uses a `HyperFunc` to dynamically render filter UI components
  in the grid's header through filter-owned abstract controls and selection list rendering.
- **Enhanced Filter Management**: Provides methods to manage excluded values from filters and
  to generate selection lists based on current data, facilitating complex filter interactions.

**Usage**:
- Integrate `AdvanceFilterPlugin` into a RevoGrid instance to enable advanced filtering features.
  Add the plugin to the grid's plugins array during initialization.

### Example
```typescript
import { AdvanceFilterPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [AdvanceFilterPlugin];
```

This plugin is essential for applications that require sophisticated filtering mechanisms, enabling
users to perform more nuanced data queries and enhancing the overall data exploration experience.

#### Dependencies

- **Optional** `FilterPlugin`: Replaces an existing core FilterPlugin while preserving its filter configuration.
- **Auto-installed** `TooltipPlugin`: Shows shared hover and keyboard-focus details for active-filter badge info icons.

```ts
class AdvanceFilterPlugin {
  initConfig(config: ColumnFilterConfig);

  beforeshow(data: ShowData): void;

  async headerclick(...args: Parameters<FilterPlugin['headerclick']>);

  async onFilterChange(
    filterItems: Parameters<FilterPlugin['onFilterChange']>[0],
    changedProp?: ColumnProp,
  );

  runFiltering(...args: Parameters<FilterPlugin['runFiltering']>);

  emit<T = any>(eventName: string, detail?: T);

  /** Returns the normalized global quick-filter payload currently in effect. */
  getQuickFilter();

  getRowFilter(
    rows: DataType[],
    _filterItems: Parameters<FilterPlugin['getRowFilter']>[1],
    _columnByProp: Record<string, ColumnRegular>,
  ): TrimmedEntity;

  /** Evaluates cascade options against every canonical condition except their own field. */
  getContextAwareRowFilter(
    rows: DataType[],
    columnProp: ColumnProp,
    columnByProp: Record<string, ColumnRegular>,
  ): TrimmedEntity;

  /** Registers or replaces one structured filter popup body for this plugin. */
  registerStructuredFilterType(type: StructuredFilterType);

  /** Removes one structured filter popup body registration. */
  unregisterStructuredFilterType(id: string);

  /** Returns one registered structured filter type by stable id. */
  getStructuredFilterType(id: string);

  /** Canonical active state used by headers even when grouped AST cannot be projected. */
  hasActiveFilterForColumn(prop: ColumnProp);

  /** Resolves one structured column into a compact, data-independent header model. */
  getStructuredFilterHeader(column: ColumnRegular);

  /** Resolves a registered filter's own popup or inline header control. */
  getStructuredFilterHeaderControl(
    column: ColumnRegular,
  ): FilterHeaderControl | undefined;

  async doFiltering(...args: Parameters<FilterPlugin['doFiltering']>);

  /** Returns a defensive clone of the currently applied canonical tree. */
  getFilterAst(): FilterAst | undefined;

  /** Mounts the canonical grouped Filter AST editor into an application-owned host. */
  mountFilterAstEditor(
    host: HTMLElement,
    options: FilterAstEditorMountOptions = {},
  ): FilterAstEditorHandle;

  /** Atomically replaces the canonical tree. Undefined clears it; quick filtering is cleared unless preserved. */
  async setFilterAst(ast?: FilterAst, options: SetFilterAstOptions = {}): Promise<void>;

  async clearFiltering();

  isSelectionCascadeEnabled();

  hasCustomSelectionItems(columnProp: ColumnProp);

  /** Returns whether a row may contribute values to advanced filter options. */
  isFilterOptionSourceRow(row?: DataType);

  /** Resolves a parsed cell value before it contributes advanced-filter options. */
  getFilterOptionValue(
    row: DataType,
    column: ColumnRegular,
    rowType?: DimensionRows,
    rowIndex?: number,
  );

  getContextAwareSelectionList(
    columnProp: ColumnProp,
    exlude = new Set<string>(),
    sourceRowTypes?: DimensionRows[],
  );

  getContextAwareSelectionItems(
    columnProp: ColumnProp,
    exlude = new Set<string>(),
    sourceRowTypes = resolveSelectionFilterConfig(
      this.filterConfig?.selection,
      columnProp,
    ).sourceRowTypes,
  );

  getExcludedValues(columnProp: ColumnProp);

  getSelectionList(
    columnProp: ColumnProp,
    exlude = new Set<string>(),
    sourceRowTypes?: DimensionRows[],
  ): { value: string, label: string }[];

  /** Mounts a framework-neutral active-filter badge list backed by this plugin. */
  createFilterBadges(root: HTMLElement, options: AdvancedFilterBadgesOptions = {});

  destroy();
}
```

---

### `getExtraByOperator`

```ts
export function getExtraByOperator(operator: DateFilterOperator): ExtraField | undefined;
```

---

### `getStartOfToday`

```ts
export function getStartOfToday();
```

---

### `getStartOfYesterday`

```ts
export function getStartOfYesterday();
```

---

### `getStartOfThisMonth`

```ts
export function getStartOfThisMonth();
```

---

### `getStartOfLastMonth`

```ts
export function getStartOfLastMonth();
```

---

### `getStartOfThisQuarter`

```ts
export function getStartOfThisQuarter();
```

---

### `getStartOfThisYear`

```ts
export function getStartOfThisYear();
```

---

### `FILTER_DATE`

```ts
FILTER_DATE: string;
```

---

### `DateFilterOperatorWithDatePickerExtra`

```ts
export type DateFilterOperatorWithDatePickerExtra =
  | 'equals' | 'before' | 'after' | 'onOrBefore' | 'onOrAfter' | 'notEqual';
```

---

### `DateFilterOperatorWithDateRangeExtra`

```ts
export type DateFilterOperatorWithDateRangeExtra = 'between';
```

---

### `DateRangeValue`

```ts
interface DateRangeValue {
  operator: DateFilterOperator;
  fromDate?: string;
  toDate?: string
}
```

---

### `datetimeFilterOperators`

```ts
datetimeFilterOperators: ("datetimeEquals" | "datetimeBefore" | "datetimeAfter" | "datetimeOnOrBefore" | "datetimeOnOrAfter" | "datetimeBetween" | "datetimeNotEqual" | "datetimeIsEmpty" | "datetimeIsNotEmpty" | "datetimeToday" | "datetimeYesterday" | "datetimeLast7Days" | "datetimeNext30Days" | "datetimeThisWeek" | "datetimeLastWeek" | "datetimeNextWeek" | "datetimeThisMonth" | "datetimeLastMonth" | "datetimeThisQuarter" | "datetimeNextQuarter" | "datetimePreviousQuarter" | "datetimeThisYear" | "datetimeNextYear" | "datetimePreviousYear" | "datetimeThisFiscalQuarter" | "datetimeNextFiscalQuarter" | "datetimePreviousFiscalQuarter" | "datetimeThisFiscalYear" | "datetimeNextFiscalYear" | "datetimePreviousFiscalYear")[];
```

---

### `DATE_FILTERS`

Browser-local compatibility registry used outside an AdvanceFilterPlugin instance.

```ts
DATE_FILTERS: Record<"equals" | "before" | "after" | "onOrBefore" | "onOrAfter" | "between" | "notEqual" | "isEmpty" | "isNotEmpty" | "today" | "yesterday" | "last7Days" | "next30Days" | "thisWeek" | "lastWeek" | "nextWeek" | "thisMonth" | "lastMonth" | "thisQuarter" | "nextQuarter" | "previousQuarter" | "thisYear" | "nextYear" | "previousYear" | "thisFiscalQuarter" | "nextFiscalQuarter" | "previousFiscalQuarter" | "thisFiscalYear" | "nextFiscalYear" | "previousFiscalYear", CustomFilter<any, LogicFunctionExtraParam>>;
```

---

### `DATETIME_FILTERS`

Browser-local datetime registry. AdvanceFilterPlugin installs an isolated per-grid registry.

```ts
DATETIME_FILTERS: Record<"datetimeEquals" | "datetimeBefore" | "datetimeAfter" | "datetimeOnOrBefore" | "datetimeOnOrAfter" | "datetimeBetween" | "datetimeNotEqual" | "datetimeIsEmpty" | "datetimeIsNotEmpty" | "datetimeToday" | "datetimeYesterday" | "datetimeLast7Days" | "datetimeNext30Days" | "datetimeThisWeek" | "datetimeLastWeek" | "datetimeNextWeek" | "datetimeThisMonth" | "datetimeLastMonth" | "datetimeThisQuarter" | "datetimeNextQuarter" | "datetimePreviousQuarter" | "datetimeThisYear" | "datetimeNextYear" | "datetimePreviousYear" | "datetimeThisFiscalQuarter" | "datetimeNextFiscalQuarter" | "datetimePreviousFiscalQuarter" | "datetimeThisFiscalYear" | "datetimeNextFiscalYear" | "datetimePreviousFiscalYear", CustomFilter<any, LogicFunctionExtraParam>>;
```

---

### `FILTER_DATETIME`

```ts
FILTER_DATETIME: string;
```

---

### `isDateFilterOperator`

```ts
export function isDateFilterOperator(operator: unknown): operator is DateFilterOperator;
```

---

### `resolveDateFilterOperators`

Resolves the authored menu order for one date/datetime column.

```ts
export function resolveDateFilterOperators(
  config?: DateFilterConfig,
  prop?: ColumnProp,
): DateFilterOperator[];
```

---

### `toDatetimeFilterOperator`

```ts
export function toDatetimeFilterOperator(operator: DateFilterOperator): DatetimeFilterOperator;
```

---

### `standardDateFilterOperators`

```ts
standardDateFilterOperators: readonly ["equals", "before", "after", "onOrBefore", "onOrAfter", "between", "notEqual", "isEmpty", "isNotEmpty", "today", "yesterday", "last7Days", "next30Days", "thisWeek", "lastWeek", "nextWeek", "thisMonth", "lastMonth", "thisQuarter", "nextQuarter", "previousQuarter", "thisYear", "nextYear", "previousYear"];
```

---

### `fiscalDateFilterOperators`

```ts
fiscalDateFilterOperators: readonly ["thisFiscalQuarter", "nextFiscalQuarter", "previousFiscalQuarter", "thisFiscalYear", "nextFiscalYear", "previousFiscalYear"];
```

---

### `filterOperators`

```ts
filterOperators: readonly ["equals", "before", "after", "onOrBefore", "onOrAfter", "between", "notEqual", "isEmpty", "isNotEmpty", "today", "yesterday", "last7Days", "next30Days", "thisWeek", "lastWeek", "nextWeek", "thisMonth", "lastMonth", "thisQuarter", "nextQuarter", "previousQuarter", "thisYear", "nextYear", "previousYear", "thisFiscalQuarter", "nextFiscalQuarter", "previousFiscalQuarter", "thisFiscalYear", "nextFiscalYear", "previousFiscalYear"];
```

---

### `DateFilterOperator`

```ts
export type DateFilterOperator = typeof filterOperators[number];
```

---

### `DatetimeFilterOperator`

```ts
export type DatetimeFilterOperator = `datetime${Capitalize<DateFilterOperator>}`;
```

---

### `validateDateFilterConfig`

```ts
export function validateDateFilterConfig(config?: DateFilterConfig);
```

---

### `resolveDateFilterSettings`

```ts
export function resolveDateFilterSettings(
  config?: DateFilterConfig,
  prop?: ColumnProp,
): ResolvedDateFilterSettings;
```

---

### `detectTemporalFilterFamily`

```ts
export function detectTemporalFilterFamily(column?: ColumnRegular): TemporalFilterFamily | undefined;
```

---

### `temporalFilterFamily`

```ts
export function temporalFilterFamily(column?: ColumnRegular): TemporalFilterFamily;
```

---

### `createTemporalFilters`

```ts
export function createTemporalFilters(
  runtime: TemporalFilterRuntime,
  family: TemporalFilterFamily,
  operators: readonly string[],
);
```

---

### `getBrowserTimeZone`

```ts
export function getBrowserTimeZone();
```

---

### `getCivilParts`

Projects an instant into Gregorian civil fields in an IANA timezone.

```ts
export function getCivilParts(instant: Date, timeZone: string): CivilDateTime;
```

---

### `getPossibleInstants`

Returns every instant represented by a civil second in an IANA timezone.

```ts
export function getPossibleInstants(value: CivilDateTime, timeZone: string): Date[];
```

---

### `resolveCivilBoundary`

Period boundaries advance through a timezone gap to its first valid civil instant.

```ts
export function resolveCivilBoundary(value: CivilDateTime, timeZone: string): Date;
```

---

### `resolveExactCivilInstant`

```ts
export function resolveExactCivilInstant(value: CivilDateTime, timeZone: string): Date | undefined;
```

---

### `assertValidTimeZone`

Validates an IANA timezone at the shared date boundary.

```ts
export function assertIanaTimeZone(timeZone: string, label = 'timeZone'): void;
```

---

### `CivilDateTime`

Calendar and clock fields interpreted in a specific IANA timezone.

```ts
interface CivilDateTime {
  readonly year: number;
  readonly month: number;
  readonly day: number;
  readonly hour: number;
  readonly minute: number;
  readonly second: number
}
```

---

### `TemporalFilterRuntime`

```ts
class TemporalFilterRuntime {
  configure(config?: DateFilterConfig);

  beginRun(referenceInstant = new Date());

  /** Calendar date containing this run's captured instant for one resolved column timezone. */
  referenceDate(prop?: ColumnProp): ISODateString;

  /** Resolves this run's captured instant in an editor-specific timezone. */
  referenceDateForTimeZone(timeZone: string): ISODateString;

  settings(prop?: ColumnProp);

  isValidControl(value: string, family: TemporalFilterFamily, prop?: ColumnProp);

  matches(
    family: TemporalFilterFamily,
    operator: string,
    rowValue: unknown,
    extra: unknown,
    context?: FilterEvaluationContext,
  );

  buildTransport(
    filterItems: MultiFilterItem,
    columns: ColumnRegular[],
    canonicalAst?: FilterAst,
  ): TemporalFilterContext;
}
```

---

### `TemporalTimeZoneMode`

```ts
export type TemporalTimeZoneMode = 'user' | 'organization' | 'utc' | 'explicit';
```

---

### `FiscalYearStart`

```ts
interface FiscalYearStart {
  /** One-based calendar month. */
    month: number;
  day: number
}
```

---

### `DateFilterSettings`

```ts
interface DateFilterSettings {
  timezoneMode?: TemporalTimeZoneMode;
  userTimeZone?: string;
  organizationTimeZone?: string;
  timeZone?: string;
  /** Sunday is 0 and Saturday is 6. Defaults to Monday. */
    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  fiscalYearStart?: FiscalYearStart;
  /** Ordered operator allowlist for this date/datetime menu. */
    operators?: readonly DateFilterOperator[]
}
```

---

### `DateFilterConfig` (Extended from `index.ts`)

```ts
interface DateFilterConfig {
  /** Partial settings keyed by column property. */
    columns?: Record<string, DateFilterSettings | undefined>
}
```

---

### `ResolvedDateFilterSettings`

```ts
interface ResolvedDateFilterSettings {
  timezoneMode: TemporalTimeZoneMode;
  timeZone: string;
  weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  fiscalYearStart: FiscalYearStart
}
```

---

### `TemporalFilterFamily`

```ts
export type TemporalFilterFamily = 'date' | 'datetime';
```

---

### `TemporalResolvedCondition`

```ts
interface TemporalResolvedCondition {
  family: TemporalFilterFamily;
  operator: string;
  /** Inclusive UTC boundary. Null means unbounded. */
    start: string | null;
  /** Exclusive UTC boundary. Null means unbounded. */
    endExclusive: string | null
}
```

---

### `TemporalColumnContext`

```ts
interface TemporalColumnContext {
  timeZone: string;
  timezoneMode: TemporalTimeZoneMode;
  /** Calendar semantics required to resolve rolling/aligned remote windows. */
    weekStartsOn: ResolvedDateFilterSettings['weekStartsOn'];
  fiscalYearStart: FiscalYearStart
}
```

---

### `TemporalFilterContext`

JSON-safe temporal envelope forwarded with remote filtering.

```ts
interface TemporalFilterContext {
  referenceInstant: string;
  columns: Record<string, TemporalColumnContext>;
  /** Entries use `<column property>:<filter id>` or a stable `:ast:<node path>` suffix. */
    conditions: Record<string, TemporalResolvedCondition[]>
}
```

---

### `FILTER_BOOLEAN`

Column filter family for boolean primitive values.

```ts
FILTER_BOOLEAN: string;
```

---

### `BooleanFilterOperator`

Operators exposed by the advanced boolean filter family.

```ts
/** Operators exposed by the advanced boolean filter family. */
export type BooleanFilterOperator = 'isTrue' | 'isFalse';
```

---

### `BOOLEAN_FILTERS`

Advanced-filter definitions for strict boolean primitive matching.

```ts
BOOLEAN_FILTERS: {
  isTrue: { columnFilterType: string; name: "Yes"; func: LogicFunction<any, LogicFunctionExtraParam>; };
  isFalse: { columnFilterType: string; name: "No"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `booleanFilterCaption`

```ts
export function booleanFilterCaption(
  labels: StructuredFilterLabels,
  id: BooleanFilterCaptionId,
): string;
```

---

### `booleanFilterMessage`

```ts
export function booleanFilterMessage(
  labels: StructuredFilterLabels,
  id: BooleanFilterCaptionId,
  values: BooleanFilterMessageValues = {},
): string;
```

---

### `booleanFilterFallbackMessage`

```ts
export function booleanFilterFallbackMessage(
  id: BooleanFilterCaptionId,
  values: BooleanFilterMessageValues = {},
): string;
```

---

### `BOOLEAN_FILTER_LOCALIZATION`

Stable localization keys and complete English fallbacks for boolean filters.

```ts
BOOLEAN_FILTER_LOCALIZATION: Readonly<{ filterNames: Readonly<{ isTrue: "Yes"; isFalse: "No"; triStateBoolean: "Is Yes or No"; }>; captions: Readonly<{ triStateBooleanTitle: "Boolean value"; triStateBooleanDescription: "Show rows by their exact boolean value."; triStateBooleanChoice: "Boolean filter"; triStateBooleanAll: "All"; triStateBooleanYes: "Yes"; triStateBooleanNo: "No"; triStateBooleanBlankTitle: "Treat blank as “No”"; triStateBooleanBlankAriaLabel: "Treat blank as No"; triStateBooleanMatchedRows: "{matched} of {total} rows"; }>; }>;
```

---

### `BooleanFilterCaptionId`

```ts
export type BooleanFilterCaptionId = keyof typeof BOOLEAN_FILTER_LOCALIZATION.captions;
```

---

### `BooleanFilterMessageValues`

```ts
export type BooleanFilterMessageValues = Readonly<Record<string, string | number>>;
```

---

### `FILTER_ARRAY`

Column filter family for array-valued cells.

```ts
FILTER_ARRAY: string;
```

---

### `ArrayFilterOperator`

Strict, valueless operators for array-valued cells.

```ts
/** Strict, valueless operators for array-valued cells. */
export type ArrayFilterOperator = 'isEmptyArray' | 'isNotEmptyArray';
```

---

### `ARRAY_FILTERS`

Advanced-filter definitions for strict array length matching.

```ts
ARRAY_FILTERS: {
  isEmptyArray: { columnFilterType: string; name: "Is empty array"; func: LogicFunction<any, LogicFunctionExtraParam>; };
  isNotEmptyArray: { columnFilterType: string; name: "Is not empty array"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `ARRAY_FILTER_LOCALIZATION`

Stable localization keys and English fallbacks for strict array operators.

```ts
ARRAY_FILTER_LOCALIZATION: Readonly<{ filterNames: Readonly<{ isEmptyArray: "Is empty array"; isNotEmptyArray: "Is not empty array"; }>; }>;
```

---

### `SliderRange`

```ts
export type SliderRange = { fromValue: number; toValue: number };
```

---

### `GroupedFilterPreviewResult`

```ts
interface GroupedFilterPreviewResult {
  matching: number;
  total: number
}
```

---

### `GroupedFilterConfig`

Options for the opt-in grouped rule-builder UI.
Omit `groupedFilter` from the column filter config to keep grouped view disabled.

```ts
interface GroupedFilterConfig {
  /** Set for a partially loaded datasource so page rows are never presented as the dataset total. */
    remote?: boolean;
  /** Optional server-backed exact match count. Superseded edits abort the supplied signal. */
    preview?(request: {
      ast?: FilterAst;
      signal: AbortSignal;
    }): GroupedFilterPreviewResult | Promise<GroupedFilterPreviewResult>
}
```

---

### `FilterAstEditorMountOptions`

Options for mounting the canonical grouped Filter AST editor into application UI.

```ts
interface FilterAstEditorMountOptions {
  /** Defaults to `builder`; explicit config is deeply merged over the preset. */
    preset?: FilterAstEditorPreset;
  config?: FilterAstEditorConfig;
  /** Field selected first when a new condition is added. */
    currentProp?: ColumnProp;
  /** Called after Cancel restores the latest mounted or applied baseline. */
    onCancel?(): void;
  /** Direct typed localization overrides for this mounted surface. */
    translations?: GroupedFilterTranslationOverrides;
  /**
     * Predeclared condition slots kept by persistent-condition layouts. The
     * effective AST may omit cleared slots without removing them from the UI.
     */
    conditionSlots?: readonly FilterAstCondition[];
  /** Field/operator-scoped value control overrides for this mounted surface. */
    valueEditors?: readonly FilterAstEditorValueEditorOverride[]
}
```

---

### `FilterAstEditorSliderValueEditor`

```ts
interface FilterAstEditorSliderValueEditor {
  kind: 'slider';
  /** Defaults to the minimum finite value in the column source. */
    min?: number;
  /** Defaults to the maximum finite value in the column source. */
    max?: number;
  /** Native range step. Defaults to `1`. */
    step?: number | 'any';
  /** Formats the visible and accessible current-value label. */
    formatValue?(value: number): string
}
```

---

### `FilterAstEditorValueEditorOverride`

```ts
interface FilterAstEditorValueEditorOverride {
  field: ColumnProp;
  /** Omit to apply the editor to every compatible operator for the field. */
    operator?: FilterAstCondition['operator'];
  editor: FilterAstEditorSliderValueEditor
}
```

---

### `FilterAstEditorPreset`

```ts
export type FilterAstEditorPreset = 'builder' | 'fixed-list' | 'read-only';
```

---

### `FilterAstEditorInteractionState`

```ts
export type FilterAstEditorInteractionState = 'editable' | 'read-only' | 'disabled';
```

---

### `FilterAstEditorStructureOptions`

```ts
interface FilterAstEditorStructureOptions {
  shape?: 'tree' | 'flat';
  rootOperator?: 'editable' | 'and' | 'or';
  incompatibleAst?: 'reject' | 'read-only';
  conditionSlots?: 'dynamic' | 'persistent'
}
```

---

### `FilterAstEditorTreeCapabilities`

```ts
interface FilterAstEditorTreeCapabilities {
  add?: 'conditions-and-groups' | 'conditions' | 'none';
  removeCondition?: boolean;
  removeGroup?: boolean;
  reorder?: 'all' | 'conditions' | 'groups' | 'none';
  negate?: boolean;
  changeNestedOperator?: boolean
}
```

---

### `FilterAstEditorConditionCapabilities`

```ts
interface FilterAstEditorConditionCapabilities {
  changeField?: boolean;
  changeOperator?: boolean;
  changeValue?: boolean;
  clear?: boolean;
  activateOnValidValue?: boolean;
  activateValueless?: boolean
}
```

---

### `FilterAstEditorCapabilities`

```ts
interface FilterAstEditorCapabilities {
  tree?: FilterAstEditorTreeCapabilities;
  condition?: FilterAstEditorConditionCapabilities;
  actions?: { apply?: boolean; cancel?: boolean; reset?: boolean; clearAll?: boolean }
}
```

---

### `FilterAstEditorHeaderPresentation`

```ts
interface FilterAstEditorHeaderPresentation {
  title?: boolean;
  description?: boolean
}
```

---

### `FilterAstEditorStatusPresentation`

```ts
interface FilterAstEditorStatusPresentation {
  ruleSummary?: boolean;
  preview?: boolean
}
```

---

### `FilterAstEditorModePresentation`

```ts
interface FilterAstEditorModePresentation {
  allowed?: readonly ('rules' | 'text')[];
  initial?: 'rules' | 'text';
  switch?: boolean
}
```

---

### `FilterAstEditorGroupPresentation`

```ts
interface FilterAstEditorGroupPresentation {
  label?: boolean;
  rootInstruction?: boolean;
  logicControl?: boolean;
  actions?: boolean
}
```

---

### `FilterAstEditorConditionPresentation`

```ts
interface FilterAstEditorConditionPresentation {
  field?: 'control' | 'label' | 'hidden';
  operator?: 'control' | 'label' | 'hidden';
  /** Visual treatment for an operator label or editable operator control. */
    operatorAppearance?: 'plain' | 'badge';
  removeAction?: boolean;
  reorderHandle?: boolean;
  clearAction?: boolean
}
```

---

### `FilterAstEditorFooterPresentation`

```ts
interface FilterAstEditorFooterPresentation {
  apply?: boolean;
  cancel?: boolean;
  reset?: boolean
}
```

---

### `FilterAstEditorPresentation`

```ts
interface FilterAstEditorPresentation {
  header?: false | FilterAstEditorHeaderPresentation;
  status?: false | FilterAstEditorStatusPresentation;
  mode?: FilterAstEditorModePresentation;
  group?: FilterAstEditorGroupPresentation;
  condition?: FilterAstEditorConditionPresentation;
  footer?: false | FilterAstEditorFooterPresentation;
  clearAll?: boolean
}
```

---

### `FilterAstEditorWorkflowOptions`

```ts
interface FilterAstEditorWorkflowOptions {
  mode?: 'staged' | 'immediate';
  debounceMs?: number;
  reset?: 'empty' | 'baseline'
}
```

---

### `FilterAstEditorConfig`

```ts
interface FilterAstEditorConfig {
  structure?: FilterAstEditorStructureOptions;
  capabilities?: FilterAstEditorCapabilities;
  presentation?: FilterAstEditorPresentation;
  workflow?: FilterAstEditorWorkflowOptions;
  interaction?: FilterAstEditorInteractionState
}
```

---

### `FilterAstEditorHandle`

Lifecycle and synchronization handle for an externally mounted Filter AST editor.

```ts
interface FilterAstEditorHandle {
  /** Replace the editor baseline and discard its current draft without applying it. */
    reset(ast?: FilterAst): void;
  /** Unmount effects and listeners and release the host. Idempotent. */
    destroy(): void
}
```

---

### `RangeSliderProps`

Props for the RangeSlider component.

The slider keeps its own visual controls synchronized with optional editable
inputs. Use `formatInputValue` and `parseInputValue` together when the input
text must follow a custom number format, such as comma decimals.

**Example:**
```typescript
slider: {
  headerView: 'range',
  showRangeInputs: true,
  formatValue: value => value.toFixed(2),
  formatInputValue: value => value.toFixed(2).replace('.', ','),
  parseInputValue: value => Number(value.replace(',', '.')),
}
```

```ts
interface RangeSliderProps {
  /** Minimum value for the range */
    min: number;
  /** Maximum value for the range */
    max: number;
  /** Current value for the start of the range */
    fromValue: number;
  /** Current value for the end of the range */
    toValue: number;
  /** Value-domain increment for native range handles. Defaults to the slider's decimal precision. */
    step?: number;
  /** Whether to show tooltips on hover */
    showTooltips?: boolean;
  /** Whether to show the current range values above the slider */
    showRangeDisplay?: boolean;
  /** Whether to show numeric inputs for editing the selected range */
    showRangeInputs?: boolean;
  /** Disable both native range handles. */
    disabled?: boolean;
  /** Scaling used to preserve decimals in native range inputs. Defaults to 100. */
    scaleFactor?: number;
  /** Extra class on the shared slider root. */
    className?: string;
  /** Extra class on the shared dual-handle control. */
    controlClassName?: string;
  /** Extra classes retained by feature adapters. */
    fromClassName?: string;
  toClassName?: string;
  /** Accessible names for the two native range handles. */
    fromAriaLabel?: string;
  toAriaLabel?: string;
  /**
     * Optional function to format values inside the editable inputs.
     * Defaults to `String(value)`, which keeps dot decimals independent of the
     * browser's localized number input rendering.
     */
    formatInputValue?: (value: number) => string;
  /**
     * Optional function to parse editable input text back to a number.
     * Return `NaN` to ignore incomplete or invalid text while the user is typing.
     * The default parser accepts both dot and comma decimal separators.
     */
    parseInputValue?: (value: string) => number;
  /** Callback fired when the range values change */
    onRangeChange: (range: SliderRange) => void;
  /** Callback fired when a native handle commits its change. */
    onRangeCommit?: (range: SliderRange) => void;
  /**
     * Optional function to format read-only labels and tooltips.
     * Editable inputs use `formatInputValue` so display labels and input text can
     * intentionally use different formats.
     */
    formatValue?: (value: number) => string;
  /** Optional handle-specific display/accessible value formatters. */
    formatFromValue?: (value: number) => string;
  formatToValue?: (value: number) => string
}
```

---

### `SliderFilterFormatContext`

Active column details available while formatting advanced-filter slider labels.

```ts
interface SliderFilterFormatContext {
  /** Property of the column whose filter popup is open. */
    readonly columnProp: ColumnProp;
  /** Full owning column definition. */
    readonly column: ColumnRegular
}
```

---

### `SliderFilterHeaderView`

Header representation used for slider-filter columns.

```ts
/** Header representation used for slider-filter columns. */
export type SliderFilterHeaderView = 'slider' | 'range';
```

---

### `SliderFilterConfig` (Extended from `index.ts`)

Public slider-filter presentation options. Filtering remains numeric.

```ts
/** Public slider-filter presentation options. Filtering remains numeric. */
export type SliderFilterConfig = Omit<
  Pick<
    RangeSliderProps,
    | 'showTooltips'
    | 'showRangeDisplay'
    | 'showRangeInputs'
    | 'formatValue'
    | 'formatInputValue'
    | 'parseInputValue'
  >,
  'formatValue'
> & {
  /**
   * Slider-filter representation rendered by FilterHeaderPlugin.
   * Defaults to `slider`; use `range` for a compact formatted from-to summary.
   */
  headerView?: SliderFilterHeaderView;
  /** Formats the slider section title with access to the active column. */
  formatTitle?: (context: SliderFilterFormatContext) => string | undefined;
  /** Formats labels and tooltips with access to the active column. */
  formatValue?: (value: number, context: SliderFilterFormatContext) => string;
};
```

---

### `SelectionItem`

```ts
export type SelectionItem = {
  value: string;
  label: string;
  [key: string]: any;
};
```

---

### `GetItemsFn`

```ts
export type GetItemsFn = (
  prop: ColumnProp,
  request?: { search?: string; signal?: AbortSignal },
) => Promise<SelectionItem[]> | SelectionItem[];
```

---

### `SelectionQuickSearchFilterContext`

```ts
export type SelectionQuickSearchFilterContext = {
  /** Current column prop for the selection filter popup. */
  columnProp: ColumnProp;
  /** Normalized search text typed into the selection popup. */
  search: string;
  /** Normalized option value used by selection filtering. */
  value: string;
  /** Display label for the option. */
  label: string;
  /** Original item returned by the default option loader or custom `selection.getItems`. */
  item: SelectionItem;
};
```

---

### `SelectionQuickSearchFilter`

```ts
export type SelectionQuickSearchFilter = (
  context: SelectionQuickSearchFilterContext,
) => boolean;
```

---

### `SelectionQuickSearchFilterValue`

```ts
export type SelectionQuickSearchFilterValue = {
  search: string;
  matchingValues: Set<string>;
};
```

---

### `SelectionItemTemplateProps`

```ts
export type SelectionItemTemplateProps = {
  /** Current column prop for the selection filter popup. */
  columnProp: ColumnProp;
  /** Original item returned by the default option loader or custom `selection.getItems`. */
  item: SelectionItem;
  /** Normalized option value used by selection filtering. */
  value: string;
  /** Display label for the option. */
  label: string;
  /** Whether this option is currently included in the filter result. */
  checked: boolean;
  /** Whether this option is unavailable in the current cascade context. */
  disabled: boolean;
};
```

---

### `SelectionItemTemplate`

```ts
export type SelectionItemTemplate = (
  h: HyperFunc<VNode>,
  props: SelectionItemTemplateProps,
) => any;
```

---

### `SelectionOptionColumn`

Read-only metadata column appended to the selection option grid.
Its `prop` reads from the corresponding `SelectionItem`, so custom loaders
can expose counts, progress, avatars, or any other option-level metadata.

```ts
/**
 * Read-only metadata column appended to the selection option grid.
 * Its `prop` reads from the corresponding `SelectionItem`, so custom loaders
 * can expose counts, progress, avatars, or any other option-level metadata.
 */
export type SelectionOptionColumn = ColumnRegular;
```

---

### `SelectionOptionProgressContext`

```ts
export type SelectionOptionProgressContext = SelectionItemTemplateProps;
```

---

### `SelectionOptionProgressMaxContext`

```ts
export type SelectionOptionProgressMaxContext = {
  /** Current filtered column property. */
  columnProp: ColumnProp;
  /** Loaded option items in their current filter-list scope. */
  items: readonly SelectionItem[];
  /** Finite progress values resolved from those items. */
  values: readonly number[];
};
```

---

### `SelectionOptionProgressConfig`

Responsive progress presentation owned by a selection option row.

```ts
/** Responsive progress presentation owned by a selection option row. */
export type SelectionOptionProgressConfig = {
  /** Item metadata property containing the numeric value. Defaults to `count`. */
  valueProp?: ColumnProp;
  /** Custom value resolver. Takes precedence over `valueProp`. */
  getValue?: (context: SelectionOptionProgressContext) => number;
  /** Numeric range minimum. Defaults to zero. */
  min?: number;
  /** Fixed numeric range maximum. Defaults to the largest loaded option value. */
  max?: number;
  /** Dynamic range maximum resolver. Takes precedence over `max`. */
  getMax?: (context: SelectionOptionProgressMaxContext) => number;
  /** Show the formatted value after the progress track. Defaults to true. */
  showValue?: boolean;
  /** Formats the numeric value displayed after the track. */
  formatValue?: (value: number, context: SelectionOptionProgressContext) => string;
  /** Accessible name for the progressbar. */
  ariaLabel?: string | ((value: number, context: SelectionOptionProgressContext) => string);
};
```

---

### `SelectionGridSettings`

```ts
export type SelectionGridSettings = Partial<{
  additionalData: HTMLRevoGridElement['additionalData'];
  autoSizeColumn: HTMLRevoGridElement['autoSizeColumn'];
  canFocus: HTMLRevoGridElement['canFocus'];
  colSize: HTMLRevoGridElement['colSize'];
  columnTypes: HTMLRevoGridElement['columnTypes'];
  editors: HTMLRevoGridElement['editors'];
  frameSize: HTMLRevoGridElement['frameSize'];
  hideAttribution: HTMLRevoGridElement['hideAttribution'];
  noHorizontalScrollTransfer: HTMLRevoGridElement['noHorizontalScrollTransfer'];
  range: HTMLRevoGridElement['range'];
  readonly: HTMLRevoGridElement['readonly'];
  resize: HTMLRevoGridElement['resize'];
  rowDefinitions: HTMLRevoGridElement['rowDefinitions'];
  rowHeaders: HTMLRevoGridElement['rowHeaders'];
  rowSize: HTMLRevoGridElement['rowSize'];
  theme: HTMLRevoGridElement['theme'];
  tree: HTMLRevoGridElement['tree'];
  useClipboard: HTMLRevoGridElement['useClipboard'];
}>;
```

---

### `SelectionCascadeOptionVisibility`

```ts
export type SelectionCascadeOptionVisibility = 'hide' | 'disable' | 'show';
```

---

### `SelectionCascadeConfig`

```ts
export type SelectionCascadeConfig = {
  /**
   * Enables context-aware selection options.
   * When true, selection values are calculated from rows matching active filters
   * in other columns, excluding the current column filter itself.
   */
  enabled?: boolean;
  /**
   * Controls how values outside the current cascade context are presented.
   * - `hide`: omit context-invalid values.
   * - `disable`: show context-invalid values with disabled controls.
   * - `show`: show every value with interactive controls.
   * Defaults to `hide` when cascading is enabled. Existing exclusions are
   * preserved in every mode.
   */
  optionVisibility?: SelectionCascadeOptionVisibility;
  /**
   * Shows active filter dependency order badges next to header filter icons.
   * Disabled by default. Set to true to show dependency badges.
   */
  showDependencyNumbers?: boolean;
};
```

---

### `SelectionConfig`

```ts
export type SelectionConfig = {
  /**
   * Enables the staged Windows Excel-style selection-filter interaction.
   * The default selection filter remains unchanged when omitted.
   */
  excelMode?: 'windows';
  sortDirection?: 'asc' | 'desc' | 'none';
  /**
   * Opt in to server-backed option search through the second `getItems`
   * argument. When omitted, custom items are searched locally so existing
   * loaders that ignore the request remain backward compatible.
   * A record can opt in individual column properties.
   */
  remoteSearch?: boolean | Record<string, boolean>;
  /**
   * Reuse the owning column's cell template for selection option content.
   * Explicit `itemTemplate` renderers take precedence.
   * - Pass a boolean to apply it globally to all selection-filter columns.
   * - Pass a record keyed by column prop to opt in per column.
   */
  syncCellTemplate?: boolean | Record<string, boolean>;
  /**
   * Row stores used by local filter option and structured-aggregate collectors.
   * Defaults to all row stores for backward compatibility. Set to `['rgRow']`
   * to derive filter values from the main data source only and ignore pinned rows.
   */
  sourceRowTypes?: DimensionRows[];
  /**
   * Controls whether typing in the selection popup search input also applies a
   * hidden `quickSearch` filter to the grid rows.
   * Defaults to true for backward compatibility. Set to false to only narrow
   * the popup option list while keeping the grid rows unchanged until checkbox
   * selection values are changed.
   */
  quickSearchFiltering?: boolean;
  /**
   * Custom matcher for the selection popup quick search.
   * Use it when option values are IDs but users should search rendered labels,
   * names, or metadata. The same matcher is used to build the hidden grid-row
   * quick search when `quickSearchFiltering` is enabled.
   * - Pass a function to apply it globally to all selection-filter columns.
   * - Pass a record keyed by column prop to override per column.
   */
  quickSearchFilter?:
    | SelectionQuickSearchFilter
    | Record<string, SelectionQuickSearchFilter>;
  /**
   * Optional grouping for selection filter option rows.
   * - Pass a config to apply it globally to all selection-filter columns.
   * - Pass a record keyed by column prop to override per column.
   */
  grouping?: GroupingOptions | Record<string, GroupingOptions>;
  /**
   * Provide a custom loader for selection list items.
   * - Pass a function to apply it globally to all columns.
   * - Pass a record keyed by column prop to override per column;
   *   columns without an entry fall back to the default store-based lookup.
   */
  getItems?: GetItemsFn | Record<string, GetItemsFn>;
  /**
   * Custom renderer for selection option content.
   * The plugin still renders and controls the checkbox; this template replaces
   * the label content next to it, so icons and custom item metadata can be shown
   * without changing selection semantics.
   * - Pass a function to apply it globally to all columns.
   * - Pass a record keyed by column prop to override per column.
   */
  itemTemplate?: SelectionItemTemplate | Record<string, SelectionItemTemplate>;
  /**
   * Additional read-only columns rendered after the owned checkbox/label column.
   * Pass an array globally or a record keyed by the filtered column prop.
   */
  optionColumns?: SelectionOptionColumn[] | Record<string, SelectionOptionColumn[]>;
  /**
   * Renders a responsive progress track and value inside the selection-owned option row.
   * Pass one config globally or a record keyed by filtered column prop; use `false` to
   * suppress a global/per-column entry.
   */
  optionProgress?:
    | SelectionOptionProgressConfig
    | Record<string, SelectionOptionProgressConfig | false>;
  /**
   * Custom plugins for the nested selection option grid.
   * - Pass an array to apply it globally to all selection-filter columns.
   * - Pass a record keyed by column prop to override per column.
   */
  plugins?: GridPlugin[] | Record<string, GridPlugin[]>;
  /**
   * Optional settings for the nested selection option grid.
   * `source`, `columns`, and `grouping` stay controlled by the filter list.
   * - Pass an object to apply it globally to all selection-filter columns.
   * - Pass a record keyed by column prop to override per column.
   */
  gridSettings?: SelectionGridSettings | Record<string, SelectionGridSettings>;
  /**
   * Optional context-aware option loading for selection filters.
   */
  cascadeOptions?: SelectionCascadeConfig;
};
```

---

### `FilterPopupHeaderConfig`

```ts
export type FilterPopupHeaderConfig = {
  /**
   * Hide the advanced filter popup header.
   */
  hidden?: boolean;
};
```

---

### `FIlTER_SELECTION`

Selection filter type

```ts
FIlTER_SELECTION: "none" | "empty" | "notEmpty" | "eq" | "notEq" | "begins" | "contains" | "notContains" | "eqN" | "neqN" | "gt" | "gte" | "lt" | "lte";
```

---

### `FIlTER_QUICK_SEARCH`

Quick search filter type

```ts
FIlTER_QUICK_SEARCH: "none" | "empty" | "notEmpty" | "eq" | "notEq" | "begins" | "contains" | "notContains" | "eqN" | "neqN" | "gt" | "gte" | "lt" | "lte";
```

---

### `FIlTER_SLIDER`

Slider filter type

```ts
FIlTER_SLIDER: "none" | "empty" | "notEmpty" | "eq" | "notEq" | "begins" | "contains" | "notContains" | "eqN" | "neqN" | "gt" | "gte" | "lt" | "lte";
```

---

### `FIlTER_EXPRESSION`

Hidden Pro expression filter type.

```ts
FIlTER_EXPRESSION: "none" | "empty" | "notEmpty" | "eq" | "notEq" | "begins" | "contains" | "notContains" | "eqN" | "neqN" | "gt" | "gte" | "lt" | "lte";
```

---

### `BEFORE_FILTER_OPTION_SOURCE_ROW_EVENT`

Cancelable event emitted before a row contributes selection options or slider bounds.

```ts
BEFORE_FILTER_OPTION_SOURCE_ROW_EVENT: string;
```

---

### `BEFORE_FILTER_OPTION_VALUE_EVENT`

Mutable value-resolution event emitted while advanced filter options are collected.

```ts
BEFORE_FILTER_OPTION_VALUE_EVENT: string;
```

---

### `BEFORE_QUICK_FILTER_APPLY_EVENT`

```ts
BEFORE_QUICK_FILTER_APPLY_EVENT: string;
```

---

### `AFTER_QUICK_FILTER_APPLY_EVENT`

```ts
AFTER_QUICK_FILTER_APPLY_EVENT: string;
```

---

### `FILTER_AST_CHANGE_EVENT`

```ts
FILTER_AST_CHANGE_EVENT: string;
```

---

### `FILTER_AST_ERROR_EVENT`

```ts
FILTER_AST_ERROR_EVENT: string;
```

---

### `QuickFilterApplyEventDetail`

```ts
interface QuickFilterApplyEventDetail {
  quickFilter?: QuickFilter;
  source: DataType[];
  columns: ColumnRegular[]
}
```

---

### `FilterOptionSourceRowEventDetail`

```ts
export type FilterOptionSourceRowEventDetail = {
  row: DataType;
};
```

---

### `FilterOptionValueEventDetail`

```ts
export type FilterOptionValueEventDetail = {
  row: DataType;
  column: ColumnRegular;
  rowType?: DimensionRows;
  rowIndex?: number;
  value: unknown;
};
```

---

### `ProFilterItemsChangeDetail`

```ts
export type ProFilterItemsChangeDetail = {
  prop: ColumnProp;
  multiFilterItems: MultiFilterItem;
};
```

---

### `ProFilterItemsChangeListener`

```ts
export type ProFilterItemsChangeListener = (detail: ProFilterItemsChangeDetail) => void;
```

---

### `ProFilterItemsChangeSubscription`

```ts
export type ProFilterItemsChangeSubscription = (
  listener: ProFilterItemsChangeListener,
) => () => void;
```

---

### `AdvancedFilterBadgesController`

```ts
class AdvancedFilterBadgesController {
  getItems(): readonly AdvancedFilterBadgeItem[];

  refresh();

  async clear();

  destroy();
}
```

---

### `filterBadgesCaption`

```ts
export function filterBadgesCaption(
  captions: FilterBadgesCaptions | undefined,
  id: FilterBadgesCaptionId,
): string;
```

---

### `filterBadgesMessage`

```ts
export function filterBadgesMessage(
  captions: FilterBadgesCaptions | undefined,
  id: FilterBadgesCaptionId,
  values: Readonly<Record<string, string | number>>,
): string;
```

---

### `FILTER_BADGES_LOCALIZATION`

Stable localization keys and English fallbacks for active-filter badges.

```ts
FILTER_BADGES_LOCALIZATION: Readonly<{ captions: Readonly<{ filterBadgesAriaLabel: "Active filters"; filterBadgesEmpty: "No active filters"; filterBadgesShowDetails: "Show details for {label}"; filterBadgesRemove: "Remove {label} filter"; filterBadgesRelationAnd: "AND"; filterBadgesRelationOr: "OR"; filterBadgesExcludedCount: "{count} excluded"; filterBadgesValueCountOne: "{count} value"; filterBadgesValueCountMany: "{count} values"; filterBadgesExcludedValues: "Excluded values: {values}"; filterBadgesValues: "Values: {values}"; filterBadgesNone: "None"; filterBadgesNotSet: "Not set"; filterBadgesYes: "Yes"; filterBadgesNo: "No"; filterBadgesItemCountOne: "{count} item"; filterBadgesItemCountMany: "{count} items"; filterBadgesConfigured: "Configured"; }>; }>;
```

---

### `FilterBadgesCaptionId`

```ts
export type FilterBadgesCaptionId = keyof typeof FILTER_BADGES_LOCALIZATION.captions;
```

---

### `FilterBadgesCaptions`

```ts
export type FilterBadgesCaptions = Partial<Record<FilterBadgesCaptionId, string>>;
```

---

### `AdvancedFilterBadgeRenderValue`

```ts
export type AdvancedFilterBadgeRenderValue = Node | string | number | null | undefined
  | readonly AdvancedFilterBadgeRenderValue[];
```

---

### `AdvancedFilterBadgeFormatContext`

```ts
interface AdvancedFilterBadgeFormatContext {
  prop: ColumnProp;
  filter: FilterData;
  index: number;
  column?: ColumnRegular;
  operatorName: string
}
```

---

### `AdvancedFilterBadgePresentation`

```ts
interface AdvancedFilterBadgePresentation {
  /** Compact value summary. The controller adds the column name. */
    summary: string;
  /** Complete plain-text explanation shown through the info control. */
    details?: string
}
```

---

### `AdvancedFilterBadgeItem` (Extended from `index.ts`)

```ts
interface AdvancedFilterBadgeItem {
  key: string;
  label: string;
  details?: string;
  remove: () => Promise<void>;
  readOnly: boolean
}
```

---

### `AdvancedFilterBadgeRenderContext`

```ts
interface AdvancedFilterBadgeRenderContext {
  item: AdvancedFilterBadgeItem;
  remove: () => Promise<void>
}
```

---

### `AdvancedFilterBadgesRenderContext`

```ts
interface AdvancedFilterBadgesRenderContext {
  items: readonly AdvancedFilterBadgeItem[];
  clear: () => Promise<void>;
  root: HTMLElement;
  readOnly: boolean
}
```

---

### `AdvancedFilterBadgesSlots`

```ts
interface AdvancedFilterBadgesSlots {
  /** Content rendered before the plugin-owned badge list. */
    start?: (context: AdvancedFilterBadgesRenderContext) => AdvancedFilterBadgeRenderValue;
  /** Content rendered after the plugin-owned badge list. */
    end?: (context: AdvancedFilterBadgesRenderContext) => AdvancedFilterBadgeRenderValue
}
```

---

### `AdvancedFilterBadgesOptions`

```ts
interface AdvancedFilterBadgesOptions {
  /** Extra class names added to the list root. */
    className?: string;
  /** Extra class names added to each default badge. */
    badgeClassName?: string;
  /** Extra class names added to each default remove button. */
    removeButtonClassName?: string;
  /** Extra class names added to the default empty state. */
    emptyClassName?: string;
  ariaLabel?: string;
  emptyLabel?: string;
  /** Localized default labels and message templates used by the built-in badge renderer. */
    captions?: FilterBadgesCaptions;
  removeAriaLabel?: (item: AdvancedFilterBadgeItem) => string;
  detailsAriaLabel?: (item: AdvancedFilterBadgeItem) => string;
  formatLabel?: (context: AdvancedFilterBadgeFormatContext) => string;
  formatDetails?: (context: AdvancedFilterBadgeFormatContext) => string | undefined;
  /** Rich content for the label shell. Strings are always appended as text. */
    renderBadge?: (context: AdvancedFilterBadgeRenderContext) => AdvancedFilterBadgeRenderValue;
  /** Replaces the default empty-state content. */
    renderEmpty?: (context: AdvancedFilterBadgesRenderContext) => AdvancedFilterBadgeRenderValue;
  /** Replaces the complete list rendering while retaining filter actions. */
    render?: (context: AdvancedFilterBadgesRenderContext) => AdvancedFilterBadgeRenderValue;
  /** Content slots around the plugin-owned badge list. */
    slots?: AdvancedFilterBadgesSlots;
  onChange?: (items: readonly AdvancedFilterBadgeItem[]) => void
}
```

---

### `AdvancedFilterBadgesConfig`

Enables the plugin-owned active-filter badge list.

```ts
/** Enables the plugin-owned active-filter badge list. */
export type AdvancedFilterBadgesConfig = boolean | AdvancedFilterBadgesOptions;
```

---

### `AdvancedFilterBadgesSource`

**@internal** Source adapter owned by AdvanceFilterPlugin.

```ts
interface AdvancedFilterBadgesSource {
  grid: HTMLRevoGridElement;
  getFilterItems: () => MultiFilterItem;
  getColumns: () => ColumnRegular[];
  getOperatorName: (filter: FilterData) => string;
  getPresentation?: (context: AdvancedFilterBadgeFormatContext) => AdvancedFilterBadgePresentation | undefined;
  isReadOnly?: () => boolean;
  applyFilterItems: (items: MultiFilterItem) => void | Promise<void>;
  subscribeFilterItemsChange: (listener: () => void) => () => void
}
```

---

### `filterCaption`

```ts
export function filterCaption(
  captions: FilterCaptionSource | undefined,
  id: FilterCaptionId,
): string;
```

---

### `filterMessage`

```ts
export function filterMessage(
  captions: FilterCaptionSource | undefined,
  id: FilterCaptionId,
  values: Readonly<Record<string, string | number>>,
): string;
```

---

### `FILTER_LOCALIZATION`

Stable localization keys and English fallbacks shared by filter surfaces.

```ts
FILTER_LOCALIZATION: Readonly<{ captions: Readonly<{ structuredFilterHeaderPlaceholder: "Choose…"; filterHeaderSearch: "Search…"; filterHeaderAnyDate: "Any date"; filterHeaderEither: "Either"; filterHeaderAnyItem: "Any item"; filterHeaderAnyValue: "Any value"; selectionAll: "All"; popupHeaderTitle: "Filter"; popupHeaderSeparator: "·"; popupHeaderActive: "Active"; popupHeaderClose: "Close filter"; popupConditionClear: "Clear {label}"; sliderTitle: "Select range"; 'filter.value.blank': "Blank"; 'filter.value.empty': "Empty"; 'filter.value.true': "True"; 'filter.value.false': "False"; 'filter.value.unsupported': "Unsupported value"; 'filter.value.more': "+{count} more"; }>; }>;
```

---

### `FilterCaptionId`

```ts
export type FilterCaptionId = keyof typeof FILTER_LOCALIZATION.captions;
```

---

### `expressionDiagnostic`

```ts
export function expressionDiagnostic(
  id: ExpressionDiagnosticId,
  values: Readonly<Record<string, string | number>> = {},
);
```

---

### `EXPRESSION_FILTER_LOCALIZATION`

Stable localization keys and English fallbacks for expression filtering.

```ts
EXPRESSION_FILTER_LOCALIZATION: Readonly<{ filterNames: Readonly<{ expression: "Expression"; }>; captions: Readonly<{ expressionButton: "Expression"; expressionTitle: "Filter expression"; expressionApply: "Apply"; expressionErrorTooltip: "Expression error details"; expressionValid: "Parsed"; expressionSuggestions: "Expression suggestions"; expressionPlaceholder: string; }>; diagnostics: Readonly<{ unexpectedToken: "Unexpected token \"{token}\"."; expectedClosingParenthesis: "Expected closing parenthesis."; expectedFilterOperator: "Expected a filter operator."; expectedFilterValue: "Expected a filter value."; expectedBetweenAnd: "Expected \"and\" in a between expression."; expectedUpperBound: "Expected the upper bound value."; expectedStructuredPayload: "Expected a structured filter payload."; expectedStructuredField: "Expected a structured value field."; expectedColonAfterField: "Expected \":\" after \"{field}\"."; expectedStructuredFieldValue: "Expected a value for \"{field}\"."; expectedStructuredClosingBrace: "Expected closing brace for structured value."; expectedArrayValue: "Expected an array value."; expectedStructuredClosingBracket: "Expected closing bracket for structured value."; expectedListValue: "Expected a list value."; expectedValueListClosingParenthesis: "Expected closing parenthesis for value list."; unclosedString: "Unclosed string literal."; unexpectedCharacter: "Unexpected character \"{character}\"."; invalidStructuredExpression: "Invalid structured filter expression."; invalidStructuredPayload: "Invalid structured filter payload."; unavailableSelectionValue: "Expression contains a selection value that is not available for this column."; currentColumnOnly: "Expression can only reference the current column \"{column}\"."; unsupportedOperator: "Unsupported expression operator \"{operator}\"."; numericUnavailable: "Numeric operators are not available for this column."; dateUnavailable: "Date operators are not available for this column."; betweenUnavailable: "Between expressions require number, slider, or date filters for this column."; selectionUnavailable: "Selection operators require the selection filter for this column."; arrayUnavailable: "Array operators require the array filter for this column."; unknownColumn: "Unknown column reference \"{column}\"."; ambiguousColumn: "Column reference \"{column}\" matches more than one column. Use its property instead."; unknownFunction: "Unsupported expression function \"{function}\"."; expectedFunctionColumn: "Function \"{function}\" expects one column reference."; expectedFunctionClosingParenthesis: "Expected closing parenthesis after function \"{function}\"."; aggregateUnavailable: "Function \"{function}\" cannot be evaluated because column data is unavailable."; }>; }>;
```

---

### `ExpressionDiagnosticId`

```ts
export type ExpressionDiagnosticId = keyof typeof EXPRESSION_FILTER_LOCALIZATION.diagnostics;
```

---

### `selectionFilterCaption`

```ts
export function selectionFilterCaption(
  captions: SelectionCaptions | undefined,
  id: SelectionFilterCaptionId,
): string;
```

---

### `SELECTION_FILTER_LOCALIZATION`

Stable localization keys and English fallbacks for selection filters.

```ts
SELECTION_FILTER_LOCALIZATION: Readonly<{ captions: Readonly<{ selectionApply: "Apply"; selectionCancel: "Cancel"; selectionSelectAll: "(Select All)"; selectionSelectAllSearchResults: "(Select All Search Results)"; selectionAddCurrentSelection: "Add current selection to filter"; selectionInvertVisible: "Invert visible"; selectionInvertVisibleAria: "Invert the visible values"; selectionBlanks: "(Blanks)"; selectionEmpty: "Empty"; selectionSearchPlaceholder: "Search..."; selectionSearchAria: "Search values"; selectionSelectAllAria: "Select all values"; }>; }>;
```

---

### `SelectionFilterCaptionId`

```ts
export type SelectionFilterCaptionId = keyof typeof SELECTION_FILTER_LOCALIZATION.captions;
```

---

### `TEMPORAL_FILTER_LOCALIZATION`

Stable English filter-name fallbacks for date and datetime operators.

```ts
TEMPORAL_FILTER_LOCALIZATION: Readonly<{ filterNames: Readonly<{ equals: "Equals"; before: "Before"; after: "After"; onOrBefore: "On or before"; onOrAfter: "On or after"; between: "Between"; notEqual: "Not equal"; isEmpty: "Is blank"; isNotEmpty: "Is not blank"; today: "Today"; yesterday: "Yesterday"; last7Days: "Last 7 days"; next30Days: "Next 30 days"; thisWeek: "This week"; lastWeek: "Last week"; nextWeek: "Next week"; thisMonth: "This month"; lastMonth: "Last month"; thisQuarter: "This quarter"; nextQuarter: "Next quarter"; previousQuarter: "Previous quarter"; thisYear: "This year"; nextYear: "Next year"; previousYear: "Previous year"; thisFiscalQuarter: "This fiscal quarter"; nextFiscalQuarter: "Next fiscal quarter"; previousFiscalQuarter: "Previous fiscal quarter"; thisFiscalYear: "This fiscal year"; nextFiscalYear: "Next fiscal year"; previousFiscalYear: "Previous fiscal year"; }>; captions: Readonly<{ rangeFrom: "From"; rangeTo: "To"; }>; }>;
```

---

### `TemporalFilterNameId`

```ts
export type TemporalFilterNameId = keyof typeof TEMPORAL_FILTER_LOCALIZATION.filterNames;
```

---

### `normalizeQuickFilterText`

```ts
export function normalizeQuickFilterText(text: unknown): string;
```

---

### `normalizeQuickFilterInput`

```ts
export function normalizeQuickFilterInput(
  input?: QuickFilterInput,
): NormalizedQuickFilterInput;
```

---

### `isSameQuickFilterInput`

```ts
export function isSameQuickFilterInput(
  previous: NormalizedQuickFilterInput,
  next: NormalizedQuickFilterInput,
);
```

---

### `normalizeQuickFilterValue`

```ts
export function normalizeQuickFilterValue(value: unknown): string;
```

---

### `quickFilterToFilterAst`

Compile global search into ANDed tokens containing per-field OR conditions.

```ts
export function quickFilterToFilterAst(
  quickFilter: QuickFilter | undefined,
  columns: QuickFilterColumn[],
): FilterAst | undefined;
```

---

### `rowMatchesQuickFilter`

```ts
export function rowMatchesQuickFilter(
  row: DataType,
  quickFilter: QuickFilter,
  columns: QuickFilterColumn[],
): boolean;
```

---

### `DEFAULT_QUICK_FILTER_DEBOUNCE_MS`

```ts
DEFAULT_QUICK_FILTER_DEBOUNCE_MS: 150;
```

---

### `QuickFilterInput`

```ts
export type QuickFilterInput =
  | string
  | {
      text: string;
      columns?: ColumnProp[];
      debounceMs?: number;
    };
```

---

### `QuickFilter`

Normalized, transport-safe quick-filter payload.

```ts
interface QuickFilter {
  text: string;
  columns?: ColumnProp[]
}
```

---

### `NormalizedQuickFilterInput`

```ts
interface NormalizedQuickFilterInput {
  quickFilter?: QuickFilter;
  debounceMs: number
}
```

---

### `QuickFilterColumn`

```ts
interface QuickFilterColumn {
  prop: ColumnProp;
  column?: ColumnRegular;
  getValue?: (row: DataType) => unknown
}
```

---

### `FilterAstPrimitive`

```ts
export type FilterAstPrimitive = string | number | boolean | null;
```

---

### `FilterAstValue`

```ts
export type FilterAstValue = FilterAstPrimitive | FilterAstValue[] | { [key: string]: FilterAstValue };
```

---

### `FilterAstValueType`

```ts
export type FilterAstValueType =
  | 'string'
  | 'number'
  | 'boolean'
  | 'date'
  | 'datetime'
  | 'array'
  | 'unknown';
```

---

### `FilterAstGroupOperator`

```ts
export type FilterAstGroupOperator = 'and' | 'or';
```

---

### `FilterAstEvaluationMode`

```ts
export type FilterAstEvaluationMode =
  | 'selectionExclusion'
  | 'selectionMembership'
  | 'dateObject'
  | 'coercedNumericRange'
  | 'localTemporal';
```

---

### `FilterAstCondition`

```ts
interface FilterAstCondition {
  type: 'condition';
  field: ColumnProp;
  operator: FilterAstOperator;
  valueType: FilterAstValueType;
  value?: FilterAstValue;
  /** Optional evaluator behavior required by the condition's input representation. */
    evaluationMode?: FilterAstEvaluationMode
}
```

---

### `FilterAstGroup`

```ts
interface FilterAstGroup {
  type: 'group';
  operator: FilterAstGroupOperator;
  children: FilterAst[]
}
```

---

### `FilterAstNot`

```ts
interface FilterAstNot {
  type: 'not';
  child: FilterAst
}
```

---

### `FilterAst`

```ts
export type FilterAst = FilterAstCondition | FilterAstGroup | FilterAstNot;
```

---

### `FilterAstOperator`

```ts
export type FilterAstOperator =
  | 'equal'
  | 'notEqual'
  | 'beginsWith'
  | 'contains'
  | 'quickContains'
  | 'notContains'
  | 'greaterThan'
  | 'greaterThanOrEqual'
  | 'lessThan'
  | 'lessThanOrEqual'
  | 'between'
  | 'in'
  | 'notIn'
  | 'isBlank'
  | 'isNotBlank'
  | 'isTrue'
  | 'isFalse'
  | 'isEmptyArray'
  | 'isNotEmptyArray'
  | 'dateEquals'
  | 'dateBefore'
  | 'dateAfter'
  | 'dateOnOrBefore'
  | 'dateOnOrAfter'
  | 'dateBetween'
  | 'dateNotEqual'
  | 'today'
  | 'yesterday'
  | 'last7Days'
  | 'next30Days'
  | 'thisWeek'
  | 'lastWeek'
  | 'nextWeek'
  | 'thisMonth'
  | 'lastMonth'
  | 'thisQuarter'
  | 'nextQuarter'
  | 'previousQuarter'
  | 'thisYear'
  | 'nextYear'
  | 'previousYear'
  | 'thisFiscalQuarter'
  | 'nextFiscalQuarter'
  | 'previousFiscalQuarter'
  | 'thisFiscalYear'
  | 'nextFiscalYear'
  | 'previousFiscalYear'
  | (string & {});
```

---

### `FilterExecutionContext`

```ts
interface FilterExecutionContext {
  /** One instant captured for the entire apply operation. */
    now: string;
  /** Default IANA timezone used by relative-date adapters. */
    timeZone: string;
  /** Effective JSON-safe blank policy by column property for remote evaluators. */
    blankSemantics?: Record<string, {
      null: boolean;
      undefined: boolean;
      emptyString: boolean;
      whitespaceOnlyString: boolean;
      emptyArray: boolean;
      missingProperty: boolean;
      /** True when the application also uses a non-serializable `isBlank` callback. */
      customEvaluator: boolean;
    }>
}
```

---

### `FilterAstOrigin`

```ts
export type FilterAstOrigin = 'config' | 'api' | 'ui' | 'quickFilter' | 'clear';
```

---

### `FilterAstDiagnostic`

```ts
interface FilterAstDiagnostic {
  code: string;
  message: string;
  path: string
}
```

---

### `FilterAstChangeEventDetail`

```ts
interface FilterAstChangeEventDetail {
  filterAst?: FilterAst;
  executionContext: FilterExecutionContext;
  origin: FilterAstOrigin;
  projectable: boolean
}
```

---

### `FilterAstErrorEventDetail`

```ts
interface FilterAstErrorEventDetail {
  attemptedAst?: unknown;
  diagnostics: FilterAstDiagnostic[];
  origin: FilterAstOrigin
}
```

---

### `FilterAstCustomEvaluators`

```ts
export type FilterAstCustomEvaluators = Record<string, LogicFunction>;
```

---

### `CANONICAL_FILTER_OPERATORS`

```ts
CANONICAL_FILTER_OPERATORS: Set<FilterAstOperator>;
```

---

### `VALUELESS_FILTER_AST_OPERATORS`

```ts
VALUELESS_FILTER_AST_OPERATORS: Set<FilterAstOperator>;
```

---

### `ARRAY_VALUE_FILTER_AST_OPERATORS`

```ts
ARRAY_VALUE_FILTER_AST_OPERATORS: Set<FilterAstOperator>;
```

---

### `FILTER_TYPE_TO_AST_OPERATOR`

```ts
FILTER_TYPE_TO_AST_OPERATOR: {
  eq: string;
  eqN: string;
  is: string;
  notEq: string;
  neqN: string;
  begins: string;
  contains: string;
  notContains: string;
  gt: string;
  gte: string;
  lt: string;
  lte: string;
  empty: string;
  isEmpty: string;
  notEmpty: string;
  isNotEmpty: string;
  isTrue: string;
  isFalse: string;
  isEmptyArray: string;
  isNotEmptyArray: string;
  equals: string;
  before: string;
  after: string;
  onOrBefore: string;
  onOrAfter: string;
  notEqual: string;
  today: string;
  yesterday: string;
  last7Days: string;
  next30Days: string;
  thisWeek: string;
  lastWeek: string;
  nextWeek: string;
  thisMonth: string;
  lastMonth: string;
  thisQuarter: string;
  nextQuarter: string;
  previousQuarter: string;
  thisYear: string;
  nextYear: string;
  previousYear: string;
  thisFiscalQuarter: string;
  nextFiscalQuarter: string;
  previousFiscalQuarter: string;
  thisFiscalYear: string;
  nextFiscalYear: string;
  previousFiscalYear: string;
};
```

---

### `AST_TO_FILTER_TYPE`

```ts
AST_TO_FILTER_TYPE: {
  equal: string;
  notEqual: string;
  beginsWith: string;
  contains: string;
  notContains: string;
  greaterThan: string;
  greaterThanOrEqual: string;
  lessThan: string;
  lessThanOrEqual: string;
  isBlank: string;
  isNotBlank: string;
  isTrue: string;
  isFalse: string;
  isEmptyArray: string;
  isNotEmptyArray: string;
  dateEquals: string;
  dateBefore: string;
  dateAfter: string;
  dateOnOrBefore: string;
  dateOnOrAfter: string;
  dateNotEqual: string;
  today: string;
  yesterday: string;
  last7Days: string;
  next30Days: string;
  thisWeek: string;
  lastWeek: string;
  nextWeek: string;
  thisMonth: string;
  lastMonth: string;
  thisQuarter: string;
  nextQuarter: string;
  previousQuarter: string;
  thisYear: string;
  nextYear: string;
  previousYear: string;
  thisFiscalQuarter: string;
  nextFiscalQuarter: string;
  previousFiscalQuarter: string;
  thisFiscalYear: string;
  nextFiscalYear: string;
  previousFiscalYear: string;
};
```

---

### `validateFilterAst`

```ts
export function validateFilterAst(
  ast: unknown,
  customEvaluators: FilterAstCustomEvaluators = {},
): FilterAstValidationResult;
```

---

### `cloneFilterAst`

```ts
export function cloneFilterAst(ast?: FilterAst): FilterAst | undefined;
```

---

### `normalizeFilterAstValue`

```ts
export function normalizeFilterAstValue(value: unknown, ancestors = new Set<object>()): FilterAstValue | undefined;
```

---

### `FilterAstValidationResult`

```ts
interface FilterAstValidationResult {
  valid: boolean;
  diagnostics: FilterAstDiagnostic[]
}
```

---

### `filterAstDiagnostic`

```ts
export function filterAstDiagnostic(
  id: FilterAstDiagnosticId,
  values: Readonly<Record<string, string | number>> = {},
);
```

---

### `FILTER_AST_LOCALIZATION`

Stable English fallbacks for canonical filter-AST validation diagnostics.

```ts
FILTER_AST_LOCALIZATION: Readonly<{ diagnostics: Readonly<{ invalidNode: "Filter AST nodes must be objects."; maxDepth: "Filter AST nesting cannot exceed 100 levels."; cycle: "Filter AST must not contain cycles."; invalidGroupOperator: "Group operator must be \"and\" or \"or\"."; emptyGroup: "Filter groups must contain at least one child."; missingChild: "Not nodes require exactly one child."; invalidDiscriminator: "Node type must be \"condition\", \"group\", or \"not\"."; invalidField: "Condition field must be a ColumnProp string or number."; invalidOperator: "Condition operator must be a non-empty string."; unknownOperator: "Unknown filter operator \"{operator}\"."; invalidValueType: "Condition valueType is not recognized."; unexpectedValue: "Operator \"{operator}\" does not accept a value."; missingValue: "Operator \"{operator}\" requires a value."; invalidArrayValue: "Operator \"{operator}\" requires {requirement}."; valueTypeMismatch: "Condition value does not match valueType \"{valueType}\"."; nonFiniteNumber: "AST numbers must be finite."; nonJsonValue: "AST values must be JSON-safe."; valueCycle: "AST values must not contain cycles."; nonPlainObject: "AST object values must be plain JSON objects."; }>; }>;
```

---

### `FilterAstDiagnosticId`

```ts
export type FilterAstDiagnosticId = keyof typeof FILTER_AST_LOCALIZATION.diagnostics;
```

---

### `multiFilterItemsToFilterAst`

```ts
export function multiFilterItemsToFilterAst(
  filterItems: MultiFilterItem,
  columns: ColumnRegular[] = [],
): FilterAst | undefined;
```

---

### `expressionAstToFilterAst`

```ts
export function expressionAstToFilterAst(
  ast: ExpressionAst,
  currentField: ColumnProp,
  column?: ColumnRegular,
  columns: ColumnRegular[] = column ? [column] : [],
): FilterAst;
```

---

### `filterTypeToAstOperator`

```ts
export function filterTypeToAstOperator(
  type: string,
  valueType: FilterAstValueType = 'unknown',
): FilterAstOperator;
```

---

### `inferFilterAstValueType`

```ts
export function inferFilterAstValueType(
  column: ColumnRegular | undefined,
  operator: string,
  value: unknown,
): FilterAstValueType;
```

---

### `projectFilterAstToMultiFilterItems`

```ts
export function projectFilterAstToMultiFilterItems(
  ast?: FilterAst,
  customOperators: ReadonlySet<string> = new Set(),
): FilterAstProjection;
```

---

### `collectFilterAstFields`

```ts
export function collectFilterAstFields(ast?: FilterAst, fields = new Set<string>()): Set<string>;
```

---

### `omitFilterAstField`

Removes one field's conditions while preserving the remaining boolean tree.

```ts
export function omitFilterAstField(ast: FilterAst | undefined, field: ColumnProp): FilterAst | undefined;
```

---

### `filterAstToBadgeItems`

Read-only flattened model used only to keep application badges visible for arbitrary trees.

```ts
export function filterAstToBadgeItems(ast?: FilterAst): MultiFilterItem;
```

---

### `combineFilterAsts`

```ts
export function combineFilterAsts(operator: 'and' | 'or', asts: (FilterAst | undefined)[]): FilterAst | undefined;
```

---

### `FilterAstProjection`

```ts
interface FilterAstProjection {
  projectable: boolean;
  multiFilterItems: MultiFilterItem;
  fields: Set<string>
}
```

---

### `compileFilterAst`

```ts
export function compileFilterAst(ast: FilterAst, options: CompileFilterAstOptions): CompiledFilterAst;
```

---

### `CompileFilterAstOptions`

```ts
interface CompileFilterAstOptions {
  columns: ColumnRegular[];
  operators: Record<string, LogicFunction>;
  customEvaluators?: FilterAstCustomEvaluators;
  blankSemantics?: BlankSemantics;
  getQuickFilterValue?: (row: DataType, column: ColumnRegular) => unknown
}
```

---

### `CompiledFilterAst`

```ts
interface CompiledFilterAst {
  matches(row: DataType): boolean
}
```

---

### `StructuredFilterAggregateScope`

```ts
export type StructuredFilterAggregateScope = 'all' | 'visible';
```

---

### `StructuredFilterAggregateNeed`

```ts
export type StructuredFilterAggregateNeed = 'values' | 'uniqueValues' | 'valueCounts' | 'numericRange';
```

---

### `StructuredFilterValueCount`

```ts
interface StructuredFilterValueCount {
  readonly value: unknown;
  readonly count: number
}
```

---

### `StructuredFilterNumericRange`

```ts
interface StructuredFilterNumericRange {
  readonly values: readonly number[];
  readonly count: number;
  readonly min?: number;
  readonly max?: number
}
```

---

### `StructuredFilterAggregateResultMap`

```ts
interface StructuredFilterAggregateResultMap {
  values: readonly unknown[];
  uniqueValues: readonly unknown[];
  valueCounts: readonly StructuredFilterValueCount[];
  numericRange: StructuredFilterNumericRange
}
```

---

### `StructuredFilterAggregateProviderRequest`

```ts
interface StructuredFilterAggregateProviderRequest {
  readonly typeId: string;
  readonly column: ColumnRegular;
  readonly need: StructuredFilterAggregateNeed;
  readonly scope: StructuredFilterAggregateScope
}
```

---

### `StructuredFilterAggregateProvider`

Supplies complete, server-produced aggregate data for remote or partially loaded grids.
Return `undefined` to use the provider-backed local-row fallback for that request.
Keep results immutable for the lifetime of the open popup.

```ts
interface StructuredFilterAggregateProvider {
  /** Prevent page-local fallback when this provider represents a partial remote row source. */
    readonly complete?: boolean;
  get(
      request: StructuredFilterAggregateProviderRequest,
    ): StructuredFilterAggregateResultMap[StructuredFilterAggregateNeed] | undefined;
  /** Optional compact, type-specific model (for example server-binned histogram data). */
    getPrepared?(request: {
      readonly typeId: string;
      readonly column: ColumnRegular;
    }): unknown
}
```

---

### `StructuredFilterAggregateAccess`

```ts
interface StructuredFilterAggregateAccess {
  get<K extends StructuredFilterAggregateNeed>(
      need: K,
      scope?: StructuredFilterAggregateScope,
    ): StructuredFilterAggregateResultMap[K]
}
```

---

### `StructuredFilterLabels`

```ts
interface StructuredFilterLabels {
  operator(operatorId: string): string;
  caption(captionId: string, fallback: string): string
}
```

---

### `StructuredFilterConditionPresentation`

Text-only condition presentation used by compact, non-editor surfaces.

```ts
interface StructuredFilterConditionPresentation {
  /** Short value summary; the consuming surface adds the column name. */
    readonly summary: string;
  /** Optional value-first summary used by the grouped editor's full-width cell. */
    readonly groupedSummary?: string;
  /** Optional complete human-readable explanation exposed by an info control. */
    readonly details?: string
}
```

---

### `StructuredFilterPresentationContext`

```ts
interface StructuredFilterPresentationContext {
  readonly condition: Readonly<StructuredFilterOwnedCondition>;
  readonly column: ColumnRegular;
  readonly config?: ColumnFilterConfig;
  readonly labels: StructuredFilterLabels;
  readonly dateSettings?: ResolvedDateFilterSettings
}
```

---

### `StructuredFilterHeaderPlaceholderContext`

```ts
export type StructuredFilterHeaderPlaceholderContext = Omit<
  StructuredFilterPresentationContext,
  'condition'
>;
```

---

### `StructuredFilterHeaderSelection`

Optional finite-selection metadata consumed by the shared filter-header ratio badge.

```ts
interface StructuredFilterHeaderSelection {
  readonly values: readonly FilterHeaderTemplateValue[];
  readonly totalCount: number
}
```

---

### `StructuredFilterHeaderSelectionContext` (Extended from `index.ts`)

```ts
interface StructuredFilterHeaderSelectionContext {
  /** Aggregate access is present when the type declares aggregate needs. */
    readonly aggregates?: StructuredFilterAggregateAccess
}
```

---

### `StructuredFilterOwnedCondition` (Extended from `index.ts`)

```ts
export type StructuredFilterOwnedCondition = Omit<FilterData, 'type'> & { type: string };
```

---

### `StructuredFilterCondition` (Extended from `index.ts`)

```ts
export type StructuredFilterCondition = Omit<StructuredFilterOwnedCondition, 'id'> & {
  id?: FilterData['id'];
};
```

---

### `StructuredFilterBodyContext`

```ts
interface StructuredFilterBodyContext {
  readonly h: HyperFunc<VNode>;
  readonly typeId: string;
  readonly column: ColumnRegular;
  /** Current filter configuration for structured types with per-column options. */
    readonly config?: ColumnFilterConfig;
  readonly conditions: readonly Readonly<StructuredFilterOwnedCondition>[];
  readonly labels: StructuredFilterLabels;
  /** Resolved per-column temporal settings for date-aware bodies. */
    readonly dateSettings?: ResolvedDateFilterSettings;
  /** Civil date resolved from this run's captured instant in this column's timezone. */
    readonly dateReferenceDate?: ISODateString;
  /** Resolves the same captured instant in a structured editor's own timezone override. */
    readonly dateReferenceDateForTimeZone?: (timeZone: string) => ISODateString;
  readonly aggregates?: StructuredFilterAggregateAccess;
  /** Compact editor-ready data supplied by a remote aggregate provider. */
    readonly preparedData?: unknown;
  replaceConditions(conditions: readonly StructuredFilterCondition[]): Promise<void>;
  commit(conditions: readonly StructuredFilterCondition[]): Promise<void>
}
```

---

### `StructuredFilterType`

```ts
interface StructuredFilterType {
  /** Stable id selected through a column's existing `filter` field. */
    readonly id: string;
  /** Ordinary operator ids this body may emit and owns. */
    readonly operatorIds: readonly string[];
  /** Canonical predicate intent used by compact grouped-editor labels. Transport ids stay unchanged. */
    readonly groupedOperatorSemantics?: Readonly<Record<string, FilterAstOperator>>;
  /** Close the grouped value popover after this type commits a complete pick. */
    readonly groupedEditorCloseOnCommit?: boolean;
  /** Provider-backed projections made available lazily to the body. */
    readonly aggregateNeeds?: readonly StructuredFilterAggregateNeed[];
  /** Validates a canonical condition operand before it can replace active state. */
    readonly validateValue?: (value: unknown, operatorId: string) => boolean;
  /** Mounts the same interactive body in alternate grid-owned surfaces. */
    readonly mount?: (host: HTMLElement, context: StructuredFilterBodyContext) => void | (() => void);
  /** Popup body renderer; popup chrome and lifecycle remain grid-owned. */
    readonly render: (context: StructuredFilterBodyContext) => VNode | VNode[] | null | undefined;
  /**
     * Resolves this type's default filter-header control. Static popup visuals can
     * be declared directly; interactive controls can use the body context to
     * inspect aggregates and replace their owned conditions.
     */
    readonly headerControl?: FilterHeaderControl | (
      (context: StructuredFilterBodyContext) => FilterHeaderControl | undefined
    );
  /** Short inactive text for compact filter headers. The column title is already shown above it. */
    readonly headerPlaceholder?: string | ((
      context: StructuredFilterHeaderPlaceholderContext
    ) => string);
  /** Describes the type-owned value without leaking its transport representation. */
    readonly describeCondition?: (
      context: StructuredFilterPresentationContext,
    ) => StructuredFilterConditionPresentation | undefined;
  /** Describes a finite selection without coupling the header to one structured filter type. */
    readonly getHeaderSelection?: (
      context: StructuredFilterHeaderSelectionContext,
    ) => StructuredFilterHeaderSelection | undefined
}
```

---

### `StructuredFilterTypeRegistry`

```ts
class StructuredFilterTypeRegistry {
  register(type: StructuredFilterType);

  unregister(id: string);

  get(id: string);

  getByOperator(operatorId: string);

  values();

  clear();

  resolve(filter?: boolean | string | string[]);
}
```

---

### `replaceStructuredFilterConditions`

```ts
export function replaceStructuredFilterConditions(
  items: MultiFilterItem,
  prop: ColumnProp,
  operatorIds: readonly string[],
  replacements: readonly StructuredFilterCondition[],
);
```

---

### `createStructuredFilterAggregateAccess`

Creates one lazy value/aggregate cache for one popup body render.

```ts
export function createStructuredFilterAggregateAccess({
  typeId,
  column,
  dataStores,
  sourceRowTypes,
  needs,
  isSourceRow,
  getValue,
  isVisibleRow,
  provider,
  sourceValueCache,
}: StructuredFilterAggregateOptions): StructuredFilterAggregateAccess;
```

---

### `StructuredFilterAggregateOptions`

```ts
interface StructuredFilterAggregateOptions {
  readonly typeId: string;
  readonly column: ColumnRegular;
  readonly dataStores: RowDataSources;
  /** Row stores allowed to contribute local values. Undefined preserves all-store behavior. */
    readonly sourceRowTypes?: readonly DimensionRows[];
  readonly needs: readonly StructuredFilterAggregateNeed[];
  readonly isSourceRow: (row?: DataType) => boolean;
  readonly getValue: (
      row: DataType,
      column: ColumnRegular,
      rowType?: DimensionRows,
      rowIndex?: number,
    ) => unknown;
  /** Local visible-scope predicate with the current aggregate column excluded. */
    readonly isVisibleRow?: (
      row: DataType,
      rowType: DimensionRows,
      rowIndex: number,
    ) => boolean;
  readonly provider?: StructuredFilterAggregateProvider;
  /** Popup-scoped raw values shared by aggregate families for the same column and scope. */
    readonly sourceValueCache?: Map<string, readonly unknown[]>
}
```

---

### `structuredFilterSection`

```ts
export function structuredFilterSection(title: string, content: VNode | VNode[], description?: string);
```

---

### `structuredFilterLabel`

```ts
export function structuredFilterLabel(text: string, control: VNode);
```

---

### `structuredFilterTextInput`

```ts
export function structuredFilterTextInput(options: {
  value?: string;
  placeholder?: string;
  ariaLabel: string;
  invalid?: boolean;
  onInput(value: string, event: InputEvent): void;
});
```

---

### `structuredFilterButton`

```ts
export function structuredFilterButton(options: {
  label: string;
  pressed?: boolean;
  disabled?: boolean;
  onClick(event: MouseEvent): void;
});
```

---

### `structuredFilterInlineError`

```ts
export function structuredFilterInlineError(message: string);
```

---

### `createStructuredFilterBodyContext`

Builds the operator-owned runtime shared by the regular and grouped filter surfaces.

```ts
export function createStructuredFilterBodyContext({
  type,
  column,
  conditions,
  options,
  replace,
  commit = replace,
}: {
  type: StructuredFilterType;
  column: import('@revolist/revogrid').ColumnRegular;
  conditions: readonly Readonly<StructuredFilterOwnedCondition>[];
  options: StructuredFilterContextOptions;
  replace(conditions: readonly StructuredFilterCondition[]): Promise<void>;
  commit?(conditions: readonly StructuredFilterCondition[]): Promise<void>;
}): StructuredFilterBodyContext;
```

---

### `renderStructuredFilterBodies`

```ts
export function renderStructuredFilterBodies(
  data: ShowData,
  types: readonly StructuredFilterType[],
  options: StructuredFilterContextOptions & {
    multiFilterItems: MultiFilterItem;
    config?: ColumnFilterConfig;
    filterNames: Readonly<Record<string, string>>;
    dataStores: RowDataSources;
    isSourceRow: StructuredFilterAggregateOptions['isSourceRow'];
    getValue: StructuredFilterAggregateOptions['getValue'];
    dateReferenceDate?: import('../../dates').ISODateString;
    change(filterItems: MultiFilterItem, changedProp?: ColumnProp): Promise<void>;
    onFilterItemsChange: ProFilterItemsChangeListener;
  },
);
```

---

### `StructuredFilterContextOptions`

```ts
interface StructuredFilterContextOptions {
  config?: ColumnFilterConfig;
  filterNames: Readonly<Record<string, string>>;
  dataStores: RowDataSources;
  sourceRowTypes?: readonly DimensionRows[];
  isSourceRow: StructuredFilterAggregateOptions['isSourceRow'];
  getValue: StructuredFilterAggregateOptions['getValue'];
  isVisibleRow?: StructuredFilterAggregateOptions['isVisibleRow'];
  dateReferenceDate?: import('../../dates').ISODateString;
  dateReferenceDateForTimeZone?: (timeZone: string) => import('../../dates').ISODateString;
  /** Shared for the lifetime of one popup so sibling rules reuse one aggregate pass. */
    runtimeCache?: Map<string, StructuredFilterRuntimeSnapshot>;
  /** Shared raw values so sibling aggregate families do not rescan one column. */
    sourceValueCache?: Map<string, readonly unknown[]>
}
```

---

### `structuredFilterMessage`

Resolves a localized caption and replaces its named, text-only placeholders.

```ts
export function structuredFilterMessage(
  labels: StructuredFilterLabels,
  id: string,
  fallback: string,
  values: StructuredFilterMessageValues = {},
);
```

---

### `formatStructuredScalar`

Human-readable scalar formatting shared by compact filter surfaces.

```ts
export function formatStructuredScalar(
  value: unknown,
  labels: StructuredFilterLabels,
);
```

---

### `summarizeStructuredValues`

Bounded summary for list-valued conditions; complete values remain in details.

```ts
export function summarizeStructuredValues(
  values: readonly unknown[],
  labels: StructuredFilterLabels,
  limit = 3,
);
```

---

### `StructuredFilterMessageValues`

```ts
export type StructuredFilterMessageValues = Readonly<Record<string, string | number>>;
```

---

### `resolveStructuredFilterHeader`

Derives the compact structured-filter header without depending on plugin lifecycle state.

```ts
export function resolveStructuredFilterHeader({
  column,
  types,
  filterAstProjectable,
  multiFilterItems,
  effectiveFilterAst,
  filterNames,
  config,
  getAggregates,
}: ResolveStructuredFilterHeaderOptions): ResolvedStructuredFilterHeader | undefined;
```

---

### `ResolveStructuredFilterHeaderOptions`

```ts
interface ResolveStructuredFilterHeaderOptions {
  readonly column: ColumnRegular;
  readonly types: readonly StructuredFilterType[];
  readonly filterAstProjectable: boolean;
  readonly multiFilterItems: MultiFilterItem;
  readonly effectiveFilterAst?: FilterAst;
  readonly filterNames: Readonly<Record<string, string>>;
  readonly config?: ColumnFilterConfig;
  readonly getAggregates: (
      type: StructuredFilterType,
      column: ColumnRegular,
    ) => StructuredFilterAggregateAccess | undefined
}
```

---

### `ResolvedStructuredFilterHeader`

```ts
interface ResolvedStructuredFilterHeader {
  readonly type: StructuredFilterType;
  readonly homogeneous: boolean;
  readonly conditions: readonly Readonly<FilterData>[];
  readonly presentation: FilterHeaderPresentation;
  readonly selection?: ReturnType<NonNullable<StructuredFilterType['getHeaderSelection']>>
}
```

---

### `resolveStructuredFilterHeaderPlaceholder`

Resolves concise inactive copy while leaving complete column context to accessible labels.

```ts
export function resolveStructuredFilterHeaderPlaceholder(
  type: StructuredFilterType,
  context: StructuredFilterHeaderPlaceholderContext,
): string;
```

---

### `createStructuredAggregateVisibleRowPredicate`

Builds the lazy local-row predicate used by visible-scope structured aggregates.
The aggregate's own column is omitted while trim layers owned by other plugins remain respected.

```ts
export function createStructuredAggregateVisibleRowPredicate({
  columnProp,
  ast,
  dataStores,
  columns,
  operators,
  customEvaluators,
  blankSemantics,
  getQuickFilterValue,
}: StructuredAggregateVisibilityOptions): NonNullable<StructuredFilterAggregateOptions['isVisibleRow']>;
```

---

### `StructuredAggregateVisibilityOptions` (Extended from `index.ts`)

```ts
interface StructuredAggregateVisibilityOptions {
  readonly columnProp: ColumnProp;
  readonly ast?: FilterAst;
  readonly dataStores: RowDataSources
}
```

---

### `fuzzyStructuredFilterType`

```ts
fuzzyStructuredFilterType: {
  id: string;
  operatorIds: string[];
  aggregateNeeds: "uniqueValues"[];
  describeCondition: ({ condition, labels }: StructuredFilterPresentationContext) => { summary: string; details: string; } | undefined;
  mount: (host: HTMLElement, context: StructuredFilterBodyContext) => PreactRootDisposer;
  render: (context: StructuredFilterBodyContext) => any;
};
```

---

### `clampFuzzyThreshold`

```ts
export function clampFuzzyThreshold(value: unknown);
```

---

### `normalizeFuzzyFilterValue`

```ts
export function normalizeFuzzyFilterValue(value: unknown): FuzzyFilterValue;
```

---

### `fuzzyCondition`

```ts
export function fuzzyCondition(value: FuzzyFilterValue): StructuredFilterCondition[];
```

---

### `fuzzyStateFromConditions`

```ts
export function fuzzyStateFromConditions(
  conditions: readonly Readonly<{ type: string; value?: unknown }>[],
);
```

---

### `fuzzyScore`

Deterministic, dependency-free similarity used by both preview and predicate.

```ts
export function fuzzyScore(value: unknown, term: string);
```

---

### `rankFuzzyValues`

```ts
export function rankFuzzyValues(
  values: readonly unknown[],
  filter: FuzzyFilterValue,
  limit = DEFAULT_FUZZY_PREVIEW_LIMIT,
  candidateLimit = DEFAULT_FUZZY_PREVIEW_CANDIDATE_LIMIT,
): readonly FuzzyPreviewItem[];
```

---

### `fuzzyHighlightParts`

Splits display text using a deterministic longest-common-subsequence match.

```ts
export function fuzzyHighlightParts(value: string, term: string): readonly FuzzyHighlightPart[];
```

---

### `FILTER_FUZZY`

```ts
FILTER_FUZZY: string;
```

---

### `FUZZY_OPERATOR`

```ts
FUZZY_OPERATOR: string;
```

---

### `DEFAULT_FUZZY_THRESHOLD`

```ts
DEFAULT_FUZZY_THRESHOLD: 0.55;
```

---

### `DEFAULT_FUZZY_PREVIEW_LIMIT`

```ts
DEFAULT_FUZZY_PREVIEW_LIMIT: 5;
```

---

### `DEFAULT_FUZZY_PREVIEW_CANDIDATE_LIMIT`

Keeps preview work bounded when a column has very high cardinality.

```ts
DEFAULT_FUZZY_PREVIEW_CANDIDATE_LIMIT: 2000;
```

---

### `FuzzyFilterValue`

```ts
interface FuzzyFilterValue {
  readonly term: string;
  readonly threshold: number
}
```

---

### `FuzzyPreviewItem`

```ts
interface FuzzyPreviewItem {
  readonly value: string;
  readonly score: number
}
```

---

### `FuzzyHighlightPart`

```ts
interface FuzzyHighlightPart {
  readonly text: string;
  readonly matched: boolean
}
```

---

### `fuzzyFilter`

```ts
fuzzyFilter: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `FUZZY_FILTERS`

```ts
FUZZY_FILTERS: {
  [FUZZY_OPERATOR]: { columnFilterType: string; name: "Fuzzy search"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `defineFuzzyEditor`

```ts
export function defineFuzzyEditor(host: HTMLElement, context: StructuredFilterBodyContext);
```

---

### `FuzzyEditor`

```ts
export function FuzzyEditor({ context }: { context: StructuredFilterBodyContext });
```

---

### `fuzzyCaption`

```ts
export function fuzzyCaption(labels: StructuredFilterLabels, id: FuzzyCaptionId);
```

---

### `fuzzyMessage`

```ts
export function fuzzyMessage(labels: StructuredFilterLabels, id: FuzzyCaptionId, values: StructuredFilterMessageValues = {});
```

---

### `FUZZY_LOCALIZATION`

```ts
FUZZY_LOCALIZATION: Readonly<{ filterNames: Readonly<{ fuzzy: "Fuzzy search"; }>; captions: Readonly<{ fuzzyHeaderPlaceholder: "Similar to…"; fuzzyTitle: "Fuzzy search"; fuzzyQuery: "Search for"; fuzzyPlaceholder: "Type a name or value"; fuzzyNoMatches: "No values meet this strictness."; fuzzyLoose: "loose"; fuzzyStrict: "strict"; fuzzyTolerance: "Match strictness"; fuzzyStrictnessValue: "{percent}% strict"; 'filter.fuzzy.description': "Fuzzy match “{term}” at {threshold}"; }>; }>;
```

---

### `FuzzyCaptionId`

```ts
export type FuzzyCaptionId = keyof typeof FUZZY_LOCALIZATION.captions;
```

---

### `regexStructuredFilterType`

```ts
regexStructuredFilterType: {
  id: string;
  operatorIds: string[];
  aggregateNeeds: "uniqueValues"[];
  describeCondition: ({ condition, labels }: StructuredFilterPresentationContext) => { summary: string; details: string; } | undefined;
  mount: (host: HTMLElement, context: StructuredFilterBodyContext) => PreactRootDisposer;
  render: (context: StructuredFilterBodyContext) => any;
};
```

---

### `normalizeRegexFlags`

Keep supported flags JSON-safe, duplicate-free, and in a stable display order.

```ts
export function normalizeRegexFlags(value: unknown);
```

---

### `normalizeRegexFilterValue`

```ts
export function normalizeRegexFilterValue(value: unknown): RegexFilterValue;
```

---

### `regexModeFromOperator`

```ts
export function regexModeFromOperator(type: unknown): RegexFilterMode;
```

---

### `regexOperatorFromMode`

```ts
export function regexOperatorFromMode(mode: RegexFilterMode): RegexFilterOperator;
```

---

### `regexValidationError`

```ts
export function regexValidationError(value: RegexFilterValue);
```

---

### `regexCondition`

Returns undefined for invalid input so callers can retain the last valid condition.

```ts
export function regexCondition(state: RegexFilterState): StructuredFilterCondition[] | undefined;
```

---

### `regexStateFromConditions`

```ts
export function regexStateFromConditions(
  conditions: readonly Readonly<{ type: string; value?: unknown }>[],
): RegexFilterState;
```

---

### `previewRegexValues`

```ts
export function previewRegexValues(
  values: readonly unknown[],
  state: RegexFilterState,
  limit = REGEX_PREVIEW_LIMIT,
  scanLimit = REGEX_PREVIEW_SCAN_LIMIT,
): RegexPreview;
```

---

### `FILTER_REGEX`

```ts
FILTER_REGEX: string;
```

---

### `REGEX_MATCHES`

```ts
REGEX_MATCHES: string;
```

---

### `REGEX_NOT_MATCHES`

```ts
REGEX_NOT_MATCHES: string;
```

---

### `REGEX_PREVIEW_LIMIT`

```ts
REGEX_PREVIEW_LIMIT: 2;
```

---

### `REGEX_PREVIEW_SCAN_LIMIT`

Keep live popup preview work bounded for high-cardinality remote/local columns.

```ts
REGEX_PREVIEW_SCAN_LIMIT: 10000;
```

---

### `RegexFilterMode`

```ts
export type RegexFilterMode = 'matches' | 'not-matches';
```

---

### `RegexFilterOperator`

```ts
export type RegexFilterOperator = typeof REGEX_MATCHES | typeof REGEX_NOT_MATCHES;
```

---

### `RegexFilterValue`

```ts
interface RegexFilterValue {
  readonly pattern: string;
  readonly flags: string
}
```

---

### `RegexFilterState` (Extended from `index.ts`)

```ts
interface RegexFilterState {
  readonly mode: RegexFilterMode
}
```

---

### `RegexPreview`

```ts
interface RegexPreview {
  readonly values: readonly string[];
  readonly total: number;
  readonly more: number;
  /** True when `total` is only a lower bound because the scan limit was reached. */
    readonly truncated: boolean
}
```

---

### `regexMatches`

```ts
regexMatches: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `regexNotMatches`

```ts
regexNotMatches: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `REGEX_FILTERS`

```ts
REGEX_FILTERS: {
  [REGEX_MATCHES]: { columnFilterType: string; name: "Matches pattern"; func: LogicFunction<any, LogicFunctionExtraParam>; };
  [REGEX_NOT_MATCHES]: { columnFilterType: string; name: "Does not match pattern"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `defineRegexEditor`

```ts
export function defineRegexEditor(host: HTMLElement, context: StructuredFilterBodyContext);
```

---

### `RegexEditor`

```ts
export function RegexEditor({ context }: { context: StructuredFilterBodyContext });
```

---

### `regexFilterCaption`

```ts
export function regexFilterCaption(labels: StructuredFilterLabels, id: RegexFilterCaptionId);
```

---

### `regexFilterMessage`

```ts
export function regexFilterMessage(
  labels: StructuredFilterLabels,
  id: RegexFilterCaptionId,
  values: RegexFilterMessageValues = {},
);
```

---

### `REGEX_FILTER_LOCALIZATION`

```ts
REGEX_FILTER_LOCALIZATION: Readonly<{ filterNames: Readonly<{ regexMatches: "Matches pattern"; regexNotMatches: "Does not match pattern"; }>; captions: Readonly<{ regexHeaderPlaceholder: "Pattern…"; regexTitle: "Regex / pattern"; regexPlaceholder: "^example\\d+$"; regexPatternInput: "Regular expression pattern"; regexFlags: "Active flags"; regexOptions: "Pattern options"; regexIgnoreCase: "ignore case"; regexMultiline: "multiline"; regexNoMatches: "No matching values"; regexMoreMatches: "…{count} more"; regexPreviewLimited: "Preview limited for this high-cardinality column."; regexInvalid: "Invalid pattern — the previous valid filter is still applied."; regexValid: "Valid pattern"; regexEmpty: "Enter a pattern to filter values."; regexUnsafeExpression: "Potentially unsafe regular expression"; regexInvalidExpression: "Invalid regular expression"; 'filter.regex.matchesDescription': "Matches {expression}"; 'filter.regex.notMatchesDescription': "Does not match {expression}"; }>; }>;
```

---

### `RegexFilterCaptionId`

```ts
export type RegexFilterCaptionId = keyof typeof REGEX_FILTER_LOCALIZATION.captions;
```

---

### `RegexFilterMessageValues`

```ts
export type RegexFilterMessageValues = Readonly<Record<string, string | number>>;
```

---

### `tokenListStructuredFilterType`

```ts
tokenListStructuredFilterType: {
  id: string;
  operatorIds: string[];
  aggregateNeeds: "uniqueValues"[];
  describeCondition: ({ condition, labels }: StructuredFilterPresentationContext) => { summary: string; details: string; } | undefined;
  mount: (host: HTMLElement, context: StructuredFilterBodyContext) => PreactRootDisposer;
  render: (context: StructuredFilterBodyContext) => any;
};
```

---

### `normalizeTokenList`

```ts
export function normalizeTokenList(values: readonly unknown[]);
```

---

### `parseTokenList`

Splits clipboard-sized input into normalized, stable-order tokens.

```ts
export function parseTokenList(value: string);
```

---

### `hasTokenListDelimiter`

```ts
export function hasTokenListDelimiter(value: string);
```

---

### `mergeTokenLists`

```ts
export function mergeTokenLists(current: readonly string[], additions: readonly unknown[]);
```

---

### `tokenListSuggestions`

```ts
export function tokenListSuggestions(
  values: readonly unknown[],
  selected: readonly string[],
  draft: string,
  limit = 8,
);
```

---

### `tokenListModeFromOperator`

```ts
export function tokenListModeFromOperator(type: unknown): TokenListMode;
```

---

### `tokenListOperatorFromMode`

```ts
export function tokenListOperatorFromMode(mode: TokenListMode): TokenListOperator;
```

---

### `tokenListCondition`

```ts
export function tokenListCondition(
  tokens: readonly string[],
  mode: TokenListMode,
): StructuredFilterCondition[];
```

---

### `tokenListStateFromConditions`

```ts
export function tokenListStateFromConditions(
  conditions: readonly Readonly<{ type: string; value?: unknown }>[],
);
```

---

### `FILTER_TOKEN_LIST`

```ts
FILTER_TOKEN_LIST: string;
```

---

### `TOKEN_LIST_ANY_OF`

```ts
TOKEN_LIST_ANY_OF: string;
```

---

### `TOKEN_LIST_NONE_OF`

```ts
TOKEN_LIST_NONE_OF: string;
```

---

### `TokenListMode`

```ts
export type TokenListMode = 'any-of' | 'none-of';
```

---

### `TokenListOperator`

```ts
export type TokenListOperator = typeof TOKEN_LIST_ANY_OF | typeof TOKEN_LIST_NONE_OF;
```

---

### `tokenListAnyOf`

```ts
tokenListAnyOf: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `tokenListNoneOf`

```ts
tokenListNoneOf: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `TOKEN_LIST_FILTERS`

```ts
TOKEN_LIST_FILTERS: {
  [TOKEN_LIST_ANY_OF]: { columnFilterType: string; name: "Is any of"; func: LogicFunction<any, LogicFunctionExtraParam>; };
  [TOKEN_LIST_NONE_OF]: { columnFilterType: string; name: "None of"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `defineTokenListEditor`

```ts
export function defineTokenListEditor(host: HTMLElement, context: StructuredFilterBodyContext);
```

---

### `TokenListEditor`

```ts
export function TokenListEditor({ context }: { context: StructuredFilterBodyContext });
```

---

### `tokenListCaption`

```ts
export function tokenListCaption(labels: StructuredFilterLabels, id: TokenListCaptionId);
```

---

### `tokenListMessage`

```ts
export function tokenListMessage(
  labels: StructuredFilterLabels,
  id: TokenListCaptionId,
  values: TokenListMessageValues = {},
);
```

---

### `TOKEN_LIST_LOCALIZATION`

```ts
TOKEN_LIST_LOCALIZATION: Readonly<{ filterNames: Readonly<{ tokenListAnyOf: "Is any of"; tokenListNoneOf: "None of"; }>; captions: Readonly<{ tokenListHeaderPlaceholder: "Any of…"; tokenListTitle: "Token list"; tokenListMode: "Match mode"; tokenListAnyOfLabel: "any of"; tokenListNoneOfLabel: "none of"; tokenListValues: "Values"; tokenListRemove: "Remove {token}"; tokenListMore: "+{count} more"; tokenListPlaceholder: "paste or type…"; tokenListSuggestions: "Suggested values"; tokenListCountOne: "{count} token"; tokenListCountMany: "{count} tokens"; 'filter.tokenList.noneOfDescription': "None of: {values}"; 'filter.tokenList.anyOfDescription': "Any of: {values}"; }>; }>;
```

---

### `TokenListCaptionId`

```ts
export type TokenListCaptionId = keyof typeof TOKEN_LIST_LOCALIZATION.captions;
```

---

### `TokenListMessageValues`

```ts
export type TokenListMessageValues = Readonly<Record<string, string | number>>;
```

---

### `facetedListStructuredFilterType`

```ts
facetedListStructuredFilterType: {
  id: string;
  operatorIds: string[];
  aggregateNeeds: "valueCounts"[];
  describeCondition: ({ condition, column, config, labels }: StructuredFilterPresentationContext) => { summary: string; details: string; } | undefined;
  getHeaderSelection: ({ condition, column, config, aggregates, labels }: StructuredFilterHeaderSelectionContext) => { values: { value: string; label: string; count: number; }[]; totalCount: number; } | undefined;
  mount: (host: HTMLElement, context: StructuredFilterBodyContext) => PreactRootDisposer;
  render: (context: StructuredFilterBodyContext) => any;
};
```

---

### `isFacetedScalar`

```ts
export function isFacetedScalar(value: unknown): value is FacetedScalar;
```

---

### `facetedScalarId`

JSON-safe typed identity; unlike display text it keeps 1, "1", and true distinct.

```ts
export function facetedScalarId(value: FacetedScalar);
```

---

### `facetedScalarLabel`

```ts
export function facetedScalarLabel(value: FacetedScalar, labels = DEFAULT_FACETED_SCALAR_LABEL_TEXT);
```

---

### `resolveFacetedListLabelFormatter`

```ts
export function resolveFacetedListLabelFormatter(
  options: FacetedListOptions | undefined,
  property: ColumnProp,
): FacetedListLabelFormatter | undefined;
```

---

### `normalizeFacetedValues`

```ts
export function normalizeFacetedValues(values: readonly unknown[]);
```

---

### `createFacetedListOptions`

```ts
export function createFacetedListOptions(
  allCounts: readonly StructuredFilterValueCount[],
  visibleCounts: readonly StructuredFilterValueCount[] = [],
  labels: FacetedScalarLabelText = DEFAULT_FACETED_SCALAR_LABEL_TEXT,
  formatLabel?: (value: FacetedScalar) => string | undefined,
);
```

---

### `facetedListStateFromConditions`

```ts
export function facetedListStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
  allValues: readonly FacetedScalar[],
): FacetedListState;
```

---

### `facetedListCondition`

```ts
export function facetedListCondition(
  selectedValues: readonly FacetedScalar[],
  allValues: readonly FacetedScalar[],
  conditionId?: number,
): StructuredFilterCondition[];
```

---

### `FILTER_FACETED_LIST`

```ts
FILTER_FACETED_LIST: string;
```

---

### `FACETED_LIST_INCLUDE`

```ts
FACETED_LIST_INCLUDE: string;
```

---

### `FACETED_LIST_EXCLUDE`

```ts
FACETED_LIST_EXCLUDE: string;
```

---

### `FACETED_LIST_RENDER_LIMIT`

```ts
FACETED_LIST_RENDER_LIMIT: 200;
```

---

### `FacetedListOperator`

```ts
export type FacetedListOperator = typeof FACETED_LIST_INCLUDE | typeof FACETED_LIST_EXCLUDE;
```

---

### `FacetedScalar`

```ts
export type FacetedScalar = string | number | boolean | null;
```

---

### `FacetedListFormatLabelContext`

```ts
interface FacetedListFormatLabelContext {
  readonly property: ColumnProp;
  readonly column?: FilterEvaluationContext['column']
}
```

---

### `FacetedListLabelFormatter`

Presents one stored scalar facet without changing its typed filter identity.

```ts
/** Presents one stored scalar facet without changing its typed filter identity. */
export type FacetedListLabelFormatter = (
  value: FacetedScalar,
  context: FacetedListFormatLabelContext,
) => string | undefined;
```

---

### `FacetedListColumnOptions`

```ts
interface FacetedListColumnOptions {
  readonly formatLabel?: FacetedListLabelFormatter
}
```

---

### `FacetedListOptions`

```ts
interface FacetedListOptions {
  readonly formatLabel?: FacetedListLabelFormatter;
  readonly columns?: Readonly<Record<string, FacetedListColumnOptions>>
}
```

---

### `FacetedListOption`

```ts
interface FacetedListOption {
  readonly id: string;
  readonly value: FacetedScalar;
  readonly label: string;
  readonly count: number;
  readonly visibleCount: number
}
```

---

### `FacetedListState`

```ts
interface FacetedListState {
  readonly selected: readonly FacetedScalar[];
  readonly conditionId?: number
}
```

---

### `FacetedScalarLabelText`

```ts
interface FacetedScalarLabelText {
  readonly blank: string;
  readonly empty: string;
  readonly true: string;
  readonly false: string
}
```

---

### `DEFAULT_FACETED_SCALAR_LABEL_TEXT`

```ts
DEFAULT_FACETED_SCALAR_LABEL_TEXT: {
  blank: string;
  empty: string;
  true: string;
  false: string;
};
```

---

### `facetedListInclude`

```ts
facetedListInclude: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `facetedListExclude`

```ts
facetedListExclude: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `FACETED_LIST_FILTERS`

```ts
FACETED_LIST_FILTERS: {
  [FACETED_LIST_INCLUDE]: { columnFilterType: string; name: "Is any selected value"; func: LogicFunction<any, LogicFunctionExtraParam>; };
  [FACETED_LIST_EXCLUDE]: { columnFilterType: string; name: "Excludes selected values"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `defineFacetedListEditor`

```ts
export function defineFacetedListEditor(host: HTMLElement, context: StructuredFilterBodyContext);
```

---

### `FacetedListEditor`

```ts
export function FacetedListEditor({ context }: { context: StructuredFilterBodyContext });
```

---

### `facetedListCaption`

```ts
export function facetedListCaption(labels: StructuredFilterLabels, id: FacetedListCaptionId);
```

---

### `facetedListMessage`

```ts
export function facetedListMessage(labels: StructuredFilterLabels, id: FacetedListCaptionId, values: StructuredFilterMessageValues = {});
```

---

### `FACETED_LIST_LOCALIZATION`

```ts
FACETED_LIST_LOCALIZATION: Readonly<{ filterNames: Readonly<{ facetedListInclude: "Is any selected value"; facetedListExclude: "Excludes selected values"; }>; captions: Readonly<{ facetedListBlank: "(Blank)"; facetedListEmpty: "(Empty)"; facetedListTrue: "True"; facetedListFalse: "False"; facetedListTitle: "Filter by values"; facetedListSelectAll: "Select all"; facetedListSearch: "Search values"; facetedListSearchPlaceholder: "Search..."; facetedListActions: "Value selection actions"; facetedListInvert: "Invert"; facetedListOnlyVisible: "Only visible"; facetedListValues: "Available values"; facetedListCount: "{visible} visible of {total} total rows"; facetedListNoMatches: "No values match your search."; facetedListNoValues: "No values available."; facetedListLimit: "Showing {visible} of {total} values. Search to narrow the list."; 'filter.facetedList.excludeDescription': "Excludes: {values}"; 'filter.facetedList.includeDescription': "Includes: {values}"; }>; }>;
```

---

### `FacetedListCaptionId`

```ts
export type FacetedListCaptionId = keyof typeof FACETED_LIST_LOCALIZATION.captions;
```

---

### `createChipBadgeStructuredFilterType`

Creates the built-in type with optional safe per-badge presentation metadata.

```ts
export function createChipBadgeStructuredFilterType(
  options?: ChipBadgeTogglesOptions,
): StructuredFilterType;
```

---

### `chipBadgeStructuredFilterType`

```ts
chipBadgeStructuredFilterType: StructuredFilterType;
```

---

### `orderChipBadgeValues`

```ts
export function orderChipBadgeValues(
  values: readonly ChipBadgeScalar[],
  order: readonly ChipBadgeScalar[] = [],
);
```

---

### `isChipBadgeScalar`

```ts
export function isChipBadgeScalar(value: unknown): value is ChipBadgeScalar;
```

---

### `isDefaultChipBadgeBlank`

```ts
export function isDefaultChipBadgeBlank(value: unknown);
```

---

### `chipBadgeScalarId`

JSON-safe typed identity; display labels never participate in matching.

```ts
export function chipBadgeScalarId(value: ChipBadgeScalar);
```

---

### `normalizeChipBadgeValues`

```ts
export function normalizeChipBadgeValues(values: readonly unknown[]);
```

---

### `defaultChipBadgeLabel`

```ts
export function defaultChipBadgeLabel(value: ChipBadgeScalar, labels = DEFAULT_CHIP_BADGE_LABEL_TEXT);
```

---

### `resolveChipBadgeDescriptor`

```ts
export function resolveChipBadgeDescriptor(
  value: ChipBadgeScalar,
  column: ColumnRegular,
  selected: boolean,
  options?: ChipBadgeTogglesOptions,
  labels: ChipBadgeLabelText = DEFAULT_CHIP_BADGE_LABEL_TEXT,
): ChipBadgeDescriptor;
```

---

### `isValidChipBadgeFilterValue`

Checks the exact JSON-safe selection transport shape before it is applied.

```ts
export function isValidChipBadgeFilterValue(value: unknown): value is ChipBadgeFilterValue;
```

---

### `describeChipBadgeValue`

Parses transport state once for compact, filter-owned presentation surfaces.

```ts
export function describeChipBadgeValue(
  value: unknown,
  column: ColumnRegular,
  options?: ChipBadgeTogglesOptions,
  labels: ChipBadgeLabelText = DEFAULT_CHIP_BADGE_LABEL_TEXT,
);
```

---

### `resolveVisibleChipBadgeLimit`

```ts
export function resolveVisibleChipBadgeLimit(options?: ChipBadgeTogglesOptions);
```

---

### `chipBadgeStateFromConditions`

```ts
export function chipBadgeStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
  allValues: readonly ChipBadgeScalar[],
): ChipBadgeState;
```

---

### `chipBadgeCondition`

```ts
export function chipBadgeCondition(
  selectedValues: readonly ChipBadgeScalar[],
  allValues: readonly ChipBadgeScalar[],
  includeBlanks: boolean,
  hasBlanks: boolean,
  conditionId?: number,
): StructuredFilterCondition[];
```

---

### `FILTER_CHIP_BADGE_TOGGLES`

```ts
FILTER_CHIP_BADGE_TOGGLES: string;
```

---

### `CHIP_BADGE_SELECTION`

```ts
CHIP_BADGE_SELECTION: string;
```

---

### `DEFAULT_VISIBLE_CHIP_BADGES`

Avoid mounting an unbounded number of interactive pills for high-cardinality columns.

```ts
DEFAULT_VISIBLE_CHIP_BADGES: 200;
```

---

### `ChipBadgeScalar`

```ts
export type ChipBadgeScalar = string | number | boolean;
```

---

### `ChipBadgeFilterValue`

```ts
interface ChipBadgeFilterValue {
  readonly values: readonly ChipBadgeScalar[];
  readonly includeBlanks: boolean
}
```

---

### `ChipBadgeDescriptor`

```ts
interface ChipBadgeDescriptor {
  /** Plain-text label. It is rendered as text, never interpreted as HTML. */
    readonly label: string;
  /** Optional classes applied to the pill button. */
    readonly className?: string;
  /** Optional CSS color used for the pill's swatch and selected accent. */
    readonly color?: string
}
```

---

### `ChipBadgeDescriptorContext`

```ts
interface ChipBadgeDescriptorContext {
  readonly value: ChipBadgeScalar;
  readonly column: ColumnRegular;
  readonly selected: boolean
}
```

---

### `ChipBadgeTogglesOptions`

```ts
interface ChipBadgeTogglesOptions {
  /** Formats a value or returns safe presentation metadata for its pill. */
    readonly badge?: (
      context: ChipBadgeDescriptorContext,
    ) => string | ChipBadgeDescriptor | null | undefined;
  /** Maximum pills mounted at once. The complete value set still drives condition semantics. */
    readonly maxVisibleBadges?: number;
  /** Preferred display order; values not listed remain in aggregate order. */
    readonly order?: readonly ChipBadgeScalar[]
}
```

---

### `ChipBadgeState` (Extended from `index.ts`)

```ts
interface ChipBadgeState {
  readonly conditionId?: number
}
```

---

### `ChipBadgeLabelText`

```ts
interface ChipBadgeLabelText {
  readonly true: string;
  readonly false: string
}
```

---

### `DEFAULT_CHIP_BADGE_LABEL_TEXT`

```ts
DEFAULT_CHIP_BADGE_LABEL_TEXT: {
  true: string;
  false: string;
};
```

---

### `chipBadgeSelection`

```ts
chipBadgeSelection: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `CHIP_BADGE_FILTERS`

```ts
CHIP_BADGE_FILTERS: {
  [CHIP_BADGE_SELECTION]: { columnFilterType: string; name: "Matches selected badges"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `defineChipBadgeTogglesEditor`

```ts
export function defineChipBadgeTogglesEditor(
  host: HTMLElement,
  context: StructuredFilterBodyContext,
  options?: ChipBadgeTogglesOptions,
);
```

---

### `ChipBadgeTogglesEditor`

```ts
export function ChipBadgeTogglesEditor({
  context,
  options,
}: {
  context: StructuredFilterBodyContext;
  options?: ChipBadgeTogglesOptions;
});
```

---

### `chipBadgeCaption`

```ts
export function chipBadgeCaption(labels: StructuredFilterLabels, id: ChipBadgeCaptionId);
```

---

### `chipBadgeMessage`

```ts
export function chipBadgeMessage(labels: StructuredFilterLabels, id: ChipBadgeCaptionId, values: StructuredFilterMessageValues = {});
```

---

### `CHIP_BADGE_LOCALIZATION`

```ts
CHIP_BADGE_LOCALIZATION: Readonly<{ filterNames: Readonly<{ chipBadgeSelection: "Matches selected badges"; }>; captions: Readonly<{ chipBadgeHeaderPlaceholder: "Any"; chipBadgeTrue: "True"; chipBadgeFalse: "False"; chipBadgeTitle: "Filter by badges"; chipBadgeValues: "Available badge values"; chipBadgeToggleLabel: "{label}, {state}"; chipBadgeSelected: "selected"; chipBadgeNotSelected: "not selected"; chipBadgeNoValues: "No badge values available."; chipBadgeTruncated: "Showing first {visible} of {total} badges."; chipBadgeIncludeBlanks: "Include blanks"; chipBadgeSelectedCount: "{selected} of {total} selected"; chipBadgeBadgeSummaryOne: "1 selected"; chipBadgeBadgeSummaryMany: "{count} selected"; chipBadgeBadgeBlanksIncluded: "blanks included"; chipBadgeBadgeBlanksExcluded: "blanks excluded"; chipBadgeNoneSelected: "No badges selected"; }>; }>;
```

---

### `ChipBadgeCaptionId`

```ts
export type ChipBadgeCaptionId = keyof typeof CHIP_BADGE_LOCALIZATION.captions;
```

---

### `createHistogramBrushStructuredFilterType`

Creates an opt-in histogram brush type with deterministic presentation options.

```ts
export function createHistogramBrushStructuredFilterType(
  options?: HistogramBrushOptions,
): StructuredFilterType;
```

---

### `histogramBrushStructuredFilterType`

```ts
histogramBrushStructuredFilterType: StructuredFilterType;
```

---

### `resolveHistogramChartTypes`

```ts
export function resolveHistogramChartTypes(
  chart?: HistogramBrushChartOptions,
): readonly DistributionChartType[];
```

---

### `resolveInitialHistogramChartType`

```ts
export function resolveInitialHistogramChartType(
  chart: HistogramBrushChartOptions | undefined,
  types = resolveHistogramChartTypes(chart),
): DistributionChartType | undefined;
```

---

### `histogramModelFromPreparedData`

```ts
export function histogramModelFromPreparedData(value: unknown): HistogramModel | undefined;
```

---

### `toHistogramNumber`

```ts
export function toHistogramNumber(value: unknown): number | undefined;
```

---

### `createHistogramModel`

```ts
export function createHistogramModel(
  aggregate: StructuredFilterNumericRange,
  options: Pick<HistogramBrushOptions, 'bins' | 'scale'> = {},
): HistogramModel;
```

---

### `parseHistogramBrushFilterValue`

```ts
export function parseHistogramBrushFilterValue(value: unknown): HistogramBrushFilterValue | undefined;
```

---

### `histogramBrushStateFromConditions`

```ts
export function histogramBrushStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
  model: HistogramModel,
): HistogramBrushState;
```

---

### `histogramBrushCondition`

```ts
export function histogramBrushCondition(
  selectedMin: number,
  selectedMax: number,
  model: Pick<HistogramModel, 'min' | 'max'>,
  conditionId?: number,
): StructuredFilterCondition[];
```

---

### `histogramBrushMatchCount`

```ts
export function histogramBrushMatchCount(model: Pick<HistogramModel, 'values'>, min: number, max: number);
```

---

### `histogramPosition`

```ts
export function histogramPosition(value: number, model: Pick<HistogramModel, 'min' | 'max' | 'scale'>);
```

---

### `histogramValueAtPosition`

```ts
export function histogramValueAtPosition(position: number, model: Pick<HistogramModel, 'min' | 'max' | 'scale'>);
```

---

### `histogramBinIsSelected`

```ts
export function histogramBinIsSelected(bin: HistogramBin, min: number, max: number);
```

---

### `FILTER_HISTOGRAM_BRUSH`

```ts
FILTER_HISTOGRAM_BRUSH: string;
```

---

### `HISTOGRAM_BRUSH_BETWEEN`

```ts
HISTOGRAM_BRUSH_BETWEEN: string;
```

---

### `HISTOGRAM_BRUSH_STEPS`

```ts
HISTOGRAM_BRUSH_STEPS: 1000;
```

---

### `HistogramBrushScale`

```ts
export type HistogramBrushScale = 'linear' | 'log';
```

---

### `HistogramBrushFilterValue`

```ts
interface HistogramBrushFilterValue {
  readonly min: number;
  readonly max: number;
  readonly inclusive: true
}
```

---

### `HistogramBrushFormatContext`

```ts
interface HistogramBrushFormatContext {
  readonly column: import('@revolist/revogrid').ColumnRegular
}
```

---

### `HistogramBrushOptions`

```ts
interface HistogramBrushOptions {
  /** Fixed bar count or deterministic Sturges-rule bins. Defaults to `auto`. */
    readonly bins?: number | 'auto';
  /** Uses logarithmic bin/brush geometry when all values are positive. */
    readonly scale?: HistogramBrushScale;
  /** Formats bounds and handle value text. */
    readonly formatValue?: (value: number, context: HistogramBrushFormatContext) => string;
  /** Formats the selected row count. */
    readonly formatMatchCount?: (count: number, context: HistogramBrushFormatContext) => string;
  /** Presentation-only chart configuration. Filtering and prepared-data contracts are unchanged. */
    readonly chart?: HistogramBrushChartOptions
}
```

---

### `HistogramBrushChartTooltipContext` (Extended from `index.ts`)

```ts
interface HistogramBrushChartTooltipContext {
  readonly index: number;
  readonly selected: boolean;
  readonly minLabel: string;
  readonly maxLabel: string
}
```

---

### `HistogramBrushChartOptions`

```ts
interface HistogramBrushChartOptions {
  /** Initial preferred chart style. Falls back to the first enabled type. */
    readonly type?: DistributionChartType;
  /** Ordered styles users may switch between. One hides the switch; an empty list hides the chart. */
    readonly types?: readonly DistributionChartType[];
  readonly height?: number;
  readonly showPoints?: boolean;
  readonly formatTooltip?: (
      bin: HistogramBin,
      context: HistogramBrushChartTooltipContext,
    ) => DistributionChartTooltip
}
```

---

### `HistogramBin`

```ts
interface HistogramBin {
  readonly min: number;
  readonly max: number;
  readonly count: number
}
```

---

### `HistogramModel`

```ts
interface HistogramModel {
  /** Finite numeric values sorted ascending for logarithmic-time range counts. */
    readonly values: readonly number[];
  readonly min?: number;
  readonly max?: number;
  readonly scale: HistogramBrushScale;
  readonly bins: readonly HistogramBin[]
}
```

---

### `HistogramPreparedData`

Compact server-produced histogram; raw row values are intentionally omitted.

```ts
interface HistogramPreparedData {
  readonly kind: 'histogramBrush';
  readonly count: number;
  readonly min: number;
  readonly max: number;
  readonly scale: HistogramBrushScale;
  readonly bins: readonly HistogramBin[]
}
```

---

### `HistogramBrushState`

```ts
interface HistogramBrushState {
  readonly min?: number;
  readonly max?: number;
  readonly conditionId?: number
}
```

---

### `histogramBrushBetween`

```ts
histogramBrushBetween: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `HISTOGRAM_BRUSH_FILTERS`

```ts
HISTOGRAM_BRUSH_FILTERS: {
  [HISTOGRAM_BRUSH_BETWEEN]: { columnFilterType: string; name: "Is in histogram range"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `defineHistogramBrushEditor`

```ts
export function defineHistogramBrushEditor(
  host: HTMLElement,
  context: StructuredFilterBodyContext,
  options?: HistogramBrushOptions,
);
```

---

### `HistogramBrushEditor`

```ts
export function HistogramBrushEditor({
  context,
  options,
}: {
  context: StructuredFilterBodyContext;
  options?: HistogramBrushOptions;
});
```

---

### `histogramBrushCaption`

```ts
export function histogramBrushCaption(labels: StructuredFilterLabels, id: HistogramBrushCaptionId);
```

---

### `histogramBrushMessage`

```ts
export function histogramBrushMessage(labels: StructuredFilterLabels, id: HistogramBrushCaptionId, values: StructuredFilterMessageValues = {});
```

---

### `histogramBrushChartTypeCaption`

```ts
export function histogramBrushChartTypeCaption(
  labels: StructuredFilterLabels,
  type: import('../../../distribution-chart').DistributionChartType,
);
```

---

### `HISTOGRAM_BRUSH_LOCALIZATION`

```ts
HISTOGRAM_BRUSH_LOCALIZATION: Readonly<{ filterNames: Readonly<{ histogramBrushBetween: "Is in histogram range"; }>; captions: Readonly<{ histogramBrushTitle: "Histogram range"; histogramBrushDescription: "Choose a numeric range. The chart shows the distribution."; histogramBrushNoValues: "No numeric values available."; histogramBrushMatchOne: "1 match"; histogramBrushMatchMany: "{count} matches"; histogramBrushItem: "item"; histogramBrushItems: "items"; histogramBrushSelected: "Selected"; histogramBrushOutsideSelection: "Outside selection"; histogramBrushChart: "Value distribution"; histogramBrushChartTypes: "Chart style"; histogramBrushChartBar: "Bar"; histogramBrushChartLine: "Line"; histogramBrushChartArea: "Area"; histogramBrushDescriptionNoChart: "Choose a numeric range."; histogramBrushMinimum: "Minimum value"; histogramBrushMaximum: "Maximum value"; histogramBrushRemoteCount: "Count updates after apply"; }>; }>;
```

---

### `HistogramBrushCaptionId`

```ts
export type HistogramBrushCaptionId = keyof typeof HISTOGRAM_BRUSH_LOCALIZATION.captions;
```

---

### `createRatingProgressThresholdStructuredFilterType`

Creates the opt-in rating/progress threshold type with bounded numeric presentation options.

```ts
export function createRatingProgressThresholdStructuredFilterType(
  options?: RatingProgressThresholdOptions,
): StructuredFilterType;
```

---

### `ratingProgressThresholdStructuredFilterType`

```ts
ratingProgressThresholdStructuredFilterType: StructuredFilterType;
```

---

### `normalizeRatingProgressOptions`

```ts
export function normalizeRatingProgressOptions(
  options: RatingProgressThresholdOptions = {},
): NormalizedRatingProgressOptions;
```

---

### `normalizeRatingProgressValue`

Produces a stable finite value aligned to the configured bounded domain.

```ts
export function normalizeRatingProgressValue(
  value: unknown,
  options: Pick<NormalizedRatingProgressOptions, 'max' | 'step'>,
);
```

---

### `ratingProgressStateFromConditions`

```ts
export function ratingProgressStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
  options: NormalizedRatingProgressOptions,
): RatingProgressState;
```

---

### `ratingProgressCondition`

```ts
export function ratingProgressCondition(
  operator: RatingProgressOperator,
  value: unknown,
  options: NormalizedRatingProgressOptions,
  conditionId?: number,
): StructuredFilterCondition[];
```

---

### `FILTER_RATING_PROGRESS_THRESHOLD`

```ts
FILTER_RATING_PROGRESS_THRESHOLD: string;
```

---

### `RATING_PROGRESS_GTE`

```ts
RATING_PROGRESS_GTE: string;
```

---

### `RATING_PROGRESS_EQ`

```ts
RATING_PROGRESS_EQ: string;
```

---

### `RATING_PROGRESS_LTE`

```ts
RATING_PROGRESS_LTE: string;
```

---

### `RATING_PROGRESS_OPERATORS`

```ts
RATING_PROGRESS_OPERATORS: readonly ["ratingProgressThresholdGte", "ratingProgressThresholdEq", "ratingProgressThresholdLte"];
```

---

### `RatingProgressOperator`

```ts
export type RatingProgressOperator = typeof RATING_PROGRESS_OPERATORS[number];
```

---

### `RatingProgressUnit`

```ts
export type RatingProgressUnit = 'stars' | 'percent' | 'score';
```

---

### `RatingProgressFormatContext`

```ts
interface RatingProgressFormatContext {
  readonly column: ColumnRegular;
  readonly unit: RatingProgressUnit;
  readonly max: number;
  readonly step: number;
  readonly operator: RatingProgressOperator
}
```

---

### `RatingProgressThresholdOptions`

```ts
interface RatingProgressThresholdOptions {
  /** Determines the visual control and default formatting. Defaults to `stars`. */
    readonly unit?: RatingProgressUnit;
  /** Inclusive upper bound. Defaults to 5 for stars and 100 otherwise. */
    readonly max?: number;
  /** Accessible control increment. Defaults to 1. */
    readonly step?: number;
  /** Formats the live value label and native control value text. */
    readonly formatValue?: (value: number, context: RatingProgressFormatContext) => string
}
```

---

### `NormalizedRatingProgressOptions`

```ts
interface NormalizedRatingProgressOptions {
  readonly unit: RatingProgressUnit;
  readonly max: number;
  readonly step: number;
  readonly formatValue?: RatingProgressThresholdOptions['formatValue']
}
```

---

### `RatingProgressState`

```ts
interface RatingProgressState {
  readonly operator: RatingProgressOperator;
  readonly value: number;
  readonly active: boolean;
  readonly conditionId?: number
}
```

---

### `ratingProgressGte`

```ts
ratingProgressGte: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `ratingProgressEq`

```ts
ratingProgressEq: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `ratingProgressLte`

```ts
ratingProgressLte: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `RATING_PROGRESS_FILTERS`

```ts
RATING_PROGRESS_FILTERS: {
  [RATING_PROGRESS_GTE]: { columnFilterType: string; name: "At least"; func: LogicFunction<any, LogicFunctionExtraParam>; };
  [RATING_PROGRESS_EQ]: { columnFilterType: string; name: "Exactly"; func: LogicFunction<any, LogicFunctionExtraParam>; };
  [RATING_PROGRESS_LTE]: { columnFilterType: string; name: "At most"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `defineRatingProgressThresholdEditor`

```ts
export function defineRatingProgressThresholdEditor(
  host: HTMLElement,
  context: StructuredFilterBodyContext,
  options?: RatingProgressThresholdOptions,
);
```

---

### `RatingProgressThresholdEditor`

```ts
export function RatingProgressThresholdEditor({
  context,
  options,
}: {
  context: StructuredFilterBodyContext;
  options?: RatingProgressThresholdOptions;
});
```

---

### `createRatingProgressHeaderTemplate`

Compact visual for discrete star domains; other configurations retain the text fallback.

```ts
export function createRatingProgressHeaderTemplate(
  options: NormalizedRatingProgressOptions,
): FilterHeaderTemplateFunc | undefined;
```

---

### `ratingProgressCaption`

```ts
export function ratingProgressCaption(labels: StructuredFilterLabels, id: RatingProgressCaptionId);
```

---

### `ratingProgressMessage`

```ts
export function ratingProgressMessage(
  labels: StructuredFilterLabels,
  id: RatingProgressCaptionId,
  values: RatingProgressMessageValues = {},
);
```

---

### `ratingProgressDescription`

```ts
export function ratingProgressDescription(labels: StructuredFilterLabels, stars: boolean);
```

---

### `RATING_PROGRESS_LOCALIZATION`

```ts
RATING_PROGRESS_LOCALIZATION: Readonly<{ filterNames: Readonly<{ ratingProgressThresholdGte: "At least"; ratingProgressThresholdEq: "Exactly"; ratingProgressThresholdLte: "At most"; }>; descriptionFallbacks: Readonly<{ stars: "Choose a rating threshold."; progress: "Choose a progress threshold."; }>; captions: Readonly<{ ratingProgressHeaderPlaceholder: "Any rating"; ratingProgressHeaderProgressPlaceholder: "Any progress"; ratingProgressHeaderScorePlaceholder: "Any score"; ratingProgressTitle: "Rating & progress threshold"; ratingProgressDescription: "Choose a progress threshold."; ratingProgressOperator: "Threshold operator"; ratingProgressStars: "Rating threshold"; ratingProgressStarValue: "{value} stars"; ratingProgressValueStars: "{value} of {max} stars"; ratingProgressCompletion: "Completion {operator}"; ratingProgressValue: "Threshold value"; }>; }>;
```

---

### `RatingProgressCaptionId`

```ts
export type RatingProgressCaptionId = keyof typeof RATING_PROGRESS_LOCALIZATION.captions;
```

---

### `RatingProgressMessageValues`

```ts
export type RatingProgressMessageValues = Readonly<Record<string, string | number>>;
```

---

### `createStatisticalPresetsStructuredFilterType`

Creates the opt-in statistical presets type. Statistics refresh on popup render; applied JSON-safe
thresholds remain stable across source changes until the user selects a preset again.

```ts
export function createStatisticalPresetsStructuredFilterType(
  options?: StatisticalPresetsOptions,
): StructuredFilterType;
```

---

### `statisticalPresetsStructuredFilterType`

```ts
statisticalPresetsStructuredFilterType: StructuredFilterType;
```

---

### `statisticalModelsFromPreparedData`

```ts
export function statisticalModelsFromPreparedData(value: unknown): readonly StatisticalPresetModel[] | undefined;
```

---

### `countStatisticalPresetMatches`

Counts a resolved preset against the summary's sorted values in logarithmic time.

```ts
export function countStatisticalPresetMatches(
  sortedValues: readonly number[],
  preset: StatisticalPresetFilterValue,
);
```

---

### `statisticalQuantile`

Deterministic sorted linear-interpolation quantile (R-7).

```ts
export function statisticalQuantile(sortedValues: readonly number[], probability: number);
```

---

### `createStatisticalSummary`

Computes deterministic population statistics from finite numeric values only.

```ts
export function createStatisticalSummary(
  aggregate: Pick<StructuredFilterNumericRange, 'values'>,
): StatisticalSummary;
```

---

### `matchesStatisticalPreset`

```ts
export function matchesStatisticalPreset(value: number, preset: StatisticalPresetFilterValue);
```

---

### `createStatisticalPresetModels`

```ts
export function createStatisticalPresetModels(
  summary: StatisticalSummary,
): readonly StatisticalPresetModel[];
```

---

### `parseStatisticalPresetFilterValue`

```ts
export function parseStatisticalPresetFilterValue(value: unknown): StatisticalPresetFilterValue | undefined;
```

---

### `statisticalPresetStateFromConditions`

```ts
export function statisticalPresetStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
);
```

---

### `statisticalPresetCondition`

```ts
export function statisticalPresetCondition(
  model: StatisticalPresetModel | undefined,
  conditionId?: number,
): StructuredFilterCondition[];
```

---

### `FILTER_STATISTICAL_PRESETS`

```ts
FILTER_STATISTICAL_PRESETS: string;
```

---

### `STATISTICAL_PRESET_OPERATOR`

```ts
STATISTICAL_PRESET_OPERATOR: string;
```

---

### `STATISTICAL_PRESET_IDS`

```ts
STATISTICAL_PRESET_IDS: readonly ["top10Percent", "aboveAverage", "bottomQuartile", "outliersTwoSigma", "negativeOnly"];
```

---

### `StatisticalPresetId`

```ts
export type StatisticalPresetId = typeof STATISTICAL_PRESET_IDS[number];
```

---

### `StatisticalPresetFilterValue`

```ts
interface StatisticalPresetFilterValue {
  readonly preset: StatisticalPresetId;
  readonly lower: number | null;
  readonly upper: number | null;
  readonly lowerInclusive: boolean;
  readonly upperInclusive: boolean;
  readonly outside: boolean
}
```

---

### `StatisticalPresetFormatContext`

```ts
interface StatisticalPresetFormatContext {
  readonly column: ColumnRegular;
  readonly preset: StatisticalPresetId
}
```

---

### `StatisticalPresetsOptions`

Presentation options for statistical presets. Statistics refresh when the popup body renders;
applied conditions keep their serialized bounds until the user selects a preset again.

```ts
interface StatisticalPresetsOptions {
  /** Formats computed means, quantiles, and deviation boundaries. */
    readonly formatValue?: (value: number, context: StatisticalPresetFormatContext) => string;
  /** Formats each preset's matching finite-row count. */
    readonly formatMatchCount?: (count: number, context: StatisticalPresetFormatContext) => string
}
```

---

### `StatisticalSummary`

```ts
interface StatisticalSummary {
  readonly values: readonly number[];
  readonly count: number;
  readonly mean?: number;
  readonly firstQuartile?: number;
  readonly ninetiethPercentile?: number;
  readonly standardDeviation?: number
}
```

---

### `StatisticalPresetModel`

```ts
interface StatisticalPresetModel {
  readonly id: StatisticalPresetId;
  readonly condition: StatisticalPresetFilterValue;
  readonly matchCount: number
}
```

---

### `StatisticalPresetsPreparedData`

```ts
interface StatisticalPresetsPreparedData {
  readonly kind: 'statisticalPresets';
  readonly models: readonly StatisticalPresetModel[]
}
```

---

### `statisticalPresetPredicate`

```ts
statisticalPresetPredicate: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `STATISTICAL_PRESET_FILTERS`

```ts
STATISTICAL_PRESET_FILTERS: {
  [STATISTICAL_PRESET_OPERATOR]: { columnFilterType: string; name: "Statistical preset"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `defineStatisticalPresetsEditor`

```ts
export function defineStatisticalPresetsEditor(
  host: HTMLElement,
  context: StructuredFilterBodyContext,
  options?: StatisticalPresetsOptions,
);
```

---

### `StatisticalPresetsEditor`

```ts
export function StatisticalPresetsEditor({
  context,
  options,
}: {
  context: StructuredFilterBodyContext;
  options?: StatisticalPresetsOptions;
});
```

---

### `formatStatisticalPresetValue`

```ts
export function formatStatisticalPresetValue(
  value: number,
  preset: StatisticalPresetId,
  column: ColumnRegular,
  options?: StatisticalPresetsOptions,
);
```

---

### `formatStatisticalPresetBoundary`

Compact resolved predicate shared by popup rows, headers, badges, and tooltips.

```ts
export function formatStatisticalPresetBoundary(
  value: StatisticalPresetFilterValue,
  column: ColumnRegular,
  labels: StructuredFilterLabels,
  options?: StatisticalPresetsOptions,
);
```

---

### `statisticalPresetsCaption`

```ts
export function statisticalPresetsCaption(labels: StructuredFilterLabels, id: StatisticalPresetsCaptionId);
```

---

### `statisticalPresetsMessage`

```ts
export function statisticalPresetsMessage(
  labels: StructuredFilterLabels,
  id: StatisticalPresetsCaptionId,
  values: StatisticalPresetsMessageValues = {},
);
```

---

### `statisticalPresetCaption`

```ts
export function statisticalPresetCaption(labels: StructuredFilterLabels, preset: StatisticalPresetId);
```

---

### `STATISTICAL_PRESETS_LOCALIZATION`

```ts
STATISTICAL_PRESETS_LOCALIZATION: Readonly<{ filterNames: Readonly<{ statisticalPreset: "Statistical preset"; }>; captions: Readonly<{ statisticalPresetTop10: "Top 10%"; statisticalPresetAboveAverage: "Above average"; statisticalPresetBottomQuartile: "Bottom quartile"; statisticalPresetOutliers: "Outliers (> 2σ)"; statisticalPresetNegative: "Negative only"; statisticalPresetOutsideRange: "< {lower} or > {upper}"; statisticalPresetRowsOne: "{count} row"; statisticalPresetRowsMany: "{count} rows"; statisticalPresetsTitle: "Statistical presets"; statisticalPresetsChoices: "Statistical preset choices"; statisticalPresetsNoValues: "No numeric values available."; }>; }>;
```

---

### `STATISTICAL_PRESET_CAPTIONS`

```ts
STATISTICAL_PRESET_CAPTIONS: Readonly<Record<"top10Percent" | "aboveAverage" | "bottomQuartile" | "outliersTwoSigma" | "negativeOnly", "statisticalPresetTop10" | "statisticalPresetAboveAverage" | "statisticalPresetBottomQuartile" | "statisticalPresetOutliers" | "statisticalPresetNegative" | "statisticalPresetOutsideRange" | "statisticalPresetRowsOne" | "statisticalPresetRowsMany" | "statisticalPresetsTitle" | "statisticalPresetsChoices" | "statisticalPresetsNoValues">>;
```

---

### `StatisticalPresetsCaptionId`

```ts
export type StatisticalPresetsCaptionId = keyof typeof STATISTICAL_PRESETS_LOCALIZATION.captions;
```

---

### `StatisticalPresetsMessageValues`

```ts
export type StatisticalPresetsMessageValues = Readonly<Record<string, string | number>>;
```

---

### `createCalendarRangeStructuredFilterType`

Creates an opt-in calendar range with calendar/date presentation options.

```ts
export function createCalendarRangeStructuredFilterType(
  options?: CalendarRangeOptions,
): StructuredFilterType;
```

---

### `calendarRangeStructuredFilterType`

```ts
calendarRangeStructuredFilterType: StructuredFilterType;
```

---

### `parseCalendarRangeValue`

```ts
export function parseCalendarRangeValue(value: unknown): CalendarRangeFilterValue | undefined;
```

---

### `calendarRangeStateFromConditions`

```ts
export function calendarRangeStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
): CalendarRangeState;
```

---

### `calendarDateFilterStateFromConditions`

```ts
export function calendarDateFilterStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
  operators: readonly CalendarDateOperator[] = CALENDAR_DATE_OPERATORS,
): CalendarDateFilterState;
```

---

### `calendarRangeCondition`

Returns no value for a partial/invalid range so callers cannot accidentally clear or commit it.

```ts
export function calendarRangeCondition(
  from: string | undefined,
  to: string | undefined,
  conditionId?: number,
): StructuredFilterCondition[] | undefined;
```

---

### `calendarDateCondition`

```ts
export function calendarDateCondition(
  operator: CalendarDateOperator,
  from: string | undefined,
  to?: string,
  conditionId?: number,
): StructuredFilterCondition[] | undefined;
```

---

### `resolveCalendarRangeOptions`

```ts
export function resolveCalendarRangeOptions(
  column: ColumnRegular,
  settings: ResolvedDateFilterSettings,
  options: CalendarRangeOptions = {},
): ResolvedCalendarRangeOptions;
```

---

### `validateCalendarRangeSelection`

```ts
export function validateCalendarRangeSelection(
  from: ISODateString,
  to: ISODateString,
  options: ResolvedCalendarRangeOptions,
): { readonly range: CalendarRangeFilterValue; readonly reason?: CalendarRangeValidationFailure | string };
```

---

### `formatCalendarRangeLabel`

Shared compact/full presentation used by calendar chips, headers, badges, and tooltips.

```ts
export function formatCalendarRangeLabel(
  range: CalendarRangeFilterValue,
  options: ResolvedCalendarRangeOptions,
  compact = true,
);
```

---

### `formatCalendarDateConditionLabel`

```ts
export function formatCalendarDateConditionLabel(
  operator: CalendarDateOperator,
  range: CalendarRangeFilterValue,
  options: ResolvedCalendarRangeOptions,
  compact = true,
);
```

---

### `isCalendarRangeDateDisabled`

```ts
export function isCalendarRangeDateDisabled(date: ISODateString, options: ResolvedCalendarRangeOptions);
```

---

### `calendarRangeMonthDates`

```ts
export function calendarRangeMonthDates(month: string, weekStartsOn: number);
```

---

### `calendarRangeToday`

```ts
export function calendarRangeToday(timeZone: string, now = new Date()): ISODateString;
```

---

### `calendarRangeKeyboardDate`

```ts
export function calendarRangeKeyboardDate(
  date: ISODateString,
  key: string,
  weekStartsOn: number,
  isDisabled: (date: ISODateString) => boolean = () => false,
): ISODateString | undefined;
```

---

### `createCalendarRangeFilters`

```ts
export function createCalendarRangeFilters(
  runtime: TemporalFilterRuntime = new TemporalFilterRuntime(),
): Record<CalendarDateOperator, CustomFilter>;
```

---

### `FILTER_CALENDAR_RANGE`

```ts
FILTER_CALENDAR_RANGE: string;
```

---

### `CalendarRangeFilterValue`

```ts
interface CalendarRangeFilterValue {
  readonly from: ISODateString;
  readonly to: ISODateString;
  readonly inclusive: true
}
```

---

### `CalendarRangeFormatContext`

```ts
interface CalendarRangeFormatContext {
  readonly column: ColumnRegular;
  readonly locale: string;
  readonly timeZone: string
}
```

---

### `CalendarRangeCalendarOptions`

```ts
export type CalendarRangeCalendarOptions = Omit<CalendarProps,
  | 'month'
  | 'focusedDate'
  | 'referenceDate'
  | 'selection'
  | 'preview'
  | 'locale'
  | 'weekStartsOn'
  | 'minDate'
  | 'maxDate'
  | 'isDateDisabled'
  | 'onMonthChange'
  | 'onFocusedDateChange'
  | 'onSelect'
  | 'onPreviewDateChange'
>;
```

---

### `CalendarRangeValidationContext` (Extended from `index.ts`)

```ts
interface CalendarRangeValidationContext {
  readonly operator: CalendarDateOperator;
  readonly isDateDisabled: (date: ISODateString) => boolean
}
```

---

### `CalendarRangeValidationOptions`

```ts
interface CalendarRangeValidationOptions {
  /** Inclusive minimum number of selected calendar days. */
    readonly minDays?: number;
  /** Inclusive maximum number of selected calendar days. */
    readonly maxDays?: number;
  /** Defaults to true for compatibility. */
    readonly allowSameDay?: boolean;
  /** Defaults to true for compatibility with ranges spanning unavailable dates. */
    readonly allowDisabledDates?: boolean;
  readonly validate?: (
      range: CalendarRangeFilterValue,
      context: CalendarRangeValidationContext,
    ) => boolean | string
}
```

---

### `CalendarRangeValidationFailure`

```ts
export type CalendarRangeValidationFailure =
  | 'sameDay'
  | 'tooShort'
  | 'tooLong'
  | 'containsDisabledDate'
  | 'invalid';
```

---

### `CalendarRangeOptions`

```ts
interface CalendarRangeOptions {
  /** Ordered operator allow-list. Defaults to between plus all single-date operators. */
    readonly operators?: readonly CalendarDateOperator[];
  /** Dates that cannot be selected, either as ISO date-only values or a predicate. */
    readonly disabledDates?: readonly string[] | ((date: ISODateString, context: CalendarRangeFormatContext) => boolean);
  /** Sunday is 0 and Saturday is 6. Inherits `filter.date` when omitted. */
    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  /** IANA timezone used to resolve today's calendar date. Inherits `filter.date` when omitted. */
    readonly timeZone?: string;
  readonly locale?: string;
  /** Earliest selectable date, inclusive. */
    readonly minDate?: ISODateString;
  /** Latest selectable date, inclusive. */
    readonly maxDate?: ISODateString;
  /** Shows adjacent-month dates instead of preserving empty month geometry. */
    readonly showOutsideDays?: boolean;
  /** Allows visible adjacent-month dates to be selected. */
    readonly allowOutsideMonthSelection?: boolean;
  /** Keeps a stable six-week grid when true. Defaults to true. */
    readonly fixedWeeks?: boolean;
  /** Adds a compact Today action below the month. */
    readonly showTodayButton?: boolean;
  /** Independent shared-calendar configuration. Nested values override compatible flat aliases. */
    readonly calendar?: CalendarRangeCalendarOptions;
  readonly showOperator?: boolean;
  readonly showSelectionSummary?: boolean;
  readonly showClearButton?: boolean;
  readonly showCalendar?: boolean;
  readonly rangeValidation?: CalendarRangeValidationOptions;
  readonly onInvalidRange?: (
      range: CalendarRangeFilterValue,
      reason: CalendarRangeValidationFailure | string,
      context: CalendarRangeValidationContext,
    ) => void;
  /** Intl options used by the selected-range chip. */
    readonly dateFormat?: Intl.DateTimeFormatOptions;
  /** Overrides selected-range date labels. */
    readonly formatDate?: (date: ISODateString, context: CalendarRangeFormatContext) => string
}
```

---

### `ResolvedCalendarRangeOptions` (Extended from `index.ts`)

```ts
interface ResolvedCalendarRangeOptions {
  readonly operators: readonly CalendarDateOperator[];
  readonly disabledDates: ReadonlySet<string> | CalendarRangeOptions['disabledDates'];
  readonly weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  readonly dateFormat: Intl.DateTimeFormatOptions;
  readonly formatDate?: CalendarRangeOptions['formatDate'];
  readonly minDate?: ISODateString;
  readonly maxDate?: ISODateString;
  readonly showOutsideDays: boolean;
  readonly allowOutsideMonthSelection: boolean;
  readonly fixedWeeks: boolean;
  readonly showTodayButton: boolean;
  readonly calendar: CalendarRangeCalendarOptions;
  readonly showOperator: boolean;
  readonly showSelectionSummary: boolean;
  readonly showClearButton: boolean;
  readonly showCalendar: boolean;
  readonly rangeValidation: Required<Pick<CalendarRangeValidationOptions,
      'allowSameDay' | 'allowDisabledDates'
    >> & Pick<CalendarRangeValidationOptions, 'minDays' | 'maxDays' | 'validate'>;
  readonly onInvalidRange?: CalendarRangeOptions['onInvalidRange']
}
```

---

### `CalendarRangeState`

```ts
interface CalendarRangeState {
  readonly range?: CalendarRangeFilterValue;
  readonly conditionId?: number;
  readonly active: boolean
}
```

---

### `CalendarDateFilterState` (Extended from `index.ts`)

```ts
interface CalendarDateFilterState {
  readonly operator: CalendarDateOperator
}
```

---

### `CALENDAR_RANGE_FILTERS`

```ts
CALENDAR_RANGE_FILTERS: Record<"calendarRangeBetween" | "calendarRangeEquals" | "calendarRangeNotEqual" | "calendarRangeBefore" | "calendarRangeOnOrBefore" | "calendarRangeAfter" | "calendarRangeOnOrAfter", CustomFilter<any, LogicFunctionExtraParam>>;
```

---

### `isCalendarDateOperator`

```ts
export function isCalendarDateOperator(value: unknown): value is CalendarDateOperator;
```

---

### `resolveCalendarDateOperators`

```ts
export function resolveCalendarDateOperators(
  operators: readonly CalendarDateOperator[] | undefined,
): readonly CalendarDateOperator[];
```

---

### `CALENDAR_RANGE_BETWEEN`

```ts
CALENDAR_RANGE_BETWEEN: string;
```

---

### `CALENDAR_DATE_OPERATOR_SEMANTICS`

```ts
CALENDAR_DATE_OPERATOR_SEMANTICS: Readonly<{ readonly calendarRangeEquals: "equals"; readonly calendarRangeNotEqual: "notEqual"; readonly calendarRangeBefore: "before"; readonly calendarRangeOnOrBefore: "onOrBefore"; readonly calendarRangeAfter: "after"; readonly calendarRangeOnOrAfter: "onOrAfter"; }>;
```

---

### `CALENDAR_DATE_SINGLE_OPERATORS`

```ts
CALENDAR_DATE_SINGLE_OPERATORS: ("calendarRangeEquals" | "calendarRangeNotEqual" | "calendarRangeBefore" | "calendarRangeOnOrBefore" | "calendarRangeAfter" | "calendarRangeOnOrAfter")[];
```

---

### `CALENDAR_DATE_OPERATORS`

```ts
CALENDAR_DATE_OPERATORS: readonly ["calendarRangeBetween", ...("calendarRangeEquals" | "calendarRangeNotEqual" | "calendarRangeBefore" | "calendarRangeOnOrBefore" | "calendarRangeAfter" | "calendarRangeOnOrAfter")[]];
```

---

### `CalendarDateSingleOperator`

```ts
export type CalendarDateSingleOperator = keyof typeof CALENDAR_DATE_OPERATOR_SEMANTICS;
```

---

### `CalendarDateOperator`

```ts
export type CalendarDateOperator = typeof CALENDAR_DATE_OPERATORS[number];
```

---

### `defineCalendarRangeEditor`

```ts
export function defineCalendarRangeEditor(
  host: HTMLElement,
  context: StructuredFilterBodyContext,
  options?: CalendarRangeOptions,
);
```

---

### `CalendarRangeEditor`

```ts
export function CalendarRangeEditor({
  context,
  options,
}: {
  context: StructuredFilterBodyContext;
  options?: CalendarRangeOptions;
});
```

---

### `calendarRangeCaption`

```ts
export function calendarRangeCaption(
  labels: StructuredFilterLabels,
  id: CalendarRangeCaptionId,
): string;
```

---

### `CALENDAR_RANGE_LOCALIZATION`

Public localization keys and English fallbacks for the calendar-range filter.

```ts
CALENDAR_RANGE_LOCALIZATION: Readonly<{ filterNames: Readonly<{ calendarRangeBetween: "Is in calendar range"; calendarRangeEquals: "Is on"; calendarRangeNotEqual: "Is not on"; calendarRangeBefore: "Is before"; calendarRangeOnOrBefore: "Is on or before"; calendarRangeAfter: "Is after"; calendarRangeOnOrAfter: "Is on or after"; }>; captions: Readonly<{ calendarRangeTitle: "Calendar range"; calendarRangeOperator: "Date operator"; calendarRangeBetween: "between"; calendarRangeChooseEnd: "Choose end date"; calendarRangeEmpty: "No range selected"; calendarRangeClear: "Clear date range"; calendarRangePreviousMonth: "Previous month"; calendarRangeNextMonth: "Next month"; calendarRangePreviousYear: "Previous year"; calendarRangeNextYear: "Next year"; calendarRangeChooseMonth: "Choose month"; calendarRangeCalendar: "Calendar"; calendarRangeToday: "Today"; calendarRangeInvalid: "Choose a valid range."; calendarRangeSameDay: "Choose two different dates."; calendarRangeTooShort: "Select a longer range."; calendarRangeTooLong: "Select a shorter range."; calendarRangeContainsDisabledDate: "The range contains an unavailable date."; }>; }>;
```

---

### `CalendarRangeCaptionId`

```ts
export type CalendarRangeCaptionId = keyof typeof CALENDAR_RANGE_LOCALIZATION.captions;
```

---

### `createRelativeWindowStructuredFilterType`

Creates the opt-in relative / rolling date-window body.

```ts
export function createRelativeWindowStructuredFilterType(
  options?: RelativeWindowOptions,
): StructuredFilterType;
```

---

### `relativeWindowStructuredFilterType`

```ts
relativeWindowStructuredFilterType: StructuredFilterType;
```

---

### `parseRelativeWindowValue`

```ts
export function parseRelativeWindowValue(value: unknown): RelativeDateWindowExpression | undefined;
```

---

### `relativeWindowStateFromConditions`

```ts
export function relativeWindowStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
): RelativeWindowState;
```

---

### `relativeWindowCondition`

```ts
export function relativeWindowCondition(
  expression: unknown,
  conditionId?: number,
): StructuredFilterCondition[] | undefined;
```

---

### `resolveRelativeWindowPreview`

```ts
export function resolveRelativeWindowPreview(
  today: ISODateString,
  expression: RelativeDateWindowExpression,
  settings: Pick<ResolvedDateFilterSettings, 'weekStartsOn' | 'fiscalYearStart'>,
): RelativeDateWindowRange | undefined;
```

---

### `createRelativeWindowFilters`

```ts
export function createRelativeWindowFilters(
  runtime: TemporalFilterRuntime = new TemporalFilterRuntime(),
): Record<typeof RELATIVE_WINDOW_OPERATOR, CustomFilter>;
```

---

### `FILTER_RELATIVE_WINDOW`

```ts
FILTER_RELATIVE_WINDOW: string;
```

---

### `RELATIVE_WINDOW_OPERATOR`

```ts
RELATIVE_WINDOW_OPERATOR: string;
```

---

### `RelativeWindowState`

```ts
interface RelativeWindowState {
  readonly active: boolean;
  readonly expression?: RelativeDateWindowExpression;
  readonly conditionId?: number;
  readonly invalid?: boolean
}
```

---

### `RELATIVE_WINDOW_FILTERS`

```ts
RELATIVE_WINDOW_FILTERS: Record<"relativeWindow", CustomFilter<any, LogicFunctionExtraParam>>;
```

---

### `defineRelativeWindowEditor`

```ts
export function defineRelativeWindowEditor(
  host: HTMLElement,
  context: StructuredFilterBodyContext,
  options?: RelativeWindowOptions,
);
```

---

### `RelativeWindowEditor`

```ts
export function RelativeWindowEditor({
  context,
  options,
}: {
  context: StructuredFilterBodyContext;
  options?: RelativeWindowOptions;
});
```

---

### `relativeWindowCaption`

```ts
export function relativeWindowCaption(labels: StructuredFilterLabels, id: RelativeWindowCaptionId);
```

---

### `relativeWindowMessage`

```ts
export function relativeWindowMessage(
  labels: StructuredFilterLabels,
  id: RelativeWindowCaptionId,
  values: RelativeWindowMessageValues = {},
);
```

---

### `relativeWindowPresetCaption`

```ts
export function relativeWindowPresetCaption(
  labels: StructuredFilterLabels,
  preset: RelativeDateWindowPreset,
);
```

---

### `relativeWindowUnitCaption`

```ts
export function relativeWindowUnitCaption(
  labels: StructuredFilterLabels,
  unit: RelativeDateWindowUnit,
  amount: number,
);
```

---

### `relativeWindowRollingDetail`

```ts
export function relativeWindowRollingDetail(labels: StructuredFilterLabels);
```

---

### `RELATIVE_WINDOW_LOCALIZATION`

```ts
RELATIVE_WINDOW_LOCALIZATION: Readonly<{ filterNames: Readonly<{ relativeWindow: "Is in relative window"; }>; detailFallbacks: Readonly<{ rolling: "Rolling"; }>; captions: Readonly<{ relativeWindowLast7Days: "Last 7 days"; relativeWindowToday: "Today"; relativeWindowThisMonth: "This month"; relativeWindowThisQuarter: "This quarter"; relativeWindowYtd: "YTD"; relativeWindowOverdue: "Overdue"; relativeWindowBeforeDate: "Before {date}"; relativeWindowInvalidPreview: "Choose a valid window"; relativeWindowTitle: "Relative / rolling window"; relativeWindowDescription: "Filter dates relative to the current day."; relativeWindowEmpty: "No window selected"; relativeWindowInvalidSaved: "The saved relative window is invalid. Choose a new window or clear it."; relativeWindowClear: "Clear"; relativeWindowPresets: "Date presets"; relativeWindowCustom: "Custom window"; relativeWindowDirection: "Direction"; relativeWindowLast: "Last"; relativeWindowNext: "Next"; relativeWindowAmount: "Amount"; relativeWindowUnit: "Unit"; relativeWindowDay: "day"; relativeWindowDays: "Days"; relativeWindowWeek: "week"; relativeWindowWeeks: "Weeks"; relativeWindowMonth: "month"; relativeWindowMonths: "Months"; relativeWindowQuarter: "quarter"; relativeWindowQuarters: "Quarters"; relativeWindowYear: "year"; relativeWindowYears: "Years"; relativeWindowRolling: "Rolling (re-evaluate daily)"; relativeWindowInvalidAmount: "Enter a whole number greater than zero."; relativeWindowCustomSummary: "{direction} {amount} {unit}"; }>; }>;
```

---

### `RELATIVE_WINDOW_PRESET_CAPTIONS`

```ts
RELATIVE_WINDOW_PRESET_CAPTIONS: Readonly<Record<RelativeDateWindowPreset, "relativeWindowLast7Days" | "relativeWindowToday" | "relativeWindowThisMonth" | "relativeWindowThisQuarter" | "relativeWindowYtd" | "relativeWindowOverdue" | "relativeWindowBeforeDate" | "relativeWindowInvalidPreview" | "relativeWindowTitle" | "relativeWindowDescription" | "relativeWindowEmpty" | "relativeWindowInvalidSaved" | "relativeWindowClear" | "relativeWindowPresets" | "relativeWindowCustom" | "relativeWindowDirection" | "relativeWindowLast" | "relativeWindowNext" | "relativeWindowAmount" | "relativeWindowUnit" | "relativeWindowDay" | "relativeWindowDays" | "relativeWindowWeek" | "relativeWindowWeeks" | "relativeWindowMonth" | "relativeWindowMonths" | "relativeWindowQuarter" | "relativeWindowQuarters" | "relativeWindowYear" | "relativeWindowYears" | "relativeWindowRolling" | "relativeWindowInvalidAmount" | "relativeWindowCustomSummary">>;
```

---

### `RelativeWindowCaptionId`

```ts
export type RelativeWindowCaptionId = keyof typeof RELATIVE_WINDOW_LOCALIZATION.captions;
```

---

### `RelativeWindowMessageValues`

```ts
export type RelativeWindowMessageValues = Readonly<Record<string, string | number>>;
```

---

### `resolveRelativeWindowOptions`

```ts
export function resolveRelativeWindowOptions(
  options?: RelativeWindowOptions,
): ResolvedRelativeWindowOptions;
```

---

### `relativeWindowExpressionKey`

```ts
export function relativeWindowExpressionKey(expression: RelativeDateWindowExpression): string;
```

---

### `DEFAULT_RELATIVE_WINDOW_PRESETS`

```ts
DEFAULT_RELATIVE_WINDOW_PRESETS: readonly RelativeDateWindowPreset[];
```

---

### `RelativeWindowShortcut`

A user-defined shortcut button backed by a valid, stable relative-window expression.

```ts
interface RelativeWindowShortcut {
  readonly id: string;
  readonly label: string;
  readonly expression: RelativeDateWindowExpression;
  readonly ariaLabel?: string;
  readonly title?: string;
  readonly disabled?: boolean
}
```

---

### `RelativeWindowPresetOption`

```ts
export type RelativeWindowPresetOption = RelativeDateWindowPreset | RelativeWindowShortcut;
```

---

### `RelativeWindowCustomWindowOptions`

```ts
interface RelativeWindowCustomWindowOptions {
  readonly directions?: readonly RelativeDateWindowDirection[];
  readonly units?: readonly RelativeDateWindowUnit[];
  readonly showRolling?: boolean;
  readonly defaultValue?: Readonly<{
      direction: RelativeDateWindowDirection;
      amount: number;
      unit: RelativeDateWindowUnit;
      rolling: boolean;
    }>
}
```

---

### `RelativeWindowOptions`

```ts
interface RelativeWindowOptions {
  readonly locale?: string;
  readonly dateFormat?: Intl.DateTimeFormatOptions;
  /** Built-in preset ids and custom shortcuts, in display order. `false` hides the shortcut group. */
    readonly presets?: false | readonly RelativeWindowPresetOption[];
  /** Custom last/next editor configuration. `false` hides the custom editor. */
    readonly customWindow?: false | RelativeWindowCustomWindowOptions;
  readonly showHeading?: boolean;
  readonly showPreview?: boolean
}
```

---

### `ResolvedRelativeWindowShortcut` (Extended from `index.ts`)

```ts
interface ResolvedRelativeWindowShortcut {
  readonly builtInPreset?: RelativeDateWindowPreset
}
```

---

### `ResolvedRelativeWindowCustomWindow`

```ts
interface ResolvedRelativeWindowCustomWindow {
  readonly directions: readonly RelativeDateWindowDirection[];
  readonly units: readonly RelativeDateWindowUnit[];
  readonly showRolling: boolean;
  readonly defaultValue: Extract<RelativeDateWindowExpression, { mode: 'custom' }>
}
```

---

### `ResolvedRelativeWindowOptions`

```ts
interface ResolvedRelativeWindowOptions {
  readonly locale?: string;
  readonly dateFormat?: Intl.DateTimeFormatOptions;
  readonly presets: readonly ResolvedRelativeWindowShortcut[];
  readonly customWindow: false | ResolvedRelativeWindowCustomWindow;
  readonly showHeading: boolean;
  readonly showPreview: boolean
}
```

---

### `createTimelineBrushStructuredFilterType`

Creates an opt-in temporal histogram/brush with deterministic presentation options.

```ts
export function createTimelineBrushStructuredFilterType(
  options?: TimelineBrushOptions,
): StructuredFilterType;
```

---

### `timelineBrushStructuredFilterType`

```ts
timelineBrushStructuredFilterType: StructuredFilterType;
```

---

### `timelineModelFromPreparedData`

```ts
export function timelineModelFromPreparedData(
  value: unknown,
  granularity: TimelineBrushGranularity,
): TimelineBrushModel | undefined;
```

---

### `resolveTimelineBrushOptions`

```ts
export function resolveTimelineBrushOptions(
  column: ColumnRegular,
  settings: ResolvedDateFilterSettings,
  options: TimelineBrushOptions = {},
): ResolvedTimelineBrushOptions;
```

---

### `timelineBrushFamily`

```ts
export function timelineBrushFamily(values: readonly unknown[], column: ColumnRegular): TemporalFilterFamily;
```

---

### `parseTimelineBrushPoints`

```ts
export function parseTimelineBrushPoints(
  values: readonly unknown[],
  family: TemporalFilterFamily,
  timeZone: string,
): readonly TimelineBrushPoint[];
```

---

### `createTimelineBrushModel`

```ts
export function createTimelineBrushModel(
  values: readonly unknown[],
  family: TemporalFilterFamily,
  options: Pick<ResolvedTimelineBrushOptions, 'granularity' | 'binCap' | 'timeZone'> & {
    weekStartsOn?: ResolvedTimelineBrushOptions['weekStartsOn'];
    fiscalYearStart?: ResolvedTimelineBrushOptions['fiscalYearStart'];
  },
): TimelineBrushModel;
```

---

### `parseTimelineBetweenValue`

```ts
export function parseTimelineBetweenValue(value: unknown): TimelineBetweenValue | undefined;
```

---

### `timelineBrushStateFromConditions`

```ts
export function timelineBrushStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
  model: TimelineBrushModel,
): TimelineBrushState;
```

---

### `timelineBrushCondition`

```ts
export function timelineBrushCondition(
  start: number,
  end: number,
  model: TimelineBrushModel,
  conditionId?: number,
): StructuredFilterCondition[];
```

---

### `timelineBrushPosition`

```ts
export function timelineBrushPosition(index: number, binCount: number);
```

---

### `timelineBrushIndex`

```ts
export function timelineBrushIndex(position: number, binCount: number);
```

---

### `timelineBrushBinSelected`

```ts
export function timelineBrushBinSelected(index: number, start: number, end: number);
```

---

### `formatTimelineBrushLabel`

```ts
export function formatTimelineBrushLabel(
  value: string,
  options: ResolvedTimelineBrushOptions,
  includeYear = true,
);
```

---

### `createTimelineBrushFilters`

```ts
export function createTimelineBrushFilters(
  runtime: TemporalFilterRuntime = new TemporalFilterRuntime(),
): Record<typeof TIMELINE_BETWEEN, CustomFilter>;
```

---

### `FILTER_TIMELINE_BRUSH`

```ts
FILTER_TIMELINE_BRUSH: string;
```

---

### `TIMELINE_BETWEEN`

```ts
TIMELINE_BETWEEN: string;
```

---

### `TIMELINE_BRUSH_STEPS`

```ts
TIMELINE_BRUSH_STEPS: 1000;
```

---

### `TimelineBrushGranularity`

```ts
export type TimelineBrushGranularity = 'day' | 'week' | 'month' | 'year' | 'fiscalYear';
```

---

### `TimelineBetweenValue`

```ts
interface TimelineBetweenValue {
  readonly from: string;
  readonly to: string;
  readonly inclusive: true
}
```

---

### `TimelineBrushFormatContext`

```ts
interface TimelineBrushFormatContext {
  readonly column: ColumnRegular;
  readonly granularity: TimelineBrushGranularity;
  readonly locale: string;
  readonly timeZone: string;
  readonly weekStartsOn: ResolvedDateFilterSettings['weekStartsOn'];
  readonly fiscalYearStart: ResolvedDateFilterSettings['fiscalYearStart']
}
```

---

### `TimelineBrushOptions`

```ts
interface TimelineBrushOptions {
  /** Initial calendar resolution. Falls back to the first enabled granularity. */
    readonly granularity?: TimelineBrushGranularity;
  /** Calendar resolutions that users can select. Defaults to day, week, month, and year. */
    readonly granularities?: readonly TimelineBrushGranularity[];
  /** Maximum number of rendered bars after deterministic coarsening. Defaults to 48. */
    readonly binCap?: number;
  /** IANA timezone used for calendar bins and labels. Inherits `filter.date`. */
    readonly timeZone?: string;
  /**
     * Intl options or a callback for boundary and selection labels. Omit this to
     * use compact month/day labels within one year and two-digit years across years.
     * An explicit value is used verbatim.
     */
    readonly format?: Intl.DateTimeFormatOptions | ((value: string, context: TimelineBrushFormatContext) => string);
  readonly locale?: string;
  /** Presentation-only chart configuration. Filtering and prepared-data contracts are unchanged. */
    readonly chart?: TimelineBrushChartOptions
}
```

---

### `TimelineBrushChartTooltipContext` (Extended from `index.ts`)

```ts
interface TimelineBrushChartTooltipContext {
  readonly index: number;
  readonly selected: boolean;
  readonly fromLabel: string;
  readonly toLabel: string
}
```

---

### `TimelineBrushChartOptions`

```ts
interface TimelineBrushChartOptions {
  readonly type?: DistributionChartType;
  readonly height?: number;
  readonly showPoints?: boolean;
  readonly formatTooltip?: (
      bin: TimelineBrushBin,
      context: TimelineBrushChartTooltipContext,
    ) => DistributionChartTooltip
}
```

---

### `ResolvedTimelineBrushOptions` (Extended from `index.ts`)

```ts
interface ResolvedTimelineBrushOptions {
  readonly binCap: number;
  readonly granularities: readonly TimelineBrushGranularity[];
  readonly format: NonNullable<TimelineBrushOptions['format']>;
  /** Whether `format` is the adaptive built-in default rather than a user override. */
    readonly usesDefaultFormat: boolean
}
```

---

### `TimelineBrushPoint`

```ts
interface TimelineBrushPoint {
  readonly instant: Date;
  readonly date: ISODateString;
  readonly boundary: string
}
```

---

### `TimelineBrushBin`

```ts
interface TimelineBrushBin {
  readonly from: ISODateString;
  readonly to: ISODateString;
  readonly count: number;
  /** Inclusive UTC instants for datetime-family filtering. */
    readonly fromInstant?: string;
  readonly toInstant?: string
}
```

---

### `TimelineBrushModel`

```ts
interface TimelineBrushModel {
  readonly family: TemporalFilterFamily;
  readonly granularity: TimelineBrushGranularity;
  readonly effectiveGranularity: TimelineBrushGranularity;
  readonly bins: readonly TimelineBrushBin[]
}
```

---

### `TimelineBrushPreparedData`

```ts
interface TimelineBrushPreparedData {
  readonly kind: 'timelineBrush';
  readonly models: Partial<Record<TimelineBrushGranularity, TimelineBrushModel>>
}
```

---

### `TimelineBrushState`

```ts
interface TimelineBrushState {
  readonly start: number;
  readonly end: number;
  readonly conditionId?: number
}
```

---

### `TIMELINE_BRUSH_FILTERS`

```ts
TIMELINE_BRUSH_FILTERS: Record<"timelineBetween", CustomFilter<any, LogicFunctionExtraParam>>;
```

---

### `defineTimelineBrushEditor`

```ts
export function defineTimelineBrushEditor(
  host: HTMLElement,
  context: StructuredFilterBodyContext,
  options?: TimelineBrushOptions,
);
```

---

### `TimelineBrushEditor`

```ts
export function TimelineBrushEditor({
  context,
  options,
}: {
  context: StructuredFilterBodyContext;
  options?: TimelineBrushOptions;
});
```

---

### `timelineBrushCaption`

```ts
export function timelineBrushCaption(labels: StructuredFilterLabels, id: TimelineBrushCaptionId);
```

---

### `timelineBrushMessage`

```ts
export function timelineBrushMessage(
  labels: StructuredFilterLabels,
  id: TimelineBrushCaptionId,
  values: TimelineBrushMessageValues = {},
);
```

---

### `timelineGranularityCaption`

```ts
export function timelineGranularityCaption(
  labels: StructuredFilterLabels,
  granularity: TimelineBrushGranularity,
);
```

---

### `TIMELINE_BRUSH_LOCALIZATION`

```ts
TIMELINE_BRUSH_LOCALIZATION: Readonly<{ filterNames: Readonly<{ timelineBetween: "Is in timeline range"; }>; captions: Readonly<{ timelineBrushTitle: "Timeline"; timelineBrushDescription: "Brush a date range over time."; timelineBrushNoRange: "No range selected"; timelineBrushSummary: "{from} → {to} · by {granularity}"; timelineBrushNoValues: "No valid dates available."; timelineBrushItem: "item"; timelineBrushItems: "items"; timelineBrushSelected: "Selected"; timelineBrushOutsideSelection: "Outside selection"; timelineBrushChart: "Timeline distribution"; timelineBrushStart: "Range start"; timelineBrushEnd: "Range end"; timelineBrushGranularity: "Timeline granularity"; timelineBrushDay: "day"; timelineBrushWeek: "week"; timelineBrushMonth: "month"; timelineBrushYear: "year"; timelineBrushFiscalYear: "fiscal year"; }>; }>;
```

---

### `TIMELINE_GRANULARITY_CAPTIONS`

```ts
TIMELINE_GRANULARITY_CAPTIONS: Readonly<Record<TimelineBrushGranularity, "timelineBrushTitle" | "timelineBrushDescription" | "timelineBrushNoRange" | "timelineBrushSummary" | "timelineBrushNoValues" | "timelineBrushItem" | "timelineBrushItems" | "timelineBrushSelected" | "timelineBrushOutsideSelection" | "timelineBrushChart" | "timelineBrushStart" | "timelineBrushEnd" | "timelineBrushGranularity" | "timelineBrushDay" | "timelineBrushWeek" | "timelineBrushMonth" | "timelineBrushYear" | "timelineBrushFiscalYear">>;
```

---

### `TimelineBrushCaptionId`

```ts
export type TimelineBrushCaptionId = keyof typeof TIMELINE_BRUSH_LOCALIZATION.captions;
```

---

### `TimelineBrushMessageValues`

```ts
export type TimelineBrushMessageValues = Readonly<Record<string, string | number>>;
```

---

### `createTimeMatrixStructuredFilterType`

Creates an opt-in weekday/hour matrix with one lossless structured condition.

```ts
export function createTimeMatrixStructuredFilterType(
  options?: TimeMatrixOptions,
): StructuredFilterType;
```

---

### `timeMatrixStructuredFilterType`

```ts
timeMatrixStructuredFilterType: StructuredFilterType;
```

---

### `timeMatrixCellKey`

```ts
export function timeMatrixCellKey(weekday: number, hour: number);
```

---

### `timeMatrixCellSelected`

```ts
export function timeMatrixCellSelected(cells: ReadonlySet<string>, weekday: number, hour: number);
```

---

### `timeMatrixCellsFromRanges`

```ts
export function timeMatrixCellsFromRanges(ranges: readonly TimeMatrixRange[]);
```

---

### `timeMatrixRangesFromCells`

```ts
export function timeMatrixRangesFromCells(cells: ReadonlySet<string>): readonly TimeMatrixRange[];
```

---

### `parseTimeMatrixValue`

```ts
export function parseTimeMatrixValue(value: unknown): TimeMatrixFilterValue | undefined;
```

---

### `timeMatrixStateFromConditions`

```ts
export function timeMatrixStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
): TimeMatrixState;
```

---

### `timeMatrixCondition`

```ts
export function timeMatrixCondition(
  cells: ReadonlySet<string>,
  timeZone: string,
  conditionId?: number,
): StructuredFilterCondition[];
```

---

### `timeMatrixPresetCells`

```ts
export function timeMatrixPresetCells(preset: TimeMatrixPreset | ResolvedTimeMatrixPreset);
```

---

### `timeMatrixCellsEqual`

```ts
export function timeMatrixCellsEqual(left: ReadonlySet<string>, right: ReadonlySet<string>);
```

---

### `timeMatrixSelectionSummary`

```ts
export function timeMatrixSelectionSummary(
  cells: ReadonlySet<string>,
  timeZone: string,
  options: TimeMatrixSelectionSummaryOptions = {},
);
```

---

### `resolveTimeMatrixOptions`

```ts
export function resolveTimeMatrixOptions(
  column: ColumnRegular,
  settings: ResolvedDateFilterSettings,
  options: TimeMatrixOptions = {},
): ResolvedTimeMatrixOptions;
```

---

### `createTimeMatrixFilters`

```ts
export function createTimeMatrixFilters(): Record<typeof TIME_MATRIX_OPERATOR, CustomFilter>;
```

---

### `FILTER_TIME_MATRIX`

```ts
FILTER_TIME_MATRIX: string;
```

---

### `TIME_MATRIX_OPERATOR`

```ts
TIME_MATRIX_OPERATOR: string;
```

---

### `TIME_MATRIX_VERSION`

```ts
TIME_MATRIX_VERSION: 1;
```

---

### `TIME_MATRIX_MAX_INPUT_RANGES`

More ranges are necessarily redundant because the matrix has 168 cells.

```ts
TIME_MATRIX_MAX_INPUT_RANGES: number;
```

---

### `TimeMatrixRange`

```ts
interface TimeMatrixRange {
  /** Sunday is 0 and Saturday is 6. */
    readonly weekday: number;
  /** Inclusive whole-hour boundary. */
    readonly startHour: number;
  /** Exclusive whole-hour boundary. */
    readonly endHour: number
}
```

---

### `TimeMatrixFilterValue`

```ts
interface TimeMatrixFilterValue {
  readonly version: typeof TIME_MATRIX_VERSION;
  readonly timeZone: string;
  readonly ranges: readonly TimeMatrixRange[]
}
```

---

### `TimeMatrixPreset`

```ts
export type TimeMatrixPreset = 'businessHours' | 'weekends' | 'nights';
```

---

### `TimeMatrixPresetWindow`

```ts
interface TimeMatrixPresetWindow {
  /** Optional visible label override for this shortcut. */
    readonly label?: string;
  /** Optional tooltip override describing the configured shortcut. */
    readonly description?: string;
  /** Sunday is 0 and Saturday is 6. */
    readonly days?: readonly number[];
  /** Inclusive whole-hour boundary. */
    readonly startHour?: number;
  /** Exclusive whole-hour boundary. Values before startHour create an overnight window. */
    readonly endHour?: number
}
```

---

### `TimeMatrixPresetOptions`

```ts
interface TimeMatrixPresetOptions {
  readonly businessHours?: false | TimeMatrixPresetWindow;
  readonly weekends?: false | Omit<TimeMatrixPresetWindow, 'startHour' | 'endHour'>;
  readonly nights?: false | TimeMatrixPresetWindow
}
```

---

### `ResolvedTimeMatrixPreset`

```ts
interface ResolvedTimeMatrixPreset {
  readonly id: TimeMatrixPreset;
  readonly days: readonly number[];
  readonly startHour: number;
  readonly endHour: number;
  readonly label?: string;
  readonly description?: string
}
```

---

### `TimeMatrixWorkingHours`

```ts
interface TimeMatrixWorkingHours {
  /** Inclusive whole-hour boundary. */
    readonly startHour: number;
  /** Exclusive whole-hour boundary. */
    readonly endHour: number
}
```

---

### `TimeMatrixOptions`

```ts
interface TimeMatrixOptions {
  /** IANA timezone used for matching. Inherits the column's date settings. */
    readonly timeZone?: string;
  readonly locale?: string;
  /** Sunday is 0 and Saturday is 6. Inherits the column's date settings. */
    readonly weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  readonly useAmPm?: boolean;
  /** Context shading only; filtering remains driven by the selected cells. */
    readonly workingHours?: false | TimeMatrixWorkingHours;
  /** Sunday is 0 and Saturday is 6. Defaults to both. */
    readonly weekendDays?: readonly number[];
  /** Hides schedule-context legend without changing matrix behavior. */
    readonly showLegend?: boolean;
  /** Configure each built-in shortcut, use false per shortcut to hide it, or false to hide all. */
    readonly presets?: false | TimeMatrixPresetOptions
}
```

---

### `ResolvedTimeMatrixOptions`

```ts
interface ResolvedTimeMatrixOptions {
  readonly column: ColumnRegular;
  readonly timeZone: string;
  readonly locale: string;
  readonly weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  readonly useAmPm: boolean;
  readonly workingHours?: TimeMatrixWorkingHours;
  readonly weekendDays: readonly number[];
  readonly showLegend: boolean;
  readonly presets: readonly ResolvedTimeMatrixPreset[]
}
```

---

### `TimeMatrixState`

```ts
interface TimeMatrixState {
  readonly value?: TimeMatrixFilterValue;
  readonly conditionId?: number
}
```

---

### `TimeMatrixSelectionSummaryOptions`

```ts
interface TimeMatrixSelectionSummaryOptions {
  readonly weekdayLabel?: (weekday: number) => string;
  readonly hourLabel?: (hour: number) => string;
  readonly message?: (id: TimeMatrixCaptionId, values: TimeMatrixMessageValues) => string
}
```

---

### `TIME_MATRIX_FILTERS`

```ts
TIME_MATRIX_FILTERS: Record<"timeMatrix", CustomFilter<any, LogicFunctionExtraParam>>;
```

---

### `defineTimeMatrixEditor`

```ts
export function defineTimeMatrixEditor(
  host: HTMLElement,
  context: StructuredFilterBodyContext,
  options?: TimeMatrixOptions,
);
```

---

### `TimeMatrixEditor`

```ts
export function TimeMatrixEditor({
  context,
  options,
}: {
  context: StructuredFilterBodyContext;
  options?: TimeMatrixOptions;
});
```

---

### `createTimeMatrixHeaderTemplate`

Creates the non-interactive schedule summary rendered inside the shared popup trigger.

```ts
export function createTimeMatrixHeaderTemplate(
  options: TimeMatrixHeaderTemplateOptions,
): FilterHeaderTemplateFunc;
```

---

### `TimeMatrixHeaderTemplateOptions`

```ts
interface TimeMatrixHeaderTemplateOptions {
  readonly labels: StructuredFilterLabels;
  readonly hourLabel: (hour: number) => string;
  readonly weekStartsOn: number
}
```

---

### `timeMatrixCaption`

```ts
export function timeMatrixCaption(
  labels: StructuredFilterLabels,
  id: TimeMatrixCaptionId,
): string;
```

---

### `timeMatrixMessage`

```ts
export function timeMatrixMessage(
  labels: StructuredFilterLabels,
  id: TimeMatrixCaptionId,
  values: TimeMatrixMessageValues = {},
): string;
```

---

### `timeMatrixFallbackMessage`

```ts
export function timeMatrixFallbackMessage(
  id: TimeMatrixCaptionId,
  values: TimeMatrixMessageValues = {},
): string;
```

---

### `timeMatrixWeekdayCaption`

```ts
export function timeMatrixWeekdayCaption(
  labels: StructuredFilterLabels,
  weekday: number,
);
```

---

### `timeMatrixFallbackWeekdayCaption`

```ts
export function timeMatrixFallbackWeekdayCaption(weekday: number);
```

---

### `TIME_MATRIX_LOCALIZATION`

Stable localization keys and complete English fallbacks for the activity-time matrix.

```ts
TIME_MATRIX_LOCALIZATION: Readonly<{ filterNames: Readonly<{ timeMatrix: "Matches time matrix"; }>; captions: Readonly<{ timeMatrixAriaTitle: "Time-of-day and weekday matrix"; timeMatrixTitle: "Time-of-day / weekday"; timeMatrixDescription: "Select the weekday and hour combinations to include."; timeMatrixGrid: "Weekday by hour selection"; timeMatrixClear: "Clear"; timeMatrixPresets: "Time presets"; timeMatrixLegend: "Schedule context"; timeMatrixLegendSelected: "Selected"; timeMatrixLegendOutsideWorkHours: "Outside work hours"; timeMatrixLegendWeekend: "Weekend"; timeMatrixCellLabel: "{day}, {start}–{end}, {state}"; timeMatrixCellStateSelected: "selected"; timeMatrixCellStateNotSelected: "not selected"; timeMatrixWeekdayShortSunday: "Sun"; timeMatrixWeekdayShortMonday: "Mon"; timeMatrixWeekdayShortTuesday: "Tue"; timeMatrixWeekdayShortWednesday: "Wed"; timeMatrixWeekdayShortThursday: "Thu"; timeMatrixWeekdayShortFriday: "Fri"; timeMatrixWeekdayShortSaturday: "Sat"; timeMatrixSummaryEmpty: "No times selected"; timeMatrixWeekdayRange: "{start}–{end}"; timeMatrixSummaryRange: "{days}, {start}–{end} selected"; timeMatrixSummaryHoursOneDay: "{hours} hours across {days} day · {timeZone}"; timeMatrixSummaryHoursManyDays: "{hours} hours across {days} days · {timeZone}"; timeMatrixHeaderAnyTime: "Any time"; timeMatrixHeaderEveryDay: "Every day"; timeMatrixHeaderAllDay: "All day"; timeMatrixHeaderRange: "{start}–{end}"; timeMatrixHeaderCustomDays: "{days} days"; timeMatrixHeaderCustomHours: "{hours} hours · Custom"; timeMatrixBadgeSummaryOne: "1 hour selected"; timeMatrixBadgeSummaryMany: "{hours} hours selected"; timeMatrixBadgeDetails: "{selection} · {timeZone}"; 'timeMatrixPreset.businessHours': "Business hours"; 'timeMatrixPreset.weekends': "Weekends"; 'timeMatrixPreset.nights': "Nights"; 'timeMatrixPresetDescription.businessHours': "Mon–Fri, 08:00–20:00"; 'timeMatrixPresetDescription.weekends': "Saturday and Sunday"; 'timeMatrixPresetDescription.nights': "Every day, 22:00–06:00"; }>; }>;
```

---

### `TimeMatrixCaptionId`

```ts
export type TimeMatrixCaptionId = keyof typeof TIME_MATRIX_LOCALIZATION.captions;
```

---

### `TimeMatrixMessageValues`

```ts
export type TimeMatrixMessageValues = Readonly<Record<string, string | number>>;
```

---

### `triStateBooleanStructuredFilterType`

```ts
triStateBooleanStructuredFilterType: {
  id: string;
  operatorIds: string[];
  aggregateNeeds: "valueCounts"[];
  validateValue: typeof isValidTriStateBooleanValue;
  mount: (host: HTMLElement, context: StructuredFilterBodyContext) => PreactRootDisposer;
  describeCondition: ({ condition, labels }: StructuredFilterPresentationContext) => { details?: string | undefined; summary: string; } | undefined;
  render: (context: StructuredFilterBodyContext) => any;
};
```

---

### `isValidTriStateBooleanValue`

Checks the exact transport shape emitted for an active boolean condition.

```ts
export function isValidTriStateBooleanValue(value: unknown): value is TriStateBooleanFilterValue;
```

---

### `parseTriStateBooleanValue`

Restores only the JSON-safe state emitted by this structured filter.

```ts
export function parseTriStateBooleanValue(value: unknown): TriStateBooleanState;
```

---

### `triStateBooleanStateFromConditions`

```ts
export function triStateBooleanStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
): TriStateBooleanState;
```

---

### `triStateBooleanCondition`

```ts
export function triStateBooleanCondition(
  state: TriStateBooleanChoice,
  coerceBlank: boolean,
  conditionId?: number,
): StructuredFilterCondition[];
```

---

### `triStateBooleanMatches`

```ts
export function triStateBooleanMatches(
  value: LogicFunctionParam,
  state: TriStateBooleanChoice,
  coerceBlank: boolean,
  context?: FilterEvaluationContext,
);
```

---

### `FILTER_TRI_STATE_BOOLEAN`

```ts
FILTER_TRI_STATE_BOOLEAN: string;
```

---

### `TRI_STATE_BOOLEAN_OPERATOR`

```ts
TRI_STATE_BOOLEAN_OPERATOR: string;
```

---

### `TRI_STATE_BOOLEAN_CHOICES`

```ts
TRI_STATE_BOOLEAN_CHOICES: readonly ["all", "yes", "no"];
```

---

### `TriStateBooleanChoice`

```ts
export type TriStateBooleanChoice = typeof TRI_STATE_BOOLEAN_CHOICES[number];
```

---

### `TriStateBooleanFilterValue`

```ts
interface TriStateBooleanFilterValue {
  readonly state: Exclude<TriStateBooleanChoice, 'all'>;
  readonly coerceBlank: boolean
}
```

---

### `TriStateBooleanState`

```ts
interface TriStateBooleanState {
  readonly state: TriStateBooleanChoice;
  readonly coerceBlank: boolean;
  readonly conditionId?: number
}
```

---

### `triStateBoolean`

```ts
triStateBoolean: LogicFunction<any, LogicFunctionExtraParam>;
```

---

### `TRI_STATE_BOOLEAN_FILTERS`

```ts
TRI_STATE_BOOLEAN_FILTERS: {
  [TRI_STATE_BOOLEAN_OPERATOR]: { columnFilterType: string; name: "Is Yes or No"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `defineTriStateBooleanEditor`

```ts
export function defineTriStateBooleanEditor(host: HTMLElement, context: StructuredFilterBodyContext);
```

---

### `TriStateBooleanEditor`

```ts
export function TriStateBooleanEditor({ context }: { context: StructuredFilterBodyContext });
```

---

### `arrayTagsStructuredFilterType`

```ts
arrayTagsStructuredFilterType: {
  id: string;
  operatorIds: string[];
  aggregateNeeds: "values"[];
  validateValue: typeof isValidArrayTagsFilterValue;
  describeCondition: ({ condition, column, config, labels }: StructuredFilterPresentationContext) => { summary: string; details: string; };
  getHeaderSelection: ({ condition, column, config, aggregates, labels }: StructuredFilterHeaderSelectionContext) => { values: { value: string; label: string; count: number; }[]; totalCount: number; } | undefined;
  mount: (host: HTMLElement, context: StructuredFilterBodyContext) => PreactRootDisposer;
  render: (context: StructuredFilterBodyContext) => any;
};
```

---

### `resolveArrayTagsAccessor`

```ts
export function resolveArrayTagsAccessor(
  options: ArrayTagsOptions | undefined,
  property: ColumnProp,
): ArrayTagsAccessor;
```

---

### `resolveArrayTagsLabelFormatter`

```ts
export function resolveArrayTagsLabelFormatter(
  options: ArrayTagsOptions | undefined,
  property: ColumnProp,
): ArrayTagsLabelFormatter | undefined;
```

---

### `isArrayTagValue`

```ts
export function isArrayTagValue(value: unknown): value is ArrayTagValue;
```

---

### `arrayTagId`

JSON-safe typed identity; labels do not participate in equality.

```ts
export function arrayTagId(value: ArrayTagValue);
```

---

### `arrayTagLabel`

```ts
export function arrayTagLabel(
  value: ArrayTagValue,
  labels: ArrayTagLabelText = DEFAULT_ARRAY_TAG_LABEL_TEXT,
);
```

---

### `arrayTagLabels`

Keeps compact labels unless typed-distinct values would look identical.

```ts
export function arrayTagLabels(
  values: readonly ArrayTagValue[],
  labels: ArrayTagLabelText = DEFAULT_ARRAY_TAG_LABEL_TEXT,
  formatLabel?: (value: ArrayTagValue) => string | undefined,
);
```

---

### `normalizeArrayTags`

Removes unsupported values and duplicates while retaining first-seen order.

```ts
export function normalizeArrayTags(values: readonly unknown[]);
```

---

### `flattenArrayTagValues`

```ts
export function flattenArrayTagValues(
  cellValues: readonly unknown[],
  accessor: ArrayTagsAccessor = value => value,
  property: ColumnProp = '',
  column?: FilterEvaluationContext['column'],
  limit = Number.POSITIVE_INFINITY,
);
```

---

### `isValidArrayTagsFilterValue`

Checks the lossless transport shape before canonical state is replaced.

```ts
export function isValidArrayTagsFilterValue(value: unknown): value is ArrayTagsFilterValue;
```

---

### `parseArrayTagsFilterValue`

Restores only the JSON-safe shape emitted by this filter.

```ts
export function parseArrayTagsFilterValue(value: unknown): ArrayTagsFilterValue;
```

---

### `arrayTagsStateFromConditions`

```ts
export function arrayTagsStateFromConditions(
  conditions: readonly Readonly<{ id?: unknown; type: string; value?: unknown }>[],
): ArrayTagsState;
```

---

### `arrayTagsCondition`

```ts
export function arrayTagsCondition(
  value: ArrayTagsFilterValue,
  conditionId?: number,
): StructuredFilterCondition[];
```

---

### `arrayTagsMatches`

```ts
export function arrayTagsMatches(
  cellValue: unknown,
  filterValue: unknown,
  accessor: ArrayTagsAccessor = value => value,
  context?: FilterEvaluationContext,
);
```

---

### `createArrayTagsFilters`

```ts
export function createArrayTagsFilters(options?: ArrayTagsOptions): Record<typeof ARRAY_TAGS_MATCH, CustomFilter>;
```

---

### `FILTER_ARRAY_TAGS`

```ts
FILTER_ARRAY_TAGS: string;
```

---

### `ARRAY_TAGS_MATCH`

```ts
ARRAY_TAGS_MATCH: string;
```

---

### `ARRAY_TAGS_MODES`

```ts
ARRAY_TAGS_MODES: readonly ["any", "all", "none"];
```

---

### `ARRAY_TAGS_OPTION_LIMIT`

Keeps a high-cardinality column from creating an unbounded tag picker.

```ts
ARRAY_TAGS_OPTION_LIMIT: 200;
```

---

### `ArrayTagsMode`

```ts
export type ArrayTagsMode = typeof ARRAY_TAGS_MODES[number];
```

---

### `ArrayTagValue`

```ts
export type ArrayTagValue = string | number | boolean | null;
```

---

### `ArrayTagsFilterValue`

```ts
interface ArrayTagsFilterValue {
  readonly mode: ArrayTagsMode;
  readonly values: readonly ArrayTagValue[];
  readonly emptyOnly: boolean;
  readonly exact: boolean
}
```

---

### `ArrayTagsState` (Extended from `index.ts`)

```ts
interface ArrayTagsState {
  readonly conditionId?: number
}
```

---

### `ArrayTagsAccessorContext`

```ts
interface ArrayTagsAccessorContext {
  readonly property: ColumnProp;
  readonly column?: FilterEvaluationContext['column'];
  readonly model?: FilterEvaluationContext['model']
}
```

---

### `ArrayTagsAccessor`

Returns the array whose members should be treated as tags for one cell.

```ts
/** Returns the array whose members should be treated as tags for one cell. */
export type ArrayTagsAccessor = (
  cellValue: unknown,
  context: ArrayTagsAccessorContext,
) => unknown;
```

---

### `ArrayTagsFormatLabelContext`

```ts
interface ArrayTagsFormatLabelContext {
  readonly property: ColumnProp;
  readonly column?: FilterEvaluationContext['column']
}
```

---

### `ArrayTagsLabelFormatter`

Presents one stored scalar tag without changing its typed filter identity.

```ts
/** Presents one stored scalar tag without changing its typed filter identity. */
export type ArrayTagsLabelFormatter = (
  value: ArrayTagValue,
  context: ArrayTagsFormatLabelContext,
) => string | undefined;
```

---

### `ArrayTagsColumnOptions`

```ts
interface ArrayTagsColumnOptions {
  readonly accessor?: ArrayTagsAccessor;
  readonly formatLabel?: ArrayTagsLabelFormatter
}
```

---

### `ArrayTagsOptions`

```ts
interface ArrayTagsOptions {
  readonly accessor?: ArrayTagsAccessor;
  readonly formatLabel?: ArrayTagsLabelFormatter;
  readonly columns?: Readonly<Record<string, ArrayTagsColumnOptions>>
}
```

---

### `ArrayTagLabelText`

```ts
interface ArrayTagLabelText {
  readonly blank: string;
  readonly true: string;
  readonly false: string;
  readonly stringType: string;
  readonly numberType: string;
  readonly booleanType: string;
  readonly nullType: string
}
```

---

### `DEFAULT_ARRAY_TAG_LABEL_TEXT`

```ts
DEFAULT_ARRAY_TAG_LABEL_TEXT: {
  blank: string;
  true: string;
  false: string;
  stringType: string;
  numberType: string;
  booleanType: string;
  nullType: string;
};
```

---

### `ARRAY_TAGS_FILTERS`

```ts
ARRAY_TAGS_FILTERS: Record<"arrayTagsMatch", CustomFilter<any, LogicFunctionExtraParam>>;
```

---

### `defineArrayTagsEditor`

```ts
export function defineArrayTagsEditor(host: HTMLElement, context: StructuredFilterBodyContext);
```

---

### `ArrayTagsEditor`

```ts
export function ArrayTagsEditor({ context }: { context: StructuredFilterBodyContext });
```

---

### `arrayTagsCaption`

```ts
export function arrayTagsCaption(labels: StructuredFilterLabels, id: ArrayTagsCaptionId);
```

---

### `arrayTagsMessage`

```ts
export function arrayTagsMessage(labels: StructuredFilterLabels, id: ArrayTagsCaptionId, values: StructuredFilterMessageValues = {});
```

---

### `ARRAY_TAGS_LOCALIZATION`

```ts
ARRAY_TAGS_LOCALIZATION: Readonly<{ filterNames: Readonly<{ arrayTagsMatch: "Matches array tags"; }>; captions: Readonly<{ arrayTagsHeaderPlaceholder: "Any tags"; arrayTagsBlank: "Blank"; arrayTagsTrue: "True"; arrayTagsFalse: "False"; arrayTagsTypeString: "string"; arrayTagsTypeNumber: "number"; arrayTagsTypeBoolean: "boolean"; arrayTagsTypeNull: "blank"; arrayTagsStringType: "string"; arrayTagsNumberType: "number"; arrayTagsBooleanType: "boolean"; arrayTagsBlankType: "blank"; arrayTagsTitle: "Array / tags"; arrayTagsDescription: "Choose tags and how each cell array should match them."; arrayTagsMode: "Tag match mode"; arrayTagsAny: "has any"; arrayTagsAll: "has all"; arrayTagsNone: "has none"; arrayTagsModeAny: "any"; arrayTagsModeAll: "all"; arrayTagsModeNone: "none"; arrayTagsAvailable: "Available tags"; arrayTagsNoValues: "No tags found in array values."; arrayTagsEmptyOnly: "Empty list only"; arrayTagsExact: "Exact set match"; arrayTagsSelected: "{summary}"; arrayTagsSelectedEmpty: "Empty arrays only"; arrayTagsSelectedOne: "1 tag selected"; arrayTagsSelectedMany: "{count} tags selected"; arrayTagsEmptyListsOnly: "empty lists only"; arrayTagsExactSet: "exact set"; arrayTagsSummaryOne: "1 tag"; arrayTagsSummaryMany: "{count} tags"; }>; }>;
```

---

### `ArrayTagsCaptionId`

```ts
export type ArrayTagsCaptionId = keyof typeof ARRAY_TAGS_LOCALIZATION.captions;
```

---

### `BUILT_IN_STRUCTURED_FILTER_TYPES`

Built-ins are registered by the Pro filter plugin but remain column opt-in.

```ts
BUILT_IN_STRUCTURED_FILTER_TYPES: readonly StructuredFilterType[];
```

---

### `formatGroupedFilterMessage`

```ts
export function formatGroupedFilterMessage(
  template: string,
  values: Readonly<Record<string, string | number>> = {},
);
```

---

### `groupedFilterMessage`

```ts
export function groupedFilterMessage(
  translations: GroupedFilterTranslations,
  key: GroupedFilterLabelKey,
  values?: Readonly<Record<string, string | number>>,
);
```

---

### `resolveGroupedFilterTranslations`

```ts
export function resolveGroupedFilterTranslations(
  captions?: Readonly<Record<string, unknown>>,
  overrides: GroupedFilterTranslationOverrides = {},
): GroupedFilterTranslations;
```

---

### `DEFAULT_GROUPED_FILTER_LABELS`

```ts
DEFAULT_GROUPED_FILTER_LABELS: { readonly launcher: "Groups"; readonly noConditions: "No filter conditions"; readonly builderAria: "Grouped filter builder"; readonly title: "Grouped filter"; readonly description: "Build a reusable canonical filter tree."; readonly incompatibleShape: "This filter cannot be edited with the selected layout ({path})."; readonly ruleOne: "{count} rule"; readonly ruleMany: "{count} rules"; readonly groupOne: "{count} group"; readonly groupMany: "{count} groups"; readonly countSeparator: " · "; readonly matchCount: "{matching} of {total} rows"; readonly viewAria: "Grouped filter view"; readonly rulesView: "Rules"; readonly textView: "Text"; readonly expressionMirrorAria: "Filter expression mirror"; readonly readableSummary: "Readable summary"; readonly readableSummaryDescription: "Read-only summary of the rules"; readonly reset: "Reset"; readonly cancel: "Cancel"; readonly apply: "Apply"; readonly applying: "Applying…"; readonly rootGroupAria: "Root filter group matching {quantifier} rules"; readonly nestedGroupAria: "Nested filter group matching {quantifier} rules"; readonly logicToggleAria: "Match {quantifier} rules. Switch to {nextQuantifier}"; readonly quantifierAll: "all"; readonly quantifierAny: "any"; readonly logicAnd: "AND"; readonly logicOr: "OR"; readonly logicNot: "NOT"; readonly rootInstruction: "Keep rows where these rules match"; readonly group: "Group"; readonly quantifierCount: "{quantifier} of {count}"; readonly inverted: "Inverted"; readonly invert: "Invert"; readonly removeGroup: "Remove group"; readonly emptyGroup: "Add a condition or group to begin."; readonly addCondition: "Add condition"; readonly addGroup: "Add group"; readonly fieldAria: "Filter field"; readonly operatorAria: "Filter operator"; readonly removeCondition: "Remove condition"; readonly clearCondition: "Clear {field} filter"; readonly applyCondition: "Apply {field} filter"; readonly clearAll: "Clear all"; readonly activeConditionCount: "{active} of {total} filters active"; readonly reorderHandle: "Reorder item {position} of {count}"; readonly reorderInstructions: "Drag to reorder. Press Alt+Arrow Up or Alt+Arrow Down to move within this group."; readonly reorderMoved: "Item reordered."; readonly fromValue: "From value"; readonly toValue: "To value"; readonly commaSeparatedValuesAria: "Comma-separated values"; readonly listPlaceholder: "value 1, value 2"; readonly editorUnavailable: "Editor unavailable for this value"; readonly filterValueAria: "Filter value"; readonly removeValueAria: "Remove {label}"; readonly addValueAria: "Add filter value"; readonly addValuePlaceholder: "Add…"; readonly searchValuesPlaceholder: "Search values…"; readonly valuesListAria: "Filter values"; readonly booleanTrue: "true"; readonly booleanFalse: "false"; readonly valuePlaceholder: "value"; readonly negatedOperator: "does not {label}"; readonly previewRemote: "Rows update on Apply"; readonly previewUpdating: "Updating preview…"; readonly previewTooLarge: "Apply to count matches"; };
```

---

### `DEFAULT_GROUPED_OPERATOR_SENTENCE_LABELS`

```ts
DEFAULT_GROUPED_OPERATOR_SENTENCE_LABELS: {
  equal: string;
  notEqual: string;
  beginsWith: string;
  contains: string;
  quickContains: string;
  notContains: string;
  greaterThan: string;
  greaterThanOrEqual: string;
  lessThan: string;
  lessThanOrEqual: string;
  between: string;
  in: string;
  notIn: string;
  isBlank: string;
  isNotBlank: string;
  isTrue: string;
  isFalse: string;
  isEmptyArray: string;
  isNotEmptyArray: string;
  dateEquals: string;
  dateNotEqual: string;
  dateBefore: string;
  dateAfter: string;
  dateOnOrBefore: string;
  dateOnOrAfter: string;
  dateBetween: string;
  today: string;
  yesterday: string;
  last7Days: string;
  next30Days: string;
  thisWeek: string;
  lastWeek: string;
  nextWeek: string;
  thisMonth: string;
  lastMonth: string;
  thisQuarter: string;
  nextQuarter: string;
  previousQuarter: string;
  thisYear: string;
  nextYear: string;
  previousYear: string;
};
```

---

### `DEFAULT_GROUPED_OPERATOR_SUMMARY_LABELS`

```ts
DEFAULT_GROUPED_OPERATOR_SUMMARY_LABELS: {
  equal: string;
  notEqual: string;
  beginsWith: string;
  contains: string;
  quickContains: string;
  notContains: string;
  greaterThan: string;
  greaterThanOrEqual: string;
  lessThan: string;
  lessThanOrEqual: string;
  between: string;
  in: string;
  notIn: string;
  isBlank: string;
  isNotBlank: string;
  isTrue: string;
  isFalse: string;
  isEmptyArray: string;
  isNotEmptyArray: string;
};
```

---

### `DEFAULT_GROUPED_NEGATED_SENTENCE_LABELS`

```ts
DEFAULT_GROUPED_NEGATED_SENTENCE_LABELS: {
  beginsWith: string;
};
```

---

### `DEFAULT_GROUPED_FILTER_VALIDATION_MESSAGES`

```ts
DEFAULT_GROUPED_FILTER_VALIDATION_MESSAGES: { readonly invalidNode: "The filter rule is incomplete or malformed."; readonly maxDepth: "The filter contains too many nested groups."; readonly cycle: "The filter contains a circular group reference."; readonly invalidGroupOperator: "Choose whether this group matches all rules or any rule."; readonly emptyGroup: "Add at least one condition to this group."; readonly missingChild: "Add a condition or group after NOT."; readonly invalidDiscriminator: "The filter contains an unsupported rule type."; readonly invalidField: "Choose a field for this rule."; readonly invalidOperator: "{field}: choose a filter operator."; readonly unknownOperator: "{field}: “{operator}” is not a supported filter."; readonly invalidValueType: "{field}: “{operator}” uses an unsupported value type."; readonly unexpectedValue: "{field}: “{operator}” does not accept a value."; readonly missingValue: "{field}: enter a value for “{operator}”."; readonly invalidArrayValue: "{field}: enter {requirement} for “{operator}”."; readonly valueTypeMismatch: "{field}: enter a valid {valueType} value for “{operator}”."; readonly nonFiniteNumber: "{field}: enter a finite number for “{operator}”."; readonly nonJsonValue: "{field}: the value for “{operator}” cannot be saved."; readonly valueCycle: "{field}: the value for “{operator}” contains a circular reference."; readonly nonPlainObject: "{field}: the value for “{operator}” must be a plain object."; readonly arrayOneOrMore: "one or more values"; readonly arrayExactlyTwo: "two values"; readonly genericField: "{field}: {message}"; readonly generic: "{message}"; };
```

---

### `GroupedFilterLabelKey`

```ts
export type GroupedFilterLabelKey = keyof typeof DEFAULT_GROUPED_FILTER_LABELS;
```

---

### `GroupedFilterLabels`

```ts
export type GroupedFilterLabels = Record<GroupedFilterLabelKey, string>;
```

---

### `GroupedFilterValidationMessageKey`

```ts
export type GroupedFilterValidationMessageKey = keyof typeof DEFAULT_GROUPED_FILTER_VALIDATION_MESSAGES;
```

---

### `GroupedFilterValidationMessages`

```ts
export type GroupedFilterValidationMessages = Record<GroupedFilterValidationMessageKey, string>;
```

---

### `GroupedFilterTranslations`

```ts
interface GroupedFilterTranslations {
  labels: GroupedFilterLabels;
  operatorSentence: Readonly<Partial<Record<FilterAstOperator, string>>>;
  operatorSummary: Readonly<Partial<Record<FilterAstOperator, string>>>;
  negatedOperatorSentence: Readonly<Partial<Record<FilterAstOperator, string>>>;
  validation: GroupedFilterValidationMessages
}
```

---

### `GroupedFilterTranslationOverrides`

```ts
interface GroupedFilterTranslationOverrides {
  labels?: Partial<GroupedFilterLabels>;
  operatorSentence?: Partial<Record<FilterAstOperator, string>>;
  operatorSummary?: Partial<Record<FilterAstOperator, string>>;
  negatedOperatorSentence?: Partial<Record<FilterAstOperator, string>>;
  validation?: Partial<GroupedFilterValidationMessages>
}
```

---

### `DEFAULT_GROUPED_FILTER_TRANSLATIONS`

```ts
DEFAULT_GROUPED_FILTER_TRANSLATIONS: {
  labels: { readonly launcher: "Groups"; readonly noConditions: "No filter conditions"; readonly builderAria: "Grouped filter builder"; readonly title: "Grouped filter"; readonly description: "Build a reusable canonical filter tree."; readonly incompatibleShape: "This filter cannot be edited with the selected layout ({path})."; readonly ruleOne: "{count} rule"; readonly ruleMany: "{count} rules"; readonly groupOne: "{count} group"; readonly groupMany: "{count} groups"; readonly countSeparator: " · "; readonly matchCount: "{matching} of {total} rows"; readonly viewAria: "Grouped filter view"; readonly rulesView: "Rules"; readonly textView: "Text"; readonly expressionMirrorAria: "Filter expression mirror"; readonly readableSummary: "Readable summary"; readonly readableSummaryDescription: "Read-only summary of the rules"; readonly reset: "Reset"; readonly cancel: "Cancel"; readonly apply: "Apply"; readonly applying: "Applying…"; readonly rootGroupAria: "Root filter group matching {quantifier} rules"; readonly nestedGroupAria: "Nested filter group matching {quantifier} rules"; readonly logicToggleAria: "Match {quantifier} rules. Switch to {nextQuantifier}"; readonly quantifierAll: "all"; readonly quantifierAny: "any"; readonly logicAnd: "AND"; readonly logicOr: "OR"; readonly logicNot: "NOT"; readonly rootInstruction: "Keep rows where these rules match"; readonly group: "Group"; readonly quantifierCount: "{quantifier} of {count}"; readonly inverted: "Inverted"; readonly invert: "Invert"; readonly removeGroup: "Remove group"; readonly emptyGroup: "Add a condition or group to begin."; readonly addCondition: "Add condition"; readonly addGroup: "Add group"; readonly fieldAria: "Filter field"; readonly operatorAria: "Filter operator"; readonly removeCondition: "Remove condition"; readonly clearCondition: "Clear {field} filter"; readonly applyCondition: "Apply {field} filter"; readonly clearAll: "Clear all"; readonly activeConditionCount: "{active} of {total} filters active"; readonly reorderHandle: "Reorder item {position} of {count}"; readonly reorderInstructions: "Drag to reorder. Press Alt+Arrow Up or Alt+Arrow Down to move within this group."; readonly reorderMoved: "Item reordered."; readonly fromValue: "From value"; readonly toValue: "To value"; readonly commaSeparatedValuesAria: "Comma-separated values"; readonly listPlaceholder: "value 1, value 2"; readonly editorUnavailable: "Editor unavailable for this value"; readonly filterValueAria: "Filter value"; readonly removeValueAria: "Remove {label}"; readonly addValueAria: "Add filter value"; readonly addValuePlaceholder: "Add…"; readonly searchValuesPlaceholder: "Search values…"; readonly valuesListAria: "Filter values"; readonly booleanTrue: "true"; readonly booleanFalse: "false"; readonly valuePlaceholder: "value"; readonly negatedOperator: "does not {label}"; readonly previewRemote: "Rows update on Apply"; readonly previewUpdating: "Updating preview…"; readonly previewTooLarge: "Apply to count matches"; };
  operatorSentence: Readonly<Partial<Record<FilterAstOperator, string>>>;
  operatorSummary: Readonly<Partial<Record<FilterAstOperator, string>>>;
  negatedOperatorSentence: Readonly<Partial<Record<FilterAstOperator, string>>>;
  validation: { readonly invalidNode: "The filter rule is incomplete or malformed."; readonly maxDepth: "The filter contains too many nested groups."; readonly cycle: "The filter contains a circular group reference."; readonly invalidGroupOperator: "Choose whether this group matches all rules or any rule."; readonly emptyGroup: "Add at least one condition to this group."; readonly missingChild: "Add a condition or group after NOT."; readonly invalidDiscriminator: "The filter contains an unsupported rule type."; readonly invalidField: "Choose a field for this rule."; readonly invalidOperator: "{field}: choose a filter operator."; readonly unknownOperator: "{field}: “{operator}” is not a supported filter."; readonly invalidValueType: "{field}: “{operator}” uses an unsupported value type."; readonly unexpectedValue: "{field}: “{operator}” does not accept a value."; readonly missingValue: "{field}: enter a value for “{operator}”."; readonly invalidArrayValue: "{field}: enter {requirement} for “{operator}”."; readonly valueTypeMismatch: "{field}: enter a valid {valueType} value for “{operator}”."; readonly nonFiniteNumber: "{field}: enter a finite number for “{operator}”."; readonly nonJsonValue: "{field}: the value for “{operator}” cannot be saved."; readonly valueCycle: "{field}: the value for “{operator}” contains a circular reference."; readonly nonPlainObject: "{field}: the value for “{operator}” must be a plain object."; readonly arrayOneOrMore: "one or more values"; readonly arrayExactlyTwo: "two values"; readonly genericField: "{field}: {message}"; readonly generic: "{message}"; };
};
```

---

### `between`

```ts
between: LogicFunction<any, SliderRange | undefined>;
```

---

### `notContains`

```ts
notContains: LogicFunction<any, Set<any> | undefined>;
```

---

### `createRangeSliderHeaderControl`

Converts slider-owned state into the abstract filter-header control contract.

```ts
export function createRangeSliderHeaderControl(
  slider: RangeSliderProps,
): Extract<FilterHeaderControl, { kind: 'inline' }>;
```

---

### `RangeSlider`

RangeSlider renders a dual-handle range control for the Pro slider filter.
The slider track and numeric inputs are separate controls that share one
normalized scaled-value state.

```ts
RangeSlider: FunctionalComponent<RangeSliderProps>;
```

---

### `SLIDER_SCALE_FACTOR`

Range inputs can contain decimals while native range inputs work most
predictably with integers. Slider logic stores values as scaled integers and
converts back to numbers only when displaying values or emitting filter state.

```ts
SLIDER_SCALE_FACTOR: 100;
```

---

### `renderRangeSlider`

Renderer shared by the Stencil filter shell and Preact structured editors.

```ts
export function renderRangeSlider(h: RangeSliderElementFactory, props: RangeSliderProps);
```

---

### `PreactRangeSlider`

Preact adapter for the shared slider renderer.

```ts
export function PreactRangeSlider(props: RangeSliderProps);
```

---

### `SingleValueSlider`

Shared native single-thumb slider for scalar thresholds and tolerances.

```ts
export function SingleValueSlider({
  min,
  max,
  value,
  step = 1,
  disabled = false,
  id,
  className = '',
  ariaLabel,
  ariaValueText,
  onChange,
  onCommit,
  onKeyDown,
}: SingleValueSliderProps): any;
```

---

### `SingleValueSliderProps`

```ts
export type SingleValueSliderProps = {
  min: number;
  max: number;
  value: number;
  step?: number | string;
  disabled?: boolean;
  id?: string;
  className?: string;
  ariaLabel: string;
  ariaValueText?: string;
  onChange: (value: number, event: Event & { currentTarget: HTMLInputElement }) => void;
  onCommit?: (value: number, event: Event & { currentTarget: HTMLInputElement }) => void;
  onKeyDown?: (event: KeyboardEvent) => void;
};
```

---

### `mergeFilterConfigs`

```ts
export function mergeFilterConfigs(
  base?: ColumnFilterConfig,
  override?: ColumnFilterConfig,
): ColumnFilterConfig | undefined;
```

---

### `createAdvancedFilterConfig`

```ts
export function createAdvancedFilterConfig(
  config?: ColumnFilterConfig,
  temporalRuntime?: TemporalFilterRuntime,
): ColumnFilterConfig;
```

---

### `createDefaultFilterTypes`

```ts
export function createDefaultFilterTypes(): Record<string, string[]>;
```

---

### `resetFilterConfigState`

```ts
export function resetFilterConfigState(state: {
  filterByType: Record<string, string[]>;
  filterNameIndexByType: Record<string, string>;
  filterFunctionsIndexedByType: Record<string, LogicFunction>;
});
```

---

### `expressionFilterFunction`

```ts
expressionFilterFunction: (value: any, extra?: LogicFunctionExtraParam, context?: FilterEvaluationContext<DataType, ColumnRegular<ColumnProp, DataType<any, ColumnProp>>> | undefined, temporalRuntime?: TemporalFilterRuntime | undefined) => boolean;
```

---

### `ADVANCED_FILTERS`

```ts
ADVANCED_FILTERS: {
  [FIlTER_SELECTION]: { columnFilterType: "none" | "empty" | "notEmpty" | "eq" | "notEq" | "begins" | "contains" | "notContains" | "eqN" | "neqN" | "gt" | "gte" | "lt" | "lte"; name: "none" | "empty" | "notEmpty" | "eq" | "notEq" | "begins" | "contains" | "notContains" | "eqN" | "neqN" | "gt" | "gte" | "lt" | "lte"; func: LogicFunction<any, LogicFunctionExtraParam>; };
  [FIlTER_SLIDER]: { columnFilterType: "none" | "empty" | "notEmpty" | "eq" | "notEq" | "begins" | "contains" | "notContains" | "eqN" | "neqN" | "gt" | "gte" | "lt" | "lte"; name: "none" | "empty" | "notEmpty" | "eq" | "notEq" | "begins" | "contains" | "notContains" | "eqN" | "neqN" | "gt" | "gte" | "lt" | "lte"; func: LogicFunction<any, LogicFunctionExtraParam>; };
  [FIlTER_QUICK_SEARCH]: { columnFilterType: "none" | "empty" | "notEmpty" | "eq" | "notEq" | "begins" | "contains" | "notContains" | "eqN" | "neqN" | "gt" | "gte" | "lt" | "lte"; name: "none" | "empty" | "notEmpty" | "eq" | "notEq" | "begins" | "contains" | "notContains" | "eqN" | "neqN" | "gt" | "gte" | "lt" | "lte"; func: LogicFunction<any, LogicFunctionExtraParam>; };
};
```

---

### `ADVANCED_FILTER_NAMES`

```ts
ADVANCED_FILTER_NAMES: {
  [FIlTER_EXPRESSION]: string;
};
```

---

### `popUpContent`

```ts
popUpContent: (data: ShowData, { multiFilterItems, onFilterItemsChange, subscribeFilterItemsChange, dataStores, isSourceRow, getFilterOptionValue, getItems, searchItems, itemTemplate, optionColumns, optionProgress, quickSearchFilter, grouping, plugins, gridSettings, excelMode, excelCaptions, sortDirection, onApply, onCancel, config, change, onClose, onOpenGrouped, structuredBodies, structuredOperatorIds, }: { multiFilterItems: MultiFilterItem; onFilterItemsChange: ProFilterItemsChangeListener; subscribeFilterItemsChange: ProFilterItemsChangeSubscription; dataStores: RowDataSources; isSourceRow?: ((row?: DataType | undefined) => boolean) | undefined; getFilterOptionValue?: ((row: DataType, column: ColumnRegular<ColumnProp, DataType<any, ColumnProp>>, rowType?: DimensionRows | undefined, rowIndex?: number | undefined) => unknown) | undefined; getItems: () => SelectionItem[] | Promise<SelectionItem[]>; searchItems?: ((search: string, signal: AbortSignal) => Promise<SelectionItem[]>) | undefined; itemTemplate?: SelectionItemTemplate | undefined; optionColumns?: SelectionOptionColumn[] | undefined; optionProgress?: SelectionOptionProgressConfig | undefined; quickSearchFilter?: SelectionQuickSearchFilter | undefined; grouping?: GroupingOptions | undefined; plugins?: typeof BasePlugin[] | undefined; gridSettings?: Partial<{ additionalData: AdditionalData; autoSizeColumn: boolean | AutoSizeColumnConfig; canFocus: boolean; colSize: number; columnTypes: { [name: string]: ColumnType<DataType<any, ColumnProp>>; }; editors: Editors; frameSize: number; hideAttribution: boolean; noHorizontalScrollTransfer: boolean; range: boolean; readonly: boolean; resize: boolean; rowDefinitions: RowDefinition[]; rowHeaders: boolean | RowHeaders; rowSize: number; theme: string; tree: TreeConfig | undefined; useClipboard: boolean | ClipboardConfig; }> | undefined; excelMode?: "windows" | undefined; excelCaptions?: SelectionExcelControlCaptions | undefined; sortDirection?: "none" | "asc" | "desc" | undefined; onApply?: (() => void | Promise<void>) | undefined; onCancel?: (() => void) | undefined; config?: ColumnFilterConfig | undefined; change(filterItems: MultiFilterItem): Promise<void>; onClose?(): void; onOpenGrouped?(): void; structuredBodies?: VNode[] | undefined; structuredOperatorIds?: readonly string[] | undefined; }) => any;
```

---

### `popUpBottomContent`

```ts
popUpBottomContent: (data: ShowData, options: { multiFilterItems: MultiFilterItem; onFilterItemsChange: ProFilterItemsChangeListener; subscribeFilterItemsChange: ProFilterItemsChangeSubscription; getItems: () => SelectionItem[] | Promise<SelectionItem[]>; expressionColumns?: ExpressionColumnReference[] | undefined; expressionRows?: readonly DataType[] | undefined; getExpressionValue?(row: DataType, column: ExpressionColumnReference): unknown; config?: ColumnFilterConfig | undefined; change(filterItems: MultiFilterItem, changedProp?: ColumnProp | undefined): Promise<void>; }) => any;
```

---

### `FilterPopupTransactionMode`

```ts
export type FilterPopupTransactionMode = 'staged' | 'excel';
```

---

### `FilterPopupTransaction`

Owns one popup draft and its current-column commit boundary.

```ts
class FilterPopupTransaction {
  owns(filterItems: MultiFilterItem);

  mergeInto(canonical: MultiFilterItem);
}
```

---

### `hasMeaningfulFilterValue`

```ts
export function hasMeaningfulFilterValue(value: unknown);
```

---

### `hasActiveFiltersForColumn`

```ts
export function hasActiveFiltersForColumn(
  columnProp: ColumnProp | undefined,
  multiFilterItems: MultiFilterItem,
);
```

---

### `isActiveFilter`

```ts
export function isActiveFilter(filter: FilterData);
```

---

### `getNextFilterItemId`

Allocates a filter id that cannot collide with any existing column item.

```ts
export function getNextFilterItemId(items: MultiFilterItem);
```

---

### `cloneFilterItems`

Deep-clones the mutable filter model used by popup editors.

```ts
export function cloneFilterItems(items: MultiFilterItem): MultiFilterItem;
```

---

### `mergeFilterColumn`

Commits only one popup column into the latest canonical model. Other columns
deliberately retain their current references so concurrent changes survive.

```ts
export function mergeFilterColumn(
  current: MultiFilterItem,
  draft: MultiFilterItem,
  prop: ColumnProp,
): MultiFilterItem;
```

---

### `FilterHeaderTemplateValue`

```ts
export type FilterHeaderTemplateValue = {
  value: string;
  label: string;
  count: number;
};
```

---

### `FilterHeaderPresentation`

Plain-text state retained by the grid-owned accessible trigger shell.

```ts
interface FilterHeaderPresentation {
  active: boolean;
  summary: string;
  details?: string
}
```

---

### `FilterHeaderTemplateProps`

Shared visual-template contract for every popup-style filter header.

```ts
/** Shared visual-template contract for every popup-style filter header. */
export type FilterHeaderTemplateProps = {
  column: ColumnRegular;
  columnProp: ColumnProp;
  conditions: readonly Readonly<FilterData>[];
  presentation: FilterHeaderPresentation;
  /** @deprecated Use `presentation.active`. */
  active: boolean;
  /** @deprecated Use `presentation.summary`. */
  text: string;
  /** Selection-only compatibility data. */
  values: FilterHeaderTemplateValue[];
  /** Selection-only compatibility data. */
  totalCount?: number;
  /** Selection-only compatibility option. */
  showCount: boolean;
};
```

---

### `FilterHeaderTemplateFunc`

Renders non-interactive content inside the grid-owned filter button.
Return `undefined` to use the standard accessible text/count fallback.

```ts
/**
 * Renders non-interactive content inside the grid-owned filter button.
 * Return `undefined` to use the standard accessible text/count fallback.
 */
export type FilterHeaderTemplateFunc = (
  h: HyperFunc<any>,
  props: FilterHeaderTemplateProps,
) => VNodeResponse;
```

---

### `FilterHeaderInlineTemplateFunc`

Renders an interactive control inside the grid-owned filter-header boundary.

```ts
/** Renders an interactive control inside the grid-owned filter-header boundary. */
export type FilterHeaderInlineTemplateFunc = FilterHeaderTemplateFunc;
```

---

### `FilterHeaderControl`

Filter-type-owned header presentation. The grid retains the outer layout,
accessibility, popup trigger, and interaction boundary.

```ts
/**
 * Filter-type-owned header presentation. The grid retains the outer layout,
 * accessibility, popup trigger, and interaction boundary.
 */
export type FilterHeaderControl =
  | {
      readonly kind: 'popup';
      /** Optional visual content rendered inside the accessible popup trigger. */
      readonly template?: FilterHeaderTemplateFunc;
    }
  | {
      readonly kind: 'inline';
      /** Interactive control rendered inside the shared non-sorting boundary. */
      readonly template: FilterHeaderInlineTemplateFunc;
      /** Optional stable class retained for type-specific presentation. */
      readonly className?: string;
    };
```

---

### `FilterHeaderTriggerState` (Extended from `header-template.types.ts`)

```ts
export type FilterHeaderTriggerState = Omit<
  FilterHeaderTemplateProps,
  'column' | 'columnProp' | 'conditions' | 'presentation'
> & {
  conditions?: FilterHeaderTemplateProps['conditions'];
  presentation?: FilterHeaderPresentation;
};
```

---

### `renderFilterPopupHeader`

```ts
export function renderFilterPopupHeader(
  data: ShowData,
  {
    multiFilterItems,
    active,
    captions,
    onClose,
  }: FilterPopupHeaderOptions,
);
```

---

### `FilterPopupHeaderOptions`

```ts
export type FilterPopupHeaderOptions = {
  multiFilterItems: MultiFilterItem;
  active?: boolean;
  captions?: Partial<FilterCaptions>;
  onClose?(): void;
};
```

---

### `isValuelessFilterType`

```ts
export function isValuelessFilterType(type: unknown);
```

---

### `VALUELESS_FILTER_TYPES`

```ts
VALUELESS_FILTER_TYPES: Set<string>;
```

---

### `bindFilterPanelBoundary`

Isolates popup inputs from the host grid and owns popup dismissal listeners.

```ts
export function bindFilterPanelBoundary(
  panel: HTMLRevogrFilterPanelElement,
  {
    onDismiss,
    onEscape,
  }: {
    onDismiss: () => void;
    onEscape: () => void;
  },
);
```

---

### `renderPopupConditions`

```ts
export function renderPopupConditions(
  data: ShowData,
  {
    multiFilterItems,
    config,
    change,
    onFilterItemsChange,
    excludedTypes = [],
  }: {
    multiFilterItems: MultiFilterItem;
    config?: ColumnFilterConfig;
    change(filterItems: MultiFilterItem): Promise<void>;
    onFilterItemsChange: ProFilterItemsChangeListener;
    excludedTypes?: readonly string[];
  },
);
```

---

### `mountPreactRoot`

Owns one manually mounted Preact root and guarantees its effects are disposed.

```ts
export function mountPreactRoot(host: HTMLElement, child: ComponentChild): PreactRootDisposer;
```

---

### `disposableElementRef`

Bridges an outer renderer's nullable element ref to one disposable nested root.

```ts
export function disposableElementRef(
  mount: (host: HTMLElement) => void | PreactRootDisposer,
);
```

---

### `PreactRootDisposer`

```ts
export type PreactRootDisposer = () => void;
```

---

### `isFilterOptionSourceRow`

```ts
export function isFilterOptionSourceRow(row?: DataType);
```

---

### `getFilterOptionSourceRows`

```ts
export function getFilterOptionSourceRows(
  stores: RowDataSources,
  sourceRowTypes?: DimensionRows[],
): DataType[];
```

---

### `compileExpressionFilter`

```ts
export function compileExpressionFilter(
  text: string,
  context: ExpressionColumnContext,
): ExpressionCompileResult;
```

---

### `normalizeExpressionConfig`

Normalizes the public expression config into one internal shape with defaults.

Returns `undefined` when expressions are disabled so callers can keep opt-in
rendering, filter registration, and stale-state cleanup behind one predicate.

```ts
export function normalizeExpressionConfig(
  config?: ColumnFilterConfig['expressions'],
): NormalizedExpressionConfig | undefined;
```

---

### `evaluateExpression`

```ts
export function evaluateExpression(
  ast: ExpressionAst,
  value: unknown,
  context?: FilterEvaluationContext,
  temporalRuntime?: TemporalFilterRuntime,
): boolean;
```

---

### `expressionFilter`

```ts
expressionFilter: (value: unknown, extra?: ExpressionFilterValue | undefined, context?: FilterEvaluationContext<DataType, ColumnRegular<ColumnProp, DataType<any, ColumnProp>>> | undefined, temporalRuntime?: TemporalFilterRuntime | undefined) => boolean;
```

---

### `ExpressionHighlight`

```ts
export function ExpressionHighlight({
  text,
  diagnostics = [],
  className = '',
}: {
  text: string;
  diagnostics?: ExpressionDiagnostic[];
  className?: string;
});
```

---

### `highlightExpression`

```ts
export function highlightExpression(text: string, diagnostics: ExpressionDiagnostic[] = []);
```

---

### `serializeExpressionLiteral`

Serializes JSON-safe filter state as a readable, typed expression literal.

```ts
export function serializeExpressionLiteral(value: unknown): string;
```

---

### `isCoreFilterType`

```ts
export function isCoreFilterType(value: string): value is FilterType;
```

---

### `isExpressionOperator`

```ts
export function isExpressionOperator(value: string): value is ExpressionOperator;
```

---

### `EXPRESSION_FILTER_OPERATORS`

```ts
EXPRESSION_FILTER_OPERATORS: { readonly empty: "empty"; readonly notEmpty: "notEmpty"; readonly eq: "eq"; readonly notEq: "notEq"; readonly begins: "begins"; readonly contains: "contains"; readonly notContains: "notContains"; readonly eqN: "eqN"; readonly neqN: "neqN"; readonly gt: "gt"; readonly gte: "gte"; readonly lt: "lt"; readonly lte: "lte"; };
```

---

### `EXPRESSION_DATE_OPERATORS`

```ts
EXPRESSION_DATE_OPERATORS: { readonly equals: "equals"; readonly before: "before"; readonly after: "after"; readonly onOrBefore: "onOrBefore"; readonly onOrAfter: "onOrAfter"; readonly between: "between"; readonly notEqual: "notEqual"; readonly isEmpty: "isEmpty"; readonly isNotEmpty: "isNotEmpty"; readonly today: "today"; readonly yesterday: "yesterday"; readonly last7Days: "last7Days"; readonly next30Days: "next30Days"; readonly thisWeek: "thisWeek"; readonly lastWeek: "lastWeek"; readonly nextWeek: "nextWeek"; readonly thisMonth: "thisMonth"; readonly lastMonth: "lastMonth"; readonly thisQuarter: "thisQuarter"; readonly nextQuarter: "nextQuarter"; readonly previousQuarter: "previousQuarter"; readonly thisYear: "thisYear"; readonly nextYear: "nextYear"; readonly previousYear: "previousYear"; readonly thisFiscalQuarter: "thisFiscalQuarter"; readonly nextFiscalQuarter: "nextFiscalQuarter"; readonly previousFiscalQuarter: "previousFiscalQuarter"; readonly thisFiscalYear: "thisFiscalYear"; readonly nextFiscalYear: "nextFiscalYear"; readonly previousFiscalYear: "previousFiscalYear"; };
```

---

### `EXPRESSION_SELECTION_OPERATORS`

```ts
EXPRESSION_SELECTION_OPERATORS: { readonly is: "is"; readonly in: "in"; readonly notIn: "notIn"; };
```

---

### `EXPRESSION_ARRAY_OPERATORS`

```ts
EXPRESSION_ARRAY_OPERATORS: { readonly isEmptyArray: "isEmptyArray"; readonly isNotEmptyArray: "isNotEmptyArray"; };
```

---

### `EXPRESSION_STRUCTURED_OPERATOR`

Exact transport form used by structured filter bodies in Expression mode.

```ts
EXPRESSION_STRUCTURED_OPERATOR: string;
```

---

### `EXPRESSION_SYMBOL_OPERATORS`

```ts
EXPRESSION_SYMBOL_OPERATORS: { readonly '=': "eq"; readonly '!=': "notEq"; readonly '>': "gt"; readonly '>=': "gte"; readonly '<': "lt"; readonly '<=': "lte"; };
```

---

### `ExpressionFilterOperator`

```ts
export type ExpressionFilterOperator =
  | typeof EXPRESSION_FILTER_OPERATORS[keyof typeof EXPRESSION_FILTER_OPERATORS]
  | typeof EXPRESSION_DATE_OPERATORS[keyof typeof EXPRESSION_DATE_OPERATORS]
  | typeof EXPRESSION_SELECTION_OPERATORS[keyof typeof EXPRESSION_SELECTION_OPERATORS]
  | typeof EXPRESSION_ARRAY_OPERATORS[keyof typeof EXPRESSION_ARRAY_OPERATORS]
  | typeof EXPRESSION_STRUCTURED_OPERATOR;
```

---

### `ExpressionSymbolOperator`

```ts
export type ExpressionSymbolOperator = keyof typeof EXPRESSION_SYMBOL_OPERATORS;
```

---

### `ExpressionOperator`

```ts
export type ExpressionOperator = ExpressionFilterOperator | ExpressionSymbolOperator;
```

---

### `DATE_PERIOD_PHRASES`

```ts
DATE_PERIOD_PHRASES: { readonly today: "today"; readonly yesterday: "yesterday"; readonly 'last 7 days': "last7Days"; readonly 'next 30 days': "next30Days"; readonly 'this week': "thisWeek"; readonly 'last week': "lastWeek"; readonly 'next week': "nextWeek"; readonly 'this month': "thisMonth"; readonly 'last month': "lastMonth"; readonly 'this quarter': "thisQuarter"; readonly 'next quarter': "nextQuarter"; readonly 'previous quarter': "previousQuarter"; readonly 'this year': "thisYear"; readonly 'next year': "nextYear"; readonly 'previous year': "previousYear"; readonly 'this fiscal quarter': "thisFiscalQuarter"; readonly 'next fiscal quarter': "nextFiscalQuarter"; readonly 'previous fiscal quarter': "previousFiscalQuarter"; readonly 'this fiscal year': "thisFiscalYear"; readonly 'next fiscal year': "nextFiscalYear"; readonly 'previous fiscal year': "previousFiscalYear"; };
```

---

### `VALUELESS_OPERATORS`

```ts
VALUELESS_OPERATORS: Set<ExpressionOperator>;
```

---

### `LIST_OPERATORS`

```ts
LIST_OPERATORS: Set<ExpressionOperator>;
```

---

### `NUMERIC_OPERATORS`

```ts
NUMERIC_OPERATORS: Set<ExpressionOperator>;
```

---

### `DATE_OPERATORS`

```ts
DATE_OPERATORS: Set<ExpressionOperator>;
```

---

### `SELECTION_OPERATORS`

```ts
SELECTION_OPERATORS: Set<ExpressionOperator>;
```

---

### `ARRAY_OPERATORS`

```ts
ARRAY_OPERATORS: Set<ExpressionOperator>;
```

---

### `VALID_OPERATORS`

```ts
VALID_OPERATORS: Set<ExpressionOperator>;
```

---

### `OPERATOR_START_WORDS`

```ts
OPERATOR_START_WORDS: Set<string>;
```

---

### `defineExpressionPanel`

```ts
export function defineExpressionPanel(el: HTMLElement, props: ExpressionPanelProps);
```

---

### `ExpressionPanelProps`

```ts
export type ExpressionPanelProps = {
  data: ShowData;
  multiFilterItems: MultiFilterItem;
  onFilterItemsChange: ProFilterItemsChangeListener;
  subscribeFilterItemsChange: ProFilterItemsChangeSubscription;
  config?: ColumnFilterConfig;
  getItems: () => Promise<SelectionItem[]> | SelectionItem[];
  columns?: ExpressionColumnReference[];
  rows?: readonly DataType[];
  getValue?(row: DataType, column: ExpressionColumnReference): unknown;
  change(filterItems: MultiFilterItem): Promise<void>;
};
```

---

### `parseExpression`

```ts
export function parseExpression(text: string): ExpressionParseResult;
```

---

### `serializeExpressionFilters`

```ts
export function serializeExpressionFilters(filters: FilterData[] = []);
```

---

### `replaceColumnFilters`

Creates the next filter item map after replacing one column's expression-owned filters.

The advanced filter panel receives mutable filter state from the core filter panel,
but expression apply logic should produce a fresh map before notifying sibling Pro
controls. This keeps the helper reusable in tests and avoids hidden prop mutation
from the expression UI.

```ts
export function replaceColumnFilters(
  multiFilterItems: MultiFilterItem,
  prop: ColumnProp,
  filters: FilterData[],
): MultiFilterItem;
```

---

### `syncFilterItemsTarget`

```ts
export function syncFilterItemsTarget(
  target: MultiFilterItem,
  source: MultiFilterItem,
): void;
```

---

### `tokenizeExpression`

```ts
export function tokenizeExpression(text: string): {
  tokens: ExpressionToken[];
  diagnostics: ExpressionDiagnostic[];
};
```

---

### `ExpressionBooleanOperator`

Boolean operator supported by the advanced filter expression AST.

```ts
/**
 * Boolean operator supported by the advanced filter expression AST.
 */
export type ExpressionBooleanOperator = 'and' | 'or';
```

---

### `ExpressionAst`

Parsed expression tree used by the hidden expression filter evaluator.

```ts
/**
 * Parsed expression tree used by the hidden expression filter evaluator.
 */
export type ExpressionAst =
  | ExpressionConditionNode
  | {
      kind: 'binary';
      op: ExpressionBooleanOperator;
      left: ExpressionAst;
      right: ExpressionAst;
    };
```

---

### `ExpressionConditionNode`

Single current-column condition parsed from an expression.

```ts
/**
 * Single current-column condition parsed from an expression.
 */
export type ExpressionConditionNode = {
  /** Condition node discriminator. */
  kind: 'condition';
  /** Optional field reference by column property or display label. */
  field?: string;
  /** Stable property resolved from a field label/property during compilation. */
  resolvedField?: ColumnProp;
  /** Filter family used to evaluate referenced temporal values correctly. */
  resolvedFamily?: string;
  /** Filter, date, selection, or symbolic operator. */
  operator: ExpressionOperator;
  /** Literal values consumed by the operator. */
  values: ExpressionLiteral[];
};
```

---

### `ExpressionLiteral`

Literal value parsed from expression text.

```ts
/**
 * Literal value parsed from expression text.
 */
export type ExpressionLiteral =
  | string
  | number
  | boolean
  | null
  | ExpressionLiteral[]
  | ExpressionFunctionValue
  | { [key: string]: ExpressionLiteral };
```

---

### `ExpressionFunctionName`

Supported value functions in filter expressions.

```ts
/** Supported value functions in filter expressions. */
export type ExpressionFunctionName = 'avg' | 'abs' | 'len';
```

---

### `ExpressionFunctionValue`

Parsed function value. Column references are resolved during compilation.

```ts
/** Parsed function value. Column references are resolved during compilation. */
export type ExpressionFunctionValue = {
  kind: 'function';
  name: string;
  field: string;
  argumentType?: 'column' | 'number' | 'string';
  resolvedField?: ColumnProp;
  /** Function result prepared once when the expression is compiled. */
  computedValue?: number;
};
```

---

### `ExpressionDiagnostic`

Validation or parsing diagnostic associated with an expression text range.

```ts
/**
 * Validation or parsing diagnostic associated with an expression text range.
 */
export type ExpressionDiagnostic = {
  /** Human-readable diagnostic message. */
  message: string;
  /** Inclusive start offset in the expression text. */
  start: number;
  /** Exclusive end offset in the expression text. */
  end: number;
};
```

---

### `ExpressionTokenType`

Token categories produced by the expression tokenizer.

```ts
/**
 * Token categories produced by the expression tokenizer.
 */
export type ExpressionTokenType =
  | 'word'
  | 'string'
  | 'number'
  | 'operator'
  | 'paren'
  | 'brace'
  | 'bracket'
  | 'colon'
  | 'comma'
  | 'invalid';
```

---

### `ExpressionToken`

Token emitted by the expression tokenizer for parsing and highlighting.

```ts
/**
 * Token emitted by the expression tokenizer for parsing and highlighting.
 */
export type ExpressionToken = {
  /** Token category. */
  type: ExpressionTokenType;
  /** Raw token value without quote delimiters for string tokens. */
  value: string;
  /** Inclusive start offset in the expression text. */
  start: number;
  /** Exclusive end offset in the expression text. */
  end: number;
};
```

---

### `ExpressionParseResult`

Result of parsing expression text.

```ts
/**
 * Result of parsing expression text.
 */
export type ExpressionParseResult = {
  /** Parsed AST when expression syntax is valid enough to build one. */
  ast?: ExpressionAst;
  /** Tokens produced from the source expression text. */
  tokens: ExpressionToken[];
  /** Parser and tokenizer diagnostics. */
  diagnostics: ExpressionDiagnostic[];
};
```

---

### `ExpressionFilterValue`

Hidden filter value stored in `multiFilterItems` for expression predicates.

```ts
/**
 * Hidden filter value stored in `multiFilterItems` for expression predicates.
 */
export type ExpressionFilterValue = {
  /** Original expression text used for serialization back into the editor. */
  text: string;
  /** Parsed expression tree used at filter evaluation time. */
  ast: ExpressionAst;
};
```

---

### `ExpressionFilterConfig`

Configuration for the Pro advanced filter expression editor.

Expression filtering is opt-in through `grid.filter.expressions`. When enabled,
the advanced filter popup renders a current-column expression editor and compiles
valid expressions into the existing RevoGrid filter model.

```ts
/**
 * Configuration for the Pro advanced filter expression editor.
 *
 * Expression filtering is opt-in through `grid.filter.expressions`. When enabled,
 * the advanced filter popup renders a current-column expression editor and compiles
 * valid expressions into the existing RevoGrid filter model.
 */
export type ExpressionFilterConfig = {
  /**
   * Enables or disables the expression editor.
   * Set to `false` to disable expressions when passing an object config.
   */
  enabled?: boolean;
  /**
   * Delay in milliseconds before applying expression edits after typing.
   * Use `0` for immediate validation/application in tests or highly reactive UIs.
   */
  applyDebounceMs?: number;
  /**
   * Label for the button that opens the expression editor.
   */
  buttonLabel?: string;
  /**
   * Placeholder shown in the expression textarea when it is empty.
   */
  placeholder?: string;
  /**
   * Accessible label/title for the validation tooltip trigger shown on invalid expressions.
   */
  errorTooltipLabel?: string;
  /**
   * Formats an expression diagnostic for the validation tooltip.
   *
   * Use this to localize diagnostic text or map low-level parser/compiler messages
   * to product-specific wording. Multiple diagnostics are formatted individually
   * and joined with new lines.
   */
  formatDiagnostic?: (diagnostic: ExpressionDiagnostic, diagnostics: ExpressionDiagnostic[]) => string;
};
```

---

### `NormalizedExpressionConfig`

Expression configuration after defaults are applied.

```ts
/**
 * Expression configuration after defaults are applied.
 */
export type NormalizedExpressionConfig = Required<ExpressionFilterConfig>;
```

---

### `ExpressionColumnContext`

Column-specific context needed to validate and compile expression text.

```ts
/**
 * Column-specific context needed to validate and compile expression text.
 */
export type ExpressionColumnContext = {
  /** Current column property. */
  prop: ColumnProp;
  /** Current column display name. */
  name?: string;
  /** Filter panel column metadata. */
  data: ShowData;
  /** Selection options available for current-column selection expressions. */
  selectionItems?: ExpressionSelectionOption[];
  /** Available columns used to validate compatible persisted cross-column expressions. */
  columns?: ExpressionColumnReference[];
  /** Current provider source used to prepare aggregate functions once. */
  rows?: readonly DataType[];
  /** Resolves a source value consistently with the grid's column parser. */
  getValue?: (row: DataType, column: ExpressionColumnReference) => unknown;
  /** Optional popup-scoped aggregate cache for function compilation. */
  getAverage?: (column: ExpressionColumnReference) => number | undefined;
};
```

---

### `ExpressionColumnReference`

Column metadata exposed to expression compilation.

```ts
/** Column metadata exposed to expression compilation. */
export type ExpressionColumnReference = {
  prop: ColumnProp;
  name?: string;
  data: ShowData;
};
```

---

### `ExpressionSuggestion`

One keyboard-selectable expression completion.

```ts
/** One keyboard-selectable expression completion. */
export type ExpressionSuggestion = {
  id: string;
  label: string;
  insertText: string;
  detail: string;
  kind: 'operator' | 'keyword' | 'function';
};
```

---

### `ExpressionCompileResult`

Result of compiling expression text into RevoGrid filter items.

```ts
/**
 * Result of compiling expression text into RevoGrid filter items.
 */
export type ExpressionCompileResult = {
  /** Filter items that should replace current-column expression-owned filters. */
  filters: FilterData[];
  /** Validation diagnostics that should prevent applying filters when present. */
  diagnostics: ExpressionDiagnostic[];
};
```

---

### `ExpressionSelectionOption`

Selection option available to expression selection operators.

```ts
/**
 * Selection option available to expression selection operators.
 */
export type ExpressionSelectionOption = {
  /** Normalized selection value used by the selection filter model. */
  value: string;
  /** User-facing selection label. */
  label: string;
};
```

---

### `normalizeExpressionText`

Value normalization helpers shared by expression evaluation and future expression
integrations. They intentionally mirror the lightweight coercion used by the
existing Pro filter predicates instead of introducing a separate expression runtime.

Normalizes a value for case-insensitive text and selection comparisons.

```ts
export function normalizeExpressionText(value: unknown);
```

---

### `toExpressionNumber`

Coerces a value for numeric expression comparisons.

```ts
export function toExpressionNumber(value: unknown);
```

---

### `toExpressionDateTime`

Coerces a value to a timestamp for date expression comparisons.

```ts
export function toExpressionDateTime(value: unknown);
```

---

### `isSameCalendarDate`

Compares values by their calendar date string, matching existing Pro date-filter semantics.

```ts
export function isSameCalendarDate(value: unknown, compare: unknown);
```

---

### `isDateLikeValue`

Detects values that should prefer date comparison over numeric comparison.

```ts
export function isDateLikeValue(value: unknown);
```

---

### `formatDefaultBadgeLabel`

```ts
export function formatDefaultBadgeLabel(
  context: AdvancedFilterBadgeFormatContext,
  presentation: AdvancedFilterBadgePresentation,
  captions?: FilterBadgesCaptions,
);
```

---

### `formatDefaultBadgePresentation`

```ts
export function formatDefaultBadgePresentation(
  context: AdvancedFilterBadgeFormatContext,
  captions?: FilterBadgesCaptions,
): AdvancedFilterBadgePresentation;
```

---

### `renderAdvancedFilterBadges`

```ts
export function renderAdvancedFilterBadges(
  context: AdvancedFilterBadgesRenderContext,
  options: AdvancedFilterBadgesOptions,
  controllerId: number,
);
```

---

### `clearAdvancedFilterBadges`

```ts
export function clearAdvancedFilterBadges(root: HTMLElement);
```

---

### `columnDropdownValueLabel`

Reuses a dropdown column's normalized display label without changing stored identity.

```ts
export function columnDropdownValueLabel(
  column: ColumnRegular | null | undefined,
  value: unknown,
);
```

---

### `columnDropdownDisplayValue`

Resolves the user-visible dropdown value while preserving unknown members.

```ts
export function columnDropdownDisplayValue(
  column: ColumnRegular | null | undefined,
  value: unknown,
): unknown;
```

---

### `createDefaultCondition`

```ts
export function createDefaultCondition(
  fields: GroupedFilterFieldOption[],
  prop?: ColumnProp,
): FilterAstCondition | undefined;
```

---

### `conditionWithOperator`

```ts
export function conditionWithOperator(
  condition: FilterAstCondition,
  operator: GroupedFilterOperatorOption,
  currentOperator?: GroupedFilterOperatorOption,
): FilterAstCondition;
```

---

### `clearConditionValue`

Creates an invalid/empty editor draft without changing the predefined predicate identity.

```ts
export function clearConditionValue(
  condition: FilterAstCondition,
  operator: GroupedFilterOperatorOption,
): FilterAstCondition;
```

---

### `hasConditionValue`

Whether a persistent slot draft currently contains an effective value.

```ts
export function hasConditionValue(
  condition: FilterAstCondition,
  operator: GroupedFilterOperatorOption,
): boolean;
```

---

### `defaultRange`

```ts
export function defaultRange(valueType: FilterAstValueType): FilterAstValue[];
```

---

### `GroupedFilterCondition`

```ts
export function GroupedFilterCondition({
  condition,
  negated,
  fields,
  replace,
  remove,
  translations = DEFAULT_GROUPED_FILTER_TRANSLATIONS,
  config,
  enabled = true,
  editorOpen = false,
  valueEditorLayout = 'popover',
  popoverTarget,
  popoverTheme,
  openEditor,
  closeEditor,
  clearSlot,
  activateSlot,
}: {
  condition: FilterAstCondition;
  negated: boolean;
  fields: GroupedFilterFieldOption[];
  replace(
    condition: FilterAstCondition,
    negated: boolean,
    operator?: GroupedFilterFieldOption['operators'][number],
  ): void;
  remove(): void;
  translations?: GroupedFilterTranslations;
  config: NormalizedFilterAstEditorConfig;
  enabled?: boolean;
  editorOpen?: boolean;
  valueEditorLayout?: 'popover' | 'inline';
  popoverTarget?: HTMLElement | null;
  popoverTheme?: string | null;
  openEditor?(): void;
  closeEditor?(): void;
  clearSlot?(condition: FilterAstCondition): void;
  activateSlot?(): void;
});
```

---

### `normalizeFilterAstEditorConfig`

```ts
export function normalizeFilterAstEditorConfig(
  preset: FilterAstEditorPreset = 'builder',
  overrides?: FilterAstEditorConfig,
): NormalizedFilterAstEditorConfig;
```

---

### `findFilterAstShapeIssue`

```ts
export function findFilterAstShapeIssue(ast: FilterAst | undefined, config: NormalizedFilterAstEditorConfig): string | undefined;
```

---

### `NormalizedFilterAstEditorConfig`

```ts
export type NormalizedFilterAstEditorConfig = DeepRequired<FilterAstEditorConfig>;
```

---

### `renderGroupedFilterPopup`

```ts
export function renderGroupedFilterPopup(
  data: ShowData,
  {
    ast,
    fields,
    validate,
    preview,
    apply,
    close,
    captions,
    translations,
  }: {
    ast?: FilterAst;
    fields: GroupedFilterFieldOption[];
    validate(ast?: FilterAst): FilterAstDiagnostic[];
    preview(ast: FilterAst | undefined, signal: AbortSignal): GroupedFilterPreview | Promise<GroupedFilterPreview>;
    apply(ast?: FilterAst): Promise<void>;
    close(): void;
    captions?: Partial<FilterCaptions> & Readonly<Record<string, unknown>>;
    translations?: GroupedFilterTranslationOverrides;
  },
);
```

---

### `IconButton`

```ts
export function IconButton({
  label,
  icon,
  onClick,
  className = '',
  disabled = false,
}: {
  label: string;
  icon: string;
  onClick(): void;
  className?: string;
  disabled?: boolean;
});
```

---

### `TextIconButton`

```ts
export function TextIconButton({
  label,
  icon,
  onClick,
  disabled = false,
}: {
  label: string;
  icon: string;
  onClick(): void;
  disabled?: boolean;
});
```

---

### `mountExternalFilterAstEditor`

Owns the application-mounted grouped editor surface and its DOM lifecycle.

```ts
export function mountExternalFilterAstEditor({
  grid,
  host,
  initialAst: sourceAst,
  options,
  getFields,
  validate,
  preview,
  apply,
  captions,
  onDestroy,
}: ExternalFilterAstEditorContext): FilterAstEditorHandle;
```

---

### `createGroupedFilterFields`

Builds grouped-editor field metadata without depending on the plugin lifecycle object.

```ts
export function createGroupedFilterFields({
  currentProp,
  columns: sourceColumns,
  registry,
  config,
  filterNames,
  structuredContext,
  getColumnFilterTypes,
  getSelectionEditor,
}: CreateGroupedFilterFieldsOptions): GroupedFilterFieldOption[];
```

---

### `CreateGroupedFilterFieldsOptions`

```ts
interface CreateGroupedFilterFieldsOptions {
  readonly currentProp?: ColumnProp;
  readonly columns: readonly ColumnRegular[];
  readonly registry: StructuredFilterTypeRegistry;
  readonly config?: ColumnFilterConfig;
  readonly filterNames: Readonly<Record<string, string>>;
  readonly structuredContext: Omit<
      StructuredFilterContextOptions,
      'isVisibleRow' | 'runtimeCache' | 'dateReferenceDate' | 'sourceRowTypes'
    > & {
      isVisibleRow(columnProp: ColumnProp): StructuredFilterContextOptions['isVisibleRow'];
      dateReferenceDate(columnProp: ColumnProp): StructuredFilterContextOptions['dateReferenceDate'];
      sourceRowTypes(columnProp: ColumnProp): StructuredFilterContextOptions['sourceRowTypes'];
    };
  readonly getColumnFilterTypes: (
      filter: ColumnRegular['filter'],
      prop: ColumnProp,
    ) => readonly string[];
  readonly getSelectionEditor: (column: ColumnRegular) => GroupedFilterOperatorEditor | undefined
}
```

---

### `GroupedFilterGroup`

```ts
export function GroupedFilterGroup({
  group,
  groupPath,
  wrapperPath,
  negated,
  root,
  fields,
  update,
  append,
  remove,
  toggleNot,
  renderNode,
  reorder,
  translations = DEFAULT_GROUPED_FILTER_TRANSLATIONS,
  config,
}: {
  group: FilterAstGroup;
  groupPath: FilterAstEditorPath;
  wrapperPath: FilterAstEditorPath;
  negated: boolean;
  root?: boolean;
  fields: GroupedFilterFieldOption[];
  update(path: FilterAstEditorPath, updater: (node: FilterAst) => FilterAst): void;
  append(path: FilterAstEditorPath, child: FilterAst): void;
  remove(path: FilterAstEditorPath): void;
  toggleNot(): void;
  renderNode(node: FilterAst, path: FilterAstEditorPath): ComponentChildren;
  reorder: GroupedFilterReorderController;
  translations?: GroupedFilterTranslations;
  config: NormalizedFilterAstEditorConfig;
});
```

---

### `sentenceOperatorLabel`

```ts
export function sentenceOperatorLabel(
  option: GroupedFilterOperatorOption,
  translations: GroupedFilterTranslations = DEFAULT_GROUPED_FILTER_TRANSLATIONS,
);
```

---

### `getConditionOperatorVariants`

```ts
export function getConditionOperatorVariants(
  options: GroupedFilterOperatorOption[],
  translations: GroupedFilterTranslations = DEFAULT_GROUPED_FILTER_TRANSLATIONS,
);
```

---

### `getConditionOperatorKey`

```ts
export function getConditionOperatorKey(
  operator: FilterAstOperator,
  negated: boolean,
  variants: ConditionOperatorVariant[],
);
```

---

### `findEquivalentConditionOperatorVariant`

```ts
export function findEquivalentConditionOperatorVariant(
  operator: FilterAstOperator,
  negated: boolean,
  variants: ConditionOperatorVariant[],
);
```

---

### `ConditionOperatorVariant`

```ts
interface ConditionOperatorVariant {
  key: string;
  option: GroupedFilterOperatorOption;
  negated: boolean;
  label: string
}
```

---

### `getEditorNodeId`

```ts
export function getEditorNodeId(node: FilterAst);
```

---

### `updateEditorNode`

```ts
export function updateEditorNode(
  ast: FilterAst,
  path: FilterAstEditorPath,
  update: (node: FilterAst) => FilterAst,
): FilterAst;
```

---

### `appendEditorNode`

```ts
export function appendEditorNode(
  ast: FilterAst,
  groupPath: FilterAstEditorPath,
  child: FilterAst,
): FilterAst;
```

---

### `removeEditorNode`

```ts
export function removeEditorNode(
  ast: FilterAst,
  path: FilterAstEditorPath,
): FilterAst | undefined;
```

---

### `moveEditorNodeById`

Moves one group child before the requested insertion index, including across nested groups.

```ts
export function moveEditorNodeById(
  ast: FilterAst,
  sourceId: number,
  targetGroupId: number,
  targetIndex: number,
): FilterAst;
```

---

### `canMoveEditorNodeById`

Checks a tree move without mutating or rebuilding the editor AST.

```ts
export function canMoveEditorNodeById(
  ast: FilterAst,
  sourceId: number,
  targetGroupId: number,
  targetIndex: number,
);
```

---

### `toggleEditorNot`

```ts
export function toggleEditorNot(
  ast: FilterAst,
  path: FilterAstEditorPath,
): FilterAst;
```

---

### `toEditorRoot`

```ts
export function toEditorRoot(ast?: FilterAst): FilterAstGroup;
```

---

### `fromEditorRoot`

```ts
export function fromEditorRoot(root: FilterAstGroup): FilterAst | undefined;
```

---

### `findPersistentConditionSlotIssue`

Reports an effective condition that cannot be represented by the predefined slots.

```ts
export function findPersistentConditionSlotIssue(
  slots: readonly FilterAstCondition[],
  effectiveAst?: FilterAst,
): string | undefined;
```

---

### `createPersistentConditionSlotState`

Builds persistent UI slots and overlays the values currently present in the effective AST.

```ts
export function createPersistentConditionSlotState(
  slots: readonly FilterAstCondition[],
  effectiveAst?: FilterAst,
  clearCondition: (condition: FilterAstCondition) => FilterAstCondition = (condition) => {
    const { value: _value, ...withoutValue } = condition;
    if (condition.operator === 'between' || condition.operator === 'dateBetween') {
      const empty = condition.valueType === 'number' ? Number.NaN : '';
      return { ...withoutValue, value: [empty, empty] };
    }
    return withoutValue;
  },
): PersistentConditionSlotState;
```

---

### `fromPersistentConditionSlots`

Projects persistent UI slots back to the canonical AST consumed by filtering.

```ts
export function fromPersistentConditionSlots(
  root: FilterAstGroup,
  enabledNodeIds: ReadonlySet<number>,
): FilterAst | undefined;
```

---

### `countFilterAstNodes`

```ts
export function countFilterAstNodes(
  ast?: FilterAst,
  includeCondition: (condition: FilterAstCondition) => boolean = () => true,
);
```

---

### `summarizeFilterAst`

```ts
export function summarizeFilterAst(
  ast: FilterAst,
  fieldLabels: Record<string, string> = {},
  operatorLabels: Record<string, string> = {},
  valuePresenters: Record<string, (condition: Readonly<FilterAstCondition>) => string | undefined> = {},
  translations: GroupedFilterTranslations = DEFAULT_GROUPED_FILTER_TRANSLATIONS,
): string;
```

---

### `conditionPresenterKey`

```ts
export function conditionPresenterKey(field: FilterAstCondition['field'], operator: string);
```

---

### `FilterAstEditorPath`

```ts
export type FilterAstEditorPath = Array<number | 'not'>;
```

---

### `PersistentConditionSlotState`

```ts
interface PersistentConditionSlotState {
  root: FilterAstGroup;
  enabledNodeIds: Set<number>
}
```

---

### `defineGroupedFilterPanel`

```ts
export function defineGroupedFilterPanel(el: HTMLElement, props: GroupedFilterPanelProps);
```

---

### `GroupedFilterFieldOption`

```ts
interface GroupedFilterFieldOption {
  field: ColumnProp;
  label: string;
  operators: GroupedFilterOperatorOption[]
}
```

---

### `GroupedFilterOperatorOption`

```ts
interface GroupedFilterOperatorOption {
  operator: FilterAstOperator;
  /** Canonical predicate used for presentation while `operator` remains the transport id. */
    semanticOperator?: FilterAstOperator;
  label: string;
  valueType: FilterAstValueType;
  /** Operator-owned value UI used when the scalar fallback would be lossy. */
    editor?: GroupedFilterOperatorEditor;
  /** Filter-owned readable value used by the Text mirror instead of transport objects. */
    describeValue?(condition: Readonly<FilterAstCondition>): string | undefined;
  /** Returns the editor-specific empty draft used when a persistent slot is cleared. */
    clearCondition?(condition: Readonly<FilterAstCondition>): FilterAstCondition
}
```

---

### `GroupedFilterPanelProps`

```ts
interface GroupedFilterPanelProps {
  ast?: FilterAst;
  /** Stable condition definitions rendered by persistent-condition layouts. */
    conditionSlots?: readonly FilterAstCondition[];
  /** Explicit synchronization token. Changing it replaces the current draft baseline. */
    baselineKey?: unknown;
  fields: GroupedFilterFieldOption[];
  validate(ast?: FilterAst): FilterAstDiagnostic[];
  preview(ast: FilterAst | undefined, signal: AbortSignal): GroupedFilterPreview | Promise<GroupedFilterPreview>;
  apply(ast?: FilterAst): Promise<void>;
  cancel(): void;
  /** Filter-config captions keyed by `groupedFilter.*`. */
    captions?: Readonly<Record<string, unknown>>;
  /** Direct typed overrides for standalone panel integrations. */
    translations?: GroupedFilterTranslationOverrides;
  config?: NormalizedFilterAstEditorConfig;
  /** Internal adapter policy: external mounts expand editors in flow. */
    valueEditorLayout?: 'popover' | 'inline';
  shapeNotice?: string
}
```

---

### `GroupedFilterPreview`

```ts
interface GroupedFilterPreview {
  matching?: number;
  total?: number;
  label?: string
}
```

---

### `GroupedFilterReorderHandle`

```ts
export function GroupedFilterReorderHandle({
  nodeId,
  groupId,
  index,
  count,
  label,
  controller,
  disabled = false,
}: {
  nodeId: number;
  groupId: number;
  index: number;
  count: number;
  label: string;
  controller: GroupedFilterReorderController;
  disabled?: boolean;
});
```

---

### `createGroupedFilterDragGhost`

```ts
export function createGroupedFilterDragGhost(source: HTMLElement, event: DragEvent);
```

---

### `GroupedFilterDropTarget`

```ts
interface GroupedFilterDropTarget {
  readonly groupId: number;
  readonly index: number
}
```

---

### `GroupedFilterReorderController`

```ts
interface GroupedFilterReorderController {
  readonly draggedNodeId?: number;
  readonly dropTarget?: GroupedFilterDropTarget;
  readonly instructionsId: string;
  start(event: DragEvent, nodeId: number, source: HTMLElement): void;
  over(event: DragEvent, target: GroupedFilterDropTarget): void;
  drop(event: DragEvent, target: GroupedFilterDropTarget): void;
  end(): void;
  moveWithinGroup(nodeId: number, groupId: number, index: number, count: number, direction: -1 | 1): void
}
```

---

### `GroupedScalarValueEditor`

```ts
export function GroupedScalarValueEditor({
  condition,
  operator,
  change,
  translations = DEFAULT_GROUPED_FILTER_TRANSLATIONS,
}: GroupedFilterValueChangeProps & { translations?: GroupedFilterTranslations });
```

---

### `GroupedSelectionValueEditor`

```ts
export function GroupedSelectionValueEditor({
  condition,
  editor,
  change,
  translations = DEFAULT_GROUPED_FILTER_TRANSLATIONS,
}: GroupedFilterSpecializedValueEditorProps<GroupedFilterSelectionEditor>);
```

---

### `GroupedSliderValueEditor`

```ts
export function GroupedSliderValueEditor({
  condition,
  editor,
  change,
  translations = DEFAULT_GROUPED_FILTER_TRANSLATIONS,
}: GroupedFilterSpecializedValueEditorProps<GroupedFilterSliderEditor>);
```

---

### `GroupedStructuredValueEditor`

```ts
export function GroupedStructuredValueEditor({
  condition,
  editor,
  change,
  remove,
  close,
}: GroupedFilterSpecializedValueEditorProps<GroupedFilterStructuredEditor> & {
  remove(): void;
});
```

---

### `GroupedFilterSelectionItem`

```ts
interface GroupedFilterSelectionItem {
  value: string;
  label: string;
  [key: string]: unknown
}
```

---

### `GroupedFilterSliderEditor`

```ts
interface GroupedFilterSliderEditor {
  kind: 'slider';
  min: number;
  max: number;
  step?: number | 'any';
  formatValue?(value: number): string
}
```

---

### `GroupedFilterSelectionEditor`

```ts
interface GroupedFilterSelectionEditor {
  kind: 'selection';
  getItems(): GroupedFilterSelectionItem[] | Promise<GroupedFilterSelectionItem[]>;
  searchItems?(
      search: string,
      signal: AbortSignal,
    ): GroupedFilterSelectionItem[] | Promise<GroupedFilterSelectionItem[]>;
  matches?(item: GroupedFilterSelectionItem, normalizedSearch: string): boolean
}
```

---

### `GroupedFilterStructuredEditor`

```ts
interface GroupedFilterStructuredEditor {
  kind: 'structured';
  family: string;
  mount(
      host: HTMLElement,
      condition: FilterAstCondition,
      change: (condition: FilterAstCondition) => void,
      remove: () => void,
      close?: () => void,
    ): void | (() => void)
}
```

---

### `GroupedFilterOperatorEditor`

```ts
export type GroupedFilterOperatorEditor =
  | GroupedFilterSliderEditor
  | GroupedFilterSelectionEditor
  | GroupedFilterStructuredEditor;
```

---

### `formatGroupedFilterDiagnostic`

Converts canonical diagnostics into field-aware, fully localizable grouped-editor messages.

```ts
export function formatGroupedFilterDiagnostic(
  diagnostic: FilterAstDiagnostic,
  ast: FilterAst | undefined,
  fields: readonly GroupedFilterFieldOption[],
  translations: GroupedFilterTranslations,
);
```

---

### `configureGroupedFilterValueEditors`

Adds configured presentation controls without coupling them to the canonical AST.

```ts
export function configureGroupedFilterValueEditors({
  fields,
  columns,
  overrides = [],
  getSliderBounds,
}: GroupedFilterValueEditorConfigContext): GroupedFilterFieldOption[];
```

---

### `GroupedFilterValueEditor`

```ts
export function GroupedFilterValueEditor({
  condition,
  operator,
  change,
  remove,
  close,
  translations = DEFAULT_GROUPED_FILTER_TRANSLATIONS,
}: GroupedFilterValueEditorProps);
```

---

### `GroupedFilterValueEditorProps`

```ts
interface GroupedFilterValueEditorProps {
  condition: FilterAstCondition;
  operator: GroupedFilterOperatorOption;
  change(condition: FilterAstCondition): void;
  remove(): void;
  close?(): void;
  translations?: GroupedFilterTranslations
}
```

---

### `GroupedFilterValueChangeProps`

```ts
export type GroupedFilterValueChangeProps = Pick<
  GroupedFilterValueEditorProps,
  'condition' | 'operator' | 'change'
>;
```

---

### `GroupedFilterSpecializedValueEditorProps` (Extended from `value-editor.types.ts`)

```ts
export type GroupedFilterSpecializedValueEditorProps<
  Editor extends GroupedFilterOperatorEditor,
> = Omit<GroupedFilterValueChangeProps, 'operator'> & {
  editor: Editor;
  close?: GroupedFilterValueEditorProps['close'];
  translations?: GroupedFilterTranslations;
};
```

---

### `FilterValueAutocompleteList`

```ts
export function FilterValueAutocompleteList({
  anchorRef,
  id,
  ariaLabel,
  options,
  activeIndex,
  onActiveIndexChange,
  onSelect,
}: {
  anchorRef: RefObject<HTMLDivElement>;
  id: string;
  ariaLabel: string;
  options: readonly FilterValueAutocompleteOption[];
  activeIndex: number;
  onActiveIndexChange(index: number): void;
  onSelect(option: FilterValueAutocompleteOption): void;
});
```

---

### `FILTER_VALUE_AUTOCOMPLETE_LIMIT`

```ts
FILTER_VALUE_AUTOCOMPLETE_LIMIT: 8;
```

---

### `FilterValueAutocompleteOption`

```ts
interface FilterValueAutocompleteOption {
  readonly value: string;
  readonly label: string
}
```

---

### `BrushRange`

Shared presentation for distribution-backed brush filters. Domain editors own
the chart data and translate slider positions to their filter conditions.

```ts
export function BrushRange({
  chart,
  slider,
  startLabel,
  selectionLabel,
  endLabel,
  legacyClassPrefix,
}: BrushRangeProps);
```

---

### `BrushRangeProps`

```ts
interface BrushRangeProps {
  readonly chart?: DistributionChartProps | null;
  readonly slider: RangeSliderProps;
  readonly startLabel: ComponentChildren;
  readonly selectionLabel: ComponentChildren;
  readonly endLabel: ComponentChildren;
  /** Retains the established filter-specific selectors while sharing the markup owner. */
    readonly legacyClassPrefix?: string
}
```

---

### `createQuickFilterCompletionDetail`

Build completion detail from the datasource state that won the remote request.

```ts
export function createQuickFilterCompletionDetail(
  providers: PluginProviders,
  quickFilter?: QuickFilter,
): QuickFilterApplyEventDetail;
```

---

### `createSelectionCellTemplate`

Build the advanced selection option renderer from the owning column template.

```ts
export function createSelectionCellTemplate({
  column,
  columnProp,
  additionalData,
}: SelectionCellTemplateOptions): SelectionItemTemplate | undefined;
```

---

### `normalizeSelectionFilterConfig`

```ts
export function normalizeSelectionFilterConfig(
  config?: ColumnFilterConfig,
): ColumnFilterConfig | undefined;
```

---

### `resolveSelectionFilterConfig`

```ts
export function resolveSelectionFilterConfig(
  selection: SelectionConfig | undefined,
  prop: ColumnProp,
): ResolvedSelectionFilterConfig;
```

---

### `normalizeSelectionItems`

```ts
export function normalizeSelectionItems(items: SelectionItem[]): SelectionItem[];
```

---

### `ResolvedSelectionFilterConfig`

```ts
export type ResolvedSelectionFilterConfig = {
  excelMode?: SelectionConfig['excelMode'];
  sortDirection?: SelectionConfig['sortDirection'];
  remoteSearch: boolean;
  getItems?: GetItemsFn;
  itemTemplate?: SelectionItemTemplate;
  optionColumns?: SelectionOptionColumn[];
  optionProgress?: SelectionOptionProgressConfig;
  quickSearchFilter?: SelectionQuickSearchFilter;
  grouping?: GroupingOptions;
  plugins?: GridPlugin[];
  gridSettings?: SelectionGridSettings;
  sourceRowTypes?: DimensionRows[];
  syncCellTemplate: boolean;
};
```

---

### `isSelectionFilterActive`

```ts
export function isSelectionFilterActive(data: ShowData);
```

---

### `renderSelectionContent`

```ts
export function renderSelectionContent(
  data: ShowData,
  {
    multiFilterItems,
    onFilterItemsChange,
    subscribeFilterItemsChange,
    getItems,
    searchItems,
    itemTemplate,
    optionColumns,
    optionProgress,
    quickSearchFilter,
    grouping,
    plugins,
    gridSettings,
    excelMode,
    excelCaptions,
    sortDirection,
    onApply,
    onCancel,
    config = {},
    change,
  }: SelectionContentOptions,
);
```

---

### `SelectionContentOptions`

```ts
export type SelectionContentOptions = {
  multiFilterItems: MultiFilterItem;
  onFilterItemsChange: ProFilterItemsChangeListener;
  subscribeFilterItemsChange: ProFilterItemsChangeSubscription;
  getItems: () => Promise<SelectionItem[]> | SelectionItem[];
  searchItems?: (search: string, signal: AbortSignal) => Promise<SelectionItem[]>;
  itemTemplate?: SelectionItemTemplate;
  optionColumns?: SelectionOptionColumn[];
  optionProgress?: SelectionOptionProgressConfig;
  quickSearchFilter?: SelectionQuickSearchFilter;
  grouping?: GroupingOptions;
  plugins?: GridPlugin[];
  gridSettings?: SelectionGridSettings;
  excelMode?: 'windows';
  excelCaptions?: SelectionExcelControlCaptions;
  sortDirection?: 'asc' | 'desc' | 'none';
  onApply?: () => void | Promise<void>;
  onCancel?: () => void;
  config?: ColumnFilterConfig;
  change(filterItems: MultiFilterItem, changedProp?: ColumnProp): Promise<void>;
};
```

---

### `createFilterDependencyBadgeController`

```ts
export function createFilterDependencyBadgeController(
  plugin: FilterDependencyBadgePlugin,
  getFilterConfig: () => ColumnFilterConfig | undefined,
): FilterDependencyBadgeController;
```

---

### `getContextAwareSelectionList`

```ts
export function getContextAwareSelectionList(
  plugin: FilterPluginLike,
  columnProp: ColumnProp,
  exclude = new Set<string>(),
  sourceRowTypes?: DimensionRows[],
): SelectionItem[];
```

---

### `getContextAwareSelectionItems`

Returns every context-valid source occurrence for header counts and summaries.

```ts
export function getContextAwareSelectionItems(
  plugin: FilterPluginLike,
  columnProp: ColumnProp,
  exclude = new Set<string>(),
  sourceRowTypes?: DimensionRows[],
): SelectionItem[];
```

---

### `createExcelDateSelectionItems`

```ts
export function createExcelDateSelectionItems(
  items: SelectionItem[],
  {
    blanksLabel = SELECTION_FILTER_LOCALIZATION.captions.selectionBlanks,
    locale,
  }: { blanksLabel?: string; locale?: string } = {},
): SelectionItem[];
```

---

### `SELECTION_FILTER_KEYS`

```ts
SELECTION_FILTER_KEYS: string;
```

---

### `resolveExcelSelectionPreset`

```ts
export function resolveExcelSelectionPreset(
  data: ShowData,
  excelMode?: 'windows',
): ExcelSelectionPreset;
```

---

### `resolveExcelSelectionCaptions`

```ts
export function resolveExcelSelectionCaptions(
  captions?: Partial<FilterCaptions>,
): SelectionExcelCaptions;
```

---

### `prepareExcelSelectionItems`

```ts
export function prepareExcelSelectionItems(
  items: SelectionItem[],
  preset: ExcelSelectionPreset,
  captions: SelectionExcelCaptions,
);
```

---

### `resolveExcelSelectionPlugins`

```ts
export function resolveExcelSelectionPlugins(
  plugins: GridPlugin[] | undefined,
  preset: ExcelSelectionPreset,
): GridPlugin[] | undefined;
```

---

### `resolveExcelSelectionGridSettings`

```ts
export function resolveExcelSelectionGridSettings(
  gridSettings: SelectionGridSettings | undefined,
  preset: ExcelSelectionPreset,
): SelectionGridSettings | undefined;
```

---

### `SELECTION_BLANK_ITEM`

```ts
SELECTION_BLANK_ITEM: string;
```

---

### `SelectionExcelCaptions`

```ts
export type SelectionExcelCaptions = {
  apply: string;
  cancel: string;
  selectAll: string;
  selectAllSearchResults: string;
  addCurrentSelection: string;
  invertVisible?: string;
  invertVisibleAria?: string;
  blanks: string;
  search?: string;
  selectAllAria?: string;
};
```

---

### `SelectionExcelControlCaptions`

```ts
export type SelectionExcelControlCaptions = Omit<SelectionExcelCaptions, 'blanks'>;
```

---

### `ExcelSelectionPreset`

```ts
export type ExcelSelectionPreset = {
  enabled: boolean;
  dateHierarchy: boolean;
};
```

---

### `resolveSelectionPopupOptions`

Resolves normal and Excel selection-popup behavior from one configuration owner.

```ts
export function resolveSelectionPopupOptions({
  data,
  prop,
  filterConfig,
  cascadeEnabled,
  getDefaultItems,
  getContextAwareItems,
}: ResolveSelectionPopupOptions);
```

---

### `ResolveSelectionPopupOptions`

```ts
export type ResolveSelectionPopupOptions = {
  data: ShowData;
  prop: ColumnProp;
  filterConfig?: ColumnFilterConfig;
  cascadeEnabled: boolean;
  getDefaultItems: (sourceRowTypes?: DimensionRows[]) => SelectionItem[];
  getContextAwareItems: (sourceRowTypes?: DimensionRows[]) => SelectionItem[];
  getExcludedItems?: (sourceRowTypes?: DimensionRows[]) => SelectionItem[];
};
```

---

### `createSelectionProgressModel`

Resolves option values and their shared range once for a virtual selection grid update.

```ts
export function createSelectionProgressModel(
  config: SelectionOptionProgressConfig,
  rows: readonly SelectionListRow[],
  columnProp: ColumnProp,
): SelectionProgressModel;
```

---

### `parseValue`

```ts
export function parseValue(
  originalValue: string | undefined,
  originalLabel?: string,
  emptyLabel = SELECTION_FILTER_LOCALIZATION.captions.selectionEmpty,
): { value: string; label: string };
```

---

### `parseSelectionValues`

```ts
export function parseSelectionValues(
  originalValue: unknown,
  originalLabel?: string,
): { value: string; label: string }[];
```

---

### `getSelectionValueKeys`

```ts
export function getSelectionValueKeys(value: unknown): string[];
```

---

### `getSliderBounds`

Derives finite numeric slider bounds from provider-backed source stores.

```ts
export function getSliderBounds({
  column,
  dataStores,
  isSourceRow,
  getValue,
}: SliderBoundsOptions): { min: number; max: number };
```

---

### `SliderBoundsOptions`

```ts
export type SliderBoundsOptions = {
  column: ColumnRegular;
  dataStores: RowDataSources;
  isSourceRow(row?: DataType): boolean;
  getValue(
    row: DataType,
    column: ColumnRegular,
    rowType?: DimensionRows,
    rowIndex?: number,
  ): unknown;
};
```

---

### `RangeSliderElementFactory`

```ts
export type RangeSliderElementFactory = (
  type: string,
  props: Record<string, unknown> | null,
  ...children: unknown[]
) => unknown;
```

---

### `renderSliderControl`

Renders the dual native range inputs used as slider handles.
Shared runtime helpers keep handle position, highlighted track, labels,
tooltips, and optional editable inputs synchronized.

```ts
export function renderSliderControl(h: RangeSliderElementFactory, runtime: RangeSliderRuntime);
```

---

### `renderRangeInputs`

Renders optional editable range inputs for the selected slider range.
Inputs intentionally use `type="text"` with `inputMode="decimal"` so custom
formatters control comma/dot decimals instead of browser-localized number UI.

```ts
export function renderRangeInputs(h: RangeSliderElementFactory, runtime: RangeSliderRuntime);
```

---

### `scaleSliderValue`

```ts
export function scaleSliderValue(value: number, scaleFactor = SLIDER_SCALE_FACTOR);
```

---

### `isFullSliderRange`

Compares ranges in the same scaled space used by the native handles.

```ts
export function isFullSliderRange(
  range: SliderRange,
  bounds: Pick<RangeSliderProps, 'min' | 'max' | 'scaleFactor'>,
);
```

---

### `unscaleSliderValue`

```ts
export function unscaleSliderValue(value: number, scaleFactor = SLIDER_SCALE_FACTOR);
```

---

### `normalizeSliderState`

```ts
export function normalizeSliderState({
  min,
  max,
  fromValue,
  toValue,
  scaleFactor = SLIDER_SCALE_FACTOR,
}: SliderStateInput): ScaledSliderState;
```

---

### `clampScaledValue`

```ts
export function clampScaledValue(value: number, minInt: number, maxInt: number);
```

---

### `normalizeFromSlider`

```ts
export function normalizeFromSlider(fromValueInt: number, toValueInt: number);
```

---

### `normalizeToSlider`

```ts
export function normalizeToSlider(fromValueInt: number, toValueInt: number);
```

---

### `normalizeFromInputValue`

```ts
export function normalizeFromInputValue(
  value: number,
  currentToValueInt: number,
  state: Pick<ScaledSliderState, 'minInt' | 'maxInt'>,
  scaleFactor = SLIDER_SCALE_FACTOR,
);
```

---

### `normalizeToInputValue`

```ts
export function normalizeToInputValue(
  value: number,
  currentFromValueInt: number,
  state: Pick<ScaledSliderState, 'minInt' | 'maxInt'>,
  scaleFactor = SLIDER_SCALE_FACTOR,
);
```

---

### `toSliderRange`

```ts
export function toSliderRange(
  fromValueInt: number,
  toValueInt: number,
  scaleFactor = SLIDER_SCALE_FACTOR,
): SliderRange;
```

---

### `toSliderDisplayValue`

```ts
export function toSliderDisplayValue(valueInt: number, scaleFactor = SLIDER_SCALE_FACTOR);
```

---

### `formatSliderInputValue`

```ts
export function formatSliderInputValue(value: number);
```

---

### `formatSliderValue`

Default formatter shared by slider labels, tooltips, and header ranges.

```ts
export function formatSliderValue(value?: number);
```

---

### `parseSliderInputValue`

Default editable input parser.
Accepts both `640.42` and `640,42`; returns `NaN` for empty text so partial
edits do not reset the current slider selection while the user is typing.

```ts
export function parseSliderInputValue(value: string);
```

---

### `ScaledSliderState`

```ts
export type ScaledSliderState = {
  minInt: number;
  maxInt: number;
  fromValueInt: number;
  toValueInt: number;
};
```

---

### `SliderStateInput`

```ts
export type SliderStateInput = {
  min: number;
  max: number;
  fromValue: number;
  toValue: number;
  scaleFactor?: number;
};
```

---

### `getCurrentRange`

```ts
export function getCurrentRange(runtime: RangeSliderRuntime);
```

---

### `syncRangeText`

```ts
export function syncRangeText(runtime: RangeSliderRuntime);
```

---

### `updateTooltip`

```ts
export function updateTooltip(
  slider: HTMLInputElement,
  tooltip: HTMLDivElement,
  state: ScaledSliderState,
  formatValue: NonNullable<RangeSliderProps['formatValue']>,
  scaleFactor = 100,
);
```

---

### `getTooltipCenterPosition`

```ts
export function getTooltipCenterPosition(
  percent: number,
  parentWidth: number,
  tooltipWidth: number,
  edgePadding = 8,
);
```

---

### `hideTooltip`

```ts
export function hideTooltip(tooltip: HTMLDivElement);
```

---

### `fillSlider`

```ts
export function fillSlider(
  from: HTMLInputElement,
  to: HTMLInputElement,
  controlSlider: HTMLInputElement,
);
```

---

### `syncVisuals`

```ts
export function syncVisuals(runtime: RangeSliderRuntime);
```

---

### `setToggleAccessible`

```ts
export function setToggleAccessible(runtime: RangeSliderRuntime);
```

---

### `emitRangeChange`

```ts
export function emitRangeChange(runtime: RangeSliderRuntime);
```

---

### `emitRangeCommit`

```ts
export function emitRangeCommit(runtime: RangeSliderRuntime);
```

---

### `preventInvalidNumberKey`

```ts
export function preventInvalidNumberKey(event: KeyboardEvent);
```

---

### `RangeSliderRefs`

```ts
export type RangeSliderRefs = {
  fromSlider?: HTMLInputElement;
  toSlider?: HTMLInputElement;
  fromInput?: HTMLInputElement;
  toInput?: HTMLInputElement;
  fromLabel?: HTMLSpanElement;
  toLabel?: HTMLSpanElement;
  fromTooltip?: HTMLDivElement;
  toTooltip?: HTMLDivElement;
};
```

---

### `RangeSliderRuntime`

```ts
export type RangeSliderRuntime = {
  refs: RangeSliderRefs;
  state: ScaledSliderState;
  scaleFactor: number;
  nativeStep: number;
  formatValue: NonNullable<RangeSliderProps['formatValue']>;
  formatFromValue: NonNullable<RangeSliderProps['formatValue']>;
  formatToValue: NonNullable<RangeSliderProps['formatValue']>;
  formatInputValue: NonNullable<RangeSliderProps['formatInputValue']>;
  parseInputValue: NonNullable<RangeSliderProps['parseInputValue']>;
  showTooltips: boolean;
  onRangeChange: RangeSliderProps['onRangeChange'];
  onRangeCommit?: RangeSliderProps['onRangeCommit'];
  disabled: boolean;
  controlClassName?: string;
  fromClassName?: string;
  toClassName?: string;
  fromAriaLabel?: string;
  toAriaLabel?: string;
  scheduleSyncVisuals: () => void;
  syncVisuals: () => void;
};
```

---

### `TimeMatrixLegend`

**@jsxImportSource** preact

```ts
export function TimeMatrixLegend({
  label,
  selected,
  outsideWorkHours,
  weekend,
}: {
  label: string;
  selected: string;
  outsideWorkHours?: string;
  weekend?: string;
});
```

---

### `TimeMatrixScheduleGrid`

```ts
export function TimeMatrixScheduleGrid(props: TimeMatrixScheduleGridProps);
```

---

### `TimeMatrixDayLabel`

```ts
interface TimeMatrixDayLabel {
  readonly weekday: number;
  readonly short: string;
  readonly long: string
}
```

---

### `TimeMatrixScheduleGridProps`

```ts
interface TimeMatrixScheduleGridProps {
  readonly days: readonly TimeMatrixDayLabel[];
  readonly cells: ReadonlySet<string>;
  readonly focused: string;
  readonly weekendDays: readonly number[];
  readonly workingHours?: TimeMatrixWorkingHours;
  readonly gridLabel: string;
  readonly hourLabel: (hour: number) => string;
  readonly cellLabel: (
      day: TimeMatrixDayLabel,
      start: string,
      end: string,
      selected: boolean,
    ) => string;
  readonly matrixRef: RefObject<HTMLDivElement>;
  readonly onFocus: (key: string) => void;
  readonly onKeyDown: (
      event: h.JSX.TargetedKeyboardEvent<HTMLButtonElement>,
      weekday: number,
      hour: number,
    ) => void;
  readonly onClick: (
      event: h.JSX.TargetedMouseEvent<HTMLButtonElement>,
      weekday: number,
      hour: number,
      selected: boolean,
    ) => void;
  readonly onPointerDown: (
      event: h.JSX.TargetedPointerEvent<HTMLButtonElement>,
      weekday: number,
      hour: number,
      selected: boolean,
    ) => void;
  readonly onPointerEnter: (weekday: number, hour: number) => void
}
```

---

### `ExcelSearchControls`

```ts
export function ExcelSearchControls({
  searchInput,
  hasSearch,
  allSelected,
  indeterminate,
  captions,
  addCurrentSelection,
  onSelectAll,
  onInvertVisible,
  onAddCurrentSelection,
}: ExcelSearchControlsProps);
```

---

### `ExcelFilterActions`

```ts
export function ExcelFilterActions({
  captions,
  onApply,
  onCancel,
}: {
  captions?: SelectionExcelControlCaptions;
  onApply: () => void;
  onCancel?: () => void;
});
```

---

### `ExcelSearchControlsProps`

```ts
export type ExcelSearchControlsProps = {
  searchInput: ComponentChildren;
  hasSearch: boolean;
  allSelected?: boolean;
  indeterminate?: boolean;
  captions?: SelectionExcelControlCaptions;
  addCurrentSelection?: boolean;
  onSelectAll: (checked: boolean) => void;
  onInvertVisible: () => void;
  onAddCurrentSelection: (checked: boolean) => void;
};
```

---

### `createExcelSearchExclude`

Selects only search matches by excluding every hidden key.

```ts
export function createExcelSearchExclude(
  allKeys: Iterable<string>,
  matchingKeys: ReadonlySet<string>,
);
```

---

### `addAppliedSelectionToExcelSearch`

Unions applied selections with search selections using exclusion-set intersection.

```ts
export function addAppliedSelectionToExcelSearch(
  searchExclude: ReadonlySet<string>,
  appliedExclude: ReadonlySet<string>,
);
```

---

### `normalizeExcelApplyExclude`

Excel clears only an all-selected Apply; all-unselected must keep excluding every value.

```ts
export function normalizeExcelApplyExclude(
  exclude: ReadonlySet<string>,
  _allKeys: ReadonlySet<string>,
);
```

---

### `SelectionGrid`

```ts
SelectionGrid: ({ columnProp, rows, itemTemplate, optionColumns, optionProgress, grouping, plugins, gridSettings, onCheckedChange, }: SelectionGridProps) => preact.JSX.Element;
```

---

### `SELECTION_REMOTE_SEARCH_DEBOUNCE_MS`

```ts
SELECTION_REMOTE_SEARCH_DEBOUNCE_MS: 150;
```

---

### `List`

```ts
List: ({ columnProp, subscribeFilterItemsChange, getItems, searchItems, exclude: initialExclude, search, searchPlaceholder, searchAriaLabel, selectAllAriaLabel, filter, quickFilter, quickSearchFilter, sortDirection, itemTemplate, optionColumns, optionProgress, grouping, plugins, gridSettings, excelMode, excelCaptions, searchLabels, blanksLast, onApply, onCancel, }: ListProps) => preact.JSX.Element;
```

---

### `defineList`

```ts
defineList: (el: HTMLElement, props: ListProps) => PreactRootDisposer;
```

---

### `Search`

```ts
Search: ({ search, selectAll, invertVisible, searchValue, placeholder, searchAriaLabel, selectAllAriaLabel, allSelected, indeterminate, excelMode, captions, addCurrentSelection, setAddCurrentSelection, onEnter, }: SearchProps) => preact.JSX.Element;
```

---

### `TriStateCheckbox`

```ts
export function TriStateCheckbox({
  checked,
  indeterminate,
  ariaLabel,
  onChange,
}: TriStateCheckboxProps);
```

---

### `TriStateCheckboxProps`

```ts
export type TriStateCheckboxProps = {
  checked?: boolean;
  indeterminate?: boolean;
  ariaLabel?: string;
  onChange: (checked: boolean) => void;
};
```

---

### `SelectionListOption`

```ts
export type SelectionListOption = {
  text: string;
  checked: boolean;
  disabled: boolean;
  indeterminate: boolean;
  filterKeys: string[];
  item: SelectionItem;
};
```

---

### `SelectionListRow`

```ts
export type SelectionListRow = {
  value: string;
  label: string;
  checked: boolean;
  disabled: boolean;
  indeterminate: boolean;
  filterKeys: string[];
  item: SelectionItem;
  [key: string]: any;
};
```

---

### `ListProps`

```ts
interface ListProps {
  columnProp: ColumnProp;
  subscribeFilterItemsChange?: ProFilterItemsChangeSubscription;
  getItems: () => Promise<SelectionItem[]> | SelectionItem[];
  searchItems?: (search: string, signal: AbortSignal) => Promise<SelectionItem[]>;
  exclude?: Set<string>;
  search?: string;
  searchPlaceholder?: string;
  searchAriaLabel?: string;
  selectAllAriaLabel?: string;
  filter: (excluded: Set<string>) => void;
  quickFilter: (txt: string, matchingValues?: Set<string>) => void;
  quickSearchFilter?: SelectionQuickSearchFilter;
  sortDirection?: 'asc' | 'desc' | 'none';
  itemTemplate?: SelectionItemTemplate;
  optionColumns?: SelectionOptionColumn[];
  optionProgress?: SelectionOptionProgressConfig;
  grouping?: GroupingOptions;
  plugins?: GridPlugin[];
  gridSettings?: SelectionGridSettings;
  excelMode?: 'windows';
  excelCaptions?: SelectionExcelControlCaptions;
  searchLabels?: boolean;
  blanksLast?: boolean;
  onApply?: () => void | Promise<void>;
  onCancel?: () => void
}
```

---

### `EMPTY_EXCLUDE`

```ts
EMPTY_EXCLUDE: Set<string>;
```

---

### `FILTER_LIST_ROW_HEIGHT`

```ts
FILTER_LIST_ROW_HEIGHT: 28;
```

---

### `FILTER_LIST_MAX_VISIBLE_ROWS`

```ts
FILTER_LIST_MAX_VISIBLE_ROWS: 8;
```

---

### `FILTER_LIST_MAX_HEIGHT`

```ts
FILTER_LIST_MAX_HEIGHT: number;
```

---

### `withSelectionCascadeAvailability`

```ts
export function withSelectionCascadeAvailability(
  item: SelectionItem,
  disabled: boolean,
): SelectionItem;
```

---

### `normalizeSelectionValue`

```ts
export function normalizeSelectionValue(value?: string);
```

---

### `createSelectionMap`

```ts
export function createSelectionMap(items: SelectionItem[], exclude: Set<string>);
```

---

### `applyExcludeToSelectionMap`

```ts
export function applyExcludeToSelectionMap(
  data: Map<string, SelectionListOption>,
  exclude: ReadonlySet<string>,
);
```

---

### `mergeSelectionMapWithExcludedOptions`

Refreshes available options without dropping values the user has excluded in
the current popup. Context-aware loaders can temporarily stop returning those
values once the main grid applies the exclusion, but they must remain in the
chooser so the user can select them again.

```ts
export function mergeSelectionMapWithExcludedOptions(
  current: Map<string, SelectionListOption>,
  next: Map<string, SelectionListOption>,
  exclude: ReadonlySet<string>,
);
```

---

### `getSelectionItemFilterKeys`

```ts
export function getSelectionItemFilterKeys(
  item: SelectionItem,
  fallback = normalizeSelectionValue(item.value),
);
```

---

### `getSelectionFilterKeys`

```ts
export function getSelectionFilterKeys(
  data: Map<string, SelectionListOption>,
  optionKeys: Iterable<string> = data.keys(),
);
```

---

### `getTreeSelectionCascadeKeys`

```ts
export function getTreeSelectionCascadeKeys(
  data: Map<string, SelectionListOption>,
  value: string,
);
```

---

### `filterSelectionMapBySearch`

```ts
export function filterSelectionMapBySearch(
  data: Map<string, SelectionListOption>,
  searchText: string,
  quickSearchFilter?: SelectionQuickSearchFilter,
  columnProp: ColumnProp = '',
  searchLabels = false,
);
```

---

### `getSelectionSearchResult`

```ts
export function getSelectionSearchResult(
  data: Map<string, SelectionListOption>,
  searchText: string,
  quickSearchFilter?: SelectionQuickSearchFilter,
  columnProp: ColumnProp = '',
  searchLabels = false,
);
```

---

### `getSelectionQuickSearchMatchingValues`

```ts
export function getSelectionQuickSearchMatchingValues(
  data: Map<string, SelectionListOption>,
  searchText: string,
  quickSearchFilter?: SelectionQuickSearchFilter,
  columnProp: ColumnProp = '',
  searchLabels = false,
);
```

---

### `sortSelectionRows`

```ts
export function sortSelectionRows(
  filteredData: Map<string, SelectionListOption>,
  sortDirection?: 'asc' | 'desc' | 'none',
  blanksLast = false,
): SelectionListRow[];
```

---

### `countGroupedSelectionRows`

```ts
export function countGroupedSelectionRows(rows: SelectionListRow[], groupingProps: ColumnProp[] = []);
```

---

# Filter Header

URL: https://pro.rv-grid.com/api/filter-header/
Source: src/content/docs/api/filter-header.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Hide filter input in the header
       */
      hideFilterHeader?: boolean;
  /**
       * Hide per-value row counts from the filter header selection tooltip.
       * The selected-value count badge remains visible.
       */
      hideFilterHeaderCount?: boolean;
  /**
       * Filter placeholder
       */
      filterPlaceholder?: string;
  /**
       * Custom template for popup-style header filter trigger content.
       */
      filterHeaderTemplate?: FilterHeaderTemplateFunc
}
```

## Plugin API

### `FilterHeaderPresentation`

Plain-text state retained by the grid-owned accessible trigger shell.

```ts
interface FilterHeaderPresentation {
  active: boolean;
  summary: string;
  details?: string
}
```

---

### `FilterHeaderTemplateFunc`

Renders non-interactive content inside the grid-owned filter button.
Return `undefined` to use the standard accessible text/count fallback.

```ts
/**
 * Renders non-interactive content inside the grid-owned filter button.
 * Return `undefined` to use the standard accessible text/count fallback.
 */
export type FilterHeaderTemplateFunc = (
  h: HyperFunc<any>,
  props: FilterHeaderTemplateProps,
) => VNodeResponse;
```

---

### `FilterHeaderTemplateProps`

Shared visual-template contract for every popup-style filter header.

```ts
/** Shared visual-template contract for every popup-style filter header. */
export type FilterHeaderTemplateProps = {
  column: ColumnRegular;
  columnProp: ColumnProp;
  conditions: readonly Readonly<FilterData>[];
  presentation: FilterHeaderPresentation;
  /** @deprecated Use `presentation.active`. */
  active: boolean;
  /** @deprecated Use `presentation.summary`. */
  text: string;
  /** Selection-only compatibility data. */
  values: FilterHeaderTemplateValue[];
  /** Selection-only compatibility data. */
  totalCount?: number;
  /** Selection-only compatibility option. */
  showCount: boolean;
};
```

---

### `FilterHeaderTemplateValue`

```ts
export type FilterHeaderTemplateValue = {
  value: string;
  label: string;
  count: number;
};
```

---

### `FilterHeaderTriggerState` (Extended from `index.ts`)

```ts
export type FilterHeaderTriggerState = Omit<
  FilterHeaderTemplateProps,
  'column' | 'columnProp' | 'conditions' | 'presentation'
> & {
  conditions?: FilterHeaderTemplateProps['conditions'];
  presentation?: FilterHeaderPresentation;
};
```

---

### `FilterHeaderPlugin`

The FilterHeaderPlugin enhances RevoGrid by adding interactive filter input elements to column headers,
allowing users to filter grid data directly from the header. It dynamically integrates with existing
column templates, providing a seamless UI for text-based filters and selection-based filters.

**Key Features**:
- Adds input fields below each column header for applying text-based filters.
- Integrates with the `AdvanceFilterPlugin` to handle complex filtering operations, supporting multiple
  filter types like selection and slider filters.
- Automatically wraps existing header templates to include filter inputs, maintaining existing header
  content alongside new filter functionality.
- Utilizes debouncing to optimize input handling, minimizing performance impact from frequent user interactions.

**Usage**:
- Include this plugin in RevoGrid's plugin array to activate header filtering capabilities.
  `AdvanceFilterPlugin` is installed automatically.
- Customize column definitions to specify filter types using the `filter` property.

Events:
- Listens for `BEFORE_HEADER_RENDER_EVENT` to modify header templates and append filter UI components.

Usage Example:
```typescript
import { FilterHeaderPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [FilterHeaderPlugin];

grid.columns = [
  {
    prop: 'name',
    name: 'Name',
    filter: ['input'],
  },
];
```

By integrating this plugin, RevoGrid provides an enhanced user experience with improved data filtering
capabilities directly accessible from the grid interface.

#### Dependencies

- **Auto-installed** `AdvanceFilterPlugin`: Provides the advanced filtering runtime used by filter header controls.

```ts
class FilterHeaderPlugin {
  destroy();
}
```

---

### `resolveFilterHeaderLabel`

```ts
export function resolveFilterHeaderLabel(captions: CaptionSource, column?: ColumnRegular): string;
```

---

### `resolveFilterHeaderPlaceholder`

```ts
export function resolveFilterHeaderPlaceholder(
  captions: CaptionSource,
  kind: FilterHeaderPlaceholderKind,
): string;
```

---

### `resolveFilterHeaderSelectionSummary`

```ts
export function resolveFilterHeaderSelectionSummary(
  captions: CaptionSource,
  selected: number,
  total: number,
  details?: string,
): string;
```

---

### `formatFilterHeaderAccessibleSummary`

```ts
export function formatFilterHeaderAccessibleSummary(label: string, summary: string): string;
```

---

### `formatFilterHeaderValueCount`

```ts
export function formatFilterHeaderValueCount(label: string, count: number): string;
```

---

### `resolveFilterHeaderAll`

```ts
export function resolveFilterHeaderAll(captions: CaptionSource): string;
```

---

### `FILTER_HEADER_LOCALIZATION`

Stable localization keys and English fallbacks for filter-header rendering.

```ts
FILTER_HEADER_LOCALIZATION: Readonly<{ captions: Readonly<{ filterHeaderLabel: "Filter {column}"; filterHeaderSearch: "Search…"; filterHeaderAnyDate: "Any date"; filterHeaderEither: "Either"; filterHeaderAnyItem: "Any item"; filterHeaderAnyValue: "Any value"; filterHeaderSelectionSummary: "{selected} of {total} selected"; filterHeaderSelectionSummaryWithDetails: "{selected} of {total} selected: {details}"; filterHeaderAccessibleSummary: "{label}. {summary}"; filterHeaderValueCount: "{label} ({count})"; selectionAll: "All"; }>; }>;
```

---

### `FilterHeaderPlaceholderKind`

```ts
export type FilterHeaderPlaceholderKind = 'search' | 'date' | 'boolean' | 'array' | 'value';
```

---

### `renderFilterHeaderView`

```ts
export function renderFilterHeaderView({
  column,
  columnProp,
  defaultNode,
  isPopupFilter,
  isInputEnabled,
  inputValue,
  showFilterCount,
  inlineControl,
  popupFilterState,
  popupFilterTemplate,
  filterLabel,
  filterPlaceholder,
  formatSelectionSummary,
  onInput,
  onPopup,
}: FilterHeaderViewOptions);
```

---

### `renderFilterHeaderTriggerContent`

```ts
export function renderFilterHeaderTriggerContent(
  column: ColumnRegular | undefined,
  columnProp: ColumnProp,
  state: FilterHeaderTriggerState,
  typeTemplate?: FilterHeaderTemplateFunc,
);
```

---

### `FilterHeaderViewOptions`

```ts
export type FilterHeaderViewOptions = {
  column?: ColumnRegular;
  columnProp: ColumnProp;
  defaultNode?: ReturnType<ColumnTemplateFunc>;
  isPopupFilter: boolean;
  isInputEnabled: boolean;
  inputValue: string;
  showFilterCount: boolean;
  inlineControl?: Extract<FilterHeaderControl, { kind: 'inline' }>;
  popupFilterState?: FilterHeaderTriggerState;
  popupFilterTemplate?: FilterHeaderTemplateFunc;
  filterLabel?: string;
  filterPlaceholder?: string;
  formatSelectionSummary?: FilterHeaderSelectionSummaryFormatter;
  onInput: FilterHeaderInputHandlers;
  onPopup: FilterHeaderPopupHandlers;
};
```

---

### `isInlineTextFilterItem`

```ts
export function isInlineTextFilterItem(filter: FilterData): boolean;
```

---

### `FilterHeaderControl`

Filter-type-owned header presentation. The grid retains the outer layout,
accessibility, popup trigger, and interaction boundary.

```ts
/**
 * Filter-type-owned header presentation. The grid retains the outer layout,
 * accessibility, popup trigger, and interaction boundary.
 */
export type FilterHeaderControl =
  | {
      readonly kind: 'popup';
      /** Optional visual content rendered inside the accessible popup trigger. */
      readonly template?: FilterHeaderTemplateFunc;
    }
  | {
      readonly kind: 'inline';
      /** Interactive control rendered inside the shared non-sorting boundary. */
      readonly template: FilterHeaderInlineTemplateFunc;
      /** Optional stable class retained for type-specific presentation. */
      readonly className?: string;
    };
```

---

### `FilterHeaderInlineTemplateFunc`

Renders an interactive control inside the grid-owned filter-header boundary.

```ts
/** Renders an interactive control inside the grid-owned filter-header boundary. */
export type FilterHeaderInlineTemplateFunc = FilterHeaderTemplateFunc;
```

---

# Form Controls

URL: https://pro.rv-grid.com/api/form-controls/
Source: src/content/docs/api/form-controls.md

### `createFormField`

```ts
export function createFormField(
  document: Document,
  options: FormFieldOptions,
): HTMLLabelElement;
```

---

### `createTextControl`

```ts
export function createTextControl(
  document: Document,
  placeholder: string,
): HTMLInputElement;
```

---

### `createSelectControl`

```ts
export function createSelectControl(
  document: Document,
  options: readonly { value: string; label: string }[],
): HTMLSelectElement;
```

---

### `FormFieldOptions`

```ts
interface FormFieldOptions {
  readonly label: string;
  readonly control: HTMLElement;
  readonly hint?: string;
  readonly className?: string
}
```

---

# Formula

URL: https://pro.rv-grid.com/api/formula/
Source: src/content/docs/api/formula.md

## Module Extensions

### `FormulaNameDefinition`

Defines a workbook-global or sheet-local name used inside formulas.

```ts
interface FormulaNameDefinition {
  name: string;
  scope?: FormulaNameScope;
  sheetId?: string;
  kind?: FormulaNameKind;
  value?: unknown;
  ref?: string;
  comment?: string
}
```

---

### `FormulaDependencyCell`

Zero-based global cell coordinate used by formula dependency highlighting.

Rows follow formula evaluation order: pinned-start, main, then pinned-end.
Columns follow the authored flat leaf order; pinning a column does not change
its A1 coordinate.

**Example:**
```typescript
const dependency: FormulaDependencyCell = { rowIndex: 0, colIndex: 1 };
```

```ts
interface FormulaDependencyCell {
  rowIndex: number;
  colIndex: number
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  asyncformulastatechange: AsyncFormulaStateChangeEventDetail
}
```

---

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  formulaNames?: FormulaNamesConfig | FormulaNameDefinition[];
  'formula-names'?: FormulaNamesConfig | FormulaNameDefinition[];
  formulaWorkbook?: FormulaGridWorkbookConfig | null;
  'formula-workbook'?: FormulaGridWorkbookConfig | null;
  formulaBar?: FormulaBarConfig | null;
  'formula-bar'?: FormulaBarConfig | null;
  formulaDependencyHighlight?: FormulaDependencyHighlightConfig | boolean | null;
  'formula-dependency-highlight'?: FormulaDependencyHighlightConfig | boolean | null
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Legacy formula names configuration.
       * @deprecated Use `grid.formulaNames` instead.
       */
      formulaNames?: FormulaNamesConfig | FormulaNameDefinition[]
}
```

## Plugin API

### `FormulaCellValueContext`

```ts
interface FormulaCellValueContext {
  readonly model: T;
  readonly column: ColumnRegular;
  readonly rowType?: DimensionRows;
  readonly rowIndex?: number;
  readonly colIndex?: number;
  readonly value?: unknown
}
```

---

### `FormulaPlugin`

Formula renderer plugin.

Formula cells still work with the original three-argument evaluator, and when
`NamedRangesPlugin` or `grid.formulaNames` is present the plugin resolves
names while rendering formula values. The plugin installs structural A1
reference tracking so genuine row/column inserts and deletes keep surviving
formulas aligned, plus formula dependency highlighting while editing by
default. Set
`grid.formulaDependencyHighlight = { highlightOnFocus: true }` to also
highlight focused formula cells, or set it to `false` to disable it.

**Example:**
```typescript
grid.plugins = [NamedRangesPlugin, FormulaPlugin];
grid.source = [{ amount: '=SUM(Revenue)' }];
grid.columns = [{ prop: 'amount', name: 'Amount' }];
grid.formulaNames = {
  names: [{ name: 'Revenue', kind: 'range', ref: 'B2:B10' }],
};
```

#### Dependencies

- **Auto-installed** `AutoFillPlugin`: Translates relative and mixed A1 references during range autofill.
- **Auto-installed** `FormulaDependencyHighlightPlugin`: Highlights direct formula precedent cells while a formula cell is edited.
- **Auto-installed** `NamedRangesPlugin`: Keeps A1 references aligned with genuine row and column insertions or deletions.

```ts
class FormulaPlugin {
  destroy();

  /**
     * Return the computed value for a formula cell without changing its raw
     * source model. Consumers such as DataGridFormattingPlugin use this to apply
     * Excel-style value formats to the formula result while editors keep the
     * original `=...` expression.
     */
  resolveCellValue<T extends DataType = DataType>(
    context: FormulaCellValueContext<T>,
  ): unknown;

  /**
     * Register a case-insensitive top-level async formula function.
     *
     * The returned disposer unregisters this exact registration. Registering a
     * FormulaJS name such as `VLOOKUP` intentionally overrides it for this grid.
     */
  registerAsyncFormulaFunction(registration: AsyncFormulaFunctionRegistration): () => void;

  /** Unregister an async formula function and abort its pending cells. */
  unregisterAsyncFormulaFunction(name: string): boolean;

  /** Abort and clear cached async formula cells, optionally for one function. */
  invalidateAsyncFormulaFunction(name?: string): void;

  /** Replace the mounted grid's active-sheet identity and external sheet data. */
  setFormulaWorkbook(config: FormulaGridWorkbookConfig | null): void;

  /** Add or replace one external workbook sheet. */
  upsertFormulaSheet(sheet: FormulaWorkbookSheet): void;

  /** Update an external sheet cell by stable row id. */
  updateFormulaSheetCell(sheetId: string, rowId: string | number, prop: ColumnProp, value: unknown): void;

  /** Remove an external workbook sheet. */
  removeFormulaSheet(sheetId: string): void;
}
```

---

### `NamedRangesPlugin`

Pro plugin that owns the formula-name registry for a grid.

The plugin observes `grid.formulaNames`, `grid['formula-names']`, and legacy
`additionalData.formulaNames`, exposes runtime mutation helpers, emits
formula-name lifecycle events, and updates deterministic A1 refs in names and
existing source formulas when rows or columns are inserted or deleted.

**Example:**
```typescript
const grid = document.querySelector('revo-grid')!;
grid.plugins = [NamedRangesPlugin, FormulaPlugin];
grid.formulaNames = {
  activeSheetId: 'Budget',
  names: [
    { name: 'Revenue', kind: 'range', ref: 'B2:B10' },
    { name: 'Target', kind: 'constant', value: 100000 },
  ],
};

grid.addEventListener('formulanameschange', event => {
  console.log(event.detail.names);
});
```

```ts
class NamedRangesPlugin {
  destroy();

  /**
     * Return a defensive copy of the currently valid formula names.
     *
     * @example
     * ```ts
     * const names = namedRangesPlugin.getFormulaNames();
     * ```
     */
  getFormulaNames(): FormulaNameDefinition[];

  /**
     * Return the current registry as public config.
     *
     * @example
     * ```ts
     * grid.formulaNames = namedRangesPlugin.getFormulaNamesConfig();
     * ```
     */
  getFormulaNamesConfig(): FormulaNamesConfig;

  /**
     * Return a defensive copy of the normalized formula-name registry.
     *
     * @example
     * ```ts
     * const registry = namedRangesPlugin.getFormulaNameRegistry();
     * ```
     */
  getFormulaNameRegistry(): FormulaNameRegistry;

  getFormulaNameRegistryForEvaluation(): FormulaNameRegistry;

  /**
     * Replace the full formula-name registry.
     *
     * Invalid names are excluded from the active registry and emitted through
     * `formulanamevalidationerror`.
     *
     * @example
     * ```ts
     * namedRangesPlugin.setFormulaNames({
     *   names: [{ name: 'Limit', kind: 'constant', value: 5000 }],
     * });
     * ```
     */
  setFormulaNames(input: FormulaNamesInput): FormulaNameRegistry;

  /**
     * Create or replace one formula name in its scope.
     *
     * @example
     * ```ts
     * namedRangesPlugin.upsertFormulaName({
     *   name: 'CurrentQuarter',
     *   scope: 'sheet',
     *   sheetId: 'Q4',
     *   kind: 'range',
     *   ref: 'C2:C20',
     * });
     * ```
     */
  upsertFormulaName(definition: FormulaNameDefinition): FormulaNameRegistry;

  /**
     * Delete a formula name.
     *
     * Pass `scope` and `sheetId` when you need to delete a specific sheet-local
     * name without affecting a workbook-global name with the same display name.
     *
     * @example
     * ```ts
     * namedRangesPlugin.deleteFormulaName('CurrentQuarter', 'sheet', 'Q4');
     * namedRangesPlugin.deleteFormulaName('Target', 'workbook');
     * ```
     */
  deleteFormulaName(name: string, scope?: FormulaNameDefinition['scope'], sheetId?: string): FormulaNameRegistry;

  /**
     * Validate a formula-name definition against the current registry.
     *
     * @example
     * ```ts
     * const validation = namedRangesPlugin.validateFormulaNameRef({
     *   name: 'Revenue',
     *   kind: 'range',
     *   ref: 'B2:B20',
     * });
     * ```
     */
  validateFormulaNameRef(definition: FormulaNameDefinition): FormulaNameValidationResult;

  /**
     * Scroll to and focus the first cell of a range name.
     *
     * Returns `false` when the name is missing, is not a range, or has an invalid
     * reference.
     *
     * @example
     * ```ts
     * await namedRangesPlugin.jumpToFormulaName('Revenue');
     * ```
     */
  async jumpToFormulaName(name: string): Promise<boolean>;
}
```

---

### `evaluate`

Evaluate a formula body with a custom cell-value resolver.

This low-level helper is kept for backward compatibility. Prefer
`evaluateRawValuesFormula` when evaluating against grid rows and columns.

**Example:**
```typescript
const result = evaluate('A1 + B1', (col, row) => {
  return col === 0 && row === 0 ? 2 : 3;
});
// 5
```

```ts
export function evaluate(
  formulaValue: string,
  getCellValueByAddress: CellValueResolver,
): unknown;
```

---

### `evaluateRawValuesFormula`

Evaluate a formula string against grid row data and columns.

The fourth argument is optional and enables formula-name resolution, active
sheet scope, and current-cell tokens used by conditional formulas.

**Example:**
```typescript
const value = evaluateRawValuesFormula('=SUM(Revenue) * TaxFactor', rows, columns, {
  activeSheetId: 'Budget',
  names: [
    { name: 'Revenue', kind: 'range', ref: 'B2:B10' },
    { name: 'TaxFactor', kind: 'constant', value: 1.2 },
  ],
});
```

```ts
export function evaluateRawValuesFormula(
  formulaValue: string,
  allSources: DataType[],
  columns: ColumnRegular[],
  options: FormulaEvaluationOptions = {},
);
```

---

### `evaluateNamedFormula`

Evaluate a named constant, range, or formula definition.

Constants return their value, ranges return their resolved range values, and
formula names execute their formula body with nested named-formula support.
Circular references return `FORMULA_ERROR`.

**Example:**
```typescript
const value = evaluateNamedFormula('GrossSales', {
  allSources: rows,
  columns,
  names: [
    { name: 'Sales', kind: 'range', ref: 'B2:B10' },
    { name: 'GrossSales', kind: 'formula', value: '=SUM(Sales)' },
  ],
});
```

```ts
export function evaluateNamedFormula(
  nameOrDefinition: string | FormulaNameDefinition,
  context: FormulaEvaluationContext,
);
```

---

### `resolveNamedRangeValues`

Resolve a named range into a flat list of values.

Returns an empty array when the name is missing or does not resolve to a range.

**Example:**
```typescript
const statuses = resolveNamedRangeValues('Statuses', {
  allSources: rows,
  columns,
  names: [{ name: 'Statuses', kind: 'range', ref: 'A2:A5' }],
});
```

```ts
export function resolveNamedRangeValues(
  name: string,
  context: FormulaEvaluationContext,
): unknown[];
```

---

### `createNamedRangeDropdown`

Build dropdown props whose source is populated from a named range.

Use this as a lightweight validation-list helper. Dropdown overrides are merged
after the named-range source is generated.

**Example:**
```typescript
const statusDropdown = createNamedRangeDropdown('Statuses', {
  allSources: rows,
  columns,
  names: [{ name: 'Statuses', kind: 'range', ref: 'A2:A5' }],
  label: value => `Status: ${value}`,
}, {
  clearable: true,
});
```

```ts
export function createNamedRangeDropdown(
  name: string,
  context: NamedRangeDropdownContext,
  dropdownOverrides: NamedRangeDropdownOptions = {},
): DropdownColumnProps;
```

---

### `createFormulaConditionalCellProperties`

Create a RevoGrid `cellProperties` callback powered by a formula.

The formula is evaluated for each cell. When it resolves to a truthy value, the
supplied cell props are applied. Conditional formulas can use named constants
and ranges plus the current-cell tokens `cellvalue`, `row`, and `column`.

**Example:**
```typescript
const highlightOverTarget = createFormulaConditionalCellProperties(
  '=cellvalue >= Target',
  { class: 'over-target' },
  {
    allSources: rows,
    columns,
    names: [{ name: 'Target', kind: 'constant', value: 1000 }],
  },
);

columns[1].cellProperties = highlightOverTarget;
```

```ts
export function createFormulaConditionalCellProperties(
  formulaValue: string,
  matchProps: FormulaConditionalCellProperties,
  context: FormulaConditionalCellPropertiesContext,
): PropertiesFunc;
```

---

### `FORMULA_PREFIX`

Prefix used to identify a formula string.

```ts
FORMULA_PREFIX: string;
```

---

### `FORMULA_ERROR`

Error string returned when formula evaluation fails or recursion is detected.

```ts
FORMULA_ERROR: string;
```

---

### `isFormula`

Check whether a value is a formula string.

```ts
isFormula: (value?: unknown) => boolean;
```

---

### `parseFormula`

Replace A1 cell references in an expression with resolved literal values.

```ts
parseFormula: (expression: string, getCellValueByAddress: CellValueResolver) => string;
```

---

### `ABS`

Returns the absolute value of a number.

Category: Math and trigonometry

**@param** {*} number The real number of which you want the absolute value.

**@returns**

```ts
export function ABS(number: any): number | Error;;
```

---

### `ACCRINT`

Returns the accrued interest for a security that pays periodic interest.

Category: Financial

**@param** {*} issue The security's issue date.

**@param** {*} first_interest The security's first interest date.

**@param** {*} settlement The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

**@param** {*} rate The security's annual coupon rate.

**@param** {*} par The security's par value. If you omit par, ACCRINT uses $1,000.

**@param** {*} frequency The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

**@param** {*} [basis] Optional. The type of day count basis to use.

**@param** {*} [calc_method] Optional. Not implemented in formulajs. A logical value that specifies the way to calculate the total accrued interest when the date of settlement is later than the date of first_interest. A value of TRUE (1) returns the total accrued interest from issue to settlement. A value of FALSE (0) returns the accrued interest from first_interest to settlement. If you do not enter the argument, it defaults to TRUE.

**@returns**

```ts
export function ACCRINT(issue: any, first_interest: any, settlement: any, rate: any, par: any, frequency: any, basis?: any): number | Error;;
```

---

### `ACOS`

Returns the arccosine of a number.

Category: Math and trigonometry

**@param** {*} number The cosine of the angle you want and must be from -1 to 1.

**@returns**

```ts
export function ACOS(number: any): number | Error;;
```

---

### `ACOSH`

Returns the inverse hyperbolic cosine of a number.

Category: Math and trigonometry

**@param** {*} number Any real number equal to or greater than 1.

**@returns**

```ts
export function ACOSH(number: any): number | Error;;
```

---

### `ACOT`

Returns the arccotangent of a number.

Category: Math and trigonometry

**@param** {*} number Number is the cotangent of the angle you want. This must be a real number.

**@returns**

```ts
export function ACOT(number: any): number | Error;;
```

---

### `ACOTH`

Returns the hyperbolic arccotangent of a number.

Category: Math and trigonometry

**@param** {*} number The absolute value of Number must be greater than 1.

**@returns**

```ts
export function ACOTH(number: any): number | Error;;
```

---

### `AGGREGATE`

Returns an aggregate in a list or database.

Category: Math and trigonometry

**@param** {*} function_num A number 1 to 19 that specifies which function to use.

**@param** {*} options A numerical value that determines which values to ignore in the evaluation range for the function. Note: The function will not ignore hidden rows, nested subtotals or nested aggregates if the array argument includes a calculation, for example: =AGGREGATE(14,3,A1:A100*(A1:A100>0),1)

**@param** {*} ref1 The first numeric argument for functions that take multiple numeric arguments for which you want the aggregate value.

**@param** {*} [ref2] Optional. Numeric arguments 2 to 253 for which you want the aggregate value. For functions that take an array, ref1 is an array, an array formula, or a reference to a range of values for which you want the aggregate value. Ref2 is a second argument that is required for certain functions.

**@returns**

```ts
export function AGGREGATE(function_num: any, options: any, ref1: any, ref2?: any): any;;
```

---

### `AND`

Returns TRUE if all of its arguments are TRUE.

Category: Logical

**@returns**

```ts
export function AND(...args: any[]): any;;
```

---

### `ARABIC`

Converts a Roman number to Arabic, as a number.

Category: Math and trigonometry

**@param** {*} text A string enclosed in quotation marks, an empty string (""), or a reference to a value containing text.

**@returns**

```ts
export function ARABIC(text: any): number | Error;;
```

---

### `ASIN`

Returns the arcsine of a number.

Category: Math and trigonometry

**@param** {*} number The sine of the angle you want and must be from -1 to 1.

**@returns**

```ts
export function ASIN(number: any): number | Error;;
```

---

### `ASINH`

Returns the inverse hyperbolic sine of a number.

Category: Math and trigonometry

**@param** {*} number Any real number.

**@returns**

```ts
export function ASINH(number: any): number | Error;;
```

---

### `ATAN`

Returns the arctangent of a number.

Category: Math and trigonometry

**@param** {*} number The tangent of the angle you want.

**@returns**

```ts
export function ATAN(number: any): number | Error;;
```

---

### `ATAN2`

Returns the arctangent from x- and y-coordinates.

Category: Math and trigonometry

**@param** {*} x_num The x-coordinate of the point.

**@param** {*} y_num The y-coordinate of the point.

**@returns**

```ts
export function ATAN2(x_num: any, y_num: any): any;;
```

---

### `ATANH`

Returns the inverse hyperbolic tangent of a number.

Category: Math and trigonometry

**@param** {*} number Any real number between 1 and -1.

**@returns**

```ts
export function ATANH(number: any): number | Error;;
```

---

### `AVEDEV`

Returns the average of the absolute deviations of data points from their mean.

Category: Statistical

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 arguments for which you want the average of the absolute deviations. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function AVEDEV(...args: any[]): number | Error;;
```

---

### `AVERAGE`

Returns the average of its arguments.

Category: Statistical

**@param** {*} args number1, number2, ...Numbers, value references or ranges for which you want the average.

**@returns**

```ts
export function AVERAGE(...args: any[]): any;;
```

---

### `AVERAGEA`

Returns the average of its arguments, including numbers, text, and logical values.

Category: Statistical

**@param** {*} args value1, value2, ... Value1 is required, subsequent values are optional. 1 to 255 values, ranges of values, or values for which you want the average.

**@returns**

```ts
export function AVERAGEA(...args: any[]): any;;
```

---

### `AVERAGEIF`

Returns the average (arithmetic mean) of all the values in a range that meet a given criteria.

Category: Statistical

**@param** {*} range One or more values to average, including numbers or names, arrays, or references that contain numbers.

**@param** {*} criteria The criteria in the form of a number, expression, value reference, or text that defines which values are averaged.

**@param** {*} [average_range] Optional. The actual set of values to average. If omitted, range is used.

**@returns**

```ts
export function AVERAGEIF(range: any, criteria: any, average_range?: any, ...args: any[]): number | Error;;
```

---

### `AVERAGEIFS`

Returns the average (arithmetic mean) of all values that meet multiple criteria.

Category: Statistical

**@param** {*} args One or more values to average, including numbers or names, arrays, or references that contain numbers.

**@returns**

```ts
export function AVERAGEIFS(...args: any[]): number;;
```

---

### `BASE`

Converts a number into a text representation with the given radix (base).

Category: Math and trigonometry

**@param** {*} number The number that you want to convert. Must be an integer greater than or equal to 0 and less than 2^53.

**@param** {*} radix The base radix that you want to convert the number into. Must be an integer greater than or equal to 2 and less than or equal to 36.

**@param** {*} [min_length] Optional. The minimum length of the returned string. Must be an integer greater than or equal to 0.

**@returns**

```ts
export function BASE(number: any, radix: any, min_length?: any): any;;
```

---

### `BESSELI`

Returns the modified Bessel function In(x).

Category: Engineering

**@param** {*} x The value at which to evaluate the function.

**@param** {*} n The order of the Bessel function. If n is not an integer, it is truncated.

**@returns**

```ts
export function BESSELI(x: any, n: any): any;;
```

---

### `BESSELJ`

Returns the Bessel function Jn(x).

Category: Engineering

**@param** {*} x The value at which to evaluate the function.

**@param** {*} n The order of the Bessel function. If n is not an integer, it is truncated.

**@returns**

```ts
export function BESSELJ(x: any, n: any): any;;
```

---

### `BESSELK`

Returns the modified Bessel function Kn(x).

Category: Engineering

**@param** {*} x The value at which to evaluate the function.

**@param** {*} n The order of the function. If n is not an integer, it is truncated.

**@returns**

```ts
export function BESSELK(x: any, n: any): any;;
```

---

### `BESSELY`

Returns the Bessel function Yn(x).

Category: Engineering

**@param** {*} x The value at which to evaluate the function.

**@param** {*} n The order of the function. If n is not an integer, it is truncated.

**@returns**

```ts
export function BESSELY(x: any, n: any): any;;
```

---

### `BETADIST`

Returns the beta cumulative distribution function.

Category: Statistical

**@param** {*} x The value between A and B at which to evaluate the function

**@param** {*} alpha A parameter of the distribution.

**@param** {*} beta A parameter of the distribution.

**@param** {*} cumulative A logical value that determines the form of the function. If cumulative is TRUE, BETA.DIST returns the cumulative distribution function; if FALSE, it returns the probability density function.

**@param** {*} [a] Optional. A lower bound to the interval of x.

**@param** {*} [b] Optional. An upper bound to the interval of x.

**@returns**

```ts
export function BETADIST(x: any, alpha: any, beta: any, cumulative: any, a?: any, b?: any, ...args: any[]): any;;
```

---

### `BETAINV`

Returns the inverse of the cumulative distribution function for a specified beta distribution.

Category: Statistical

**@param** {*} probability A probability associated with the beta distribution.

**@param** {*} alpha A parameter of the distribution.

**@param** {*} beta A parameter the distribution.

**@param** {*} [a] Optional. A lower bound to the interval of x.

**@param** {*} [b] Optional. An upper bound to the interval of x.

**@returns**

```ts
export function BETAINV(probability: any, alpha: any, beta: any, a?: any, b?: any): any;;
```

---

### `BIN2DEC`

Converts a binary number to decimal.

Category: Engineering

**@param** {*} number The binary number you want to convert. Number cannot contain more than 10 characters (10 bits). The most significant bit of number is the sign bit. The remaining 9 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@returns**

```ts
export function BIN2DEC(number: any): number | Error;;
```

---

### `BIN2HEX`

Converts a binary number to hexadecimal.

Category: Engineering

**@param** {*} number The binary number you want to convert. Number cannot contain more than 10 characters (10 bits). The most significant bit of number is the sign bit. The remaining 9 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@param** {*} [places] Optional. The number of characters to use. If places is omitted, BIN2HEX uses the minimum number of characters necessary. Places is useful for padding the return value with leading 0s (zeros).

**@returns**

```ts
export function BIN2HEX(number: any, places?: any): string | Error;;
```

---

### `BIN2OCT`

Converts a binary number to octal.

Category: Engineering

**@param** {*} number The binary number you want to convert. Number cannot contain more than 10 characters (10 bits). The most significant bit of number is the sign bit. The remaining 9 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@param** {*} [places] Optional. The number of characters to use. If places is omitted, BIN2OCT uses the minimum number of characters necessary. Places is useful for padding the return value with leading 0s (zeros).

**@returns**

```ts
export function BIN2OCT(number: any, places?: any): string | Error;;
```

---

### `BINOMDIST`

Returns the individual term binomial distribution probability.

Category: Statistical

**@param** {*} number_s The number of successes in trials.

**@param** {*} trials The number of independent trials.

**@param** {*} probability_s The probability of success on each trial.

**@param** {*} cumulative A logical value that determines the form of the function. If cumulative is TRUE, then BINOM.DIST returns the cumulative distribution function, which is the probability that there are at most number_s successes; if FALSE, it returns the probability mass function, which is the probability that there are number_s successes.

**@returns**

```ts
export function BINOMDIST(number_s: any, trials: any, probability_s: any, cumulative: any): any;;
```

---

### `BITAND`

Returns a 'Bitwise And' of two numbers.

Category: Engineering

**@param** {*} number1 Must be in decimal form and greater than or equal to 0.

**@param** {*} number2 Must be in decimal form and greater than or equal to 0.

**@returns**

```ts
export function BITAND(number1: any, number2: any): number | Error;;
```

---

### `BITLSHIFT`

Returns a value number shifted left by shift_amount bits.

Category: Engineering

**@param** {*} number Number must be an integer greater than or equal to 0.

**@param** {*} shift_amount Shift_amount must be an integer.

**@returns**

```ts
export function BITLSHIFT(number: any, shift_amount: any): number | Error;;
```

---

### `BITOR`

Returns a bitwise OR of 2 numbers.

Category: Engineering

**@param** {*} number1 Must be in decimal form and greater than or equal to 0.

**@param** {*} number2 Must be in decimal form and greater than or equal to 0.

**@returns**

```ts
export function BITOR(number1: any, number2: any): number | Error;;
```

---

### `BITRSHIFT`

Returns a value number shifted right by shift_amount bits.

Category: Engineering

**@param** {*} number Must be an integer greater than or equal to 0.

**@param** {*} shift_amount Must be an integer.

**@returns**

```ts
export function BITRSHIFT(number: any, shift_amount: any): number | Error;;
```

---

### `BITXOR`

Returns a bitwise 'Exclusive Or' of two numbers.

Category: Engineering

**@param** {*} number1 Must be greater than or equal to 0.

**@param** {*} number2 Must be greater than or equal to 0.

**@returns**

```ts
export function BITXOR(number1: any, number2: any): number | Error;;
```

---

### `CEILING`

Rounds a number to the nearest integer or to the nearest multiple of significance.

Category: Math and trigonometry

**@param** {*} number The value you want to round.

**@param** {*} significance The multiple to which you want to round.

**@param** {*} [mode] Optional. For negative numbers, controls whether Number is rounded toward or away from zero.

**@returns**

```ts
export function CEILING(number: any, significance: any): any;;
```

---

### `CEILINGMATH`

Rounds a number up, to the nearest integer or to the nearest multiple of significance.

Category: Math and trigonometry

**@param** {*} number The value you want to round.

**@param** {*} [significance] Optional. This is the number of significant digits after the decimal point to which number is to be rounded.

**@param** {*} [mode] Optional. For negative numbers, controls whether Number is rounded toward or away from zero.

**@returns**

```ts
export function CEILINGMATH(number: any, significance?: any, mode?: any): any;;
```

---

### `CEILINGPRECISE`

Rounds a number up, to the nearest integer or to the nearest multiple of significance.

Category: Math and trigonometry

**@param** {*} number The value you want to round.

**@param** {*} [significance] Optional. This is the number of significant digits after the decimal point to which number is to be rounded.

**@returns**

```ts
export function CEILINGPRECISE(number: any, significance?: any): any;;
```

---

### `CHAR`

Returns the character specified by the code number.

Category: Text

**@param** {*} number A number between 1 and 255 specifying which character you want. The character is from the character set used by your computer. Note: Excel for the web supports only CHAR(9), CHAR(10), CHAR(13), and CHAR(32) and above.

**@returns**

```ts
export function CHAR(number: any): string | Error;;
```

---

### `CHIDIST`

Returns the cumulative beta probability density function.

Category: Statistical

**@param** {*} x The value at which you want to evaluate the distribution.

**@param** {*} deg_freedom The number of degrees of freedom.

**@param** {*} cumulative A logical value that determines the form of the function. If cumulative is TRUE, CHISQ.DIST returns the cumulative distribution function; if FALSE, it returns the probability density function.

**@returns**

```ts
export function CHIDIST(x: any, deg_freedom: any, cumulative: any): any;;
```

---

### `CHIDISTRT`

Returns the one-tailed probability of the chi-squared distribution.

Category: Statistical

**@param** {*} x The value at which you want to evaluate the distribution.

**@param** {*} deg_freedom The number of degrees of freedom.

**@returns**

```ts
export function CHIDISTRT(x: any, deg_freedom: any): number | Error;;
```

---

### `CHIINV`

Returns the cumulative beta probability density function.

Category: Statistical

**@param** {*} probability A probability associated with the chi-squared distribution.

**@param** {*} deg_freedom The number of degrees of freedom.

**@returns**

```ts
export function CHIINV(probability: any, deg_freedom: any): any;;
```

---

### `CHIINVRT`

Returns the inverse of the one-tailed probability of the chi-squared distribution.

Category: Statistical

**@param** {*} probability A probability associated with the chi-squared distribution.

**@param** {*} deg_freedom The number of degrees of freedom.

**@returns**

```ts
export function CHIINVRT(probability: any, deg_freedom: any): any;;
```

---

### `CHITEST`

Returns the test for independence.

Category: Statistical

**@param** {*} actual_range The range of data that contains observations to test against expected values.

**@param** {*} expected_range The range of data that contains the ratio of the product of row totals and column totals to the grand total.

**@returns**

```ts
export function CHITEST(actual_range: any, expected_range: any, ...args: any[]): number | Error;;
```

---

### `CHOOSE`

Chooses a value from a list of values.

Category: Lookup and reference

**@param** {*} index_num Specifies which value argument is selected. Index_num must be a number between 1 and 254, or a formula or reference to a value containing a number between 1 and 254. If index_num is 1, CHOOSE returns value1; if it is 2, CHOOSE returns value2; and so on. If index_num is less than 1 or greater than the number of the last value in the list, CHOOSE returns the #VALUE! error value. If index_num is a fraction, it is truncated to the lowest integer before being used.
 - If index_num is 1, CHOOSE returns value1; if it is 2, CHOOSE returns value2; and so on.
 - If index_num is less than 1 or greater than the number of the last value in the list, CHOOSE returns the #VALUE! error value.
 - If index_num is a fraction, it is truncated to the lowest integer before being used.

**@param** {*} args value1, value2, ... Value 1 is required, subsequent values are optional. 1 to 254 value arguments from which CHOOSE selects a value or an action to perform based on index_num. The arguments can be numbers, value references, defined names, formulas, functions, or text.

**@returns**

```ts
export function CHOOSE(...args: any[]): any;;
```

---

### `CHOOSECOLS`

Returns the specified columns from an array.

Category: Lookup and reference

**@param** {*} array range of values or an array constant.

**@param** {*} col_num1 required column index

**@param** {*} col_nums additionnal column indexes

**@returns**

```ts
export function CHOOSECOLS(array: any, col_num1: any, ...col_nums: any): any[] | Error;;
```

---

### `CHOOSEROWS`

Returns the specified rows from an array.

Category: Lookup and reference

**@param** {*} array array range of values or an array constant.

**@param** {*} row_num1 required row index

**@param** {*} row_nums additionnal row indexes

**@returns**

```ts
export function CHOOSEROWS(array: any, row_num1: any, ...row_nums: any): any;;
```

---

### `CLEAN`

Removes all nonprintable characters from text.

Category: Text

**@param** {*} text Any worksheet information from which you want to remove nonprintable characters.

**@returns**

```ts
export function CLEAN(text: any): any;;
```

---

### `CODE`

Returns a numeric code for the first character in a text string.

Category: Text

**@param** {*} text The text for which you want the code of the first character.

**@returns**

```ts
export function CODE(text: any): any;;
```

---

### `COLUMN`

Returns the column number of a reference.

Category: Lookup and reference

**@param** {*} reference the value or range of values for which you want to return the column number.

**@param** {*} index

**@returns**

```ts
export function COLUMN(reference: any, index: any, ...args: any[]): any;;
```

---

### `COLUMNS`

Returns the number of columns in a reference.

Category: Lookup and reference

**@param** {*} array An array or array formula, or a reference to a range of values for which you want the number of columns.

**@returns**

```ts
export function COLUMNS(array: any, ...args: any[]): any;;
```

---

### `COMBIN`

Returns the number of combinations for a given number of objects.

Category: Math and trigonometry

**@param** {*} number The number of items.

**@param** {*} number_chosen The number of items in each combination.

**@returns**

```ts
export function COMBIN(number: any, number_chosen: any): any;;
```

---

### `COMBINA`

Returns the number of combinations with repetitions for a given number of items.

Category: Math and trigonometry

**@param** {*} number Must be greater than or equal to 0, and greater than or equal to Number_chosen. Non-integer values are truncated.

**@param** {*} number_chosen Must be greater than or equal to 0. Non-integer values are truncated.

**@returns**

```ts
export function COMBINA(number: any, number_chosen: any): any;;
```

---

### `COMPLEX`

Converts real and imaginary coefficients into a complex number.

Category: Engineering

**@param** {*} real_num The real coefficient of the complex number.

**@param** {*} i_num The imaginary coefficient of the complex number.

**@param** {*} [suffix] Optional. The suffix for the imaginary component of the complex number. If omitted, suffix is assumed to be "i".

**@returns**

```ts
export function COMPLEX(real_num: any, i_num: any, suffix?: any): any;;
```

---

### `CONCAT`

Joins several text items into one text item.

Category: Text

**@returns**

```ts
export function CONCAT(...args: any[]): any;;
```

---

### `CONCATENATE`

Joins several text items into one text item.

Category: Text

**@returns**

```ts
export function CONCATENATE(...args: any[]): any;;
```

---

### `CONVERT`

Converts a number from one measurement system to another.

Category: Engineering

**@param** {*} number is the value in from_units to convert.

**@param** {*} from_unit is the units for number.

**@param** {*} to_unit is the units for the result. CONVERT accepts the following text values (in quotation marks) for from_unit and to_unit.

**@returns**

```ts
export function CONVERT(number: any, from_unit: any, to_unit: any): number | Error;;
```

---

### `CORREL`

Returns the correlation coefficient between two data sets.

Category: Statistical

**@param** {*} array1 A range of value values.

**@param** {*} array2 A second range of value values.

**@returns**

```ts
export function CORREL(array1: any, array2: any): any;;
```

---

### `COS`

Returns the cosine of a number.

Category: Math and trigonometry

**@param** {*} number The angle in radians for which you want the cosine.

**@returns**

```ts
export function COS(number: any): number | Error;;
```

---

### `COSH`

Returns the hyperbolic cosine of a number.

Category: Math and trigonometry

**@param** {*} number Any real number for which you want to find the hyperbolic cosine.

**@returns**

```ts
export function COSH(number: any): number | Error;;
```

---

### `COT`

Returns the hyperbolic cosine of a number.

Category: Math and trigonometry

**@param** {*} number The angle in radians for which you want the cotangent.

**@returns**

```ts
export function COT(number: any): number | Error;;
```

---

### `COTH`

Returns the cotangent of an angle.

Category: Math and trigonometry

**@param** {*} number

**@returns**

```ts
export function COTH(number: any): number | Error;;
```

---

### `COUNT`

Counts how many numbers are in the list of arguments.

Category: Statistical

**@param** {*} args Cell reference, or range within which you want to count numbers.count numbers.

**@returns**

```ts
export function COUNT(...args: any[]): any;;
```

---

### `COUNTA`

Counts how many values are in the list of arguments.

Category: Statistical

**@param** {*} args Arguments representing the values that you want to count.

**@returns**

```ts
export function COUNTA(...args: any[]): number;;
```

---

### `COUNTBLANK`

Counts the number of blank values within a range.

Category: Statistical

**@param** {*} args The range from which you want to count the blank values.

**@returns**

```ts
export function COUNTBLANK(...args: any[]): number;;
```

---

### `COUNTIF`

Counts the number of values within a range that meet the given criteria.

Category: Statistical

**@returns**

```ts
export function COUNTIF(range: any, criteria: any): any;;
```

---

### `COUNTIFS`

Counts the number of values within a range that meet multiple criteria.

Category: Statistical

**@param** {*} args Range in which to evaluate the associated criteria.

**@returns**

```ts
export function COUNTIFS(...args: any[]): number;;
```

---

### `COUPDAYS`

Returns the number of days in the coupon period that contains the settlement date.

Category: Financial

**@param** {*} settlement The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

**@param** {*} maturity The security's maturity date. The maturity date is the date when the security expires.

**@param** {*} frequency The number of coupon payments per year. For annual payments, frequency = 1; for semiannual, frequency = 2; for quarterly, frequency = 4.

**@param** {*} [basis] Optional. The type of day count basis to use.

**@returns**

```ts
export function COUPDAYS(settlement: any, maturity: any, frequency: any, basis?: any): number | Error;;
```

---

### `COVAR`

Returns covariance, the average of the products of paired deviations.

Category: Statistical

**@param** {*} array1 The first value range of integers.

**@param** {*} array2 The second value range of integers.

**@returns**

```ts
export function COVAR(array1: any, array2: any): number | Error;;
```

---

### `COVARIANCEP`

Returns covariance, the average of the products of paired deviations.

Category: Statistical

**@param** {*} array1 The first value range of integers.

**@param** {*} array2 The second value range of integers.

**@returns**

```ts
export function COVARIANCEP(array1: any, array2: any): number | Error;;
```

---

### `COVARIANCES`

Returns the sample covariance, the average of the products deviations for each data point pair in two data sets.

Category: Statistical

**@param** {*} array1 The first value range of integers.

**@param** {*} array2 The second value range of integers.

**@returns**

```ts
export function COVARIANCES(array1: any, array2: any): any;;
```

---

### `CRITBINOM`

Returns the smallest value for which the cumulative binomial distribution is less than or equal to a criterion value.

Category: Statistical

**@param** {*} trials The number of Bernoulli trials.

**@param** {*} probability_s The probability of a success on each trial.

**@param** {*} alpha The criterion value.

**@returns**

```ts
export function CRITBINOM(trials: any, probability_s: any, alpha: any): number | Error;;
```

---

### `CSC`

Returns the cosecant of an angle.

Category: Math and trigonometry

**@param** {*} number

**@returns**

```ts
export function CSC(number: any): number | Error;;
```

---

### `CSCH`

Returns the hyperbolic cosecant of an angle.

Category: Math and trigonometry

**@param** {*} number

**@returns**

```ts
export function CSCH(number: any): number | Error;;
```

---

### `CUMIPMT`

Returns the cumulative interest paid between two periods.

Category: Financial

**@param** {*} rate The interest rate.

**@param** {*} nper The total number of payment periods.

**@param** {*} pv The present value.

**@param** {*} start_period The first period in the calculation. Payment periods are numbered beginning with 1.

**@param** {*} end_period The last period in the calculation.

**@param** {*} type The timing of the payment.

**@returns**

```ts
export function CUMIPMT(rate: any, nper: any, pv: any, start_period: any, end_period: any, type: any): number | Error;;
```

---

### `CUMPRINC`

Returns the cumulative principal paid on a loan between two periods.

Category: Financial

**@param** {*} rate The interest rate.

**@param** {*} nper The total number of payment periods.

**@param** {*} pv The present value.

**@param** {*} start_period The first period in the calculation. Payment periods are numbered beginning with 1.

**@param** {*} end_period The last period in the calculation.

**@param** {*} type The timing of the payment.

**@returns**

```ts
export function CUMPRINC(rate: any, nper: any, pv: any, start_period: any, end: any, type: any): number | Error;;
```

---

### `DATE`

Returns the serial number of a particular date.

Category: Date and time

**@param** {*} year Year

**@param** {*} month Month

**@param** {*} day Day

**@returns**

```ts
export function DATE(year: any, month: any, day: any): number | Date | Error;;
```

---

### `DATEDIF`

Calculates the number of days, months, or years between two dates. This function is useful in formulas where you need to calculate an age.

Category: Date and time

**@param** {*} start_date A date that represents the first, or starting date of a given period.

**@param** {*} end_date A date that represents the last, or ending, date of the period.

**@param** {*} unit The type of information that you want returned, where:
 - "Y": The number of complete years in the period.
 - "M": The number of complete months in the period.
 - "D": The number of days in the period.
 - "MD": The difference between the days in start_date and end_date. The months and years of the dates are ignored.
 - "YM": The difference between the months in start_date and end_date. The days and years of the dates are ignored
 - "YD": The difference between the days of start_date and end_date. The years of the dates are ignored.

**@returns**

```ts
export function DATEDIF(start_date: any, end_date: any, unit: any): number | Error;;
```

---

### `DATEVALUE`

Converts a date in the form of text to a serial number.

Category: Date and time

**@param** {*} date_text Text that represents a date in an Excel date format, or a reference to a value that contains text that represents a date in an Excel date format.

**@returns**

```ts
export function DATEVALUE(date_text: any): number | Date | Error;;
```

---

### `DAVERAGE`

Returns the average of selected database entries.

Category: Database

**@param** {*} database Range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria Range of values that contains the conditions you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DAVERAGE(database: any, field: any, criteria: any): number | Error;;
```

---

### `DAY`

Converts a serial number to a day of the month.

Category: Date and time

**@param** {*} serial_number The date of the day you are trying to find.

**@returns**

```ts
export function DAY(serial_number: any): any;;
```

---

### `DAYS`

Returns the number of days between two dates.

Category: Date and time

**@param** {*} end_date Start_date and End_date are the two dates between which you want to know the number of days.

**@param** {*} start_date Start_date and End_date are the two dates between which you want to know the number of days.

**@returns**

```ts
export function DAYS(end_date: any, start_date: any): number | Error;;
```

---

### `DAYS360`

Calculates the number of days between two dates based on a 360-day year.

Category: Date and time

**@param** {*} start_date A date that represents the start date. If start_date occurs after end_date, the DAYS360 function returns a negative number.

**@param** {*} end_date A date that represents the end date.

**@param** {*} [method] Optional. A logical value that specifies whether to use the U.S. or European method in the calculation.

**@returns**

```ts
export function DAYS360(start_date: any, end_date: any, method?: any): number | Error;;
```

---

### `DB`

Returns the depreciation of an asset for a specified period by using the fixed-declining balance method.

Category: Financial

**@param** {*} cost The initial cost of the asset.

**@param** {*} salvage The value at the end of the depreciation (sometimes called the salvage value of the asset).

**@param** {*} life The number of periods over which the asset is being depreciated (sometimes called the useful life of the asset).

**@param** {*} period The period for which you want to calculate the depreciation. Period must use the same units as life.

**@param** {*} [month] Optional. The number of months in the first year. If month is omitted, it is assumed to be 12.

**@returns**

```ts
export function DB(cost: any, salvage: any, life: any, period: any, month?: any): number | Error;;
```

---

### `DCOUNT`

Counts the values that contain numbers in a database.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria The range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as the argument includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DCOUNT(database: any, field: any, criteria: any): any;;
```

---

### `DCOUNTA`

Counts nonblank values in a database.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Optional. Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria The range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DCOUNTA(database: any, field: any, criteria: any): number | Error;;
```

---

### `DDB`

Returns the depreciation of an asset for a specified period by using the double-declining balance method or some other method that you specify.

Category: Financial

**@param** {*} cost The initial cost of the asset.

**@param** {*} salvage The value at the end of the depreciation (sometimes called the salvage value of the asset). This value can be 0.

**@param** {*} life The number of periods over which the asset is being depreciated (sometimes called the useful life of the asset).

**@param** {*} period The period for which you want to calculate the depreciation. Period must use the same units as life.

**@param** {*} [factor] Optional. The rate at which the balance declines. If factor is omitted, it is assumed to be 2 (the double-declining balance method).

**@returns**

```ts
export function DDB(cost: any, salvage: any, life: any, period: any, factor?: any): number | Error;;
```

---

### `DEC2BIN`

Converts a decimal number to binary.

Category: Engineering

**@param** {*} number The decimal integer you want to convert. If number is negative, valid place values are ignored and DEC2BIN returns a 10-character (10-bit) binary number in which the most significant bit is the sign bit. The remaining 9 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@param** {*} [places] Optional. The number of characters to use. If places is omitted, DEC2BIN uses the minimum number of characters necessary. Places is useful for padding the return value with leading 0s (zeros).

**@returns**

```ts
export function DEC2BIN(number: any, places?: any): string | Error;;
```

---

### `DEC2HEX`

Converts a decimal number to hexadecimal.

Category: Engineering

**@param** {*} number The decimal integer you want to convert. If number is negative, places is ignored and DEC2HEX returns a 10-character (40-bit) hexadecimal number in which the most significant bit is the sign bit. The remaining 39 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@param** {*} [places] Optional. The number of characters to use. If places is omitted, DEC2HEX uses the minimum number of characters necessary. Places is useful for padding the return value with leading 0s (zeros).

**@returns**

```ts
export function DEC2HEX(number: any, places?: any): any;;
```

---

### `DEC2OCT`

Converts a decimal number to octal.

Category: Engineering

**@param** {*} number The decimal integer you want to convert. If number is negative, places is ignored and DEC2OCT returns a 10-character (30-bit) octal number in which the most significant bit is the sign bit. The remaining 29 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@param** {*} [places] Optional. The number of characters to use. If places is omitted, DEC2OCT uses the minimum number of characters necessary. Places is useful for padding the return value with leading 0s (zeros).

**@returns**

```ts
export function DEC2OCT(number: any, places?: any): any;;
```

---

### `DECIMAL`

Converts a text representation of a number in a given base into a decimal number.

Category: Math and trigonometry

**@param** {*} text

**@param** {*} radix Radix must be an integer.

**@returns**

```ts
export function DECIMAL(text: any, radix: any, ...args: any[]): any;;
```

---

### `DEGREES`

Converts radians to degrees.

Category: Math and trigonometry

**@param** {*} angle The angle in radians that you want to convert.

**@returns**

```ts
export function DEGREES(angle: any): number | Error;;
```

---

### `DELTA`

Tests whether two values are equal.

Category: Engineering

**@param** {*} number1 The first number.

**@param** {*} [number2] Optional. The second number. If omitted, number2 is assumed to be zero.

**@returns**

```ts
export function DELTA(number1: any, number2?: any): 0 | Error | 1;;
```

---

### `DEVSQ`

Returns the sum of squares of deviations.

Category: Statistical

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 arguments for which you want to calculate the sum of squared deviations. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function DEVSQ(...args: any[]): number | Error;;
```

---

### `DGET`

Extracts from a database a single record that matches the specified criteria.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria The range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DGET(database: any, field: any, criteria: any): any;;
```

---

### `DISC`

Returns the discount rate for a security.

Category: Financial

**@param** {*} settlement The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

**@param** {*} maturity The security's maturity date. The maturity date is the date when the security expires.

**@param** {*} pr The security's price per $100 face value.

**@param** {*} redemption The security's redemption value per $100 face value.

**@param** {*} [basis] Optional. The type of day count basis to use.

**@returns**

```ts
export function DISC(settlement: any, maturity: any, pr: any, redemption: any, basis?: any): number | Error;;
```

---

### `DMAX`

Returns the maximum value from selected database entries.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria The range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DMAX(database: any, field: any, criteria: any): any;;
```

---

### `DMIN`

Returns the minimum value from selected database entries.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria The range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DMIN(database: any, field: any, criteria: any): any;;
```

---

### `DOLLAR`

Converts a number to text, using the $ (dollar) currency format.

Category: Text

**@param** {*} number A number, a reference to a value containing a number, or a formula that evaluates to a number.

**@param** {*} [decimals] Optional. The number of digits to the right of the decimal point. If this is negative, the number is rounded to the left of the decimal point. If you omit decimals, it is assumed to be 2.

**@returns**

```ts
export function DOLLAR(number: any, decimals?: any): any;;
```

---

### `DOLLARDE`

Converts a dollar price, expressed as a fraction, into a dollar price, expressed as a decimal number.

Category: Financial

**@param** {*} fractional_dollar A number expressed as an integer part and a fraction part, separated by a decimal symbol.

**@param** {*} fraction The integer to use in the denominator of the fraction.

**@returns**

```ts
export function DOLLARDE(fractional_dollar: any, fraction: any): number | Error;;
```

---

### `DOLLARFR`

Converts a dollar price, expressed as a decimal number, into a dollar price, expressed as a fraction.

Category: Financial

**@param** {*} decimal_dollar A decimal number.

**@param** {*} fraction The integer to use in the denominator of a fraction.

**@returns**

```ts
export function DOLLARFR(decimal_dollar: any, fraction: any): number | Error;;
```

---

### `DPRODUCT`

Multiplies the values in a particular field of records that match the criteria in a database.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria The range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DPRODUCT(database: any, field: any, criteria: any): number | Error;;
```

---

### `DROP`

Excludes a specified number of rows or columns from the start or end of an array.

Category: Lookup and reference

**@param** {*} array The array from which to drop rows or columns.

**@param** {*} rows The number of rows to drop. A negative value drops from the end of the array. Optionnal when columns provided

**@param** {*} columns The number of columns to exclude. A negative value drops from the end of the array. Optionnal when rows provided

**@returns**

```ts
export function DROP(array: any, rows: any, columns: any): any;;
```

---

### `DSTDEV`

Estimates the standard deviation based on a sample of selected database entries.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria The range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DSTDEV(database: any, field: any, criteria: any): number | Error;;
```

---

### `DSTDEVP`

Calculates the standard deviation based on the entire population of selected database entries.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria The range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DSTDEVP(database: any, field: any, criteria: any): number | Error;;
```

---

### `DSUM`

Adds the numbers in the field column of records in the database that match the criteria.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria Is the range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DSUM(database: any, field: any, criteria: any): number | Error;;
```

---

### `DVAR`

Estimates variance based on a sample from selected database entries.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria The range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DVAR(database: any, field: any, criteria: any): number | Error;;
```

---

### `DVARP`

Calculates variance based on the entire population of selected database entries.

Category: Database

**@param** {*} database The range of values that makes up the list or database. A database is a list of related data in which rows of related information are records, and columns of data are fields. The first row of the list contains labels for each column.

**@param** {*} field Indicates which column is used in the function. Enter the column label enclosed between double quotation marks, such as "Age" or "Yield," or a number (without quotation marks) that represents the position of the column within the list: 1 for the first column, 2 for the second column, and so on.

**@param** {*} criteria The range of values that contains the conditions that you specify. You can use any range for the criteria argument, as long as it includes at least one column label and at least one value below the column label in which you specify a condition for the column.

**@returns**

```ts
export function DVARP(database: any, field: any, criteria: any): number | Error;;
```

---

### `EDATE`

Returns the serial number of the date that is the indicated number of months before or after the start date.

Category: Date and time

**@param** {*} start_date A date that represents the start date.

**@param** {*} months The number of months before or after start_date. A positive value for months yields a future date; a negative value yields a past date.

**@returns**

```ts
export function EDATE(start_date: any, months: any): any;;
```

---

### `EFFECT`

Returns the effective annual interest rate.

Category: Financial

**@param** {*} nominal_rate The nominal interest rate.

**@param** {*} npery The number of compounding periods per year.

**@returns**

```ts
export function EFFECT(nominal_rate: any, npery: any): number | Error;;
```

---

### `EOMONTH`

Returns the serial number of the last day of the month before or after a specified number of months.

Category: Date and time

**@param** {*} start_date A date that represents the starting date.

**@param** {*} months The number of months before or after start_date. A positive value for months yields a future date; a negative value yields a past date.

**@returns**

```ts
export function EOMONTH(start_date: any, months: any): number | Date | Error;;
```

---

### `ERF`

Returns the error function.

Category: Engineering

**@param** {*} lower_limit The lower bound for integrating ERF.

**@param** {*} [upper_limit] Optional. The upper bound for integrating ERF. If omitted, ERF integrates between zero and lower_limit.

**@returns**

```ts
export function ERF(lower_limit: any, upper_limit?: any): any;;
```

---

### `ERFC`

Returns the complementary error function.

Category: Engineering

**@param** {*} x The lower bound for integrating ERFC.

**@returns**

```ts
export function ERFC(x: any): any;;
```

---

### `EVEN`

Rounds a number up to the nearest even integer.

Category: Math and trigonometry

**@param** {*} number The value to round.

**@returns**

```ts
export function EVEN(number: any): any;;
```

---

### `EXACT`

Checks to see if two text values are identical.

Category: Text

**@param** {*} text1 The first text string.

**@param** {*} text2 The second text string.

**@returns**

```ts
export function EXACT(text1: any, text2: any, ...args: any[]): any;;
```

---

### `EXP`

Returns e raised to the power of a given number.

Category: Math and trigonometry

**@param** {*} number The exponent applied to the base e.

**@returns**

```ts
export function EXP(number: any, ...args: any[]): any;;
```

---

### `EXPAND`

Expands or pads an array to specified row and column dimensions.

Category: Lookup and reference

**@param** {*} array The array to expand.

**@param** {*} rows The number of rows in the expanded array. If missing, rows will not be expanded.

**@param** {*} columns The number of columns in the expanded array. If missing, columns will not be expanded.

**@param** {*} pad_with The value with which to pad. If missing, #N/A will be used.

```ts
export function EXPAND(array: any, rows: any, columns: any, pad_with: any): Error | undefined[][];;
```

---

### `EXPONDIST`

Returns the exponential distribution.

Category: Statistical

**@param** {*} x The value of the function.

**@param** {*} lambda The parameter value.

**@param** {*} cumulative A logical value that indicates which form of the exponential function to provide. If cumulative is TRUE, EXPON.DIST returns the cumulative distribution function; if FALSE, it returns the probability density function.

**@returns**

```ts
export function EXPONDIST(x: any, lambda: any, cumulative: any): any;;
```

---

### `FACT`

Returns the factorial of a number.

Category: Math and trigonometry

**@param** {*} number The nonnegative number for which you want the factorial. If number is not an integer, it is truncated.

**@returns**

```ts
export function FACT(number: any): any;;
```

---

### `FACTDOUBLE`

Returns the double factorial of a number.

Category: Math and trigonometry

**@param** {*} number The value for which to return the double factorial. If number is not an integer, it is truncated.

**@returns**

```ts
export function FACTDOUBLE(number: any): any;;
```

---

### `FALSE`

Returns the logical value FALSE.

Category: Logical

**@returns**

```ts
export function FALSE(): boolean;;
```

---

### `FDIST`

Returns the F probability distribution.

Category: Statistical

**@param** {*} x The value at which to evaluate the function.

**@param** {*} deg_freedom1 The numerator degrees of freedom.

**@param** {*} deg_freedom2 The denominator degrees of freedom.

**@param** {*} cumulative A logical value that determines the form of the function. If cumulative is TRUE, F.DIST returns the cumulative distribution function; if FALSE, it returns the probability density function.

**@returns**

```ts
export function FDIST(x: any, deg_freedom1: any, deg_freedom2: any, cumulative: any): any;;
```

---

### `FDISTRT`

Returns the F probability distribution.

Category: Statistical

**@param** {*} x The value at which to evaluate the function.

**@param** {*} deg_freedom1 The numerator degrees of freedom.

**@param** {*} deg_freedom2 The denominator degrees of freedom.

**@returns**

```ts
export function FDISTRT(x: any, deg_freedom1: any, deg_freedom2: any, ...args: any[]): number | Error;;
```

---

### `FIND`

Locate one text string within a second text string, and return the number of the starting position of the first text string from the first character of the second text string.

Category: Text

**@param** {*} find_text The text you want to find.

**@param** {*} within_text The text containing the text you want to find.

**@param** {*} [start_num] Optional. Specifies the character at which to start the search. The first character in within_text is character number 1. If you omit start_num, it is assumed to be 1.

**@returns**

```ts
export function FIND(find_text: any, within_text: any, start_num?: any, ...args: any[]): any;;
```

---

### `FINV`

Returns the inverse of the F probability distribution.

Category: Statistical

**@param** {*} probability A probability associated with the F cumulative distribution.

**@param** {*} deg_freedom1 The numerator degrees of freedom.

**@param** {*} deg_freedom2 The denominator degrees of freedom.

**@returns**

```ts
export function FINV(probability: any, deg_freedom1: any, deg_freedom2: any): any;;
```

---

### `FINVRT`

Returns the inverse of the F probability distribution.

Category: Statistical

**@param** {*} probability A probability associated with the F cumulative distribution.

**@param** {*} deg_freedom1 The numerator degrees of freedom.

**@param** {*} deg_freedom2 The denominator degrees of freedom.

**@returns**

```ts
export function FINVRT(probability: any, deg_freedom1: any, deg_freedom2: any, ...args: any[]): any;;
```

---

### `FISHER`

Returns the Fisher transformation.

Category: Statistical

**@param** {*} x A numeric value for which you want the transformation.

**@returns**

```ts
export function FISHER(x: any): number | Error;;
```

---

### `FISHERINV`

Returns the inverse of the Fisher transformation.

Category: Statistical

**@param** {*} y The value for which you want to perform the inverse of the transformation.

**@returns**

```ts
export function FISHERINV(y: any): number | Error;;
```

---

### `FIXED`

Formats a number as text with a fixed number of decimals.

Category: Text

**@param** {*} number The number you want to round and convert to text.

**@param** {*} [decimals] Optional. The number of digits to the right of the decimal point.

**@param** {*} [no_commas] Optional. A logical value that, if TRUE, prevents FIXED from including commas in the returned text.

**@returns**

```ts
export function FIXED(number: any, decimals?: any, no_commas?: any): any;;
```

---

### `FLOOR`

Rounds a number down, toward zero.

Category: Math and trigonometry

**@param** {*} number The numeric value you want to round.

**@param** {*} significance The multiple to which you want to round.

**@returns**

```ts
export function FLOOR(number: any, significance: any): any;;
```

---

### `FLOORMATH`

Rounds a number down, to the nearest integer or to the nearest multiple of significance.

Category: Math and trigonometry

**@param** {*} number The number to be rounded down.

**@param** {*} [significance] Optional. The multiple to which you want to round.

**@param** {*} [mode] Optional. The direction (toward or away from 0) to round negative numbers.

**@returns**

```ts
export function FLOORMATH(number: any, significance?: any, mode?: any): any;;
```

---

### `FLOORPRECISE`

Rounds a number the nearest integer or to the nearest multiple of significance. Regardless of the sign of the number, the number is rounded up.

Category: Math and trigonometry

**@param** {*} number The value to be rounded.

**@param** {*} [significance] Optional. The multiple to which number is to be rounded. If significance is omitted, its default value is 1.

**@returns**

```ts
export function FLOORPRECISE(number: any, significance?: any): any;;
```

---

### `FORECAST`

Returns a value along a linear trend.

Category: Statistical

**@param** {*} x The data point for which you want to predict a value.

**@param** {*} known_ys The dependent array or range of data.

**@param** {*} known_xs The independent array or range of data.

**@returns**

```ts
export function FORECAST(x: any, known_ys: any, known_xs: any): number | Error;;
```

---

### `FREQUENCY`

Returns a frequency distribution as a vertical array.

Category: Statistical

**@param** {*} data_array An array of or reference to a set of values for which you want to count frequencies. If data_array contains no values, FREQUENCY returns an array of zeros.

**@param** {*} bins_array An array of or reference to intervals into which you want to group the values in data_array. If bins_array contains no values, FREQUENCY returns the number of elements in data_array.

**@returns**

```ts
export function FREQUENCY(data_array: any, bins_array: any): number[] | Error;;
```

---

### `FTEST`

Returns the result of an F-test.

Category: Statistical

**@param** {*} array1 The first array or range of data.

**@param** {*} array2 The second array or range of data.

**@returns**

```ts
export function FTEST(array1: any, array2: any): number | Error;;
```

---

### `FV`

Returns the future value of an investment.

Category: Financial

**@param** {*} rate The interest rate per period.

**@param** {*} nper The total number of payment periods in an annuity.

**@param** {*} pmt The payment made each period; it cannot change over the life of the annuity. Typically, pmt contains principal and interest but no other fees or taxes. If pmt is omitted, you must include the pv argument.

**@param** {*} [pv] Optional. The present value, or the lump-sum amount that a series of future payments is worth right now. If pv is omitted, it is assumed to be 0 (zero), and you must include the pmt argument.

**@param** {*} [type] Optional. The number 0 or 1 and indicates when payments are due. If type is omitted, it is assumed to be 0.

**@returns**

```ts
export function FV(rate: any, nper: any, payment: any, value$1: any, type?: any): number | Error;;
```

---

### `FVSCHEDULE`

Returns the future value of an initial principal after applying a series of compound interest rates.

Category: Financial

**@param** {*} principal The present value.

**@param** {*} schedule An array of interest rates to apply.

**@returns**

```ts
export function FVSCHEDULE(principal: any, schedule: any): any;;
```

---

### `GAMMA`

Returns the Gamma function value.

Category: Statistical

**@param** {*} number Returns a number.

**@returns**

```ts
export function GAMMA(number: any): any;;
```

---

### `GAMMADIST`

Returns the gamma distribution.

Category: Statistical

**@param** {*} x The value at which you want to evaluate the distribution.

**@param** {*} alpha A parameter to the distribution.

**@param** {*} beta A parameter to the distribution. If beta = 1, GAMMA.DIST returns the standard gamma distribution.

**@param** {*} cumulative A logical value that determines the form of the function. If cumulative is TRUE, GAMMA.DIST returns the cumulative distribution function; if FALSE, it returns the probability density function.

**@returns**

```ts
export function GAMMADIST(value$1: any, alpha: any, beta: any, cumulative: any, ...args: any[]): any;;
```

---

### `GAMMAINV`

Returns the inverse of the gamma cumulative distribution.

Category: Statistical

**@param** {*} probability The probability associated with the gamma distribution.

**@param** {*} alpha A parameter to the distribution.

**@param** {*} beta A parameter to the distribution. If beta = 1, GAMMA.INV returns the standard gamma distribution.

**@returns**

```ts
export function GAMMAINV(probability: any, alpha: any, beta: any, ...args: any[]): any;;
```

---

### `GAMMALN`

Returns the natural logarithm of the gamma function, Γ(x).

Category: Statistical

**@param** {*} x The value for which you want to calculate GAMMALN.

**@returns**

```ts
export function GAMMALN(x: any): any;;
```

---

### `GAMMALNPRECISE`

Returns the natural logarithm of the gamma function, Γ(x).

Category: Statistical

**@param** {*} x The value for which you want to calculate GAMMALN.PRECISE.

**@returns**

```ts
export function GAMMALNPRECISE(x: any, ...args: any[]): any;;
```

---

### `GAUSS`

Returns 0.5 less than the standard normal cumulative distribution.

Category: Statistical

**@param** {*} z Returns a number.

**@returns**

```ts
export function GAUSS(z: any): number | Error;;
```

---

### `GCD`

Returns the greatest common divisor.

Category: Math and trigonometry

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 values. If any value is not an integer, it is truncated.

**@returns**

```ts
export function GCD(...args: any[]): any;;
```

---

### `GEOMEAN`

Returns the geometric mean.

Category: Statistical

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 arguments for which you want to calculate the mean. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function GEOMEAN(...args: any[]): any;;
```

---

### `GESTEP`

Tests whether a number is greater than a threshold value.

Category: Engineering

**@param** {*} number The value to test against step.

**@param** {*} [step] Optional. The threshold value. If you omit a value for step, GESTEP uses zero.

**@returns**

```ts
export function GESTEP(number: any, step?: any): any;;
```

---

### `GROWTH`

Returns values along an exponential trend.

Category: Statistical

**@param** {*} known_y The set of y-values you already know in the relationship y = b*m^x.
 - If the array known_y's is in a single column, then each column of known_x's is interpreted as a separate variable.
 - If the array known_y's is in a single row, then each row of known_x's is interpreted as a separate variable.
 - If any of the numbers in known_y's is 0 or negative, GROWTH returns the #NUM! error value.

**@param** {*} [known_x] Optional. An optional set of x-values that you may already know in the relationship y = b*m^x.
 - The array known_x's can include one or more sets of variables. If only one variable is used, known_y's and known_x's can be ranges of any shape, as long as they have equal dimensions. If more than one variable is used, known_y's must be a vector (that is, a range with a height of one row or a width of one column).
 - If known_x's is omitted, it is assumed to be the array {1,2,3,...} that is the same size as known_y's.

**@param** {*} [new_x] Optional. Are new x-values for which you want GROWTH to return corresponding y-values.
 - new_x's must include a column (or row) for each independent variable, just as known_x's does. So, if known_y's is in a single column, known_x's and new_x's must have the same number of columns. If known_y's is in a single row, known_x's and new_x's must have the same number of rows.
 - If new_x's is omitted, it is assumed to be the same as known_x's.
 - If both known_x's and new_x's are omitted, they are assumed to be the array {1,2,3,...} that is the same size as known_y's.

**@param** {*} [use_const] Optional. A logical value specifying whether to force the constant b to equal 1. If const is TRUE or omitted, b is calculated normally. If const is FALSE, b is set equal to 1 and the m-values are adjusted so that y = m^x.
 - If const is TRUE or omitted, b is calculated normally.
 - If const is FALSE, b is set equal to 1 and the m-values are adjusted so that y = m^x.

**@returns**

```ts
export function GROWTH(known_y: any, known_x?: any, new_x?: any, use_const?: any): number[] | Error;;
```

---

### `HARMEAN`

Returns the harmonic mean.

Category: Statistical

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 arguments for which you want to calculate the mean. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function HARMEAN(...args: any[]): number | Error;;
```

---

### `HEX2BIN`

Converts a hexadecimal number to binary.

Category: Engineering

**@param** {*} number The hexadecimal number you want to convert. Number cannot contain more than 10 characters. The most significant bit of number is the sign bit (40th bit from the right). The remaining 9 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@param** {*} [places] Optional. The number of characters to use. If places is omitted, HEX2BIN uses the minimum number of characters necessary. Places is useful for padding the return value with leading 0s (zeros).

**@returns**

```ts
export function HEX2BIN(number: any, places?: any): string | Error;;
```

---

### `HEX2DEC`

Converts a hexadecimal number to decimal.

Category: Engineering

**@param** {*} number The hexadecimal number you want to convert. Number cannot contain more than 10 characters (40 bits). The most significant bit of number is the sign bit. The remaining 39 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@returns**

```ts
export function HEX2DEC(number: any): number | Error;;
```

---

### `HEX2OCT`

Converts a hexadecimal number to octal.

Category: Engineering

**@param** {*} number The hexadecimal number you want to convert. Number cannot contain more than 10 characters. The most significant bit of number is the sign bit. The remaining 39 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@param** {*} [places] Optional. The number of characters to use. If places is omitted, HEX2OCT uses the minimum number of characters necessary. Places is useful for padding the return value with leading 0s (zeros).

**@returns**

```ts
export function HEX2OCT(number: any, places?: any): string | Error;;
```

---

### `HLOOKUP`

Looks in the top row of an array and returns the value of the indicated value.

Category: Lookup and reference

**@param** {*} lookup_value The value to be found in the first row of the table. Lookup_value can be a value, a reference, or a text string.

**@param** {*} table_array A table of information in which data is looked up. Use a reference to a range or a range name.

**@param** {*} row_index_num The row number in table_array from which the matching value will be returned. A row_index_num of 1 returns the first row value in table_array, a row_index_num of 2 returns the second row value in table_array, and so on. If row_index_num is less than 1, HLOOKUP returns the #VALUE! error value; if row_index_num is greater than the number of rows on table_array, HLOOKUP returns the #REF! error value.

**@param** {*} [range_lookup] Optional. A logical value that specifies whether you want HLOOKUP to find an exact match or an approximate match. If TRUE or omitted, an approximate match is returned. In other words, if an exact match is not found, the next largest value that is less than lookup_value is returned. If FALSE, HLOOKUP will find an exact match. If one is not found, the error value #N/A is returned.

**@returns**

```ts
export function HLOOKUP(lookup_value: any, table_array: any, row_index_num: any, range_lookup?: any): Error;;
```

---

### `HOUR`

Converts a serial number to an hour.

Category: Date and time

**@param** {*} serial_number The time that contains the hour you want to find. Times may be entered as text strings within quotation marks (for example, "6:45 PM"), as decimal numbers (for example, 0.78125, which represents 6:45 PM), or as results of other formulas or functions (for example, TIMEVALUE("6:45 PM")).

**@returns**

```ts
export function HOUR(serial_number: any): any;;
```

---

### `HSTACK`

Appends arrays horizontally and in sequence to return a larger array.

Category: Lookup and reference

**@param** {*} array

**@param** {...*} otherArrays

**@returns**

```ts
export function HSTACK(array: any, ...otherArrays: any[]): any[][];;
```

---

### `HYPGEOMDIST`

Returns the hypergeometric distribution.

Category: Statistical

**@param** {*} sample_s The number of successes in the sample.

**@param** {*} number_sample The size of the sample.

**@param** {*} population_s The number of successes in the population.

**@param** {*} number_pop The population size.

**@param** {*} cumulative A logical value that determines the form of the function. If cumulative is TRUE, then HYPGEOM.DIST returns the cumulative distribution function; if FALSE, it returns the probability mass function.

**@returns**

```ts
export function HYPGEOMDIST(sample_s: any, number_sample: any, population_s: any, number_pop: any, cumulative: any): number | Error;;
```

---

### `IF`

Specifies a logical test to perform.

Category: Logical

**@param** {*} logical_test

**@param** {*} value_if_true

**@param** {*} value_if_false

**@returns**

```ts
export function IF(logical_test: any, value_if_true: any, value_if_false: any, ...args: any[]): any;;
```

---

### `IFERROR`

Returns a value you specify if a formula evaluates to an error; otherwise, returns the result of the formula.

Category: Logical

**@param** {*} value The argument that is checked for an error.

**@param** {*} value_if_error The value to return if the formula evaluates to an error. The following error types are evaluated: #N/A, #VALUE!, #REF!, #DIV/0!, #NUM!, #NAME?, or #NULL!.

**@returns**

```ts
export function IFERROR(value: any, value_if_error: any): any;;
```

---

### `IFNA`

Returns the value you specify if the expression resolves to #N/A, otherwise returns the result of the expression.

Category: Logical

**@returns**

```ts
export function IFNA(value: any, value_if_na: any): any;;
```

---

### `IFS`

Checks whether one or more conditions are met and returns a value that corresponds to the first TRUE condition.

Category: Logical

**@returns**

```ts
export function IFS(...args: any[]): any;;
```

---

### `IMABS`

Returns the absolute value (modulus) of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the absolute value.

**@returns**

```ts
export function IMABS(inumber: any): number | Error;;
```

---

### `IMAGINARY`

Returns the imaginary coefficient of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the imaginary coefficient.

**@returns**

```ts
export function IMAGINARY(inumber: any): any;;
```

---

### `IMARGUMENT`

Returns the argument theta, an angle expressed in radians.

Category: Engineering

**@param** {*} inumber A complex number for which you want the argument .

**@returns**

```ts
export function IMARGUMENT(inumber: any): number | Error;;
```

---

### `IMCONJUGATE`

Returns the complex conjugate of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the conjugate.

**@returns**

```ts
export function IMCONJUGATE(inumber: any): any;;
```

---

### `IMCOS`

Returns the cosine of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the cosine.

**@returns**

```ts
export function IMCOS(inumber: any): any;;
```

---

### `IMCOSH`

Returns the hyperbolic cosine of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the hyperbolic cosine.

**@returns**

```ts
export function IMCOSH(inumber: any): any;;
```

---

### `IMCOT`

Returns the cotangent of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the cotangent.

**@returns**

```ts
export function IMCOT(inumber: any): any;;
```

---

### `IMCSC`

Returns the cosecant of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the cosecant.

**@returns**

```ts
export function IMCSC(inumber: any): any;;
```

---

### `IMCSCH`

Returns the hyperbolic cosecant of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the hyperbolic cosecant.

**@returns**

```ts
export function IMCSCH(inumber: any): any;;
```

---

### `IMDIV`

Returns the quotient of two complex numbers.

Category: Engineering

**@param** {*} inumber1 The complex numerator or dividend.

**@param** {*} inumber2 The complex denominator or divisor.

**@returns**

```ts
export function IMDIV(inumber1: any, inumber2: any): any;;
```

---

### `IMEXP`

Returns the exponential of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the exponential.

**@returns**

```ts
export function IMEXP(inumber: any): any;;
```

---

### `IMLN`

Returns the natural logarithm of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the natural logarithm.

**@returns**

```ts
export function IMLN(inumber: any): any;;
```

---

### `IMLOG10`

Returns the base-10 logarithm of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the common logarithm.

**@returns**

```ts
export function IMLOG10(inumber: any): any;;
```

---

### `IMLOG2`

Returns the base-2 logarithm of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the base-2 logarithm.

**@returns**

```ts
export function IMLOG2(inumber: any): any;;
```

---

### `IMPOWER`

Returns a complex number raised to an integer power.

Category: Engineering

**@param** {*} inumber A complex number you want to raise to a power.

**@param** {*} number The power to which you want to raise the complex number.

**@returns**

```ts
export function IMPOWER(inumber: any, number: any): any;;
```

---

### `IMPRODUCT`

Returns the product of complex numbers.

Category: Engineering

**@param** {*} args inumber1, [inumber2], … Inumber1 is required, subsequent inumbers are not. 1 to 255 complex numbers to multiply.

**@returns**

```ts
export function IMPRODUCT(...args: any[]): any;;
```

---

### `IMREAL`

Returns the real coefficient of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the real coefficient.

**@returns**

```ts
export function IMREAL(inumber: any): any;;
```

---

### `IMSEC`

Returns the secant of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the secant.

**@returns**

```ts
export function IMSEC(inumber: any): any;;
```

---

### `IMSECH`

Returns the hyperbolic secant of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the hyperbolic secant.

**@returns**

```ts
export function IMSECH(inumber: any): any;;
```

---

### `IMSIN`

Returns the sine of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the sine.

**@returns**

```ts
export function IMSIN(inumber: any): any;;
```

---

### `IMSINH`

Returns the hyperbolic sine of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the hyperbolic sine.

**@returns**

```ts
export function IMSINH(inumber: any): any;;
```

---

### `IMSQRT`

Returns the square root of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the square root.

**@returns**

```ts
export function IMSQRT(inumber: any): any;;
```

---

### `IMSUB`

Returns the difference between two complex numbers.

Category: Engineering

**@param** {*} inumber1 The complex number from which to subtract inumber2.

**@param** {*} inumber2 The complex number to subtract from inumber1.

**@returns**

```ts
export function IMSUB(inumber1: any, inumber2: any): any;;
```

---

### `IMSUM`

Returns the sum of complex numbers.

Category: Engineering

**@param** {*} args inumber1, [inumber2], ... Inumber1 is required, subsequent numbers are not. 1 to 255 complex numbers to add.

**@returns**

```ts
export function IMSUM(...args: any[]): any;;
```

---

### `IMTAN`

Returns the tangent of a complex number.

Category: Engineering

**@param** {*} inumber A complex number for which you want the tangent.

**@returns**

```ts
export function IMTAN(inumber: any): any;;
```

---

### `INDEX`

Uses an index to choose a value from a reference or array.

Category: Lookup and reference

**@param** {*} array A range of values or an array constant.
 - If array contains only one row or column, the corresponding row_num or column_num argument is optional.
 - If array has more than one row and more than one column, and only row_num or column_num is used, INDEX returns an array of the entire row or column in array.

**@param** {*} row_num Required, unless column_num is present. Selects the row in array from which to return a value. If row_num is omitted, column_num is required.

**@param** {*} [column_num] Optional. Selects the column in array from which to return a value. If column_num is omitted, row_num is required.

**@returns**

```ts
export function INDEX(array: any, row_num: any, column_num?: any): any;;
```

---

### `INT`

Rounds a number down to the nearest integer.

Category: Math and trigonometry

**@param** {*} number The real number you want to round down to an integer.

**@returns**

```ts
export function INT(number: any): number | Error;;
```

---

### `INTERCEPT`

Returns the intercept of the linear regression line.

Category: Statistical

**@param** {*} known_y The dependent set of observations or data.

**@param** {*} known_x The independent set of observations or data.

**@returns**

```ts
export function INTERCEPT(known_y: any, known_x: any): number | Error;;
```

---

### `IPMT`

Returns the interest payment for an investment for a given period.

Category: Financial

**@param** {*} rate The interest rate per period.

**@param** {*} per The period for which you want to find the interest and must be in the range 1 to nper.

**@param** {*} nper The total number of payment periods in an annuity.

**@param** {*} pv The present value, or the lump-sum amount that a series of future payments is worth right now.

**@param** {*} [fv] Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (the future value of a loan, for example, is 0).

**@param** {*} [type] Optional. The number 0 or 1 and indicates when payments are due. If type is omitted, it is assumed to be 0.

**@returns**

```ts
export function IPMT(rate: any, per: any, nper: any, pv: any, fv?: any, type?: any): number | Error;;
```

---

### `IRR`

Returns the internal rate of return for a series of cash flows.

Category: Financial

**@param** {*} values An array or a reference to values that contain numbers for which you want to calculate the internal rate of return.
 - Values must contain at least one positive value and one negative value to calculate the internal rate of return.
 - IRR uses the order of values to interpret the order of cash flows. Be sure to enter your payment and income values in the sequence you want.
 - If an array or reference argument contains text, logical values, or empty values, those values are ignored.

**@param** {*} [guess] Optional. A number that you guess is close to the result of IRR.
 - Microsoft Excel uses an iterative technique for calculating IRR. Starting with guess, IRR cycles through the calculation until the result is accurate within 0.00001 percent. If IRR can't find a result that works after 20 tries, the #NUM! error value is returned.
 - In most cases you do not need to provide guess for the IRR calculation. If guess is omitted, it is assumed to be 0.1 (10 percent).
 - If IRR gives the #NUM! error value, or if the result is not close to what you expected, try again with a different value for guess.

**@returns**

```ts
export function IRR(values: any, guess?: any): any;;
```

---

### `ISBLANK`

Returns TRUE if the value is blank.

Category: Information

**@param** {*} value The value that you want tested. The value argument can be a blank (empty value), error, logical value, text, number, or reference value, or a name referring to any of these.

**@returns**

```ts
export function ISBLANK(value: any): boolean;;
```

---

### `ISERR`

Returns TRUE if the value is any error value except #N/A.

Category: Information

**@param** {*} value The value that you want tested. The value argument can be a blank (empty value), error, logical value, text, number, or reference value, or a name referring to any of these.

**@returns**

```ts
export function ISERR(value$1: any): boolean;;
```

---

### `ISERROR`

Returns TRUE if the value is any error value.

Category: Information

**@param** {*} value The value that you want tested. The value argument can be a blank (empty value), error, logical value, text, number, or reference value, or a name referring to any of these.

**@returns**

```ts
export function ISERROR(value: any): boolean;;
```

---

### `ISEVEN`

Returns TRUE if the number is even.

Category: Information

**@param** {*} number The value to test. If number is not an integer, it is truncated.

**@returns**

```ts
export function ISEVEN(number: any): boolean;;
```

---

### `ISLOGICAL`

Returns TRUE if the value is a logical value.

Category: Information

**@param** {*} value The value that you want tested. The value argument can be a blank (empty value), error, logical value, text, number, or reference value, or a name referring to any of these.

**@returns**

```ts
export function ISLOGICAL(value: any): boolean;;
```

---

### `ISNA`

Returns TRUE if the value is the #N/A error value.

Category: Information

**@param** {*} value The value that you want tested. The value argument can be a blank (empty value), error, logical value, text, number, or reference value, or a name referring to any of these.

**@returns**

```ts
export function ISNA(value: any): boolean;;
```

---

### `ISNONTEXT`

Returns TRUE if the value is not text.

Category: Information

**@param** {*} value The value that you want tested. The value argument can be a blank (empty value), error, logical value, text, number, or reference value, or a name referring to any of these.

**@returns**

```ts
export function ISNONTEXT(value: any): boolean;;
```

---

### `ISNUMBER`

Returns TRUE if the value is a number.

Category: Information

**@param** {*} value The value that you want tested. The value argument can be a blank (empty value), error, logical value, text, number, or reference value, or a name referring to any of these.

**@returns**

```ts
export function ISNUMBER(value: any): boolean;;
```

---

### `ISODD`

Returns TRUE if the number is odd.

Category: Information

**@param** {*} value The value that you want tested. The value argument can be a blank (empty value), error, logical value, text, number, or reference value, or a name referring to any of these.

**@returns**

```ts
export function ISODD(value: any): boolean;;
```

---

### `ISOWEEKNUM`

Returns the number of the ISO week number of the year for a given date.

Category: Date and time

**@param** {*} date Date is the date-time code used by Excel for date and time calculation.

**@returns**

```ts
export function ISOWEEKNUM(date: any): number | Error;;
```

---

### `ISPMT`

Calculates the interest paid during a specific period of an investment.

Category: Financial

**@param** {*} rate The interest rate for the investment.

**@param** {*} per The period for which you want to find the interest, and must be between 1 and Nper.

**@param** {*} nper The total number of payment periods for the investment.

**@param** {*} pv The present value of the investment. For a loan, Pv is the loan amount.

**@returns**

```ts
export function ISPMT(rate: any, per: any, nper: any, pv: any): number | Error;;
```

---

### `ISTEXT`

Returns TRUE if the value is text.

Category: Information

**@param** {*} value The value that you want tested. The value argument can be a blank (empty value), error, logical value, text, number, or reference value, or a name referring to any of these.

**@returns**

```ts
export function ISTEXT(value: any): value is string;;
```

---

### `KURT`

Returns the kurtosis of a data set.

Category: Statistical

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 arguments for which you want to calculate kurtosis. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function KURT(...args: any[]): number | Error;;
```

---

### `LARGE`

Returns the k-th largest value in a data set.

Category: Statistical

**@param** {*} array The array or range of data for which you want to determine the k-th largest value.

**@param** {*} k The position (from the largest) in the array or value range of data to return.

**@returns**

```ts
export function LARGE(array: any, k: any): any;;
```

---

### `LCM`

Returns the least common multiple.

Category: Math and trigonometry

**@param** {*} args number1, number2,... Number1 is required, subsequent numbers are optional. 1 to 255 values for which you want the least common multiple. If value is not an integer, it is truncated.

**@returns**

```ts
export function LCM(...args: any[]): number | Error;;
```

---

### `LEFT`

Returns the leftmost characters from a text value.

Category: Text

**@param** {*} text The text string that contains the characters you want to extract.

**@param** {*} [num_chars] Optional. Specifies the number of characters you want LEFT to extract.

**@returns**

```ts
export function LEFT(text: any, num_chars?: any): any;;
```

---

### `LEN`

Returns the number of characters in a text string

Category: Text

**@param** {*} text The text whose length you want to find. Spaces count as characters.

**@returns**

```ts
export function LEN(text: any, ...args: any[]): any;;
```

---

### `LINEST`

Returns the parameters of a linear trend.

Category: Statistical

**@param** {*} known_y The set of y-values that you already know in the relationship y = mx + b.
 - If the range of known_y's is in a single column, each column of known_x's is interpreted as a separate variable.
 - If the range of known_y's is contained in a single row, each row of known_x's is interpreted as a separate variable.

**@param** {*} [known_x] Optional. A set of x-values that you may already know in the relationship y = mx + b.
 - The range of known_x's can include one or more sets of variables. If only one variable is used, known_y's and known_x's can be ranges of any shape, as long as they have equal dimensions. If more than one variable is used, known_y's must be a vector (that is, a range with a height of one row or a width of one column).
 - If known_x's is omitted, it is assumed to be the array {1,2,3,...} that is the same size as known_y's.

**@returns**

```ts
export function LINEST(known_y: any, known_x?: any): number[] | Error;;
```

---

### `LN`

Returns the natural logarithm of a number.

Category: Math and trigonometry

**@param** {*} number The positive real number for which you want the natural logarithm.

**@returns**

```ts
export function LN(number: any): number | Error;;
```

---

### `LOG`

Returns the logarithm of a number to a specified base.

Category: Math and trigonometry

**@param** {*} number The positive real number for which you want the logarithm.

**@param** {*} [base] Optional. The base of the logarithm. If base is omitted, it is assumed to be 10.

**@returns**

```ts
export function LOG(number: any, base?: any): any;;
```

---

### `LOG10`

Returns the base-10 logarithm of a number.

Category: Math and trigonometry

**@param** {*} number The positive real number for which you want the base-10 logarithm.

**@returns**

```ts
export function LOG10(number: any): number | Error;;
```

---

### `LOGEST`

Returns the parameters of an exponential trend.

Category: Statistical

**@param** {*} known_y The set of y-values you already know in the relationship y = b*m^x.
 - If the array known_y's is in a single column, then each column of known_x's is interpreted as a separate variable.
 - If the array known_y's is in a single row, then each row of known_x's is interpreted as a separate variable.

**@param** {*} [known_x] Optional. An optional set of x-values that you may already know in the relationship y = b*m^x.
 - The array known_x's can include one or more sets of variables. If only one variable is used, known_y's and known_x's can be ranges of any shape, as long as they have equal dimensions. If more than one variable is used, known_y's must be a range of values with a height of one row or a width of one column (which is also known as a vector).
 - If known_x's is omitted, it is assumed to be the array {1,2,3,...} that is the same size as known_y's.

**@returns**

```ts
export function LOGEST(known_y: any, known_x?: any): number[] | Error;;
```

---

### `LOGINV`

Returns the inverse of the lognormal cumulative distribution.

Category: Statistical

**@param** {*} probability A probability associated with the lognormal distribution.

**@param** {*} mean The mean of ln(x).

**@param** {*} standard_dev The standard deviation of ln(x).

**@returns**

```ts
export function LOGINV(probability: any, mean: any, standard_dev: any): any;;
```

---

### `LOGNORMDIST`

Returns the cumulative lognormal distribution.

Category: Statistical

**@param** {*} x The value at which to evaluate the function.

**@param** {*} mean The mean of ln(x).

**@param** {*} standard_dev The standard deviation of ln(x).

**@param** {*} cumulative A logical value that determines the form of the function. If cumulative is TRUE, LOGNORM.DIST returns the cumulative distribution function; if FALSE, it returns the probability density function.

**@returns**

```ts
export function LOGNORMDIST(x: any, mean: any, standard_dev: any, cumulative: any): any;;
```

---

### `LOGNORMINV`

Returns the inverse of the lognormal cumulative distribution.

Category: Statistical

**@param** {*} probability A probability associated with the lognormal distribution.

**@param** {*} mean The mean of ln(x).

**@param** {*} standard_dev The standard deviation of ln(x).

**@returns**

```ts
export function LOGNORMINV(probability: any, mean: any, standard_dev: any): any;;
```

---

### `LOOKUP`

Looks up values in a vector or array.

Category: Lookup and reference

**@param** {*} lookup_value A value that LOOKUP searches for in an array. The lookup_value argument can be a number, text, a logical value, or a name or reference that refers to a value.
 - If LOOKUP can't find the value of lookup_value, it uses the largest value in the array that is less than or equal to lookup_value.
 - If the value of lookup_value is smaller than the smallest value in the first row or column (depending on the array dimensions), LOOKUP returns the #N/A error value.

**@param** {*} array A range of values that contains text, numbers, or logical values that you want to compare with lookup_value. The array form of LOOKUP is very similar to the HLOOKUP and VLOOKUP functions. The difference is that HLOOKUP searches for the value of lookup_value in the first row, VLOOKUP searches in the first column, and LOOKUP searches according to the dimensions of array.

**@param** {*} [result_array] Optional. A range that contains only one row or column. The result_array argument must be the same size as lookup_value. It has to be the same size.

**@returns**

```ts
export function LOOKUP(lookup_value: any, array: any, result_array?: any): any;;
```

---

### `LOWER`

Converts text to lowercase.

Category: Text

**@param** {*} text The text you want to convert to lowercase. LOWER does not change characters in text that are not letters.

**@returns**

```ts
export function LOWER(text: any, ...args: any[]): any;;
```

---

### `MATCH`

Looks up values in a reference or array.

Category: Lookup and reference

**@param** {*} lookup_value The value that you want to match in lookup_array. For example, when you look up someone's number in a telephone book, you are using the person's name as the lookup value, but the telephone number is the value you want.The lookup_value argument can be a value (number, text, or logical value) or a value reference to a number, text, or logical value.

**@param** {*} lookup_array The range of values being searched.

**@param** {*} [match_type] Optional. The number -1, 0, or 1. The match_type argument specifies how Excel matches lookup_value with values in lookup_array. The default value for this argument is 1.

**@returns**

```ts
export function MATCH(lookup_value: any, lookup_array: any, match_type?: any, ...args: any[]): number | Error;;
```

---

### `MAX`

Returns the maximum value in a list of arguments.

Category: Statistical

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 numbers for which you want to find the maximum value.

**@returns**

```ts
export function MAX(...args: any[]): any;;
```

---

### `MAXA`

Returns the maximum value in a list of arguments, including numbers, text, and logical values.

Category: Statistical

**@param** {*} args value1, value2,... Number arguments 2 to 255 for which you want to find the largest value.

**@returns**

```ts
export function MAXA(...args: any[]): any;;
```

---

### `MAXIFS`

Returns the maximum of all values in a range that meet multiple criteria.

Category: Statistical

**@returns**

```ts
export function MAXIFS(...args: any[]): any;;
```

---

### `MEDIAN`

Returns the median of the given numbers.

Category: Statistical

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 numbers for which you want the median.

**@returns**

```ts
export function MEDIAN(...args: any[]): any;;
```

---

### `MID`

Returns a specific number of characters from a text string starting at the position you specify

Category: Text

**@param** {*} text The text string containing the characters you want to extract.

**@param** {*} start_num The position of the first character you want to extract in text. The first character in text has start_num 1, and so on.

**@param** {*} num_chars Specifies the number of characters you want MID to return from text.

**@returns**

```ts
export function MID(text: any, start_num: any, num_chars: any): any;;
```

---

### `MIN`

Returns the minimum value in a list of arguments.

Category: Statistical

**@param** {*} args number1, number2, ... Number1 is optional, subsequent numbers are optional. 1 to 255 numbers for which you want to find the minimum value.

**@returns**

```ts
export function MIN(...args: any[]): any;;
```

---

### `MINA`

Returns the smallest value in a list of arguments, including numbers, text, and logical values.

Category: Statistical

**@param** {*} args value1, value2, ... Value1 is required, subsequent values are optional. 1 to 255 values for which you want to find the smallest value.

**@returns**

```ts
export function MINA(...args: any[]): any;;
```

---

### `MINIFS`

Returns the minimum of all values in a range that meet multiple criteria.

Category: Statistical

**@returns**

```ts
export function MINIFS(...args: any[]): any;;
```

---

### `MINUTE`

Converts a serial number to a minute.

Category: Date and time

**@param** {*} serial_number The time that contains the minute you want to find. Times may be entered as text strings within quotation marks (for example, "6:45 PM"), as decimal numbers (for example, 0.78125, which represents 6:45 PM), or as results of other formulas or functions (for example, TIMEVALUE("6:45 PM")).

**@returns**

```ts
export function MINUTE(serial_number: any): any;;
```

---

### `MIRR`

Returns the internal rate of return where positive and negative cash flows are financed at different rates.

Category: Financial

**@param** {*} values An array or a reference to values that contain numbers. These numbers represent a series of payments (negative values) and income (positive values) occurring at regular periods.
 - Values must contain at least one positive value and one negative value to calculate the modified internal rate of return. Otherwise, MIRR returns the #DIV/0! error value.
 - If an array or reference argument contains text, logical values, or empty values, those values are ignored; however, values with the value zero are included.

**@param** {*} finance_rate The interest rate you pay on the money used in the cash flows.

**@param** {*} reinvest_rate The interest rate you receive on the cash flows as you reinvest them.

**@returns**

```ts
export function MIRR(values: any, finance_rate: any, reinvest_rate: any): number | Error;;
```

---

### `MMULT`

Returns the matrix product of two arrays. The result is an array with the same number of rows as array1 and the same number of columns as array2.

Category: Math and trigonometry

**@param** {*} array1 Required. 1st array you want to multiply.

**@param** {*} array2 Required. 2nd array you want to multiply.

**@returns**

```ts
export function MMULT(array1: any, array2: any): Error | any[][];;
```

---

### `MOD`

Returns the remainder from division.

Category: Math and trigonometry

**@param** {*} number The number for which you want to find the remainder.

**@param** {*} divisor The number by which you want to divide number.

**@returns**

```ts
export function MOD(number: any, divisor: any): any;;
```

---

### `MODEMULT`

Returns a vertical array of the most frequently occurring, or repetitive values in an array or range of data.

Category: Statistical

**@param** {*} args number1, number2, ... Number arguments 2 to 254 for which you want to calculate the mode. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function MODEMULT(...args: any[]): any[] | Error;;
```

---

### `MODESNGL`

Returns the most common value in a data set.

Category: Statistical

**@param** {*} args number1, number2, ... Arguments 2 to 254 for which you want to calculate the mode. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function MODESNGL(...args: any[]): any;;
```

---

### `MONTH`

Converts a serial number to a month.

Category: Date and time

**@param** {*} serial_number The date of the month you are trying to find.

**@returns**

```ts
export function MONTH(serial_number: any): any;;
```

---

### `MROUND`

Returns a number rounded to the desired multiple.

Category: Math and trigonometry

**@param** {*} number The value to round.

**@param** {*} multiple The multiple to which you want to round number.

**@returns**

```ts
export function MROUND(number: any, multiple: any): any;;
```

---

### `MULTINOMIAL`

Returns the multinomial of a set of numbers.

Category: Math and trigonometry

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 values for which you want the multinomial.

**@returns**

```ts
export function MULTINOMIAL(...args: any[]): number | Error;;
```

---

### `MUNIT`

Returns the unit matrix for the specified dimension.

Category: Math and trigonometry

**@param** {*} dimension Required. Dimension is an integer specifying the dimension of the unit matrix that you want to return. It returns an array. The dimension has to be greater than zero.

**@returns**

```ts
export function MUNIT(dimension: any, ...args: any[]): Error | any[][];;
```

---

### `N`

Returns a value converted to a number.

Category: Information

**@param** {*} value The value you want converted. N converts values listed in the following table.

**@returns**

```ts
export function N(value: any): any;;
```

---

### `NA`

Returns the error value #N/A.

Category: Information

**@returns**

```ts
export function NA(): Error;;
```

---

### `NEGBINOMDIST`

Returns the negative binomial distribution.

Category: Statistical

**@param** {*} number_f The number of failures.

**@param** {*} number_s The threshold number of successes.

**@param** {*} probability_s The probability of a success.

**@param** {*} cumulative A logical value that determines the form of the function. If cumulative is TRUE, NEGBINOM.DIST returns the cumulative distribution function; if FALSE, it returns the probability density function.

**@returns**

```ts
export function NEGBINOMDIST(number_f: any, number_s: any, probability_s: any, cumulative: any): any;;
```

---

### `NETWORKDAYS`

Returns the number of whole workdays between two dates.

Category: Date and time

**@param** {*} start_date A date that represents the start date.

**@param** {*} end_date A date that represents the end date.

**@param** {*} [holidays] Optional. An optional range of one or more dates to exclude from the working calendar, such as state and federal holidays and floating holidays. The list can be either a range of values that contains the dates or an array constant of the serial numbers that represent the dates.

**@returns**

```ts
export function NETWORKDAYS(start_date: any, end_date: any, holidays?: any): number | Error;;
```

---

### `NETWORKDAYSINTL`

Returns the number of whole workdays between two dates using parameters to indicate which and how many days are weekend days.

Category: Date and time

**@param** {*} start_date The date for from which the difference is to be computed. The start_date can be earlier than, the same as, or later than the end_date.

**@param** {*} end_date The date for to which the difference is to be computed.

**@param** {*} [weekend] Optional. Indicates the days of the week that are weekend days and are not included in the number of whole working days between start_date and end_date. Weekend is a weekend number or string that specifies when weekends occur. Weekend number values indicate the following weekend days:

**@param** {*} [holidays] Optional. An optional set of one or more dates that are to be excluded from the working day calendar. holidays shall be a range of values that contain the dates, or an array constant of the serial values that represent those dates. The ordering of dates or serial values in holidays can be arbitrary.

**@returns**

```ts
export function NETWORKDAYSINTL(start_date: any, end_date: any, weekend?: any, holidays?: any): number | Error;;
```

---

### `NOMINAL`

Returns the annual nominal interest rate.

Category: Financial

**@param** {*} effect_rate The effective interest rate.

**@param** {*} npery The number of compounding periods per year.

**@returns**

```ts
export function NOMINAL(effect_rate: any, npery: any): number | Error;;
```

---

### `NORMDIST`

Returns the normal cumulative distribution.

Category: Statistical

**@param** {*} x The value for which you want the distribution.

**@param** {*} mean The arithmetic mean of the distribution.

**@param** {*} standard_dev The standard deviation of the distribution.

**@param** {*} cumulative A logical value that determines the form of the function. If cumulative is TRUE, NORM.DIST returns the cumulative distribution function; if FALSE, it returns the probability density function.

**@returns**

```ts
export function NORMDIST(x: any, mean: any, standard_dev: any, cumulative: any): any;;
```

---

### `NORMINV`

Returns the inverse of the normal cumulative distribution.

Category: Statistical

**@param** {*} probability A probability corresponding to the normal distribution.

**@param** {*} mean The arithmetic mean of the distribution.

**@param** {*} standard_dev The standard deviation of the distribution.

**@returns**

```ts
export function NORMINV(probability: any, mean: any, standard_dev: any): any;;
```

---

### `NORMSDIST`

Returns the standard normal cumulative distribution.

Category: Statistical

**@param** {*} z The value for which you want the distribution.

**@param** {*} cumulative Cumulative is a logical value that determines the form of the function. If cumulative is TRUE, NORMS.DIST returns the cumulative distribution function; if FALSE, it returns the probability mass function.

**@returns**

```ts
export function NORMSDIST(z: any, cumulative: any): any;;
```

---

### `NORMSINV`

Returns the inverse of the standard normal cumulative distribution.

Category: Statistical

**@param** {*} probability A probability corresponding to the normal distribution.

**@returns**

```ts
export function NORMSINV(probability: any): any;;
```

---

### `NOT`

Reverses the logic of its argument.

Category: Logical

**@returns**

```ts
export function NOT(logical: any): boolean | Error;;
```

---

### `NOW`

Returns the serial number of the current date and time.

Category: Date and time

**@returns**

```ts
export function NOW(): number | Date;;
```

---

### `NPER`

Returns the number of periods for an investment.

Category: Financial

**@param** {*} rate The interest rate per period.

**@param** {*} pmt The payment made each period; it cannot change over the life of the annuity. Typically, pmt contains principal and interest but no other fees or taxes.

**@param** {*} pv The present value, or the lump-sum amount that a series of future payments is worth right now.

**@param** {*} [fv] Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (the future value of a loan, for example, is 0).

**@param** {*} [type] Optional. The number 0 or 1 and indicates when payments are due.

**@returns**

```ts
export function NPER(rate: any, pmt: any, pv: any, fv?: any, type?: any): number | Error;;
```

---

### `NPV`

Returns the net present value of an investment based on a series of periodic cash flows and a discount rate.

Category: Financial

**@param** {*} rate The rate of discount over the length of one period.

**@param** {*} args value1, value2, ... Value1 is required, subsequent values are optional. 1 to 254 arguments representing the payments and income.
 - value1, value2, ... must be equally spaced in time and occur at the end of each period.
 - NPV uses the order of value1, value2, ... to interpret the order of cash flows. Be sure to enter your payment and income values in the correct sequence.
 - Arguments that are empty values, logical values, or text representations of numbers, error values, or text that cannot be translated into numbers are ignored.
 - If an argument is an array or reference, only numbers in that array or reference are counted. Empty values, logical values, text, or error values in the array or reference are ignored.

**@returns**

```ts
export function NPV(...args: any[]): number | Error;;
```

---

### `NUMBERVALUE`

Converts text to number in a locale-independent manner.

Category: Text

**@param** {*} text The text to convert to a number.

**@param** {*} [decimal_separator] Optional. The character used to separate the integer and fractional part of the result.

**@param** {*} [group_separator] Optional. The character used to separate groupings of numbers, such as thousands from hundreds and millions from thousands.

**@returns**

```ts
export function NUMBERVALUE(text: any, decimal_separator?: any, group_separator?: any): number | Error;;
```

---

### `OCT2BIN`

Converts an octal number to binary.

Category: Engineering

**@param** {*} number The octal number you want to convert. Number may not contain more than 10 characters. The most significant bit of number is the sign bit. The remaining 29 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@param** {*} [places] Optional. The number of characters to use. If places is omitted, OCT2BIN uses the minimum number of characters necessary. Places is useful for padding the return value with leading 0s (zeros).

**@returns**

```ts
export function OCT2BIN(number: any, places?: any): string | Error;;
```

---

### `OCT2DEC`

Converts an octal number to decimal.

Category: Engineering

**@param** {*} number The octal number you want to convert. Number may not contain more than 10 octal characters (30 bits). The most significant bit of number is the sign bit. The remaining 29 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@returns**

```ts
export function OCT2DEC(number: any): number | Error;;
```

---

### `OCT2HEX`

Converts an octal number to hexadecimal.

Category: Engineering

**@param** {*} number The octal number you want to convert. Number may not contain more than 10 octal characters (30 bits). The most significant bit of number is the sign bit. The remaining 29 bits are magnitude bits. Negative numbers are represented using two's-complement notation.

**@param** {*} [places] Optional. The number of characters to use. If places is omitted, OCT2HEX uses the minimum number of characters necessary. Places is useful for padding the return value with leading 0s (zeros).

**@returns**

```ts
export function OCT2HEX(number: any, places?: any): string | Error;;
```

---

### `ODD`

Rounds a number up to the nearest odd integer.

Category: Math and trigonometry

**@param** {*} number: The value to round.

**@returns**

```ts
export function ODD(number: any): number | Error;;
```

---

### `OR`

Returns TRUE if any argument is TRUE.

Category: Logical

**@returns**

```ts
export function OR(...args: any[]): any;;
```

---

### `PDURATION`

Returns the number of periods required by an investment to reach a specified value.

Category: Financial

**@param** {*} rate Rate is the interest rate per period.

**@param** {*} pv Pv is the present value of the investment.

**@param** {*} fv Fv is the desired future value of the investment.

**@returns**

```ts
export function PDURATION(rate: any, pv: any, fv: any): number | Error;;
```

---

### `PEARSON`

Returns the Pearson product moment correlation coefficient.

Category: Statistical

**@param** {*} array1 A set of independent values.

**@param** {*} array2 A set of dependent values.

**@returns**

```ts
export function PEARSON(array1: any, array2: any): number | Error;;
```

---

### `PERCENTILEEXC`

Returns the k-th percentile of values in a range, where k is in the range 0..1, exclusive.

Category: Statistical

**@returns**

```ts
export function PERCENTILEEXC(array: any, k: any): number | Error;;
```

---

### `PERCENTILEINC`

Returns the k-th percentile of values in a range.

Category: Statistical

**@param** {*} array The array or range of data that defines relative standing.

**@param** {*} k The percentile value in the range 0..1, inclusive.

**@returns**

```ts
export function PERCENTILEINC(array: any, k: any): number | Error;;
```

---

### `PERCENTRANKEXC`

Returns the rank of a value in a data set as a percentage (0..1, exclusive) of the data set.

Category: Statistical

**@param** {*} array The array or range of data with numeric values that defines relative standing

**@param** {*} x The value for which you want to know the rank.

**@param** {*} [significance] Optional. A value that identifies the number of significant digits for the returned percentage value. If omitted, PERCENTRANK.EXC uses three digits (0.xxx).

**@returns**

```ts
export function PERCENTRANKEXC(array: any, x: any, significance?: any): number | Error;;
```

---

### `PERCENTRANKINC`

Returns the percentage rank of a value in a data set.

Category: Statistical

**@param** {*} array The array or range of data with numeric values that defines relative standing.

**@param** {*} x The value for which you want to know the rank.

**@param** {*} [significance] Optional. A value that identifies the number of significant digits for the returned percentage value. If omitted, PERCENTRANK.INC uses three digits (0.xxx).

**@returns**

```ts
export function PERCENTRANKINC(array: any, x: any, significance?: any): number | Error;;
```

---

### `PERMUT`

Returns the number of permutations for a given number of objects.

Category: Statistical

**@param** {*} number An integer that describes the number of objects.

**@param** {*} number_chosen An integer that describes the number of objects in each permutation.

**@returns**

```ts
export function PERMUT(number: any, number_chosen: any): number | Error;;
```

---

### `PERMUTATIONA`

Returns the number of permutations for a given number of objects (with repetitions) that can be selected from the total objects.

Category: Statistical

**@param** {*} number An integer that describes the total number of objects.

**@param** {*} number_chosen An integer that describes the number of objects in each permutation.

**@returns**

```ts
export function PERMUTATIONA(number: any, number_chosen: any): number | Error;;
```

---

### `PHI`

Returns the value of the density function for a standard normal distribution.

Category: Statistical

**@param** {*} x X is the number for which you want the density of the standard normal distribution.

**@returns**

```ts
export function PHI(x: any): number | Error;;
```

---

### `PI`

Returns the value of pi.

Category: Math and trigonometry

**@returns**

```ts
export function PI(): number;;
```

---

### `PMT`

Returns the periodic payment for an annuity.

Category: Financial

**@param** {*} rate The interest rate for the loan.

**@param** {*} nper The total number of payments for the loan.

**@param** {*} pv The present value, or the total amount that a series of future payments is worth now; also known as the principal.

**@param** {*} [fv] Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (zero), that is, the future value of a loan is 0.

**@param** {*} [type] Optional. The number 0 (zero) or 1 and indicates when payments are due.

**@returns**

```ts
export function PMT(rate: any, nper: any, pv: any, fv?: any, type?: any): number | Error;;
```

---

### `POISSONDIST`

Returns the Poisson distribution.

Category: Statistical

**@param** {*} x The number of events.

**@param** {*} mean The expected numeric value.

**@param** {*} cumulative A logical value that determines the form of the probability distribution returned. If cumulative is TRUE, POISSON.DIST returns the cumulative Poisson probability that the number of random events occurring will be between zero and x inclusive; if FALSE, it returns the Poisson probability mass function that the number of events occurring will be exactly x.

**@returns**

```ts
export function POISSONDIST(x: any, mean: any, cumulative: any): any;;
```

---

### `POWER`

Returns the result of a number raised to a power.

Category: Math and trigonometry

**@param** {*} number The base number. It can be any real number.

**@param** {*} power The exponent to which the base number is raised.

**@returns**

```ts
export function POWER(number: any, power: any): any;;
```

---

### `PPMT`

Returns the payment on the principal for an investment for a given period.

Category: Financial

**@param** {*} rate The interest rate per period.

**@param** {*} per Specifies the period and must be in the range 1 to nper.

**@param** {*} nper The total number of payment periods in an annuity.

**@param** {*} pv The present value — the total amount that a series of future payments is worth now.

**@param** {*} [fv] Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (zero), that is, the future value of a loan is 0.

**@param** {*} [type] Optional. The number 0 or 1 and indicates when payments are due.

**@returns**

```ts
export function PPMT(rate: any, per: any, nper: any, pv: any, fv?: any, type?: any): number | Error;;
```

---

### `PRICEDISC`

Returns the price per $100 face value of a discounted security.

Category: Financial

**@param** {*} settlement The security's settlement date. The security settlement date is the date after the issue date when the security is traded to the buyer.

**@param** {*} maturity The security's maturity date. The maturity date is the date when the security expires.

**@param** {*} discount The security's discount rate.

**@param** {*} redemption The security's redemption value per $100 face value.

**@param** {*} [basis] Optional. The type of day count basis to use.

**@returns**

```ts
export function PRICEDISC(settlement: any, maturity: any, discount: any, redemption: any, basis?: any): number | Error;;
```

---

### `PROB`

Returns the probability that values in a range are between two limits.

Category: Statistical

**@param** {*} x_range The range of numeric values of x with which there are associated probabilities.

**@param** {*} prob_range A set of probabilities associated with values in x_range.

**@param** {*} [lower_limit] Optional. The lower bound on the value for which you want a probability.

**@param** {*} [upper_limit] Optional. The optional upper bound on the value for which you want a probability.

**@returns**

```ts
export function PROB(x_range: any, prob_range: any, lower_limit?: any, upper_limit?: any): any;;
```

---

### `PRODUCT`

Multiplies its arguments.

Category: Math and trigonometry

**@param** {*} number1 The first number or range that you want to multiply.

**@param** {*} args number2, ... Optional. Additional numbers or ranges that you want to multiply, up to a maximum of 255 arguments.

**@returns**

```ts
export function PRODUCT(...args: any[]): number | Error;;
```

---

### `PROPER`

Capitalizes the first letter in each word of a text value.

Category: Text

**@param** {*} text Text enclosed in quotation marks, a formula that returns text, or a reference to a value containing the text you want to partially capitalize.

**@returns**

```ts
export function PROPER(text: any): any;;
```

---

### `PV`

Returns the present value of an investment.

Category: Financial

**@param** {*} rate The interest rate per period. For example, if you obtain an automobile loan at a 10 percent annual interest rate and make monthly payments, your interest rate per month is 10%/12, or 0.83%. You would enter 10%/12, or 0.83%, or 0.0083, into the formula as the rate.

**@param** {*} nper The total number of payment periods in an annuity. For example, if you get a four-year car loan and make monthly payments, your loan has 4*12 (or 48) periods. You would enter 48 into the formula for nper.

**@param** {*} pmt The payment made each period and cannot change over the life of the annuity. Typically, pmt includes principal and interest but no other fees or taxes. For example, the monthly payments on a $10,000, four-year car loan at 12 percent are $263.33. You would enter -263.33 into the formula as the pmt. If pmt is omitted, you must include the fv argument.

**@param** {*} [fv] Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (the future value of a loan, for example, is 0). For example, if you want to save $50,000 to pay for a special project in 18 years, then $50,000 is the future value. You could then make a conservative guess at an interest rate and determine how much you must save each month. If fv is omitted, you must include the pmt argument.

**@param** {*} [type] Optional. The number 0 or 1 and indicates when payments are due.

**@returns**

```ts
export function PV(rate: any, per: any, pmt: any, fv?: any, type?: any): number | Error;;
```

---

### `QUARTILEEXC`

Returns the quartile of the data set, based on percentile values from 0..1, exclusive.

Category: Statistical

**@param** {*} array The array or value range of numeric values for which you want the quartile value.

**@param** {*} quart Indicates which value to return.

**@returns**

```ts
export function QUARTILEEXC(range: any, quart: any): number | Error;;
```

---

### `QUARTILEINC`

Returns the quartile of a data set.

Category: Statistical

**@param** {*} array The array or value range of numeric values for which you want the quartile value.

**@param** {*} quart Indicates which value to return.

**@returns**

```ts
export function QUARTILEINC(range: any, quart: any): number | Error;;
```

---

### `QUOTIENT`

Returns the integer portion of a division.

Category: Math and trigonometry

**@param** {*} numerator The dividend.

**@param** {*} denominator The divisor.

**@returns**

```ts
export function QUOTIENT(numerator: any, denominator: any): any;;
```

---

### `RADIANS`

Converts degrees to radians.

Category: Math and trigonometry

**@param** {*} angle An angle in degrees that you want to convert.

**@returns**

```ts
export function RADIANS(angle: any): number | Error;;
```

---

### `RAND`

Returns a random number between 0 and 1.

Category: Math and trigonometry

**@returns**

```ts
export function RAND(): number;;
```

---

### `RANDBETWEEN`

Returns a random number between the numbers you specify.

Category: Math and trigonometry

**@param** {*} bottom The smallest integer RANDBETWEEN will return.

**@param** {*} top The largest integer RANDBETWEEN will return.

**@returns**

```ts
export function RANDBETWEEN(bottom: any, top: any): any;;
```

---

### `RANKAVG`

Returns the rank of a number in a list of numbers.

Category: Statistical

**@param** {*} number The number whose rank you want to find.

**@param** {*} ref An array of, or a reference to, a list of numbers. Nonnumeric values in Ref are ignored.

**@param** {*} [order] Optional. A number specifying how to rank number.

**@returns**

```ts
export function RANKAVG(number: any, ref: any, order?: any): any;;
```

---

### `RANKEQ`

Returns the rank of a number in a list of numbers.

Category: Statistical

**@param** {*} number The number whose rank you want to find.

**@param** {*} ref An array of, or a reference to, a list of numbers. Non-numeric values in Ref are ignored.

**@param** {*} [order] Optional. A number specifying how to rank number.

**@returns**

```ts
export function RANKEQ(number: any, ref: any, order?: any): any;;
```

---

### `RATE`

Returns the interest rate per period of an annuity.

Category: Financial

**@param** {*} nper The total number of payment periods in an annuity.

**@param** {*} pmt The payment made each period and cannot change over the life of the annuity. Typically, pmt includes principal and interest but no other fees or taxes. If pmt is omitted, you must include the fv argument.

**@param** {*} pv The present value — the total amount that a series of future payments is worth now.

**@param** {*} [fv] Optional. The future value, or a cash balance you want to attain after the last payment is made. If fv is omitted, it is assumed to be 0 (the future value of a loan, for example, is 0). If fv is omitted, you must include the pmt argument.

**@param** {*} [type] Optional. The number 0 or 1 and indicates when payments are due.

**@param** {*} [guess] Optional. Your guess for what the rate will be. If you omit guess, it is assumed to be 10 percent. If RATE does not converge, try different values for guess. RATE usually converges if guess is between 0 and 1.
 - If you omit guess, it is assumed to be 10 percent.
 - If RATE does not converge, try different values for guess. RATE usually converges if guess is between 0 and 1.

**@returns**

```ts
export function RATE(nper: any, pmt: any, pv: any, fv?: any, type?: any, guess?: any): any;;
```

---

### `REPLACE`

Replaces characters within text

Category: Text

**@param** {*} old_text Text in which you want to replace some characters.

**@param** {*} num_chars The number of characters in old_text that you want REPLACE to replace with new_text.

**@param** {*} length he number of characters in old_text that you want REPLACEB to replace with new_text.

**@param** {*} new_text he text that will replace characters in old_text.

**@returns**

```ts
export function REPLACE(old_text: any, num_chars: any, length: any, new_text: any): string | Error;;
```

---

### `REPT`

Repeats text a given number of times.

Category: Text

**@param** {*} text The text you want to repeat.

**@param** {*} number_times A positive number specifying the number of times to repeat text.

**@returns**

```ts
export function REPT(text: any, number_times: any): any;;
```

---

### `RIGHT`

Returns the rightmost characters from a text value

Category: Text

**@param** {*} text The text string containing the characters you want to extract.

**@param** {*} [num_chars] Optional. Specifies the number of characters you want RIGHT to extract.

**@returns**

```ts
export function RIGHT(text: any, num_chars?: any): any;;
```

---

### `ROMAN`

Converts an arabic numeral to roman, as text.

Category: Math and trigonometry

**@param** {*} number The Arabic numeral you want converted.

**@returns**

```ts
export function ROMAN(number: any): string | Error;;
```

---

### `ROUND`

Rounds a number to a specified number of digits.

Category: Math and trigonometry

**@param** {*} number The number that you want to round.

**@param** {*} num_digits The number of digits to which you want to round the number argument.

**@returns**

```ts
export function ROUND(number: any, num_digits: any): any;;
```

---

### `ROUNDDOWN`

Rounds a number down, toward zero.

Category: Math and trigonometry

**@param** {*} number Any real number that you want rounded down.

**@param** {*} num_digits The number of digits to which you want to round number.

**@returns**

```ts
export function ROUNDDOWN(number: any, num_digits: any): any;;
```

---

### `ROUNDUP`

Rounds a number up, away from zero.

Category: Math and trigonometry

**@param** {*} number Any real number that you want rounded up.

**@param** {*} num_digits The number of digits to which you want to round number.

**@returns**

```ts
export function ROUNDUP(number: any, num_digits: any): any;;
```

---

### `ROW`

Returns the row number of a reference.

Category: Lookup and reference

**@param** {*} reference the value or range of values for which you want the row number.

**@param** {*} index

**@returns**

```ts
export function ROW(reference: any, index: any, ...args: any[]): any;;
```

---

### `ROWS`

Returns the number of rows in a reference.

Category: Lookup and reference

**@param** {*} array An array, an array formula, or a reference to a range of values for which you want the number of rows.

**@returns**

```ts
export function ROWS(array: any, ...args: any[]): any;;
```

---

### `RRI`

Returns an equivalent interest rate for the growth of an investment.

Category: Financial

**@param** {*} nper Nper is the number of periods for the investment.

**@param** {*} pv Pv is the present value of the investment.

**@param** {*} fv Fv is the future value of the investment.

**@returns**

```ts
export function RRI(nper: any, pv: any, fv: any): number | Error;;
```

---

### `RSQ`

Returns the square of the Pearson product moment correlation coefficient.

Category: Statistical

**@param** {*} known_y An array or range of data points.

**@param** {*} known_x An array or range of data points.

**@returns**

```ts
export function RSQ(known_y: any, known_x: any): number | Error;;
```

---

### `SEARCH`

Finds one text value within another (not case-sensitive)

Category: Text

**@param** {*} find_text The text that you want to find.

**@param** {*} within_text The text in which you want to search for the value of the find_text argument.

**@param** {*} [start_num] Optional. The character number in the within_text argument at which you want to start searching.

**@returns**

```ts
export function SEARCH(find_text: any, within_text: any, start_num?: any): number | Error;;
```

---

### `SEC`

Returns the secant of an angle.

Category: Math and trigonometry

**@param** {*} number The angle in radians for which you want the secant.

**@returns**

```ts
export function SEC(number: any): number | Error;;
```

---

### `SECH`

Returns the hyperbolic secant of an angle.

Category: Math and trigonometry

**@param** {*} number The angle in radians for which you want the hyperbolic secant.

**@returns**

```ts
export function SECH(number: any): number | Error;;
```

---

### `SECOND`

Converts a serial number to a second.

Category: Date and time

**@param** {*} serial_number The time that contains the seconds you want to find. Times may be entered as text strings within quotation marks (for example, "6:45 PM"), as decimal numbers (for example, 0.78125, which represents 6:45 PM), or as results of other formulas or functions (for example, TIMEVALUE("6:45 PM")).

**@returns**

```ts
export function SECOND(serial_number: any): any;;
```

---

### `SERIESSUM`

Returns the sum of a power series based on the formula.

Category: Math and trigonometry

**@param** {*} x The input value to the power series.

**@param** {*} n The initial power to which you want to raise x.

**@param** {*} m The step by which to increase n for each term in the series.

**@param** {*} coefficients A set of coefficients by which each successive power of x is multiplied. The number of values in coefficients determines the number of terms in the power series. For example, if there are three values in coefficients, then there will be three terms in the power series.

**@returns**

```ts
export function SERIESSUM(x: any, n: any, m: any, coefficients: any): number | Error;;
```

---

### `SIGN`

Returns the sign of a number.

Category: Math and trigonometry

**@param** {*} number Any real number.

**@returns**

```ts
export function SIGN(number: any): 0 | Error | 1 | -1;;
```

---

### `SIN`

Returns the sine of the given angle.

Category: Math and trigonometry

**@param** {*} number The angle in radians for which you want the sine.

**@returns**

```ts
export function SIN(number: any): number | Error;;
```

---

### `SINH`

Returns the hyperbolic sine of a number.

Category: Math and trigonometry

**@param** {*} number Any real number.

**@returns**

```ts
export function SINH(number: any): number | Error;;
```

---

### `SKEW`

Returns the skewness of a distribution.

Category: Statistical

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 arguments for which you want to calculate skewness. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function SKEW(...args: any[]): number | Error;;
```

---

### `SKEWP`

Returns the skewness of a distribution based on a population.

Category: Statistical

**@returns**

```ts
export function SKEWP(...args: any[]): number | Error;;
```

---

### `SLN`

Returns the straight-line depreciation of an asset for one period.

Category: Financial

**@param** {*} cost The initial cost of the asset.

**@param** {*} salvage The value at the end of the depreciation (sometimes called the salvage value of the asset).

**@param** {*} life The number of periods over which the asset is depreciated (sometimes called the useful life of the asset).

**@returns**

```ts
export function SLN(cost: any, salvage: any, life: any): number | Error;;
```

---

### `SLOPE`

Returns the slope of the linear regression line.

Category: Statistical

**@param** {*} known_y An array or value range of numeric dependent data points.

**@param** {*} known_x The set of independent data points.

**@returns**

```ts
export function SLOPE(known_y: any, known_x: any): number | Error;;
```

---

### `SMALL`

Returns the k-th smallest value in a data set.

Category: Statistical

**@param** {*} array An array or range of numerical data for which you want to determine the k-th smallest value.

**@param** {*} k The position (from the smallest) in the array or range of data to return.

**@returns**

```ts
export function SMALL(array: any, k: any): any;;
```

---

### `SORT`

Returns a sorted array of the elements in an array. The returned array is the same shape as the provided array argument.

Category: Lookup and reference

**@param** {*} array Array to sort

**@param** {*} [sort_index] Optional. A number indicating the row or column to sort by

**@param** {*} [sort_order] Optional. A number indicating the desired sort order; 1 for ascending order (default), -1 for descending order

**@param** {*} [by_col] Optional. A logical value indicating the desired sort direction; FALSE to sort by row (default), TRUE to sort by column

**@returns**

```ts
export function SORT(array: any, sort_index?: any, sort_order?: any, by_col?: any): any;;
```

---

### `SQRT`

Returns a positive square root.

Category: Math and trigonometry

**@param** {*} number The number for which you want the square root.

**@returns**

```ts
export function SQRT(number: any): number | Error;;
```

---

### `SQRTPI`

Returns the square root of (number * pi).

Category: Math and trigonometry

**@param** {*} number The number by which pi is multiplied.

**@returns**

```ts
export function SQRTPI(number: any): number | Error;;
```

---

### `STANDARDIZE`

Returns a normalized value.

Category: Statistical

**@param** {*} x The value you want to normalize.

**@param** {*} mean The arithmetic mean of the distribution.

**@param** {*} standard_dev The standard deviation of the distribution.

**@returns**

```ts
export function STANDARDIZE(x: any, mean: any, standard_dev: any): number | Error;;
```

---

### `STDEVA`

Estimates standard deviation based on a sample, including numbers, text, and logical values.

Category: Statistical

**@param** {*} args value1, value2, ... Value1 is required, subsequent values are optional. 1 to 255 values corresponding to a sample of a population. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function STDEVA(...args: any[]): number;;
```

---

### `STDEVP`

Calculates standard deviation based on the entire population.

Category: Statistical

**@param** {*} args number1, number2, ... Number arguments 2 to 254 corresponding to a population. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function STDEVP(...args: any[]): number;;
```

---

### `STDEVPA`

Calculates standard deviation based on the entire population, including numbers, text, and logical values.

Category: Statistical

**@param** {*} args value1, value2, ... Value1 is required, subsequent values are optional. 1 to 255 values corresponding to a population. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function STDEVPA(...args: any[]): number;;
```

---

### `STDEVS`

Estimates standard deviation based on a sample.

Category: Statistical

**@param** {*} args number1, number2, ... Number arguments 2 to 254 corresponding to a sample of a population. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function STDEVS(...args: any[]): number;;
```

---

### `STEYX`

Returns the standard error of the predicted y-value for each x in the regression.

Category: Statistical

**@param** {*} known_y An array or range of dependent data points.

**@param** {*} known_x An array or range of independent data points.

**@returns**

```ts
export function STEYX(known_y: any, known_x: any): number | Error;;
```

---

### `SUBSTITUTE`

Substitutes new text for old text in a text string.

Category: Text

**@param** {*} text The text or the reference to a value containing text for which you want to substitute characters.

**@param** {*} old_text The text you want to replace.

**@param** {*} new_text The text you want to replace old_text with.

**@param** {*} [instance_num] Optional. Specifies which occurrence of old_text you want to replace with new_text. If you specify instance_num, only that instance of old_text is replaced. Otherwise, every occurrence of old_text in text is changed to new_text.

**@returns**

```ts
export function SUBSTITUTE(text: any, old_text: any, new_text: any, instance_num?: any, ...args: any[]): any;;
```

---

### `SUBTOTAL`

Returns a subtotal in a list or database.

Category: Math and trigonometry

**@param** {*} function_num The number 1-11 or 101-111 that specifies the function to use for the subtotal. 1-11 includes manually-hidden rows, while 101-111 excludes them; filtered-out values are always excluded.

**@param** {*} ref1 The first named range or reference for which you want the subtotal.

**@returns**

```ts
export function SUBTOTAL(function_num: any, ref1: any): any;;
```

---

### `SUM`

Adds its arguments.

Category: Math and trigonometry

**@returns**

```ts
export function SUM(...args: any[]): number;;
```

---

### `SUMIF`

Adds the values specified by a given criteria.

Category: Math and trigonometry

**@param** {*} range The range of values that you want evaluated by criteria. Cells in each range must be numbers or names, arrays, or references that contain numbers. Blank and text values are ignored.

**@param** {*} criteria The criteria in the form of a number, expression, a value reference, text, or a function that defines which values will be added.

**@param** {*} [sum_range] Optional. The actual values to add, if you want to add values other than those specified in the range argument. If the sum_range argument is omitted, Excel adds the values that are specified in the range argument (the same values to which the criteria is applied). Sum_range should be the same size and shape as range. If it isn't, performance may suffer, and the formula will sum a range of values that starts with the first value in sum_range but has the same dimensions as range.

**@returns**

```ts
export function SUMIF(range: any, criteria: any, sum_range?: any): number | Error;;
```

---

### `SUMIFS`

Adds the values in a range that meet multiple criteria.

Category: Math and trigonometry

**@returns**

```ts
export function SUMIFS(...args: any[]): number;;
```

---

### `SUMPRODUCT`

Returns the sum of the products of corresponding array components.

Category: Math and trigonometry

**@returns**

```ts
export function SUMPRODUCT(...args: any[]): number | Error;;
```

---

### `SUMSQ`

Returns the sum of the squares of the arguments.

Category: Math and trigonometry

**@param** {*} args number1, number2, ... Number1 is required, subsequent numbers are optional. 1 to 255 arguments for which you want the sum of the squares. You can also use a single array or a reference to an array instead of arguments separated by commas.

**@returns**

```ts
export function SUMSQ(...args: any[]): number | Error;;
```

---

### `SUMX2MY2`

Returns the sum of the difference of squares of corresponding values in two arrays.

Category: Math and trigonometry

**@param** {*} array_x The first array or range of values.

**@param** {*} array_y The second array or range of values.

**@returns**

```ts
export function SUMX2MY2(array_x: any, array_y: any): number | Error;;
```

---

### `SUMX2PY2`

Returns the sum of the sum of squares of corresponding values in two arrays.

Category: Math and trigonometry

**@param** {*} array_x The first array or range of values.

**@param** {*} array_y The second array or range of values.

**@returns**

```ts
export function SUMX2PY2(array_x: any, array_y: any): number | Error;;
```

---

### `SUMXMY2`

Returns the sum of squares of differences of corresponding values in two arrays.

Category: Math and trigonometry

**@param** {*} array_x The first array or range of values.

**@param** {*} array_y The second array or range of values.

**@returns**

```ts
export function SUMXMY2(array_x: any, array_y: any): number | Error;;
```

---

### `SWITCH`

Evaluates an expression against a list of values and returns the result corresponding to the first matching value. If there is no match, an optional default value may be returned.

Category: Logical

**@returns**

```ts
export function SWITCH(...args: any[]): any;;
```

---

### `SYD`

Returns the sum-of-years' digits depreciation of an asset for a specified period.

Category: Financial

**@param** {*} cost The initial cost of the asset.

**@param** {*} salvage The value at the end of the depreciation (sometimes called the salvage value of the asset).

**@param** {*} life The number of periods over which the asset is depreciated (sometimes called the useful life of the asset).

**@param** {*} per The period and must use the same units as life.

**@returns**

```ts
export function SYD(cost: any, salvage: any, life: any, per: any): number | Error;;
```

---

### `T`

Converts its arguments to text.

Category: Text

**@param** {*} value The value you want to test.

**@returns**

```ts
export function T(value: any): string | Error;;
```

---

### `TAN`

Returns the tangent of a number.

Category: Math and trigonometry

**@param** {*} number The angle in radians for which you want the tangent.

**@returns**

```ts
export function TAN(number: any): number | Error;;
```

---

### `TANH`

Returns the hyperbolic tangent of a number.

Category: Math and trigonometry

**@param** {*} number Any real number.

**@returns**

```ts
export function TANH(number: any): number | Error;;
```

---

### `TBILLEQ`

Returns the bond-equivalent yield for a Treasury bill.

Category: Financial

**@param** {*} settlement The Treasury bill's settlement date. The security settlement date is the date after the issue date when the Treasury bill is traded to the buyer.

**@param** {*} maturity The Treasury bill's maturity date. The maturity date is the date when the Treasury bill expires.

**@param** {*} discount The Treasury bill's discount rate.

**@returns**

```ts
export function TBILLEQ(settlement: any, maturity: any, discount: any): number | Error;;
```

---

### `TBILLPRICE`

Returns the price per $100 face value for a Treasury bill.

Category: Financial

**@param** {*} settlement The Treasury bill's settlement date. The security settlement date is the date after the issue date when the Treasury bill is traded to the buyer.

**@param** {*} maturity The Treasury bill's maturity date. The maturity date is the date when the Treasury bill expires.

**@param** {*} discount The Treasury bill's discount rate.

**@returns**

```ts
export function TBILLPRICE(settlement: any, maturity: any, discount: any): number | Error;;
```

---

### `TBILLYIELD`

Returns the yield for a Treasury bill.

Category: Financial

**@param** {*} settlement The Treasury bill's settlement date. The security settlement date is the date after the issue date when the Treasury bill is traded to the buyer.

**@param** {*} maturity The Treasury bill's maturity date. The maturity date is the date when the Treasury bill expires.

**@param** {*} pr The Treasury bill's price per $100 face value.

**@returns**

```ts
export function TBILLYIELD(settlement: any, maturity: any, pr: any): number | Error;;
```

---

### `TDIST`

Returns the Percentage Points (probability) for the Student t-distribution.

Category: Statistical

**@param** {*} x The numeric value at which to evaluate the distribution

**@param** {*} deg_freedom An integer indicating the number of degrees of freedom.

**@param** {*} cumulative A logical value that determines the form of the function. If cumulative is TRUE, T.DIST returns the cumulative distribution function; if FALSE, it returns the probability density function.

**@returns**

```ts
export function TDIST(x: any, deg_freedom: any, cumulative: any): number | Error;;
```

---

### `TDISTRT`

Returns the Student's t-distribution.

Category: Statistical

**@param** {*} x The numeric value at which to evaluate the distribution.

**@param** {*} deg_freedom An integer indicating the number of degrees of freedom.

**@returns**

```ts
export function TDISTRT(x: any, deg_freedom: any, ...args: any[]): number | Error;;
```

---

### `TEXT`

Formats a number and converts it to text.

Category: Text

**@param** {*} value A numeric value that you want to be converted into text.

**@param** {*} format_text A text string that defines the formatting that you want to be applied to the supplied value.

**@returns**

```ts
export function TEXT(value$1: any, format_text: any): any;;
```

---

### `TEXTJOIN`

Combines the text from multiple ranges and/or strings.

Category: Text

**@param** {*} delimiter A text string, either empty, or one or more characters enclosed by double quotes, or a reference to a valid text string. If a number is supplied, it will be treated as text.

**@param** {*} ignore_empty If TRUE, ignores empty values.

**@param** {*} args Text item to be joined. A text string, or array of strings, such as a range of values.

**@returns**

```ts
export function TEXTJOIN(delimiter: any, ignore_empty: any, ...args: any): any;;
```

---

### `TIME`

Returns the serial number of a particular time.

Category: Date and time

**@param** {*} hour A number from 0 (zero) to 32767 representing the hour. Any value greater than 23 will be divided by 24 and the remainder will be treated as the hour value. For example, TIME(27,0,0) = TIME(3,0,0) = .125 or 3:00 AM.

**@param** {*} minute A number from 0 to 32767 representing the minute. Any value greater than 59 will be converted to hours and minutes. For example, TIME(0,750,0) = TIME(12,30,0) = .520833 or 12:30 PM.

**@param** {*} second A number from 0 to 32767 representing the second. Any value greater than 59 will be converted to hours, minutes, and seconds. For example, TIME(0,0,2000) = TIME(0,33,22) = .023148 or 12:33:20 AM

**@returns**

```ts
export function TIME(hour: any, minute: any, second: any): number | Error;;
```

---

### `TIMEVALUE`

Converts a time in the form of text to a serial number.

Category: Date and time

**@param** {*} time_text A text string that represents a time in any one of the Microsoft Excel time formats; for example, "6:45 PM" and "18:45" text strings within quotation marks that represent time.

**@returns**

```ts
export function TIMEVALUE(time_text: any): number | Error;;
```

---

### `TINV`

Returns the t-value of the Student's t-distribution as a function of the probability and the degrees of freedom.

Category: Statistical

**@param** {*} probability The probability associated with the Student's t-distribution.

**@param** {*} deg_freedom The number of degrees of freedom with which to characterize the distribution.

**@returns**

```ts
export function TINV(probability: any, deg_freedom: any): any;;
```

---

### `TODAY`

Returns the serial number of today's date.

Category: Date and time

**@returns**

```ts
export function TODAY(): number | Date;;
```

---

### `TRANSPOSE`

Returns the transpose of an array.

Category: Lookup and reference

**@param** {*} array An array or range of values on a worksheet that you want to transpose. The transpose of an array is created by using the first row of the array as the first column of the new array, the second row of the array as the second column of the new array, and so on. If you're not sure of how to enter an array formula, see Create an array formula.

**@returns**

```ts
export function TRANSPOSE(array: any): any;;
```

---

### `TREND`

Returns values along a linear trend.

Category: Statistical

**@param** {*} known_ys The set of y-values you already know in the relationship y = mx + b

**@param** {*} known_xs An optional set of x-values that you may already know in the relationship y = mx + b

**@param** {*} [new_xs] Optional. New x-values for which you want TREND to return corresponding y-values.

**@returns**

```ts
export function TREND(known_ys: any, known_xs: any, new_xs?: any): any[] | Error;;
```

---

### `TRIM`

Removes spaces from text.

Category: Text

**@param** {*} text The text from which you want spaces removed.

**@returns**

```ts
export function TRIM(text: any): any;;
```

---

### `TRIMMEAN`

Returns the mean of the interior of a data set.

Category: Statistical

**@param** {*} array The array or range of values to trim and average.

**@param** {*} percent The fractional number of data points to exclude from the calculation. For example, if percent = 0.2, 4 points are trimmed from a data set of 20 points (20 x 0.2): 2 from the top and 2 from the bottom of the set.

**@returns**

```ts
export function TRIMMEAN(range: any, percent: any): any;;
```

---

### `TRUE`

Returns the logical value TRUE.

Category: Logical

**@returns**

```ts
export function TRUE(): boolean;;
```

---

### `TRUNC`

Truncates a number to an integer.

Category: Math and trigonometry

**@param** {*} number The number you want to truncate.

**@param** {*} [num_digits] Optional. A number specifying the precision of the truncation. The default value for num_digits is 0 (zero).

**@returns**

```ts
export function TRUNC(number: any, num_digits?: any): any;;
```

---

### `TTEST`

Returns the probability associated with a Student's t-test.

Category: Statistical

**@param** {*} array1 The first data set.

**@param** {*} array2 The second data set.

**@returns**

```ts
export function TTEST(array1: any, array2: any): number | Error;;
```

---

### `TYPE`

Returns a number indicating the data type of a value.

Category: Information

**@param** {*} value Can be any Microsoft Excel value, such as a number, text, logical value, and so on.

**@returns**

```ts
export function TYPE(value: any): 1 | 2 | 4 | 16 | 64;;
```

---

### `UNICHAR`

Returns the character specified by the code number.

Category: Text

**@param** {*} number A number between 1 and 255 specifying which character you want. The character is from the character set used by your computer. Note: Excel for the web supports only CHAR(9), CHAR(10), CHAR(13), and CHAR(32) and above.

**@returns**

```ts
export function UNICHAR(number: any): string | Error;;
```

---

### `UNICODE`

Returns a numeric code for the first character in a text string.

Category: Text

**@param** {*} text The text for which you want the code of the first character.

**@returns**

```ts
export function UNICODE(text: any): any;;
```

---

### `UNIQUE`

Returns a list of unique values in a list or range.

Category: Lookup and reference

**@returns**

```ts
export function UNIQUE(...args: any[]): any[];;
```

---

### `UPPER`

Converts text to uppercase.

Category: Text

**@param** {*} text The text you want converted to uppercase. Text can be a reference or text string.

**@returns**

```ts
export function UPPER(text: any): any;;
```

---

### `VALUE`

Converts a text argument to a number.

Category: Text

**@param** {*} text The text enclosed in quotation marks or a reference to a value containing the text you want to convert.

**@returns**

```ts
export function VALUE(text: any): any;;
```

---

### `VARA`

Estimates variance based on a sample, including numbers, text, and logical values.

Category: Statistical

**@param** {*} args value1, value2, ... Value1 is required, subsequent values are optional. 1 to 255 value arguments corresponding to a sample of a population.

**@returns**

```ts
export function VARA(...args: any[]): number;;
```

---

### `VARP`

Calculates variance based on the entire population.

Category: Statistical

**@param** {*} args number1, number2, ... Number arguments 2 to 254 corresponding to a population.

**@returns**

```ts
export function VARP(...args: any[]): number | Error;;
```

---

### `VARPA`

Calculates variance based on the entire population, including numbers, text, and logical values.

Category: Statistical

**@param** {*} args value1, value2, ... Value1 is required, subsequent values are optional. 1 to 255 value arguments corresponding to a population.

**@returns**

```ts
export function VARPA(...args: any[]): number | Error;;
```

---

### `VARS`

Estimates variance based on a sample.

Category: Statistical

**@param** {*} args number1, number2, ... Number arguments 2 to 254 corresponding to a sample of a population.

**@returns**

```ts
export function VARS(...args: any[]): number;;
```

---

### `VLOOKUP`

Looks in the first column of an array and moves across the row to return the value of a value.

Category: Lookup and reference

**@param** {*} lookup_value The value to be found in the first row of the table. Lookup_value can be a value, a reference, or a text string.

**@param** {*} table_array A table of information in which data is looked up. Use a reference to a range or a range name.

**@param** {*} col_index_num The row number in table_array from which the matching value will be returned. A row_index_num of 1 returns the first row value in table_array, a row_index_num of 2 returns the second row value in table_array, and so on. If row_index_num is less than 1, HLOOKUP returns the #VALUE! error value; if row_index_num is greater than the number of rows on table_array, HLOOKUP returns the #REF! error value.

**@param** {*} [range_lookup] Optional. A logical value that specifies whether you want HLOOKUP to find an exact match or an approximate match. If TRUE or omitted, an approximate match is returned. In other words, if an exact match is not found, the next largest value that is less than lookup_value is returned. If FALSE, HLOOKUP will find an exact match. If one is not found, the error value #N/A is returned.

**@returns**

```ts
export function VLOOKUP(lookup_value: any, table_array: any, col_index_num: any, range_lookup?: any): Error;;
```

---

### `VSTACK`

Appends arrays vertically and in sequence to return a larger array.

Category: Lookup and reference

**@param** {*} array

**@param** {...*} otherArrays

**@returns**

```ts
export function VSTACK(array: any, ...otherArrays: any[]): any[];;
```

---

### `WEEKDAY`

Converts a serial number to a day of the week.

Category: Date and time

**@param** {*} serial_number A sequential number that represents the date of the day you are trying to find.

**@param** {*} [return_type] Optional. A number that determines the type of return value.

**@returns**

```ts
export function WEEKDAY(serial_number: any, return_type?: any): number | Error;;
```

---

### `WEEKNUM`

Converts a serial number to a number representing where the week falls numerically with a year.

Category: Date and time

**@param** {*} serial_number A date within the week.

**@param** {*} [return_type] Optional. A number that determines on which day the week begins. The default is 1.

**@returns**

```ts
export function WEEKNUM(serial_number: any, return_type?: any): number | Error;;
```

---

### `WEIBULLDIST`

Returns the Weibull distribution.

Category: Statistical

**@param** {*} x The value at which to evaluate the function.

**@param** {*} alpha A parameter to the distribution.

**@param** {*} beta A parameter to the distribution.

**@param** {*} cumulative Determines the form of the function.

**@returns**

```ts
export function WEIBULLDIST(x: any, alpha: any, beta: any, cumulative: any): number | Error;;
```

---

### `WORKDAY`

Returns the serial number of the date before or after a specified number of workdays.

Category: Date and time

**@param** {*} start_date A date that represents the start date.

**@param** {*} days The number of nonweekend and nonholiday days before or after start_date. A positive value for days yields a future date; a negative value yields a past date.

**@param** {*} [holidays] Optional. An optional list of one or more dates to exclude from the working calendar, such as state and federal holidays and floating holidays. The list can be either a range of values that contain the dates or an array constant of the serial numbers that represent the dates.

**@returns**

```ts
export function WORKDAY(start_date: any, days: any, holidays?: any): any;;
```

---

### `WORKDAYINTL`

Returns the serial number of the date before or after a specified number of workdays using parameters to indicate which and how many days are weekend days.

Category: Date and time

**@param** {*} start_date The start date, truncated to integer.

**@param** {*} days The number of workdays before or after the start_date. A positive value yields a future date; a negative value yields a past date; a zero value yields the start_date. Day-offset is truncated to an integer.

**@param** {*} [weekend] Optional. Indicates the days of the week that are weekend days and are not considered working days. Weekend is a weekend number or string that specifies when weekends occur. Weekend number values indicate the following weekend days:

**@param** {*} [holidays] Optional. An optional set of one or more dates that are to be excluded from the working day calendar. Holidays shall be a range of values that contain the dates, or an array constant of the serial values that represent those dates. The ordering of dates or serial values in holidays can be arbitrary.

**@returns**

```ts
export function WORKDAYINTL(start_date: any, days: any, weekend?: any, holidays?: any): any;;
```

---

### `XIRR`

Returns the internal rate of return for a schedule of cash flows that is not necessarily periodic.

Category: Financial

**@param** {*} values A series of cash flows that corresponds to a schedule of payments in dates. The first payment is optional and corresponds to a cost or payment that occurs at the beginning of the investment. If the first value is a cost or payment, it must be a negative value. All succeeding payments are discounted based on a 365-day year. The series of values must contain at least one positive and one negative value.

**@param** {*} dates A schedule of payment dates that corresponds to the cash flow payments. Dates may occur in any order. Dates should be entered by using the DATE function, or as results of other formulas or functions. For example, use DATE(2008,5,23) for the 23rd day of May, 2008. Problems can occur if dates are entered as text. .

**@param** {*} [guess] Optional. A number that you guess is close to the result of XIRR.

**@returns**

```ts
export function XIRR(values: any, dates: any, guess?: any): any;;
```

---

### `XNPV`

Returns the net present value for a schedule of cash flows that is not necessarily periodic.

Category: Financial

**@param** {*} rate The discount rate to apply to the cash flows.

**@param** {*} values A series of cash flows that corresponds to a schedule of payments in dates. The first payment is optional and corresponds to a cost or payment that occurs at the beginning of the investment. If the first value is a cost or payment, it must be a negative value. All succeeding payments are discounted based on a 365-day year. The series of values must contain at least one positive value and one negative value.

**@param** {*} dates A schedule of payment dates that corresponds to the cash flow payments. The first payment date indicates the beginning of the schedule of payments. All other dates must be later than this date, but they may occur in any order.

**@returns**

```ts
export function XNPV(rate: any, values: any, dates: any): number | Error;;
```

---

### `XOR`

Returns a logical exclusive OR of all arguments.

Category: Logical

**@param** {*} args logical1, logical2,… Logical 1 is required, subsequent logical values are optional. 1 to 254 conditions you want to test that can be either TRUE or FALSE, and can be logical values, arrays, or references.

**@returns**

```ts
export function XOR(...args: any[]): any;;
```

---

### `YEAR`

Converts a serial number to a year.

Category: Date and time

**@param** {*} serial_number The date of the year you want to find.

**@returns**

```ts
export function YEAR(serial_number: any): any;;
```

---

### `YEARFRAC`

Returns the year fraction representing the number of whole days between start_date and end_date.

Category: Date and time

**@param** {*} start_date A date that represents the start date.

**@param** {*} end_date A date that represents the end date.

**@param** {*} [basis] Optional. The type of day count basis to use.

**@returns**

```ts
export function YEARFRAC(start_date: any, end_date: any, basis?: any): number | Error;;
```

---

### `ZTEST`

Returns the one-tailed probability-value of a z-test.

Category: Statistical

**@param** {*} array The array or range of data against which to test x.

**@param** {*} x The value to test.

**@param** {*} [sigma] Optional. The population (known) standard deviation. If omitted, the sample standard deviation is used.

**@returns**

```ts
export function ZTEST(array: any, x: any, sigma?: any): number | Error;;
```

---

### `BETA`

```ts
export namespace BETA {

}
```

---

### `BINOM`

```ts
export namespace BINOM {

}
```

---

### `CHISQ`

```ts
export namespace CHISQ {

}
```

---

### `CONFIDENCE`

```ts
export namespace CONFIDENCE {

}
```

---

### `COVARIANCE`

```ts
export namespace COVARIANCE {

}
```

---

### `ERFCPRECISE`

```ts
ERFCPRECISE: any;
```

---

### `ERFPRECISE`

```ts
ERFPRECISE: any;
```

---

### `ERROR`

```ts
export namespace ERROR {

}
```

---

### `EXPON`

```ts
export namespace EXPON {

}
```

---

### `F`

```ts
export namespace F {

}
```

---

### `HYPGEOM`

```ts
export namespace HYPGEOM {

}
```

---

### `ISO`

```ts
export namespace ISO {

}
```

---

### `LOGNORM`

```ts
export namespace LOGNORM {

}
```

---

### `MODE`

```ts
export namespace MODE {

}
```

---

### `NEGBINOM`

```ts
export namespace NEGBINOM {

}
```

---

### `NORM`

```ts
export namespace NORM {

}
```

---

### `PERCENTILE`

```ts
export namespace PERCENTILE {

}
```

---

### `PERCENTRANK`

```ts
export namespace PERCENTRANK {

}
```

---

### `POISSON`

```ts
export namespace POISSON {

}
```

---

### `QUARTILE`

```ts
export namespace QUARTILE {

}
```

---

### `RANK`

```ts
export namespace RANK {

}
```

---

### `STDEV`

```ts
export namespace STDEV {

}
```

---

### `VAR`

```ts
export namespace VAR {

}
```

---

### `WEIBULL`

```ts
export namespace WEIBULL {

}
```

---

### `Z`

```ts
export namespace Z {

}
```

---

### `utils`

```ts
export namespace utils {

}
```

---

### `parseCellAddress`

Parse an A1 cell address into zero-based `[column, row]` coordinates.

**Example:**
```typescript
parseCellAddress('C5'); // [2, 4]
```

```ts
export function parseCellAddress(address: string): [number, number];
```

---

### `formatCellAddress`

Format zero-based coordinates as an A1 cell address.

**Example:**
```typescript
formatCellAddress(2, 4); // 'C5'
```

```ts
export function formatCellAddress(col: number, row: number): string;
```

---

### `isCellAddress`

Check whether a value is a valid A1 cell address.

**Example:**
```typescript
isCellAddress('A1'); // true
isCellAddress('Sales'); // false
```

```ts
export function isCellAddress(value: string): boolean;
```

---

### `parseA1Range`

Parse and normalize an A1 cell or range reference into zero-based coordinates.

**Example:**
```typescript
const range = parseA1Range('B2:C4');
console.log(range.start.row, range.end.col);
```

```ts
export function parseA1Range(ref: string): CellRange;
```

---

### `normalizeA1Ref`

Normalize an A1 reference by removing `$`, uppercasing, and sorting endpoints.

**Example:**
```typescript
normalizeA1Ref('$c$4:a1'); // 'A1:C4'
```

```ts
export function normalizeA1Ref(ref: string): string;
```

---

### `getRangeValues`

Read values from a physical A1 range using the provided rows and columns.

**Example:**
```typescript
const values = getRangeValues('A1:A2', rows, columns);
```

```ts
export function getRangeValues(
  ref: string,
  allSources: DataType[],
  columns: ColumnRegular[],
): unknown[];
```

---

### `toFormulaNamesConfig`

Convert shorthand formula-name input into a config object.

**Example:**
```typescript
toFormulaNamesConfig([{ name: 'Limit', kind: 'constant', value: 10 }]);
// { names: [...] }
```

```ts
export function toFormulaNamesConfig(input: FormulaNamesInput): FormulaNamesConfig;
```

---

### `cloneFormulaNameDefinition`

Create a defensive copy of a formula-name definition.

**Example:**
```typescript
const copy = cloneFormulaNameDefinition(definition);
```

```ts
export function cloneFormulaNameDefinition(definition: FormulaNameDefinition): FormulaNameDefinition;
```

---

### `cloneFormulaNamesConfig`

Create a defensive copy of a formula-name config or shorthand array.

**Example:**
```typescript
const config = cloneFormulaNamesConfig(grid.formulaNames);
```

```ts
export function cloneFormulaNamesConfig(input: FormulaNamesInput): FormulaNamesConfig;
```

---

### `normalizeFormulaNameDefinition`

Normalize a single formula-name definition.

Defaults scope/kind, applies the active sheet id for sheet-local names, and
normalizes range refs.

**Example:**
```typescript
normalizeFormulaNameDefinition({ name: 'Sales', ref: 'b2:b10' });
// { name: 'Sales', scope: 'workbook', kind: 'range', ref: 'B2:B10' }
```

```ts
export function normalizeFormulaNameDefinition(
  definition: FormulaNameDefinition,
  activeSheetId = DEFAULT_FORMULA_SHEET_ID,
): FormulaNameDefinition;
```

---

### `validateFormulaName`

Validate a formula-name definition against naming rules and existing names.

Invalid names include cell addresses, formula function names, and duplicates in
the same scope.

**Example:**
```typescript
const result = validateFormulaName(
  { name: 'Revenue', kind: 'range', ref: 'B2:B20' },
  existingNames,
  'Budget',
);
if (!result.valid) console.warn(result.errors);
```

```ts
export function validateFormulaName(
  definition: FormulaNameDefinition,
  existingNames: FormulaNameDefinition[] = [],
  activeSheetId = DEFAULT_FORMULA_SHEET_ID,
): FormulaNameValidationResult;
```

---

### `normalizeFormulaNames`

Normalize and validate a formula-name registry.

Valid names are returned in `names`; invalid definitions are returned in
`errors` and are not used for formula resolution.

**Example:**
```typescript
const registry = normalizeFormulaNames({
  activeSheetId: 'Budget',
  names: [
    { name: 'Target', kind: 'constant', value: 5000 },
    { name: 'Spend', scope: 'sheet', kind: 'range', ref: 'C2:C10' },
  ],
});
```

```ts
export function normalizeFormulaNames(input: FormulaNamesInput = undefined): FormulaNameRegistry;
```

---

### `resolveFormulaName`

Resolve a name using Excel-style precedence.

Sheet-local names for the active sheet win over workbook names. Use
`workbook!Name` or `global!Name` to force workbook lookup, or `SheetId!Name` to
resolve a specific sheet-local name.

**Example:**
```typescript
const local = resolveFormulaName('Revenue', {
  activeSheetId: 'Q4',
  names: [
    { name: 'Revenue', kind: 'range', ref: 'B2:B10' },
    { name: 'Revenue', scope: 'sheet', sheetId: 'Q4', kind: 'range', ref: 'C2:C10' },
  ],
});

const workbook = resolveFormulaName('workbook!Revenue', config);
```

```ts
export function resolveFormulaName(
  name: string,
  input: FormulaNamesInput,
): FormulaNameDefinition | undefined;
```

---

### `formulaNameToConfig`

Convert a normalized registry back to public config shape.

**Example:**
```typescript
grid.formulaNames = formulaNameToConfig(registry);
```

```ts
export function formulaNameToConfig(registry: FormulaNameRegistry): FormulaNamesConfig;
```

---

### `shiftFormulaNameRefs`

Shift range refs and formula refs in a list of names after a deterministic row
or column insertion/deletion.

**Example:**
```typescript
const nextNames = shiftFormulaNameRefs(names, {
  axis: 'row',
  startIndex: 2,
  insertedCount: 1,
});
```

```ts
export function shiftFormulaNameRefs(
  names: FormulaNameDefinition[],
  shift: FormulaRefShift,
): FormulaNameDefinition[];
```

---

### `shiftFormulaRefs`

Shift every A1 reference inside a formula string.

**Example:**
```typescript
shiftFormulaRefs('=SUM(A1:A3)', { axis: 'row', startIndex: 1, insertedCount: 1 });
// '=SUM(A1:A4)'
```

```ts
export function shiftFormulaRefs(formulaValue: string, shift: FormulaRefShift): string;
```

---

### `shiftA1Ref`

Shift a single A1 cell or range reference.

**Example:**
```typescript
shiftA1Ref('A2:A5', { axis: 'row', startIndex: 1, insertedCount: 1 });
// 'A3:A6'
```

```ts
export function shiftA1Ref(ref: string, shift: FormulaRefShift): string;
```

---

### `cloneFormulaNameRegistry`

```ts
export function cloneFormulaNameRegistry(registry: FormulaNameRegistry): FormulaNameRegistry;
```

---

### `DEFAULT_FORMULA_SHEET_ID`

Default sheet id used when no formula-name sheet context is supplied.

```ts
DEFAULT_FORMULA_SHEET_ID: string;
```

---

### `FORMULA_REF_ERROR`

Reference error marker returned when an A1 reference can no longer be resolved.

```ts
FORMULA_REF_ERROR: string;
```

---

### `CellAddress`

Zero-based cell coordinates parsed from an A1 address.

**Example:**
```typescript
const [col, row] = parseCellAddress('B3'); // [1, 2]
const address: CellAddress = { col, row };
```

```ts
interface CellAddress {
  col: number;
  row: number
}
```

---

### `CellRange`

Zero-based normalized cell range.

**Example:**
```typescript
const range = parseA1Range('B3:A1');
// range.start is A1, range.end is B3
```

```ts
interface CellRange {
  start: CellAddress;
  end: CellAddress
}
```

---

### `FormulaRefShift`

Describes a deterministic row or column insertion/deletion used to update refs.

**Example:**
```typescript
const shift: FormulaRefShift = {
  axis: 'row',
  startIndex: 1,
  insertedCount: 1,
};
```

```ts
interface FormulaRefShift {
  axis: 'row' | 'column';
  startIndex: number;
  removedCount?: number;
  insertedCount?: number;
  /** Sheet whose structure changed. Qualified refs to other sheets are preserved. */
    sheetId?: string
}
```

---

### `FormulaNameKind`

Supported formula-name value categories.

```ts
/** Supported formula-name value categories. */
export type FormulaNameKind = 'range' | 'constant' | 'formula';
```

---

### `FormulaNameScope`

Scope used when resolving a formula name.

```ts
/** Scope used when resolving a formula name. */
export type FormulaNameScope = 'workbook' | 'sheet';
```

---

### `FormulaEvaluationSheet`

A sheet available to formula evaluation.

```ts
interface FormulaEvaluationSheet {
  id: string;
  rows: DataType[];
  columns: ColumnRegular[]
}
```

---

### `FormulaEvaluationWorkbook`

Multi-sheet context used by the low-level formula evaluator.

```ts
interface FormulaEvaluationWorkbook {
  currentSheetId: string;
  sheets: readonly FormulaEvaluationSheet[];
  /** @internal Shared memoization for one workbook calculation session. */
    cache?: Map<string, unknown>;
  /** @internal Shared recursion guard for one workbook calculation session. */
    activeCells?: Set<string>
}
```

---

### `FormulaGridWorkbookConfig`

Workbook configuration attached to a mounted grid.

```ts
interface FormulaGridWorkbookConfig {
  sheetId: string;
  rowIdProp: string;
  externalSheets?: readonly FormulaWorkbookSheet[]
}
```

---

### `FormulaWorkbookCellLocation`

Stable location of a calculated workbook cell.

```ts
interface FormulaWorkbookCellLocation {
  sheetId: string;
  rowId: string | number;
  rowIndex: number;
  colIndex: number;
  prop: ColumnProp;
  address: string
}
```

---

### `FormulaWorkbookError` (Extended from `index.ts`)

Cell-level calculation error that does not abort independent formulas.

```ts
interface FormulaWorkbookError {
  code: string;
  message: string;
  formula: string
}
```

---

### `FormulaWorkbookInput`

Input accepted by the headless workbook calculator.

```ts
interface FormulaWorkbookInput {
  sheets: readonly FormulaWorkbookSheet[];
  names?: readonly FormulaNameDefinition[];
  previousValues?: FormulaWorkbookValues
}
```

---

### `FormulaWorkbookPatch` (Extended from `index.ts`)

A calculated value for the host application to persist.

```ts
interface FormulaWorkbookPatch {
  formula: string;
  previousValue?: unknown;
  value: unknown;
  error?: string
}
```

---

### `FormulaWorkbookResult`

Result of a complete workbook recalculation.

```ts
interface FormulaWorkbookResult {
  patches: FormulaWorkbookPatch[];
  values: FormulaWorkbookValues;
  errors: FormulaWorkbookError[]
}
```

---

### `FormulaWorkbookSheet` (Extended from `index.ts`)

A persisted-data sheet supplied to the headless workbook calculator.

```ts
interface FormulaWorkbookSheet {
  rowIdProp: string
}
```

---

### `FormulaWorkbookValues`

Previously calculated or newly calculated values, keyed by sheet, row id, and column prop.

```ts
/** Previously calculated or newly calculated values, keyed by sheet, row id, and column prop. */
export type FormulaWorkbookValues = Record<string, Record<string, Record<string, unknown>>>;
```

---

### `FormulaNamesConfig`

Formula-name registry configuration for a grid.

Set this on `grid.formulaNames` or pass it through `additionalData.formulaNames`
for legacy integrations.

**Example:**
```typescript
grid.formulaNames = {
  activeSheetId: 'Q4',
  autoUpdateRefs: true,
  names: [
    { name: 'Revenue', kind: 'range', ref: 'B2:B50' },
    { name: 'Target', kind: 'constant', value: 100000 },
  ],
};
```

```ts
interface FormulaNamesConfig {
  names?: FormulaNameDefinition[];
  activeSheetId?: string;
  /**
     * Optional stable row key used when an application replaces source rows with
     * immutable clones. Normal grid operations preserve identity automatically.
     */
    rowIdProp?: string;
  autoUpdateRefs?: boolean
}
```

---

### `FormulaNameValidationResult`

Result returned by name validation.

**Example:**
```typescript
const result = validateFormulaName({ name: 'A1', kind: 'constant', value: 1 });
if (!result.valid) {
  console.warn(result.errors);
}
```

```ts
interface FormulaNameValidationResult {
  valid: boolean;
  errors: string[];
  definition?: FormulaNameDefinition
}
```

---

### `FormulaNameRegistry`

Normalized formula-name registry used by the formula runtime and plugin APIs.

**Example:**
```typescript
const registry = normalizeFormulaNames({
  activeSheetId: 'Budget',
  names: [{ name: 'Limit', kind: 'constant', value: 5000 }],
});
```

```ts
interface FormulaNameRegistry {
  names: FormulaNameDefinition[];
  errors: FormulaNameValidationResult[];
  activeSheetId: string;
  rowIdProp?: string;
  autoUpdateRefs: boolean;
  /** @internal Lookup index used by the formula render hot path. */
    workbookNames?: Record<string, FormulaNameDefinition>;
  /** @internal Lookup index used by the formula render hot path. */
    sheetNames?: Record<string, Record<string, FormulaNameDefinition>>
}
```

---

### `FormulaEvaluationOptions` (Extended from `index.ts`)

Optional context passed to formula evaluation.

**Example:**
```typescript
evaluateRawValuesFormula('=Revenue > Target', rows, columns, {
  names,
  activeSheetId: 'Budget',
  currentCell: { rowIndex: 0, colIndex: 1, prop: 'amount', type: 'rgRow', value: 1200, model: rows[0] },
});
```

```ts
interface FormulaEvaluationOptions {
  /**
     * Pre-normalized registry for hot paths that evaluate many formulas.
     *
     * Most integrations should pass `names`; plugins that already own a normalized
     * registry can pass this field to avoid repeated validation/index creation.
     *
     * @example
     * ```ts
     * evaluateRawValuesFormula('=Revenue > Target', rows, columns, {
     *   registry: normalizeFormulaNames({ names }),
     * });
     * ```
     */
    registry?: FormulaNameRegistry;
  currentCell?: Pick<CellTemplateProp, 'rowIndex' | 'colIndex' | 'prop' | 'type' | 'value' | 'model'>;
  /** First zero-based A1 row occupied by pinned-bottom source models. */
    pinnedBottomStartIndex?: number;
  /** @internal Pinned-bottom models when their authored A1 rows are not contiguous. */
    pinnedBottomRows?: readonly DataType[];
  /** Optional multi-sheet context for qualified A1 references. */
    workbook?: FormulaEvaluationWorkbook
}
```

---

### `FormulaEvaluationContext` (Extended from `index.ts`)

Complete formula-evaluation context with grid data and columns.

**Example:**
```typescript
const context: FormulaEvaluationContext = {
  allSources: rows,
  columns,
  names: [{ name: 'Totals', kind: 'range', ref: 'B2:B10' }],
};
```

```ts
interface FormulaEvaluationContext {
  allSources: DataType[];
  columns: ColumnRegular[]
}
```

---

### `AsyncFormulaFunctionContext`

Cell and workbook identity supplied to an application-defined async formula function.

```ts
interface AsyncFormulaFunctionContext {
  readonly name: string;
  readonly formula: string;
  readonly rawArgs: readonly string[];
  readonly sheetId: string;
  readonly rowId?: string | number;
  readonly rowIndex: number;
  readonly colIndex: number;
  readonly rowType: DimensionRows;
  readonly model: T;
  readonly column: ColumnRegular;
  /** Aborted when the formula becomes obsolete, is invalidated, or the plugin is destroyed. */
    readonly signal: AbortSignal
}
```

---

### `AsyncFormulaFunctionHandler`

Application callback used by a registered async formula function.

```ts
/** Application callback used by a registered async formula function. */
export type AsyncFormulaFunctionHandler = (
  args: readonly unknown[],
  context: AsyncFormulaFunctionContext,
) => unknown | PromiseLike<unknown>;
```

---

### `AsyncFormulaFunctionRegistration`

Registration accepted by `FormulaPlugin.registerAsyncFormulaFunction`.

```ts
interface AsyncFormulaFunctionRegistration {
  /** Formula function name. Matching is case-insensitive. */
    name: string;
  handler: AsyncFormulaFunctionHandler;
  /** Value rendered until the handler settles. Defaults to `#LOADING`. */
    loadingValue?: unknown;
  /** Value rendered after rejection. Defaults to `#ERROR`. */
    errorValue?: unknown;
  /** Derive a rendered rejection value from the thrown error. Takes precedence over `errorValue`. */
    mapError?: (error: unknown, context: AsyncFormulaFunctionContext) => unknown
}
```

---

### `AsyncFormulaCellStatus`

```ts
export type AsyncFormulaCellStatus = 'pending' | 'resolved' | 'rejected';
```

---

### `AsyncFormulaStateChangeEventDetail`

Detail dispatched through `asyncformulastatechange`.

```ts
interface AsyncFormulaStateChangeEventDetail {
  readonly name: string;
  readonly formula: string;
  readonly sheetId: string;
  readonly rowId?: string | number;
  readonly rowIndex: number;
  readonly colIndex: number;
  readonly prop: ColumnRegular['prop'];
  readonly status: AsyncFormulaCellStatus;
  readonly value?: unknown;
  readonly error?: unknown
}
```

---

### `NamedRangeDropdownContext` (Extended from `index.ts`)

Context used when converting a named range into dropdown options.

**Example:**
```typescript
const dropdown = createNamedRangeDropdown('Statuses', {
  allSources: rows,
  columns,
  names,
  label: value => String(value).toUpperCase(),
});
```

```ts
interface NamedRangeDropdownContext {
  label?: (value: unknown) => string
}
```

---

### `FormulaConditionalCellPropertiesContext` (Extended from `index.ts`)

Context used by formula-driven conditional cell properties.

**Example:**
```typescript
const cellProperties = createFormulaConditionalCellProperties(
  '=cellvalue > Target',
  { class: 'over-target' },
  { allSources: rows, columns, names },
);
```

```ts
interface FormulaConditionalCellPropertiesContext {
  getFormula?: (params: CellTemplateProp) => string
}
```

---

### `FormulaConditionalCellProperties`

Properties applied when a conditional formula evaluates to truthy.

**Example:**
```typescript
const props: FormulaConditionalCellProperties = ({ value }) =>
  Number(value) > 100 ? { class: 'high-value' } : undefined;
```

```ts
/**
 * Properties applied when a conditional formula evaluates to truthy.
 *
 * @example
 * ```ts
 * const props: FormulaConditionalCellProperties = ({ value }) =>
 *   Number(value) > 100 ? { class: 'high-value' } : undefined;
 * ```
 */
export type FormulaConditionalCellProperties = CellProps | ((params: CellTemplateProp) => CellProps | undefined);
```

---

### `NamedRangeDropdownOptions`

Dropdown overrides merged with the generated named-range dropdown source.

**Example:**
```typescript
const options: NamedRangeDropdownOptions = { placeholder: 'Select status' };
```

```ts
/**
 * Dropdown overrides merged with the generated named-range dropdown source.
 *
 * @example
 * ```ts
 * const options: NamedRangeDropdownOptions = { placeholder: 'Select status' };
 * ```
 */
export type NamedRangeDropdownOptions = Partial<DropdownColumnProps>;
```

---

### `FormulaNameManagerOptions`

Options for the bundled Formula Name Manager panel.

**Example:**
```typescript
defineFormulaNameManager(container, grid, { pageSize: 20 });
```

```ts
/**
 * Options for the bundled Formula Name Manager panel.
 *
 * @example
 * ```ts
 * defineFormulaNameManager(container, grid, { pageSize: 20 });
 * ```
 */
export type FormulaNameManagerOptions = {
  pageSize?: number;
};
```

---

### `FormulaBarState`

Active cell state exposed by the Formula Bar runtime.

**Example:**
```typescript
const state = formulaBarPlugin.getFormulaBarState();
if (!state.disabled) {
  console.log(state.value);
}
```

```ts
interface FormulaBarState {
  value: string;
  /** Typed source value. `value` remains the compatibility text representation. */
    rawValue?: unknown;
  /** Semantic control selected for the focused cell. */
    editorKind?: FormulaBarEditorKind;
  disabled: boolean;
  invalid?: boolean;
  validationMessage?: string;
  rowIndex?: number;
  colIndex?: number;
  prop?: ColumnRegular['prop'];
  rowType?: DimensionRows;
  colType?: DimensionCols
}
```

---

### `FormulaBarEditorKind`

Built-in and application-defined Formula Bar control identifiers.

```ts
/** Built-in and application-defined Formula Bar control identifiers. */
export type FormulaBarEditorKind =
  | 'formula'
  | 'text'
  | 'number'
  | 'percent'
  | 'dropdown'
  | 'boolean'
  | 'date'
  | 'datetime'
  | 'time'
  | 'unsupported'
  | `custom:${string}`;
```

---

### `FormulaBarControlContext`

Cell context used to select and render an adaptive Formula Bar control.

```ts
interface FormulaBarControlContext {
  readonly state: FormulaBarState;
  readonly rawValue: unknown;
  readonly column: ColumnRegular;
  readonly model: DataType;
  readonly format?: DataGridCellFormat;
  readonly commit: (value: unknown) => Promise<FormulaBarState>;
  readonly openCellEditor: () => Promise<void>
}
```

---

### `FormulaBarControlController`

Mounted application control returned by a Formula Bar adapter.

```ts
interface FormulaBarControlController {
  update(context: FormulaBarControlContext): void;
  focus?(): void;
  destroy(): void
}
```

---

### `FormulaBarControlAdapter`

Application extension point for custom Formula Bar value controls.

```ts
interface FormulaBarControlAdapter {
  readonly id: string;
  matches(context: Omit<FormulaBarControlContext, 'commit' | 'openCellEditor'>): boolean;
  mount(host: HTMLElement, context: FormulaBarControlContext): FormulaBarControlController
}
```

---

### `FormulaBarEditTarget`

Cell target actively edited through a configured formula bar input.

```ts
interface FormulaBarEditTarget {
  rowIndex: number;
  colIndex: number;
  rowType: DimensionRows;
  colType: DimensionCols;
  prop?: ColumnRegular['prop']
}
```

---

### `FormulaBarRuntime`

Runtime API exposed by `FormulaBarPlugin`.

**Example:**
```typescript
await formulaBar.setFormulaBarValue('=A1+TargetPrice');
```

```ts
interface FormulaBarRuntime {
  getFormulaBarState(): FormulaBarState;
  setFormulaBarValue(value: unknown, target?: FormulaBarState): Promise<FormulaBarState>
}
```

---

### `FormulaBarConfig`

Formula bar configuration observed by `FormulaBarPlugin`.

**Example:**
```typescript
grid.formulaBar = { host, badgeEl: badge, showCellBadge: true };
```

```ts
interface FormulaBarConfig {
  /** Legacy text-only Formula Bar input. Ignored when `host` is supplied. */
    el?: HTMLInputElement | null;
  /** Host where FormulaBarPlugin renders its adaptive editing surface. */
    host?: HTMLElement | null;
  /** Ordered application controls checked before built-in semantic controls. */
    adapters?: readonly FormulaBarControlAdapter[];
  badgeEl?: HTMLElement | null;
  showCellBadge?: boolean
}
```

---

### `FormulaDependencyHighlightCell` (Extended from `index.ts`)

Render-partitioned formula dependency highlight cell.

**Example:**
```typescript
const cell: FormulaDependencyHighlightCell = {
  rowIndex: 0,
  colIndex: 1,
  rowType: 'rgRow',
  colType: 'rgCol',
};
```

```ts
interface FormulaDependencyHighlightCell {
  rowType: DimensionRows;
  colType: DimensionCols;
  color?: string
}
```

---

### `FormulaDependencyHighlightState`

Runtime state exposed by `FormulaDependencyHighlightPlugin`.

**Example:**
```typescript
const state = plugin.getFormulaDependencyHighlightState();
```

```ts
interface FormulaDependencyHighlightState {
  activeCell?: FormulaDependencyHighlightCell;
  dependencies: FormulaDependencyHighlightCell[]
}
```

---

### `FormulaDependencyReferenceOptions` (Extended from `index.ts`)

Options used by the formula dependency resolver.

**Example:**
```typescript
collectFormulaDependencyCells('=SUM(Revenue)', {
  names: [{ name: 'Revenue', kind: 'range', ref: 'A1:A10' }],
  includeNamedRanges: true,
});
```

```ts
interface FormulaDependencyReferenceOptions {
  registry?: FormulaNameRegistry;
  includeNamedRanges?: boolean;
  /** Optional physical source bounds used to clip ranges before expansion. */
    bounds?: {
      readonly rowCount: number;
      readonly colCount: number;
    };
  /** Hard cap across all expanded references. @default 10000 */
    maxCells?: number
}
```

---

### `FormulaDependencyHighlightConfig`

Formula dependency highlight configuration observed by
`FormulaDependencyHighlightPlugin`.

**Example:**
```typescript
grid.formulaDependencyHighlight = {
  highlightOnFocus: true,
  dependencyClass: 'formula-source-cell',
  formulaCellClass: 'formula-active-cell',
  dependencyColors: ['#2563eb', '#dc2626'],
};
```

```ts
interface FormulaDependencyHighlightConfig {
  enabled?: boolean;
  /**
     * Also show dependency highlights when a formula cell is only focused.
     * By default highlights are shown only while the formula cell is edited.
     * @default false
     */
    highlightOnFocus?: boolean;
  dependencyClass?: string;
  formulaCellClass?: string;
  /** Palette cycled per reference token; every cell in one range shares a color. */
    dependencyColors?: string[];
  includeNamedRanges?: boolean
}
```

---

### `FormulaCellPropertiesFactory`

Creates RevoGrid cell properties from a formula and a matching style/object.

**Example:**
```typescript
const factory: FormulaCellPropertiesFactory = createFormulaConditionalCellProperties;
column.cellProperties = factory('=cellvalue >= Target', { class: 'hit-target' }, context);
```

```ts
/**
 * Creates RevoGrid cell properties from a formula and a matching style/object.
 *
 * @example
 * ```ts
 * const factory: FormulaCellPropertiesFactory = createFormulaConditionalCellProperties;
 * column.cellProperties = factory('=cellvalue >= Target', { class: 'hit-target' }, context);
 * ```
 */
export type FormulaCellPropertiesFactory = (
  formula: string,
  matchProps: FormulaConditionalCellProperties,
  context: FormulaConditionalCellPropertiesContext,
) => PropertiesFunc;
```

---

### `defineFormulaNameManager`

Render the bundled Formula Name Manager panel into an element.

The target grid must have `NamedRangesPlugin` installed so the panel can read,
validate, mutate, and jump to formula names.

**Example:**
```typescript
import {
  FormulaPlugin,
  NamedRangesPlugin,
  defineFormulaNameManager,
} from '@revolist/revogrid-pro';

grid.plugins = [NamedRangesPlugin, FormulaPlugin];
defineFormulaNameManager(document.querySelector('#name-manager')!, grid, {
  pageSize: 25,
});
```

```ts
export function defineFormulaNameManager(
  el: HTMLElement,
  grid: HTMLRevoGridElement,
  options?: FormulaNameManagerOptions,
): void;
```

---

### `FormulaBarPlugin`

Runtime plugin that exposes the focused cell's raw source value to an external
formula bar and writes edited values back through RevoGrid. Formula bar edit
target changes are emitted as `formulabareditchange` for companion plugins.

**Example:**
```typescript
grid.plugins = [FormulaBarPlugin, NamedRangesPlugin, FormulaPlugin];
grid.formulaBar = { host: document.querySelector('#formula-bar')! };
```

```ts
class FormulaBarPlugin {
  destroy();

  getFormulaBarState(): FormulaBarState;

  async setFormulaBarValue(value: unknown, target = this.state): Promise<FormulaBarState>;

  setFormulaBarEditTarget(target: FormulaBarState | undefined);

  setFormulaBarFormulaMode(enabled: boolean);

  getFormulaBarResolvedControl(state = this.state): FormulaBarResolvedControl | undefined;

  getFormulaBarControlContext(state = this.state): FormulaBarControlContext | undefined;
}
```

---

### `FormulaDependencyHighlightPlugin`

Highlight direct formula precedent cells while a formula cell is edited or
its configured formula bar is focused. Range references share one color and
render as a single outlined region. Set `highlightOnFocus` to also highlight
the currently focused formula cell.

**Example:**
```typescript
grid.plugins = [FormulaDependencyHighlightPlugin, FormulaPlugin];
grid.formulaDependencyHighlight = {
  includeNamedRanges: true,
  highlightOnFocus: true,
};
```

```ts
class FormulaDependencyHighlightPlugin {
  destroy();

  getFormulaDependencyHighlightState(): FormulaDependencyHighlightState;
}
```

---

### `collectFormulaDependencyCells`

```ts
export function collectFormulaDependencyCells(
  formulaValue: string,
  options: FormulaDependencyReferenceOptions = {},
): FormulaDependencyCell[];
```

---

### `calculateFormulaWorkbook`

Recalculate every formula in a multi-sheet workbook without mutating source rows.

The caller owns loading data, invoking this function after changes, and
persisting the returned patches. Pass the previous `values` result to suppress
patches whose calculated value did not change.

```ts
export function calculateFormulaWorkbook(input: FormulaWorkbookInput): FormulaWorkbookResult;
```

---

### `createFormulaExcelExportCellProperties`

Create Excel export cell properties that export raw formula strings as
workbook formulas instead of their evaluated grid values.

```ts
export function createFormulaExcelExportCellProperties(
  options: FormulaExcelExportCellPropertiesOptions = {},
): ExcelExportCellProperties;
```

---

### `createFormulaExcelExportTransformer`

Create a final export-context transformer that preserves raw grid formulas.

Export context transformers run after grouped headers and Data Grid Formatting,
so the helper can translate grid A1 rows to their final worksheet coordinates
while retaining native number formats and appearance styles.

```ts
export function createFormulaExcelExportTransformer(
  options: FormulaExcelExportTransformerOptions = {},
): ExcelExportContextTransformer;
```

---

### `FormulaExcelExportCellPropertiesOptions`

```ts
export type FormulaExcelExportCellPropertiesOptions = {
  /**
   * Include the already prepared export value as `result` for providers that
   * support cached formula results.
   */
  includeEvaluatedResult?: boolean;
};
```

---

### `FormulaExcelExportTransformerOptions` (Extended from `index.ts`)

```ts
export type FormulaExcelExportTransformerOptions = FormulaExcelExportCellPropertiesOptions & {
  /** Expand formula names to plain Excel expressions for providers without defined-name support. */
  expandFormulaNames?: boolean;
};
```

---

### `createFormulaAutoFillTransformer`

Create the Formula-owned post-processor used by the shared AutoFill pipeline.

```ts
export function createFormulaAutoFillTransformer(
  coordinates: FormulaCoordinateResolver,
  providers: PluginProviders,
): AutoFillResultTransformer;
```

---

### `transformFormulaAutoFillMatrix`

**@internal** Pure matrix transformation entry point used by focused tests.

```ts
export function transformFormulaAutoFillMatrix(
  matrix: any[][],
  context: AutoFillResultTransformerContext,
  resolveCoordinates: (location: AutoFillCellLocation) => FormulaCellCoordinates | undefined,
): any[][];
```

---

### `translateFormulaReferences`

Translate supported A1 refs by a copied formula cell's column/row delta.

```ts
export function translateFormulaReferences(
  formulaValue: string,
  columnDelta: number,
  rowDelta: number,
): string;
```

---

### `ASYNC_FORMULA_LOADING`

```ts
ASYNC_FORMULA_LOADING: string;
```

---

### `DEFAULT_ASYNC_FORMULA_SHEET_ID`

```ts
DEFAULT_ASYNC_FORMULA_SHEET_ID: string;
```

---

### `AsyncFormulaCall`

```ts
export type AsyncFormulaCall = {
  readonly name: string;
  readonly rawArgs: readonly string[];
};
```

---

### `AsyncFormulaRuntime`

Owns async formula registration, request state, caching, and cancellation.

```ts
class AsyncFormulaRuntime {
  register(registration: AsyncFormulaFunctionRegistration): () => void;

  unregister(name: string): boolean;

  invalidate(name?: string): void;

  reset(): void;

  dispose(): void;

  match(formulaValue: string): {
    call: AsyncFormulaCall;
    registration: AsyncFormulaFunctionRegistration;
  } | undefined;

  invalidateCell(identity: AsyncFormulaCellIdentity): boolean;

  resolve(options: AsyncFormulaResolveOptions): unknown;
}
```

---

### `bindAdaptiveFormulaBarHost`

```ts
export function bindAdaptiveFormulaBarHost(
  host: HTMLElement,
  grid: HTMLRevoGridElement,
  runtime: AdaptiveFormulaBarRuntime,
  options: Omit<FormulaBarConfig, 'host' | 'el'>,
): () => void;
```

---

### `preserveGridFocusOnFormulaBarInteraction`

```ts
export function preserveGridFocusOnFormulaBarInteraction(
  event: MouseEvent | TouchEvent,
);
```

---

### `AdaptiveFormulaBarRuntime` (Extended from `formula-bar-adaptive.ts`)

```ts
interface AdaptiveFormulaBarRuntime {
  getFormulaBarControlContext(state?: FormulaBarState): FormulaBarControlContext | undefined;
  getFormulaBarResolvedControl(state?: FormulaBarState): FormulaBarResolvedControl | undefined;
  setFormulaBarFormulaMode(enabled: boolean): void;
  setFormulaBarEditTarget(target: FormulaBarState | undefined): void
}
```

---

### `resolveFormulaBarControl`

```ts
export function resolveFormulaBarControl(
  options: ResolveFormulaBarControlOptions,
): FormulaBarResolvedControl;
```

---

### `formatFormulaBarControlValue`

```ts
export function formatFormulaBarControlValue(
  kind: FormulaBarEditorKind,
  value: unknown,
): string;
```

---

### `parseFormulaBarControlValue`

```ts
export function parseFormulaBarControlValue(
  kind: FormulaBarEditorKind,
  draft: string,
  previousValue: unknown,
): { valid: true; value: unknown } | { valid: false; message: string };
```

---

### `FormulaBarResolvedControl`

```ts
interface FormulaBarResolvedControl {
  readonly kind: FormulaBarEditorKind;
  readonly adapter?: FormulaBarControlAdapter;
  readonly dropdown?: DropdownColumnProps;
  readonly displayValue?: string;
  readonly format?: DataGridCellFormat
}
```

---

### `ResolveFormulaBarControlOptions`

```ts
interface ResolveFormulaBarControlOptions {
  readonly state: FormulaBarState;
  readonly rawValue: unknown;
  readonly model: DataType;
  readonly column: ColumnRegular;
  readonly rowType: DimensionRows;
  readonly providers: PluginProviders;
  readonly formulaMode?: boolean;
  readonly adapters?: readonly FormulaBarControlAdapter[];
  readonly additionalData?: unknown
}
```

---

### `applyFormulaAwareFilterTrim`

```ts
export function applyFormulaAwareFilterTrim(
  event: Event,
  providers: PluginProviders,
  resolveFormulaValue: FormulaFilterValueResolver,
  referenceColumns: ColumnRegular[] = providers.column.getColumns('all'),
);
```

---

### `FormulaFilterValueResolver`

```ts
export type FormulaFilterValueResolver = (context: {
  model: DataType;
  column: ColumnRegular;
  rowType: 'rgRow';
  rowIndex: number;
  colIndex: number;
  value: unknown;
}) => unknown;
```

---

### `createFormulaCellKey`

Collision-safe identity for formula memoization and recursion guards.

```ts
export function createFormulaCellKey(
  sheetId: string,
  rowIndex: number,
  colIndex: number,
): string;
```

---

### `getFormulaReferenceColumns`

Return formula-addressable columns in the application's authored leaf order.
Pin partitions affect rendering only and therefore never change A1 identity.

```ts
export function getFormulaReferenceColumns(
  revogrid: HTMLRevoGridElement,
  providers: PluginProviders,
): ColumnRegular[];
```

---

### `getFormulaColumnIndex`

Resolve a rendered or provider column to its authored A1 column index.

```ts
export function getFormulaColumnIndex(
  columns: readonly ColumnRegular[],
  column: ColumnRegular,
  suggestedIndex?: number,
): number;
```

---

### `getFormulaColumnLocation`

Map an authored A1 column back to its current rendered pin partition.

```ts
export function getFormulaColumnLocation(
  columns: readonly ColumnRegular[],
  referenceIndex: number,
  providers: PluginProviders,
): FormulaColumnLocation | undefined;
```

---

### `createFormulaColumnIndexMap`

Map indexes between two column projections while preserving duplicate props.

```ts
export function createFormulaColumnIndexMap(
  sourceColumns: readonly ColumnRegular[],
  targetColumns: readonly ColumnRegular[],
): Map<number, number>;
```

---

### `FormulaColumnLocation`

```ts
export type FormulaColumnLocation = {
  column: ColumnRegular;
  colType: DimensionCols;
  sourceIndex: number;
  colIndex: number;
};
```

---

### `getFormulaCoordinateResolver`

```ts
export function getFormulaCoordinateResolver(
  revogrid: HTMLRevoGridElement,
  providers: PluginProviders,
): FormulaCoordinateResolver;
```

---

### `FormulaRowLocation`

```ts
export type FormulaRowLocation = {
  model: DataType;
  rowType: DimensionRows;
  sourceIndex: number;
  rowIndex: number;
};
```

---

### `FormulaRowsChange`

```ts
export type FormulaRowsChange = {
  previousRows: DataType[];
  rows: DataType[];
};
```

---

### `FormulaCoordinateResolver`

Owns the grid-specific A1 coordinate space used by the formula subsystem.
Provider projections are consulted only when mapping an authored coordinate
back to a rendered viewport.

```ts
class FormulaCoordinateResolver {
  getReferenceColumns(): ColumnRegular[];

  getReferenceRows(): DataType[];

  /** @internal Configure the optional immutable-row identity compatibility key. */
  setRowIdProp(rowIdProp?: string): void;

  getColumnIndex(column: ColumnRegular, suggestedIndex?: number): number;

  getColumnLocation(referenceIndex: number): FormulaColumnLocation | undefined;

  getRowIndex(
    model: DataType,
    rowType?: DimensionRows,
    suggestedIndex?: number,
  ): number;

  getRowLocation(referenceIndex: number): FormulaRowLocation | undefined;

  getPinnedBottomRows(): DataType[];

  subscribeRows(listener: (change: FormulaRowsChange) => void): () => void;

  /** @internal Used by projection consumers to avoid intermediate pin state. */
  isRowPartitionMoveActive(): boolean;

  acquire(): this;

  release(): void;
}
```

---

### `applyFormulaRenderResult`

Applies a calculated value and the shared accessible pending presentation.

```ts
export function applyFormulaRenderResult(
  schemaModel: CellTemplateProp,
  result: unknown,
  missingSheetIds: readonly string[],
): void;
```

---

### `FormulaSortingConfigChangedEvent`

```ts
export type FormulaSortingConfigChangedEvent = CustomEvent<{
  columns?: Array<{
    prop: ColumnProp;
    order?: 'asc' | 'desc';
    cellCompare?: CellCompareFunc;
  }>;
}>;
```

---

### `FormulaSortingRuntime`

Enhances core sorting configuration with calculated formula values.

```ts
class FormulaSortingRuntime {
  enhance(event: FormulaSortingConfigChangedEvent): void;
}
```

---

### `collectFormulaDependencyReferences`

```ts
export function collectFormulaDependencyReferences(
  formulaValue: string,
  options: FormulaDependencyReferenceOptions = {},
): FormulaDependencyReference[];
```

---

### `FormulaDependencyReference`

```ts
export type FormulaDependencyReference = {
  range: CellRange;
  cells: FormulaDependencyCell[];
};
```

---

### `getGridFormulaNamesOptions`

```ts
export function getGridFormulaNamesOptions(
  revogrid: HTMLRevoGridElement,
  providers: PluginProviders,
): FormulaNamesConfig & { registry?: FormulaNameRegistry };
```

---

### `FormulaNamesRuntime`

```ts
interface FormulaNamesRuntime {
  getFormulaNamesConfig(): FormulaNamesConfig;
  getFormulaNameRegistryForEvaluation?(): FormulaNameRegistry
}
```

---

### `sameScopedName`

```ts
export function sameScopedName(
  left: FormulaNameDefinition,
  right: FormulaNameDefinition,
  activeSheetId: string,
);
```

---

### `sameRow`

```ts
export function sameRow(
  left: DataType,
  right: DataType,
  rowIdProp?: string,
): boolean;
```

---

### `detectIndexSplice`

```ts
export function detectIndexSplice<T>(
  previous: T[],
  next: T[],
  isSame: (left: T, right: T) => boolean,
): { startIndex: number; removedCount: number; insertedCount: number } | undefined;
```

---

### `shiftSourceFormulaRefs`

```ts
export function shiftSourceFormulaRefs(
  source: DataType[],
  columns: ColumnRegular[],
  shift: FormulaRefShift,
  shouldShiftRow: (row: DataType, rowIndex: number) => boolean = () => true,
);
```

---

### `FormulaGridWorkbookRuntime`

Owns the mounted grid's workbook snapshot and workbook-only operations.

```ts
class FormulaGridWorkbookRuntime {
  set(config: FormulaGridWorkbookConfig | undefined): void;

  upsertSheet(sheet: FormulaWorkbookSheet): void;

  updateSheetCell(
    sheetId: string,
    rowId: string | number,
    prop: ColumnProp,
    value: unknown,
  ): void;

  removeSheet(sheetId: string): void;

  createEvaluation(rows: DataType[], columns: ColumnRegular[]): FormulaEvaluationWorkbook | undefined;

  getRowId(model: DataType): string | number | undefined;

  getMissingSheetIds(value: unknown, context: MissingSheetContext): string[];
}
```

---

# Gantt API

URL: https://pro.rv-grid.com/api/gantt/
Source: src/content/docs/api/gantt.md
Description: Public API reference for RevoGrid Gantt plugins, project data, scheduling, visuals, events, columns, and extensions.
Surface: gantt

The Gantt API reference is generated from symbols reachable through the standalone Gantt package barrel. Test files, internal modules, private/protected class members, and declarations tagged `@internal` are excluded.

## API Areas

- [Plugin And Configuration](/api/gantt/plugin/) — 74 symbols
- [Project Data Model](/api/gantt/data-model/) — 41 symbols
- [Scheduling And Diagnostics](/api/gantt/scheduling/) — 38 symbols
- [Timeline And Visuals](/api/gantt/visuals/) — 80 symbols
- [Columns And Grid Projection](/api/gantt/columns/) — 20 symbols
- [Events And Lifecycle](/api/gantt/events/) — 38 symbols
- [Editors, Toolbar, Export, And Recipes](/api/gantt/extensions/) — 207 symbols

## Common Entry Points

- [`GanttPlugin`](/api/gantt/plugin/#ganttplugin)
- [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig)
- [`GanttTaskSourceRow`](/api/gantt/plugin/#gantttasksourcerow)
- [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)
- [`DependencyEntity`](/api/gantt/data-model/#dependencyentity)
- [`GanttVisualConfig`](/api/gantt/visuals/#ganttvisualconfig)
- [Gantt Events](/api/gantt/events/)

For behavior and examples, start with the [Gantt guides](/guides/gantt/) or [example browser](/guides/gantt/examples/).

## Legacy Symbol Anchors

Existing links to symbols on the former single-page reference remain valid here. Select the symbol to open its structured API page.

<span id="approvalgatevalidatoroptions"></span>[`ApprovalGateValidatorOptions`](/api/gantt/extensions/#approvalgatevalidatoroptions)
<span id="approvalrecord"></span>[`ApprovalRecord`](/api/gantt/extensions/#approvalrecord)
<span id="areganttdependencydropdownvaluesequal"></span>[`areGanttDependencyDropdownValuesEqual`](/api/gantt/extensions/#areganttdependencydropdownvaluesequal)
<span id="assignmententity"></span>[`AssignmentEntity`](/api/gantt/data-model/#assignmententity)
<span id="assignmentid"></span>[`AssignmentId`](/api/gantt/data-model/#assignmentid)
<span id="assignmentstore"></span>[`AssignmentStore`](/api/gantt/data-model/#assignmentstore)
<span id="assignresourcemenuitemoptions"></span>[`AssignResourceMenuItemOptions`](/api/gantt/extensions/#assignresourcemenuitemoptions)
<span id="autodependencyadjustment"></span>[`AutoDependencyAdjustment`](/api/gantt/scheduling/#autodependencyadjustment)
<span id="baselineid"></span>[`BaselineId`](/api/gantt/data-model/#baselineid)
<span id="baselinesnapshot"></span>[`BaselineSnapshot`](/api/gantt/data-model/#baselinesnapshot)
<span id="baselinetasksnapshot"></span>[`BaselineTaskSnapshot`](/api/gantt/data-model/#baselinetasksnapshot)
<span id="buildcreateprojectsnapshottablesql"></span>[`buildCreateProjectSnapshotTableSql`](/api/gantt/extensions/#buildcreateprojectsnapshottablesql)
<span id="buildloadprojectsnapshotsql"></span>[`buildLoadProjectSnapshotSql`](/api/gantt/extensions/#buildloadprojectsnapshotsql)
<span id="buildsaveprojectsnapshotsql"></span>[`buildSaveProjectSnapshotSql`](/api/gantt/extensions/#buildsaveprojectsnapshotsql)
<span id="buildwbsmap"></span>[`buildWbsMap`](/api/gantt/visuals/#buildwbsmap)
<span id="calculatetaskstatus"></span>[`calculateTaskStatus`](/api/gantt/scheduling/#calculatetaskstatus)
<span id="captureganttbaseline"></span>[`captureGanttBaseline`](/api/gantt/extensions/#captureganttbaseline)
<span id="clamplevelindex"></span>[`clampLevelIndex`](/api/gantt/visuals/#clamplevelindex)
<span id="cloneprojectsnapshot"></span>[`cloneProjectSnapshot`](/api/gantt/data-model/#cloneprojectsnapshot)
<span id="constraintwindowconflict"></span>[`ConstraintWindowConflict`](/api/gantt/scheduling/#constraintwindowconflict)
<span id="createapprovalgatevalidator"></span>[`createApprovalGateValidator`](/api/gantt/extensions/#createapprovalgatevalidator)
<span id="createassignresourcemenuitem"></span>[`createAssignResourceMenuItem`](/api/gantt/extensions/#createassignresourcemenuitem)
<span id="createbaselinebarlayout"></span>[`createBaselineBarLayout`](/api/gantt/visuals/#createbaselinebarlayout)
<span id="createcustomtaskeditorformrecipe"></span>[`createCustomTaskEditorFormRecipe`](/api/gantt/extensions/#createcustomtaskeditorformrecipe)
<span id="createcustomvalidationrecipe"></span>[`createCustomValidationRecipe`](/api/gantt/extensions/#createcustomvalidationrecipe)
<span id="createdefaulttasktablecolumn"></span>[`createDefaultTaskTableColumn`](/api/gantt/columns/#createdefaulttasktablecolumn)
<span id="createdeletetaskmenuitem"></span>[`createDeleteTaskMenuItem`](/api/gantt/extensions/#createdeletetaskmenuitem)
<span id="createdependencygraph"></span>[`createDependencyGraph`](/api/gantt/scheduling/#createdependencygraph)
<span id="createdependencyvalidationsummaryrecipe"></span>[`createDependencyValidationSummaryRecipe`](/api/gantt/extensions/#createdependencyvalidationsummaryrecipe)
<span id="createduplicatetaskmenuitem"></span>[`createDuplicateTaskMenuItem`](/api/gantt/extensions/#createduplicatetaskmenuitem)
<span id="createexportmenuitem"></span>[`createExportMenuItem`](/api/gantt/extensions/#createexportmenuitem)
<span id="createforbiddendaterangevalidator"></span>[`createForbiddenDateRangeValidator`](/api/gantt/extensions/#createforbiddendaterangevalidator)
<span id="createganttbarlayout"></span>[`createGanttBarLayout`](/api/gantt/visuals/#createganttbarlayout)
<span id="createganttbeforetaskchangevalidationhandler"></span>[`createGanttBeforeTaskChangeValidationHandler`](/api/gantt/events/#createganttbeforetaskchangevalidationhandler)
<span id="createganttcolumn"></span>[`createGanttColumn`](/api/gantt/columns/#createganttcolumn)
<span id="createganttcolumnpreset"></span>[`createGanttColumnPreset`](/api/gantt/columns/#createganttcolumnpreset)
<span id="createganttcolumnpresetrecipe"></span>[`createGanttColumnPresetRecipe`](/api/gantt/extensions/#createganttcolumnpresetrecipe)
<span id="createganttcolumnpresets"></span>[`createGanttColumnPresets`](/api/gantt/columns/#createganttcolumnpresets)
<span id="createganttcontextmenuextensionitems"></span>[`createGanttContextMenuExtensionItems`](/api/gantt/extensions/#createganttcontextmenuextensionitems)
<span id="createganttcontextmenuquickwinrecipe"></span>[`createGanttContextMenuQuickWinRecipe`](/api/gantt/extensions/#createganttcontextmenuquickwinrecipe)
<span id="createganttdateadapter"></span>[`createGanttDateAdapter`](/api/gantt/plugin/#createganttdateadapter)
<span id="createganttdateformatcontext"></span>[`createGanttDateFormatContext`](/api/gantt/plugin/#createganttdateformatcontext)
<span id="createganttexcelexportrecipe"></span>[`createGanttExcelExportRecipe`](/api/gantt/extensions/#createganttexcelexportrecipe)
<span id="createganttgridrows"></span>[`createGanttGridRows`](/api/gantt/columns/#createganttgridrows)
<span id="createganttpdfexcelreportingrecipe"></span>[`createGanttPdfExcelReportingRecipe`](/api/gantt/extensions/#createganttpdfexcelreportingrecipe)
<span id="createganttprintoptions"></span>[`createGanttPrintOptions`](/api/gantt/extensions/#createganttprintoptions)
<span id="createganttprintstyles"></span>[`createGanttPrintStyles`](/api/gantt/extensions/#createganttprintstyles)
<span id="creategantttaskstatusindicatorrecipe"></span>[`createGanttTaskStatusIndicatorRecipe`](/api/gantt/extensions/#creategantttaskstatusindicatorrecipe)
<span id="creategantttoolbarquickwinactions"></span>[`createGanttToolbarQuickWinActions`](/api/gantt/extensions/#creategantttoolbarquickwinactions)
<span id="creategraphqlprojectpersistencerecipe"></span>[`createGraphqlProjectPersistenceRecipe`](/api/gantt/extensions/#creategraphqlprojectpersistencerecipe)
<span id="createindicatorlayout"></span>[`createIndicatorLayout`](/api/gantt/visuals/#createindicatorlayout)
<span id="createinitialtasktablecolumns"></span>[`createInitialTaskTableColumns`](/api/gantt/columns/#createinitialtasktablecolumns)
<span id="createjsonsnapshotrecipe"></span>[`createJsonSnapshotRecipe`](/api/gantt/extensions/#createjsonsnapshotrecipe)
<span id="createlockedphasevalidator"></span>[`createLockedPhaseValidator`](/api/gantt/extensions/#createlockedphasevalidator)
<span id="createpostgressqlpersistencerecipe"></span>[`createPostgresSqlPersistenceRecipe`](/api/gantt/extensions/#createpostgressqlpersistencerecipe)
<span id="createprintableganttmetadata"></span>[`createPrintableGanttMetadata`](/api/gantt/extensions/#createprintableganttmetadata)
<span id="createprintpdfexportrecipe"></span>[`createPrintPdfExportRecipe`](/api/gantt/extensions/#createprintpdfexportrecipe)
<span id="createresourceloadsummaryexample"></span>[`createResourceLoadSummaryExample`](/api/gantt/extensions/#createresourceloadsummaryexample)
<span id="createresourceoverallocationsummaryrecipe"></span>[`createResourceOverallocationSummaryRecipe`](/api/gantt/extensions/#createresourceoverallocationsummaryrecipe)
<span id="createrestprojectpersistencerecipe"></span>[`createRestProjectPersistenceRecipe`](/api/gantt/extensions/#createrestprojectpersistencerecipe)
<span id="createrolebasededitabilityrecipe"></span>[`createRoleBasedEditabilityRecipe`](/api/gantt/extensions/#createrolebasededitabilityrecipe)
<span id="createroleguardvalidator"></span>[`createRoleGuardValidator`](/api/gantt/extensions/#createroleguardvalidator)
<span id="createschedulerdiagnosticsexample"></span>[`createSchedulerDiagnosticsExample`](/api/gantt/extensions/#createschedulerdiagnosticsexample)
<span id="createschedulerengine"></span>[`createSchedulerEngine`](/api/gantt/scheduling/#createschedulerengine)
<span id="createsupabasepostgrespersistencerecipe"></span>[`createSupabasePostgresPersistenceRecipe`](/api/gantt/extensions/#createsupabasepostgrespersistencerecipe)
<span id="createtaskdetailpopoverrecipe"></span>[`createTaskDetailPopoverRecipe`](/api/gantt/extensions/#createtaskdetailpopoverrecipe)
<span id="createtaskeditordialoglocaletext"></span>[`createTaskEditorDialogLocaleText`](/api/gantt/extensions/#createtaskeditordialoglocaletext)
<span id="createtaskgridconfig"></span>[`createTaskGridConfig`](/api/gantt/plugin/#createtaskgridconfig)
<span id="createtaskgridscaleconfig"></span>[`createTaskGridScaleConfig`](/api/gantt/plugin/#createtaskgridscaleconfig)
<span id="createtaskgridsource"></span>[`createTaskGridSource`](/api/gantt/plugin/#createtaskgridsource)
<span id="createtasknameexcelexportmenuitem"></span>[`createTaskNameExcelExportMenuItem`](/api/gantt/extensions/#createtasknameexcelexportmenuitem)
<span id="createtasktypeoptions"></span>[`createTaskTypeOptions`](/api/gantt/data-model/#createtasktypeoptions)
<span id="createtimelinedateformatcontext"></span>[`createTimelineDateFormatContext`](/api/gantt/visuals/#createtimelinedateformatcontext)
<span id="createtimelinescale"></span>[`createTimelineScale`](/api/gantt/visuals/#createtimelinescale)
<span id="customtaskeditorrecipe"></span>[`CustomTaskEditorRecipe`](/api/gantt/extensions/#customtaskeditorrecipe)
<span id="customtaskeditorrecipeoptions"></span>[`CustomTaskEditorRecipeOptions`](/api/gantt/extensions/#customtaskeditorrecipeoptions)
<span id="customvalidationrecipe"></span>[`CustomValidationRecipe`](/api/gantt/extensions/#customvalidationrecipe)
<span id="customvalidationrecipeoptions"></span>[`CustomValidationRecipeOptions`](/api/gantt/extensions/#customvalidationrecipeoptions)
<span id="deadlinemissedconflict"></span>[`DeadlineMissedConflict`](/api/gantt/scheduling/#deadlinemissedconflict)
<span id="default_gantt_dependency_types"></span>[`DEFAULT_GANTT_DEPENDENCY_TYPES`](/api/gantt/extensions/#default_gantt_dependency_types)
<span id="default_gantt_error_labels"></span>[`DEFAULT_GANTT_ERROR_LABELS`](/api/gantt/plugin/#default_gantt_error_labels)
<span id="default_gantt_warning_labels"></span>[`DEFAULT_GANTT_WARNING_LABELS`](/api/gantt/plugin/#default_gantt_warning_labels)
<span id="default_smooth_wheel_threshold"></span>[`DEFAULT_SMOOTH_WHEEL_THRESHOLD`](/api/gantt/visuals/#default_smooth_wheel_threshold)
<span id="default_task_editor_dialog_locale_text"></span>[`DEFAULT_TASK_EDITOR_DIALOG_LOCALE_TEXT`](/api/gantt/extensions/#default_task_editor_dialog_locale_text)
<span id="default_timeline_zoom_levels"></span>[`DEFAULT_TIMELINE_ZOOM_LEVELS`](/api/gantt/visuals/#default_timeline_zoom_levels)
<span id="defaulttasktablecolumns"></span>[`defaultTaskTableColumns`](/api/gantt/columns/#defaulttasktablecolumns)
<span id="definegantttoolbar"></span>[`defineGanttToolbar`](/api/gantt/extensions/#definegantttoolbar)
<span id="deletetaskmenuitemoptions"></span>[`DeleteTaskMenuItemOptions`](/api/gantt/extensions/#deletetaskmenuitemoptions)
<span id="dependencyconstraintconflict"></span>[`DependencyConstraintConflict`](/api/gantt/scheduling/#dependencyconstraintconflict)
<span id="dependencycycle"></span>[`DependencyCycle`](/api/gantt/scheduling/#dependencycycle)
<span id="dependencyendpointpair"></span>[`DependencyEndpointPair`](/api/gantt/extensions/#dependencyendpointpair)
<span id="dependencyendpointstotype"></span>[`dependencyEndpointsToType`](/api/gantt/extensions/#dependencyendpointstotype)
<span id="dependencyentity"></span>[`DependencyEntity`](/api/gantt/data-model/#dependencyentity)
<span id="dependencygraph"></span>[`DependencyGraph`](/api/gantt/scheduling/#dependencygraph)
<span id="dependencyid"></span>[`DependencyId`](/api/gantt/data-model/#dependencyid)
<span id="dependencytype"></span>[`DependencyType`](/api/gantt/data-model/#dependencytype)
<span id="dependencytypetoendpoints"></span>[`dependencyTypeToEndpoints`](/api/gantt/extensions/#dependencytypetoendpoints)
<span id="dependencyvalidationsummaryrecipe"></span>[`DependencyValidationSummaryRecipe`](/api/gantt/extensions/#dependencyvalidationsummaryrecipe)
<span id="duplicatetaskmenuitemoptions"></span>[`DuplicateTaskMenuItemOptions`](/api/gantt/extensions/#duplicatetaskmenuitemoptions)
<span id="entityid"></span>[`EntityId`](/api/gantt/data-model/#entityid)
<span id="exportganttcsv"></span>[`exportGanttCsv`](/api/gantt/extensions/#exportganttcsv)
<span id="exportganttexcel"></span>[`exportGanttExcel`](/api/gantt/extensions/#exportganttexcel)
<span id="exportmenuitemoptions"></span>[`ExportMenuItemOptions`](/api/gantt/extensions/#exportmenuitemoptions)
<span id="exportprojectsnapshot"></span>[`exportProjectSnapshot`](/api/gantt/data-model/#exportprojectsnapshot)
<span id="fallback_zoom_level"></span>[`FALLBACK_ZOOM_LEVEL`](/api/gantt/visuals/#fallback_zoom_level)
<span id="finishconstraintconflict"></span>[`FinishConstraintConflict`](/api/gantt/scheduling/#finishconstraintconflict)
<span id="fitgantttoproject"></span>[`fitGanttToProject`](/api/gantt/extensions/#fitgantttoproject)
<span id="forbiddendaterangevalidatoroptions"></span>[`ForbiddenDateRangeValidatorOptions`](/api/gantt/extensions/#forbiddendaterangevalidatoroptions)
<span id="formatganttdatewithoption"></span>[`formatGanttDateWithOption`](/api/gantt/plugin/#formatganttdatewithoption)
<span id="formatgantteditordate"></span>[`formatGanttEditorDate`](/api/gantt/plugin/#formatgantteditordate)
<span id="formatganttprintrange"></span>[`formatGanttPrintRange`](/api/gantt/extensions/#formatganttprintrange)
<span id="formatgantttabledate"></span>[`formatGanttTableDate`](/api/gantt/plugin/#formatgantttabledate)
<span id="formatgantttooltipdate"></span>[`formatGanttTooltipDate`](/api/gantt/plugin/#formatgantttooltipdate)
<span id="gantt_assignment_change_event"></span>[`GANTT_ASSIGNMENT_CHANGE_EVENT`](/api/gantt/events/#gantt_assignment_change_event)
<span id="gantt_before_assignment_change_event"></span>[`GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT`](/api/gantt/events/#gantt_before_assignment_change_event)
<span id="gantt_before_dependency_change_event"></span>[`GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT`](/api/gantt/events/#gantt_before_dependency_change_event)
<span id="gantt_before_task_change_event"></span>[`GANTT_BEFORE_TASK_CHANGE_EVENT`](/api/gantt/events/#gantt_before_task_change_event)
<span id="gantt_dependency_change_event"></span>[`GANTT_DEPENDENCY_CHANGE_EVENT`](/api/gantt/events/#gantt_dependency_change_event)
<span id="gantt_dependency_dropdown_column_type"></span>[`GANTT_DEPENDENCY_DROPDOWN_COLUMN_TYPE`](/api/gantt/plugin/#gantt_dependency_dropdown_column_type)
<span id="gantt_dependency_hover_event"></span>[`GANTT_DEPENDENCY_HOVER_EVENT`](/api/gantt/events/#gantt_dependency_hover_event)
<span id="gantt_dependency_select_event"></span>[`GANTT_DEPENDENCY_SELECT_EVENT`](/api/gantt/events/#gantt_dependency_select_event)
<span id="gantt_history_record_event"></span>[`GANTT_HISTORY_RECORD_EVENT`](/api/gantt/events/#gantt_history_record_event)
<span id="gantt_panel_resize_event"></span>[`GANTT_PANEL_RESIZE_EVENT`](/api/gantt/events/#gantt_panel_resize_event)
<span id="gantt_persistence_quick_win_examples"></span>[`GANTT_PERSISTENCE_QUICK_WIN_EXAMPLES`](/api/gantt/extensions/#gantt_persistence_quick_win_examples)
<span id="gantt_search_event"></span>[`GANTT_SEARCH_EVENT`](/api/gantt/events/#gantt_search_event)
<span id="gantt_task_change_event"></span>[`GANTT_TASK_CHANGE_EVENT`](/api/gantt/events/#gantt_task_change_event)
<span id="gantt_task_convert_to_milestone_event"></span>[`GANTT_TASK_CONVERT_TO_MILESTONE_EVENT`](/api/gantt/events/#gantt_task_convert_to_milestone_event)
<span id="gantt_task_create_event"></span>[`GANTT_TASK_CREATE_EVENT`](/api/gantt/events/#gantt_task_create_event)
<span id="gantt_task_created_event"></span>[`GANTT_TASK_CREATED_EVENT`](/api/gantt/events/#gantt_task_created_event)
<span id="gantt_task_delete_event"></span>[`GANTT_TASK_DELETE_EVENT`](/api/gantt/events/#gantt_task_delete_event)
<span id="gantt_task_edit_event"></span>[`GANTT_TASK_EDIT_EVENT`](/api/gantt/events/#gantt_task_edit_event)
<span id="gantt_task_indent_event"></span>[`GANTT_TASK_INDENT_EVENT`](/api/gantt/events/#gantt_task_indent_event)
<span id="gantt_task_outdent_event"></span>[`GANTT_TASK_OUTDENT_EVENT`](/api/gantt/events/#gantt_task_outdent_event)
<span id="gantt_toolbar_select_all_columns"></span>[`GANTT_TOOLBAR_SELECT_ALL_COLUMNS`](/api/gantt/extensions/#gantt_toolbar_select_all_columns)
<span id="gantt_zoom_in_event"></span>[`GANTT_ZOOM_IN_EVENT`](/api/gantt/events/#gantt_zoom_in_event)
<span id="gantt_zoom_out_event"></span>[`GANTT_ZOOM_OUT_EVENT`](/api/gantt/events/#gantt_zoom_out_event)
<span id="gantt_zoom_set_level_event"></span>[`GANTT_ZOOM_SET_LEVEL_EVENT`](/api/gantt/events/#gantt_zoom_set_level_event)
<span id="ganttapprovalregistry"></span>[`GanttApprovalRegistry`](/api/gantt/extensions/#ganttapprovalregistry)
<span id="ganttassignmentdomainchangedetail"></span>[`GanttAssignmentDomainChangeDetail`](/api/gantt/plugin/#ganttassignmentdomainchangedetail)
<span id="ganttassignmenterrorlabelkey"></span>[`GanttAssignmentErrorLabelKey`](/api/gantt/plugin/#ganttassignmenterrorlabelkey)
<span id="ganttbarkind"></span>[`GanttBarKind`](/api/gantt/visuals/#ganttbarkind)
<span id="ganttbarlayout"></span>[`GanttBarLayout`](/api/gantt/visuals/#ganttbarlayout)
<span id="ganttbaselinecaptureruntime"></span>[`GanttBaselineCaptureRuntime`](/api/gantt/extensions/#ganttbaselinecaptureruntime)
<span id="ganttbaselinelayout"></span>[`GanttBaselineLayout`](/api/gantt/visuals/#ganttbaselinelayout)
<span id="ganttbeforeassignmentchangeaction"></span>[`GanttBeforeAssignmentChangeAction`](/api/gantt/events/#ganttbeforeassignmentchangeaction)
<span id="ganttbeforeassignmentchangedetail"></span>[`GanttBeforeAssignmentChangeDetail`](/api/gantt/events/#ganttbeforeassignmentchangedetail)
<span id="ganttbeforedependencychangeaction"></span>[`GanttBeforeDependencyChangeAction`](/api/gantt/events/#ganttbeforedependencychangeaction)
<span id="ganttbeforedependencychangedetail"></span>[`GanttBeforeDependencyChangeDetail`](/api/gantt/events/#ganttbeforedependencychangedetail)
<span id="ganttbeforetaskchangeaction"></span>[`GanttBeforeTaskChangeAction`](/api/gantt/events/#ganttbeforetaskchangeaction)
<span id="ganttbeforetaskchangedetail"></span>[`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail)
<span id="ganttbeforetaskchangevalidator"></span>[`GanttBeforeTaskChangeValidator`](/api/gantt/events/#ganttbeforetaskchangevalidator)
<span id="ganttcolorpaletteconfig"></span>[`GanttColorPaletteConfig`](/api/gantt/plugin/#ganttcolorpaletteconfig)
<span id="ganttcolumnpresetname"></span>[`GanttColumnPresetName`](/api/gantt/columns/#ganttcolumnpresetname)
<span id="ganttcolumnpresetoptions"></span>[`GanttColumnPresetOptions`](/api/gantt/columns/#ganttcolumnpresetoptions)
<span id="ganttcolumnpresetprop"></span>[`GanttColumnPresetProp`](/api/gantt/columns/#ganttcolumnpresetprop)
<span id="ganttcolumnpresetprops"></span>[`ganttColumnPresetProps`](/api/gantt/columns/#ganttcolumnpresetprops)
<span id="ganttcolumnpresetrecipe"></span>[`GanttColumnPresetRecipe`](/api/gantt/extensions/#ganttcolumnpresetrecipe)
<span id="ganttcolumnpresetrecipeoptions"></span>[`GanttColumnPresetRecipeOptions`](/api/gantt/extensions/#ganttcolumnpresetrecipeoptions)
<span id="ganttconstrainttypelabelvalue"></span>[`GanttConstraintTypeLabelValue`](/api/gantt/plugin/#ganttconstrainttypelabelvalue)
<span id="ganttconstrainttypeoption"></span>[`GanttConstraintTypeOption`](/api/gantt/plugin/#ganttconstrainttypeoption)
<span id="ganttcontextmenubaseitemoptions"></span>[`GanttContextMenuBaseItemOptions`](/api/gantt/extensions/#ganttcontextmenubaseitemoptions)
<span id="ganttcontextmenuconfig"></span>[`GanttContextMenuConfig`](/api/gantt/plugin/#ganttcontextmenuconfig)
<span id="ganttcontextmenudisableditems"></span>[`GanttContextMenuDisabledItems`](/api/gantt/plugin/#ganttcontextmenudisableditems)
<span id="ganttcontextmenuextensioncontext"></span>[`GanttContextMenuExtensionContext`](/api/gantt/extensions/#ganttcontextmenuextensioncontext)
<span id="ganttcontextmenuhiddenitems"></span>[`GanttContextMenuHiddenItems`](/api/gantt/plugin/#ganttcontextmenuhiddenitems)
<span id="ganttcontextmenuitemid"></span>[`GanttContextMenuItemId`](/api/gantt/plugin/#ganttcontextmenuitemid)
<span id="ganttcontextmenuitemstate"></span>[`GanttContextMenuItemState`](/api/gantt/plugin/#ganttcontextmenuitemstate)
<span id="ganttcontextmenuitemstatecontext"></span>[`GanttContextMenuItemStateContext`](/api/gantt/plugin/#ganttcontextmenuitemstatecontext)
<span id="ganttcontextmenulabels"></span>[`GanttContextMenuLabels`](/api/gantt/plugin/#ganttcontextmenulabels)
<span id="ganttcontextmenuquickwinrecipeoptions"></span>[`GanttContextMenuQuickWinRecipeOptions`](/api/gantt/extensions/#ganttcontextmenuquickwinrecipeoptions)
<span id="ganttcreatetaskoptions"></span>[`GanttCreateTaskOptions`](/api/gantt/plugin/#ganttcreatetaskoptions)
<span id="ganttcsvexportoptions"></span>[`GanttCsvExportOptions`](/api/gantt/extensions/#ganttcsvexportoptions)
<span id="ganttdateadapter"></span>[`GanttDateAdapter`](/api/gantt/plugin/#ganttdateadapter)
<span id="ganttdateeditorformatconfig"></span>[`GanttDateEditorFormatConfig`](/api/gantt/plugin/#ganttdateeditorformatconfig)
<span id="ganttdateformatconfig"></span>[`GanttDateFormatConfig`](/api/gantt/plugin/#ganttdateformatconfig)
<span id="ganttdateformatcontext"></span>[`GanttDateFormatContext`](/api/gantt/plugin/#ganttdateformatcontext)
<span id="ganttdateformatoption"></span>[`GanttDateFormatOption`](/api/gantt/plugin/#ganttdateformatoption)
<span id="ganttdateformatsurface"></span>[`GanttDateFormatSurface`](/api/gantt/plugin/#ganttdateformatsurface)
<span id="ganttdateformatter"></span>[`GanttDateFormatter`](/api/gantt/plugin/#ganttdateformatter)
<span id="ganttdateparser"></span>[`GanttDateParser`](/api/gantt/plugin/#ganttdateparser)
<span id="ganttdaterange"></span>[`GanttDateRange`](/api/gantt/extensions/#ganttdaterange)
<span id="ganttdependencydomainchangedetail"></span>[`GanttDependencyDomainChangeDetail`](/api/gantt/plugin/#ganttdependencydomainchangedetail)
<span id="ganttdependencydropdowncelltemplate"></span>[`ganttDependencyDropdownCellTemplate`](/api/gantt/plugin/#ganttdependencydropdowncelltemplate)
<span id="ganttdependencydropdowncolumn"></span>[`GanttDependencyDropdownColumn`](/api/gantt/columns/#ganttdependencydropdowncolumn)
<span id="ganttdependencydropdownconfig"></span>[`GanttDependencyDropdownConfig`](/api/gantt/extensions/#ganttdependencydropdownconfig)
<span id="ganttdependencydropdowncontrol"></span>[`GanttDependencyDropdownControl`](/api/gantt/extensions/#ganttdependencydropdowncontrol)
<span id="ganttdependencydropdowncontrolprops"></span>[`GanttDependencyDropdownControlProps`](/api/gantt/extensions/#ganttdependencydropdowncontrolprops)
<span id="ganttdependencydropdowneditor"></span>[`GanttDependencyDropdownEditor`](/api/gantt/plugin/#ganttdependencydropdowneditor)
<span id="ganttdependencydropdowntaskoption"></span>[`GanttDependencyDropdownTaskOption`](/api/gantt/extensions/#ganttdependencydropdowntaskoption)
<span id="ganttdependencydropdownvalue"></span>[`GanttDependencyDropdownValue`](/api/gantt/extensions/#ganttdependencydropdownvalue)
<span id="ganttdependencyendpoint"></span>[`GanttDependencyEndpoint`](/api/gantt/extensions/#ganttdependencyendpoint)
<span id="ganttdependencyerrorlabelkey"></span>[`GanttDependencyErrorLabelKey`](/api/gantt/plugin/#ganttdependencyerrorlabelkey)
<span id="ganttdependencyinteractiondetail"></span>[`GanttDependencyInteractionDetail`](/api/gantt/events/#ganttdependencyinteractiondetail)
<span id="ganttdependencytooltipcontext"></span>[`GanttDependencyTooltipContext`](/api/gantt/plugin/#ganttdependencytooltipcontext)
<span id="ganttdependencytooltiphook"></span>[`GanttDependencyTooltipHook`](/api/gantt/plugin/#ganttdependencytooltiphook)
<span id="gantterrorlabelsconfig"></span>[`GanttErrorLabelsConfig`](/api/gantt/plugin/#gantterrorlabelsconfig)
<span id="gantteventmanagerdomainchange"></span>[`GanttEventManagerDomainChange`](/api/gantt/events/#gantteventmanagerdomainchange)
<span id="gantteventmanagerevent"></span>[`GanttEventManagerEvent`](/api/gantt/events/#gantteventmanagerevent)
<span id="ganttexamplecancelableevent"></span>[`GanttExampleCancelableEvent`](/api/gantt/events/#ganttexamplecancelableevent)
<span id="ganttexcelexportoptions"></span>[`GanttExcelExportOptions`](/api/gantt/extensions/#ganttexcelexportoptions)
<span id="ganttexcelexportrecipe"></span>[`GanttExcelExportRecipe`](/api/gantt/extensions/#ganttexcelexportrecipe)
<span id="ganttexcelexportrecipeoptions"></span>[`GanttExcelExportRecipeOptions`](/api/gantt/extensions/#ganttexcelexportrecipeoptions)
<span id="ganttgridrow"></span>[`GanttGridRow`](/api/gantt/columns/#ganttgridrow)
<span id="ganttindicatorlayout"></span>[`GanttIndicatorLayout`](/api/gantt/visuals/#ganttindicatorlayout)
<span id="ganttlabelsconfig"></span>[`GanttLabelsConfig`](/api/gantt/plugin/#ganttlabelsconfig)
<span id="ganttmessagecontext"></span>[`GanttMessageContext`](/api/gantt/plugin/#ganttmessagecontext)
<span id="ganttmessagetemplate"></span>[`GanttMessageTemplate`](/api/gantt/plugin/#ganttmessagetemplate)
<span id="ganttmilestoneline"></span>[`GanttMilestoneLine`](/api/gantt/plugin/#ganttmilestoneline)
<span id="ganttpanelresizedetail"></span>[`GanttPanelResizeDetail`](/api/gantt/extensions/#ganttpanelresizedetail)
<span id="ganttpanelresizeeventdetail"></span>[`GanttPanelResizeEventDetail`](/api/gantt/events/#ganttpanelresizeeventdetail)
<span id="ganttpanelresizeplugin"></span>[`GanttPanelResizePlugin`](/api/gantt/extensions/#ganttpanelresizeplugin)
<span id="ganttpanelresizepluginconfig"></span>[`GanttPanelResizePluginConfig`](/api/gantt/extensions/#ganttpanelresizepluginconfig)
<span id="ganttpdfexcelreportingexportoptions"></span>[`GanttPdfExcelReportingExportOptions`](/api/gantt/extensions/#ganttpdfexcelreportingexportoptions)
<span id="ganttpdfexcelreportingrecipe"></span>[`GanttPdfExcelReportingRecipe`](/api/gantt/extensions/#ganttpdfexcelreportingrecipe)
<span id="ganttpdfexcelreportingrecipeoptions"></span>[`GanttPdfExcelReportingRecipeOptions`](/api/gantt/extensions/#ganttpdfexcelreportingrecipeoptions)
<span id="ganttpercentdonecolumn"></span>[`GanttPercentDoneColumn`](/api/gantt/columns/#ganttpercentdonecolumn)
<span id="ganttpercentdonecolumnmode"></span>[`GanttPercentDoneColumnMode`](/api/gantt/columns/#ganttpercentdonecolumnmode)
<span id="ganttpersistencerecipechannel"></span>[`GanttPersistenceRecipeChannel`](/api/gantt/extensions/#ganttpersistencerecipechannel)
<span id="ganttpersistencerecipeframework"></span>[`GanttPersistenceRecipeFramework`](/api/gantt/extensions/#ganttpersistencerecipeframework)
<span id="ganttpersistencerecipeid"></span>[`GanttPersistenceRecipeId`](/api/gantt/extensions/#ganttpersistencerecipeid)
<span id="ganttpersistencerecipemetadata"></span>[`GanttPersistenceRecipeMetadata`](/api/gantt/extensions/#ganttpersistencerecipemetadata)
<span id="ganttplugin"></span>[`GanttPlugin`](/api/gantt/plugin/#ganttplugin)
<span id="ganttpluginconfig"></span>[`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig)
<span id="ganttprintablemetadata"></span>[`GanttPrintableMetadata`](/api/gantt/extensions/#ganttprintablemetadata)
<span id="ganttprintablemetadataoptions"></span>[`GanttPrintableMetadataOptions`](/api/gantt/extensions/#ganttprintablemetadataoptions)
<span id="ganttprintdaterange"></span>[`GanttPrintDateRange`](/api/gantt/extensions/#ganttprintdaterange)
<span id="ganttprintoptions"></span>[`GanttPrintOptions`](/api/gantt/extensions/#ganttprintoptions)
<span id="ganttprintorientation"></span>[`GanttPrintOrientation`](/api/gantt/extensions/#ganttprintorientation)
<span id="ganttprintpdfrecipe"></span>[`GanttPrintPdfRecipe`](/api/gantt/extensions/#ganttprintpdfrecipe)
<span id="ganttprintpdfrecipeoptions"></span>[`GanttPrintPdfRecipeOptions`](/api/gantt/extensions/#ganttprintpdfrecipeoptions)
<span id="ganttprintresult"></span>[`GanttPrintResult`](/api/gantt/extensions/#ganttprintresult)
<span id="ganttprintstyleoptions"></span>[`GanttPrintStyleOptions`](/api/gantt/extensions/#ganttprintstyleoptions)
<span id="ganttprintwindow"></span>[`GanttPrintWindow`](/api/gantt/extensions/#ganttprintwindow)
<span id="ganttprojectfitoptions"></span>[`GanttProjectFitOptions`](/api/gantt/extensions/#ganttprojectfitoptions)
<span id="ganttresourceplanningconfig"></span>[`GanttResourcePlanningConfig`](/api/gantt/plugin/#ganttresourceplanningconfig)
<span id="ganttrolebasededitabilityrecipe"></span>[`GanttRoleBasedEditabilityRecipe`](/api/gantt/extensions/#ganttrolebasededitabilityrecipe)
<span id="ganttrolebasededitabilityrecipeoptions"></span>[`GanttRoleBasedEditabilityRecipeOptions`](/api/gantt/extensions/#ganttrolebasededitabilityrecipeoptions)
<span id="ganttruntimelabelsconfig"></span>[`GanttRuntimeLabelsConfig`](/api/gantt/plugin/#ganttruntimelabelsconfig)
<span id="ganttschedulerwarninglabelkey"></span>[`GanttSchedulerWarningLabelKey`](/api/gantt/plugin/#ganttschedulerwarninglabelkey)
<span id="ganttschedulingconfig"></span>[`GanttSchedulingConfig`](/api/gantt/plugin/#ganttschedulingconfig)
<span id="ganttsearcheventdetail"></span>[`GanttSearchEventDetail`](/api/gantt/events/#ganttsearcheventdetail)
<span id="ganttsnapconfig"></span>[`GanttSnapConfig`](/api/gantt/plugin/#ganttsnapconfig)
<span id="ganttsplitgaplayout"></span>[`GanttSplitGapLayout`](/api/gantt/visuals/#ganttsplitgaplayout)
<span id="gantttaskbarcolor"></span>[`GanttTaskBarColor`](/api/gantt/visuals/#gantttaskbarcolor)
<span id="gantttaskbarcolorhook"></span>[`GanttTaskBarColorHook`](/api/gantt/visuals/#gantttaskbarcolorhook)
<span id="gantttaskbarcontentcontext"></span>[`GanttTaskBarContentContext`](/api/gantt/visuals/#gantttaskbarcontentcontext)
<span id="gantttaskbarcontenthook"></span>[`GanttTaskBarContentHook`](/api/gantt/visuals/#gantttaskbarcontenthook)
<span id="gantttaskbarvisualcontext"></span>[`GanttTaskBarVisualContext`](/api/gantt/visuals/#gantttaskbarvisualcontext)
<span id="gantttaskcreatedeventdetail"></span>[`GanttTaskCreatedEventDetail`](/api/gantt/events/#gantttaskcreatedeventdetail)
<span id="gantttaskdomainchangedetail"></span>[`GanttTaskDomainChangeDetail`](/api/gantt/plugin/#gantttaskdomainchangedetail)
<span id="gantttaskediterrorlabelkey"></span>[`GanttTaskEditErrorLabelKey`](/api/gantt/plugin/#gantttaskediterrorlabelkey)
<span id="gantttaskediteventdetail"></span>[`GanttTaskEditEventDetail`](/api/gantt/events/#gantttaskediteventdetail)
<span id="gantttaskeditorcontrolid"></span>[`GanttTaskEditorControlId`](/api/gantt/extensions/#gantttaskeditorcontrolid)
<span id="gantttaskeditordialog"></span>[`GanttTaskEditorDialog`](/api/gantt/extensions/#gantttaskeditordialog)
<span id="gantttaskeditordialogcustomization"></span>[`GanttTaskEditorDialogCustomization`](/api/gantt/extensions/#gantttaskeditordialogcustomization)
<span id="gantttaskeditordialogdependencies"></span>[`ganttTaskEditorDialogDependencies`](/api/gantt/extensions/#gantttaskeditordialogdependencies)
<span id="gantttaskeditordialogdependencydraft"></span>[`GanttTaskEditorDialogDependencyDraft`](/api/gantt/extensions/#gantttaskeditordialogdependencydraft)
<span id="gantttaskeditordialoglocaletext"></span>[`GanttTaskEditorDialogLocaleText`](/api/gantt/extensions/#gantttaskeditordialoglocaletext)
<span id="gantttaskeditordialoglocaletextoptions"></span>[`GanttTaskEditorDialogLocaleTextOptions`](/api/gantt/extensions/#gantttaskeditordialoglocaletextoptions)
<span id="gantttaskeditordialogoptions"></span>[`GanttTaskEditorDialogOptions`](/api/gantt/extensions/#gantttaskeditordialogoptions)
<span id="gantttaskeditordialogplugin"></span>[`GanttTaskEditorDialogPlugin`](/api/gantt/extensions/#gantttaskeditordialogplugin)
<span id="gantttaskeditordialogresourcesoptions"></span>[`GanttTaskEditorDialogResourcesOptions`](/api/gantt/extensions/#gantttaskeditordialogresourcesoptions)
<span id="gantttaskeditordialogsearchtext"></span>[`GanttTaskEditorDialogSearchText`](/api/gantt/extensions/#gantttaskeditordialogsearchtext)
<span id="gantttaskeditordialogstate"></span>[`GanttTaskEditorDialogState`](/api/gantt/extensions/#gantttaskeditordialogstate)
<span id="gantttaskeditordialogstatustext"></span>[`GanttTaskEditorDialogStatusText`](/api/gantt/extensions/#gantttaskeditordialogstatustext)
<span id="gantttaskeditordialogsubmitcontext"></span>[`GanttTaskEditorDialogSubmitContext`](/api/gantt/extensions/#gantttaskeditordialogsubmitcontext)
<span id="gantttaskeditordialogvalidationtext"></span>[`GanttTaskEditorDialogValidationText`](/api/gantt/extensions/#gantttaskeditordialogvalidationtext)
<span id="gantttaskeditordomrenderer"></span>[`GanttTaskEditorDomRenderer`](/api/gantt/extensions/#gantttaskeditordomrenderer)
<span id="gantttaskeditordraftcontroller"></span>[`GanttTaskEditorDraftController`](/api/gantt/extensions/#gantttaskeditordraftcontroller)
<span id="gantttaskeditordraftstate"></span>[`GanttTaskEditorDraftState`](/api/gantt/extensions/#gantttaskeditordraftstate)
<span id="gantttaskeditorerrorlabelkey"></span>[`GanttTaskEditorErrorLabelKey`](/api/gantt/plugin/#gantttaskeditorerrorlabelkey)
<span id="gantttaskeditorfieldeditabilityid"></span>[`GanttTaskEditorFieldEditabilityId`](/api/gantt/extensions/#gantttaskeditorfieldeditabilityid)
<span id="gantttaskeditorrenderercontext"></span>[`GanttTaskEditorRendererContext`](/api/gantt/extensions/#gantttaskeditorrenderercontext)
<span id="gantttaskeditorrendererlifecycle"></span>[`GanttTaskEditorRendererLifecycle`](/api/gantt/extensions/#gantttaskeditorrendererlifecycle)
<span id="gantttaskeditortaboptions"></span>[`GanttTaskEditorTabOptions`](/api/gantt/extensions/#gantttaskeditortaboptions)
<span id="gantttaskeditortabsoptions"></span>[`GanttTaskEditorTabsOptions`](/api/gantt/extensions/#gantttaskeditortabsoptions)
<span id="gantttaskhierarchyactiondetail"></span>[`GanttTaskHierarchyActionDetail`](/api/gantt/plugin/#gantttaskhierarchyactiondetail)
<span id="gantttasklabelmode"></span>[`GanttTaskLabelMode`](/api/gantt/visuals/#gantttasklabelmode)
<span id="gantttaskmarker"></span>[`GanttTaskMarker`](/api/gantt/visuals/#gantttaskmarker)
<span id="gantttaskmarkerhook"></span>[`GanttTaskMarkerHook`](/api/gantt/visuals/#gantttaskmarkerhook)
<span id="gantttaskmodelabelvalue"></span>[`GanttTaskModeLabelValue`](/api/gantt/plugin/#gantttaskmodelabelvalue)
<span id="gantttaskmodeoption"></span>[`GanttTaskModeOption`](/api/gantt/plugin/#gantttaskmodeoption)
<span id="gantttaskmutationerrorlabelkey"></span>[`GanttTaskMutationErrorLabelKey`](/api/gantt/plugin/#gantttaskmutationerrorlabelkey)
<span id="gantttasksourcerow"></span>[`GanttTaskSourceRow`](/api/gantt/plugin/#gantttasksourcerow)
<span id="gantttaskstatusindicatorrecipeoptions"></span>[`GanttTaskStatusIndicatorRecipeOptions`](/api/gantt/extensions/#gantttaskstatusindicatorrecipeoptions)
<span id="gantttaskstatusindicatorreciperow"></span>[`GanttTaskStatusIndicatorRecipeRow`](/api/gantt/extensions/#gantttaskstatusindicatorreciperow)
<span id="gantttasktooltipcontext"></span>[`GanttTaskTooltipContext`](/api/gantt/plugin/#gantttasktooltipcontext)
<span id="gantttasktooltipfield"></span>[`GanttTaskTooltipField`](/api/gantt/plugin/#gantttasktooltipfield)
<span id="gantttasktooltipfieldconfig"></span>[`GanttTaskTooltipFieldConfig`](/api/gantt/plugin/#gantttasktooltipfieldconfig)
<span id="gantttasktooltipfieldid"></span>[`GanttTaskTooltipFieldId`](/api/gantt/plugin/#gantttasktooltipfieldid)
<span id="gantttasktooltiphook"></span>[`GanttTaskTooltipHook`](/api/gantt/plugin/#gantttasktooltiphook)
<span id="gantttimelineheaderelementrenderer"></span>[`GanttTimelineHeaderElementRenderer`](/api/gantt/visuals/#gantttimelineheaderelementrenderer)
<span id="gantttimelineheaderplugin"></span>[`GanttTimelineHeaderPlugin`](/api/gantt/visuals/#gantttimelineheaderplugin)
<span id="gantttimelineheaderrenderoptions"></span>[`GanttTimelineHeaderRenderOptions`](/api/gantt/visuals/#gantttimelineheaderrenderoptions)
<span id="gantttimelinenavigationoptions"></span>[`GanttTimelineNavigationOptions`](/api/gantt/extensions/#gantttimelinenavigationoptions)
<span id="gantttimelinenavigationruntime"></span>[`GanttTimelineNavigationRuntime`](/api/gantt/extensions/#gantttimelinenavigationruntime)
<span id="gantttimelinerange"></span>[`GanttTimelineRange`](/api/gantt/visuals/#gantttimelinerange)
<span id="gantttimerange"></span>[`GanttTimeRange`](/api/gantt/plugin/#gantttimerange)
<span id="gantttodaynavigationoptions"></span>[`GanttTodayNavigationOptions`](/api/gantt/extensions/#gantttodaynavigationoptions)
<span id="gantttoolbar"></span>[`GanttToolbar`](/api/gantt/extensions/#gantttoolbar)
<span id="gantttoolbarcolumnoption"></span>[`GanttToolbarColumnOption`](/api/gantt/extensions/#gantttoolbarcolumnoption)
<span id="gantttoolbarcontrols"></span>[`GanttToolbarControls`](/api/gantt/extensions/#gantttoolbarcontrols)
<span id="gantttoolbardependencies"></span>[`ganttToolbarDependencies`](/api/gantt/extensions/#gantttoolbardependencies)
<span id="gantttoolbaroptions"></span>[`GanttToolbarOptions`](/api/gantt/extensions/#gantttoolbaroptions)
<span id="gantttoolbarquickwinaction"></span>[`GanttToolbarQuickWinAction`](/api/gantt/extensions/#gantttoolbarquickwinaction)
<span id="gantttoolbarquickwinactionid"></span>[`GanttToolbarQuickWinActionId`](/api/gantt/extensions/#gantttoolbarquickwinactionid)
<span id="gantttoolbarquickwinactions"></span>[`GanttToolbarQuickWinActions`](/api/gantt/extensions/#gantttoolbarquickwinactions)
<span id="gantttoolbarquickwinoptions"></span>[`GanttToolbarQuickWinOptions`](/api/gantt/extensions/#gantttoolbarquickwinoptions)
<span id="gantttoolbarvisuals"></span>[`GanttToolbarVisuals`](/api/gantt/extensions/#gantttoolbarvisuals)
<span id="ganttvalidationcontext"></span>[`GanttValidationContext`](/api/gantt/extensions/#ganttvalidationcontext)
<span id="ganttvalidationdecision"></span>[`GanttValidationDecision`](/api/gantt/extensions/#ganttvalidationdecision)
<span id="ganttvalidationhandleroptions"></span>[`GanttValidationHandlerOptions`](/api/gantt/extensions/#ganttvalidationhandleroptions)
<span id="ganttvalidationreject"></span>[`GanttValidationReject`](/api/gantt/extensions/#ganttvalidationreject)
<span id="ganttvisualconfig"></span>[`GanttVisualConfig`](/api/gantt/visuals/#ganttvisualconfig)
<span id="ganttwarninglabelsconfig"></span>[`GanttWarningLabelsConfig`](/api/gantt/plugin/#ganttwarninglabelsconfig)
<span id="ganttzoomsetleveldetail"></span>[`GanttZoomSetLevelDetail`](/api/gantt/visuals/#ganttzoomsetleveldetail)
<span id="getanchoroffset"></span>[`getAnchorOffset`](/api/gantt/visuals/#getanchoroffset)
<span id="getcsvexportplugin"></span>[`getCsvExportPlugin`](/api/gantt/extensions/#getcsvexportplugin)
<span id="getdefaultdependencydropdowntype"></span>[`getDefaultDependencyDropdownType`](/api/gantt/extensions/#getdefaultdependencydropdowntype)
<span id="getganttbaselinecaptureruntime"></span>[`getGanttBaselineCaptureRuntime`](/api/gantt/extensions/#getganttbaselinecaptureruntime)
<span id="getganttcolumnpresetprops"></span>[`getGanttColumnPresetProps`](/api/gantt/columns/#getganttcolumnpresetprops)
<span id="getganttdependencydropdowncellbadges"></span>[`getGanttDependencyDropdownCellBadges`](/api/gantt/extensions/#getganttdependencydropdowncellbadges)
<span id="getganttdependencydropdownsearchtext"></span>[`getGanttDependencyDropdownSearchText`](/api/gantt/extensions/#getganttdependencydropdownsearchtext)
<span id="getganttdependencydropdowntasks"></span>[`getGanttDependencyDropdownTasks`](/api/gantt/extensions/#getganttdependencydropdowntasks)
<span id="getganttdependencydropdownvalue"></span>[`getGanttDependencyDropdownValue`](/api/gantt/extensions/#getganttdependencydropdownvalue)
<span id="getgantttimelinenavigationruntime"></span>[`getGanttTimelineNavigationRuntime`](/api/gantt/extensions/#getgantttimelinenavigationruntime)
<span id="getlevelbyid"></span>[`getLevelById`](/api/gantt/visuals/#getlevelbyid)
<span id="getlevelindex"></span>[`getLevelIndex`](/api/gantt/visuals/#getlevelindex)
<span id="getnextscrollleft"></span>[`getNextScrollLeft`](/api/gantt/visuals/#getnextscrollleft)
<span id="getpersistencerecipemetadata"></span>[`getPersistenceRecipeMetadata`](/api/gantt/extensions/#getpersistencerecipemetadata)
<span id="getprojecttimelinerange"></span>[`getProjectTimelineRange`](/api/gantt/visuals/#getprojecttimelinerange)
<span id="getzoomanchordate"></span>[`getZoomAnchorDate`](/api/gantt/visuals/#getzoomanchordate)
<span id="getzoompresetconfig"></span>[`getZoomPresetConfig`](/api/gantt/columns/#getzoompresetconfig)
<span id="hardconstraintconflict"></span>[`HardConstraintConflict`](/api/gantt/scheduling/#hardconstraintconflict)
<span id="hascustomgantteditordateformat"></span>[`hasCustomGanttEditorDateFormat`](/api/gantt/plugin/#hascustomgantteditordateformat)
<span id="inmemoryassignmentstore"></span>[`InMemoryAssignmentStore`](/api/gantt/data-model/#inmemoryassignmentstore)
<span id="inmemoryresourcestore"></span>[`InMemoryResourceStore`](/api/gantt/data-model/#inmemoryresourcestore)
<span id="inmemorytaskstore"></span>[`InMemoryTaskStore`](/api/gantt/data-model/#inmemorytaskstore)
<span id="invalidtaskconstraintissue"></span>[`InvalidTaskConstraintIssue`](/api/gantt/scheduling/#invalidtaskconstraintissue)
<span id="isganttaddtaskrow"></span>[`isGanttAddTaskRow`](/api/gantt/extensions/#isganttaddtaskrow)
<span id="isganttdependencytype"></span>[`isGanttDependencyType`](/api/gantt/extensions/#isganttdependencytype)
<span id="listgantttoolbarquickwinactions"></span>[`listGanttToolbarQuickWinActions`](/api/gantt/extensions/#listgantttoolbarquickwinactions)
<span id="lockedphasevalidatoroptions"></span>[`LockedPhaseValidatorOptions`](/api/gantt/extensions/#lockedphasevalidatoroptions)
<span id="manualdependencyviolation"></span>[`ManualDependencyViolation`](/api/gantt/scheduling/#manualdependencyviolation)
<span id="missingdependencytaskissue"></span>[`MissingDependencyTaskIssue`](/api/gantt/scheduling/#missingdependencytaskissue)
<span id="normalizeganttdependencydropdownallowedtypes"></span>[`normalizeGanttDependencyDropdownAllowedTypes`](/api/gantt/extensions/#normalizeganttdependencydropdownallowedtypes)
<span id="normalizeganttdependencydropdownvalues"></span>[`normalizeGanttDependencyDropdownValues`](/api/gantt/extensions/#normalizeganttdependencydropdownvalues)
<span id="normalizepinnedtaskcolumns"></span>[`normalizePinnedTaskColumns`](/api/gantt/columns/#normalizepinnedtaskcolumns)
<span id="normalizetimelineheaderlabel"></span>[`normalizeTimelineHeaderLabel`](/api/gantt/visuals/#normalizetimelineheaderlabel)
<span id="normalizetimelinezoomconfig"></span>[`normalizeTimelineZoomConfig`](/api/gantt/visuals/#normalizetimelinezoomconfig)
<span id="parsedependencydropdowndisplayvalue"></span>[`parseDependencyDropdownDisplayValue`](/api/gantt/extensions/#parsedependencydropdowndisplayvalue)
<span id="parseganttdateinput"></span>[`parseGanttDateInput`](/api/gantt/plugin/#parseganttdateinput)
<span id="parseprojectsnapshotjson"></span>[`parseProjectSnapshotJson`](/api/gantt/data-model/#parseprojectsnapshotjson)
<span id="parsetasktypevalue"></span>[`parseTaskTypeValue`](/api/gantt/data-model/#parsetasktypevalue)
<span id="postgresstatement"></span>[`PostgresStatement`](/api/gantt/extensions/#postgresstatement)
<span id="printganttcontainer"></span>[`printGanttContainer`](/api/gantt/extensions/#printganttcontainer)
<span id="project_snapshot_table"></span>[`PROJECT_SNAPSHOT_TABLE`](/api/gantt/extensions/#project_snapshot_table)
<span id="projectsnapshot"></span>[`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)
<span id="projectsnapshotgraphqladapter"></span>[`ProjectSnapshotGraphqlAdapter`](/api/gantt/extensions/#projectsnapshotgraphqladapter)
<span id="projectsnapshotgraphqladapteroptions"></span>[`ProjectSnapshotGraphqlAdapterOptions`](/api/gantt/extensions/#projectsnapshotgraphqladapteroptions)
<span id="projectsnapshotgraphqlerror"></span>[`ProjectSnapshotGraphqlError`](/api/gantt/extensions/#projectsnapshotgraphqlerror)
<span id="projectsnapshotgraphqlerrorcode"></span>[`ProjectSnapshotGraphqlErrorCode`](/api/gantt/extensions/#projectsnapshotgraphqlerrorcode)
<span id="projectsnapshotgraphqlerrordetails"></span>[`ProjectSnapshotGraphqlErrorDetails`](/api/gantt/extensions/#projectsnapshotgraphqlerrordetails)
<span id="projectsnapshotgraphqlrequestoptions"></span>[`ProjectSnapshotGraphqlRequestOptions`](/api/gantt/extensions/#projectsnapshotgraphqlrequestoptions)
<span id="projectsnapshotjsonoptions"></span>[`ProjectSnapshotJsonOptions`](/api/gantt/data-model/#projectsnapshotjsonoptions)
<span id="projectsnapshotjsonrecipe"></span>[`ProjectSnapshotJsonRecipe`](/api/gantt/extensions/#projectsnapshotjsonrecipe)
<span id="projectsnapshotjsonrecipeoptions"></span>[`ProjectSnapshotJsonRecipeOptions`](/api/gantt/extensions/#projectsnapshotjsonrecipeoptions)
<span id="projectsnapshotparsefailure"></span>[`ProjectSnapshotParseFailure`](/api/gantt/data-model/#projectsnapshotparsefailure)
<span id="projectsnapshotparseresult"></span>[`ProjectSnapshotParseResult`](/api/gantt/data-model/#projectsnapshotparseresult)
<span id="projectsnapshotparsesuccess"></span>[`ProjectSnapshotParseSuccess`](/api/gantt/data-model/#projectsnapshotparsesuccess)
<span id="projectsnapshotpersistencerecipe"></span>[`ProjectSnapshotPersistenceRecipe`](/api/gantt/extensions/#projectsnapshotpersistencerecipe)
<span id="projectsnapshotpostgreserror"></span>[`ProjectSnapshotPostgresError`](/api/gantt/extensions/#projectsnapshotpostgreserror)
<span id="projectsnapshotpostgreserrorcode"></span>[`ProjectSnapshotPostgresErrorCode`](/api/gantt/extensions/#projectsnapshotpostgreserrorcode)
<span id="projectsnapshotpostgreserrordetails"></span>[`ProjectSnapshotPostgresErrorDetails`](/api/gantt/extensions/#projectsnapshotpostgreserrordetails)
<span id="projectsnapshotpostgresoptions"></span>[`ProjectSnapshotPostgresOptions`](/api/gantt/extensions/#projectsnapshotpostgresoptions)
<span id="projectsnapshotpostgresrecipe"></span>[`ProjectSnapshotPostgresRecipe`](/api/gantt/extensions/#projectsnapshotpostgresrecipe)
<span id="projectsnapshotpostgresrow"></span>[`ProjectSnapshotPostgresRow`](/api/gantt/extensions/#projectsnapshotpostgresrow)
<span id="projectsnapshotrestadapter"></span>[`ProjectSnapshotRestAdapter`](/api/gantt/extensions/#projectsnapshotrestadapter)
<span id="projectsnapshotrestadapteroptions"></span>[`ProjectSnapshotRestAdapterOptions`](/api/gantt/extensions/#projectsnapshotrestadapteroptions)
<span id="projectsnapshotresterror"></span>[`ProjectSnapshotRestError`](/api/gantt/extensions/#projectsnapshotresterror)
<span id="projectsnapshotresterrorcode"></span>[`ProjectSnapshotRestErrorCode`](/api/gantt/extensions/#projectsnapshotresterrorcode)
<span id="projectsnapshotresterrordetails"></span>[`ProjectSnapshotRestErrorDetails`](/api/gantt/extensions/#projectsnapshotresterrordetails)
<span id="projectsnapshotrestrequestoptions"></span>[`ProjectSnapshotRestRequestOptions`](/api/gantt/extensions/#projectsnapshotrestrequestoptions)
<span id="projectsnapshotsqlexecutor"></span>[`ProjectSnapshotSqlExecutor`](/api/gantt/extensions/#projectsnapshotsqlexecutor)
<span id="projectsnapshotstate"></span>[`ProjectSnapshotState`](/api/gantt/extensions/#projectsnapshotstate)
<span id="projectsnapshotstoragerecipe"></span>[`ProjectSnapshotStorageRecipe`](/api/gantt/extensions/#projectsnapshotstoragerecipe)
<span id="projectsnapshotsupabaseadapter"></span>[`ProjectSnapshotSupabaseAdapter`](/api/gantt/extensions/#projectsnapshotsupabaseadapter)
<span id="projectvisibletaskbaranchors"></span>[`projectVisibleTaskBarAnchors`](/api/gantt/visuals/#projectvisibletaskbaranchors)
<span id="rendergantttimelineheader"></span>[`renderGanttTimelineHeader`](/api/gantt/visuals/#rendergantttimelineheader)
<span id="resolvedscheduleroptions"></span>[`ResolvedSchedulerOptions`](/api/gantt/scheduling/#resolvedscheduleroptions)
<span id="resolvedtimelinezoomconfig"></span>[`ResolvedTimelineZoomConfig`](/api/gantt/visuals/#resolvedtimelinezoomconfig)
<span id="resolvegantterrorlabel"></span>[`resolveGanttErrorLabel`](/api/gantt/plugin/#resolvegantterrorlabel)
<span id="resolvegantttimelinedateformatter"></span>[`resolveGanttTimelineDateFormatter`](/api/gantt/visuals/#resolvegantttimelinedateformatter)
<span id="resolveganttwarninglabel"></span>[`resolveGanttWarningLabel`](/api/gantt/plugin/#resolveganttwarninglabel)
<span id="resolvehiddencolumnsfromtoolbarselection"></span>[`resolveHiddenColumnsFromToolbarSelection`](/api/gantt/extensions/#resolvehiddencolumnsfromtoolbarselection)
<span id="resolvehighlightvisibility"></span>[`resolveHighlightVisibility`](/api/gantt/visuals/#resolvehighlightvisibility)
<span id="resolvetaskedit"></span>[`resolveTaskEdit`](/api/gantt/scheduling/#resolvetaskedit)
<span id="resolvetasktypeafterdurationedit"></span>[`resolveTaskTypeAfterDurationEdit`](/api/gantt/data-model/#resolvetasktypeafterdurationedit)
<span id="resourceentity"></span>[`ResourceEntity`](/api/gantt/data-model/#resourceentity)
<span id="resourceid"></span>[`ResourceId`](/api/gantt/data-model/#resourceid)
<span id="resourcelevelingadjustmentconflict"></span>[`ResourceLevelingAdjustmentConflict`](/api/gantt/scheduling/#resourcelevelingadjustmentconflict)
<span id="resourceloadsegment"></span>[`ResourceLoadSegment`](/api/gantt/visuals/#resourceloadsegment)
<span id="resourceoverallocationconflict"></span>[`ResourceOverallocationConflict`](/api/gantt/scheduling/#resourceoverallocationconflict)
<span id="resourceoverallocationsummaryrecipe"></span>[`ResourceOverallocationSummaryRecipe`](/api/gantt/extensions/#resourceoverallocationsummaryrecipe)
<span id="resourceplanningrowdata"></span>[`ResourcePlanningRowData`](/api/gantt/visuals/#resourceplanningrowdata)
<span id="resourcestore"></span>[`ResourceStore`](/api/gantt/data-model/#resourcestore)
<span id="revogridcsvexportplugin"></span>[`RevoGridCsvExportPlugin`](/api/gantt/extensions/#revogridcsvexportplugin)
<span id="roleguardvalidatoroptions"></span>[`RoleGuardValidatorOptions`](/api/gantt/extensions/#roleguardvalidatoroptions)
<span id="scheduledtask"></span>[`ScheduledTask`](/api/gantt/scheduling/#scheduledtask)
<span id="scheduledtaskkind"></span>[`ScheduledTaskKind`](/api/gantt/scheduling/#scheduledtaskkind)
<span id="scheduleorigin"></span>[`ScheduleOrigin`](/api/gantt/scheduling/#scheduleorigin)
<span id="schedulerconflict"></span>[`SchedulerConflict`](/api/gantt/scheduling/#schedulerconflict)
<span id="schedulercycleissue"></span>[`SchedulerCycleIssue`](/api/gantt/scheduling/#schedulercycleissue)
<span id="schedulerdatavalidationcode"></span>[`SchedulerDataValidationCode`](/api/gantt/scheduling/#schedulerdatavalidationcode)
<span id="schedulerdatavalidationissue"></span>[`SchedulerDataValidationIssue`](/api/gantt/scheduling/#schedulerdatavalidationissue)
<span id="schedulerengine"></span>[`SchedulerEngine`](/api/gantt/scheduling/#schedulerengine)
<span id="schedulerissue"></span>[`SchedulerIssue`](/api/gantt/scheduling/#schedulerissue)
<span id="scheduleroptions"></span>[`SchedulerOptions`](/api/gantt/scheduling/#scheduleroptions)
<span id="schedulingresult"></span>[`SchedulingResult`](/api/gantt/scheduling/#schedulingresult)
<span id="scrollgantttotoday"></span>[`scrollGanttToToday`](/api/gantt/extensions/#scrollgantttotoday)
<span id="shouldhandlewheeltrigger"></span>[`shouldHandleWheelTrigger`](/api/gantt/visuals/#shouldhandlewheeltrigger)
<span id="shouldreplayrawgantttaskpatch"></span>[`shouldReplayRawGanttTaskPatch`](/api/gantt/plugin/#shouldreplayrawgantttaskpatch)
<span id="supabaselikeclient"></span>[`SupabaseLikeClient`](/api/gantt/extensions/#supabaselikeclient)
<span id="supabaselikeerror"></span>[`SupabaseLikeError`](/api/gantt/extensions/#supabaselikeerror)
<span id="supabaselikefilterbuilder"></span>[`SupabaseLikeFilterBuilder`](/api/gantt/extensions/#supabaselikefilterbuilder)
<span id="supabaselikemaybesinglequery"></span>[`SupabaseLikeMaybeSingleQuery`](/api/gantt/extensions/#supabaselikemaybesinglequery)
<span id="supabaselikeresult"></span>[`SupabaseLikeResult`](/api/gantt/extensions/#supabaselikeresult)
<span id="supabaselikesinglequery"></span>[`SupabaseLikeSingleQuery`](/api/gantt/extensions/#supabaselikesinglequery)
<span id="supabaseliketable"></span>[`SupabaseLikeTable`](/api/gantt/extensions/#supabaseliketable)
<span id="supabaselikeupsertbuilder"></span>[`SupabaseLikeUpsertBuilder`](/api/gantt/extensions/#supabaselikeupsertbuilder)
<span id="task_type_labels"></span>[`TASK_TYPE_LABELS`](/api/gantt/data-model/#task_type_labels)
<span id="task_type_values"></span>[`TASK_TYPE_VALUES`](/api/gantt/data-model/#task_type_values)
<span id="taskbaranchorpoint"></span>[`TaskBarAnchorPoint`](/api/gantt/visuals/#taskbaranchorpoint)
<span id="taskconstrainttype"></span>[`TaskConstraintType`](/api/gantt/data-model/#taskconstrainttype)
<span id="taskconstrainttypeeditvalue"></span>[`TaskConstraintTypeEditValue`](/api/gantt/scheduling/#taskconstrainttypeeditvalue)
<span id="taskdetailpopoverrecipe"></span>[`TaskDetailPopoverRecipe`](/api/gantt/extensions/#taskdetailpopoverrecipe)
<span id="taskdetailpopoverrecipeoptions"></span>[`TaskDetailPopoverRecipeOptions`](/api/gantt/extensions/#taskdetailpopoverrecipeoptions)
<span id="taskeditfailure"></span>[`TaskEditFailure`](/api/gantt/scheduling/#taskeditfailure)
<span id="taskeditlabeloverrides"></span>[`TaskEditLabelOverrides`](/api/gantt/scheduling/#taskeditlabeloverrides)
<span id="taskeditoptions"></span>[`TaskEditOptions`](/api/gantt/scheduling/#taskeditoptions)
<span id="taskeditresult"></span>[`TaskEditResult`](/api/gantt/scheduling/#taskeditresult)
<span id="taskeditsuccess"></span>[`TaskEditSuccess`](/api/gantt/scheduling/#taskeditsuccess)
<span id="taskeffortmode"></span>[`TaskEffortMode`](/api/gantt/data-model/#taskeffortmode)
<span id="taskentity"></span>[`TaskEntity`](/api/gantt/data-model/#taskentity)
<span id="taskgridassignee"></span>[`TaskGridAssignee`](/api/gantt/visuals/#taskgridassignee)
<span id="taskgridconfig"></span>[`TaskGridConfig`](/api/gantt/plugin/#taskgridconfig)
<span id="taskgridscaleconfig"></span>[`TaskGridScaleConfig`](/api/gantt/plugin/#taskgridscaleconfig)
<span id="taskgridscaleoptions"></span>[`TaskGridScaleOptions`](/api/gantt/plugin/#taskgridscaleoptions)
<span id="taskid"></span>[`TaskId`](/api/gantt/data-model/#taskid)
<span id="taskmodeeditvalue"></span>[`TaskModeEditValue`](/api/gantt/scheduling/#taskmodeeditvalue)
<span id="taskrowdiagnostics"></span>[`TaskRowDiagnostics`](/api/gantt/visuals/#taskrowdiagnostics)
<span id="taskrowprojectionoptions"></span>[`TaskRowProjectionOptions`](/api/gantt/visuals/#taskrowprojectionoptions)
<span id="tasksplitrange"></span>[`TaskSplitRange`](/api/gantt/data-model/#tasksplitrange)
<span id="taskstatus"></span>[`TaskStatus`](/api/gantt/data-model/#taskstatus)
<span id="taskstore"></span>[`TaskStore`](/api/gantt/data-model/#taskstore)
<span id="tasktablecolumnprop"></span>[`TaskTableColumnProp`](/api/gantt/columns/#tasktablecolumnprop)
<span id="tasktreerow"></span>[`TaskTreeRow`](/api/gantt/data-model/#tasktreerow)
<span id="tasktype"></span>[`TaskType`](/api/gantt/data-model/#tasktype)
<span id="tasktypeoption"></span>[`TaskTypeOption`](/api/gantt/data-model/#tasktypeoption)
<span id="taskupdate"></span>[`TaskUpdate`](/api/gantt/data-model/#taskupdate)
<span id="taskworkflowstatus"></span>[`TaskWorkflowStatus`](/api/gantt/data-model/#taskworkflowstatus)
<span id="timeline_zoom_preset_levels"></span>[`TIMELINE_ZOOM_PRESET_LEVELS`](/api/gantt/visuals/#timeline_zoom_preset_levels)
<span id="timelineband"></span>[`TimelineBand`](/api/gantt/visuals/#timelineband)
<span id="timelinebandunit"></span>[`TimelineBandUnit`](/api/gantt/visuals/#timelinebandunit)
<span id="timelinedateformatter"></span>[`TimelineDateFormatter`](/api/gantt/visuals/#timelinedateformatter)
<span id="timelinedateformattercontext"></span>[`TimelineDateFormatterContext`](/api/gantt/visuals/#timelinedateformattercontext)
<span id="timelineflagline"></span>[`TimelineFlagLine`](/api/gantt/visuals/#timelineflagline)
<span id="timelineheadercell"></span>[`TimelineHeaderCell`](/api/gantt/visuals/#timelineheadercell)
<span id="timelineheaderhighlightrange"></span>[`TimelineHeaderHighlightRange`](/api/gantt/visuals/#timelineheaderhighlightrange)
<span id="timelineheaderlabel"></span>[`TimelineHeaderLabel`](/api/gantt/visuals/#timelineheaderlabel)
<span id="timelineheaderlabelparts"></span>[`TimelineHeaderLabelParts`](/api/gantt/visuals/#timelineheaderlabelparts)
<span id="timelineheaderrowconfig"></span>[`TimelineHeaderRowConfig`](/api/gantt/visuals/#timelineheaderrowconfig)
<span id="timelineheaderrowmodel"></span>[`TimelineHeaderRowModel`](/api/gantt/visuals/#timelineheaderrowmodel)
<span id="timelinehighlightvisibility"></span>[`TimelineHighlightVisibility`](/api/gantt/visuals/#timelinehighlightvisibility)
<span id="timelinescale"></span>[`TimelineScale`](/api/gantt/visuals/#timelinescale)
<span id="timelinescaleconfig"></span>[`TimelineScaleConfig`](/api/gantt/visuals/#timelinescaleconfig)
<span id="timelinetaskinteractionrange"></span>[`TimelineTaskInteractionRange`](/api/gantt/visuals/#timelinetaskinteractionrange)
<span id="timelinetick"></span>[`TimelineTick`](/api/gantt/visuals/#timelinetick)
<span id="timelinetickunit"></span>[`TimelineTickUnit`](/api/gantt/visuals/#timelinetickunit)
<span id="timelinevisibledaterange"></span>[`TimelineVisibleDateRange`](/api/gantt/visuals/#timelinevisibledaterange)
<span id="timelinevisiblespan"></span>[`TimelineVisibleSpan`](/api/gantt/visuals/#timelinevisiblespan)
<span id="timelinewheelinput"></span>[`TimelineWheelInput`](/api/gantt/visuals/#timelinewheelinput)
<span id="timelinezoomanchorcontext"></span>[`TimelineZoomAnchorContext`](/api/gantt/visuals/#timelinezoomanchorcontext)
<span id="timelinezoomconfig"></span>[`TimelineZoomConfig`](/api/gantt/visuals/#timelinezoomconfig)
<span id="timelinezoomcontroller"></span>[`TimelineZoomController`](/api/gantt/visuals/#timelinezoomcontroller)
<span id="timelinezoomlevel"></span>[`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)
<span id="timelinezoommode"></span>[`TimelineZoomMode`](/api/gantt/visuals/#timelinezoommode)
<span id="timelinezoompreset"></span>[`TimelineZoomPreset`](/api/gantt/columns/#timelinezoompreset)
<span id="timelinezoomtransition"></span>[`TimelineZoomTransition`](/api/gantt/visuals/#timelinezoomtransition)
<span id="toggleganttcriticalpath"></span>[`toggleGanttCriticalPath`](/api/gantt/extensions/#toggleganttcriticalpath)
<span id="topologicallysortdependencygraph"></span>[`topologicallySortDependencyGraph`](/api/gantt/scheduling/#topologicallysortdependencygraph)
<span id="topologicalsortresult"></span>[`TopologicalSortResult`](/api/gantt/scheduling/#topologicalsortresult)
<span id="toprojectsnapshotrow"></span>[`toProjectSnapshotRow`](/api/gantt/extensions/#toprojectsnapshotrow)
<span id="validateganttbeforetaskchange"></span>[`validateGanttBeforeTaskChange`](/api/gantt/events/#validateganttbeforetaskchange)
<span id="visibletaskbaranchors"></span>[`VisibleTaskBarAnchors`](/api/gantt/visuals/#visibletaskbaranchors)
<span id="visibletaskbarprojection"></span>[`VisibleTaskBarProjection`](/api/gantt/visuals/#visibletaskbarprojection)
<span id="wheelzoomtrigger"></span>[`WheelZoomTrigger`](/api/gantt/visuals/#wheelzoomtrigger)
<span id="zoomanchormode"></span>[`ZoomAnchorMode`](/api/gantt/visuals/#zoomanchormode)

---

# Gantt Panel Resize Plugin

URL: https://pro.rv-grid.com/api/gantt-panel-resize-plugin/
Source: src/content/docs/api/gantt-panel-resize-plugin.md

### `GanttPanelResizeDetail`

Payload emitted with each `gantt-panel-resize` event.

```ts
interface GanttPanelResizeDetail {
  /** The current width of the gantt panel in pixels. */
    readonly width: number
}
```

---

### `GanttPanelResizePluginConfig`

```ts
interface GanttPanelResizePluginConfig {
  /**
     * Initial width of the gantt (colPinEnd) panel in pixels or as a percentage
     * of the grid width (e.g. `"40%"`).
     * Defaults to the current rendered width of the panel.
     */
    initialWidth?: number | string
}
```

---

### `GanttPanelResizePlugin`

GanttPanelResizePlugin adds a drag handle on the left edge of the
pinned-end (gantt chart) viewport, allowing the user to resize the split
between the task-list columns (rgCol) and the gantt chart (colPinEnd).

Dragging the handle left expands the gantt panel; dragging right shrinks it.
An `gantt-panel-resize` event is emitted on the revogrid element during and
after each drag with `{ width: number }` in its detail.

```ts
class GanttPanelResizePlugin {
  /**
     * Programmatically set the gantt panel width.
     */
  setPanelWidth(width: number): void;

  /**
     * Returns the current gantt panel (colPinEnd) width in pixels, or null if
     * the viewport is not yet rendered.
     */
  getPanelWidth(): number | null;
}
```

---

# Gantt Task Editor Dialog

URL: https://pro.rv-grid.com/api/gantt-task-editor-dialog/
Source: src/content/docs/api/gantt-task-editor-dialog.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  ganttTaskEditorDialog?: GanttTaskEditorDialogOptions;
  'gantt-task-editor-dialog'?: GanttTaskEditorDialogOptions
}
```

## Plugin API

### `DependencyEditor`

```ts
export function DependencyEditor({
  direction,
  task,
  tasks,
  drafts,
  localeText,
  onChange,
}: DependencyEditorProps);
```

---

### `DependencyEditorProps`

```ts
interface DependencyEditorProps {
  readonly direction: 'predecessors' | 'successors';
  readonly task: TaskEntity | null;
  readonly tasks: readonly TaskEntity[];
  readonly drafts: readonly GanttTaskEditorDialogDependencyDraft[];
  readonly localeText: GanttTaskEditorDialogLocaleText;
  readonly onChange: (drafts: readonly GanttTaskEditorDialogDependencyDraft[]) => void
}
```

---

### `FieldControl`

Selects a focused dialog adapter from the shared task-field editor kind.

```ts
export function FieldControl(props: FieldControlProps);
```

---

### `FieldControlProps`

```ts
interface FieldControlProps {
  readonly field: TaskEditorFieldSchema;
  readonly values: TaskEditorFormValues;
  readonly localeText: GanttTaskEditorDialogLocaleText;
  readonly dateFormatProject?: GanttPluginConfig | null;
  readonly dateTimeEnabled?: boolean;
  readonly resourceSelection?: ResourceSelection;
  readonly colorPalette?: ResolvedGanttColorPalette | null;
  readonly onChange: (values: TaskEditorFormValues) => void;
  readonly onDateTimeToggle?: (enabled: boolean) => void
}
```

---

### `ResourceSelection`

```ts
interface ResourceSelection {
  readonly resources: readonly ResourceEntity[];
  readonly selectedResourceIds: readonly ResourceId[];
  readonly onChange: (resourceIds: readonly ResourceId[]) => void
}
```

---

### `resolveTaskEditorTabs`

```ts
export function resolveTaskEditorTabs(
  options: GanttTaskEditorTabsOptions | undefined,
  localeText: GanttTaskEditorDialogLocaleText,
  legacyFields: readonly TaskEditorFieldId[],
): readonly ResolvedTaskEditorTab[];
```

---

### `TaskEditorDomRendererHost`

```ts
export function TaskEditorDomRendererHost({
  renderer,
  context,
  className,
}: {
  readonly renderer: GanttTaskEditorDomRenderer;
  readonly context: GanttTaskEditorRendererContext;
  readonly className?: string;
});
```

---

### `ResolvedTaskEditorTab`

```ts
interface ResolvedTaskEditorTab {
  readonly id: string;
  readonly title: string;
  readonly builtin: TaskEditorTabId | null;
  readonly fields: readonly TaskEditorFieldId[];
  readonly renderer?: GanttTaskEditorDomRenderer
}
```

---

### `TaskEditorTabId`

```ts
export type TaskEditorTabId = 'details' | 'advanced' | 'predecessors' | 'successors' | 'assignments' | 'notes';
```

---

### `DETAIL_FIELDS`

```ts
DETAIL_FIELDS: readonly TaskEditorFieldId[];
```

---

### `ADVANCED_FIELDS`

```ts
ADVANCED_FIELDS: readonly TaskEditorFieldId[];
```

---

### `ASSIGNMENT_FIELDS`

```ts
ASSIGNMENT_FIELDS: readonly TaskEditorFieldId[];
```

---

### `NOTES_FIELDS`

```ts
NOTES_FIELDS: readonly TaskEditorFieldId[];
```

---

### `DEFAULT_FIELDS`

```ts
DEFAULT_FIELDS: readonly TaskEditorFieldId[];
```

---

### `TAB_LABELS`

```ts
TAB_LABELS: {
  details: string;
  advanced: string;
  predecessors: string;
  successors: string;
  assignments: string;
  notes: string;
};
```

---

### `DEPENDENCY_TYPE_OPTIONS`

```ts
DEPENDENCY_TYPE_OPTIONS: readonly { readonly label: string; readonly value: DependencyType; }[];
```

---

### `createTaskEditorDialogLocaleText`

```ts
export function createTaskEditorDialogLocaleText(
  localeText: GanttTaskEditorDialogLocaleTextOptions | undefined,
  inheritedLocaleText?: GanttTaskEditorDialogLocaleTextOptions,
): GanttTaskEditorDialogLocaleText;
```

---

### `DEFAULT_TASK_EDITOR_DIALOG_LOCALE_TEXT`

```ts
DEFAULT_TASK_EDITOR_DIALOG_LOCALE_TEXT: {
  title: string;
  description: string;
  fallbackTaskTitle: string;
  closeLabel: string;
  closeButtonText: string;
  applyLabel: string;
  resetLabel: string;
  menuItemName: string;
  tabListAriaLabel: string;
  readOnlyLabel: string;
  noResourcesAvailable: string;
  noAssignedResources: string;
  assignedResourcesAriaLabel: string;
  colorPaletteAriaLabel: string;
  defaultColorOption: string;
  projectDefaultOption: string;
  noConstraintOption: string;
  timeToggleLabel: string;
  switchOnLabel: string;
  switchOffLabel: string;
  manualSchedulingOnLabel: string;
  manualSchedulingOffLabel: string;
  dependencyTargetLabel: { predecessors: string; successors: string; };
  dependencyEmptyLabel: { predecessors: string; successors: string; };
  dependencySearch: { predecessors: { placeholder: string; ariaLabel: string; empty: string; }; successors: { placeholder: string; ariaLabel: string; empty: string; }; };
  resourcesSearch: { placeholder: string; ariaLabel: string; empty: string; };
  dependencyTypeLabel: string;
  dependencyLagDaysLabel: string;
  removeDependencyLabel: (targetLabel: string) => string;
  removeDependencyButton: string;
  addDependencyButton: { predecessors: string; successors: string; };
  tabs: { details: string; advanced: string; predecessors: string; successors: string; assignments: string; notes: string; };
  dependencyTypes: { 'finish-to-start': string; 'start-to-start': string; 'finish-to-finish': string; 'start-to-finish': string; };
  fields: Partial<Record<TaskEditorFieldId, string>>;
  fieldOptions: Partial<Record<TaskEditorFieldId, readonly TaskEditorFieldOption<string>[]>>;
  status: { ready: string; closed: string; changesSaved: string; noChangesToSave: string; readOnlyProject: string; fixValidationErrors: string; saveFailed: string; };
  validation: { checkRequiredFields: string; couldNotSave: string; fieldError: (error: TaskEditorSubmitError) => string; resourceNotFound: (resourceId: string) => string; taskCannotDependOnItself: string; predecessorTaskNotFound: (taskId: string) => string; successorTaskNotFound: (taskId: string) => string; dependencyMustIncludeCurrentTask: string; duplicateDependencyLinks: string; };
};
```

---

### `GanttTaskEditorDialog`

```ts
export function GanttTaskEditorDialog({
  grid,
  task,
  tasks,
  resources,
  assignments,
  dependencies,
  project,
  allowedTaskTypes,
  calendars,
  options,
  open,
  status,
  onClose,
  onReset,
  onSubmit,
}: GanttTaskEditorDialogProps);
```

---

### `GanttTaskEditorDialogSubmitContext`

```ts
interface GanttTaskEditorDialogSubmitContext {
  readonly grid: HTMLRevoGridElement;
  readonly task: TaskEntity;
  readonly values: TaskEditorFormValues;
  readonly result: TaskEditorSubmitSuccess;
  readonly assignmentResourceIds: readonly ResourceId[];
  readonly assignments: readonly AssignmentEntity[];
  readonly assignmentsChanged: boolean;
  readonly dependencyDrafts: readonly GanttTaskEditorDialogDependencyDraft[];
  readonly dependencies: readonly DependencyEntity[];
  readonly dependenciesChanged: boolean;
  readonly customValues: Readonly<Record<string, unknown>>
}
```

---

### `GanttTaskEditorDraftState`

```ts
interface GanttTaskEditorDraftState {
  readonly values: TaskEditorFormValues;
  readonly resourceIds: readonly ResourceId[];
  readonly dependencyDrafts: readonly GanttTaskEditorDialogDependencyDraft[];
  readonly customValues: Readonly<Record<string, unknown>>;
  readonly validationErrors: readonly string[];
  readonly dirty: boolean
}
```

---

### `GanttTaskEditorDraftController`

```ts
interface GanttTaskEditorDraftController {
  getState(): GanttTaskEditorDraftState;
  setValues(values: Partial<TaskEditorFormValues>): void;
  setResourceIds(resourceIds: readonly ResourceId[]): void;
  setDependencyDrafts(drafts: readonly GanttTaskEditorDialogDependencyDraft[]): void;
  setCustomValue(key: string, value: unknown): void;
  setValidationErrors(errors: readonly string[]): void;
  reset(): void;
  close(): void;
  submit(): void
}
```

---

### `GanttTaskEditorRendererContext`

```ts
interface GanttTaskEditorRendererContext {
  readonly grid: HTMLRevoGridElement;
  readonly task: TaskEntity | null;
  readonly project: ProjectSnapshot | null;
  readonly open: boolean;
  readonly status: string;
  readonly state: GanttTaskEditorDraftState;
  readonly controller: GanttTaskEditorDraftController
}
```

---

### `GanttTaskEditorRendererLifecycle`

```ts
interface GanttTaskEditorRendererLifecycle {
  update?(context: GanttTaskEditorRendererContext): void;
  destroy?(): void
}
```

---

### `GanttTaskEditorDomRenderer`

```ts
interface GanttTaskEditorDomRenderer {
  mount(container: HTMLElement, context: GanttTaskEditorRendererContext): void | GanttTaskEditorRendererLifecycle
}
```

---

### `GanttTaskEditorTabOptions`

```ts
interface GanttTaskEditorTabOptions {
  readonly title?: string;
  readonly hidden?: boolean;
  readonly fields?: readonly TaskEditorFieldId[];
  readonly renderer?: GanttTaskEditorDomRenderer
}
```

---

### `GanttTaskEditorTabsOptions`

```ts
interface GanttTaskEditorTabsOptions {
  readonly items?: Readonly<Record<string, false | GanttTaskEditorTabOptions>>;
  readonly order?: readonly string[]
}
```

---

### `GanttTaskEditorControlId`

```ts
export type GanttTaskEditorControlId =
  | 'header'
  | 'title'
  | 'description'
  | 'close'
  | 'tabs'
  | 'validation'
  | 'preview'
  | 'reset'
  | 'apply'
  | 'footer';
```

---

### `GanttTaskEditorDialogCustomization`

```ts
interface GanttTaskEditorDialogCustomization {
  readonly tabs?: GanttTaskEditorTabsOptions;
  readonly controls?: Partial<Record<GanttTaskEditorControlId, boolean>>;
  readonly editor?: GanttTaskEditorDomRenderer
}
```

---

### `GanttTaskEditorDialogResourcesOptions`

```ts
interface GanttTaskEditorDialogResourcesOptions {
  readonly editable?: boolean;
  readonly defaultAllocationUnits?: number;
  readonly defaultResponsibility?: string
}
```

---

### `GanttTaskEditorDialogDependencyDraft`

```ts
interface GanttTaskEditorDialogDependencyDraft {
  readonly id?: DependencyId;
  readonly predecessorTaskId: TaskId | '';
  readonly successorTaskId: TaskId | '';
  readonly type: DependencyType;
  readonly lagDays: number
}
```

---

### `GanttTaskEditorDialogSearchText`

```ts
interface GanttTaskEditorDialogSearchText {
  readonly placeholder: string;
  readonly ariaLabel: string;
  readonly empty: string
}
```

---

### `GanttTaskEditorDialogStatusText`

```ts
interface GanttTaskEditorDialogStatusText {
  readonly ready: string;
  readonly closed: string;
  readonly changesSaved: string;
  readonly noChangesToSave: string;
  readonly readOnlyProject: string;
  readonly fixValidationErrors: string;
  readonly saveFailed: string
}
```

---

### `GanttTaskEditorDialogValidationText`

```ts
interface GanttTaskEditorDialogValidationText {
  readonly checkRequiredFields: string;
  readonly couldNotSave: string;
  readonly fieldError: (error: TaskEditorSubmitError, fieldLabel: string) => string;
  readonly resourceNotFound: (resourceId: ResourceId) => string;
  readonly taskCannotDependOnItself: string;
  readonly predecessorTaskNotFound: (taskId: TaskId) => string;
  readonly successorTaskNotFound: (taskId: TaskId) => string;
  readonly dependencyMustIncludeCurrentTask: string;
  readonly duplicateDependencyLinks: string
}
```

---

### `GanttTaskEditorDialogLocaleText`

```ts
interface GanttTaskEditorDialogLocaleText {
  readonly title: string;
  readonly description: string;
  readonly fallbackTaskTitle: string;
  readonly closeLabel: string;
  readonly closeButtonText: string;
  readonly applyLabel: string;
  readonly resetLabel: string;
  readonly menuItemName: string;
  readonly tabListAriaLabel: string;
  readonly readOnlyLabel: string;
  readonly noResourcesAvailable: string;
  readonly noAssignedResources: string;
  readonly assignedResourcesAriaLabel: string;
  readonly colorPaletteAriaLabel: string;
  readonly defaultColorOption: string;
  readonly projectDefaultOption: string;
  readonly noConstraintOption: string;
  readonly timeToggleLabel: string;
  readonly switchOnLabel: string;
  readonly switchOffLabel: string;
  readonly manualSchedulingOnLabel: string;
  readonly manualSchedulingOffLabel: string;
  readonly dependencyTargetLabel: {
      readonly predecessors: string;
      readonly successors: string;
    };
  readonly dependencyEmptyLabel: {
      readonly predecessors: string;
      readonly successors: string;
    };
  readonly dependencySearch: {
      readonly predecessors: GanttTaskEditorDialogSearchText;
      readonly successors: GanttTaskEditorDialogSearchText;
    };
  readonly resourcesSearch: GanttTaskEditorDialogSearchText;
  readonly dependencyTypeLabel: string;
  readonly dependencyLagDaysLabel: string;
  readonly removeDependencyLabel: (targetLabel: string) => string;
  readonly removeDependencyButton: string;
  readonly addDependencyButton: {
      readonly predecessors: string;
      readonly successors: string;
    };
  readonly tabs: Record<TaskEditorTabId, string>;
  readonly dependencyTypes: Record<DependencyType, string>;
  readonly fields: Partial<Record<TaskEditorFieldId, string>>;
  readonly fieldOptions: Partial<Record<TaskEditorFieldId, readonly TaskEditorFieldOption[]>>;
  readonly status: GanttTaskEditorDialogStatusText;
  readonly validation: GanttTaskEditorDialogValidationText
}
```

---

### `GanttTaskEditorDialogLocaleTextOptions` (Extended from `gantt-task-editor-dialog.types.ts`)

```ts
export type GanttTaskEditorDialogLocaleTextOptions = Partial<Omit<
  GanttTaskEditorDialogLocaleText,
  | 'dependencyTargetLabel'
  | 'dependencyEmptyLabel'
  | 'dependencySearch'
  | 'resourcesSearch'
  | 'addDependencyButton'
  | 'tabs'
  | 'dependencyTypes'
  | 'fields'
  | 'fieldOptions'
  | 'status'
  | 'validation'
>> & {
  readonly dependencyTargetLabel?: Partial<GanttTaskEditorDialogLocaleText['dependencyTargetLabel']>;
  readonly dependencyEmptyLabel?: Partial<GanttTaskEditorDialogLocaleText['dependencyEmptyLabel']>;
  readonly dependencySearch?: {
    readonly predecessors?: Partial<GanttTaskEditorDialogSearchText>;
    readonly successors?: Partial<GanttTaskEditorDialogSearchText>;
  };
  readonly resourcesSearch?: Partial<GanttTaskEditorDialogSearchText>;
  readonly addDependencyButton?: Partial<GanttTaskEditorDialogLocaleText['addDependencyButton']>;
  readonly tabs?: Partial<Record<TaskEditorTabId, string>>;
  readonly dependencyTypes?: Partial<Record<DependencyType, string>>;
  readonly fields?: Partial<Record<TaskEditorFieldId, string>>;
  readonly fieldOptions?: Partial<Record<TaskEditorFieldId, readonly TaskEditorFieldOption[]>>;
  readonly status?: Partial<GanttTaskEditorDialogStatusText>;
  readonly validation?: Partial<GanttTaskEditorDialogValidationText>;
};
```

---

### `GanttTaskEditorDialogOptions`

```ts
interface GanttTaskEditorDialogOptions {
  readonly fields?: readonly TaskEditorFieldId[];
  readonly localeText?: GanttTaskEditorDialogLocaleTextOptions;
  readonly menuItemName?: string;
  readonly title?: string;
  readonly description?: string;
  readonly applyLabel?: string;
  readonly resetLabel?: string;
  readonly closeLabel?: string;
  /**
     * Controls the packaged row context-menu entry for opening the task editor.
     * Defaults to the Gantt context-menu setting. Set to `false` to remove only
     * the editor menu item, or `true` to keep it when `gantt.contextMenu` is
     * disabled.
     */
    readonly contextMenu?: boolean;
  /**
     * Opens the dialog immediately after the Gantt plugin creates a task. Defaults
     * to `true`. Set to `false` to keep task creation silent. This
     * covers task creation from the toolbar, row context menu, and custom
     * dispatches of the task-create event.
     */
    readonly openOnCreate?: boolean;
  /**
     * Controls the built-in resource assignment picker. Set to `false` to keep
     * the resources field read-only.
     */
    readonly resources?: false | GanttTaskEditorDialogResourcesOptions;
  /**
     * Configures task colors in the packaged editor. Omit to inherit the Gantt
     * context-menu palette; set to `false` to remove the editor field.
     */
    readonly colorPalette?: GanttColorPaletteConfig | false;
  /**
     * Shows the normalized TaskUpdate JSON preview. Intended for documentation,
     * diagnostics, and custom developer tooling; hidden by default for end-user UI.
     */
    readonly preview?: boolean;
  readonly readOnly?: boolean;
  readonly onSubmit?: (context: GanttTaskEditorDialogSubmitContext) => boolean | void | Promise<boolean | void>;
  readonly getTask?: (taskId: TaskId, grid: HTMLRevoGridElement) => TaskEntity | null | undefined;
  readonly customization?: GanttTaskEditorDialogCustomization
}
```

---

### `GanttTaskEditorDialogState`

```ts
interface GanttTaskEditorDialogState {
  readonly taskId: TaskId | null;
  readonly task: TaskEntity | null;
  readonly values: TaskEditorFormValues;
  readonly status: string
}
```

---

### `formatValue`

```ts
export function formatValue(value: unknown): string;
```

---

### `formatDateInputValue`

```ts
export function formatDateInputValue(value: unknown): string;
```

---

### `formatDateTimeInputValue`

```ts
export function formatDateTimeInputValue(value: unknown): string;
```

---

### `isEditableInputField`

```ts
export function isEditableInputField(field: TaskEditorFieldSchema): boolean;
```

---

### `cloneValues`

```ts
export function cloneValues(values: TaskEditorFormValues): TaskEditorFormValues;
```

---

### `hasActiveConstraint`

```ts
export function hasActiveConstraint(values: TaskEditorFormValues): boolean;
```

---

### `createNormalizedDialogValues`

```ts
export function createNormalizedDialogValues(values: TaskEditorFormValues): TaskEditorFormValues;
```

---

### `hasTimeGranularity`

```ts
export function hasTimeGranularity(value: unknown): boolean;
```

---

### `createUtcDateTimeValue`

```ts
export function createUtcDateTimeValue(value: string): string;
```

---

### `createInitialDateTimeFieldIds`

```ts
export function createInitialDateTimeFieldIds(
  values: TaskEditorFormValues,
  fields: readonly TaskEditorFieldSchema[],
): readonly TaskEditorFieldId[];
```

---

### `isTaskEntity`

```ts
export function isTaskEntity(model: unknown): model is TaskEntity;
```

---

### `getGridTasks`

```ts
export function getGridTasks(grid: HTMLRevoGridElement): readonly TaskEntity[];
```

---

### `createDependencyDrafts`

```ts
export function createDependencyDrafts(
  task: TaskEntity | null,
  dependencies: readonly DependencyEntity[],
): readonly GanttTaskEditorDialogDependencyDraft[];
```

---

### `areDependencyDraftsEqual`

```ts
export function areDependencyDraftsEqual(
  left: readonly GanttTaskEditorDialogDependencyDraft[],
  right: readonly GanttTaskEditorDialogDependencyDraft[],
): boolean;
```

---

### `normalizeDependencyLagDaysInput`

```ts
export function normalizeDependencyLagDaysInput(value: unknown): number;
```

---

### `getFieldsForTab`

```ts
export function getFieldsForTab(
  tab: TaskEditorTabId,
  fields: readonly TaskEditorFieldSchema[],
): readonly TaskEditorFieldSchema[];
```

---

### `areResourceIdsEqual`

```ts
export function areResourceIdsEqual(left: readonly ResourceId[], right: readonly ResourceId[]): boolean;
```

---

### `createSelectedResourceIds`

```ts
export function createSelectedResourceIds(
  task: TaskEntity | null,
  assignments: readonly AssignmentEntity[],
): readonly ResourceId[];
```

---

### `createErrors`

```ts
export function createErrors(
  errors: readonly TaskEditorSubmitError[],
  fields: readonly TaskEditorFieldSchema[],
  localeText: GanttTaskEditorDialogLocaleText,
): Map<string, string>;
```

---

### `shouldShowStatusMessage`

```ts
export function shouldShowStatusMessage(status: string, statusText: GanttTaskEditorDialogStatusText): boolean;
```

---

### `compareTextAscending`

```ts
export function compareTextAscending(left: string, right: string): number;
```

---

### `includesSearchText`

```ts
export function includesSearchText(value: string, searchText: string): boolean;
```

---

### `getFieldLabel`

```ts
export function getFieldLabel(
  field: TaskEditorFieldSchema,
  localeText: GanttTaskEditorDialogLocaleText,
): string;
```

---

### `getSortedFieldOptions`

```ts
export function getSortedFieldOptions(
  field: TaskEditorFieldSchema,
  localeText: GanttTaskEditorDialogLocaleText,
): readonly { readonly label: string; readonly value: string }[];
```

---

### `EMPTY_RESOURCES`

```ts
EMPTY_RESOURCES: readonly ResourceEntity[];
```

---

### `EMPTY_ASSIGNMENTS`

```ts
EMPTY_ASSIGNMENTS: readonly AssignmentEntity[];
```

---

### `EMPTY_DEPENDENCIES`

```ts
EMPTY_DEPENDENCIES: readonly DependencyEntity[];
```

---

### `ganttTaskEditorDialogDependencies`

#### Dependencies

- **Optional** `GanttPlugin`: Uses Gantt task metadata, resource assignments, and read-only state when present.
- **Auto-installed** `ContextMenuPlugin`: Adds the Edit action to the row context menu.

```ts
ganttTaskEditorDialogDependencies: PluginDependency[];
```

---

### `GanttTaskEditorDialogPlugin`

```ts
class GanttTaskEditorDialogPlugin {
  openTask(taskId: TaskId | null): void;

  closeTaskEditor(): void;

  destroy(): void;
}
```

---

### `getResourceInitials`

```ts
export function getResourceInitials(name: string): string;
```

---

### `ResourcePicker`

```ts
export function ResourcePicker({
  resources,
  selectedResourceIds,
  localeText,
  onChange,
}: ResourcePickerProps);
```

---

### `ResourcePickerProps`

```ts
interface ResourcePickerProps {
  readonly resources: readonly ResourceEntity[];
  readonly selectedResourceIds: readonly ResourceId[];
  readonly localeText: GanttTaskEditorDialogLocaleText;
  readonly onChange: (resourceIds: readonly ResourceId[]) => void
}
```

---

### `TaskEditorField`

```ts
export function TaskEditorField({
  field,
  values,
  errors,
  localeText,
  dateFormatProject,
  dateTimeEnabled,
  resourceSelection,
  colorPalette,
  onChange,
  onDateTimeToggle,
}: TaskEditorFieldProps);
```

---

### `TaskEditorFieldProps`

```ts
interface TaskEditorFieldProps {
  readonly field: TaskEditorFieldSchema;
  readonly values: TaskEditorFormValues;
  readonly errors: ReadonlyMap<string, string>;
  readonly localeText: GanttTaskEditorDialogLocaleText;
  readonly dateFormatProject?: GanttPluginConfig | null;
  readonly dateTimeEnabled?: boolean;
  readonly resourceSelection?: ResourceSelection;
  readonly colorPalette?: ResolvedGanttColorPalette | null;
  readonly onChange: (values: TaskEditorFormValues) => void;
  readonly onDateTimeToggle?: (fieldId: TaskEditorFieldId, enabled: boolean) => void
}
```

---

### `TaskEditorTabs`

```ts
export function TaskEditorTabs({
  activeTab,
  tabs,
  ariaLabel,
  onChange,
}: TaskEditorTabsProps);
```

---

### `TaskEditorTabsProps`

```ts
interface TaskEditorTabsProps {
  readonly activeTab: string;
  readonly tabs: readonly { readonly id: string; readonly title: string }[];
  readonly ariaLabel: string;
  readonly onChange: (tab: string) => void
}
```

---

### `ColorFieldControl`

```ts
export function ColorFieldControl({
  field,
  values,
  localeText,
  colorPalette,
  onChange,
}: FieldControlProps);
```

---

### `DateFieldControl`

```ts
export function DateFieldControl({
  field,
  values,
  localeText,
  dateFormatProject,
  dateTimeEnabled,
  onChange,
  onDateTimeToggle,
}: FieldControlProps);
```

---

### `InputFieldControl`

```ts
export function InputFieldControl({ field, values, onChange }: FieldControlProps);
```

---

### `LabelsFieldControl`

```ts
export function LabelsFieldControl({ field, values, localeText, resourceSelection }: FieldControlProps);
```

---

### `SelectFieldControl`

```ts
export function SelectFieldControl({ field, values, localeText, onChange }: FieldControlProps);
```

---

### `SwitchFieldControl`

```ts
export function SwitchFieldControl({ field, values, localeText, onChange }: FieldControlProps);
```

---

### `TagsFieldControl`

```ts
export function TagsFieldControl({ field, values, onChange }: FieldControlProps);
```

---

### `TextareaFieldControl`

```ts
export function TextareaFieldControl({ field, values, onChange }: FieldControlProps);
```

---

# Gantt Toolbar

URL: https://pro.rv-grid.com/api/gantt-toolbar/
Source: src/content/docs/api/gantt-toolbar.md

### `getGanttBaselineCaptureRuntime`

```ts
export async function getGanttBaselineCaptureRuntime(
  grid: HTMLRevoGridElement,
): Promise<GanttBaselineCaptureRuntime | undefined>;
```

---

### `captureGanttBaseline`

```ts
export async function captureGanttBaseline(
  grid: HTMLRevoGridElement,
  options?: CaptureBaselineOptions,
): Promise<BaselineSnapshot | null>;
```

---

### `GanttBaselineCaptureRuntime`

```ts
interface GanttBaselineCaptureRuntime {
  captureBaseline(options?: CaptureBaselineOptions): BaselineSnapshot | null
}
```

---

### `toggleGanttCriticalPath`

Toggle critical-path highlighting on the grid's Gantt visual config.

Returns the next visibility state, or `undefined` when the grid has no
Gantt config to update.

```ts
export function toggleGanttCriticalPath(grid: HTMLRevoGridElement): boolean | undefined;
```

---

### `getCsvExportPlugin`

```ts
export async function getCsvExportPlugin(grid: HTMLRevoGridElement): Promise<RevoGridCsvExportPlugin | undefined>;
```

---

### `exportGanttCsv`

```ts
export async function exportGanttCsv(
  grid: HTMLRevoGridElement,
  options: GanttCsvExportOptions = {},
): Promise<boolean>;
```

---

### `exportGanttExcel`

```ts
export function exportGanttExcel(
  grid: HTMLRevoGridElement,
  options: GanttExcelExportOptions = {},
): CustomEvent<GanttExcelExportOptions>;
```

---

### `GanttCsvExportOptions`

```ts
interface GanttCsvExportOptions {
  filename?: string;
  bom?: boolean;
  columnDelimiter?: string;
  rowDelimiter?: string;
  mime?: string;
  encoding?: string
}
```

---

### `GanttExcelExportOptions`

```ts
export type GanttExcelExportOptions = ExportExcelEvent;
```

---

### `RevoGridCsvExportPlugin`

```ts
interface RevoGridCsvExportPlugin {
  exportFile(options?: GanttCsvExportOptions): Promise<void>
}
```

---

### `getGanttTimelineNavigationRuntime`

```ts
export async function getGanttTimelineNavigationRuntime(
  grid: HTMLRevoGridElement,
): Promise<GanttTimelineNavigationRuntime | undefined>;
```

---

### `scrollGanttToToday`

```ts
export async function scrollGanttToToday(
  grid: HTMLRevoGridElement,
  options: GanttTodayNavigationOptions = {},
): Promise<boolean>;
```

---

### `fitGanttToProject`

```ts
export async function fitGanttToProject(
  grid: HTMLRevoGridElement,
  options: GanttProjectFitOptions = {},
): Promise<boolean>;
```

---

### `GanttTimelineNavigationOptions`

```ts
interface GanttTimelineNavigationOptions {
  align?: number
}
```

---

### `GanttTodayNavigationOptions` (Extended from `index.ts`)

```ts
interface GanttTodayNavigationOptions {
  date?: ISODateString
}
```

---

### `GanttProjectFitOptions` (Extended from `index.ts`)

```ts
interface GanttProjectFitOptions {
  viewportWidth?: number
}
```

---

### `GanttTimelineNavigationRuntime`

```ts
interface GanttTimelineNavigationRuntime {
  scrollToToday?: () => Promise<void> | void;
  fitToProject?: () => Promise<void> | void;
  getZoomLevel?: () => { id?: string } | null | undefined;
  setZoomLevel?: (levelId: string) => boolean
}
```

---

### `createGanttToolbarQuickWinActions`

Framework-neutral command descriptors for common Gantt toolbar additions.

Render the returned commands in any toolbar UI and call `run()` from the
button handler. Creating the descriptors does not dispatch events, scroll, or
mutate the grid.

```ts
export function createGanttToolbarQuickWinActions(
  grid: HTMLRevoGridElement,
  options: GanttToolbarQuickWinOptions = {},
): GanttToolbarQuickWinActions;
```

---

### `listGanttToolbarQuickWinActions`

```ts
export function listGanttToolbarQuickWinActions(
  actions: GanttToolbarQuickWinActions,
): readonly GanttToolbarQuickWinAction[];
```

---

### `GanttToolbarQuickWinActionId`

```ts
export type GanttToolbarQuickWinActionId =
  | 'export-csv'
  | 'export-excel'
  | 'capture-baseline'
  | 'toggle-critical-path'
  | 'timeline-today'
  | 'timeline-fit-project';
```

---

### `GanttToolbarQuickWinAction`

```ts
interface GanttToolbarQuickWinAction {
  readonly id: GanttToolbarQuickWinActionId;
  readonly label: string;
  readonly title: string;
  readonly run: () => Result | Promise<Result>
}
```

---

### `GanttToolbarQuickWinOptions`

```ts
interface GanttToolbarQuickWinOptions {
  readonly csv?: GanttCsvExportOptions | false;
  readonly excel?: GanttExcelExportOptions | false;
  readonly baseline?: CaptureBaselineOptions | false;
  readonly criticalPath?: false;
  readonly today?: GanttTodayNavigationOptions | false;
  readonly fitToProject?: GanttProjectFitOptions | false
}
```

---

### `GanttToolbarQuickWinActions`

```ts
interface GanttToolbarQuickWinActions {
  readonly exportCsv?: GanttToolbarQuickWinAction<boolean>;
  readonly exportExcel?: GanttToolbarQuickWinAction<CustomEvent<GanttExcelExportOptions>>;
  readonly captureBaseline?: GanttToolbarQuickWinAction<BaselineSnapshot | null>;
  readonly toggleCriticalPath?: GanttToolbarQuickWinAction<boolean | undefined>;
  readonly scrollToToday?: GanttToolbarQuickWinAction<boolean>;
  readonly fitToProject?: GanttToolbarQuickWinAction<boolean>
}
```

---

### `resolveHiddenColumnsFromToolbarSelection`

```ts
export function resolveHiddenColumnsFromToolbarSelection(
  selectedValues: string | string[],
  allProps: string[],
  previousHiddenColumns: string[],
): string[];
```

---

### `GANTT_TOOLBAR_SELECT_ALL_COLUMNS`

```ts
GANTT_TOOLBAR_SELECT_ALL_COLUMNS: string;
```

---

### `GanttToolbar`

```ts
GanttToolbar: ({ grid, columns, visuals: initialVisuals, controls }: GanttToolbarComponentProps) => preact.JSX.Element;
```

---

### `GanttToolbarColumnOption`

A single column entry shown in the Gantt toolbar column-visibility dropdown.

```ts
interface GanttToolbarColumnOption {
  /** Property name matching a task-table column (e.g. `'wbs'`, `'status'`). */
    prop: string;
  /** Human-readable label shown in the dropdown. */
    label: string;
  /**
     * Whether the column is visible by default.
     * Columns with `visible: false` will be added to `grid.hideColumns` on mount.
     * @default true
     */
    visible?: boolean
}
```

---

### `GanttToolbarVisuals`

Initial visual toggle state passed to the toolbar.

```ts
interface GanttToolbarVisuals {
  showBaseline?: boolean;
  showDependencies?: boolean;
  showCriticalPath?: boolean
}
```

---

### `GanttToolbarControls`

Visibility switches for each toolbar control or control group.

```ts
interface GanttToolbarControls {
  search?: boolean;
  history?: boolean;
  undo?: boolean;
  redo?: boolean;
  tree?: boolean;
  expandAll?: boolean;
  collapseAll?: boolean;
  zoom?: boolean;
  zoomIn?: boolean;
  zoomOut?: boolean;
  tasks?: boolean;
  addTask?: boolean;
  indent?: boolean;
  outdent?: boolean;
  export?: boolean;
  exportExcel?: boolean;
  columns?: boolean;
  dependencies?: boolean;
  baseline?: boolean;
  criticalPath?: boolean
}
```

---

### `GanttToolbarOptions`

Options accepted by {@link defineGanttToolbar}.

```ts
interface GanttToolbarOptions {
  /** The `revo-grid` element the toolbar should control. */
    grid: HTMLRevoGridElement;
  /**
     * Column options to show in the visibility dropdown.
     * If omitted, no column dropdown is rendered.
     */
    columns?: GanttToolbarColumnOption[];
  /**
     * Initial state of the visual/scheduling toggles.
     * When omitted, values are read from the current `grid.gantt.visuals` config.
     */
    visuals?: GanttToolbarVisuals;
  /**
     * Per-control visibility. Omitted options default to visible, except
     * `baseline`, which is opt-in to keep the default command bar compact.
     */
    controls?: GanttToolbarControls
}
```

---

### `ganttToolbarDependencies`

#### Dependencies

- **Optional** `HistoryPlugin`: Integrates with HistoryPlugin undo and redo controls when present.
- **Optional** `GanttPlugin`: Integrates with Gantt runtime zoom and editing capabilities when present.
- **Event integration** `gantt-runtime`: Dispatches and listens to Pro and Gantt events for toolbar controls.

```ts
ganttToolbarDependencies: PluginDependency[];
```

---

### `defineGanttToolbar`

Mounts the Gantt editing toolbar into `el` and wires it to the given
`revo-grid` element.  Call this once after the grid's `gantt` property
has been set so the toolbar can read the initial visual config.

`controls` hides built-in controls. Omitted flags are visible by default,
except `baseline`, which is opt-in.

### Example
```ts
import { defineGanttToolbar } from '@revolist/gantt';

const toolbarEl = document.querySelector('#gantt-toolbar');
const grid      = document.querySelector('revo-grid');

defineGanttToolbar(toolbarEl, {
  grid,
  columns: [
    { prop: 'wbs',       label: 'WBS',       visible: true  },
    { prop: 'name',      label: 'Name',       visible: true  },
    { prop: 'startDate', label: 'Start Date', visible: true  },
    { prop: 'duration',  label: 'Duration',   visible: true  },
    { prop: 'status',    label: 'Status',     visible: true  },
    { prop: 'endDate',   label: 'End Date',   visible: false },
  ],
  visuals: {
    showDependencies:            true,
    showBaseline:                true,
    showCriticalPath:            true,
  },
  controls: {
    search: true,
    history: true,
    undo: true,
    redo: true,
    tree: true,
    expandAll: true,
    collapseAll: true,
    zoom: true,
    zoomIn: true,
    zoomOut: true,
    tasks: true,
    addTask: true,
    indent: true,
    outdent: true,
    export: true,
    exportExcel: true,
    columns: true,
    dependencies: true,
    baseline: true,
    criticalPath: true,
  },
});
```

```ts
defineGanttToolbar: (el: HTMLElement, options: GanttToolbarOptions) => void;
```

---

# Columns And Grid Projection

URL: https://pro.rv-grid.com/api/gantt/columns/
Source: src/content/docs/api/gantt/columns.md
Description: Public RevoGrid Gantt API for columns and grid projection.
Surface: gantt

This page documents 20 public symbols exported by `@revolist/gantt`.

## `createDefaultTaskTableColumn`

<span class="api-kind">function</span>

Look up a default task-table column definition by property name.

```ts
export function createDefaultTaskTableColumn(prop: TaskTableColumnProp, labels?: GanttLabelsConfig, allowedTaskTypes?: readonly TaskType[]): ColumnRegular;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `prop` | `TaskTableColumnProp` | Yes | — | - The column property key (e.g. `"wbs"`, `"name"`). |
| `labels` | `GanttLabelsConfig \| undefined` | No | — |  |
| `allowedTaskTypes` | `readonly TaskType[] \| undefined` | No | — |  |

**Returns:** A cloned `ColumnRegular` if a default exists, or `null`.

**Related types:** [`GanttLabelsConfig`](/api/gantt/plugin/#ganttlabelsconfig), [`TaskTableColumnProp`](/api/gantt/columns/#tasktablecolumnprop), [`TaskType`](/api/gantt/data-model/#tasktype)

## `createGanttColumn`

<span class="api-kind">function</span>

Create the pinned-end gantt column definition.

This produces a single read-only column that uses the `gantt` column type
for rendering. Runtime timeline width is managed by the dimension store.

```ts
export function createGanttColumn(_totalWidth?: number): ColumnRegular;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `_totalWidth` | `number \| undefined` | No | — |  |

**Returns:** A `ColumnRegular` pinned to `colPinEnd`.

## `createGanttColumnPreset`

<span class="api-kind">function</span>

```ts
export function createGanttColumnPreset(preset: GanttColumnPresetName, options: GanttColumnPresetOptions = {}): ColumnRegular[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `preset` | `GanttColumnPresetName` | Yes | — |  |
| `options` | `GanttColumnPresetOptions` | No | `{}` |  |

**Related types:** [`GanttColumnPresetName`](/api/gantt/columns/#ganttcolumnpresetname), [`GanttColumnPresetOptions`](/api/gantt/columns/#ganttcolumnpresetoptions)

## `createGanttColumnPresets`

<span class="api-kind">function</span>

```ts
export function createGanttColumnPresets(options: GanttColumnPresetOptions = {}): Record<GanttColumnPresetName, ColumnRegular[]>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttColumnPresetOptions` | No | `{}` |  |

**Related types:** [`GanttColumnPresetName`](/api/gantt/columns/#ganttcolumnpresetname), [`GanttColumnPresetOptions`](/api/gantt/columns/#ganttcolumnpresetoptions)

## `createGanttGridRows`

<span class="api-kind">function</span>

Projects the full project state into an ordered array of flat grid rows ready for rendering.
Combines scheduling results, WBS numbering, dependency labels, baseline overlays, resource assignments,
and Gantt bar layouts into a single row model per task.

```ts
export function createGanttGridRows(project: ProjectSnapshot, scale: TimelineScale, scheduledTasksById: ReadonlyMap<TaskId, ScheduledTask>, taskStore: TaskStore = new InMemoryTaskStore(project.tasks), resourceStore: ResourceStore = new InMemoryResourceStore(project.resources), assignmentStore: AssignmentStore = new InMemoryAssignmentStore(project.assignments), options: TaskRowProjectionOptions = {}, diagnostics?: TaskRowDiagnostics): readonly GanttGridRow[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `ProjectSnapshot` | Yes | — | - The current project snapshot (tasks, resources, assignments, baselines, dependencies). |
| `scale` | `TimelineScale` | Yes | — | - The active timeline scale for date-to-pixel conversion. |
| `scheduledTasksById` | `ReadonlyMap<string, ScheduledTask>` | Yes | — | - Map of task IDs to their engine-computed schedule results. |
| `taskStore` | `TaskStore` | No | `new InMemoryTaskStore(project.tasks)` | - Task store instance (defaults to an in-memory store built from the project). |
| `resourceStore` | `ResourceStore` | No | `new InMemoryResourceStore(project.resources)` | - Resource store instance (defaults to an in-memory store built from the project). |
| `assignmentStore` | `AssignmentStore` | No | `new InMemoryAssignmentStore(project.assignments)` | - Assignment store instance (defaults to an in-memory store built from the project). |
| `options` | `TaskRowProjectionOptions` | No | `{}` | - Optional projection options (baseline, critical path, labels, resource planning). |
| `diagnostics` | `TaskRowDiagnostics \| undefined` | No | — |  |

**Returns:** An ordered array of {@link GanttGridRow} objects.

**Related types:** [`AssignmentStore`](/api/gantt/data-model/#assignmentstore), [`GanttGridRow`](/api/gantt/columns/#ganttgridrow), [`InMemoryAssignmentStore`](/api/gantt/data-model/#inmemoryassignmentstore), [`InMemoryResourceStore`](/api/gantt/data-model/#inmemoryresourcestore), [`InMemoryTaskStore`](/api/gantt/data-model/#inmemorytaskstore), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ResourceStore`](/api/gantt/data-model/#resourcestore), [`ScheduledTask`](/api/gantt/scheduling/#scheduledtask), [`TaskId`](/api/gantt/data-model/#taskid), [`TaskRowDiagnostics`](/api/gantt/visuals/#taskrowdiagnostics), [`TaskRowProjectionOptions`](/api/gantt/visuals/#taskrowprojectionoptions), [`TaskStore`](/api/gantt/data-model/#taskstore), [`TimelineScale`](/api/gantt/visuals/#timelinescale)

## `createInitialTaskTableColumns`

<span class="api-kind">function</span>

Create the initial set of task-table columns shown before the user
supplies custom columns.

```ts
export function createInitialTaskTableColumns(labels?: GanttLabelsConfig, allowedTaskTypes?: readonly TaskType[]): ColumnRegular[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `labels` | `GanttLabelsConfig \| undefined` | No | — |  |
| `allowedTaskTypes` | `readonly TaskType[] \| undefined` | No | — |  |

**Returns:** An array containing the Name column.

**Related types:** [`GanttLabelsConfig`](/api/gantt/plugin/#ganttlabelsconfig), [`TaskType`](/api/gantt/data-model/#tasktype)

## `defaultTaskTableColumns`

<span class="api-kind">constant</span>

```ts
export const defaultTaskTableColumns: Record<TaskTableColumnProp, ColumnRegular<ColumnProp, DataType<any, ColumnProp>>>;
```

**Related types:** [`TaskTableColumnProp`](/api/gantt/columns/#tasktablecolumnprop)

## `GanttColumnPresetName`

<span class="api-kind">type</span>

```ts
export type GanttColumnPresetName =
  | 'core'
  | 'schedule'
  | 'dependencies'
  | 'resources'
  | 'baseline'
  | 'cost'
  | 'progress'
  | 'all';
```

## `GanttColumnPresetOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttColumnPresetOptions {
  /** Built-in Gantt option label overrides applied to generated default columns. */
  readonly labels?: GanttLabelsConfig;
  /** Task kinds offered by the generated Task Type column. */
  readonly allowedTaskTypes?: readonly TaskType[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `labels` | `GanttLabelsConfig \| undefined` | No | — | Built-in Gantt option label overrides applied to generated default columns. |
| `allowedTaskTypes` | `readonly TaskType[] \| undefined` | No | — | Task kinds offered by the generated Task Type column. |

**Related types:** [`GanttLabelsConfig`](/api/gantt/plugin/#ganttlabelsconfig), [`TaskType`](/api/gantt/data-model/#tasktype)

## `GanttColumnPresetProp`

<span class="api-kind">type</span>

```ts
export type GanttColumnPresetProp = Extract<TaskTableColumnProp, TaskGridColumnProp>;
```

**Related types:** [`TaskTableColumnProp`](/api/gantt/columns/#tasktablecolumnprop)

## `ganttColumnPresetProps`

<span class="api-kind">constant</span>

```ts
export const ganttColumnPresetProps: { readonly core: readonly ["wbs", "name", "type", "startDate", "endDate", "duration", "percentDone"]; readonly schedule: readonly ["wbs", "name", "taskMode", "scheduleOrigin", "startDate", "endDate", "duration", "constraintType", "constraintDate", "deadlineDate", "schedulingWarning", "totalSlackDays"]; readonly dependencies: readonly ["wbs", "name", "predecessors", "successors", "totalSlackDays"]; readonly resources: readonly ["wbs", "name", "assignees", "workHours", "effortMode", "effortDriven", "resourceRole", "resourceCapacity", "resourceLoadSummary", "canLevel", "levelingDelayDays"]; readonly baseline: readonly ["wbs", "name", "startDate", "endDate", "actualStartDate", "actualFinishDate", "startVarianceDays", "finishVarianceDays", "durationVariance", "progressVariancePercent"]; readonly cost: readonly ["wbs", "name", "type", "cost", "workHours", "assignees"]; readonly progress: readonly ["wbs", "name", "status", "statusIndicator", "percentDone", "remainingDuration", "actualStartDate", "actualFinishDate", "progressVariancePercent"]; readonly all: readonly ["wbs", "name", "type", "cost", "startDate", "endDate", "duration", "workHours", "remainingDuration", "actualStartDate", "actualFinishDate", "effortMode", "effortDriven", "inactive", "priority", "canLevel", "levelingDelayDays", "earlyStartDate", "earlyFinishDate", "lateStartDate", "lateFinishDate", "totalSlackDays", "startVarianceDays", "finishVarianceDays", "durationVariance", "progressVariancePercent", "taskMode", "scheduleOrigin", "constraintType", "constraintDate", "deadlineDate", "schedulingWarning", "percentDone", "predecessors", "successors", "status", "statusIndicator", "workflowStatus", "assignees", "resourceRole", "resourceCapacity", "resourceLoadSummary"]; };
```

## `GanttDependencyDropdownColumn`

<span class="api-kind">constant</span>

```ts
export const GanttDependencyDropdownColumn: ColumnType<DataType<any, ColumnProp>>;
```

## `GanttGridRow`

<span class="api-kind">interface</span>

Flat render row produced by projecting a scheduled task onto the Gantt grid. Contains display-ready fields and computed layout, not domain/UI state.

```ts
export interface GanttGridRow {
  /** Row projection kind. Omitted task rows are treated as task rows. */
  readonly rowKind?: 'task' | 'resource';
  /** Unique task identifier. */
  readonly id: TaskId;
  /** Parent task identifier, or `null` for top-level tasks. */
  readonly parentId: TaskId | null;
  /** Work Breakdown Structure code (e.g. "1.2.3"). */
  readonly wbs: string;
  /** Display name of the task. */
  readonly name: string;
  /** Optional authored task-bar color. */
  readonly color?: string;
  /** Scheduler-determined kind (task, summary, milestone). */
  readonly taskKind: ScheduledTaskKind;
  /** Raw authored task type used by task-table editors. */
  readonly type?: ScheduledTaskKind;
  /** Human-readable task type label. */
  readonly taskType: string;
  /** Human-readable status label. */
  readonly status: string;
  /** Raw calculated task status key. Omitted for non-task resource rows. */
  readonly statusKey?: TaskStatus;
  /** Calculated status used by the Status Indicator column. */
  readonly statusIndicator?: TaskStatus;
  /** Human-readable editable workflow status label. */
  readonly workflowStatus?: string;
  /** Raw editable workflow status key. */
  readonly workflowStatusKey?: TaskWorkflowStatus;
  /** Task tags. */
  readonly tags: readonly string[];
  /** Optional scheduling constraint type. */
  readonly constraintType?: string;
  /** Optional scheduling constraint date. */
  readonly constraintDate?: string;
  /** Optional task deadline date. */
  readonly deadlineDate?: string;
  /** Scheduled start date (ISO string). */
  readonly startDate: string;
  /** Scheduled end date (ISO string). */
  readonly endDate: string;
  /** Scheduled task duration. */
  readonly duration: number;
  /** Unit used by duration cells and editors. */
  readonly durationUnit?: DurationUnit;
  /** Whether duration ignores working calendars. */
  readonly durationIsElapsed?: boolean;
  /** Display-ready scheduled duration. */
  readonly formattedDuration?: string;
  /** Planned work for the task, in hours. */
  readonly workHours?: number;
  /** Unit used by Work cells and editors. */
  readonly workUnit?: DurationUnit;
  /** Display-ready planned Work value. */
  readonly formattedWork?: string;
  /** Remaining duration for progress-aware scheduling. */
  readonly remainingDuration?: number;
  /** Display-ready remaining duration. */
  readonly formattedRemainingDuration?: string;
  /** Date work actually started. */
  readonly actualStartDate?: string;
  /** Date work actually finished. */
  readonly actualFinishDate?: string;
  /** Task effort mode controlling work/duration/unit calculation. */
  readonly effortMode?: TaskEffortMode;
  /** Whether assignment changes should preserve total work where supported. */
  readonly effortDriven?: boolean;
  /** Whether this task is excluded from scheduling. */
  readonly inactive: boolean;
  /** Leveling priority from 0 to 1000. */
  readonly priority?: number;
  /** Whether automatic resource leveling may delay this task. */
  readonly canLevel?: boolean;
  /** Resource leveling delay in calendar days. */
  readonly levelingDelayDays?: number;
  /** Completion percentage (0-100). */
  readonly percentDone: number;
  /** Total slack (float) in days before the task delays the project. Present when critical-path projection is available. */
  readonly totalSlackDays?: number;
  /** Earliest scheduled start date. Present when critical-path projection is available. */
  readonly earlyStartDate?: string;
  /** Earliest scheduled finish date. Present when critical-path projection is available. */
  readonly earlyFinishDate?: string;
  /** Latest start date that preserves the project finish. Present when critical-path projection is available. */
  readonly lateStartDate?: string;
  /** Latest finish date that preserves the project finish. Present when critical-path projection is available. */
  readonly lateFinishDate?: string;
  /** Whether the task is auto- or manually scheduled. */
  readonly taskMode: 'auto' | 'manual';
  /** How the scheduler determined the rendered dates. */
  readonly scheduleOrigin: ScheduledTask['scheduleOrigin'];
  /** Scheduling warning messages associated with this task. */
  readonly schedulingWarnings: readonly string[];
  /** First scheduling warning, suitable for compact columns and tooltips. */
  readonly schedulingWarning: string;
  /** Optional inline label rendered on the Gantt bar. */
  readonly taskLabel?: string;
  /** Optional baseline bar layout for plan-vs-actual comparison. */
  readonly baselineLayout?: GanttBaselineLayout;
  /** Start variance against the selected baseline, in calendar days. */
  readonly startVarianceDays?: number;
  /** Finish variance against the selected baseline, in calendar days. */
  readonly finishVarianceDays?: number;
  /** Duration variance against the selected baseline, in canonical hours. */
  readonly durationVariance?: number;
  /** Display-ready duration variance in the task duration unit. */
  readonly formattedDurationVariance?: string;
  /** Progress variance against the selected baseline, in percentage points. */
  readonly progressVariancePercent?: number;
  /** Point indicators (deadlines, constraints, custom markers) on this row. */
  readonly indicators: readonly GanttIndicatorLayout[];
  /** Assigned resource names used by the multi-select editor. */
  readonly assignees: readonly string[];
  /** Comma-separated list of assigned resource names for search and tooltips. */
  readonly assigneeLabels: string;
  /** Display-ready resource assignment metadata. */
  readonly assigneeDetails: readonly TaskGridAssignee[];
  /** Estimated task cost in the project currency. */
  readonly cost: number;
  /** Formatted estimated task cost. */
  readonly formattedCost: string;
  /** Comma-separated predecessor reference tokens. */
  readonly predecessors: string;
  /** Comma-separated successor reference tokens. */
  readonly successors: string;
  /** Computed pixel layout for the Gantt bar. */
  readonly ganttLayout: GanttBarLayout;
  /** Reserved field for the Gantt bar cell renderer. */
  readonly gantt: string;
  /** Resource identifier for resource-planning rows. */
  readonly resourceId?: ResourceId;
  /** Optional resource profile image URL for resource-planning rows. */
  readonly resourceAvatarUrl?: string;
  /** Resource role for resource-planning rows. */
  readonly resourceRole?: string;
  /** Display-ready capacity label for resource-planning rows. */
  readonly resourceCapacity?: string;
  /** Display-ready load summary for resource-planning rows. */
  readonly resourceLoadSummary?: string;
  /** Resource planning load data rendered on the timeline. */
  readonly resourcePlanning?: ResourcePlanningRowData;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `rowKind` | `"task" \| "resource" \| undefined` | No | — | Row projection kind. Omitted task rows are treated as task rows. |
| `id` | `string` | Yes | — | Unique task identifier. |
| `parentId` | `string \| null` | Yes | — | Parent task identifier, or `null` for top-level tasks. |
| `wbs` | `string` | Yes | — | Work Breakdown Structure code (e.g. "1.2.3"). |
| `name` | `string` | Yes | — | Display name of the task. |
| `color` | `string \| undefined` | No | — | Optional authored task-bar color. |
| `taskKind` | `ScheduledTaskKind` | Yes | — | Scheduler-determined kind (task, summary, milestone). |
| `type` | `ScheduledTaskKind \| undefined` | No | — | Raw authored task type used by task-table editors. |
| `taskType` | `string` | Yes | — | Human-readable task type label. |
| `status` | `string` | Yes | — | Human-readable status label. |
| `statusKey` | `TaskStatus \| undefined` | No | — | Raw calculated task status key. Omitted for non-task resource rows. |
| `statusIndicator` | `TaskStatus \| undefined` | No | — | Calculated status used by the Status Indicator column. |
| `workflowStatus` | `string \| undefined` | No | — | Human-readable editable workflow status label. |
| `workflowStatusKey` | `TaskWorkflowStatus \| undefined` | No | — | Raw editable workflow status key. |
| `tags` | `readonly string[]` | Yes | — | Task tags. |
| `constraintType` | `string \| undefined` | No | — | Optional scheduling constraint type. |
| `constraintDate` | `string \| undefined` | No | — | Optional scheduling constraint date. |
| `deadlineDate` | `string \| undefined` | No | — | Optional task deadline date. |
| `startDate` | `string` | Yes | — | Scheduled start date (ISO string). |
| `endDate` | `string` | Yes | — | Scheduled end date (ISO string). |
| `duration` | `number` | Yes | — | Scheduled task duration. |
| `durationUnit` | `DurationUnit \| undefined` | No | — | Unit used by duration cells and editors. |
| `durationIsElapsed` | `boolean \| undefined` | No | — | Whether duration ignores working calendars. |
| `formattedDuration` | `string \| undefined` | No | — | Display-ready scheduled duration. |
| `workHours` | `number \| undefined` | No | — | Planned work for the task, in hours. |
| `workUnit` | `DurationUnit \| undefined` | No | — | Unit used by Work cells and editors. |
| `formattedWork` | `string \| undefined` | No | — | Display-ready planned Work value. |
| `remainingDuration` | `number \| undefined` | No | — | Remaining duration for progress-aware scheduling. |
| `formattedRemainingDuration` | `string \| undefined` | No | — | Display-ready remaining duration. |
| `actualStartDate` | `string \| undefined` | No | — | Date work actually started. |
| `actualFinishDate` | `string \| undefined` | No | — | Date work actually finished. |
| `effortMode` | `TaskEffortMode \| undefined` | No | — | Task effort mode controlling work/duration/unit calculation. |
| `effortDriven` | `boolean \| undefined` | No | — | Whether assignment changes should preserve total work where supported. |
| `inactive` | `boolean` | Yes | — | Whether this task is excluded from scheduling. |
| `priority` | `number \| undefined` | No | — | Leveling priority from 0 to 1000. |
| `canLevel` | `boolean \| undefined` | No | — | Whether automatic resource leveling may delay this task. |
| `levelingDelayDays` | `number \| undefined` | No | — | Resource leveling delay in calendar days. |
| `percentDone` | `number` | Yes | — | Completion percentage (0-100). |
| `totalSlackDays` | `number \| undefined` | No | — | Total slack (float) in days before the task delays the project. Present when critical-path projection is available. |
| `earlyStartDate` | `string \| undefined` | No | — | Earliest scheduled start date. Present when critical-path projection is available. |
| `earlyFinishDate` | `string \| undefined` | No | — | Earliest scheduled finish date. Present when critical-path projection is available. |
| `lateStartDate` | `string \| undefined` | No | — | Latest start date that preserves the project finish. Present when critical-path projection is available. |
| `lateFinishDate` | `string \| undefined` | No | — | Latest finish date that preserves the project finish. Present when critical-path projection is available. |
| `taskMode` | `"manual" \| "auto"` | Yes | — | Whether the task is auto- or manually scheduled. |
| `scheduleOrigin` | `ScheduleOrigin` | Yes | — | How the scheduler determined the rendered dates. |
| `schedulingWarnings` | `readonly string[]` | Yes | — | Scheduling warning messages associated with this task. |
| `schedulingWarning` | `string` | Yes | — | First scheduling warning, suitable for compact columns and tooltips. |
| `taskLabel` | `string \| undefined` | No | — | Optional inline label rendered on the Gantt bar. |
| `baselineLayout` | `GanttBaselineLayout \| undefined` | No | — | Optional baseline bar layout for plan-vs-actual comparison. |
| `startVarianceDays` | `number \| undefined` | No | — | Start variance against the selected baseline, in calendar days. |
| `finishVarianceDays` | `number \| undefined` | No | — | Finish variance against the selected baseline, in calendar days. |
| `durationVariance` | `number \| undefined` | No | — | Duration variance against the selected baseline, in canonical hours. |
| `formattedDurationVariance` | `string \| undefined` | No | — | Display-ready duration variance in the task duration unit. |
| `progressVariancePercent` | `number \| undefined` | No | — | Progress variance against the selected baseline, in percentage points. |
| `indicators` | `readonly GanttIndicatorLayout[]` | Yes | — | Point indicators (deadlines, constraints, custom markers) on this row. |
| `assignees` | `readonly string[]` | Yes | — | Assigned resource names used by the multi-select editor. |
| `assigneeLabels` | `string` | Yes | — | Comma-separated list of assigned resource names for search and tooltips. |
| `assigneeDetails` | `readonly TaskGridAssignee[]` | Yes | — | Display-ready resource assignment metadata. |
| `cost` | `number` | Yes | — | Estimated task cost in the project currency. |
| `formattedCost` | `string` | Yes | — | Formatted estimated task cost. |
| `predecessors` | `string` | Yes | — | Comma-separated predecessor reference tokens. |
| `successors` | `string` | Yes | — | Comma-separated successor reference tokens. |
| `ganttLayout` | `GanttBarLayout` | Yes | — | Computed pixel layout for the Gantt bar. |
| `gantt` | `string` | Yes | — | Reserved field for the Gantt bar cell renderer. |
| `resourceId` | `string \| undefined` | No | — | Resource identifier for resource-planning rows. |
| `resourceAvatarUrl` | `string \| undefined` | No | — | Optional resource profile image URL for resource-planning rows. |
| `resourceRole` | `string \| undefined` | No | — | Resource role for resource-planning rows. |
| `resourceCapacity` | `string \| undefined` | No | — | Display-ready capacity label for resource-planning rows. |
| `resourceLoadSummary` | `string \| undefined` | No | — | Display-ready load summary for resource-planning rows. |
| `resourcePlanning` | `ResourcePlanningRowData \| undefined` | No | — | Resource planning load data rendered on the timeline. |

**Related types:** [`GanttBarLayout`](/api/gantt/visuals/#ganttbarlayout), [`GanttBaselineLayout`](/api/gantt/visuals/#ganttbaselinelayout), [`GanttIndicatorLayout`](/api/gantt/visuals/#ganttindicatorlayout), [`ResourceId`](/api/gantt/data-model/#resourceid), [`ResourcePlanningRowData`](/api/gantt/visuals/#resourceplanningrowdata), [`ScheduledTask`](/api/gantt/scheduling/#scheduledtask), [`ScheduledTaskKind`](/api/gantt/scheduling/#scheduledtaskkind), [`TaskEffortMode`](/api/gantt/data-model/#taskeffortmode), [`TaskGridAssignee`](/api/gantt/visuals/#taskgridassignee), [`TaskId`](/api/gantt/data-model/#taskid), [`TaskStatus`](/api/gantt/data-model/#taskstatus), [`TaskWorkflowStatus`](/api/gantt/data-model/#taskworkflowstatus)

## `GanttPercentDoneColumn`

<span class="api-kind">interface</span>

Percent Done task-table column with an optional per-column visual override.

```ts
export interface GanttPercentDoneColumn extends ColumnRegular {
  readonly prop: 'percentDone';
  /** Overrides `visuals.percentDoneMode` for this column. */
  readonly mode?: GanttPercentDoneColumnMode;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `prop` | `"percentDone"` | Yes | — |  |
| `mode` | `GanttPercentDoneColumnMode \| undefined` | No | — | Overrides `visuals.percentDoneMode` for this column. |

**Related types:** [`GanttPercentDoneColumnMode`](/api/gantt/columns/#ganttpercentdonecolumnmode)

## `GanttPercentDoneColumnMode`

<span class="api-kind">type</span>

Built-in visual modes for the managed Percent Done task-table column.

```ts
export type GanttPercentDoneColumnMode = 'number' | 'bar' | 'circle';
```

## `getGanttColumnPresetProps`

<span class="api-kind">function</span>

```ts
export function getGanttColumnPresetProps(preset: GanttColumnPresetName): GanttColumnPresetProp[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `preset` | `GanttColumnPresetName` | Yes | — |  |

**Related types:** [`GanttColumnPresetName`](/api/gantt/columns/#ganttcolumnpresetname), [`GanttColumnPresetProp`](/api/gantt/columns/#ganttcolumnpresetprop)

## `getZoomPresetConfig`

<span class="api-kind">function</span>

Returns the scale configuration fields for a named zoom preset.

```ts
export function getZoomPresetConfig(preset: TimelineZoomPreset): Pick<TimelineScaleConfig, 'levelId' | 'tickUnit' | 'tickCount' | 'tickWidth' | 'headerRows'>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `preset` | `TimelineZoomPreset` | Yes | — | - One of the predefined zoom preset identifiers. |

**Returns:** A partial {@link TimelineScaleConfig} with tick and header settings.

**Related types:** [`TimelineScaleConfig`](/api/gantt/visuals/#timelinescaleconfig), [`TimelineZoomPreset`](/api/gantt/columns/#timelinezoompreset)

## `normalizePinnedTaskColumns`

<span class="api-kind">function</span>

Normalize user-supplied columns for the task-table side of the gantt grid.

Strips any existing `gantt` column (it is managed internally), fills in
missing properties from default column definitions, and falls back to the
initial columns if the array is empty.

```ts
export function normalizePinnedTaskColumns(columns: Array<ColumnGrouping | ColumnRegular> | undefined, getProject: () => GanttPluginConfig | null | undefined = () => undefined, getRowOrder: () => RowOrderPluginConfig | false | undefined = () => undefined): Array<ColumnGrouping | ColumnRegular>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `columns` | `(ColumnRegular<ColumnProp, DataType<any, ColumnProp>> \| ColumnGrouping<any>)[] \| undefined` | Yes | — | - The raw column array from the grid or user config. |
| `getProject` | `() => GanttPluginConfig \| null \| undefined` | No | `() => undefined` |  |
| `getRowOrder` | `() => RowOrderPluginConfig \| false \| undefined` | No | `() => undefined` |  |

**Returns:** A cleaned array of columns ready to be combined with the gantt column.

**Related types:** [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig)

## `TaskTableColumnProp`

<span class="api-kind">type</span>

```ts
export type TaskTableColumnProp =
  | 'wbs'
  | 'name'
  | 'type'
  | 'cost'
  | 'startDate'
  | 'endDate'
  | 'duration'
  | 'workHours'
  | 'remainingDuration'
  | 'actualStartDate'
  | 'actualFinishDate'
  | 'effortMode'
  | 'effortDriven'
  | 'inactive'
  | 'priority'
  | 'canLevel'
  | 'levelingDelayDays'
  | 'earlyStartDate'
  | 'earlyFinishDate'
  | 'lateStartDate'
  | 'lateFinishDate'
  | 'totalSlackDays'
  | 'startVarianceDays'
  | 'finishVarianceDays'
  | 'durationVariance'
  | 'progressVariancePercent'
  | 'taskMode'
  | 'scheduleOrigin'
  | 'constraintType'
  | 'constraintDate'
  | 'deadlineDate'
  | 'schedulingWarning'
  | 'percentDone'
  | 'predecessors'
  | 'successors'
  | 'status'
  | 'statusIndicator'
  | 'workflowStatus'
  | 'assignees'
  | 'resourceRole'
  | 'resourceCapacity'
  | 'resourceLoadSummary';
```

## `TimelineZoomPreset`

<span class="api-kind">type</span>

Named presets mapping to entries in the built-in timeline preset list.

```ts
export type TimelineZoomPreset =
  | 'minute-hour'
  | 'hour-day'
  | 'two-hour-day-wide'
  | 'two-hour-day'
  | 'six-hour-day-wide'
  | 'six-hour-day'
  | 'day-week-wide'
  | 'day-month'
  | 'day-week-medium'
  | 'day-week'
  | 'week-month'
  | 'month-quarter'
  | 'quarter-year'
  | 'year-quarter'
  | 'multi-year-quarter';
```

---

# Project Data Model

URL: https://pro.rv-grid.com/api/gantt/data-model/
Source: src/content/docs/api/gantt/data-model.md
Description: Public RevoGrid Gantt API for project data model.
Surface: gantt

This page documents 41 public symbols exported by `@revolist/gantt`.

## `AssignmentEntity`

<span class="api-kind">interface</span>

Links a {@link ResourceEntity} to a {@link TaskEntity}, representing
the resource's involvement in that task.

```ts
export interface AssignmentEntity {
  /** Unique assignment identifier. */
  readonly id: AssignmentId;
  /** The task this assignment belongs to. */
  readonly taskId: TaskId;
  /** The resource assigned to the task. */
  readonly resourceId: ResourceId;
  /** Allocation units. Accepts either `100` or `1.0` for 100 % of the resource capacity. */
  readonly allocationUnits: number;
  /** Assignment work, in hours. */
  readonly workHours?: number;
  /** Description of what the resource is responsible for. */
  readonly responsibility: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique assignment identifier. |
| `taskId` | `string` | Yes | — | The task this assignment belongs to. |
| `resourceId` | `string` | Yes | — | The resource assigned to the task. |
| `allocationUnits` | `number` | Yes | — | Allocation units. Accepts either `100` or `1.0` for 100 % of the resource capacity. |
| `workHours` | `number \| undefined` | No | — | Assignment work, in hours. |
| `responsibility` | `string` | Yes | — | Description of what the resource is responsible for. |

**Related types:** [`AssignmentId`](/api/gantt/data-model/#assignmentid), [`ResourceId`](/api/gantt/data-model/#resourceid), [`TaskId`](/api/gantt/data-model/#taskid)

## `AssignmentId`

<span class="api-kind">type</span>

Unique identifier for a task–resource assignment.

```ts
export type AssignmentId = EntityId;
```

**Related types:** [`EntityId`](/api/gantt/data-model/#entityid)

## `AssignmentStore`

<span class="api-kind">interface</span>

Read/write store for {@link AssignmentEntity} instances.
Maintains indexes for fast lookup by task or resource.

```ts
export interface AssignmentStore {
  /** Returns all assignments. */
  getAll(): readonly AssignmentEntity[];
  /** Looks up an assignment by its id. */
  getById(assignmentId: AssignmentId): AssignmentEntity | undefined;
  /** Returns all assignments for a given task. */
  getByTaskId(taskId: TaskId): readonly AssignmentEntity[];
  /** Returns all assignments for a given resource. */
  getByResourceId(resourceId: ResourceId): readonly AssignmentEntity[];
  /** Replaces the entire assignment list, rebuilding all indexes. */
  replaceAll(assignments: readonly AssignmentEntity[]): void;
  /** Replaces only the assignments for a specific task, keeping others intact. */
  replaceTaskAssignments(taskId: TaskId, assignments: readonly AssignmentEntity[]): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `getAll()` | `readonly AssignmentEntity[]` | Yes | — | Returns all assignments. |
| `getById(assignmentId: AssignmentId)` | `AssignmentEntity \| undefined` | Yes | — | Looks up an assignment by its id. |
| `getByTaskId(taskId: TaskId)` | `readonly AssignmentEntity[]` | Yes | — | Returns all assignments for a given task. |
| `getByResourceId(resourceId: ResourceId)` | `readonly AssignmentEntity[]` | Yes | — | Returns all assignments for a given resource. |
| `replaceAll(assignments: readonly AssignmentEntity[])` | `void` | Yes | — | Replaces the entire assignment list, rebuilding all indexes. |
| `replaceTaskAssignments(taskId: TaskId, assignments: readonly AssignmentEntity[])` | `void` | Yes | — | Replaces only the assignments for a specific task, keeping others intact. |

**Related types:** [`AssignmentEntity`](/api/gantt/data-model/#assignmententity), [`AssignmentId`](/api/gantt/data-model/#assignmentid), [`ResourceId`](/api/gantt/data-model/#resourceid), [`TaskId`](/api/gantt/data-model/#taskid)

## `BaselineId`

<span class="api-kind">type</span>

Unique identifier for a baseline snapshot.

```ts
export type BaselineId = EntityId;
```

**Related types:** [`EntityId`](/api/gantt/data-model/#entityid)

## `BaselineSnapshot`

<span class="api-kind">interface</span>

A point-in-time snapshot of the entire project schedule.
Baselines allow users to track schedule drift over time.

```ts
export interface BaselineSnapshot {
  /** Unique baseline identifier. */
  readonly id: BaselineId;
  /** Human-readable baseline name (e.g. `"Sprint 1 Plan"`). */
  readonly name: string;
  /** When this baseline was captured. */
  readonly capturedAt: ISODateTimeString;
  /** Per-task snapshots at capture time. */
  readonly tasks: readonly BaselineTaskSnapshot[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique baseline identifier. |
| `name` | `string` | Yes | — | Human-readable baseline name (e.g. `"Sprint 1 Plan"`). |
| `capturedAt` | ``${number}-${number}-${number}T${string}`` | Yes | — | When this baseline was captured. |
| `tasks` | `readonly BaselineTaskSnapshot[]` | Yes | — | Per-task snapshots at capture time. |

**Related types:** [`BaselineId`](/api/gantt/data-model/#baselineid), [`BaselineTaskSnapshot`](/api/gantt/data-model/#baselinetasksnapshot)

## `BaselineTaskSnapshot`

<span class="api-kind">interface</span>

A snapshot of a single task's dates at the time a baseline was captured.
Used to compare planned vs. actual progress.

```ts
export interface BaselineTaskSnapshot {
  /** The task this snapshot refers to. */
  readonly taskId: TaskId;
  /** Baseline start date. */
  readonly startDate: ISODateString;
  /** Baseline end date. */
  readonly endDate: ISODateString;
  /** Baseline task duration stored canonically in hours. */
  readonly duration: number;
  /** Baseline completion percentage. */
  readonly progressPercent: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskId` | `string` | Yes | — | The task this snapshot refers to. |
| `startDate` | `ISODateString` | Yes | — | Baseline start date. |
| `endDate` | `ISODateString` | Yes | — | Baseline end date. |
| `duration` | `number` | Yes | — | Baseline task duration stored canonically in hours. |
| `progressPercent` | `number` | Yes | — | Baseline completion percentage. |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `cloneProjectSnapshot`

<span class="api-kind">function</span>

Creates a JSON-safe deep copy of a project snapshot.

```ts
export function cloneProjectSnapshot(project: ProjectSnapshot): ProjectSnapshot;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `ProjectSnapshot` | Yes | — |  |

**Related types:** [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)

## `createTaskTypeOptions`

<span class="api-kind">function</span>

Builds packaged task-type choices, optionally restricted by project policy.

```ts
export function createTaskTypeOptions(allowedTaskTypes?: readonly TaskType[], labelOverrides?: Partial<Record<TaskType, string>>): TaskTypeOption[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `allowedTaskTypes` | `readonly TaskType[] \| undefined` | No | — |  |
| `labelOverrides` | `Partial<Record<TaskType, string>> \| undefined` | No | — |  |

**Related types:** [`TaskType`](/api/gantt/data-model/#tasktype), [`TaskTypeOption`](/api/gantt/data-model/#tasktypeoption)

## `DependencyEntity`

<span class="api-kind">interface</span>

A directed link between two tasks that constrains their scheduling order.
The scheduler uses dependencies to compute task start/end dates.

```ts
export interface DependencyEntity {
  /** Unique dependency identifier. */
  readonly id: DependencyId;
  /** The task that must complete (or start) first. */
  readonly predecessorTaskId: TaskId;
  /** The task whose schedule depends on the predecessor. */
  readonly successorTaskId: TaskId;
  /** Relationship type — see {@link DependencyType}. */
  readonly type: DependencyType;
  /** Lead (negative) or lag (positive) applied to the link; calendar basis is controlled by scheduling options. */
  readonly lagDays: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique dependency identifier. |
| `predecessorTaskId` | `string` | Yes | — | The task that must complete (or start) first. |
| `successorTaskId` | `string` | Yes | — | The task whose schedule depends on the predecessor. |
| `type` | `DependencyType` | Yes | — | Relationship type — see {@link DependencyType}. |
| `lagDays` | `number` | Yes | — | Lead (negative) or lag (positive) applied to the link; calendar basis is controlled by scheduling options. |

**Related types:** [`DependencyId`](/api/gantt/data-model/#dependencyid), [`DependencyType`](/api/gantt/data-model/#dependencytype), [`TaskId`](/api/gantt/data-model/#taskid)

## `DependencyId`

<span class="api-kind">type</span>

Unique identifier for a dependency link between two tasks.

```ts
export type DependencyId = EntityId;
```

**Related types:** [`EntityId`](/api/gantt/data-model/#entityid)

## `DependencyType`

<span class="api-kind">type</span>

Defines the logical relationship between a predecessor and successor task.
- `'finish-to-start'` (FS) — successor starts after predecessor finishes.
- `'start-to-start'` (SS) — successor starts when predecessor starts.
- `'finish-to-finish'` (FF) — successor finishes when predecessor finishes.
- `'start-to-finish'` (SF) — successor finishes when predecessor starts.

```ts
export type DependencyType =
  | 'finish-to-start'
  | 'start-to-start'
  | 'finish-to-finish'
  | 'start-to-finish';
```

## `EntityId`

<span class="api-kind">type</span>

Opaque string identifier used across Gantt entities.

```ts
export type EntityId = string;
```

## `exportProjectSnapshot`

<span class="api-kind">function</span>

Serializes a project snapshot into JSON without adding persistence semantics.

```ts
export function exportProjectSnapshot(project: ProjectSnapshot, options: ProjectSnapshotJsonOptions = {}): string;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `ProjectSnapshot` | Yes | — |  |
| `options` | `ProjectSnapshotJsonOptions` | No | `{}` |  |

**Related types:** [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ProjectSnapshotJsonOptions`](/api/gantt/data-model/#projectsnapshotjsonoptions)

## `InMemoryAssignmentStore`

<span class="api-kind">class</span>

Default in-memory implementation of {@link AssignmentStore}.
Maintains by-id, by-task, and by-resource indexes that are
rebuilt on every write operation.

```ts
export class InMemoryAssignmentStore {
  constructor(assignments: readonly AssignmentEntity[] = []);
  getAll(): readonly AssignmentEntity[];
  getById(assignmentId: AssignmentId): AssignmentEntity | undefined;
  getByTaskId(taskId: TaskId): readonly AssignmentEntity[];
  getByResourceId(resourceId: ResourceId): readonly AssignmentEntity[];
  replaceAll(assignments: readonly AssignmentEntity[]): void;
  replaceTaskAssignments(taskId: TaskId, assignments: readonly AssignmentEntity[]): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `assignments` | `AssignmentEntity[]` | Yes | `[]` |  |
| `assignmentsById` | `Map<string, AssignmentEntity>` | Yes | `new Map<AssignmentId, AssignmentEntity>()` |  |
| `assignmentsByTaskId` | `Map<string, AssignmentEntity[]>` | Yes | `new Map<TaskId, AssignmentEntity[]>()` |  |
| `assignmentsByResourceId` | `Map<string, AssignmentEntity[]>` | Yes | `new Map<ResourceId, AssignmentEntity[]>()` |  |
| `getAll()` | `readonly AssignmentEntity[]` | Yes | — |  |
| `getById(assignmentId: AssignmentId)` | `AssignmentEntity \| undefined` | Yes | — |  |
| `getByTaskId(taskId: TaskId)` | `readonly AssignmentEntity[]` | Yes | — |  |
| `getByResourceId(resourceId: ResourceId)` | `readonly AssignmentEntity[]` | Yes | — |  |
| `replaceAll(assignments: readonly AssignmentEntity[])` | `void` | Yes | — |  |
| `replaceTaskAssignments(taskId: TaskId, assignments: readonly AssignmentEntity[])` | `void` | Yes | — |  |
| `rebuildIndexes()` | `void` | Yes | — |  |

**Related types:** [`AssignmentEntity`](/api/gantt/data-model/#assignmententity), [`AssignmentId`](/api/gantt/data-model/#assignmentid), [`ResourceId`](/api/gantt/data-model/#resourceid), [`TaskId`](/api/gantt/data-model/#taskid)

## `InMemoryResourceStore`

<span class="api-kind">class</span>

Default in-memory implementation of {@link ResourceStore}.

```ts
export class InMemoryResourceStore {
  constructor(resources: readonly ResourceEntity[] = []);
  getAll(): readonly ResourceEntity[];
  getById(resourceId: ResourceId): ResourceEntity | undefined;
  replaceAll(resources: readonly ResourceEntity[]): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `resources` | `ResourceEntity[]` | Yes | `[]` |  |
| `resourcesById` | `Map<string, ResourceEntity>` | Yes | `new Map<ResourceId, ResourceEntity>()` |  |
| `getAll()` | `readonly ResourceEntity[]` | Yes | — |  |
| `getById(resourceId: ResourceId)` | `ResourceEntity \| undefined` | Yes | — |  |
| `replaceAll(resources: readonly ResourceEntity[])` | `void` | Yes | — |  |

**Related types:** [`ResourceEntity`](/api/gantt/data-model/#resourceentity), [`ResourceId`](/api/gantt/data-model/#resourceid)

## `InMemoryTaskStore`

<span class="api-kind">class</span>

Default in-memory implementation of {@link TaskStore}.
Maintains parent–child indexes and task mutation state.

```ts
export class InMemoryTaskStore {
  constructor(tasks: readonly TaskEntity[] = []);
  getAll(): readonly TaskEntity[];
  getTaskRevision(): number;
  getById(taskId: TaskId): TaskEntity | undefined;
  getOrderedRows(): readonly TaskTreeRow[];
  getRoots(): readonly TaskEntity[];
  getChildren(parentId: TaskId): readonly TaskEntity[];
  getParent(taskId: TaskId): TaskEntity | undefined;
  hasChildren(taskId: TaskId): boolean;
  getIndentLevel(taskId: TaskId): number;
  updateTask(taskId: TaskId, patch: TaskUpdate): TaskEntity;
  replaceAll(tasks: readonly TaskEntity[]): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `allTasks` | `TaskEntity[]` | Yes | `[]` |  |
| `tasksById` | `Map<string, TaskEntity>` | Yes | `new Map<TaskId, TaskEntity>()` |  |
| `childrenByParentId` | `Map<string \| null, TaskEntity[]>` | Yes | `new Map()` |  |
| `parentById` | `Map<string, string \| null>` | Yes | `new Map<TaskId, TaskId \| null>()` |  |
| `depthById` | `Map<string, number>` | Yes | `new Map<TaskId, number>()` |  |
| `taskRevision` | `number` | Yes | `0` |  |
| `getAll()` | `readonly TaskEntity[]` | Yes | — |  |
| `getTaskRevision()` | `number` | Yes | — |  |
| `getById(taskId: TaskId)` | `TaskEntity \| undefined` | Yes | — |  |
| `getOrderedRows()` | `readonly TaskTreeRow[]` | Yes | — |  |
| `getRoots()` | `readonly TaskEntity[]` | Yes | — |  |
| `getChildren(parentId: TaskId)` | `readonly TaskEntity[]` | Yes | — |  |
| `getParent(taskId: TaskId)` | `TaskEntity \| undefined` | Yes | — |  |
| `hasChildren(taskId: TaskId)` | `boolean` | Yes | — |  |
| `getIndentLevel(taskId: TaskId)` | `number` | Yes | — |  |
| `updateTask(taskId: TaskId, patch: TaskUpdate)` | `TaskEntity` | Yes | — |  |
| `replaceAll(tasks: readonly TaskEntity[])` | `void` | Yes | — |  |

**Related types:** [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskId`](/api/gantt/data-model/#taskid), [`TaskTreeRow`](/api/gantt/data-model/#tasktreerow), [`TaskUpdate`](/api/gantt/data-model/#taskupdate)

## `parseProjectSnapshotJson`

<span class="api-kind">function</span>

Parses and lightly validates a JSON project snapshot.

```ts
export function parseProjectSnapshotJson(json: string): ProjectSnapshotParseResult;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `json` | `string` | Yes | — |  |

**Related types:** [`ProjectSnapshotParseResult`](/api/gantt/data-model/#projectsnapshotparseresult)

## `parseTaskTypeValue`

<span class="api-kind">function</span>

Resolves a canonical task type or any packaged/default localized label.

```ts
export function parseTaskTypeValue(value: unknown, labelOverrides?: Partial<Record<TaskType, string>>): TaskType | null;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `value` | `unknown` | Yes | — |  |
| `labelOverrides` | `Partial<Record<TaskType, string>> \| undefined` | No | — |  |

**Related types:** [`TaskType`](/api/gantt/data-model/#tasktype)

## `ProjectSnapshot`

<span class="api-kind">interface</span>

Complete state of the Gantt project at a single point in time.
This is the primary input to the {@link GanttPlugin} — pass it via
the grid's `gantt`, `ganttDependencies`, `ganttCalendars`, etc. properties.

```ts
export interface ProjectSnapshot {
  /** Project identifier. */
  readonly id: EntityId;
  /** Project name. */
  readonly name: string;
  /** Semantic version of the project data schema. */
  readonly version: string;
  /** Currency code used for cost calculations (e.g. `"USD"`). */
  readonly currency: string;
  /** Default IANA time zone for the project. */
  readonly timeZone: string;
  /** Calendar used by default for new tasks. */
  readonly primaryCalendarId: CalendarId;
  /** Project duration display and working-time conversion settings. */
  readonly durationSettings?: DurationSettings;
  /** Timestamp of the last modification. */
  readonly updatedAt: ISODateTimeString;
  /** Reporting date used to calculate Microsoft Project-style task status. Defaults to today. */
  readonly statusDate?: ISODateString;
  /** All tasks in the project. */
  readonly tasks: readonly TaskEntity[];
  /** All dependency links between tasks. */
  readonly dependencies: readonly DependencyEntity[];
  /** All available resources. */
  readonly resources: readonly ResourceEntity[];
  /** All task–resource assignments. */
  readonly assignments: readonly AssignmentEntity[];
  /** All working calendars. */
  readonly calendars: readonly CalendarEntity[];
  /** Historical baseline snapshots. */
  readonly baselines: readonly BaselineSnapshot[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Project identifier. |
| `name` | `string` | Yes | — | Project name. |
| `version` | `string` | Yes | — | Semantic version of the project data schema. |
| `currency` | `string` | Yes | — | Currency code used for cost calculations (e.g. `"USD"`). |
| `timeZone` | `string` | Yes | — | Default IANA time zone for the project. |
| `primaryCalendarId` | `CalendarId` | Yes | — | Calendar used by default for new tasks. |
| `durationSettings` | `DurationSettings \| undefined` | No | — | Project duration display and working-time conversion settings. |
| `updatedAt` | ``${number}-${number}-${number}T${string}`` | Yes | — | Timestamp of the last modification. |
| `statusDate` | `ISODateString \| undefined` | No | — | Reporting date used to calculate Microsoft Project-style task status. Defaults to today. |
| `tasks` | `readonly TaskEntity[]` | Yes | — | All tasks in the project. |
| `dependencies` | `readonly DependencyEntity[]` | Yes | — | All dependency links between tasks. |
| `resources` | `readonly ResourceEntity[]` | Yes | — | All available resources. |
| `assignments` | `readonly AssignmentEntity[]` | Yes | — | All task–resource assignments. |
| `calendars` | `readonly CalendarEntity[]` | Yes | — | All working calendars. |
| `baselines` | `readonly BaselineSnapshot[]` | Yes | — | Historical baseline snapshots. |

**Related types:** [`AssignmentEntity`](/api/gantt/data-model/#assignmententity), [`BaselineSnapshot`](/api/gantt/data-model/#baselinesnapshot), [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`EntityId`](/api/gantt/data-model/#entityid), [`ResourceEntity`](/api/gantt/data-model/#resourceentity), [`TaskEntity`](/api/gantt/data-model/#taskentity)

## `ProjectSnapshotJsonOptions`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotJsonOptions {
  /** Indentation passed to `JSON.stringify` for readable exports. */
  readonly space?: number | string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `space` | `string \| number \| undefined` | No | — | Indentation passed to `JSON.stringify` for readable exports. |

## `ProjectSnapshotParseFailure`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotParseFailure {
  readonly ok: false;
  readonly error: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `ok` | `false` | Yes | — |  |
| `error` | `string` | Yes | — |  |

## `ProjectSnapshotParseResult`

<span class="api-kind">type</span>

```ts
export type ProjectSnapshotParseResult = ProjectSnapshotParseSuccess | ProjectSnapshotParseFailure;
```

**Related types:** [`ProjectSnapshotParseFailure`](/api/gantt/data-model/#projectsnapshotparsefailure), [`ProjectSnapshotParseSuccess`](/api/gantt/data-model/#projectsnapshotparsesuccess)

## `ProjectSnapshotParseSuccess`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotParseSuccess {
  readonly ok: true;
  readonly project: ProjectSnapshot;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `ok` | `true` | Yes | — |  |
| `project` | `ProjectSnapshot` | Yes | — |  |

**Related types:** [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)

## `resolveTaskTypeAfterDurationEdit`

<span class="api-kind">function</span>

Keeps the zero-duration milestone transition reversible.

A positive duration cannot remain a milestone, while task and summary types
otherwise retain their existing ownership and validation rules.

```ts
export function resolveTaskTypeAfterDurationEdit(currentType: TaskType, durationHours: number): TaskType;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `currentType` | `TaskType` | Yes | — |  |
| `durationHours` | `number` | Yes | — |  |

**Related types:** [`TaskType`](/api/gantt/data-model/#tasktype)

## `ResourceEntity`

<span class="api-kind">interface</span>

A person, team, or piece of equipment that can be assigned to tasks.

```ts
export interface ResourceEntity extends ResourceIdentity<ResourceId> {
  /** Unique resource identifier. */
  /** Display name of the resource. */
  /** Optional profile image URL displayed in resource-oriented views. */
  /** Role or job title. */
  readonly role: string;
  /** Working calendar for this resource. */
  readonly calendarId: CalendarId;
  /** Maximum allocation capacity. Accepts either `100` or `1.0` for 100 %. */
  readonly allocationCapacity: number;
  /** Cost per hour in the project currency. */
  readonly hourlyCost: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `role` | `string` | Yes | — | Unique resource identifier.  Display name of the resource.  Optional profile image URL displayed in resource-oriented views.  Role or job title. |
| `calendarId` | `CalendarId` | Yes | — | Working calendar for this resource. |
| `allocationCapacity` | `number` | Yes | — | Maximum allocation capacity. Accepts either `100` or `1.0` for 100 %. |
| `hourlyCost` | `number` | Yes | — | Cost per hour in the project currency. |

**Related types:** [`ResourceId`](/api/gantt/data-model/#resourceid)

## `ResourceId`

<span class="api-kind">type</span>

Unique identifier for a resource (person or equipment).

```ts
export type ResourceId = EntityId;
```

**Related types:** [`EntityId`](/api/gantt/data-model/#entityid)

## `ResourceStore`

<span class="api-kind">interface</span>

Read/write store for {@link ResourceEntity} instances.
Provides lookup by id and bulk replacement.

```ts
export interface ResourceStore {
  /** Returns all resources. */
  getAll(): readonly ResourceEntity[];
  /** Looks up a resource by its id. */
  getById(resourceId: ResourceId): ResourceEntity | undefined;
  /** Replaces the entire resource list. */
  replaceAll(resources: readonly ResourceEntity[]): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `getAll()` | `readonly ResourceEntity[]` | Yes | — | Returns all resources. |
| `getById(resourceId: ResourceId)` | `ResourceEntity \| undefined` | Yes | — | Looks up a resource by its id. |
| `replaceAll(resources: readonly ResourceEntity[])` | `void` | Yes | — | Replaces the entire resource list. |

**Related types:** [`ResourceEntity`](/api/gantt/data-model/#resourceentity), [`ResourceId`](/api/gantt/data-model/#resourceid)

## `TASK_TYPE_LABELS`

<span class="api-kind">constant</span>

```ts
export const TASK_TYPE_LABELS: Readonly<Record<TaskType, string>>;
```

**Related types:** [`TaskType`](/api/gantt/data-model/#tasktype)

## `TASK_TYPE_VALUES`

<span class="api-kind">constant</span>

Canonical task kinds in the order used by packaged editors.

```ts
export const TASK_TYPE_VALUES: readonly ["task", "milestone", "summary"];
```

## `TaskConstraintType`

<span class="api-kind">type</span>

Scheduling constraint applied to a task's start or finish date.
The scheduler engine honours these constraints when computing the schedule.

```ts
export type TaskConstraintType =
  | 'start-no-earlier-than'
  | 'start-no-later-than'
  | 'finish-no-earlier-than'
  | 'finish-no-later-than'
  | 'must-start-on'
  | 'must-finish-on';
```

## `TaskEffortMode`

<span class="api-kind">type</span>

Determines which task variable remains fixed when work, duration, or units change.
Mirrors the common Microsoft Project task type model.

RevoGrid applies the model during schedule calculation and task/assignment
mutation. The edit matrix is deterministic and formula-based; it intentionally
does not mirror every Microsoft Project prompt or per-assignment side-effect.

```ts
export type TaskEffortMode = 'fixed-duration' | 'fixed-work' | 'fixed-units';
```

## `TaskEntity`

<span class="api-kind">interface</span>

Represents a single task (work item) in the Gantt project.
Tasks form a tree structure via {@link parentId} and are the primary
data source for the Gantt timeline.

```ts
export interface TaskEntity {
  /** Unique task identifier. */
  readonly id: TaskId;
  /** Project this task belongs to. */
  readonly projectId: EntityId;
  /** Parent task id, or `null` for root-level tasks. */
  readonly parentId: TaskId | null;
  /** Work Breakdown Structure code (e.g. `"1.2.3"`). */
  readonly wbsCode: string;
  /** Human-readable task name. */
  readonly name: string;
  /** Optional authored task-bar color. */
  readonly color?: string;
  /** Determines scheduling behaviour — see {@link TaskType}. */
  readonly type: TaskType;
  /** Optional user-authored workflow state — see {@link TaskWorkflowStatus}. */
  readonly workflowStatus?: TaskWorkflowStatus;
  /** Planned start date (inclusive). */
  readonly startDate: ISODateString;
  /** Planned end date (inclusive). */
  readonly endDate: ISODateString;
  /** Planned task duration stored canonically in hours. */
  readonly duration: number;
  /** Unit retained only for authored/display formatting; it does not change storage. */
  readonly durationUnit?: DurationUnit;
  /** When true, duration is continuous elapsed time and ignores working calendars. */
  readonly durationIsElapsed?: boolean;
  /** Task type used for work/duration/unit calculations. Defaults to `fixed-duration`. */
  readonly effortMode?: TaskEffortMode;
  /** Whether resource changes should preserve total work where the task type allows it. */
  readonly effortDriven?: boolean;
  /** Planned work for the task, in hours. */
  readonly workHours?: number;
  /** Unit retained for Work display and editing; canonical storage remains hours. */
  readonly workUnit?: DurationUnit;
  /** Remaining duration stored canonically in hours; used when progress rescheduling is enabled. */
  readonly remainingDuration?: number;
  /** Date work actually started; anchors the schedule only under progress-aware rescheduling. */
  readonly actualStartDate?: ISODateString;
  /** Date work actually finished; always pins completed work to the recorded finish. */
  readonly actualFinishDate?: ISODateString;
  /** Non-working gaps inside the task span. */
  readonly splitRanges?: readonly TaskSplitRange[];
  /** When `true`, authored dates are preserved and dependency violations become diagnostics. */
  readonly manuallyScheduled?: boolean;
  /** When `true`, the task is excluded from scheduling and critical-path analysis. */
  readonly inactive?: boolean;
  /** Leveling priority from 0 to 1000. Higher priority tasks are protected first. Defaults to 500. */
  readonly priority?: number;
  /** Whether automatic resource leveling may delay this task. Defaults to true. */
  readonly canLevel?: boolean;
  /** When `true`, packaged Gantt task mutations are rejected for this task. */
  readonly locked?: boolean;
  /** Existing resource leveling delay in calendar days. Defaults to 0. */
  readonly levelingDelayDays?: number;
  /** Optional scheduling constraint type — see {@link TaskConstraintType}. */
  readonly constraintType?: TaskConstraintType;
  /** Date associated with the scheduling constraint. */
  readonly constraintDate?: ISODateString;
  /** Deadline date — tasks finishing after this date are flagged. */
  readonly deadlineDate?: ISODateString;
  /** Completion percentage (0–100). */
  readonly progressPercent: number;
  /** Calendar governing working days and holidays for this task. */
  readonly calendarId: CalendarId;
  /** Whether this task lies on the critical path. */
  readonly isCritical: boolean;
  /** Optional free-text notes attached to the task. */
  readonly notes?: string;
  /** Arbitrary tags for categorisation or filtering. */
  readonly tags: readonly string[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique task identifier. |
| `projectId` | `string` | Yes | — | Project this task belongs to. |
| `parentId` | `string \| null` | Yes | — | Parent task id, or `null` for root-level tasks. |
| `wbsCode` | `string` | Yes | — | Work Breakdown Structure code (e.g. `"1.2.3"`). |
| `name` | `string` | Yes | — | Human-readable task name. |
| `color` | `string \| undefined` | No | — | Optional authored task-bar color. |
| `type` | `TaskType` | Yes | — | Determines scheduling behaviour — see {@link TaskType}. |
| `workflowStatus` | `TaskWorkflowStatus \| undefined` | No | — | Optional user-authored workflow state — see {@link TaskWorkflowStatus}. |
| `startDate` | `ISODateString` | Yes | — | Planned start date (inclusive). |
| `endDate` | `ISODateString` | Yes | — | Planned end date (inclusive). |
| `duration` | `number` | Yes | — | Planned task duration stored canonically in hours. |
| `durationUnit` | `DurationUnit \| undefined` | No | — | Unit retained only for authored/display formatting; it does not change storage. |
| `durationIsElapsed` | `boolean \| undefined` | No | — | When true, duration is continuous elapsed time and ignores working calendars. |
| `effortMode` | `TaskEffortMode \| undefined` | No | — | Task type used for work/duration/unit calculations. Defaults to `fixed-duration`. |
| `effortDriven` | `boolean \| undefined` | No | — | Whether resource changes should preserve total work where the task type allows it. |
| `workHours` | `number \| undefined` | No | — | Planned work for the task, in hours. |
| `workUnit` | `DurationUnit \| undefined` | No | — | Unit retained for Work display and editing; canonical storage remains hours. |
| `remainingDuration` | `number \| undefined` | No | — | Remaining duration stored canonically in hours; used when progress rescheduling is enabled. |
| `actualStartDate` | `ISODateString \| undefined` | No | — | Date work actually started; anchors the schedule only under progress-aware rescheduling. |
| `actualFinishDate` | `ISODateString \| undefined` | No | — | Date work actually finished; always pins completed work to the recorded finish. |
| `splitRanges` | `readonly TaskSplitRange[] \| undefined` | No | — | Non-working gaps inside the task span. |
| `manuallyScheduled` | `boolean \| undefined` | No | — | When `true`, authored dates are preserved and dependency violations become diagnostics. |
| `inactive` | `boolean \| undefined` | No | — | When `true`, the task is excluded from scheduling and critical-path analysis. |
| `priority` | `number \| undefined` | No | — | Leveling priority from 0 to 1000. Higher priority tasks are protected first. Defaults to 500. |
| `canLevel` | `boolean \| undefined` | No | — | Whether automatic resource leveling may delay this task. Defaults to true. |
| `locked` | `boolean \| undefined` | No | — | When `true`, packaged Gantt task mutations are rejected for this task. |
| `levelingDelayDays` | `number \| undefined` | No | — | Existing resource leveling delay in calendar days. Defaults to 0. |
| `constraintType` | `TaskConstraintType \| undefined` | No | — | Optional scheduling constraint type — see {@link TaskConstraintType}. |
| `constraintDate` | `ISODateString \| undefined` | No | — | Date associated with the scheduling constraint. |
| `deadlineDate` | `ISODateString \| undefined` | No | — | Deadline date — tasks finishing after this date are flagged. |
| `progressPercent` | `number` | Yes | — | Completion percentage (0–100). |
| `calendarId` | `CalendarId` | Yes | — | Calendar governing working days and holidays for this task. |
| `isCritical` | `boolean` | Yes | — | Whether this task lies on the critical path. |
| `notes` | `string \| undefined` | No | — | Optional free-text notes attached to the task. |
| `tags` | `readonly string[]` | Yes | — | Arbitrary tags for categorisation or filtering. |

**Related types:** [`EntityId`](/api/gantt/data-model/#entityid), [`TaskConstraintType`](/api/gantt/data-model/#taskconstrainttype), [`TaskEffortMode`](/api/gantt/data-model/#taskeffortmode), [`TaskId`](/api/gantt/data-model/#taskid), [`TaskSplitRange`](/api/gantt/data-model/#tasksplitrange), [`TaskType`](/api/gantt/data-model/#tasktype), [`TaskWorkflowStatus`](/api/gantt/data-model/#taskworkflowstatus)

## `TaskId`

<span class="api-kind">type</span>

Unique identifier for a task within a project.

```ts
export type TaskId = EntityId;
```

**Related types:** [`EntityId`](/api/gantt/data-model/#entityid)

## `TaskSplitRange`

<span class="api-kind">interface</span>

Date range where work is intentionally split and the task should not consume work.
Split ranges extend the computed finish because the same work is spread over
more calendar time.

```ts
export interface TaskSplitRange {
  /** Split start date (inclusive). */
  readonly startDate: ISODateString;
  /** Split end date (inclusive). */
  readonly endDate: ISODateString;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `startDate` | `ISODateString` | Yes | — | Split start date (inclusive). |
| `endDate` | `ISODateString` | Yes | — | Split end date (inclusive). |

## `TaskStatus`

<span class="api-kind">type</span>

Microsoft Project-style calculated schedule health for a task.

```ts
export type TaskStatus = 'complete' | 'on-schedule' | 'late' | 'future-task';
```

## `TaskStore`

<span class="api-kind">interface</span>

Read/write store that manages the hierarchical task list.
Handles parent–child relationships and incremental task updates.

```ts
export interface TaskStore {
  /** Returns all tasks in insertion order. */
  getAll(): readonly TaskEntity[];
  /** Monotonically increasing revision counter bumped on every task data change. */
  getTaskRevision(): number;
  /** Returns every task as a {@link TaskTreeRow} in canonical authored tree order. */
  getOrderedRows(): readonly TaskTreeRow[];
  /** Looks up a task by its id. */
  getById(taskId: TaskId): TaskEntity | undefined;
  /** Returns top-level (root) tasks. */
  getRoots(): readonly TaskEntity[];
  /** Returns direct children of the given parent task. */
  getChildren(parentId: TaskId): readonly TaskEntity[];
  /** Returns the parent task, or `undefined` for root tasks. */
  getParent(taskId: TaskId): TaskEntity | undefined;
  /** Returns `true` if the task has at least one child. */
  hasChildren(taskId: TaskId): boolean;
  /** Returns the nesting depth of a task in the tree hierarchy. */
  getIndentLevel(taskId: TaskId): number;
  /** Applies a partial update to a task and returns the updated entity. */
  updateTask(taskId: TaskId, patch: TaskUpdate): TaskEntity;
  /** Replaces the entire task list, rebuilding internal indexes. */
  replaceAll(tasks: readonly TaskEntity[]): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `getAll()` | `readonly TaskEntity[]` | Yes | — | Returns all tasks in insertion order. |
| `getTaskRevision()` | `number` | Yes | — | Monotonically increasing revision counter bumped on every task data change. |
| `getOrderedRows()` | `readonly TaskTreeRow[]` | Yes | — | Returns every task as a {@link TaskTreeRow} in canonical authored tree order. |
| `getById(taskId: TaskId)` | `TaskEntity \| undefined` | Yes | — | Looks up a task by its id. |
| `getRoots()` | `readonly TaskEntity[]` | Yes | — | Returns top-level (root) tasks. |
| `getChildren(parentId: TaskId)` | `readonly TaskEntity[]` | Yes | — | Returns direct children of the given parent task. |
| `getParent(taskId: TaskId)` | `TaskEntity \| undefined` | Yes | — | Returns the parent task, or `undefined` for root tasks. |
| `hasChildren(taskId: TaskId)` | `boolean` | Yes | — | Returns `true` if the task has at least one child. |
| `getIndentLevel(taskId: TaskId)` | `number` | Yes | — | Returns the nesting depth of a task in the tree hierarchy. |
| `updateTask(taskId: TaskId, patch: TaskUpdate)` | `TaskEntity` | Yes | — | Applies a partial update to a task and returns the updated entity. |
| `replaceAll(tasks: readonly TaskEntity[])` | `void` | Yes | — | Replaces the entire task list, rebuilding internal indexes. |

**Related types:** [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskId`](/api/gantt/data-model/#taskid), [`TaskTreeRow`](/api/gantt/data-model/#tasktreerow), [`TaskUpdate`](/api/gantt/data-model/#taskupdate)

## `TaskTreeRow`

<span class="api-kind">interface</span>

A task together with its canonical position in the authored tree.
Grid visibility, expansion, sorting, filtering, and selection live in the
RevoGrid runtime layer, not in this domain store.

```ts
export interface TaskTreeRow {
  /** The underlying task entity. */
  readonly task: TaskEntity;
  /** Nesting depth (0 for root tasks). */
  readonly depth: number;
  /** Whether the task has child tasks. */
  readonly hasChildren: boolean;
  /** Zero-based index in the canonical flattened tree. */
  readonly index: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `task` | `TaskEntity` | Yes | — | The underlying task entity. |
| `depth` | `number` | Yes | — | Nesting depth (0 for root tasks). |
| `hasChildren` | `boolean` | Yes | — | Whether the task has child tasks. |
| `index` | `number` | Yes | — | Zero-based index in the canonical flattened tree. |

**Related types:** [`TaskEntity`](/api/gantt/data-model/#taskentity)

## `TaskType`

<span class="api-kind">type</span>

Determines how a task is treated by the scheduling engine.
- `'summary'` — a parent task whose dates roll up from its children.
- `'task'` — a regular schedulable work item with its own duration.
- `'milestone'` — a zero-duration marker for a key date or deliverable.

```ts
export type TaskType = 'summary' | 'task' | 'milestone';
```

## `TaskTypeOption`

<span class="api-kind">interface</span>

```ts
export interface TaskTypeOption {
  readonly label: string;
  readonly value: TaskType;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `label` | `string` | Yes | — |  |
| `value` | `TaskType` | Yes | — |  |

**Related types:** [`TaskType`](/api/gantt/data-model/#tasktype)

## `TaskUpdate`

<span class="api-kind">type</span>

Partial update payload for mutable fields of a {@link TaskEntity}.
Only the listed properties may be changed via {@link TaskStore.updateTask}.

```ts
export type TaskUpdate = Partial<
  Pick<
    TaskEntity,
    | 'name'
    | 'color'
    | 'workflowStatus'
    | 'type'
    | 'startDate'
    | 'endDate'
    | 'duration'
    | 'durationUnit'
    | 'durationIsElapsed'
    | 'workHours'
    | 'workUnit'
    | 'remainingDuration'
    | 'actualStartDate'
    | 'actualFinishDate'
    | 'splitRanges'
    | 'effortMode'
    | 'effortDriven'
    | 'progressPercent'
    | 'manuallyScheduled'
    | 'inactive'
    | 'priority'
    | 'canLevel'
    | 'levelingDelayDays'
    | 'constraintType'
    | 'constraintDate'
    | 'deadlineDate'
    | 'notes'
    | 'calendarId'
    | 'tags'
  >
>;
```

**Related types:** [`TaskEntity`](/api/gantt/data-model/#taskentity)

## `TaskWorkflowStatus`

<span class="api-kind">type</span>

User-authored workflow state kept separately from calculated schedule health.

```ts
export type TaskWorkflowStatus = 'not-started' | 'in-progress' | 'done' | 'blocked';
```

---

# Events And Lifecycle

URL: https://pro.rv-grid.com/api/gantt/events/
Source: src/content/docs/api/gantt/events.md
Description: Public RevoGrid Gantt API for events and lifecycle.
Surface: gantt

This page documents 38 public symbols exported by `@revolist/gantt`.

## `createGanttBeforeTaskChangeValidationHandler`

<span class="api-kind">function</span>

```ts
export function createGanttBeforeTaskChangeValidationHandler<TContext>(options: GanttValidationHandlerOptions<TContext>): (event: CustomEvent<GanttBeforeTaskChangeDetail>) => void;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttValidationHandlerOptions` | Yes | — |  |

**Related types:** [`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail), [`GanttValidationHandlerOptions`](/api/gantt/extensions/#ganttvalidationhandleroptions)

## `GANTT_ASSIGNMENT_CHANGE_EVENT`

<span class="api-kind">constant</span>

EventManager tag for committed assignment mutations.

```ts
export const GANTT_ASSIGNMENT_CHANGE_EVENT: "gantt-assignment-change";
```

## `GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT`

<span class="api-kind">constant</span>

Cancelable event fired before task assignments are modified.

```ts
export const GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT: "gantt-before-assignment-change";
```

## `GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT`

<span class="api-kind">constant</span>

Cancelable event fired before a dependency is created, deleted, or edited.

```ts
export const GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT: "gantt-before-dependency-change";
```

## `GANTT_BEFORE_TASK_CHANGE_EVENT`

<span class="api-kind">constant</span>

Cancelable event fired before a task is created, moved, resized, or edited.

```ts
export const GANTT_BEFORE_TASK_CHANGE_EVENT: "gantt-before-task-change";
```

## `GANTT_DEPENDENCY_CHANGE_EVENT`

<span class="api-kind">constant</span>

EventManager tag for committed dependency mutations.

```ts
export const GANTT_DEPENDENCY_CHANGE_EVENT: "gantt-dependency-change";
```

## `GANTT_DEPENDENCY_HOVER_EVENT`

<span class="api-kind">constant</span>

Fired when the user hovers over a dependency arrow.

```ts
export const GANTT_DEPENDENCY_HOVER_EVENT: "gantt-dependency-hover";
```

## `GANTT_DEPENDENCY_SELECT_EVENT`

<span class="api-kind">constant</span>

Fired when the user clicks a dependency arrow.

```ts
export const GANTT_DEPENDENCY_SELECT_EVENT: "gantt-dependency-select";
```

## `GANTT_HISTORY_RECORD_EVENT`

<span class="api-kind">constant</span>

Internal history marker used to record Gantt timeline mutations without replaying them immediately.

```ts
export const GANTT_HISTORY_RECORD_EVENT: "gantt-history-record";
```

## `GANTT_PANEL_RESIZE_EVENT`

<span class="api-kind">constant</span>

Fired when the user resizes the table/timeline panel divider.

```ts
export const GANTT_PANEL_RESIZE_EVENT: "gantt-panel-resize";
```

## `GANTT_SEARCH_EVENT`

<span class="api-kind">constant</span>

Dispatched to filter visible Gantt rows by a free-text query.

```ts
export const GANTT_SEARCH_EVENT: "gantt-search";
```

## `GANTT_TASK_CHANGE_EVENT`

<span class="api-kind">constant</span>

EventManager tag for committed task mutations.

```ts
export const GANTT_TASK_CHANGE_EVENT: "gantt-task-change";
```

## `GANTT_TASK_CONVERT_TO_MILESTONE_EVENT`

<span class="api-kind">constant</span>

Dispatched to convert the selected task into a milestone.

```ts
export const GANTT_TASK_CONVERT_TO_MILESTONE_EVENT: "gantt-task-convert-to-milestone";
```

## `GANTT_TASK_CREATE_EVENT`

<span class="api-kind">constant</span>

Dispatched to create a new task. Provide {@link GanttCreateTaskOptions} as the detail.

```ts
export const GANTT_TASK_CREATE_EVENT: "gantt-task-create";
```

## `GANTT_TASK_CREATED_EVENT`

<span class="api-kind">constant</span>

Fired after a task is created and selected.

```ts
export const GANTT_TASK_CREATED_EVENT: "gantt-task-created";
```

## `GANTT_TASK_DELETE_EVENT`

<span class="api-kind">constant</span>

Dispatched to delete the selected task and its descendants.

```ts
export const GANTT_TASK_DELETE_EVENT: "gantt-task-delete";
```

## `GANTT_TASK_EDIT_EVENT`

<span class="api-kind">constant</span>

Dispatched to open editing UI for a task.

```ts
export const GANTT_TASK_EDIT_EVENT: "gantt-task-edit";
```

## `GANTT_TASK_INDENT_EVENT`

<span class="api-kind">constant</span>

Dispatched to indent (demote) the selected task one level deeper.

```ts
export const GANTT_TASK_INDENT_EVENT: "gantt-task-indent";
```

## `GANTT_TASK_OUTDENT_EVENT`

<span class="api-kind">constant</span>

Dispatched to outdent (promote) the selected task one level up.

```ts
export const GANTT_TASK_OUTDENT_EVENT: "gantt-task-outdent";
```

## `GANTT_ZOOM_IN_EVENT`

<span class="api-kind">constant</span>

Dispatched to zoom in by one level.

```ts
export const GANTT_ZOOM_IN_EVENT: "gantt-zoom-in";
```

## `GANTT_ZOOM_OUT_EVENT`

<span class="api-kind">constant</span>

Dispatched to zoom out by one level.

```ts
export const GANTT_ZOOM_OUT_EVENT: "gantt-zoom-out";
```

## `GANTT_ZOOM_SET_LEVEL_EVENT`

<span class="api-kind">constant</span>

Dispatched to jump directly to a specific zoom level by id.

```ts
export const GANTT_ZOOM_SET_LEVEL_EVENT: "gantt-zoom-set-level";
```

## `GanttBeforeAssignmentChangeAction`

<span class="api-kind">type</span>

Kind of assignment mutation that triggered the before-change event.

```ts
export type GanttBeforeAssignmentChangeAction = 'edit';
```

## `GanttBeforeAssignmentChangeDetail`

<span class="api-kind">interface</span>

Detail payload for the cancelable {@link GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT}.
Call `event.preventDefault()` to block the change.

```ts
export interface GanttBeforeAssignmentChangeDetail {
  readonly action: GanttBeforeAssignmentChangeAction;
  readonly taskId: TaskId;
  readonly assignments: readonly AssignmentEntity[];
  readonly previousAssignments: readonly AssignmentEntity[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `action` | `"edit"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `assignments` | `readonly AssignmentEntity[]` | Yes | — |  |
| `previousAssignments` | `readonly AssignmentEntity[]` | Yes | — |  |

**Related types:** [`AssignmentEntity`](/api/gantt/data-model/#assignmententity), [`GanttBeforeAssignmentChangeAction`](/api/gantt/events/#ganttbeforeassignmentchangeaction), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttBeforeDependencyChangeAction`

<span class="api-kind">type</span>

Kind of dependency mutation that triggered the before-change event.

```ts
export type GanttBeforeDependencyChangeAction = 'create' | 'delete' | 'edit' | 'replace';
```

## `GanttBeforeDependencyChangeDetail`

<span class="api-kind">interface</span>

Detail payload for the cancelable {@link GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT}.
Call `event.preventDefault()` to block the change.

```ts
export interface GanttBeforeDependencyChangeDetail {
  readonly action: GanttBeforeDependencyChangeAction;
  readonly dependencyId: DependencyId | null;
  readonly dependency: DependencyEntity | null;
  readonly previousDependency?: DependencyEntity | null;
  /** Full proposed dependency set for batch replacements. */
  readonly dependencies?: readonly DependencyEntity[];
  /** Full previous dependency set for batch replacements. */
  readonly previousDependencies?: readonly DependencyEntity[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `action` | `GanttBeforeDependencyChangeAction` | Yes | — |  |
| `dependencyId` | `string \| null` | Yes | — |  |
| `dependency` | `DependencyEntity \| null` | Yes | — |  |
| `previousDependency` | `DependencyEntity \| null \| undefined` | No | — |  |
| `dependencies` | `readonly DependencyEntity[] \| undefined` | No | — | Full proposed dependency set for batch replacements. |
| `previousDependencies` | `readonly DependencyEntity[] \| undefined` | No | — | Full previous dependency set for batch replacements. |

**Related types:** [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`DependencyId`](/api/gantt/data-model/#dependencyid), [`GanttBeforeDependencyChangeAction`](/api/gantt/events/#ganttbeforedependencychangeaction)

## `GanttBeforeTaskChangeAction`

<span class="api-kind">type</span>

Kind of task mutation that triggered the before-change event.

```ts
export type GanttBeforeTaskChangeAction = 'move' | 'resize' | 'create' | 'edit' | 'progress' | 'split' | 'indent' | 'outdent' | 'delete' | 'convert-to-milestone';
```

## `GanttBeforeTaskChangeDetail`

<span class="api-kind">interface</span>

Detail payload for the cancelable {@link GANTT_BEFORE_TASK_CHANGE_EVENT}.
Call `event.preventDefault()` to block the change.

```ts
export interface GanttBeforeTaskChangeDetail {
  readonly action: GanttBeforeTaskChangeAction;
  readonly taskId: TaskId | null;
  /** Partial task with proposed values */
  readonly changes: Partial<TaskEntity>;
  /** Previous values of fields being changed */
  readonly previousValues: Partial<TaskEntity>;
  /** Source row that will receive the task-row write, when available. */
  readonly sourceRow?: DataType;
  /** Physical source row index that will receive the mapped write, when available. */
  readonly sourceIndex?: number;
  /** Proposed flat source-row patch for this task row. */
  readonly sourcePatch?: Record<string, unknown>;
  /** Previous source values for the keys in `sourcePatch`. */
  readonly previousSourceValues?: Record<string, unknown>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `action` | `GanttBeforeTaskChangeAction` | Yes | — |  |
| `taskId` | `string \| null` | Yes | — |  |
| `changes` | `Partial` | Yes | — | Partial task with proposed values |
| `previousValues` | `Partial` | Yes | — | Previous values of fields being changed |
| `sourceRow` | `DataType \| undefined` | No | — | Source row that will receive the task-row write, when available. |
| `sourceIndex` | `number \| undefined` | No | — | Physical source row index that will receive the mapped write, when available. |
| `sourcePatch` | `Record<string, unknown> \| undefined` | No | — | Proposed flat source-row patch for this task row. |
| `previousSourceValues` | `Record<string, unknown> \| undefined` | No | — | Previous source values for the keys in `sourcePatch`. |

**Related types:** [`GanttBeforeTaskChangeAction`](/api/gantt/events/#ganttbeforetaskchangeaction), [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttBeforeTaskChangeValidator`

<span class="api-kind">type</span>

```ts
export type GanttBeforeTaskChangeValidator<TContext = GanttValidationContext> = (
  detail: GanttBeforeTaskChangeDetail,
  context: TContext,
) => GanttValidationDecision | boolean;
```

**Related types:** [`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail), [`GanttValidationContext`](/api/gantt/extensions/#ganttvalidationcontext), [`GanttValidationDecision`](/api/gantt/extensions/#ganttvalidationdecision)

## `GanttDependencyInteractionDetail`

<span class="api-kind">interface</span>

Detail payload for dependency hover/select events.

```ts
export interface GanttDependencyInteractionDetail {
  /** Dependency id, or `null` when the interaction is cleared. */
  readonly dependencyId: DependencyId | null;
  /** Full dependency entity, or `null` when cleared. */
  readonly dependency: DependencyEntity | null;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `dependencyId` | `string \| null` | Yes | — | Dependency id, or `null` when the interaction is cleared. |
| `dependency` | `DependencyEntity \| null` | Yes | — | Full dependency entity, or `null` when cleared. |

**Related types:** [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`DependencyId`](/api/gantt/data-model/#dependencyid)

## `GanttEventManagerDomainChange`

<span class="api-kind">type</span>

Typed semantic Gantt entries carried in `EventManagerEvent.domainChanges`.

```ts
export type GanttEventManagerDomainChange =
  | EventManagerDomainChange<'gantt-task', GanttTaskDomainChangeDetail>
  | EventManagerDomainChange<'gantt-dependency', GanttDependencyDomainChangeDetail>
  | EventManagerDomainChange<'gantt-assignment', GanttAssignmentDomainChangeDetail>;
```

**Related types:** [`GanttAssignmentDomainChangeDetail`](/api/gantt/plugin/#ganttassignmentdomainchangedetail), [`GanttDependencyDomainChangeDetail`](/api/gantt/plugin/#ganttdependencydomainchangedetail), [`GanttTaskDomainChangeDetail`](/api/gantt/plugin/#gantttaskdomainchangedetail)

## `GanttEventManagerEvent`

<span class="api-kind">type</span>

Typed `gridedit` detail for consumers collecting committed Gantt changes.

```ts
export type GanttEventManagerEvent = Omit<EventManagerEvent, 'domainChanges'> & {
  readonly domainChanges?: readonly GanttEventManagerDomainChange[];
};
```

**Related types:** [`GanttEventManagerDomainChange`](/api/gantt/events/#gantteventmanagerdomainchange)

## `GanttExampleCancelableEvent`

<span class="api-kind">interface</span>

```ts
export interface GanttExampleCancelableEvent<TDetail> {
  readonly detail: TDetail;
  preventDefault(): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `detail` | `TDetail` | Yes | — |  |
| `preventDefault()` | `void` | Yes | — |  |

## `GanttPanelResizeEventDetail`

<span class="api-kind">interface</span>

Detail payload for panel resize events.

```ts
export interface GanttPanelResizeEventDetail {
  /** New panel width in pixels. */
  readonly width: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `width` | `number` | Yes | — | New panel width in pixels. |

## `GanttSearchEventDetail`

<span class="api-kind">interface</span>

Detail payload for Gantt search events.

```ts
export interface GanttSearchEventDetail {
  /** Free-text query matched against task rows, assignees, dates, status, tags, and costs. */
  readonly query: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `query` | `string` | Yes | — | Free-text query matched against task rows, assignees, dates, status, tags, and costs. |

## `GanttTaskCreatedEventDetail`

<span class="api-kind">interface</span>

Detail payload for the post-create task event.

```ts
export interface GanttTaskCreatedEventDetail {
  /** Created task id. */
  readonly taskId: TaskId;
  /** Created task entity. */
  readonly task: TaskEntity;
  /**
   * Whether task-created listeners such as the packaged editor should open a
   * follow-up UI for the new task.
   */
  readonly openEditor?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskId` | `string` | Yes | — | Created task id. |
| `task` | `TaskEntity` | Yes | — | Created task entity. |
| `openEditor` | `boolean \| undefined` | No | — | Whether task-created listeners such as the packaged editor should open a follow-up UI for the new task. |

**Related types:** [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttTaskEditEventDetail`

<span class="api-kind">interface</span>

Detail payload for task edit requests.

```ts
export interface GanttTaskEditEventDetail {
  /** Task id to edit. */
  readonly taskId: TaskId;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskId` | `string` | Yes | — | Task id to edit. |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `validateGanttBeforeTaskChange`

<span class="api-kind">function</span>

```ts
export function validateGanttBeforeTaskChange<TContext>(detail: GanttBeforeTaskChangeDetail, context: TContext, validators: readonly GanttBeforeTaskChangeValidator<TContext>[]): GanttValidationDecision;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `detail` | `GanttBeforeTaskChangeDetail` | Yes | — |  |
| `context` | `TContext` | Yes | — |  |
| `validators` | `readonly GanttBeforeTaskChangeValidator[]` | Yes | — |  |

**Related types:** [`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail), [`GanttBeforeTaskChangeValidator`](/api/gantt/events/#ganttbeforetaskchangevalidator), [`GanttValidationDecision`](/api/gantt/extensions/#ganttvalidationdecision)

---

# Editors, Toolbar, Export, And Recipes

URL: https://pro.rv-grid.com/api/gantt/extensions/
Source: src/content/docs/api/gantt/extensions.md
Description: Public RevoGrid Gantt API for editors, toolbar, export, and recipes.
Surface: gantt

This page documents 207 public symbols exported by `@revolist/gantt`.

## `ApprovalGateValidatorOptions`

<span class="api-kind">interface</span>

```ts
export interface ApprovalGateValidatorOptions<TContext extends GanttValidationContext> {
  readonly actions?: readonly GanttBeforeTaskChangeAction[];
  readonly requiresApproval?: (
    detail: GanttBeforeTaskChangeDetail,
    context: TContext,
  ) => boolean;
  readonly isApprovalValid?: (
    approval: ApprovalRecord,
    detail: GanttBeforeTaskChangeDetail,
    context: TContext,
  ) => boolean;
  readonly message?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `actions` | `readonly GanttBeforeTaskChangeAction[] \| undefined` | No | — |  |
| `requiresApproval` | `((detail: GanttBeforeTaskChangeDetail, context: TContext) => boolean) \| undefined` | No | — |  |
| `isApprovalValid` | `((approval: ApprovalRecord, detail: GanttBeforeTaskChangeDetail, context: TContext) => boolean) \| undefined` | No | — |  |
| `message` | `string \| undefined` | No | — |  |

**Related types:** [`ApprovalRecord`](/api/gantt/extensions/#approvalrecord), [`GanttBeforeTaskChangeAction`](/api/gantt/events/#ganttbeforetaskchangeaction), [`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail), [`GanttValidationContext`](/api/gantt/extensions/#ganttvalidationcontext)

## `ApprovalRecord`

<span class="api-kind">interface</span>

```ts
export interface ApprovalRecord {
  readonly approved: boolean;
  readonly approvedBy?: string;
  readonly expiresAt?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `approved` | `boolean` | Yes | — |  |
| `approvedBy` | `string \| undefined` | No | — |  |
| `expiresAt` | `string \| undefined` | No | — |  |

## `areGanttDependencyDropdownValuesEqual`

<span class="api-kind">function</span>

```ts
export function areGanttDependencyDropdownValuesEqual(left: readonly GanttDependencyDropdownValue[], right: readonly GanttDependencyDropdownValue[]): boolean;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `left` | `readonly GanttDependencyDropdownValue[]` | Yes | — |  |
| `right` | `readonly GanttDependencyDropdownValue[]` | Yes | — |  |

**Related types:** [`GanttDependencyDropdownValue`](/api/gantt/extensions/#ganttdependencydropdownvalue)

## `AssignResourceMenuItemOptions`

<span class="api-kind">interface</span>

```ts
export interface AssignResourceMenuItemOptions extends GanttContextMenuBaseItemOptions {
  readonly onAssignResource: (context: GanttContextMenuExtensionContext) => void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `onAssignResource` | `(context: GanttContextMenuExtensionContext) => void` | Yes | — |  |

**Related types:** [`GanttContextMenuBaseItemOptions`](/api/gantt/extensions/#ganttcontextmenubaseitemoptions), [`GanttContextMenuExtensionContext`](/api/gantt/extensions/#ganttcontextmenuextensioncontext)

## `buildCreateProjectSnapshotTableSql`

<span class="api-kind">function</span>

SQL shape for storing one JSONB project snapshot per project id.

```ts
export function buildCreateProjectSnapshotTableSql(options: ProjectSnapshotPostgresOptions = {}): PostgresStatement;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `ProjectSnapshotPostgresOptions` | No | `{}` |  |

**Related types:** [`PostgresStatement`](/api/gantt/extensions/#postgresstatement), [`ProjectSnapshotPostgresOptions`](/api/gantt/extensions/#projectsnapshotpostgresoptions)

## `buildLoadProjectSnapshotSql`

<span class="api-kind">function</span>

```ts
export function buildLoadProjectSnapshotSql(projectId: string, options: ProjectSnapshotPostgresOptions = {}): PostgresStatement;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `projectId` | `string` | Yes | — |  |
| `options` | `ProjectSnapshotPostgresOptions` | No | `{}` |  |

**Related types:** [`PostgresStatement`](/api/gantt/extensions/#postgresstatement), [`ProjectSnapshotPostgresOptions`](/api/gantt/extensions/#projectsnapshotpostgresoptions)

## `buildSaveProjectSnapshotSql`

<span class="api-kind">function</span>

```ts
export function buildSaveProjectSnapshotSql(project: ProjectSnapshot, options: ProjectSnapshotPostgresOptions = {}): PostgresStatement;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `ProjectSnapshot` | Yes | — |  |
| `options` | `ProjectSnapshotPostgresOptions` | No | `{}` |  |

**Related types:** [`PostgresStatement`](/api/gantt/extensions/#postgresstatement), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ProjectSnapshotPostgresOptions`](/api/gantt/extensions/#projectsnapshotpostgresoptions)

## `captureGanttBaseline`

<span class="api-kind">function</span>

```ts
export function captureGanttBaseline(grid: HTMLRevoGridElement, options?: CaptureBaselineOptions): Promise<BaselineSnapshot | null>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |
| `options` | `CaptureBaselineOptions \| undefined` | No | — |  |

**Related types:** [`BaselineSnapshot`](/api/gantt/data-model/#baselinesnapshot)

## `createApprovalGateValidator`

<span class="api-kind">function</span>

```ts
export function createApprovalGateValidator<TContext extends GanttValidationContext>(options: ApprovalGateValidatorOptions<TContext> = {}): GanttBeforeTaskChangeValidator<TContext>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `ApprovalGateValidatorOptions` | No | `{}` |  |

**Related types:** [`ApprovalGateValidatorOptions`](/api/gantt/extensions/#approvalgatevalidatoroptions), [`GanttBeforeTaskChangeValidator`](/api/gantt/events/#ganttbeforetaskchangevalidator), [`GanttValidationContext`](/api/gantt/extensions/#ganttvalidationcontext)

## `createAssignResourceMenuItem`

<span class="api-kind">function</span>

```ts
export function createAssignResourceMenuItem(options: AssignResourceMenuItemOptions): ContextMenuItem;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `AssignResourceMenuItemOptions` | Yes | — |  |

**Related types:** [`AssignResourceMenuItemOptions`](/api/gantt/extensions/#assignresourcemenuitemoptions)

## `createCustomTaskEditorFormRecipe`

<span class="api-kind">function</span>

Recipe: use the schema to render any UI form, then normalize submitted values
into the task mutation patch expected by Gantt task services.

```ts
export function createCustomTaskEditorFormRecipe(options: CustomTaskEditorRecipeOptions): CustomTaskEditorRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `CustomTaskEditorRecipeOptions` | Yes | — |  |

**Related types:** [`CustomTaskEditorRecipe`](/api/gantt/extensions/#customtaskeditorrecipe), [`CustomTaskEditorRecipeOptions`](/api/gantt/extensions/#customtaskeditorrecipeoptions)

## `createCustomValidationRecipe`

<span class="api-kind">function</span>

Recipe: compose custom before-task-change validation from small validators.
Add this handler to `gantt-before-task-change` and render `onReject` however
the app reports validation failures.

```ts
export function createCustomValidationRecipe(options: CustomValidationRecipeOptions): CustomValidationRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `CustomValidationRecipeOptions` | Yes | — |  |

**Related types:** [`CustomValidationRecipe`](/api/gantt/extensions/#customvalidationrecipe), [`CustomValidationRecipeOptions`](/api/gantt/extensions/#customvalidationrecipeoptions)

## `createDeleteTaskMenuItem`

<span class="api-kind">function</span>

```ts
export function createDeleteTaskMenuItem(options: DeleteTaskMenuItemOptions): ContextMenuItem;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `DeleteTaskMenuItemOptions` | Yes | — |  |

**Related types:** [`DeleteTaskMenuItemOptions`](/api/gantt/extensions/#deletetaskmenuitemoptions)

## `createDependencyValidationSummaryRecipe`

<span class="api-kind">function</span>

Recipe: combine scheduler diagnostics and projected row warnings into one
compact dependency-health object for side panels, badges, or command palettes.

```ts
export function createDependencyValidationSummaryRecipe(input: DependencyValidationSummaryInput): DependencyValidationSummaryRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `input` | `DependencyValidationSummaryInput` | Yes | — |  |

**Related types:** [`DependencyValidationSummaryRecipe`](/api/gantt/extensions/#dependencyvalidationsummaryrecipe)

## `createDuplicateTaskMenuItem`

<span class="api-kind">function</span>

```ts
export function createDuplicateTaskMenuItem(options: DuplicateTaskMenuItemOptions = {}): ContextMenuItem;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `DuplicateTaskMenuItemOptions` | No | `{}` |  |

**Related types:** [`DuplicateTaskMenuItemOptions`](/api/gantt/extensions/#duplicatetaskmenuitemoptions)

## `createExportMenuItem`

<span class="api-kind">function</span>

```ts
export function createExportMenuItem(options: ExportMenuItemOptions = {}): ContextMenuItem;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `ExportMenuItemOptions` | No | `{}` |  |

**Related types:** [`ExportMenuItemOptions`](/api/gantt/extensions/#exportmenuitemoptions)

## `createForbiddenDateRangeValidator`

<span class="api-kind">function</span>

```ts
export function createForbiddenDateRangeValidator<TContext extends GanttValidationContext>(options: ForbiddenDateRangeValidatorOptions): GanttBeforeTaskChangeValidator<TContext>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `ForbiddenDateRangeValidatorOptions` | Yes | — |  |

**Related types:** [`ForbiddenDateRangeValidatorOptions`](/api/gantt/extensions/#forbiddendaterangevalidatoroptions), [`GanttBeforeTaskChangeValidator`](/api/gantt/events/#ganttbeforetaskchangevalidator), [`GanttValidationContext`](/api/gantt/extensions/#ganttvalidationcontext)

## `createGanttColumnPresetRecipe`

<span class="api-kind">function</span>

Framework-neutral column recipe for switching between Gantt-aware presets and
customer-defined columns before assigning the result to `grid.columns`.

```ts
export function createGanttColumnPresetRecipe(options: GanttColumnPresetRecipeOptions): GanttColumnPresetRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttColumnPresetRecipeOptions` | Yes | — |  |

**Related types:** [`GanttColumnPresetRecipe`](/api/gantt/extensions/#ganttcolumnpresetrecipe), [`GanttColumnPresetRecipeOptions`](/api/gantt/extensions/#ganttcolumnpresetrecipeoptions)

## `createGanttContextMenuExtensionItems`

<span class="api-kind">function</span>

```ts
export function createGanttContextMenuExtensionItems(options: {
  readonly duplicate?: DuplicateTaskMenuItemOptions | false;
  readonly delete?: DeleteTaskMenuItemOptions | false;
  readonly assignResource?: AssignResourceMenuItemOptions | false;
  readonly export?: ExportMenuItemOptions | false;
}): ContextMenuItem[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `{ readonly duplicate?: DuplicateTaskMenuItemOptions \| false; readonly delete?: DeleteTaskMenuItemOptions \| false; readonly assignResource?: AssignResourceMenuItemOptions \| false; readonly export?: ExportMenuItemOptions \| false; }` | Yes | — |  |

**Related types:** [`AssignResourceMenuItemOptions`](/api/gantt/extensions/#assignresourcemenuitemoptions), [`DeleteTaskMenuItemOptions`](/api/gantt/extensions/#deletetaskmenuitemoptions), [`DuplicateTaskMenuItemOptions`](/api/gantt/extensions/#duplicatetaskmenuitemoptions), [`ExportMenuItemOptions`](/api/gantt/extensions/#exportmenuitemoptions)

## `createGanttContextMenuQuickWinRecipe`

<span class="api-kind">function</span>

Framework-neutral context-menu recipe for composing the Gantt quick actions
with RevoGrid Pro's context-menu plugin.

```ts
export function createGanttContextMenuQuickWinRecipe(options: GanttContextMenuQuickWinRecipeOptions): readonly ContextMenuItem[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttContextMenuQuickWinRecipeOptions` | Yes | — |  |

**Related types:** [`GanttContextMenuQuickWinRecipeOptions`](/api/gantt/extensions/#ganttcontextmenuquickwinrecipeoptions)

## `createGanttExcelExportRecipe`

<span class="api-kind">function</span>

Framework-neutral Excel recipe for customers that export the projected Gantt
task table instead of serializing renderer-only timeline fields.

```ts
export function createGanttExcelExportRecipe(options: GanttExcelExportRecipeOptions): GanttExcelExportRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttExcelExportRecipeOptions` | Yes | — |  |

**Related types:** [`GanttExcelExportRecipe`](/api/gantt/extensions/#ganttexcelexportrecipe), [`GanttExcelExportRecipeOptions`](/api/gantt/extensions/#ganttexcelexportrecipeoptions)

## `createGanttPdfExcelReportingRecipe`

<span class="api-kind">function</span>

Framework-neutral reporting recipe for toolbars that offer both stakeholder
PDF reports and spreadsheet handoff from the same Gantt grid.

```ts
export function createGanttPdfExcelReportingRecipe(options: GanttPdfExcelReportingRecipeOptions): GanttPdfExcelReportingRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttPdfExcelReportingRecipeOptions` | Yes | — |  |

**Related types:** [`GanttPdfExcelReportingRecipe`](/api/gantt/extensions/#ganttpdfexcelreportingrecipe), [`GanttPdfExcelReportingRecipeOptions`](/api/gantt/extensions/#ganttpdfexcelreportingrecipeoptions)

## `createGanttPrintOptions`

<span class="api-kind">function</span>

```ts
export function createGanttPrintOptions(options: GanttPrintStyleOptions = {}): NormalizedGanttPrintOptions;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttPrintStyleOptions` | No | `{}` |  |

**Related types:** [`GanttPrintStyleOptions`](/api/gantt/extensions/#ganttprintstyleoptions)

## `createGanttPrintStyles`

<span class="api-kind">function</span>

```ts
export function createGanttPrintStyles(options: GanttPrintStyleOptions = {}): string;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttPrintStyleOptions` | No | `{}` |  |

**Related types:** [`GanttPrintStyleOptions`](/api/gantt/extensions/#ganttprintstyleoptions)

## `createGanttTaskStatusIndicatorRecipe`

<span class="api-kind">function</span>

Framework-neutral visual-indicator recipe for read-only projects and locked
tasks. The returned class/title values can be bound to a custom cell renderer
or status column without changing the projected task row.

```ts
export function createGanttTaskStatusIndicatorRecipe(options: GanttTaskStatusIndicatorRecipeOptions): readonly GanttTaskStatusIndicatorRecipeRow[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttTaskStatusIndicatorRecipeOptions` | Yes | — |  |

**Related types:** [`GanttTaskStatusIndicatorRecipeOptions`](/api/gantt/extensions/#gantttaskstatusindicatorrecipeoptions), [`GanttTaskStatusIndicatorRecipeRow`](/api/gantt/extensions/#gantttaskstatusindicatorreciperow)

## `createGanttToolbarQuickWinActions`

<span class="api-kind">function</span>

Framework-neutral command descriptors for common Gantt toolbar additions.

Render the returned commands in any toolbar UI and call `run()` from the
button handler. Creating the descriptors does not dispatch events, scroll, or
mutate the grid.

```ts
export function createGanttToolbarQuickWinActions(grid: HTMLRevoGridElement, options: GanttToolbarQuickWinOptions = {}): GanttToolbarQuickWinActions;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |
| `options` | `GanttToolbarQuickWinOptions` | No | `{}` |  |

**Related types:** [`GanttToolbarQuickWinActions`](/api/gantt/extensions/#gantttoolbarquickwinactions), [`GanttToolbarQuickWinOptions`](/api/gantt/extensions/#gantttoolbarquickwinoptions)

## `createGraphqlProjectPersistenceRecipe`

<span class="api-kind">function</span>

```ts
export function createGraphqlProjectPersistenceRecipe(options: ProjectSnapshotGraphqlAdapterOptions, state: ProjectSnapshotState): ProjectSnapshotPersistenceRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `ProjectSnapshotGraphqlAdapterOptions` | Yes | — |  |
| `state` | `ProjectSnapshotState` | Yes | — |  |

**Related types:** [`ProjectSnapshotGraphqlAdapterOptions`](/api/gantt/extensions/#projectsnapshotgraphqladapteroptions), [`ProjectSnapshotPersistenceRecipe`](/api/gantt/extensions/#projectsnapshotpersistencerecipe), [`ProjectSnapshotState`](/api/gantt/extensions/#projectsnapshotstate)

## `createJsonSnapshotRecipe`

<span class="api-kind">function</span>

```ts
export function createJsonSnapshotRecipe(options: ProjectSnapshotJsonRecipeOptions = {}): ProjectSnapshotJsonRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `ProjectSnapshotJsonRecipeOptions` | No | `{}` |  |

**Related types:** [`ProjectSnapshotJsonRecipe`](/api/gantt/extensions/#projectsnapshotjsonrecipe), [`ProjectSnapshotJsonRecipeOptions`](/api/gantt/extensions/#projectsnapshotjsonrecipeoptions)

## `createLockedPhaseValidator`

<span class="api-kind">function</span>

```ts
export function createLockedPhaseValidator<TContext>(options: LockedPhaseValidatorOptions<TContext>): GanttBeforeTaskChangeValidator<TContext>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `LockedPhaseValidatorOptions` | Yes | — |  |

**Related types:** [`GanttBeforeTaskChangeValidator`](/api/gantt/events/#ganttbeforetaskchangevalidator), [`LockedPhaseValidatorOptions`](/api/gantt/extensions/#lockedphasevalidatoroptions)

## `createPostgresSqlPersistenceRecipe`

<span class="api-kind">function</span>

```ts
export function createPostgresSqlPersistenceRecipe(executor: ProjectSnapshotSqlExecutor, state: ProjectSnapshotState, options: ProjectSnapshotPostgresOptions = {}): ProjectSnapshotPostgresRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `executor` | `ProjectSnapshotSqlExecutor` | Yes | — |  |
| `state` | `ProjectSnapshotState` | Yes | — |  |
| `options` | `ProjectSnapshotPostgresOptions` | No | `{}` |  |

**Related types:** [`ProjectSnapshotPostgresOptions`](/api/gantt/extensions/#projectsnapshotpostgresoptions), [`ProjectSnapshotPostgresRecipe`](/api/gantt/extensions/#projectsnapshotpostgresrecipe), [`ProjectSnapshotSqlExecutor`](/api/gantt/extensions/#projectsnapshotsqlexecutor), [`ProjectSnapshotState`](/api/gantt/extensions/#projectsnapshotstate)

## `createPrintableGanttMetadata`

<span class="api-kind">function</span>

```ts
export function createPrintableGanttMetadata(options: GanttPrintableMetadataOptions = {}): GanttPrintableMetadata;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttPrintableMetadataOptions` | No | `{}` |  |

**Related types:** [`GanttPrintableMetadata`](/api/gantt/extensions/#ganttprintablemetadata), [`GanttPrintableMetadataOptions`](/api/gantt/extensions/#ganttprintablemetadataoptions)

## `createPrintPdfExportRecipe`

<span class="api-kind">function</span>

```ts
export function createPrintPdfExportRecipe(options: GanttPrintPdfRecipeOptions): GanttPrintPdfRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttPrintPdfRecipeOptions` | Yes | — |  |

**Related types:** [`GanttPrintPdfRecipe`](/api/gantt/extensions/#ganttprintpdfrecipe), [`GanttPrintPdfRecipeOptions`](/api/gantt/extensions/#ganttprintpdfrecipeoptions)

## `createResourceLoadSummaryExample`

<span class="api-kind">function</span>

```ts
export function createResourceLoadSummaryExample(resourceId: string, resourceName: string, planning: ResourcePlanningRowData): ResourceOverallocationLoadSummary;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `resourceId` | `string` | Yes | — |  |
| `resourceName` | `string` | Yes | — |  |
| `planning` | `ResourcePlanningRowData` | Yes | — |  |

**Related types:** [`ResourcePlanningRowData`](/api/gantt/visuals/#resourceplanningrowdata)

## `createResourceOverallocationSummaryRecipe`

<span class="api-kind">function</span>

Recipe: feed either projected resource rows, raw load summaries, or scheduler
conflicts into a summary object that a resource dashboard can render.

```ts
export function createResourceOverallocationSummaryRecipe(input: ResourceOverallocationSummaryInput): ResourceOverallocationSummaryRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `input` | `ResourceOverallocationSummaryInput` | Yes | — |  |

**Related types:** [`ResourceOverallocationSummaryRecipe`](/api/gantt/extensions/#resourceoverallocationsummaryrecipe)

## `createRestProjectPersistenceRecipe`

<span class="api-kind">function</span>

```ts
export function createRestProjectPersistenceRecipe(options: ProjectSnapshotRestAdapterOptions, state: ProjectSnapshotState): ProjectSnapshotPersistenceRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `ProjectSnapshotRestAdapterOptions` | Yes | — |  |
| `state` | `ProjectSnapshotState` | Yes | — |  |

**Related types:** [`ProjectSnapshotPersistenceRecipe`](/api/gantt/extensions/#projectsnapshotpersistencerecipe), [`ProjectSnapshotRestAdapterOptions`](/api/gantt/extensions/#projectsnapshotrestadapteroptions), [`ProjectSnapshotState`](/api/gantt/extensions/#projectsnapshotstate)

## `createRoleBasedEditabilityRecipe`

<span class="api-kind">function</span>

Recipe: attach these handlers to the three cancelable Gantt before-change events.
The app owns role lookup; the helper only turns roles into deterministic decisions.

```ts
export function createRoleBasedEditabilityRecipe(options: GanttRoleBasedEditabilityRecipeOptions): GanttRoleBasedEditabilityRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `GanttRoleBasedEditabilityRecipeOptions` | Yes | — |  |

**Related types:** [`GanttRoleBasedEditabilityRecipe`](/api/gantt/extensions/#ganttrolebasededitabilityrecipe), [`GanttRoleBasedEditabilityRecipeOptions`](/api/gantt/extensions/#ganttrolebasededitabilityrecipeoptions)

## `createRoleGuardValidator`

<span class="api-kind">function</span>

```ts
export function createRoleGuardValidator<TContext extends GanttValidationContext>(options: RoleGuardValidatorOptions<TContext>): GanttBeforeTaskChangeValidator<TContext>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `RoleGuardValidatorOptions` | Yes | — |  |

**Related types:** [`GanttBeforeTaskChangeValidator`](/api/gantt/events/#ganttbeforetaskchangevalidator), [`GanttValidationContext`](/api/gantt/extensions/#ganttvalidationcontext), [`RoleGuardValidatorOptions`](/api/gantt/extensions/#roleguardvalidatoroptions)

## `createSchedulerDiagnosticsExample`

<span class="api-kind">function</span>

```ts
export function createSchedulerDiagnosticsExample(conflicts: readonly SchedulerConflict[] = [], issues: readonly SchedulerIssue[] = []): DependencyValidationSummaryInput;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `conflicts` | `readonly SchedulerConflict[]` | No | `[]` |  |
| `issues` | `readonly SchedulerIssue[]` | No | `[]` |  |

**Related types:** [`SchedulerConflict`](/api/gantt/scheduling/#schedulerconflict), [`SchedulerIssue`](/api/gantt/scheduling/#schedulerissue)

## `createSupabasePostgresPersistenceRecipe`

<span class="api-kind">function</span>

```ts
export function createSupabasePostgresPersistenceRecipe(client: SupabaseLikeClient<ProjectSnapshotPostgresRow>, state: ProjectSnapshotState, options: ProjectSnapshotPostgresOptions = {}): ProjectSnapshotStorageRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `client` | `SupabaseLikeClient` | Yes | — |  |
| `state` | `ProjectSnapshotState` | Yes | — |  |
| `options` | `ProjectSnapshotPostgresOptions` | No | `{}` |  |

**Related types:** [`ProjectSnapshotPostgresOptions`](/api/gantt/extensions/#projectsnapshotpostgresoptions), [`ProjectSnapshotPostgresRow`](/api/gantt/extensions/#projectsnapshotpostgresrow), [`ProjectSnapshotState`](/api/gantt/extensions/#projectsnapshotstate), [`ProjectSnapshotStorageRecipe`](/api/gantt/extensions/#projectsnapshotstoragerecipe), [`SupabaseLikeClient`](/api/gantt/extensions/#supabaselikeclient)

## `createTaskDetailPopoverRecipe`

<span class="api-kind">function</span>

Recipe: resolve the presentation-free popover model at hover/focus time and
let the framework render sections, fields, warnings, and resource assignments.

```ts
export function createTaskDetailPopoverRecipe(options: TaskDetailPopoverRecipeOptions): TaskDetailPopoverRecipe;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `TaskDetailPopoverRecipeOptions` | Yes | — |  |

**Related types:** [`TaskDetailPopoverRecipe`](/api/gantt/extensions/#taskdetailpopoverrecipe), [`TaskDetailPopoverRecipeOptions`](/api/gantt/extensions/#taskdetailpopoverrecipeoptions)

## `createTaskEditorDialogLocaleText`

<span class="api-kind">function</span>

```ts
export function createTaskEditorDialogLocaleText(localeText: GanttTaskEditorDialogLocaleTextOptions | undefined, inheritedLocaleText?: GanttTaskEditorDialogLocaleTextOptions): GanttTaskEditorDialogLocaleText;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `localeText` | `GanttTaskEditorDialogLocaleTextOptions \| undefined` | Yes | — |  |
| `inheritedLocaleText` | `GanttTaskEditorDialogLocaleTextOptions \| undefined` | No | — |  |

**Related types:** [`GanttTaskEditorDialogLocaleText`](/api/gantt/extensions/#gantttaskeditordialoglocaletext), [`GanttTaskEditorDialogLocaleTextOptions`](/api/gantt/extensions/#gantttaskeditordialoglocaletextoptions)

## `createTaskNameExcelExportMenuItem`

<span class="api-kind">function</span>

```ts
export function createTaskNameExcelExportMenuItem(workbookName: string): ContextMenuItem;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `workbookName` | `string` | Yes | — |  |

## `CustomTaskEditorRecipe`

<span class="api-kind">interface</span>

```ts
export interface CustomTaskEditorRecipe {
  readonly fields: readonly TaskEditorFieldSchema[];
  readonly initialValues: TaskEditorFormValues;
  readonly submit: (values: TaskEditorFormValues, options?: NormalizeTaskEditorSubmitOptions) => TaskEditorSubmitResult;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `fields` | `readonly TaskEditorFieldSchema[]` | Yes | — |  |
| `initialValues` | `Partial<Record<TaskEditorFieldId, unknown>>` | Yes | — |  |
| `submit` | `(values: TaskEditorFormValues, options?: NormalizeTaskEditorSubmitOptions) => TaskEditorSubmitResult` | Yes | — |  |

## `CustomTaskEditorRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface CustomTaskEditorRecipeOptions {
  readonly task: TaskEntity;
  readonly resources?: readonly ResourceEntity[];
  readonly assignments?: readonly AssignmentEntity[];
  readonly fieldIds?: readonly TaskEditorFieldId[];
  readonly includeUnchanged?: boolean;
  readonly onSubmitPatch?: (patch: TaskUpdate) => void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `task` | `TaskEntity` | Yes | — |  |
| `resources` | `readonly ResourceEntity[] \| undefined` | No | — |  |
| `assignments` | `readonly AssignmentEntity[] \| undefined` | No | — |  |
| `fieldIds` | `readonly TaskEditorFieldId[] \| undefined` | No | — |  |
| `includeUnchanged` | `boolean \| undefined` | No | — |  |
| `onSubmitPatch` | `((patch: TaskUpdate) => void) \| undefined` | No | — |  |

**Related types:** [`AssignmentEntity`](/api/gantt/data-model/#assignmententity), [`ResourceEntity`](/api/gantt/data-model/#resourceentity), [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskUpdate`](/api/gantt/data-model/#taskupdate)

## `CustomValidationRecipe`

<span class="api-kind">interface</span>

```ts
export interface CustomValidationRecipe {
  readonly validators: readonly GanttBeforeTaskChangeValidator<GanttValidationContext>[];
  readonly handler: (event: GanttExampleCancelableEvent<GanttBeforeTaskChangeDetail>) => void;
  readonly validate: (detail: GanttBeforeTaskChangeDetail) => GanttValidationDecision;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `validators` | `readonly GanttBeforeTaskChangeValidator[]` | Yes | — |  |
| `handler` | `(event: GanttExampleCancelableEvent) => void` | Yes | — |  |
| `validate` | `(detail: GanttBeforeTaskChangeDetail) => GanttValidationDecision` | Yes | — |  |

**Related types:** [`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail), [`GanttBeforeTaskChangeValidator`](/api/gantt/events/#ganttbeforetaskchangevalidator), [`GanttExampleCancelableEvent`](/api/gantt/events/#ganttexamplecancelableevent), [`GanttValidationContext`](/api/gantt/extensions/#ganttvalidationcontext), [`GanttValidationDecision`](/api/gantt/extensions/#ganttvalidationdecision)

## `CustomValidationRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface CustomValidationRecipeOptions {
  readonly context: GanttValidationContext | (() => GanttValidationContext);
  readonly rolePolicy?: GanttRoleEditabilityPolicy;
  readonly freezeWindows?: readonly GanttDateRange[];
  readonly lockedPhaseIds?: readonly string[];
  readonly phaseByTaskId?: Readonly<Record<TaskId, string>>;
  readonly validators?: readonly GanttBeforeTaskChangeValidator<GanttValidationContext>[];
  readonly onReject?: (rejection: GanttValidationReject) => void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `context` | `GanttValidationContext \| (() => GanttValidationContext)` | Yes | — |  |
| `rolePolicy` | `GanttRoleEditabilityPolicy \| undefined` | No | — |  |
| `freezeWindows` | `readonly GanttDateRange[] \| undefined` | No | — |  |
| `lockedPhaseIds` | `readonly string[] \| undefined` | No | — |  |
| `phaseByTaskId` | `Readonly<Record<string, string>> \| undefined` | No | — |  |
| `validators` | `readonly GanttBeforeTaskChangeValidator[] \| undefined` | No | — |  |
| `onReject` | `((rejection: GanttValidationReject) => void) \| undefined` | No | — |  |

**Related types:** [`GanttBeforeTaskChangeValidator`](/api/gantt/events/#ganttbeforetaskchangevalidator), [`GanttDateRange`](/api/gantt/extensions/#ganttdaterange), [`GanttValidationContext`](/api/gantt/extensions/#ganttvalidationcontext), [`GanttValidationReject`](/api/gantt/extensions/#ganttvalidationreject), [`TaskId`](/api/gantt/data-model/#taskid)

## `DEFAULT_GANTT_DEPENDENCY_TYPES`

<span class="api-kind">constant</span>

```ts
export const DEFAULT_GANTT_DEPENDENCY_TYPES: readonly ["finish-to-start", "start-to-start", "finish-to-finish", "start-to-finish"];
```

## `DEFAULT_TASK_EDITOR_DIALOG_LOCALE_TEXT`

<span class="api-kind">constant</span>

```ts
export const DEFAULT_TASK_EDITOR_DIALOG_LOCALE_TEXT: GanttTaskEditorDialogLocaleText;
```

**Related types:** [`GanttTaskEditorDialogLocaleText`](/api/gantt/extensions/#gantttaskeditordialoglocaletext)

## `defineGanttToolbar`

<span class="api-kind">constant</span>

Mounts the Gantt editing toolbar into `el` and wires it to the given
`revo-grid` element.  Call this once after the grid's `gantt` property
has been set so the toolbar can read the initial visual config.

`controls` hides built-in controls. Omitted flags are visible by default,
except `baseline`, which is opt-in.

### Example
```ts
import { defineGanttToolbar } from '@revolist/gantt';

const toolbarEl = document.querySelector('#gantt-toolbar');
const grid      = document.querySelector('revo-grid');

defineGanttToolbar(toolbarEl, {
  grid,
  columns: [
    { prop: 'wbs',       label: 'WBS',       visible: true  },
    { prop: 'name',      label: 'Name',       visible: true  },
    { prop: 'startDate', label: 'Start Date', visible: true  },
    { prop: 'duration',  label: 'Duration',   visible: true  },
    { prop: 'status',    label: 'Status',     visible: true  },
    { prop: 'endDate',   label: 'End Date',   visible: false },
  ],
  visuals: {
    showDependencies:            true,
    showBaseline:                true,
    showCriticalPath:            true,
  },
  controls: {
    search: true,
    history: true,
    undo: true,
    redo: true,
    tree: true,
    expandAll: true,
    collapseAll: true,
    zoom: true,
    zoomIn: true,
    zoomOut: true,
    tasks: true,
    addTask: true,
    indent: true,
    outdent: true,
    export: true,
    exportExcel: true,
    columns: true,
    dependencies: true,
    baseline: true,
    criticalPath: true,
  },
});
```

```ts
export const defineGanttToolbar: (el: HTMLElement, options: GanttToolbarOptions) => void;
```

**Related types:** [`GanttToolbarOptions`](/api/gantt/extensions/#gantttoolbaroptions)

## `DeleteTaskMenuItemOptions`

<span class="api-kind">interface</span>

```ts
export interface DeleteTaskMenuItemOptions extends GanttContextMenuBaseItemOptions {
  readonly onDeleteTask: (context: GanttContextMenuExtensionContext) => void;
  readonly confirm?: (context: GanttContextMenuExtensionContext) => boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `onDeleteTask` | `(context: GanttContextMenuExtensionContext) => void` | Yes | — |  |
| `confirm` | `((context: GanttContextMenuExtensionContext) => boolean) \| undefined` | No | — |  |

**Related types:** [`GanttContextMenuBaseItemOptions`](/api/gantt/extensions/#ganttcontextmenubaseitemoptions), [`GanttContextMenuExtensionContext`](/api/gantt/extensions/#ganttcontextmenuextensioncontext)

## `DependencyEndpointPair`

<span class="api-kind">interface</span>

```ts
export interface DependencyEndpointPair {
  readonly predecessor: GanttDependencyEndpoint;
  readonly successor: GanttDependencyEndpoint;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `predecessor` | `GanttDependencyEndpoint` | Yes | — |  |
| `successor` | `GanttDependencyEndpoint` | Yes | — |  |

**Related types:** [`GanttDependencyEndpoint`](/api/gantt/extensions/#ganttdependencyendpoint)

## `dependencyEndpointsToType`

<span class="api-kind">function</span>

```ts
export function dependencyEndpointsToType(predecessor: GanttDependencyEndpoint, successor: GanttDependencyEndpoint): DependencyType;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `predecessor` | `GanttDependencyEndpoint` | Yes | — |  |
| `successor` | `GanttDependencyEndpoint` | Yes | — |  |

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype), [`GanttDependencyEndpoint`](/api/gantt/extensions/#ganttdependencyendpoint)

## `dependencyTypeToEndpoints`

<span class="api-kind">function</span>

```ts
export function dependencyTypeToEndpoints(type: DependencyType): DependencyEndpointPair;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `type` | `DependencyType` | Yes | — |  |

**Related types:** [`DependencyEndpointPair`](/api/gantt/extensions/#dependencyendpointpair), [`DependencyType`](/api/gantt/data-model/#dependencytype)

## `DependencyValidationSummaryRecipe`

<span class="api-kind">interface</span>

```ts
export interface DependencyValidationSummaryRecipe {
  readonly summary: DependencyValidationSummary;
  readonly hasBlockingConflicts: boolean;
  readonly badgeLabel: string;
  readonly focusTaskIds: readonly TaskId[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `summary` | `DependencyValidationSummary` | Yes | — |  |
| `hasBlockingConflicts` | `boolean` | Yes | — |  |
| `badgeLabel` | `string` | Yes | — |  |
| `focusTaskIds` | `readonly string[]` | Yes | — |  |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `DuplicateTaskMenuItemOptions`

<span class="api-kind">interface</span>

```ts
export interface DuplicateTaskMenuItemOptions extends GanttContextMenuBaseItemOptions {
  readonly copyName?: (task: Partial<TaskEntity>, context: GanttContextMenuExtensionContext) => string;
  readonly createTaskOptions?: (
    context: GanttContextMenuExtensionContext,
  ) => GanttCreateTaskOptions | null | undefined;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `copyName` | `((task: Partial, context: GanttContextMenuExtensionContext) => string) \| undefined` | No | — |  |
| `createTaskOptions` | `((context: GanttContextMenuExtensionContext) => GanttCreateTaskOptions \| null \| undefined) \| undefined` | No | — |  |

**Related types:** [`GanttContextMenuBaseItemOptions`](/api/gantt/extensions/#ganttcontextmenubaseitemoptions), [`GanttContextMenuExtensionContext`](/api/gantt/extensions/#ganttcontextmenuextensioncontext), [`GanttCreateTaskOptions`](/api/gantt/plugin/#ganttcreatetaskoptions), [`TaskEntity`](/api/gantt/data-model/#taskentity)

## `exportGanttCsv`

<span class="api-kind">function</span>

```ts
export function exportGanttCsv(grid: HTMLRevoGridElement, options: GanttCsvExportOptions = {}): Promise<boolean>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |
| `options` | `GanttCsvExportOptions` | No | `{}` |  |

**Related types:** [`GanttCsvExportOptions`](/api/gantt/extensions/#ganttcsvexportoptions)

## `exportGanttExcel`

<span class="api-kind">function</span>

```ts
export function exportGanttExcel(grid: HTMLRevoGridElement, options: GanttExcelExportOptions = {}): CustomEvent<GanttExcelExportOptions>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |
| `options` | `ExportExcelEvent` | No | `{}` |  |

**Related types:** [`GanttExcelExportOptions`](/api/gantt/extensions/#ganttexcelexportoptions)

## `ExportMenuItemOptions`

<span class="api-kind">interface</span>

```ts
export interface ExportMenuItemOptions extends GanttContextMenuBaseItemOptions {
  readonly exportOptions?: ExportExcelEvent | ((context: GanttContextMenuExtensionContext) => ExportExcelEvent | undefined);
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `exportOptions` | `ExportExcelEvent \| ((context: GanttContextMenuExtensionContext) => ExportExcelEvent \| undefined) \| undefined` | No | — |  |

**Related types:** [`GanttContextMenuBaseItemOptions`](/api/gantt/extensions/#ganttcontextmenubaseitemoptions), [`GanttContextMenuExtensionContext`](/api/gantt/extensions/#ganttcontextmenuextensioncontext)

## `fitGanttToProject`

<span class="api-kind">function</span>

```ts
export function fitGanttToProject(grid: HTMLRevoGridElement, options: GanttProjectFitOptions = {}): Promise<boolean>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |
| `options` | `GanttProjectFitOptions` | No | `{}` |  |

**Related types:** [`GanttProjectFitOptions`](/api/gantt/extensions/#ganttprojectfitoptions)

## `ForbiddenDateRangeValidatorOptions`

<span class="api-kind">interface</span>

```ts
export interface ForbiddenDateRangeValidatorOptions {
  readonly ranges: readonly GanttDateRange[];
  readonly actions?: readonly GanttBeforeTaskChangeAction[];
  readonly message?: (range: GanttDateRange) => string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `ranges` | `readonly GanttDateRange[]` | Yes | — |  |
| `actions` | `readonly GanttBeforeTaskChangeAction[] \| undefined` | No | — |  |
| `message` | `((range: GanttDateRange) => string) \| undefined` | No | — |  |

**Related types:** [`GanttBeforeTaskChangeAction`](/api/gantt/events/#ganttbeforetaskchangeaction), [`GanttDateRange`](/api/gantt/extensions/#ganttdaterange)

## `formatGanttPrintRange`

<span class="api-kind">function</span>

```ts
export function formatGanttPrintRange(range: GanttPrintDateRange | undefined): string | undefined;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `range` | `GanttPrintDateRange \| undefined` | Yes | — |  |

**Related types:** [`GanttPrintDateRange`](/api/gantt/extensions/#ganttprintdaterange)

## `GANTT_PERSISTENCE_QUICK_WIN_EXAMPLES`

<span class="api-kind">constant</span>

```ts
export const GANTT_PERSISTENCE_QUICK_WIN_EXAMPLES: readonly GanttPersistenceRecipeMetadata[];
```

**Related types:** [`GanttPersistenceRecipeMetadata`](/api/gantt/extensions/#ganttpersistencerecipemetadata)

## `GANTT_TOOLBAR_SELECT_ALL_COLUMNS`

<span class="api-kind">constant</span>

```ts
export const GANTT_TOOLBAR_SELECT_ALL_COLUMNS: "__select_all__";
```

## `GanttApprovalRegistry`

<span class="api-kind">type</span>

```ts
export type GanttApprovalRegistry =
  | Readonly<Record<TaskId, ApprovalRecord | undefined>>
  | ((detail: GanttBeforeTaskChangeDetail) => ApprovalRecord | null | undefined);
```

**Related types:** [`ApprovalRecord`](/api/gantt/extensions/#approvalrecord), [`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttBaselineCaptureRuntime`

<span class="api-kind">interface</span>

```ts
export interface GanttBaselineCaptureRuntime {
  captureBaseline(options?: CaptureBaselineOptions): BaselineSnapshot | null;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `captureBaseline(options?: CaptureBaselineOptions)` | `BaselineSnapshot \| null` | Yes | — |  |

**Related types:** [`BaselineSnapshot`](/api/gantt/data-model/#baselinesnapshot)

## `GanttColumnPresetRecipe`

<span class="api-kind">interface</span>

```ts
export interface GanttColumnPresetRecipe {
  readonly preset: GanttColumnPresetName;
  readonly presetProps: readonly GanttColumnPresetProp[];
  readonly columns: readonly ColumnRegular[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `preset` | `GanttColumnPresetName` | Yes | — |  |
| `presetProps` | `readonly GanttColumnPresetProp[]` | Yes | — |  |
| `columns` | `readonly ColumnRegular<ColumnProp, DataType<any, ColumnProp>>[]` | Yes | — |  |

**Related types:** [`GanttColumnPresetName`](/api/gantt/columns/#ganttcolumnpresetname), [`GanttColumnPresetProp`](/api/gantt/columns/#ganttcolumnpresetprop)

## `GanttColumnPresetRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttColumnPresetRecipeOptions {
  readonly preset: GanttColumnPresetName;
  readonly extraColumns?: readonly ColumnRegular[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `preset` | `GanttColumnPresetName` | Yes | — |  |
| `extraColumns` | `readonly ColumnRegular<ColumnProp, DataType<any, ColumnProp>>[] \| undefined` | No | — |  |

**Related types:** [`GanttColumnPresetName`](/api/gantt/columns/#ganttcolumnpresetname)

## `GanttContextMenuBaseItemOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttContextMenuBaseItemOptions {
  readonly name?: ContextMenuItem['name'];
  readonly class?: string;
  readonly rowClass?: ContextMenuItem['rowClass'];
  readonly icon?: string;
  readonly hidden?: ContextMenuItem['hidden'];
  readonly keepOpen?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `name` | `string \| ((focused?: Cell \| null, range?: RangeArea \| null) => string) \| undefined` | No | — |  |
| `class` | `string \| undefined` | No | — |  |
| `rowClass` | `string \| ((item: ContextMenuItem, focused?: Cell \| null, range?: RangeArea \| null) => string) \| undefined` | No | — |  |
| `icon` | `string \| undefined` | No | — |  |
| `hidden` | `boolean \| ContextMenuItemStateResolver \| undefined` | No | — |  |
| `keepOpen` | `boolean \| undefined` | No | — |  |

## `GanttContextMenuExtensionContext`

<span class="api-kind">interface</span>

```ts
export interface GanttContextMenuExtensionContext {
  readonly event: MouseEvent;
  readonly focused?: Cell | null;
  readonly range?: RangeArea | null;
  readonly close?: () => void;
  readonly revogrid: HTMLRevoGridElement;
  readonly providers: PluginProviders;
  readonly taskId: TaskId | null;
  readonly task: Partial<TaskEntity> | null;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `event` | `MouseEvent` | Yes | — |  |
| `focused` | `Cell \| null \| undefined` | No | — |  |
| `range` | `RangeArea \| null \| undefined` | No | — |  |
| `close` | `(() => void) \| undefined` | No | — |  |
| `revogrid` | `HTMLRevoGridElement` | Yes | — |  |
| `providers` | `PluginProviders` | Yes | — |  |
| `taskId` | `string \| null` | Yes | — |  |
| `task` | `Partial \| null` | Yes | — |  |

**Related types:** [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttContextMenuQuickWinRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttContextMenuQuickWinRecipeOptions {
  readonly duplicate?: DuplicateTaskMenuItemOptions | false;
  readonly delete?: DeleteTaskMenuItemOptions | false;
  readonly assignResource?: AssignResourceMenuItemOptions | false;
  readonly export?: ExportMenuItemOptions | false;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `duplicate` | `false \| DuplicateTaskMenuItemOptions \| undefined` | No | — |  |
| `delete` | `false \| DeleteTaskMenuItemOptions \| undefined` | No | — |  |
| `assignResource` | `false \| AssignResourceMenuItemOptions \| undefined` | No | — |  |
| `export` | `false \| ExportMenuItemOptions \| undefined` | No | — |  |

**Related types:** [`AssignResourceMenuItemOptions`](/api/gantt/extensions/#assignresourcemenuitemoptions), [`DeleteTaskMenuItemOptions`](/api/gantt/extensions/#deletetaskmenuitemoptions), [`DuplicateTaskMenuItemOptions`](/api/gantt/extensions/#duplicatetaskmenuitemoptions), [`ExportMenuItemOptions`](/api/gantt/extensions/#exportmenuitemoptions)

## `GanttCsvExportOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttCsvExportOptions {
  filename?: string;
  bom?: boolean;
  columnDelimiter?: string;
  rowDelimiter?: string;
  mime?: string;
  encoding?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `filename` | `string \| undefined` | No | — |  |
| `bom` | `boolean \| undefined` | No | — |  |
| `columnDelimiter` | `string \| undefined` | No | — |  |
| `rowDelimiter` | `string \| undefined` | No | — |  |
| `mime` | `string \| undefined` | No | — |  |
| `encoding` | `string \| undefined` | No | — |  |

## `GanttDateRange`

<span class="api-kind">interface</span>

```ts
export interface GanttDateRange {
  readonly startDate: ISODateString;
  readonly endDate: ISODateString;
  readonly label?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `startDate` | `ISODateString` | Yes | — |  |
| `endDate` | `ISODateString` | Yes | — |  |
| `label` | `string \| undefined` | No | — |  |

## `GanttDependencyDropdownConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttDependencyDropdownConfig {
  readonly tasks: readonly GanttDependencyDropdownTaskOption[];
  readonly getTasks?: () => readonly GanttDependencyDropdownTaskOption[];
  readonly allowedTypes?: readonly DependencyType[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `tasks` | `readonly GanttDependencyDropdownTaskOption[]` | Yes | — |  |
| `getTasks` | `(() => readonly GanttDependencyDropdownTaskOption[]) \| undefined` | No | — |  |
| `allowedTypes` | `readonly DependencyType[] \| undefined` | No | — |  |

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype), [`GanttDependencyDropdownTaskOption`](/api/gantt/extensions/#ganttdependencydropdowntaskoption)

## `GanttDependencyDropdownControl`

<span class="api-kind">function</span>

```ts
export function GanttDependencyDropdownControl({
  getOptions,
  currentTaskId,
  value,
  rawValue,
  allowedTypes,
  displayValue,
  autoOpen = false,
  theme,
  onChange,
  onClose,
}: GanttDependencyDropdownControlProps): h.JSX.Element;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `{   getOptions,   currentTaskId,   value,   rawValue,   allowedTypes,   displayValue,   autoOpen = false,   theme,   onChange,   onClose, }` | `GanttDependencyDropdownControlProps` | Yes | — |  |

**Related types:** [`GanttDependencyDropdownControlProps`](/api/gantt/extensions/#ganttdependencydropdowncontrolprops)

## `GanttDependencyDropdownControlProps`

<span class="api-kind">interface</span>

```ts
export interface GanttDependencyDropdownControlProps {
  readonly getOptions: () => readonly GanttDependencyDropdownTaskOption[];
  readonly currentTaskId: TaskId;
  readonly value: readonly GanttDependencyDropdownValue[];
  readonly rawValue?: unknown;
  readonly allowedTypes: readonly DependencyType[];
  readonly displayValue: string;
  readonly autoOpen?: boolean;
  readonly theme?: string;
  readonly onChange: (value: readonly GanttDependencyDropdownValue[]) => void;
  readonly onClose?: (focusNext?: boolean) => void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `getOptions` | `() => readonly GanttDependencyDropdownTaskOption[]` | Yes | — |  |
| `currentTaskId` | `string` | Yes | — |  |
| `value` | `readonly GanttDependencyDropdownValue[]` | Yes | — |  |
| `rawValue` | `unknown` | No | — |  |
| `allowedTypes` | `readonly DependencyType[]` | Yes | — |  |
| `displayValue` | `string` | Yes | — |  |
| `autoOpen` | `boolean \| undefined` | No | — |  |
| `theme` | `string \| undefined` | No | — |  |
| `onChange` | `(value: readonly GanttDependencyDropdownValue[]) => void` | Yes | — |  |
| `onClose` | `((focusNext?: boolean) => void) \| undefined` | No | — |  |

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype), [`GanttDependencyDropdownTaskOption`](/api/gantt/extensions/#ganttdependencydropdowntaskoption), [`GanttDependencyDropdownValue`](/api/gantt/extensions/#ganttdependencydropdownvalue), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttDependencyDropdownTaskOption`

<span class="api-kind">interface</span>

```ts
export interface GanttDependencyDropdownTaskOption {
  readonly taskId: TaskId;
  readonly wbs: string;
  readonly name: string;
  readonly label: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskId` | `string` | Yes | — |  |
| `wbs` | `string` | Yes | — |  |
| `name` | `string` | Yes | — |  |
| `label` | `string` | Yes | — |  |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttDependencyDropdownValue`

<span class="api-kind">interface</span>

```ts
export interface GanttDependencyDropdownValue {
  readonly taskId: TaskId;
  readonly type: DependencyType;
  readonly lagDays?: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskId` | `string` | Yes | — |  |
| `type` | `DependencyType` | Yes | — |  |
| `lagDays` | `number \| undefined` | No | — |  |

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttDependencyEndpoint`

<span class="api-kind">type</span>

```ts
export type GanttDependencyEndpoint = 'start' | 'finish';
```

## `GanttExcelExportOptions`

<span class="api-kind">type</span>

```ts
export type GanttExcelExportOptions = ExportExcelEvent;
```

## `GanttExcelExportRecipe`

<span class="api-kind">interface</span>

```ts
export interface GanttExcelExportRecipe {
  readonly rows: readonly GanttExcelExportRow[];
  readonly fieldNames: readonly (keyof GanttExcelExportRow)[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `rows` | `readonly GanttExcelExportRow[]` | Yes | — |  |
| `fieldNames` | `readonly (keyof GanttExcelExportRow)[]` | Yes | — |  |

## `GanttExcelExportRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttExcelExportRecipeOptions extends GanttExcelMappingOptions {
  readonly rows: readonly GanttGridRow[];
  readonly project: ProjectSnapshot;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `rows` | `readonly GanttGridRow[]` | Yes | — |  |
| `project` | `ProjectSnapshot` | Yes | — |  |

**Related types:** [`GanttGridRow`](/api/gantt/columns/#ganttgridrow), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)

## `GanttPanelResizeDetail`

<span class="api-kind">interface</span>

Payload emitted with each `gantt-panel-resize` event.

```ts
export interface GanttPanelResizeDetail {
  /** The current width of the gantt panel in pixels. */
  readonly width: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `width` | `number` | Yes | — | The current width of the gantt panel in pixels. |

## `GanttPanelResizePlugin`

<span class="api-kind">class</span>

GanttPanelResizePlugin adds a drag handle on the left edge of the
pinned-end (gantt chart) viewport, allowing the user to resize the split
between the task-list columns (rgCol) and the gantt chart (colPinEnd).

Dragging the handle left expands the gantt panel; dragging right shrinks it.
An `gantt-panel-resize` event is emitted on the revogrid element during and
after each drag with `{ width: number }` in its detail.

```ts
export class GanttPanelResizePlugin extends CorePlugin {
  constructor(revogrid: HTMLRevoGridElement, providers: PluginProviders, config?: GanttPanelResizePluginConfig);
  setPanelWidth(width: number): void;
  getPanelWidth(): number | null;
  syncTimelineScrollPosition(coordinate: number): void;
  destroy(): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `handle` | `HTMLDivElement` | Yes | — |  |
| `ghost` | `HTMLDivElement` | Yes | — |  |
| `taskListScroll` | `PanelScrollElement` | Yes | — |  |
| `timelineScroll` | `PanelScrollElement` | Yes | — |  |
| `rAFId` | `number \| null` | Yes | `null` |  |
| `dragRafId` | `number \| null` | Yes | `null` |  |
| `dragWidth` | `number \| null` | Yes | `null` |  |
| `dragColPinEnd` | `HTMLElement \| null` | Yes | `null` |  |
| `isDragging` | `boolean` | Yes | `false` |  |
| `isDestroyed` | `boolean` | Yes | `false` |  |
| `pendingInitialWidth` | `string \| number \| null` | Yes | `null` |  |
| `fullWidthBecauseNoTaskColumns` | `boolean` | Yes | `false` |  |
| `desiredPanelWidth` | `number \| null` | Yes | `null` |  |
| `lastTaskListPanelWidth` | `number \| null` | Yes | `null` |  |
| `lastTaskListViewportWidth` | `number \| null` | Yes | `null` |  |
| `lastAppliedTaskListViewportWidth` | `number \| null` | Yes | `null` |  |
| `pendingPanelForward` | `{ side: PanelScrollSide; coordinate: number; } \| null` | Yes | `null` |  |
| `leftEdgeSyncGeneration` | `Record<PanelScrollSide, number>` | Yes | `{     'task-list': 0,     timeline: 0,   }` |  |
| `setPanelWidth(width: number)` | `void` | Yes | — | Programmatically set the gantt panel width. |
| `getPanelWidth()` | `number \| null` | Yes | — | Returns the current gantt panel (colPinEnd) width in pixels, or null if the viewport is not yet rendered. |
| `syncTimelineScrollPosition(coordinate: number)` | `void` | Yes | — | Mirror a programmatic timeline viewport scroll into the visible panel scrollbar without forwarding the change back through the viewport. |
| `destroy()` | `void` | Yes | — |  |
| `createPanelScroll(side: PanelScrollSide)` | `PanelScrollElement` | Yes | — |  |
| `applyInitialWidth(initialWidth: number \| string)` | `boolean` | Yes | — |  |
| `getColPinEnd()` | `HTMLElement \| null` | Yes | — |  |
| `getRgCol()` | `HTMLElement \| null` | Yes | — |  |
| `schedulePositionUpdate()` | `void` | Yes | — |  |
| `updateHandlePosition()` | `void` | Yes | — |  |
| `onPointerDown` | `(e: PointerEvent) => void` | Yes | `(e: PointerEvent): void => {     const colPinEnd = this.getColPinEnd();     if (!colPinEnd \|\| !this.hasVisibleTaskListColumns()) return;      e.preventDefault();     this.isDragging = true;     this.dragColPinEnd = colPinEnd;     this.handle.classList.add('is-dragging');      const startX = e.clientX;     const startWidth = colPinEnd.getBoundingClientRect().width;     this.dragWidth = startWidth;     this.updateGhostPosition(startWidth, colPinEnd);      this.handle.setPointerCapture(e.pointerId);      const onPointerMove = (moveEvent: PointerEvent): void => {       // Dragging left = positive delta = wider gantt pane       const delta = startX - moveEvent.clientX;       const nextWidth = this.clampWidth(startWidth + delta, colPinEnd);       this.dragWidth = nextWidth;       this.scheduleDragUpdate();     };      const onPointerUp = (): void => {       this.applyPendingDragWidth();       this.isDragging = false;       this.dragColPinEnd = null;       this.dragWidth = null;       this.ghost.style.display = 'none';       this.handle.classList.remove('is-dragging');       if (this.handle.hasPointerCapture(e.pointerId)) {         this.handle.releasePointerCapture(e.pointerId);       }       this.handle.removeEventListener('pointermove', onPointerMove);       this.handle.removeEventListener('pointerup', onPointerUp);       this.handle.removeEventListener('pointercancel', onPointerUp);       this.schedulePositionUpdate();     };      this.handle.addEventListener('pointermove', onPointerMove);     this.handle.addEventListener('pointerup', onPointerUp);     this.handle.addEventListener('pointercancel', onPointerUp);   }` |  |
| `clampWidth(desiredWidth: number, _colPinEnd: HTMLElement)` | `number` | Yes | — |  |
| `scheduleDragUpdate()` | `void` | Yes | — |  |
| `flushDragPreview()` | `void` | Yes | — |  |
| `applyPendingDragWidth()` | `void` | Yes | — |  |
| `applyPanelWidth(colPinEnd: HTMLElement, width: number, emitEvent = true, rememberWidth = true)` | `void` | Yes | — |  |
| `updateGhostPosition(width: number, colPinEnd: HTMLElement)` | `void` | Yes | — |  |
| `syncGridStoresWithPanelWidth(width: number)` | `boolean` | Yes | — |  |
| `syncPanelScrollbars()` | `void` | Yes | — |  |
| `syncPanelScrollbar(side: PanelScrollSide)` | `void` | Yes | — |  |
| `getViewportBounds(viewport: HTMLElement)` | `{ left: number; bottom: number; width: number }` | Yes | — |  |
| `getHorizontalRealSize(side: PanelScrollSide)` | `number` | Yes | — |  |
| `onTaskListPanelScroll` | `(event: Event) => void` | Yes | `(event: Event): void => {     this.forwardPanelScroll('task-list', event as CustomEvent<{ dimension?: unknown; coordinate?: unknown }>);   }` |  |
| `onTimelinePanelScroll` | `(event: Event) => void` | Yes | `(event: Event): void => {     this.forwardPanelScroll('timeline', event as CustomEvent<{ dimension?: unknown; coordinate?: unknown }>);   }` |  |
| `onTaskListPanelNativeScroll` | `() => void` | Yes | `(): void => {     const generation = this.invalidateLeftEdgeSync('task-list');     this.syncViewportLeftEdgeFromPanel('task-list');     this.scheduleViewportLeftEdgeSyncFromPanel('task-list', generation);   }` |  |
| `onTimelinePanelNativeScroll` | `() => void` | Yes | `(): void => {     const generation = this.invalidateLeftEdgeSync('timeline');     this.syncViewportLeftEdgeFromPanel('timeline');     this.scheduleViewportLeftEdgeSyncFromPanel('timeline', generation);   }` |  |
| `syncViewportLeftEdgeFromPanel(side: PanelScrollSide)` | `void` | Yes | — |  |
| `invalidateLeftEdgeSync(side: PanelScrollSide)` | `number` | Yes | — |  |
| `scheduleViewportLeftEdgeSyncFromPanel(side: PanelScrollSide, generation: number)` | `void` | Yes | — |  |
| `forwardPanelScroll(side: PanelScrollSide, event: CustomEvent<{ dimension?: unknown; coordinate?: unknown }>)` | `void` | Yes | — |  |
| `syncPanelScrollFromViewport(event: CustomEvent<{ dimension?: unknown; coordinate?: unknown }>)` | `void` | Yes | — |  |
| `syncTimelineWidthWithTaskColumns()` | `void` | Yes | — |  |
| `getPanelWidthForTaskListAnchor(gridWidth: number)` | `number \| null` | Yes | — |  |
| `getCurrentPanelWidth(colPinEnd: HTMLElement)` | `number` | Yes | — |  |
| `getMinimumTaskListWidth()` | `number` | Yes | — |  |
| `hasVisibleTaskListColumns()` | `boolean` | Yes | — |  |
| `hasVisibleColumnsInDimension(type: TaskListColumnType)` | `boolean \| null` | Yes | — |  |
| `emitResizeEvent(width: number)` | `void` | Yes | — |  |

**Related types:** [`GanttPanelResizePluginConfig`](/api/gantt/extensions/#ganttpanelresizepluginconfig)

## `GanttPanelResizePluginConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttPanelResizePluginConfig {
  /**
   * Initial width of the gantt (colPinEnd) panel in pixels or as a percentage
   * of the grid width (e.g. `"40%"`).
   * Defaults to the current rendered width of the panel.
   */
  initialWidth?: number | string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `initialWidth` | `string \| number \| undefined` | No | — | Initial width of the gantt (colPinEnd) panel in pixels or as a percentage of the grid width (e.g. `"40%"`). Defaults to the current rendered width of the panel. |

## `GanttPdfExcelReportingExportOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttPdfExcelReportingExportOptions {
  readonly range?: GanttPrintDateRange;
  readonly excel?: GanttExcelExportOptions;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `range` | `GanttPrintDateRange \| undefined` | No | — |  |
| `excel` | `ExportExcelEvent \| undefined` | No | — |  |

**Related types:** [`GanttExcelExportOptions`](/api/gantt/extensions/#ganttexcelexportoptions), [`GanttPrintDateRange`](/api/gantt/extensions/#ganttprintdaterange)

## `GanttPdfExcelReportingRecipe`

<span class="api-kind">interface</span>

```ts
export interface GanttPdfExcelReportingRecipe {
  exportPdf(project: ProjectSnapshot, range?: GanttPrintDateRange): GanttPrintResult;
  exportExcel(options?: GanttExcelExportOptions): CustomEvent<GanttExcelExportOptions>;
  exportReport(project: ProjectSnapshot, options?: GanttPdfExcelReportingExportOptions): {
    readonly pdf: GanttPrintResult;
    readonly excel: CustomEvent<GanttExcelExportOptions>;
  };
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `exportPdf(project: ProjectSnapshot, range?: GanttPrintDateRange)` | `GanttPrintResult` | Yes | — |  |
| `exportExcel(options?: GanttExcelExportOptions)` | `CustomEvent` | Yes | — |  |
| `exportReport(project: ProjectSnapshot, options?: GanttPdfExcelReportingExportOptions)` | `{ readonly pdf: GanttPrintResult; readonly excel: CustomEvent; }` | Yes | — |  |

**Related types:** [`GanttExcelExportOptions`](/api/gantt/extensions/#ganttexcelexportoptions), [`GanttPdfExcelReportingExportOptions`](/api/gantt/extensions/#ganttpdfexcelreportingexportoptions), [`GanttPrintDateRange`](/api/gantt/extensions/#ganttprintdaterange), [`GanttPrintResult`](/api/gantt/extensions/#ganttprintresult), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)

## `GanttPdfExcelReportingRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttPdfExcelReportingRecipeOptions {
  readonly grid: HTMLRevoGridElement;
  readonly target: Element | null | undefined;
  readonly document?: Document;
  readonly window?: GanttPrintOptions['window'];
  readonly now?: () => Date | string;
  readonly pdf?: Omit<GanttPrintOptions, 'document' | 'window' | 'metadata'>;
  readonly excel?: GanttExcelExportOptions;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |
| `target` | `Element \| null \| undefined` | Yes | — |  |
| `document` | `Document \| undefined` | No | — |  |
| `window` | `GanttPrintWindow \| undefined` | No | — |  |
| `now` | `(() => Date \| string) \| undefined` | No | — |  |
| `pdf` | `Omit<GanttPrintOptions, "window" \| "document" \| "metadata"> \| undefined` | No | — |  |
| `excel` | `ExportExcelEvent \| undefined` | No | — |  |

**Related types:** [`GanttExcelExportOptions`](/api/gantt/extensions/#ganttexcelexportoptions), [`GanttPrintOptions`](/api/gantt/extensions/#ganttprintoptions)

## `GanttPersistenceRecipeChannel`

<span class="api-kind">type</span>

```ts
export type GanttPersistenceRecipeChannel =
  | 'persistence'
  | 'export'
  | 'reporting'
  | 'framework';
```

## `GanttPersistenceRecipeFramework`

<span class="api-kind">type</span>

```ts
export type GanttPersistenceRecipeFramework =
  | 'framework-neutral'
  | 'svelte'
  | 'vanilla';
```

## `GanttPersistenceRecipeId`

<span class="api-kind">type</span>

```ts
export type GanttPersistenceRecipeId =
  | 'rest-project-snapshot'
  | 'graphql-project-snapshot'
  | 'supabase-postgres-project-snapshot'
  | 'postgres-sql-project-snapshot'
  | 'print-pdf-export'
  | 'json-snapshot-helpers'
  | 'portal-svelte-gantt'
  | 'portal-resource-filter';
```

## `GanttPersistenceRecipeMetadata`

<span class="api-kind">interface</span>

```ts
export interface GanttPersistenceRecipeMetadata {
  readonly id: GanttPersistenceRecipeId;
  readonly title: string;
  readonly channel: GanttPersistenceRecipeChannel;
  readonly frameworks: readonly GanttPersistenceRecipeFramework[];
  readonly sourceFiles: readonly string[];
  readonly dependencies: readonly string[];
  readonly summary: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `GanttPersistenceRecipeId` | Yes | — |  |
| `title` | `string` | Yes | — |  |
| `channel` | `GanttPersistenceRecipeChannel` | Yes | — |  |
| `frameworks` | `readonly GanttPersistenceRecipeFramework[]` | Yes | — |  |
| `sourceFiles` | `readonly string[]` | Yes | — |  |
| `dependencies` | `readonly string[]` | Yes | — |  |
| `summary` | `string` | Yes | — |  |

**Related types:** [`GanttPersistenceRecipeChannel`](/api/gantt/extensions/#ganttpersistencerecipechannel), [`GanttPersistenceRecipeFramework`](/api/gantt/extensions/#ganttpersistencerecipeframework), [`GanttPersistenceRecipeId`](/api/gantt/extensions/#ganttpersistencerecipeid)

## `GanttPrintableMetadata`

<span class="api-kind">interface</span>

```ts
export interface GanttPrintableMetadata {
  readonly title: string;
  readonly subtitle?: string;
  readonly range?: GanttPrintDateRange;
  readonly rangeLabel?: string;
  readonly printedAt?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `title` | `string` | Yes | — |  |
| `subtitle` | `string \| undefined` | No | — |  |
| `range` | `GanttPrintDateRange \| undefined` | No | — |  |
| `rangeLabel` | `string \| undefined` | No | — |  |
| `printedAt` | `string \| undefined` | No | — |  |

**Related types:** [`GanttPrintDateRange`](/api/gantt/extensions/#ganttprintdaterange)

## `GanttPrintableMetadataOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttPrintableMetadataOptions {
  readonly title?: string;
  readonly subtitle?: string;
  readonly range?: GanttPrintDateRange;
  readonly printedAt?: Date | string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `title` | `string \| undefined` | No | — |  |
| `subtitle` | `string \| undefined` | No | — |  |
| `range` | `GanttPrintDateRange \| undefined` | No | — |  |
| `printedAt` | `string \| Date \| undefined` | No | — |  |

**Related types:** [`GanttPrintDateRange`](/api/gantt/extensions/#ganttprintdaterange)

## `GanttPrintDateRange`

<span class="api-kind">interface</span>

```ts
export interface GanttPrintDateRange {
  readonly startDate?: ISODateString;
  readonly endDate?: ISODateString;
  readonly label?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `startDate` | `ISODateString \| undefined` | No | — |  |
| `endDate` | `ISODateString \| undefined` | No | — |  |
| `label` | `string \| undefined` | No | — |  |

## `GanttPrintOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttPrintOptions extends GanttPrintStyleOptions {
  readonly metadata?: GanttPrintableMetadataOptions;
  readonly document?: Document;
  readonly window?: GanttPrintWindow;
  readonly cleanupDelayMs?: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `metadata` | `GanttPrintableMetadataOptions \| undefined` | No | — |  |
| `document` | `Document \| undefined` | No | — |  |
| `window` | `GanttPrintWindow \| undefined` | No | — |  |
| `cleanupDelayMs` | `number \| undefined` | No | — |  |

**Related types:** [`GanttPrintStyleOptions`](/api/gantt/extensions/#ganttprintstyleoptions), [`GanttPrintWindow`](/api/gantt/extensions/#ganttprintwindow), [`GanttPrintableMetadataOptions`](/api/gantt/extensions/#ganttprintablemetadataoptions)

## `GanttPrintOrientation`

<span class="api-kind">type</span>

```ts
export type GanttPrintOrientation = 'portrait' | 'landscape';
```

## `GanttPrintPdfRecipe`

<span class="api-kind">interface</span>

```ts
export interface GanttPrintPdfRecipe {
  readonly metadata: GanttPersistenceRecipeMetadata;
  exportProject(project: ProjectSnapshot, range?: GanttPrintDateRange): GanttPrintResult;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `metadata` | `GanttPersistenceRecipeMetadata` | Yes | — |  |
| `exportProject(project: ProjectSnapshot, range?: GanttPrintDateRange)` | `GanttPrintResult` | Yes | — |  |

**Related types:** [`GanttPersistenceRecipeMetadata`](/api/gantt/extensions/#ganttpersistencerecipemetadata), [`GanttPrintDateRange`](/api/gantt/extensions/#ganttprintdaterange), [`GanttPrintResult`](/api/gantt/extensions/#ganttprintresult), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)

## `GanttPrintPdfRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttPrintPdfRecipeOptions {
  readonly target: Element | null | undefined;
  readonly document?: Document;
  readonly window?: GanttPrintOptions['window'];
  readonly now?: () => Date | string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `target` | `Element \| null \| undefined` | Yes | — |  |
| `document` | `Document \| undefined` | No | — |  |
| `window` | `GanttPrintWindow \| undefined` | No | — |  |
| `now` | `(() => Date \| string) \| undefined` | No | — |  |

**Related types:** [`GanttPrintOptions`](/api/gantt/extensions/#ganttprintoptions)

## `GanttPrintResult`

<span class="api-kind">interface</span>

```ts
export interface GanttPrintResult {
  readonly ok: boolean;
  readonly reason?: 'missing-target' | 'missing-document' | 'missing-window-print' | 'print-failed';
  readonly error?: unknown;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `ok` | `boolean` | Yes | — |  |
| `reason` | `"missing-target" \| "missing-document" \| "missing-window-print" \| "print-failed" \| undefined` | No | — |  |
| `error` | `unknown` | No | — |  |

## `GanttPrintStyleOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttPrintStyleOptions {
  readonly pageSize?: string;
  readonly orientation?: GanttPrintOrientation;
  readonly margin?: string;
  readonly printRootClass?: string;
  readonly printHeaderClass?: string;
  readonly hideSelectors?: readonly string[];
  readonly preserveColor?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `pageSize` | `string \| undefined` | No | — |  |
| `orientation` | `GanttPrintOrientation \| undefined` | No | — |  |
| `margin` | `string \| undefined` | No | — |  |
| `printRootClass` | `string \| undefined` | No | — |  |
| `printHeaderClass` | `string \| undefined` | No | — |  |
| `hideSelectors` | `readonly string[] \| undefined` | No | — |  |
| `preserveColor` | `boolean \| undefined` | No | — |  |

**Related types:** [`GanttPrintOrientation`](/api/gantt/extensions/#ganttprintorientation)

## `GanttPrintWindow`

<span class="api-kind">interface</span>

```ts
export interface GanttPrintWindow {
  print(): void;
  addEventListener?(type: 'afterprint', listener: () => void, options?: AddEventListenerOptions): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `print()` | `void` | Yes | — |  |
| `addEventListener(type: 'afterprint', listener: () => void, options?: AddEventListenerOptions)` | `void` | Yes | — |  |

## `GanttProjectFitOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttProjectFitOptions extends GanttTimelineNavigationOptions {
  viewportWidth?: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `viewportWidth` | `number \| undefined` | No | — |  |

**Related types:** [`GanttTimelineNavigationOptions`](/api/gantt/extensions/#gantttimelinenavigationoptions)

## `GanttRoleBasedEditabilityRecipe`

<span class="api-kind">interface</span>

```ts
export interface GanttRoleBasedEditabilityRecipe {
  readonly policy: GanttRoleEditabilityPolicy;
  readonly handlers: {
    readonly [GANTT_BEFORE_TASK_CHANGE_EVENT]: (event: GanttExampleCancelableEvent<GanttBeforeTaskChangeDetail>) => void;
    readonly [GANTT_BEFORE_DEPENDENCY_CHANGE_EVENT]: (
      event: GanttExampleCancelableEvent<GanttBeforeDependencyChangeDetail>,
    ) => void;
    readonly [GANTT_BEFORE_ASSIGNMENT_CHANGE_EVENT]: (
      event: GanttExampleCancelableEvent<GanttBeforeAssignmentChangeDetail>,
    ) => void;
  };
  readonly canEdit: <TEventName extends GanttBeforeChangeEventName>(
    eventName: TEventName,
    detail: Pick<GanttBeforeChangeDetailByEventName[TEventName], 'action'>,
  ) => boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `policy` | `GanttRoleEditabilityPolicy` | Yes | — |  |
| `handlers` | `{ readonly "gantt-before-task-change": (event: GanttExampleCancelableEvent) => void; readonly "gantt-before-dependency-change": (event: GanttExampleCancelableEvent) => void; readonly "gantt-before-assignment-change": (event: GanttExampleCancelableEvent) => void; }` | Yes | — |  |
| `canEdit` | `(eventName: TEventName, detail: Pick<GanttBeforeChangeDetailByEventName[TEventName], "action">) => boolean` | Yes | — |  |

**Related types:** [`GanttBeforeAssignmentChangeDetail`](/api/gantt/events/#ganttbeforeassignmentchangedetail), [`GanttBeforeDependencyChangeDetail`](/api/gantt/events/#ganttbeforedependencychangedetail), [`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail), [`GanttExampleCancelableEvent`](/api/gantt/events/#ganttexamplecancelableevent)

## `GanttRoleBasedEditabilityRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttRoleBasedEditabilityRecipeOptions {
  readonly policy?: GanttRoleEditabilityPolicy;
  readonly getRoleContext: () => GanttRoleEditabilityContext;
  readonly onDeny?: (
    eventName: GanttBeforeChangeEventName,
    detail: GanttBeforeChangeDetailByEventName[GanttBeforeChangeEventName],
  ) => void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `policy` | `GanttRoleEditabilityPolicy \| undefined` | No | — |  |
| `getRoleContext` | `() => GanttRoleEditabilityContext` | Yes | — |  |
| `onDeny` | `((eventName: GanttBeforeChangeEventName, detail: GanttBeforeChangeDetailByEventName[GanttBeforeChangeEventName]) => void) \| undefined` | No | — |  |

## `GanttTaskEditorControlId`

<span class="api-kind">type</span>

```ts
export type GanttTaskEditorControlId =
  | 'header'
  | 'title'
  | 'description'
  | 'close'
  | 'tabs'
  | 'validation'
  | 'preview'
  | 'cancel'
  /** @deprecated Use `cancel`. */
  | 'reset'
  | 'apply'
  | 'footer';
```

## `GanttTaskEditorDialog`

<span class="api-kind">function</span>

```ts
export function GanttTaskEditorDialog({
  grid,
  task,
  tasks,
  resources,
  assignments,
  dependencies,
  project,
  allowedTaskTypes,
  calendars,
  options,
  open,
  status,
  onClose,
  fieldReadonly = {},
  onSubmit,
}: GanttTaskEditorDialogProps): h.JSX.Element | null;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `{   grid,   task,   tasks,   resources,   assignments,   dependencies,   project,   allowedTaskTypes,   calendars,   options,   open,   status,   onClose,   fieldReadonly = {},   onSubmit, }` | `GanttTaskEditorDialogProps` | Yes | — |  |

## `GanttTaskEditorDialogCustomization`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDialogCustomization {
  readonly tabs?: GanttTaskEditorTabsOptions;
  readonly controls?: Partial<Record<GanttTaskEditorControlId, boolean>>;
  readonly editor?: GanttTaskEditorDomRenderer;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `tabs` | `GanttTaskEditorTabsOptions \| undefined` | No | — |  |
| `controls` | `Partial<Record<GanttTaskEditorControlId, boolean>> \| undefined` | No | — |  |
| `editor` | `GanttTaskEditorDomRenderer \| undefined` | No | — |  |

**Related types:** [`GanttTaskEditorControlId`](/api/gantt/extensions/#gantttaskeditorcontrolid), [`GanttTaskEditorDomRenderer`](/api/gantt/extensions/#gantttaskeditordomrenderer), [`GanttTaskEditorTabsOptions`](/api/gantt/extensions/#gantttaskeditortabsoptions)

## `ganttTaskEditorDialogDependencies`

<span class="api-kind">constant</span>

```ts
export const ganttTaskEditorDialogDependencies: PluginDependency[];
```

## `GanttTaskEditorDialogDependencyDraft`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDialogDependencyDraft {
  readonly id?: DependencyId;
  readonly predecessorTaskId: TaskId | '';
  readonly successorTaskId: TaskId | '';
  readonly type: DependencyType;
  readonly lagDays: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string \| undefined` | No | — |  |
| `predecessorTaskId` | `string` | Yes | — |  |
| `successorTaskId` | `string` | Yes | — |  |
| `type` | `DependencyType` | Yes | — |  |
| `lagDays` | `number` | Yes | — |  |

**Related types:** [`DependencyId`](/api/gantt/data-model/#dependencyid), [`DependencyType`](/api/gantt/data-model/#dependencytype), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttTaskEditorDialogLocaleText`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDialogLocaleText {
  readonly title: string;
  readonly description: string;
  readonly fallbackTaskTitle: string;
  readonly closeLabel: string;
  readonly closeButtonText: string;
  readonly applyLabel: string;
  readonly cancelLabel: string;
  /** @deprecated Use `cancelLabel`. */
  readonly resetLabel: string;
  readonly menuItemName: string;
  readonly tabListAriaLabel: string;
  readonly readOnlyLabel: string;
  readonly noResourcesAvailable: string;
  readonly noAssignedResources: string;
  readonly assignedResourcesAriaLabel: string;
  readonly colorPaletteAriaLabel: string;
  readonly defaultColorOption: string;
  readonly projectDefaultOption: string;
  readonly noConstraintOption: string;
  readonly timeToggleLabel: string;
  readonly switchOnLabel: string;
  readonly switchOffLabel: string;
  readonly manualSchedulingOnLabel: string;
  readonly manualSchedulingOffLabel: string;
  readonly dependencyTargetLabel: {
    readonly predecessors: string;
    readonly successors: string;
  };
  readonly dependencyEmptyLabel: {
    readonly predecessors: string;
    readonly successors: string;
  };
  readonly dependencySearch: {
    readonly predecessors: GanttTaskEditorDialogSearchText;
    readonly successors: GanttTaskEditorDialogSearchText;
  };
  readonly resourcesSearch: GanttTaskEditorDialogSearchText;
  readonly dependencyTypeLabel: string;
  readonly dependencyLagDaysLabel: string;
  readonly removeDependencyLabel: (targetLabel: string) => string;
  readonly removeDependencyButton: string;
  readonly addDependencyButton: {
    readonly predecessors: string;
    readonly successors: string;
  };
  readonly tabs: Record<TaskEditorTabId, string>;
  readonly dependencyTypes: Record<DependencyType, string>;
  readonly fields: Partial<Record<TaskEditorFieldId, string>>;
  readonly fieldOptions: Partial<Record<TaskEditorFieldId, readonly TaskEditorFieldOption[]>>;
  readonly status: GanttTaskEditorDialogStatusText;
  readonly validation: GanttTaskEditorDialogValidationText;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `title` | `string` | Yes | — |  |
| `description` | `string` | Yes | — |  |
| `fallbackTaskTitle` | `string` | Yes | — |  |
| `closeLabel` | `string` | Yes | — |  |
| `closeButtonText` | `string` | Yes | — |  |
| `applyLabel` | `string` | Yes | — |  |
| `cancelLabel` | `string` | Yes | — |  |
| `resetLabel` | `string` | Yes | — |  |
| `menuItemName` | `string` | Yes | — |  |
| `tabListAriaLabel` | `string` | Yes | — |  |
| `readOnlyLabel` | `string` | Yes | — |  |
| `noResourcesAvailable` | `string` | Yes | — |  |
| `noAssignedResources` | `string` | Yes | — |  |
| `assignedResourcesAriaLabel` | `string` | Yes | — |  |
| `colorPaletteAriaLabel` | `string` | Yes | — |  |
| `defaultColorOption` | `string` | Yes | — |  |
| `projectDefaultOption` | `string` | Yes | — |  |
| `noConstraintOption` | `string` | Yes | — |  |
| `timeToggleLabel` | `string` | Yes | — |  |
| `switchOnLabel` | `string` | Yes | — |  |
| `switchOffLabel` | `string` | Yes | — |  |
| `manualSchedulingOnLabel` | `string` | Yes | — |  |
| `manualSchedulingOffLabel` | `string` | Yes | — |  |
| `dependencyTargetLabel` | `{ readonly predecessors: string; readonly successors: string; }` | Yes | — |  |
| `dependencyEmptyLabel` | `{ readonly predecessors: string; readonly successors: string; }` | Yes | — |  |
| `dependencySearch` | `{ readonly predecessors: GanttTaskEditorDialogSearchText; readonly successors: GanttTaskEditorDialogSearchText; }` | Yes | — |  |
| `resourcesSearch` | `GanttTaskEditorDialogSearchText` | Yes | — |  |
| `dependencyTypeLabel` | `string` | Yes | — |  |
| `dependencyLagDaysLabel` | `string` | Yes | — |  |
| `removeDependencyLabel` | `(targetLabel: string) => string` | Yes | — |  |
| `removeDependencyButton` | `string` | Yes | — |  |
| `addDependencyButton` | `{ readonly predecessors: string; readonly successors: string; }` | Yes | — |  |
| `tabs` | `Record<TaskEditorTabId, string>` | Yes | — |  |
| `dependencyTypes` | `Record<DependencyType, string>` | Yes | — |  |
| `fields` | `Partial<Record<TaskEditorFieldId, string>>` | Yes | — |  |
| `fieldOptions` | `Partial<Record<TaskEditorFieldId, readonly TaskEditorFieldOption<string>[]>>` | Yes | — |  |
| `status` | `GanttTaskEditorDialogStatusText` | Yes | — |  |
| `validation` | `GanttTaskEditorDialogValidationText` | Yes | — |  |

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype), [`GanttTaskEditorDialogSearchText`](/api/gantt/extensions/#gantttaskeditordialogsearchtext), [`GanttTaskEditorDialogStatusText`](/api/gantt/extensions/#gantttaskeditordialogstatustext), [`GanttTaskEditorDialogValidationText`](/api/gantt/extensions/#gantttaskeditordialogvalidationtext)

## `GanttTaskEditorDialogLocaleTextOptions`

<span class="api-kind">type</span>

```ts
export type GanttTaskEditorDialogLocaleTextOptions = Partial<Omit<
  GanttTaskEditorDialogLocaleText,
  | 'dependencyTargetLabel'
  | 'dependencyEmptyLabel'
  | 'dependencySearch'
  | 'resourcesSearch'
  | 'addDependencyButton'
  | 'tabs'
  | 'dependencyTypes'
  | 'fields'
  | 'fieldOptions'
  | 'status'
  | 'validation'
>> & {
  readonly dependencyTargetLabel?: Partial<GanttTaskEditorDialogLocaleText['dependencyTargetLabel']>;
  readonly dependencyEmptyLabel?: Partial<GanttTaskEditorDialogLocaleText['dependencyEmptyLabel']>;
  readonly dependencySearch?: {
    readonly predecessors?: Partial<GanttTaskEditorDialogSearchText>;
    readonly successors?: Partial<GanttTaskEditorDialogSearchText>;
  };
  readonly resourcesSearch?: Partial<GanttTaskEditorDialogSearchText>;
  readonly addDependencyButton?: Partial<GanttTaskEditorDialogLocaleText['addDependencyButton']>;
  readonly tabs?: Partial<Record<TaskEditorTabId, string>>;
  readonly dependencyTypes?: Partial<Record<DependencyType, string>>;
  readonly fields?: Partial<Record<TaskEditorFieldId, string>>;
  readonly fieldOptions?: Partial<Record<TaskEditorFieldId, readonly TaskEditorFieldOption[]>>;
  readonly status?: Partial<GanttTaskEditorDialogStatusText>;
  readonly validation?: Partial<GanttTaskEditorDialogValidationText>;
};
```

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype), [`GanttTaskEditorDialogLocaleText`](/api/gantt/extensions/#gantttaskeditordialoglocaletext), [`GanttTaskEditorDialogSearchText`](/api/gantt/extensions/#gantttaskeditordialogsearchtext), [`GanttTaskEditorDialogStatusText`](/api/gantt/extensions/#gantttaskeditordialogstatustext), [`GanttTaskEditorDialogValidationText`](/api/gantt/extensions/#gantttaskeditordialogvalidationtext)

## `GanttTaskEditorDialogOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDialogOptions {
  readonly fields?: readonly TaskEditorFieldId[];
  readonly localeText?: GanttTaskEditorDialogLocaleTextOptions;
  readonly menuItemName?: string;
  readonly title?: string;
  readonly description?: string;
  readonly applyLabel?: string;
  /** Label for the footer action that discards drafts and closes the dialog. */
  readonly cancelLabel?: string;
  /** @deprecated Use `cancelLabel`. */
  readonly resetLabel?: string;
  readonly closeLabel?: string;
  /**
   * Controls the packaged row context-menu entry for opening the task editor.
   * Defaults to the Gantt context-menu setting. Set to `false` to remove only
   * the editor menu item, or `true` to keep it when `gantt.contextMenu` is
   * disabled.
   */
  readonly contextMenu?: boolean;
  /**
   * Opens the dialog immediately after the Gantt plugin creates a task. Defaults
   * to `true`. Set to `false` to keep task creation silent. This
   * covers task creation from the toolbar, row context menu, and custom
   * dispatches of the task-create event.
   */
  readonly openOnCreate?: boolean;
  /**
   * Controls the built-in resource assignment picker. Set to `false` to keep
   * the resources field read-only.
   */
  readonly resources?: false | GanttTaskEditorDialogResourcesOptions;
  /**
   * Overrides inherited task-table editability for packaged dialog fields.
   * `true` enables a field and `false` makes it read-only. Gantt-wide read-only
   * mode and `resources: false` remain hard restrictions.
   */
  readonly fieldEditability?: Partial<Record<GanttTaskEditorFieldEditabilityId, boolean>>;
  /**
   * Configures task colors in the packaged editor. Omit to inherit the Gantt
   * context-menu palette; set to `false` to remove the editor field.
   */
  readonly colorPalette?: GanttColorPaletteConfig | false;
  /**
   * Shows the normalized TaskUpdate JSON preview. Intended for documentation,
   * diagnostics, and custom developer tooling; hidden by default for end-user UI.
   */
  readonly preview?: boolean;
  readonly readOnly?: boolean;
  readonly onSubmit?: (context: GanttTaskEditorDialogSubmitContext) => boolean | void | Promise<boolean | void>;
  readonly getTask?: (taskId: TaskId, grid: HTMLRevoGridElement) => TaskEntity | null | undefined;
  readonly customization?: GanttTaskEditorDialogCustomization;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `fields` | `readonly TaskEditorFieldId[] \| undefined` | No | — |  |
| `localeText` | `GanttTaskEditorDialogLocaleTextOptions \| undefined` | No | — |  |
| `menuItemName` | `string \| undefined` | No | — |  |
| `title` | `string \| undefined` | No | — |  |
| `description` | `string \| undefined` | No | — |  |
| `applyLabel` | `string \| undefined` | No | — |  |
| `cancelLabel` | `string \| undefined` | No | — | Label for the footer action that discards drafts and closes the dialog. |
| `resetLabel` | `string \| undefined` | No | — |  |
| `closeLabel` | `string \| undefined` | No | — |  |
| `contextMenu` | `boolean \| undefined` | No | — | Controls the packaged row context-menu entry for opening the task editor. Defaults to the Gantt context-menu setting. Set to `false` to remove only the editor menu item, or `true` to keep it when `gantt.contextMenu` is disabled. |
| `openOnCreate` | `boolean \| undefined` | No | — | Opens the dialog immediately after the Gantt plugin creates a task. Defaults to `true`. Set to `false` to keep task creation silent. This covers task creation from the toolbar, row context menu, and custom dispatches of the task-create event. |
| `resources` | `false \| GanttTaskEditorDialogResourcesOptions \| undefined` | No | — | Controls the built-in resource assignment picker. Set to `false` to keep the resources field read-only. |
| `fieldEditability` | `Partial<Record<GanttTaskEditorFieldEditabilityId, boolean>> \| undefined` | No | — | Overrides inherited task-table editability for packaged dialog fields. `true` enables a field and `false` makes it read-only. Gantt-wide read-only mode and `resources: false` remain hard restrictions. |
| `colorPalette` | `false \| GanttColorPaletteConfig \| undefined` | No | — | Configures task colors in the packaged editor. Omit to inherit the Gantt context-menu palette; set to `false` to remove the editor field. |
| `preview` | `boolean \| undefined` | No | — | Shows the normalized TaskUpdate JSON preview. Intended for documentation, diagnostics, and custom developer tooling; hidden by default for end-user UI. |
| `readOnly` | `boolean \| undefined` | No | — |  |
| `onSubmit` | `((context: GanttTaskEditorDialogSubmitContext) => boolean \| void \| Promise<boolean \| void>) \| undefined` | No | — |  |
| `getTask` | `((taskId: TaskId, grid: HTMLRevoGridElement) => TaskEntity \| null \| undefined) \| undefined` | No | — |  |
| `customization` | `GanttTaskEditorDialogCustomization \| undefined` | No | — |  |

**Related types:** [`GanttColorPaletteConfig`](/api/gantt/plugin/#ganttcolorpaletteconfig), [`GanttTaskEditorDialogCustomization`](/api/gantt/extensions/#gantttaskeditordialogcustomization), [`GanttTaskEditorDialogLocaleTextOptions`](/api/gantt/extensions/#gantttaskeditordialoglocaletextoptions), [`GanttTaskEditorDialogResourcesOptions`](/api/gantt/extensions/#gantttaskeditordialogresourcesoptions), [`GanttTaskEditorDialogSubmitContext`](/api/gantt/extensions/#gantttaskeditordialogsubmitcontext), [`GanttTaskEditorFieldEditabilityId`](/api/gantt/extensions/#gantttaskeditorfieldeditabilityid), [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskId`](/api/gantt/data-model/#taskid), [`TaskUpdate`](/api/gantt/data-model/#taskupdate)

## `GanttTaskEditorDialogPlugin`

<span class="api-kind">class</span>

```ts
export class GanttTaskEditorDialogPlugin extends CorePlugin {
  pluginDependencies: PluginDependency[];
  constructor(revogrid: HTMLRevoGridElement, providers: PluginProviders);
  openTask(taskId: TaskId | null): void;
  closeTaskEditor(): void;
  destroy(): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `pluginDependencies` | `PluginDependency[]` | Yes | `ganttTaskEditorDialogDependencies` |  |
| `host` | `HTMLDivElement` | Yes | — |  |
| `originalRowContextMenu` | `ContextMenuConfig \| undefined` | Yes | — |  |
| `appliedRowContextMenu` | `ContextMenuConfig \| null` | Yes | `null` |  |
| `selectedTaskId` | `string \| null` | Yes | `null` |  |
| `recentCreatedTasks` | `Map<string, TaskEntity>` | Yes | `new Map<TaskId, TaskEntity>()` |  |
| `status` | `string` | Yes | `DEFAULT_TASK_EDITOR_DIALOG_LOCALE_TEXT.status.ready` |  |
| `open` | `boolean` | Yes | `false` |  |
| `renderKey` | `number` | Yes | `0` |  |
| `taskEditorDialogOptions` | `GanttTaskEditorDialogOptions` | Yes | `DEFAULT_TASK_EDITOR_DIALOG_OPTIONS` |  |
| `ganttConfig` | `GanttPluginConfig \| undefined` | Yes | — |  |
| `openTask(taskId: TaskId \| null)` | `void` | Yes | — |  |
| `closeTaskEditor()` | `void` | Yes | — |  |
| `destroy()` | `void` | Yes | — |  |
| `removeContextMenu()` | `void` | Yes | — |  |
| `isContextMenuEnabled()` | `boolean` | Yes | — |  |
| `getTaskRuntime()` | `GanttTaskRuntime \| undefined` | Yes | — |  |
| `getCurrentProjectSnapshot()` | `ProjectSnapshot \| null` | Yes | — |  |
| `getCurrentTasks()` | `readonly TaskEntity[]` | Yes | — |  |
| `getCurrentResources()` | `readonly ResourceEntity[]` | Yes | — |  |
| `getCurrentAssignments()` | `readonly AssignmentEntity[]` | Yes | — |  |
| `getCurrentDependencies()` | `readonly DependencyEntity[]` | Yes | — |  |
| `getCurrentCalendars()` | `readonly CalendarEntity[]` | Yes | — |  |
| `deleteUnsavedCreatedTask()` | `void` | Yes | — |  |
| `getTaskRowIndex(taskId: TaskId)` | `number \| null` | Yes | — |  |
| `applyTaskPatch(task: TaskEntity, patch: TaskUpdate)` | `boolean` | Yes | — |  |
| `getTask(taskId: TaskId)` | `TaskEntity \| null` | Yes | — |  |
| `isReadOnly()` | `boolean` | Yes | — |  |
| `getFieldReadonly(task: TaskEntity)` | `Partial<Record<GanttTaskEditorFieldEditabilityId, boolean>>` | Yes | — |  |
| `createNextAssignments(taskId: TaskId, selectedResourceIds: readonly ResourceId[])` | `{ assignments: readonly AssignmentEntity[]; changed: boolean; error: string \| null }` | Yes | — |  |
| `createNextDependencies(taskId: TaskId, dependencyDrafts: readonly GanttTaskEditorDialogDependencyDraft[])` | `{ dependencies: readonly DependencyEntity[]; changed: boolean; error: string \| null }` | Yes | — |  |
| `applyContextMenu()` | `void` | Yes | — |  |
| `syncContextMenuPlugin()` | `Promise<void>` | Yes | — |  |
| `submit(values: TaskEditorFormValues, selectedResourceIds: readonly ResourceId[], dependencyDrafts: readonly GanttTaskEditorDialogDependencyDraft[], customValues: Readonly<Record<string, unknown>> = {})` | `Promise<void>` | Yes | — |  |
| `renderDialog()` | `void` | Yes | — |  |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttTaskEditorDialogResourcesOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDialogResourcesOptions {
  readonly editable?: boolean;
  readonly defaultAllocationUnits?: number;
  readonly defaultResponsibility?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `editable` | `boolean \| undefined` | No | — |  |
| `defaultAllocationUnits` | `number \| undefined` | No | — |  |
| `defaultResponsibility` | `string \| undefined` | No | — |  |

## `GanttTaskEditorDialogSearchText`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDialogSearchText {
  readonly placeholder: string;
  readonly ariaLabel: string;
  readonly empty: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `placeholder` | `string` | Yes | — |  |
| `ariaLabel` | `string` | Yes | — |  |
| `empty` | `string` | Yes | — |  |

## `GanttTaskEditorDialogState`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDialogState {
  readonly taskId: TaskId | null;
  readonly task: TaskEntity | null;
  readonly values: TaskEditorFormValues;
  readonly status: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskId` | `string \| null` | Yes | — |  |
| `task` | `TaskEntity \| null` | Yes | — |  |
| `values` | `Partial<Record<TaskEditorFieldId, unknown>>` | Yes | — |  |
| `status` | `string` | Yes | — |  |

**Related types:** [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttTaskEditorDialogStatusText`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDialogStatusText {
  readonly ready: string;
  readonly closed: string;
  readonly changesSaved: string;
  readonly noChangesToSave: string;
  readonly readOnlyProject: string;
  readonly fixValidationErrors: string;
  readonly saveFailed: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `ready` | `string` | Yes | — |  |
| `closed` | `string` | Yes | — |  |
| `changesSaved` | `string` | Yes | — |  |
| `noChangesToSave` | `string` | Yes | — |  |
| `readOnlyProject` | `string` | Yes | — |  |
| `fixValidationErrors` | `string` | Yes | — |  |
| `saveFailed` | `string` | Yes | — |  |

## `GanttTaskEditorDialogSubmitContext`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDialogSubmitContext {
  readonly grid: HTMLRevoGridElement;
  readonly task: TaskEntity;
  readonly values: TaskEditorFormValues;
  readonly result: TaskEditorSubmitSuccess;
  readonly assignmentResourceIds: readonly ResourceId[];
  readonly assignments: readonly AssignmentEntity[];
  readonly assignmentsChanged: boolean;
  readonly dependencyDrafts: readonly GanttTaskEditorDialogDependencyDraft[];
  readonly dependencies: readonly DependencyEntity[];
  readonly dependenciesChanged: boolean;
  readonly customValues: Readonly<Record<string, unknown>>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |
| `task` | `TaskEntity` | Yes | — |  |
| `values` | `Partial<Record<TaskEditorFieldId, unknown>>` | Yes | — |  |
| `result` | `TaskEditorSubmitSuccess` | Yes | — |  |
| `assignmentResourceIds` | `readonly string[]` | Yes | — |  |
| `assignments` | `readonly AssignmentEntity[]` | Yes | — |  |
| `assignmentsChanged` | `boolean` | Yes | — |  |
| `dependencyDrafts` | `readonly GanttTaskEditorDialogDependencyDraft[]` | Yes | — |  |
| `dependencies` | `readonly DependencyEntity[]` | Yes | — |  |
| `dependenciesChanged` | `boolean` | Yes | — |  |
| `customValues` | `Readonly<Record<string, unknown>>` | Yes | — |  |

**Related types:** [`AssignmentEntity`](/api/gantt/data-model/#assignmententity), [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`GanttTaskEditorDialogDependencyDraft`](/api/gantt/extensions/#gantttaskeditordialogdependencydraft), [`ResourceId`](/api/gantt/data-model/#resourceid), [`TaskEntity`](/api/gantt/data-model/#taskentity)

## `GanttTaskEditorDialogValidationText`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDialogValidationText {
  readonly checkRequiredFields: string;
  readonly couldNotSave: string;
  readonly fieldError: (error: TaskEditorSubmitError, fieldLabel: string) => string;
  readonly resourceNotFound: (resourceId: ResourceId) => string;
  readonly taskCannotDependOnItself: string;
  readonly predecessorTaskNotFound: (taskId: TaskId) => string;
  readonly successorTaskNotFound: (taskId: TaskId) => string;
  readonly dependencyMustIncludeCurrentTask: string;
  readonly duplicateDependencyLinks: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `checkRequiredFields` | `string` | Yes | — |  |
| `couldNotSave` | `string` | Yes | — |  |
| `fieldError` | `(error: TaskEditorSubmitError, fieldLabel: string) => string` | Yes | — |  |
| `resourceNotFound` | `(resourceId: ResourceId) => string` | Yes | — |  |
| `taskCannotDependOnItself` | `string` | Yes | — |  |
| `predecessorTaskNotFound` | `(taskId: TaskId) => string` | Yes | — |  |
| `successorTaskNotFound` | `(taskId: TaskId) => string` | Yes | — |  |
| `dependencyMustIncludeCurrentTask` | `string` | Yes | — |  |
| `duplicateDependencyLinks` | `string` | Yes | — |  |

**Related types:** [`ResourceId`](/api/gantt/data-model/#resourceid), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttTaskEditorDomRenderer`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDomRenderer {
  mount(container: HTMLElement, context: GanttTaskEditorRendererContext): void | GanttTaskEditorRendererLifecycle;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `mount(container: HTMLElement, context: GanttTaskEditorRendererContext)` | `void \| GanttTaskEditorRendererLifecycle` | Yes | — |  |

**Related types:** [`GanttTaskEditorRendererContext`](/api/gantt/extensions/#gantttaskeditorrenderercontext), [`GanttTaskEditorRendererLifecycle`](/api/gantt/extensions/#gantttaskeditorrendererlifecycle)

## `GanttTaskEditorDraftController`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDraftController {
  getState(): GanttTaskEditorDraftState;
  setValues(values: Partial<TaskEditorFormValues>): void;
  setResourceIds(resourceIds: readonly ResourceId[]): void;
  setDependencyDrafts(drafts: readonly GanttTaskEditorDialogDependencyDraft[]): void;
  setCustomValue(key: string, value: unknown): void;
  setValidationErrors(errors: readonly string[]): void;
  reset(): void;
  close(): void;
  submit(): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `getState()` | `GanttTaskEditorDraftState` | Yes | — |  |
| `setValues(values: Partial)` | `void` | Yes | — |  |
| `setResourceIds(resourceIds: readonly ResourceId[])` | `void` | Yes | — |  |
| `setDependencyDrafts(drafts: readonly GanttTaskEditorDialogDependencyDraft[])` | `void` | Yes | — |  |
| `setCustomValue(key: string, value: unknown)` | `void` | Yes | — |  |
| `setValidationErrors(errors: readonly string[])` | `void` | Yes | — |  |
| `reset()` | `void` | Yes | — |  |
| `close()` | `void` | Yes | — |  |
| `submit()` | `void` | Yes | — |  |

**Related types:** [`GanttTaskEditorDialogDependencyDraft`](/api/gantt/extensions/#gantttaskeditordialogdependencydraft), [`GanttTaskEditorDraftState`](/api/gantt/extensions/#gantttaskeditordraftstate), [`ResourceId`](/api/gantt/data-model/#resourceid)

## `GanttTaskEditorDraftState`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorDraftState {
  readonly values: TaskEditorFormValues;
  readonly resourceIds: readonly ResourceId[];
  readonly dependencyDrafts: readonly GanttTaskEditorDialogDependencyDraft[];
  readonly customValues: Readonly<Record<string, unknown>>;
  readonly validationErrors: readonly string[];
  readonly dirty: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `values` | `Partial<Record<TaskEditorFieldId, unknown>>` | Yes | — |  |
| `resourceIds` | `readonly string[]` | Yes | — |  |
| `dependencyDrafts` | `readonly GanttTaskEditorDialogDependencyDraft[]` | Yes | — |  |
| `customValues` | `Readonly<Record<string, unknown>>` | Yes | — |  |
| `validationErrors` | `readonly string[]` | Yes | — |  |
| `dirty` | `boolean` | Yes | — |  |

**Related types:** [`GanttTaskEditorDialogDependencyDraft`](/api/gantt/extensions/#gantttaskeditordialogdependencydraft), [`ResourceId`](/api/gantt/data-model/#resourceid)

## `GanttTaskEditorFieldEditabilityId`

<span class="api-kind">type</span>

Packaged task-dialog controls that can inherit task-table editability.

```ts
export type GanttTaskEditorFieldEditabilityId =
  | TaskEditorFieldId
  | 'predecessors'
  | 'successors';
```

## `GanttTaskEditorRendererContext`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorRendererContext {
  readonly grid: HTMLRevoGridElement;
  readonly task: TaskEntity | null;
  readonly project: ProjectSnapshot | null;
  readonly open: boolean;
  readonly status: string;
  readonly state: GanttTaskEditorDraftState;
  readonly controller: GanttTaskEditorDraftController;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |
| `task` | `TaskEntity \| null` | Yes | — |  |
| `project` | `ProjectSnapshot \| null` | Yes | — |  |
| `open` | `boolean` | Yes | — |  |
| `status` | `string` | Yes | — |  |
| `state` | `GanttTaskEditorDraftState` | Yes | — |  |
| `controller` | `GanttTaskEditorDraftController` | Yes | — |  |

**Related types:** [`GanttTaskEditorDraftController`](/api/gantt/extensions/#gantttaskeditordraftcontroller), [`GanttTaskEditorDraftState`](/api/gantt/extensions/#gantttaskeditordraftstate), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`TaskEntity`](/api/gantt/data-model/#taskentity)

## `GanttTaskEditorRendererLifecycle`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorRendererLifecycle {
  update?(context: GanttTaskEditorRendererContext): void;
  destroy?(): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `update(context: GanttTaskEditorRendererContext)` | `void` | Yes | — |  |
| `destroy()` | `void` | Yes | — |  |

**Related types:** [`GanttTaskEditorRendererContext`](/api/gantt/extensions/#gantttaskeditorrenderercontext)

## `GanttTaskEditorTabOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorTabOptions {
  readonly title?: string;
  readonly hidden?: boolean;
  readonly fields?: readonly TaskEditorFieldId[];
  readonly renderer?: GanttTaskEditorDomRenderer;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `title` | `string \| undefined` | No | — |  |
| `hidden` | `boolean \| undefined` | No | — |  |
| `fields` | `readonly TaskEditorFieldId[] \| undefined` | No | — |  |
| `renderer` | `GanttTaskEditorDomRenderer \| undefined` | No | — |  |

**Related types:** [`GanttTaskEditorDomRenderer`](/api/gantt/extensions/#gantttaskeditordomrenderer)

## `GanttTaskEditorTabsOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskEditorTabsOptions {
  readonly items?: Readonly<Record<string, false | GanttTaskEditorTabOptions>>;
  readonly order?: readonly string[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `items` | `Readonly<Record<string, false \| GanttTaskEditorTabOptions>> \| undefined` | No | — |  |
| `order` | `readonly string[] \| undefined` | No | — |  |

**Related types:** [`GanttTaskEditorTabOptions`](/api/gantt/extensions/#gantttaskeditortaboptions)

## `GanttTaskStatusIndicatorRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskStatusIndicatorRecipeOptions {
  readonly rows: readonly Pick<GanttGridRow, 'id'>[];
  readonly projectReadOnly?: boolean;
  readonly lockedTaskIds?: ReadonlySet<TaskId> | readonly TaskId[];
  readonly labels?: Parameters<typeof createTaskStatusIndicators>[0]['labels'];
  readonly classNames?: Parameters<typeof createTaskStatusIndicators>[0]['classNames'];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `rows` | `readonly Pick<GanttGridRow, "id">[]` | Yes | — |  |
| `projectReadOnly` | `boolean \| undefined` | No | — |  |
| `lockedTaskIds` | `readonly string[] \| ReadonlySet<string> \| undefined` | No | — |  |
| `labels` | `Partial<Record<TaskStatusIndicatorKind, string>> \| undefined` | No | — |  |
| `classNames` | `Partial<Record<TaskStatusIndicatorKind, string>> \| undefined` | No | — |  |

**Related types:** [`GanttGridRow`](/api/gantt/columns/#ganttgridrow), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttTaskStatusIndicatorRecipeRow`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskStatusIndicatorRecipeRow {
  readonly taskId: TaskId;
  readonly status: TaskStatusIndicatorProjection;
  readonly className: string;
  readonly title: string;
  readonly ariaLabel: string | undefined;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskId` | `string` | Yes | — |  |
| `status` | `TaskStatusIndicatorProjection` | Yes | — |  |
| `className` | `string` | Yes | — |  |
| `title` | `string` | Yes | — |  |
| `ariaLabel` | `string \| undefined` | Yes | — |  |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttTimelineNavigationOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttTimelineNavigationOptions {
  align?: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `align` | `number \| undefined` | No | — |  |

## `GanttTimelineNavigationRuntime`

<span class="api-kind">interface</span>

```ts
export interface GanttTimelineNavigationRuntime {
  scrollToToday?: () => Promise<void> | void;
  fitToProject?: () => Promise<void> | void;
  getZoomLevel?: () => { id?: string } | null | undefined;
  setZoomLevel?: (levelId: string) => boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `scrollToToday` | `(() => Promise<void> \| void) \| undefined` | No | — |  |
| `fitToProject` | `(() => Promise<void> \| void) \| undefined` | No | — |  |
| `getZoomLevel` | `(() => { id?: string; } \| null \| undefined) \| undefined` | No | — |  |
| `setZoomLevel` | `((levelId: string) => boolean) \| undefined` | No | — |  |

## `GanttTodayNavigationOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttTodayNavigationOptions extends GanttTimelineNavigationOptions {
  date?: ISODateString;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `date` | `ISODateString \| undefined` | No | — |  |

**Related types:** [`GanttTimelineNavigationOptions`](/api/gantt/extensions/#gantttimelinenavigationoptions)

## `GanttToolbar`

<span class="api-kind">constant</span>

```ts
export const GanttToolbar: ({ grid, columns, visuals: initialVisuals, controls }: GanttToolbarComponentProps) => h.JSX.Element;
```

## `GanttToolbarColumnOption`

<span class="api-kind">interface</span>

A single column entry shown in the Gantt toolbar column-visibility dropdown.

```ts
export interface GanttToolbarColumnOption {
  /** Property name matching a task-table column (e.g. `'wbs'`, `'status'`). */
  prop: string;
  /** Human-readable label shown in the dropdown. */
  label: string;
  /**
   * Whether the column is visible by default.
   * Columns with `visible: false` will be added to `grid.hideColumns` on mount.
   * @default true
   */
  visible?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `prop` | `string` | Yes | — | Property name matching a task-table column (e.g. `'wbs'`, `'status'`). |
| `label` | `string` | Yes | — | Human-readable label shown in the dropdown. |
| `visible` | `boolean \| undefined` | No | `true` | Whether the column is visible by default. Columns with `visible: false` will be added to `grid.hideColumns` on mount. |

## `GanttToolbarControls`

<span class="api-kind">interface</span>

Visibility switches for each toolbar control or control group.

```ts
export interface GanttToolbarControls {
  search?: boolean;
  history?: boolean;
  undo?: boolean;
  redo?: boolean;
  tree?: boolean;
  expandAll?: boolean;
  collapseAll?: boolean;
  zoom?: boolean;
  zoomIn?: boolean;
  zoomOut?: boolean;
  tasks?: boolean;
  addTask?: boolean;
  indent?: boolean;
  outdent?: boolean;
  export?: boolean;
  exportExcel?: boolean;
  columns?: boolean;
  dependencies?: boolean;
  baseline?: boolean;
  criticalPath?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `search` | `boolean \| undefined` | No | — |  |
| `history` | `boolean \| undefined` | No | — |  |
| `undo` | `boolean \| undefined` | No | — |  |
| `redo` | `boolean \| undefined` | No | — |  |
| `tree` | `boolean \| undefined` | No | — |  |
| `expandAll` | `boolean \| undefined` | No | — |  |
| `collapseAll` | `boolean \| undefined` | No | — |  |
| `zoom` | `boolean \| undefined` | No | — |  |
| `zoomIn` | `boolean \| undefined` | No | — |  |
| `zoomOut` | `boolean \| undefined` | No | — |  |
| `tasks` | `boolean \| undefined` | No | — |  |
| `addTask` | `boolean \| undefined` | No | — |  |
| `indent` | `boolean \| undefined` | No | — |  |
| `outdent` | `boolean \| undefined` | No | — |  |
| `export` | `boolean \| undefined` | No | — |  |
| `exportExcel` | `boolean \| undefined` | No | — |  |
| `columns` | `boolean \| undefined` | No | — |  |
| `dependencies` | `boolean \| undefined` | No | — |  |
| `baseline` | `boolean \| undefined` | No | — |  |
| `criticalPath` | `boolean \| undefined` | No | — |  |

## `ganttToolbarDependencies`

<span class="api-kind">constant</span>

```ts
export const ganttToolbarDependencies: PluginDependency[];
```

## `GanttToolbarOptions`

<span class="api-kind">interface</span>

Options accepted by {@link defineGanttToolbar}.

```ts
export interface GanttToolbarOptions {
  /** The `revo-grid` element the toolbar should control. */
  grid: HTMLRevoGridElement;
  /**
   * Column options to show in the visibility dropdown.
   * If omitted, no column dropdown is rendered.
   */
  columns?: GanttToolbarColumnOption[];
  /**
   * Initial state of the visual/scheduling toggles.
   * When omitted, values are read from the current `grid.gantt.visuals` config.
   */
  visuals?: GanttToolbarVisuals;
  /**
   * Per-control visibility. Omitted options default to visible, except
   * `baseline`, which is opt-in to keep the default command bar compact.
   */
  controls?: GanttToolbarControls;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — | The `revo-grid` element the toolbar should control. |
| `columns` | `GanttToolbarColumnOption[] \| undefined` | No | — | Column options to show in the visibility dropdown. If omitted, no column dropdown is rendered. |
| `visuals` | `GanttToolbarVisuals \| undefined` | No | — | Initial state of the visual/scheduling toggles. When omitted, values are read from the current `grid.gantt.visuals` config. |
| `controls` | `GanttToolbarControls \| undefined` | No | — | Per-control visibility. Omitted options default to visible, except `baseline`, which is opt-in to keep the default command bar compact. |

**Related types:** [`GanttToolbarColumnOption`](/api/gantt/extensions/#gantttoolbarcolumnoption), [`GanttToolbarControls`](/api/gantt/extensions/#gantttoolbarcontrols), [`GanttToolbarVisuals`](/api/gantt/extensions/#gantttoolbarvisuals)

## `GanttToolbarQuickWinAction`

<span class="api-kind">interface</span>

```ts
export interface GanttToolbarQuickWinAction<Result = unknown> {
  readonly id: GanttToolbarQuickWinActionId;
  readonly label: string;
  readonly title: string;
  readonly run: () => Result | Promise<Result>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `GanttToolbarQuickWinActionId` | Yes | — |  |
| `label` | `string` | Yes | — |  |
| `title` | `string` | Yes | — |  |
| `run` | `() => Result \| Promise` | Yes | — |  |

**Related types:** [`GanttToolbarQuickWinActionId`](/api/gantt/extensions/#gantttoolbarquickwinactionid)

## `GanttToolbarQuickWinActionId`

<span class="api-kind">type</span>

```ts
export type GanttToolbarQuickWinActionId =
  | 'export-csv'
  | 'export-excel'
  | 'capture-baseline'
  | 'toggle-critical-path'
  | 'timeline-today'
  | 'timeline-fit-project';
```

## `GanttToolbarQuickWinActions`

<span class="api-kind">interface</span>

```ts
export interface GanttToolbarQuickWinActions {
  readonly exportCsv?: GanttToolbarQuickWinAction<boolean>;
  readonly exportExcel?: GanttToolbarQuickWinAction<CustomEvent<GanttExcelExportOptions>>;
  readonly captureBaseline?: GanttToolbarQuickWinAction<BaselineSnapshot | null>;
  readonly toggleCriticalPath?: GanttToolbarQuickWinAction<boolean | undefined>;
  readonly scrollToToday?: GanttToolbarQuickWinAction<boolean>;
  readonly fitToProject?: GanttToolbarQuickWinAction<boolean>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `exportCsv` | `GanttToolbarQuickWinAction<boolean> \| undefined` | No | — |  |
| `exportExcel` | `GanttToolbarQuickWinAction<CustomEvent> \| undefined` | No | — |  |
| `captureBaseline` | `GanttToolbarQuickWinAction \| undefined` | No | — |  |
| `toggleCriticalPath` | `GanttToolbarQuickWinAction<boolean \| undefined> \| undefined` | No | — |  |
| `scrollToToday` | `GanttToolbarQuickWinAction<boolean> \| undefined` | No | — |  |
| `fitToProject` | `GanttToolbarQuickWinAction<boolean> \| undefined` | No | — |  |

**Related types:** [`BaselineSnapshot`](/api/gantt/data-model/#baselinesnapshot), [`GanttExcelExportOptions`](/api/gantt/extensions/#ganttexcelexportoptions), [`GanttToolbarQuickWinAction`](/api/gantt/extensions/#gantttoolbarquickwinaction)

## `GanttToolbarQuickWinOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttToolbarQuickWinOptions {
  readonly csv?: GanttCsvExportOptions | false;
  readonly excel?: GanttExcelExportOptions | false;
  readonly baseline?: CaptureBaselineOptions | false;
  readonly criticalPath?: false;
  readonly today?: GanttTodayNavigationOptions | false;
  readonly fitToProject?: GanttProjectFitOptions | false;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `csv` | `false \| GanttCsvExportOptions \| undefined` | No | — |  |
| `excel` | `false \| ExportExcelEvent \| undefined` | No | — |  |
| `baseline` | `false \| CaptureBaselineOptions \| undefined` | No | — |  |
| `criticalPath` | `false \| undefined` | No | — |  |
| `today` | `false \| GanttTodayNavigationOptions \| undefined` | No | — |  |
| `fitToProject` | `false \| GanttProjectFitOptions \| undefined` | No | — |  |

**Related types:** [`GanttCsvExportOptions`](/api/gantt/extensions/#ganttcsvexportoptions), [`GanttExcelExportOptions`](/api/gantt/extensions/#ganttexcelexportoptions), [`GanttProjectFitOptions`](/api/gantt/extensions/#ganttprojectfitoptions), [`GanttTodayNavigationOptions`](/api/gantt/extensions/#gantttodaynavigationoptions)

## `GanttToolbarVisuals`

<span class="api-kind">interface</span>

Initial visual toggle state passed to the toolbar.

```ts
export interface GanttToolbarVisuals {
  showBaseline?: boolean;
  showDependencies?: boolean;
  showCriticalPath?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `showBaseline` | `boolean \| undefined` | No | — |  |
| `showDependencies` | `boolean \| undefined` | No | — |  |
| `showCriticalPath` | `boolean \| undefined` | No | — |  |

## `GanttValidationContext`

<span class="api-kind">interface</span>

```ts
export interface GanttValidationContext {
  readonly getTaskById?: (taskId: TaskId) => TaskEntity | null | undefined;
  readonly roleContext?: GanttRoleEditabilityContext;
  readonly approvals?: GanttApprovalRegistry;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `getTaskById` | `((taskId: TaskId) => TaskEntity \| null \| undefined) \| undefined` | No | — |  |
| `roleContext` | `GanttRoleEditabilityContext \| undefined` | No | — |  |
| `approvals` | `GanttApprovalRegistry \| undefined` | No | — |  |

**Related types:** [`GanttApprovalRegistry`](/api/gantt/extensions/#ganttapprovalregistry), [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttValidationDecision`

<span class="api-kind">interface</span>

```ts
export interface GanttValidationDecision {
  readonly ok: boolean;
  readonly code?: string;
  readonly message?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `ok` | `boolean` | Yes | — |  |
| `code` | `string \| undefined` | No | — |  |
| `message` | `string \| undefined` | No | — |  |

## `GanttValidationHandlerOptions`

<span class="api-kind">interface</span>

```ts
export interface GanttValidationHandlerOptions<TContext> {
  readonly context: TContext | (() => TContext);
  readonly validators: readonly GanttBeforeTaskChangeValidator<TContext>[];
  readonly onReject?: (rejection: GanttValidationReject) => void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `context` | `TContext \| (() => TContext)` | Yes | — |  |
| `validators` | `readonly GanttBeforeTaskChangeValidator[]` | Yes | — |  |
| `onReject` | `((rejection: GanttValidationReject) => void) \| undefined` | No | — |  |

**Related types:** [`GanttBeforeTaskChangeValidator`](/api/gantt/events/#ganttbeforetaskchangevalidator), [`GanttValidationReject`](/api/gantt/extensions/#ganttvalidationreject)

## `GanttValidationReject`

<span class="api-kind">interface</span>

```ts
export interface GanttValidationReject {
  readonly detail: GanttBeforeTaskChangeDetail;
  readonly decision: GanttValidationDecision;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `detail` | `GanttBeforeTaskChangeDetail` | Yes | — |  |
| `decision` | `GanttValidationDecision` | Yes | — |  |

**Related types:** [`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail), [`GanttValidationDecision`](/api/gantt/extensions/#ganttvalidationdecision)

## `getCsvExportPlugin`

<span class="api-kind">function</span>

```ts
export function getCsvExportPlugin(grid: HTMLRevoGridElement): Promise<RevoGridCsvExportPlugin | undefined>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |

**Related types:** [`RevoGridCsvExportPlugin`](/api/gantt/extensions/#revogridcsvexportplugin)

## `getDefaultDependencyDropdownType`

<span class="api-kind">function</span>

```ts
export function getDefaultDependencyDropdownType(allowedTypes: readonly DependencyType[] = DEFAULT_GANTT_DEPENDENCY_TYPES): DependencyType | null;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `allowedTypes` | `readonly DependencyType[]` | No | `DEFAULT_GANTT_DEPENDENCY_TYPES` |  |

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype)

## `getGanttBaselineCaptureRuntime`

<span class="api-kind">function</span>

```ts
export function getGanttBaselineCaptureRuntime(grid: HTMLRevoGridElement): Promise<GanttBaselineCaptureRuntime | undefined>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |

**Related types:** [`GanttBaselineCaptureRuntime`](/api/gantt/extensions/#ganttbaselinecaptureruntime)

## `getGanttDependencyDropdownCellBadges`

<span class="api-kind">function</span>

```ts
export function getGanttDependencyDropdownCellBadges(value: unknown, config: GanttDependencyDropdownConfig): string[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `value` | `unknown` | Yes | — |  |
| `config` | `GanttDependencyDropdownConfig` | Yes | — |  |

**Related types:** [`GanttDependencyDropdownConfig`](/api/gantt/extensions/#ganttdependencydropdownconfig)

## `getGanttDependencyDropdownSearchText`

<span class="api-kind">function</span>

```ts
export function getGanttDependencyDropdownSearchText(option: GanttDependencyDropdownTaskOption): string;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `option` | `GanttDependencyDropdownTaskOption` | Yes | — |  |

**Related types:** [`GanttDependencyDropdownTaskOption`](/api/gantt/extensions/#ganttdependencydropdowntaskoption)

## `getGanttDependencyDropdownTasks`

<span class="api-kind">function</span>

```ts
export function getGanttDependencyDropdownTasks(config: GanttDependencyDropdownConfig): readonly GanttDependencyDropdownTaskOption[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `config` | `GanttDependencyDropdownConfig` | Yes | — |  |

**Related types:** [`GanttDependencyDropdownConfig`](/api/gantt/extensions/#ganttdependencydropdownconfig), [`GanttDependencyDropdownTaskOption`](/api/gantt/extensions/#ganttdependencydropdowntaskoption)

## `getGanttDependencyDropdownValue`

<span class="api-kind">function</span>

```ts
export function getGanttDependencyDropdownValue(value: unknown, config: GanttDependencyDropdownConfig): GanttDependencyDropdownValue[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `value` | `unknown` | Yes | — |  |
| `config` | `GanttDependencyDropdownConfig` | Yes | — |  |

**Related types:** [`GanttDependencyDropdownConfig`](/api/gantt/extensions/#ganttdependencydropdownconfig), [`GanttDependencyDropdownValue`](/api/gantt/extensions/#ganttdependencydropdownvalue)

## `getGanttTimelineNavigationRuntime`

<span class="api-kind">function</span>

```ts
export function getGanttTimelineNavigationRuntime(grid: HTMLRevoGridElement): Promise<GanttTimelineNavigationRuntime | undefined>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |

**Related types:** [`GanttTimelineNavigationRuntime`](/api/gantt/extensions/#gantttimelinenavigationruntime)

## `getPersistenceRecipeMetadata`

<span class="api-kind">function</span>

```ts
export function getPersistenceRecipeMetadata(id: GanttPersistenceRecipeId): GanttPersistenceRecipeMetadata;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `GanttPersistenceRecipeId` | Yes | — |  |

**Related types:** [`GanttPersistenceRecipeId`](/api/gantt/extensions/#ganttpersistencerecipeid), [`GanttPersistenceRecipeMetadata`](/api/gantt/extensions/#ganttpersistencerecipemetadata)

## `isGanttAddTaskRow`

<span class="api-kind">function</span>

```ts
export function isGanttAddTaskRow(row: unknown): boolean;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `row` | `unknown` | Yes | — |  |

## `isGanttDependencyType`

<span class="api-kind">function</span>

```ts
export function isGanttDependencyType(value: unknown): value is DependencyType;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `value` | `unknown` | Yes | — |  |

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype)

## `listGanttToolbarQuickWinActions`

<span class="api-kind">function</span>

```ts
export function listGanttToolbarQuickWinActions(actions: GanttToolbarQuickWinActions): readonly GanttToolbarQuickWinAction[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `actions` | `GanttToolbarQuickWinActions` | Yes | — |  |

**Related types:** [`GanttToolbarQuickWinAction`](/api/gantt/extensions/#gantttoolbarquickwinaction), [`GanttToolbarQuickWinActions`](/api/gantt/extensions/#gantttoolbarquickwinactions)

## `LockedPhaseValidatorOptions`

<span class="api-kind">interface</span>

```ts
export interface LockedPhaseValidatorOptions<TContext> {
  readonly lockedPhaseIds: readonly string[];
  readonly getPhaseId: (detail: GanttBeforeTaskChangeDetail, context: TContext) => string | null | undefined;
  readonly actions?: readonly GanttBeforeTaskChangeAction[];
  readonly message?: (phaseId: string) => string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `lockedPhaseIds` | `readonly string[]` | Yes | — |  |
| `getPhaseId` | `(detail: GanttBeforeTaskChangeDetail, context: TContext) => string \| null \| undefined` | Yes | — |  |
| `actions` | `readonly GanttBeforeTaskChangeAction[] \| undefined` | No | — |  |
| `message` | `((phaseId: string) => string) \| undefined` | No | — |  |

**Related types:** [`GanttBeforeTaskChangeAction`](/api/gantt/events/#ganttbeforetaskchangeaction), [`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail)

## `normalizeGanttDependencyDropdownAllowedTypes`

<span class="api-kind">function</span>

```ts
export function normalizeGanttDependencyDropdownAllowedTypes(allowedTypes: readonly DependencyType[] | undefined): readonly DependencyType[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `allowedTypes` | `readonly DependencyType[] \| undefined` | Yes | — |  |

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype)

## `normalizeGanttDependencyDropdownValues`

<span class="api-kind">function</span>

```ts
export function normalizeGanttDependencyDropdownValues(value: readonly GanttDependencyDropdownValue[], options: readonly GanttDependencyDropdownTaskOption[]): GanttDependencyDropdownValue[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `value` | `readonly GanttDependencyDropdownValue[]` | Yes | — |  |
| `options` | `readonly GanttDependencyDropdownTaskOption[]` | Yes | — |  |

**Related types:** [`GanttDependencyDropdownTaskOption`](/api/gantt/extensions/#ganttdependencydropdowntaskoption), [`GanttDependencyDropdownValue`](/api/gantt/extensions/#ganttdependencydropdownvalue)

## `parseDependencyDropdownDisplayValue`

<span class="api-kind">function</span>

```ts
export function parseDependencyDropdownDisplayValue(displayValue: unknown, options: readonly GanttDependencyDropdownTaskOption[]): GanttDependencyDropdownValue[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `displayValue` | `unknown` | Yes | — |  |
| `options` | `readonly GanttDependencyDropdownTaskOption[]` | Yes | — |  |

**Related types:** [`GanttDependencyDropdownTaskOption`](/api/gantt/extensions/#ganttdependencydropdowntaskoption), [`GanttDependencyDropdownValue`](/api/gantt/extensions/#ganttdependencydropdownvalue)

## `PostgresStatement`

<span class="api-kind">interface</span>

```ts
export interface PostgresStatement {
  readonly text: string;
  readonly values: readonly unknown[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `text` | `string` | Yes | — |  |
| `values` | `readonly unknown[]` | Yes | — |  |

## `printGanttContainer`

<span class="api-kind">function</span>

```ts
export function printGanttContainer(target: Element | null | undefined, options: GanttPrintOptions = {}): GanttPrintResult;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `target` | `Element \| null \| undefined` | Yes | — |  |
| `options` | `GanttPrintOptions` | No | `{}` |  |

**Related types:** [`GanttPrintOptions`](/api/gantt/extensions/#ganttprintoptions), [`GanttPrintResult`](/api/gantt/extensions/#ganttprintresult)

## `PROJECT_SNAPSHOT_TABLE`

<span class="api-kind">constant</span>

```ts
export const PROJECT_SNAPSHOT_TABLE: "gantt_project_snapshots";
```

## `ProjectSnapshotGraphqlAdapter`

<span class="api-kind">class</span>

Framework-neutral example for persisting project snapshots through GraphQL.

```ts
export class ProjectSnapshotGraphqlAdapter {
  constructor(private readonly options: ProjectSnapshotGraphqlAdapterOptions);
  load(request: ProjectSnapshotGraphqlRequestOptions = {}): Promise<ProjectSnapshot>;
  save(project: ProjectSnapshot, request: ProjectSnapshotGraphqlRequestOptions = {}): Promise<void>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `fetchImpl` | `typeof fetch` | Yes | — |  |
| `load(request: ProjectSnapshotGraphqlRequestOptions = {})` | `Promise` | Yes | — |  |
| `save(project: ProjectSnapshot, request: ProjectSnapshotGraphqlRequestOptions = {})` | `Promise<void>` | Yes | — |  |
| `execute(request: {     readonly query: string;     readonly variables?: Readonly<Record<string, unknown>>;     readonly signal?: AbortSignal;   })` | `Promise` | Yes | — |  |
| `request(run: () => Promise)` | `Promise` | Yes | — |  |
| `readPayload(response: Response)` | `Promise` | Yes | — |  |

**Related types:** [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ProjectSnapshotGraphqlAdapterOptions`](/api/gantt/extensions/#projectsnapshotgraphqladapteroptions), [`ProjectSnapshotGraphqlRequestOptions`](/api/gantt/extensions/#projectsnapshotgraphqlrequestoptions)

## `ProjectSnapshotGraphqlAdapterOptions`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotGraphqlAdapterOptions {
  /** GraphQL HTTP endpoint. */
  readonly url: string;
  /** Optional headers for authentication, tenancy, or content negotiation. */
  readonly headers?: Readonly<Record<string, string>>;
  /** Custom fetch implementation for tests, SSR, or framework adapters. */
  readonly fetchImpl?: typeof fetch;
  /** JSON indentation used for readable save payloads. */
  readonly space?: number | string;
  /** Query used by load(). Must return a serialized project snapshot string. */
  readonly loadQuery?: string;
  /** Mutation used by save(). Receives the serialized snapshot in `$snapshot`. */
  readonly saveMutation?: string;
  /** Response data field read by load(). */
  readonly loadField?: string;
  /** Response data field checked by save(). */
  readonly saveField?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `url` | `string` | Yes | — | GraphQL HTTP endpoint. |
| `headers` | `Readonly<Record<string, string>> \| undefined` | No | — | Optional headers for authentication, tenancy, or content negotiation. |
| `fetchImpl` | `typeof fetch \| undefined` | No | — | Custom fetch implementation for tests, SSR, or framework adapters. |
| `space` | `string \| number \| undefined` | No | — | JSON indentation used for readable save payloads. |
| `loadQuery` | `string \| undefined` | No | — | Query used by load(). Must return a serialized project snapshot string. |
| `saveMutation` | `string \| undefined` | No | — | Mutation used by save(). Receives the serialized snapshot in `$snapshot`. |
| `loadField` | `string \| undefined` | No | — | Response data field read by load(). |
| `saveField` | `string \| undefined` | No | — | Response data field checked by save(). |

## `ProjectSnapshotGraphqlError`

<span class="api-kind">class</span>

```ts
export class ProjectSnapshotGraphqlError extends Error {
  constructor(public readonly code: ProjectSnapshotGraphqlErrorCode, message: string, public readonly details: ProjectSnapshotGraphqlErrorDetails = {});
}
```

**Related types:** [`ProjectSnapshotGraphqlErrorCode`](/api/gantt/extensions/#projectsnapshotgraphqlerrorcode), [`ProjectSnapshotGraphqlErrorDetails`](/api/gantt/extensions/#projectsnapshotgraphqlerrordetails)

## `ProjectSnapshotGraphqlErrorCode`

<span class="api-kind">type</span>

```ts
export type ProjectSnapshotGraphqlErrorCode =
  | 'GRAPHQL_ERROR'
  | 'HTTP_ERROR'
  | 'INVALID_RESPONSE'
  | 'INVALID_SNAPSHOT'
  | 'NETWORK_ERROR';
```

## `ProjectSnapshotGraphqlErrorDetails`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotGraphqlErrorDetails {
  readonly status?: number;
  readonly payload?: unknown;
  readonly cause?: unknown;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `status` | `number \| undefined` | No | — |  |
| `payload` | `unknown` | No | — |  |
| `cause` | `unknown` | No | — |  |

## `ProjectSnapshotGraphqlRequestOptions`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotGraphqlRequestOptions {
  readonly signal?: AbortSignal;
  readonly variables?: Readonly<Record<string, unknown>>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `signal` | `AbortSignal \| undefined` | No | — |  |
| `variables` | `Readonly<Record<string, unknown>> \| undefined` | No | — |  |

## `ProjectSnapshotJsonRecipe`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotJsonRecipe {
  readonly metadata: GanttPersistenceRecipeMetadata;
  clone(project: ProjectSnapshot): ProjectSnapshot;
  export(project: ProjectSnapshot, space?: number | string): string;
  parse(json: string): ProjectSnapshotParseResult;
  load(): Promise<ProjectSnapshot>;
  save(project: ProjectSnapshot, space?: number | string): Promise<string>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `metadata` | `GanttPersistenceRecipeMetadata` | Yes | — |  |
| `clone(project: ProjectSnapshot)` | `ProjectSnapshot` | Yes | — |  |
| `export(project: ProjectSnapshot, space?: number \| string)` | `string` | Yes | — |  |
| `parse(json: string)` | `ProjectSnapshotParseResult` | Yes | — |  |
| `load()` | `Promise` | Yes | — |  |
| `save(project: ProjectSnapshot, space?: number \| string)` | `Promise<string>` | Yes | — |  |

**Related types:** [`GanttPersistenceRecipeMetadata`](/api/gantt/extensions/#ganttpersistencerecipemetadata), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ProjectSnapshotParseResult`](/api/gantt/data-model/#projectsnapshotparseresult)

## `ProjectSnapshotJsonRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotJsonRecipeOptions {
  readonly readText?: () => string | Promise<string>;
  readonly writeText?: (fileName: string, contents: string) => void | Promise<void>;
  readonly fileName?: (project: ProjectSnapshot) => string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `readText` | `(() => string \| Promise<string>) \| undefined` | No | — |  |
| `writeText` | `((fileName: string, contents: string) => void \| Promise<void>) \| undefined` | No | — |  |
| `fileName` | `((project: ProjectSnapshot) => string) \| undefined` | No | — |  |

**Related types:** [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)

## `ProjectSnapshotPersistenceRecipe`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotPersistenceRecipe {
  readonly metadata: GanttPersistenceRecipeMetadata;
  load(request?: ProjectSnapshotRestRequestOptions | ProjectSnapshotGraphqlRequestOptions): Promise<ProjectSnapshot>;
  save(request?: ProjectSnapshotRestRequestOptions | ProjectSnapshotGraphqlRequestOptions): Promise<void>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `metadata` | `GanttPersistenceRecipeMetadata` | Yes | — |  |
| `load(request?: ProjectSnapshotRestRequestOptions \| ProjectSnapshotGraphqlRequestOptions)` | `Promise` | Yes | — |  |
| `save(request?: ProjectSnapshotRestRequestOptions \| ProjectSnapshotGraphqlRequestOptions)` | `Promise<void>` | Yes | — |  |

**Related types:** [`GanttPersistenceRecipeMetadata`](/api/gantt/extensions/#ganttpersistencerecipemetadata), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ProjectSnapshotGraphqlRequestOptions`](/api/gantt/extensions/#projectsnapshotgraphqlrequestoptions), [`ProjectSnapshotRestRequestOptions`](/api/gantt/extensions/#projectsnapshotrestrequestoptions)

## `ProjectSnapshotPostgresError`

<span class="api-kind">class</span>

```ts
export class ProjectSnapshotPostgresError extends Error {
  constructor(public readonly code: ProjectSnapshotPostgresErrorCode, message: string, public readonly details: ProjectSnapshotPostgresErrorDetails = {});
}
```

**Related types:** [`ProjectSnapshotPostgresErrorCode`](/api/gantt/extensions/#projectsnapshotpostgreserrorcode), [`ProjectSnapshotPostgresErrorDetails`](/api/gantt/extensions/#projectsnapshotpostgreserrordetails)

## `ProjectSnapshotPostgresErrorCode`

<span class="api-kind">type</span>

```ts
export type ProjectSnapshotPostgresErrorCode =
  | 'INVALID_IDENTIFIER'
  | 'INVALID_SNAPSHOT'
  | 'QUERY_ERROR';
```

## `ProjectSnapshotPostgresErrorDetails`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotPostgresErrorDetails {
  readonly cause?: unknown;
  readonly payload?: unknown;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `cause` | `unknown` | No | — |  |
| `payload` | `unknown` | No | — |  |

## `ProjectSnapshotPostgresOptions`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotPostgresOptions {
  readonly tableName?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `tableName` | `string \| undefined` | No | — |  |

## `ProjectSnapshotPostgresRecipe`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotPostgresRecipe {
  readonly metadata: GanttPersistenceRecipeMetadata;
  createTable(): Promise<void>;
  load(projectId: string): Promise<ProjectSnapshot | null>;
  save(): Promise<ProjectSnapshot>;
  buildReportingStatement(projectId: string): PostgresStatement;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `metadata` | `GanttPersistenceRecipeMetadata` | Yes | — |  |
| `createTable()` | `Promise<void>` | Yes | — |  |
| `load(projectId: string)` | `Promise` | Yes | — |  |
| `save()` | `Promise` | Yes | — |  |
| `buildReportingStatement(projectId: string)` | `PostgresStatement` | Yes | — |  |

**Related types:** [`GanttPersistenceRecipeMetadata`](/api/gantt/extensions/#ganttpersistencerecipemetadata), [`PostgresStatement`](/api/gantt/extensions/#postgresstatement), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)

## `ProjectSnapshotPostgresRow`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotPostgresRow {
  readonly project_id: string;
  readonly version: string;
  readonly snapshot: unknown;
  readonly updated_at: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `project_id` | `string` | Yes | — |  |
| `version` | `string` | Yes | — |  |
| `snapshot` | `unknown` | Yes | — |  |
| `updated_at` | `string` | Yes | — |  |

## `ProjectSnapshotRestAdapter`

<span class="api-kind">class</span>

Framework-neutral example for persisting project snapshots through REST.

```ts
export class ProjectSnapshotRestAdapter {
  constructor(private readonly options: ProjectSnapshotRestAdapterOptions);
  load(request: ProjectSnapshotRestRequestOptions = {}): Promise<ProjectSnapshot>;
  save(project: ProjectSnapshot, request: ProjectSnapshotRestRequestOptions = {}): Promise<void>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `fetchImpl` | `typeof fetch` | Yes | — |  |
| `load(request: ProjectSnapshotRestRequestOptions = {})` | `Promise` | Yes | — |  |
| `save(project: ProjectSnapshot, request: ProjectSnapshotRestRequestOptions = {})` | `Promise<void>` | Yes | — |  |
| `request(run: () => Promise)` | `Promise` | Yes | — |  |
| `assertOk(response: Response)` | `Promise<void>` | Yes | — |  |

**Related types:** [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ProjectSnapshotRestAdapterOptions`](/api/gantt/extensions/#projectsnapshotrestadapteroptions), [`ProjectSnapshotRestRequestOptions`](/api/gantt/extensions/#projectsnapshotrestrequestoptions)

## `ProjectSnapshotRestAdapterOptions`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotRestAdapterOptions {
  /** Endpoint that returns and accepts a serialized project snapshot. */
  readonly url: string;
  /** Optional headers for authentication, tenancy, or content negotiation. */
  readonly headers?: Readonly<Record<string, string>>;
  /** Custom fetch implementation for tests, SSR, or framework adapters. */
  readonly fetchImpl?: typeof fetch;
  /** JSON indentation used for readable save payloads. */
  readonly space?: number | string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `url` | `string` | Yes | — | Endpoint that returns and accepts a serialized project snapshot. |
| `headers` | `Readonly<Record<string, string>> \| undefined` | No | — | Optional headers for authentication, tenancy, or content negotiation. |
| `fetchImpl` | `typeof fetch \| undefined` | No | — | Custom fetch implementation for tests, SSR, or framework adapters. |
| `space` | `string \| number \| undefined` | No | — | JSON indentation used for readable save payloads. |

## `ProjectSnapshotRestError`

<span class="api-kind">class</span>

```ts
export class ProjectSnapshotRestError extends Error {
  constructor(public readonly code: ProjectSnapshotRestErrorCode, message: string, public readonly details: ProjectSnapshotRestErrorDetails = {});
}
```

**Related types:** [`ProjectSnapshotRestErrorCode`](/api/gantt/extensions/#projectsnapshotresterrorcode), [`ProjectSnapshotRestErrorDetails`](/api/gantt/extensions/#projectsnapshotresterrordetails)

## `ProjectSnapshotRestErrorCode`

<span class="api-kind">type</span>

```ts
export type ProjectSnapshotRestErrorCode =
  | 'HTTP_ERROR'
  | 'INVALID_SNAPSHOT'
  | 'NETWORK_ERROR';
```

## `ProjectSnapshotRestErrorDetails`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotRestErrorDetails {
  readonly status?: number;
  readonly payload?: unknown;
  readonly cause?: unknown;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `status` | `number \| undefined` | No | — |  |
| `payload` | `unknown` | No | — |  |
| `cause` | `unknown` | No | — |  |

## `ProjectSnapshotRestRequestOptions`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotRestRequestOptions {
  readonly signal?: AbortSignal;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `signal` | `AbortSignal \| undefined` | No | — |  |

## `ProjectSnapshotSqlExecutor`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotSqlExecutor {
  query<T>(statement: PostgresStatement): Promise<{ readonly rows: readonly T[] }>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `query(statement: PostgresStatement)` | `Promise<{ readonly rows: readonly T[] }>` | Yes | — |  |

**Related types:** [`PostgresStatement`](/api/gantt/extensions/#postgresstatement)

## `ProjectSnapshotState`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotState {
  getProject(): ProjectSnapshot;
  setProject(project: ProjectSnapshot): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `getProject()` | `ProjectSnapshot` | Yes | — |  |
| `setProject(project: ProjectSnapshot)` | `void` | Yes | — |  |

**Related types:** [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)

## `ProjectSnapshotStorageRecipe`

<span class="api-kind">interface</span>

```ts
export interface ProjectSnapshotStorageRecipe {
  readonly metadata: GanttPersistenceRecipeMetadata;
  load(projectId: string): Promise<ProjectSnapshot | null>;
  save(): Promise<ProjectSnapshot>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `metadata` | `GanttPersistenceRecipeMetadata` | Yes | — |  |
| `load(projectId: string)` | `Promise` | Yes | — |  |
| `save()` | `Promise` | Yes | — |  |

**Related types:** [`GanttPersistenceRecipeMetadata`](/api/gantt/extensions/#ganttpersistencerecipemetadata), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot)

## `ProjectSnapshotSupabaseAdapter`

<span class="api-kind">class</span>

Framework-neutral Supabase-style example for storing ProjectSnapshot JSON.
The client shape is intentionally local and minimal, so no Supabase package is
required by the Gantt package or by consumers using another data client.

```ts
export class ProjectSnapshotSupabaseAdapter {
  constructor(private readonly client: SupabaseLikeClient<ProjectSnapshotPostgresRow>, private readonly options: ProjectSnapshotPostgresOptions = {});
  load(projectId: string): Promise<ProjectSnapshot | null>;
  save(project: ProjectSnapshot): Promise<ProjectSnapshot>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `load(projectId: string)` | `Promise` | Yes | — |  |
| `save(project: ProjectSnapshot)` | `Promise` | Yes | — |  |

**Related types:** [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ProjectSnapshotPostgresOptions`](/api/gantt/extensions/#projectsnapshotpostgresoptions), [`ProjectSnapshotPostgresRow`](/api/gantt/extensions/#projectsnapshotpostgresrow), [`SupabaseLikeClient`](/api/gantt/extensions/#supabaselikeclient)

## `resolveHiddenColumnsFromToolbarSelection`

<span class="api-kind">function</span>

```ts
export function resolveHiddenColumnsFromToolbarSelection(selectedValues: string | string[], allProps: string[], previousHiddenColumns: string[]): string[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `selectedValues` | `string \| string[]` | Yes | — |  |
| `allProps` | `string[]` | Yes | — |  |
| `previousHiddenColumns` | `string[]` | Yes | — |  |

## `ResourceOverallocationSummaryRecipe`

<span class="api-kind">interface</span>

```ts
export interface ResourceOverallocationSummaryRecipe {
  readonly summary: ResourceOverallocationSummary;
  readonly hasOverallocations: boolean;
  readonly badgeLabel: string;
  readonly worstResourceId: string | null;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `summary` | `ResourceOverallocationSummary` | Yes | — |  |
| `hasOverallocations` | `boolean` | Yes | — |  |
| `badgeLabel` | `string` | Yes | — |  |
| `worstResourceId` | `string \| null` | Yes | — |  |

## `RevoGridCsvExportPlugin`

<span class="api-kind">interface</span>

```ts
export interface RevoGridCsvExportPlugin {
  exportFile(options?: GanttCsvExportOptions): Promise<void>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `exportFile(options?: GanttCsvExportOptions)` | `Promise<void>` | Yes | — |  |

**Related types:** [`GanttCsvExportOptions`](/api/gantt/extensions/#ganttcsvexportoptions)

## `RoleGuardValidatorOptions`

<span class="api-kind">interface</span>

```ts
export interface RoleGuardValidatorOptions<TContext extends GanttValidationContext> {
  readonly policy: GanttRoleEditabilityPolicy;
  readonly getRoleContext?: (
    detail: GanttBeforeTaskChangeDetail,
    context: TContext,
  ) => GanttRoleEditabilityContext;
  readonly message?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `policy` | `GanttRoleEditabilityPolicy` | Yes | — |  |
| `getRoleContext` | `((detail: GanttBeforeTaskChangeDetail, context: TContext) => GanttRoleEditabilityContext) \| undefined` | No | — |  |
| `message` | `string \| undefined` | No | — |  |

**Related types:** [`GanttBeforeTaskChangeDetail`](/api/gantt/events/#ganttbeforetaskchangedetail), [`GanttValidationContext`](/api/gantt/extensions/#ganttvalidationcontext)

## `scrollGanttToToday`

<span class="api-kind">function</span>

```ts
export function scrollGanttToToday(grid: HTMLRevoGridElement, options: GanttTodayNavigationOptions = {}): Promise<boolean>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |
| `options` | `GanttTodayNavigationOptions` | No | `{}` |  |

**Related types:** [`GanttTodayNavigationOptions`](/api/gantt/extensions/#gantttodaynavigationoptions)

## `SupabaseLikeClient`

<span class="api-kind">interface</span>

```ts
export interface SupabaseLikeClient<T> {
  from(table: string): SupabaseLikeTable<T>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `from(table: string)` | `SupabaseLikeTable` | Yes | — |  |

**Related types:** [`SupabaseLikeTable`](/api/gantt/extensions/#supabaseliketable)

## `SupabaseLikeError`

<span class="api-kind">interface</span>

```ts
export interface SupabaseLikeError {
  readonly message: string;
  readonly code?: string;
  readonly details?: string;
  readonly hint?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `message` | `string` | Yes | — |  |
| `code` | `string \| undefined` | No | — |  |
| `details` | `string \| undefined` | No | — |  |
| `hint` | `string \| undefined` | No | — |  |

## `SupabaseLikeFilterBuilder`

<span class="api-kind">interface</span>

```ts
export interface SupabaseLikeFilterBuilder<T> {
  eq(column: string, value: unknown): SupabaseLikeMaybeSingleQuery<T>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `eq(column: string, value: unknown)` | `SupabaseLikeMaybeSingleQuery` | Yes | — |  |

**Related types:** [`SupabaseLikeMaybeSingleQuery`](/api/gantt/extensions/#supabaselikemaybesinglequery)

## `SupabaseLikeMaybeSingleQuery`

<span class="api-kind">interface</span>

```ts
export interface SupabaseLikeMaybeSingleQuery<T> {
  maybeSingle(): Promise<SupabaseLikeResult<T | null>>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `maybeSingle()` | `Promise<SupabaseLikeResult>` | Yes | — |  |

**Related types:** [`SupabaseLikeResult`](/api/gantt/extensions/#supabaselikeresult)

## `SupabaseLikeResult`

<span class="api-kind">interface</span>

```ts
export interface SupabaseLikeResult<T> {
  readonly data: T;
  readonly error: SupabaseLikeError | null;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `data` | `T` | Yes | — |  |
| `error` | `SupabaseLikeError \| null` | Yes | — |  |

**Related types:** [`SupabaseLikeError`](/api/gantt/extensions/#supabaselikeerror)

## `SupabaseLikeSingleQuery`

<span class="api-kind">interface</span>

```ts
export interface SupabaseLikeSingleQuery<T> {
  single(): Promise<SupabaseLikeResult<T>>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `single()` | `Promise<SupabaseLikeResult>` | Yes | — |  |

**Related types:** [`SupabaseLikeResult`](/api/gantt/extensions/#supabaselikeresult)

## `SupabaseLikeTable`

<span class="api-kind">interface</span>

```ts
export interface SupabaseLikeTable<T> {
  select(columns?: string): SupabaseLikeFilterBuilder<T>;
  upsert(row: T, options?: { readonly onConflict?: string }): SupabaseLikeUpsertBuilder<T>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `select(columns?: string)` | `SupabaseLikeFilterBuilder` | Yes | — |  |
| `upsert(row: T, options?: { readonly onConflict?: string })` | `SupabaseLikeUpsertBuilder` | Yes | — |  |

**Related types:** [`SupabaseLikeFilterBuilder`](/api/gantt/extensions/#supabaselikefilterbuilder), [`SupabaseLikeUpsertBuilder`](/api/gantt/extensions/#supabaselikeupsertbuilder)

## `SupabaseLikeUpsertBuilder`

<span class="api-kind">interface</span>

```ts
export interface SupabaseLikeUpsertBuilder<T> {
  select(columns?: string): SupabaseLikeSingleQuery<T>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `select(columns?: string)` | `SupabaseLikeSingleQuery` | Yes | — |  |

**Related types:** [`SupabaseLikeSingleQuery`](/api/gantt/extensions/#supabaselikesinglequery)

## `TaskDetailPopoverRecipe`

<span class="api-kind">interface</span>

```ts
export interface TaskDetailPopoverRecipe {
  readonly model: TaskDetailPopoverModel;
  readonly sectionTitles: readonly string[];
  readonly warningMessages: readonly string[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `model` | `TaskDetailPopoverModel` | Yes | — |  |
| `sectionTitles` | `readonly string[]` | Yes | — |  |
| `warningMessages` | `readonly string[]` | Yes | — |  |

## `TaskDetailPopoverRecipeOptions`

<span class="api-kind">interface</span>

```ts
export interface TaskDetailPopoverRecipeOptions {
  readonly row: GanttGridRow;
  readonly task?: TaskEntity;
  readonly resources?: readonly ResourceEntity[];
  readonly assignments?: readonly AssignmentEntity[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `row` | `GanttGridRow` | Yes | — |  |
| `task` | `TaskEntity \| undefined` | No | — |  |
| `resources` | `readonly ResourceEntity[] \| undefined` | No | — |  |
| `assignments` | `readonly AssignmentEntity[] \| undefined` | No | — |  |

**Related types:** [`AssignmentEntity`](/api/gantt/data-model/#assignmententity), [`GanttGridRow`](/api/gantt/columns/#ganttgridrow), [`ResourceEntity`](/api/gantt/data-model/#resourceentity), [`TaskEntity`](/api/gantt/data-model/#taskentity)

## `toggleGanttCriticalPath`

<span class="api-kind">function</span>

Toggle critical-path highlighting on the grid's Gantt visual config.

Returns the next visibility state, or `undefined` when the grid has no
Gantt config to update.

```ts
export function toggleGanttCriticalPath(grid: HTMLRevoGridElement): boolean | undefined;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `grid` | `HTMLRevoGridElement` | Yes | — |  |

## `toProjectSnapshotRow`

<span class="api-kind">function</span>

```ts
export function toProjectSnapshotRow(project: ProjectSnapshot): ProjectSnapshotPostgresRow;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `ProjectSnapshot` | Yes | — |  |

**Related types:** [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ProjectSnapshotPostgresRow`](/api/gantt/extensions/#projectsnapshotpostgresrow)

---

# Plugin And Configuration

URL: https://pro.rv-grid.com/api/gantt/plugin/
Source: src/content/docs/api/gantt/plugin.md
Description: Public RevoGrid Gantt API for plugin and configuration.
Surface: gantt

This page documents 74 public symbols exported by `@revolist/gantt`.

## `createGanttDateAdapter`

<span class="api-kind">function</span>

Creates the project-aware adapter used by managed Gantt date columns.

```ts
export function createGanttDateAdapter(getProject: () => GanttPluginConfig | null | undefined, field: string): GanttDateAdapter;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `getProject` | `() => GanttPluginConfig \| null \| undefined` | Yes | — |  |
| `field` | `string` | Yes | — |  |

**Related types:** [`GanttDateAdapter`](/api/gantt/plugin/#ganttdateadapter), [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig)

## `createGanttDateFormatContext`

<span class="api-kind">function</span>

```ts
export function createGanttDateFormatContext(project: Pick<GanttPluginConfig, 'timeZone' | 'dateFormats'> | null | undefined, surface: GanttDateFormatSurface, field?: string, fallbackLocale = 'en-US'): GanttDateFormatContext;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `Pick<GanttPluginConfig, "timeZone" \| "dateFormats"> \| null \| undefined` | Yes | — |  |
| `surface` | `GanttDateFormatSurface` | Yes | — |  |
| `field` | `string \| undefined` | No | — |  |
| `fallbackLocale` | `string` | No | `'en-US'` |  |

**Related types:** [`GanttDateFormatContext`](/api/gantt/plugin/#ganttdateformatcontext), [`GanttDateFormatSurface`](/api/gantt/plugin/#ganttdateformatsurface), [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig)

## `createTaskGridConfig`

<span class="api-kind">function</span>

One-shot helper that runs the scheduling engine_and_ builds the full grid
configuration (scale + projected rows) in a single call.

```ts
export function createTaskGridConfig(project: ProjectSnapshot, taskStore: TaskStore, resourceStore: ResourceStore, assignmentStore: AssignmentStore, zoomLevel: TimelineZoomLevel | TimelineZoomPreset, schedulerEngine: SchedulerEngine = createSchedulerEngine(), locale = 'en-US', defaultHeaderFormatter?: TimelineDateFormatter, projectionOptions: TaskRowProjectionOptions = {}, scaleOptions: TaskGridScaleOptions = {}): TaskGridConfig;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `ProjectSnapshot` | Yes | — | - The resolved project snapshot. |
| `taskStore` | `TaskStore` | Yes | — | - Task store instance. |
| `resourceStore` | `ResourceStore` | Yes | — | - Resource store instance. |
| `assignmentStore` | `AssignmentStore` | Yes | — | - Assignment store instance. |
| `zoomLevel` | `TimelineZoomLevel \| TimelineZoomPreset` | Yes | — | - Zoom level descriptor or named preset. |
| `schedulerEngine` | `SchedulerEngine` | No | `createSchedulerEngine()` | - Optional pre-configured scheduler engine. |
| `locale` | `string` | No | `'en-US'` | - BCP 47 locale tag (default `"en-US"`). |
| `defaultHeaderFormatter` | `TimelineDateFormatter \| undefined` | No | — | - Optional custom header formatter. |
| `projectionOptions` | `TaskRowProjectionOptions` | No | `{}` | - Optional row projection overrides. |
| `scaleOptions` | `TaskGridScaleOptions` | No | `{}` |  |

**Returns:** A complete `TaskGridConfig`.

**Related types:** [`AssignmentStore`](/api/gantt/data-model/#assignmentstore), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ResourceStore`](/api/gantt/data-model/#resourcestore), [`SchedulerEngine`](/api/gantt/scheduling/#schedulerengine), [`TaskGridConfig`](/api/gantt/plugin/#taskgridconfig), [`TaskGridScaleOptions`](/api/gantt/plugin/#taskgridscaleoptions), [`TaskRowProjectionOptions`](/api/gantt/visuals/#taskrowprojectionoptions), [`TaskStore`](/api/gantt/data-model/#taskstore), [`TimelineDateFormatter`](/api/gantt/visuals/#timelinedateformatter), [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel), [`TimelineZoomPreset`](/api/gantt/columns/#timelinezoompreset)

## `createTaskGridScaleConfig`

<span class="api-kind">function</span>

Build the timeline scale configuration from a scheduling result and zoom
level.

Determines the visible date range, creates the timeline scale, and derives
the header rows, ticks, bands, and visible range for the gantt view-model.

```ts
export function createTaskGridScaleConfig(schedulingResult: SchedulingResult, zoomLevelOrPreset: TimelineZoomLevel | TimelineZoomPreset, locale = 'en-US', defaultHeaderFormatter?: TimelineDateFormatter, options: TaskGridScaleOptions = {}): TaskGridScaleConfig;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `schedulingResult` | `SchedulingResult` | Yes | — | - The output of the scheduling engine. |
| `zoomLevelOrPreset` | `TimelineZoomLevel \| TimelineZoomPreset` | Yes | — | - A concrete zoom level descriptor or a named preset string. |
| `locale` | `string` | No | `'en-US'` | - BCP 47 locale tag used for date formatting (default `"en-US"`). |
| `defaultHeaderFormatter` | `TimelineDateFormatter \| undefined` | No | — | - Optional custom formatter for header cell labels. |
| `options` | `TaskGridScaleOptions` | No | `{}` |  |

**Returns:** A `TaskGridScaleConfig` ready for rendering.

**Related types:** [`SchedulingResult`](/api/gantt/scheduling/#schedulingresult), [`TaskGridScaleConfig`](/api/gantt/plugin/#taskgridscaleconfig), [`TaskGridScaleOptions`](/api/gantt/plugin/#taskgridscaleoptions), [`TimelineDateFormatter`](/api/gantt/visuals/#timelinedateformatter), [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel), [`TimelineZoomPreset`](/api/gantt/columns/#timelinezoompreset)

## `createTaskGridSource`

<span class="api-kind">function</span>

Project tasks into grid rows using a pre-built timeline scale.

```ts
export function createTaskGridSource(project: ProjectSnapshot, taskStore: TaskStore, resourceStore: ResourceStore, assignmentStore: AssignmentStore, scale: TimelineScale, schedulingResult: SchedulingResult, projectionOptions: TaskRowProjectionOptions = {}): readonly DataType[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `ProjectSnapshot` | Yes | — | - The resolved project snapshot. |
| `taskStore` | `TaskStore` | Yes | — | - The task store providing the ordered task list. |
| `resourceStore` | `ResourceStore` | Yes | — | - The resource store for resource name lookups. |
| `assignmentStore` | `AssignmentStore` | Yes | — | - The assignment store for task–resource links. |
| `scale` | `TimelineScale` | Yes | — | - The timeline scale used for coordinate projection. |
| `schedulingResult` | `SchedulingResult` | Yes | — | - The scheduling engine output. |
| `projectionOptions` | `TaskRowProjectionOptions` | No | `{}` | - Optional overrides for row projection behaviour. |

**Returns:** An array of data rows suitable for the grid source.

**Related types:** [`AssignmentStore`](/api/gantt/data-model/#assignmentstore), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ResourceStore`](/api/gantt/data-model/#resourcestore), [`SchedulingResult`](/api/gantt/scheduling/#schedulingresult), [`TaskRowProjectionOptions`](/api/gantt/visuals/#taskrowprojectionoptions), [`TaskStore`](/api/gantt/data-model/#taskstore), [`TimelineScale`](/api/gantt/visuals/#timelinescale)

## `DEFAULT_GANTT_ERROR_LABELS`

<span class="api-kind">constant</span>

```ts
export const DEFAULT_GANTT_ERROR_LABELS: { readonly taskEdit: { readonly invalidField: ({ field }: GanttMessageContext) => string; readonly booleanRequired: ({ field }: GanttMessageContext) => string; readonly unsupportedConstraintType: ({ value }: GanttMessageContext) => string; readonly invalidDate: ({ field }: GanttMessageContext) => string; readonly summaryDatesDerived: "Summary task dates are derived from children."; readonly invalidScheduledDate: ({ label }: GanttMessageContext) => string; readonly startAfterEnd: "Start date must not be later than the current computed end date."; readonly endBeforeStart: "End date must not be earlier than the current computed start date."; readonly invalidEffortMode: "Effort mode must be Fixed Duration, Fixed Work, or Fixed Units."; readonly taskNameEmpty: "Task name cannot be empty."; readonly invalidLevelingDelay: "Leveling delay must be a non-negative number."; readonly invalidPriority: "Priority must be a number between 0 and 1000."; readonly summaryProgressDerived: "Summary task progress is derived from children."; readonly invalidPercentDone: "Percent done must be numeric."; readonly statusCalculated: "Task status is calculated from progress, scheduled dates, and the project status date."; readonly invalidWorkflowStatus: "Workflow status must be Not Started, In Progress, Done, or Blocked."; readonly invalidTaskMode: "Task mode must be Auto or Manual."; readonly unsupportedTaskType: ({ value }: GanttMessageContext) => string; readonly disallowedTaskType: ({ value }: GanttMessageContext) => string; readonly summaryDurationDerived: "Summary duration is derived from children."; readonly invalidDuration: "Duration must be a value such as 5h, 2d, 3w, or 30m."; readonly invalidRemainingDuration: "Remaining duration must be a value such as 5h, 2d, 3w, or 30m."; readonly milestoneDurationZero: "Milestone duration is fixed at zero in scheduling v1."; readonly invalidWork: "Work must be a value such as 5h, 2d, 3w, or 30m; elapsed units are not supported."; }; readonly taskMutation: { readonly readOnly: ({ action }: GanttMessageContext) => string; readonly lockedTask: ({ taskId, action }: GanttMessageContext) => string; readonly taskNotFound: ({ taskId, action }: GanttMessageContext) => string; readonly serviceNotConfigured: "Task mutation service is not configured."; readonly invalidDate: ({ date }: GanttMessageContext) => string; readonly invalidRange: "End date must not be earlier than start date."; readonly invalidOptionalDate: ({ label, value }: GanttMessageContext) => string; readonly invalidNonNegativeNumber: ({ label }: GanttMessageContext) => string; readonly invalidBoolean: ({ label }: GanttMessageContext) => string; readonly summaryProgressDerived: "Summary task progress is derived from children."; readonly invalidDuration: "Duration must be a non-negative number."; readonly invalidPriority: "Priority must be a number between 0 and 1000."; readonly unsupportedEffortMode: ({ value }: GanttMessageContext) => string; readonly unsupportedTaskType: ({ value }: GanttMessageContext) => string; readonly nonWorkingDate: ({ date }: GanttMessageContext) => string; readonly actualDateRange: "Actual finish date must not be earlier than actual start date."; readonly firstTaskIndent: "The first task cannot be indented."; readonly firstSiblingIndent: "The first sibling task cannot be indented."; readonly rootTaskOutdent: "Root tasks cannot be outdented."; readonly taskOutdentFailed: ({ taskId }: GanttMessageContext) => string; readonly splitRangesArray: "Split ranges must be an array."; readonly invalidSplitStart: ({ startDate }: GanttMessageContext) => string; readonly invalidSplitEnd: ({ endDate }: GanttMessageContext) => string; readonly invalidSplitRange: "Split end date must not be earlier than split start date."; readonly regularTaskSplitOnly: "Only regular task bars can be split."; readonly splitOverlapRequired: "Split range must overlap the task date range."; readonly regularSplitMoveOnly: "Only regular task split ranges can be moved."; readonly splitNotFound: ({ splitIndex, taskId }: GanttMessageContext) => string; readonly summaryMove: "Summary tasks cannot be moved directly on the timeline."; readonly actualFinishMove: "Tasks with an actual finish date cannot be moved on the timeline."; readonly resizeTaskOnly: "Only non-summary task bars can be resized in this milestone."; readonly noWorkingDays: "Selected range contains no working days."; readonly alreadyMilestone: ({ taskId }: GanttMessageContext) => string; readonly summaryMilestone: "Summary tasks with children cannot be converted to milestones."; }; readonly assignment: { readonly invalidUnitsForResource: ({ resourceId }: GanttMessageContext) => string; readonly invalidWorkForResource: ({ resourceId }: GanttMessageContext) => string; readonly resourceNotFound: ({ resourceName, resourceId }: GanttMessageContext) => string; readonly invalidUnitsForName: ({ resourceName }: GanttMessageContext) => string; readonly serviceNotConfigured: "Assignment mutation service is not configured."; readonly taskNotFound: ({ taskId }: GanttMessageContext) => string; readonly readOnly: ({ action }: GanttMessageContext) => string; readonly editCanceled: "Assignment edit was canceled."; }; readonly dependency: { readonly duplicate: "Dependency already exists."; readonly notFound: ({ dependencyId }: GanttMessageContext) => string; readonly taskNotFound: ({ taskId }: GanttMessageContext) => string; readonly tasksMustExist: "Dependency tasks must exist."; readonly selfReference: "A task cannot depend on itself."; readonly invalidType: ({ dependencyType }: GanttMessageContext) => string; readonly invalidReference: ({ value }: GanttMessageContext) => string; readonly unsupportedReferenceType: ({ value }: GanttMessageContext) => string; readonly taskReferenceNotFound: ({ value }: GanttMessageContext) => string; readonly invalidReferenceValue: "Invalid dependency reference value."; readonly cycle: "Dependency would create a circular relationship."; readonly readOnly: ({ action }: GanttMessageContext) => string; readonly replacementCanceled: "Dependency replacement was canceled."; }; readonly taskEditor: { readonly invalidDate: ({ field }: GanttMessageContext) => string; readonly invalidNonNegativeNumber: ({ field }: GanttMessageContext) => string; readonly invalidRangeNumber: ({ field, min, max }: GanttMessageContext) => string; readonly invalidBoolean: ({ field }: GanttMessageContext) => string; readonly unsupportedField: ({ field }: GanttMessageContext) => string; readonly taskNameEmpty: "Task name cannot be empty."; readonly unsupportedWorkflowStatus: ({ value }: GanttMessageContext) => string; readonly disallowedTaskType: ({ value }: GanttMessageContext) => string; readonly summaryDurationDerived: "Summary duration is derived from children."; readonly invalidDuration: "Duration must be a value such as 5h, 2d, 3w, or 30m."; readonly invalidDateRange: "End date must not be earlier than start date."; readonly unsupportedConstraintType: ({ value }: GanttMessageContext) => string; readonly invalidWork: "Work must be a value such as 5h, 2d, 3w, or 30m; elapsed units are not supported."; readonly invalidRemainingDuration: "Remaining duration must be a value such as 5h, 2d, 3w, or 30m."; readonly unsupportedEffortMode: ({ value }: GanttMessageContext) => string; readonly calendarUnavailable: ({ calendarId }: GanttMessageContext) => string; readonly invalidTags: "Tags must be a comma-separated string or string array."; }; };
```

**Related types:** [`GanttMessageContext`](/api/gantt/plugin/#ganttmessagecontext)

## `DEFAULT_GANTT_WARNING_LABELS`

<span class="api-kind">constant</span>

```ts
export const DEFAULT_GANTT_WARNING_LABELS: { readonly scheduler: { readonly duplicateId: ({ entityName, entityId }: GanttMessageContext) => string; readonly calendarWithoutWorkingDay: ({ calendarId }: GanttMessageContext) => string; readonly invalidWorkingCalendar: ({ calendarId }: GanttMessageContext) => string; readonly invalidTaskConstraint: ({ taskId }: GanttMessageContext) => string; readonly missingTaskCalendar: ({ taskId, calendarId }: GanttMessageContext) => string; readonly invalidTaskDateRange: ({ taskId }: GanttMessageContext) => string; readonly invalidTaskDuration: ({ taskId }: GanttMessageContext) => string; readonly invalidTaskProgress: ({ taskId }: GanttMessageContext) => string; readonly invalidTaskWork: ({ taskId }: GanttMessageContext) => string; readonly invalidTaskPriority: ({ taskId }: GanttMessageContext) => string; readonly missingDependencyTask: ({ dependencyId }: GanttMessageContext) => string; readonly missingResourceCalendar: ({ resourceId, calendarId }: GanttMessageContext) => string; readonly invalidResourceUnits: ({ resourceId }: GanttMessageContext) => string; readonly invalidResourceCost: ({ resourceId }: GanttMessageContext) => string; readonly missingAssignmentTask: ({ assignmentId, taskId }: GanttMessageContext) => string; readonly missingAssignmentResource: ({ assignmentId, resourceId }: GanttMessageContext) => string; readonly invalidAssignmentUnits: ({ assignmentId }: GanttMessageContext) => string; readonly invalidAssignmentWork: ({ assignmentId }: GanttMessageContext) => string; readonly dependencyCycle: "Dependencies contain a cycle."; readonly dependencyConstraint: ({ taskId, constraintType, dependencyId }: GanttMessageContext) => string; readonly hardConstraintOverride: ({ taskId, constraintType }: GanttMessageContext) => string; readonly constraintWindowForward: ({ taskId, constraintType }: GanttMessageContext) => string; readonly constraintWindowBackward: ({ taskId, constraintType }: GanttMessageContext) => string; readonly autoDependencyAdjustment: ({ taskId, startDate, dependencyId }: GanttMessageContext) => string; readonly finishConstraint: ({ taskId, endDate, constraintType, constraintDate }: GanttMessageContext) => string; readonly manualDependencyForward: ({ taskId, dependencyId }: GanttMessageContext) => string; readonly manualDependencyBackward: ({ taskId, dependencyId }: GanttMessageContext) => string; readonly deadlineMissed: ({ taskId, date }: GanttMessageContext) => string; readonly resourceOverallocation: ({ resourceId, date, allocatedUnits, capacityUnits }: GanttMessageContext) => string; readonly storedLevelingDelay: ({ taskId }: GanttMessageContext) => string; readonly resourceLevelingAdjustment: ({ taskId, resourceId }: GanttMessageContext) => string; }; };
```

**Related types:** [`GanttMessageContext`](/api/gantt/plugin/#ganttmessagecontext)

## `formatGanttDateWithOption`

<span class="api-kind">function</span>

```ts
export function formatGanttDateWithOption(value: string | null | undefined, option: GanttDateFormatOption | undefined, context: GanttDateFormatContext): string;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `value` | `string \| null \| undefined` | Yes | — |  |
| `option` | `GanttDateFormatOption \| undefined` | Yes | — |  |
| `context` | `GanttDateFormatContext` | Yes | — |  |

**Related types:** [`GanttDateFormatContext`](/api/gantt/plugin/#ganttdateformatcontext), [`GanttDateFormatOption`](/api/gantt/plugin/#ganttdateformatoption)

## `formatGanttEditorDate`

<span class="api-kind">function</span>

```ts
export function formatGanttEditorDate(value: string | null | undefined, project: Pick<GanttPluginConfig, 'timeZone' | 'dateFormats'> | null | undefined, field?: string): string;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `value` | `string \| null \| undefined` | Yes | — |  |
| `project` | `Pick<GanttPluginConfig, "timeZone" \| "dateFormats"> \| null \| undefined` | Yes | — |  |
| `field` | `string \| undefined` | No | — |  |

**Related types:** [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig)

## `formatGanttTableDate`

<span class="api-kind">function</span>

```ts
export function formatGanttTableDate(value: string | null | undefined, project: Pick<GanttPluginConfig, 'timeZone' | 'dateFormats'> | null | undefined, field?: string): string;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `value` | `string \| null \| undefined` | Yes | — |  |
| `project` | `Pick<GanttPluginConfig, "timeZone" \| "dateFormats"> \| null \| undefined` | Yes | — |  |
| `field` | `string \| undefined` | No | — |  |

**Related types:** [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig)

## `formatGanttTooltipDate`

<span class="api-kind">function</span>

```ts
export function formatGanttTooltipDate(value: string, project: Pick<GanttPluginConfig, 'timeZone' | 'dateFormats'> | null | undefined, field?: string): string;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `value` | `string` | Yes | — |  |
| `project` | `Pick<GanttPluginConfig, "timeZone" \| "dateFormats"> \| null \| undefined` | Yes | — |  |
| `field` | `string \| undefined` | No | — |  |

**Related types:** [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig)

## `GANTT_DEPENDENCY_DROPDOWN_COLUMN_TYPE`

<span class="api-kind">constant</span>

```ts
export const GANTT_DEPENDENCY_DROPDOWN_COLUMN_TYPE: "gantt-dependency-dropdown";
```

## `GanttAssignmentDomainChangeDetail`

<span class="api-kind">interface</span>

Committed assignment mutation exposed through EventManager's `gridedit`.

```ts
export interface GanttAssignmentDomainChangeDetail {
  readonly action: GanttBeforeAssignmentChangeAction;
  readonly taskId: TaskId;
  readonly previousAssignments: readonly AssignmentEntity[];
  readonly assignments: readonly AssignmentEntity[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `action` | `"edit"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `previousAssignments` | `readonly AssignmentEntity[]` | Yes | — |  |
| `assignments` | `readonly AssignmentEntity[]` | Yes | — |  |

**Related types:** [`AssignmentEntity`](/api/gantt/data-model/#assignmententity), [`GanttBeforeAssignmentChangeAction`](/api/gantt/events/#ganttbeforeassignmentchangeaction), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttAssignmentErrorLabelKey`

<span class="api-kind">type</span>

```ts
export type GanttAssignmentErrorLabelKey =
  | 'invalidUnitsForResource'
  | 'invalidWorkForResource'
  | 'resourceNotFound'
  | 'invalidUnitsForName'
  | 'serviceNotConfigured'
  | 'taskNotFound'
  | 'readOnly'
  | 'editCanceled';
```

## `GanttColorPaletteConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttColorPaletteConfig {
  /** Replace the shared default palette with these options. */
  readonly options?: readonly ColorPaletteOption[];
  /** Append options to either `options` or the shared default palette. */
  readonly extendOptions?: readonly ColorPaletteOption[];
  /** Disable every palette choice while retaining the visible submenu. */
  readonly disabled?: boolean;
  /** Configure the inherited/default choice, or set to `false` to remove it. */
  readonly defaultOption?: false | {
    readonly label?: string;
    readonly disabled?: boolean;
  };
  /** Accessible label resolver for individual swatches. */
  readonly colorAriaLabel?: (option: ColorPaletteOption) => string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `options` | `readonly ColorPaletteOption[] \| undefined` | No | — | Replace the shared default palette with these options. |
| `extendOptions` | `readonly ColorPaletteOption[] \| undefined` | No | — | Append options to either `options` or the shared default palette. |
| `disabled` | `boolean \| undefined` | No | — | Disable every palette choice while retaining the visible submenu. |
| `defaultOption` | `false \| { readonly label?: string; readonly disabled?: boolean; } \| undefined` | No | — | Configure the inherited/default choice, or set to `false` to remove it. |
| `colorAriaLabel` | `((option: ColorPaletteOption) => string) \| undefined` | No | — | Accessible label resolver for individual swatches. |

## `GanttConstraintTypeLabelValue`

<span class="api-kind">type</span>

```ts
export type GanttConstraintTypeLabelValue = '' | TaskConstraintType;
```

**Related types:** [`TaskConstraintType`](/api/gantt/data-model/#taskconstrainttype)

## `GanttConstraintTypeOption`

<span class="api-kind">type</span>

```ts
export type GanttConstraintTypeOption = '' | TaskConstraintType;
```

**Related types:** [`TaskConstraintType`](/api/gantt/data-model/#taskconstrainttype)

## `GanttContextMenuConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttContextMenuConfig {
  /**
   * Enables generated task row and task bar actions such as Add, Indent,
   * Outdent, and Delete. Defaults to `true`.
   */
  readonly row?: boolean;
  /**
   * Enables generated task-table column actions and pinned timeline zoom
   * actions. Defaults to `true`.
   */
  readonly column?: boolean;
  /** Label overrides for built-in Gantt context-menu items. */
  readonly labels?: GanttContextMenuLabels;
  /** Hide specific built-in Gantt context-menu items by id or task-aware predicate. */
  readonly hidden?: GanttContextMenuHiddenItems;
  /** Disable specific built-in items while keeping them visible, optionally per targeted task. */
  readonly disabled?: GanttContextMenuDisabledItems;
  /** Shared task-color submenu configuration. Set to `false` to remove color editing. */
  readonly colorPalette?: GanttColorPaletteConfig | false;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `row` | `boolean \| undefined` | No | — | Enables generated task row and task bar actions such as Add, Indent, Outdent, and Delete. Defaults to `true`. |
| `column` | `boolean \| undefined` | No | — | Enables generated task-table column actions and pinned timeline zoom actions. Defaults to `true`. |
| `labels` | `Partial<Record<GanttContextMenuItemId, string>> \| undefined` | No | — | Label overrides for built-in Gantt context-menu items. |
| `hidden` | `Partial<Record<GanttContextMenuItemId, GanttContextMenuItemState>> \| undefined` | No | — | Hide specific built-in Gantt context-menu items by id or task-aware predicate. |
| `disabled` | `Partial<Record<GanttContextMenuItemId, GanttContextMenuItemState>> \| undefined` | No | — | Disable specific built-in items while keeping them visible, optionally per targeted task. |
| `colorPalette` | `false \| GanttColorPaletteConfig \| undefined` | No | — | Shared task-color submenu configuration. Set to `false` to remove color editing. |

**Related types:** [`GanttColorPaletteConfig`](/api/gantt/plugin/#ganttcolorpaletteconfig), [`GanttContextMenuDisabledItems`](/api/gantt/plugin/#ganttcontextmenudisableditems), [`GanttContextMenuHiddenItems`](/api/gantt/plugin/#ganttcontextmenuhiddenitems), [`GanttContextMenuLabels`](/api/gantt/plugin/#ganttcontextmenulabels)

## `GanttContextMenuDisabledItems`

<span class="api-kind">type</span>

```ts
export type GanttContextMenuDisabledItems = Partial<Record<GanttContextMenuItemId, GanttContextMenuItemState>>;
```

**Related types:** [`GanttContextMenuItemId`](/api/gantt/plugin/#ganttcontextmenuitemid), [`GanttContextMenuItemState`](/api/gantt/plugin/#ganttcontextmenuitemstate)

## `GanttContextMenuHiddenItems`

<span class="api-kind">type</span>

```ts
export type GanttContextMenuHiddenItems = Partial<Record<GanttContextMenuItemId, GanttContextMenuItemState>>;
```

**Related types:** [`GanttContextMenuItemId`](/api/gantt/plugin/#ganttcontextmenuitemid), [`GanttContextMenuItemState`](/api/gantt/plugin/#ganttcontextmenuitemstate)

## `GanttContextMenuItemId`

<span class="api-kind">type</span>

```ts
export type GanttContextMenuItemId =
  | 'edit'
  | 'add'
  | 'addTaskAbove'
  | 'addTaskBelow'
  | 'addMilestone'
  | 'addSubtask'
  | 'addSuccessor'
  | 'addPredecessor'
  | 'convertToMilestone'
  | 'indent'
  | 'outdent'
  | 'color'
  | 'delete'
  | 'search'
  | 'sortAsc'
  | 'sortDesc'
  | 'filter'
  | 'hideColumn'
  | 'columns'
  | 'zoom'
  | 'dateRange'
  | 'showToday'
  | 'showFlags'
  /** @deprecated Configure the `zoom` item instead. */
  | 'zoomIn'
  /** @deprecated Configure the `zoom` item instead. */
  | 'zoomOut';
```

## `GanttContextMenuItemState`

<span class="api-kind">type</span>

```ts
export type GanttContextMenuItemState = boolean | ((context: GanttContextMenuItemStateContext) => boolean);
```

**Related types:** [`GanttContextMenuItemStateContext`](/api/gantt/plugin/#ganttcontextmenuitemstatecontext)

## `GanttContextMenuItemStateContext`

<span class="api-kind">interface</span>

```ts
export interface GanttContextMenuItemStateContext {
  /** Built-in item currently being evaluated. */
  readonly itemId: GanttContextMenuItemId;
  /** Tasks targeted by the menu invocation. */
  readonly taskIds: readonly TaskId[];
  /** Resolved tasks for the target ids. */
  readonly tasks: readonly TaskEntity[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `itemId` | `GanttContextMenuItemId` | Yes | — | Built-in item currently being evaluated. |
| `taskIds` | `readonly string[]` | Yes | — | Tasks targeted by the menu invocation. |
| `tasks` | `readonly TaskEntity[]` | Yes | — | Resolved tasks for the target ids. |

**Related types:** [`GanttContextMenuItemId`](/api/gantt/plugin/#ganttcontextmenuitemid), [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttContextMenuLabels`

<span class="api-kind">type</span>

```ts
export type GanttContextMenuLabels = Partial<Record<GanttContextMenuItemId, string>>;
```

**Related types:** [`GanttContextMenuItemId`](/api/gantt/plugin/#ganttcontextmenuitemid)

## `GanttCreateTaskOptions`

<span class="api-kind">interface</span>

Options for programmatic task creation via the
{@link GANTT_TASK_CREATE_EVENT} event.

```ts
export interface GanttCreateTaskOptions {
  /** Parent task id, or `null` for a root-level task. */
  readonly parentId?: TaskId | null;
  /** Insert the new task after this sibling. */
  readonly insertAfterTaskId?: TaskId | null;
  /** Insert the task before this sibling. Mutually exclusive with `insertAfterTaskId`. */
  readonly insertBeforeTaskId?: TaskId | null;
  /** Initial canonical task type. Defaults to `task`. */
  readonly type?: TaskType;
  /** Initial start date. */
  readonly startDate?: ISODateString;
  /** Initial end date. */
  readonly endDate?: ISODateString;
  /** Initial task name. */
  readonly name?: string;
  /** Initial custom source-row values used when creating a task. */
  readonly initialValues?: DataType;
  /** Optionally link the new task to an existing task in the same transaction. */
  readonly dependency?: {
    readonly taskId: TaskId;
    /** Role of the newly created task relative to `taskId`. */
    readonly relation: 'predecessor' | 'successor';
    /** Dependency type. Defaults to `finish-to-start`. */
    readonly type?: DependencyType;
    /** Dependency lag in days. Defaults to `0`. */
    readonly lagDays?: number;
  };
  /**
   * Whether task-created listeners such as the packaged editor should open a
   * follow-up UI for the new task. Defaults to `true`.
   */
  readonly openEditor?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `parentId` | `string \| null \| undefined` | No | — | Parent task id, or `null` for a root-level task. |
| `insertAfterTaskId` | `string \| null \| undefined` | No | — | Insert the new task after this sibling. |
| `insertBeforeTaskId` | `string \| null \| undefined` | No | — | Insert the task before this sibling. Mutually exclusive with `insertAfterTaskId`. |
| `type` | `TaskType \| undefined` | No | — | Initial canonical task type. Defaults to `task`. |
| `startDate` | `ISODateString \| undefined` | No | — | Initial start date. |
| `endDate` | `ISODateString \| undefined` | No | — | Initial end date. |
| `name` | `string \| undefined` | No | — | Initial task name. |
| `initialValues` | `DataType \| undefined` | No | — | Initial custom source-row values used when creating a task. |
| `dependency` | `{ readonly taskId: TaskId; readonly relation: "predecessor" \| "successor"; readonly type?: DependencyType; readonly lagDays?: number; } \| undefined` | No | — | Optionally link the new task to an existing task in the same transaction. |
| `openEditor` | `boolean \| undefined` | No | — | Whether task-created listeners such as the packaged editor should open a follow-up UI for the new task. Defaults to `true`. |

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype), [`TaskId`](/api/gantt/data-model/#taskid), [`TaskType`](/api/gantt/data-model/#tasktype)

## `GanttDateAdapter`

<span class="api-kind">interface</span>

Structural Duet adapter shape kept independent from the optional date-column runtime.

```ts
export interface GanttDateAdapter {
  parse(value: string, createDate: (year: string, month: string, day: string) => Date): Date | undefined;
  format(date: Date): string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `parse(value: string, createDate: (year: string, month: string, day: string) => Date)` | `Date \| undefined` | Yes | — |  |
| `format(date: Date)` | `string` | Yes | — |  |

## `GanttDateEditorFormatConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttDateEditorFormatConfig {
  readonly formatter?: GanttDateFormatter;
  readonly parser?: GanttDateParser;
  readonly options?: Intl.DateTimeFormatOptions;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `formatter` | `GanttDateFormatter \| undefined` | No | — |  |
| `parser` | `GanttDateParser \| undefined` | No | — |  |
| `options` | `Intl.DateTimeFormatOptions \| undefined` | No | — |  |

**Related types:** [`GanttDateFormatter`](/api/gantt/plugin/#ganttdateformatter), [`GanttDateParser`](/api/gantt/plugin/#ganttdateparser)

## `GanttDateFormatConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttDateFormatConfig {
  /** BCP 47 locale tag used by Intl-based Gantt date formatting. */
  readonly locale?: string;
  /** IANA time zone used by Intl-based Gantt date formatting. Defaults to the project time zone. */
  readonly timeZone?: string;
  /** Managed task-table date cell format. Defaults to locale-aware medium date output. */
  readonly table?: GanttDateFormatOption;
  /** Task-bar tooltip date format. Omit to keep the existing UTC tooltip labels. */
  readonly tooltip?: GanttDateFormatOption;
  /** Task editor date display/parser configuration. */
  readonly editor?: GanttDateEditorFormatConfig;
  /** Timeline header formatter. Preferred over `zoom.defaultHeaderFormatter` when set. */
  readonly timeline?: TimelineDateFormatter;
  /** Fallback parser for custom table/editor date text. */
  readonly parser?: GanttDateParser;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `locale` | `string \| undefined` | No | — | BCP 47 locale tag used by Intl-based Gantt date formatting. |
| `timeZone` | `string \| undefined` | No | — | IANA time zone used by Intl-based Gantt date formatting. Defaults to the project time zone. |
| `table` | `GanttDateFormatOption \| undefined` | No | — | Managed task-table date cell format. Defaults to locale-aware medium date output. |
| `tooltip` | `GanttDateFormatOption \| undefined` | No | — | Task-bar tooltip date format. Omit to keep the existing UTC tooltip labels. |
| `editor` | `GanttDateEditorFormatConfig \| undefined` | No | — | Task editor date display/parser configuration. |
| `timeline` | `TimelineDateFormatter \| undefined` | No | — | Timeline header formatter. Preferred over `zoom.defaultHeaderFormatter` when set. |
| `parser` | `GanttDateParser \| undefined` | No | — | Fallback parser for custom table/editor date text. |

**Related types:** [`GanttDateEditorFormatConfig`](/api/gantt/plugin/#ganttdateeditorformatconfig), [`GanttDateFormatOption`](/api/gantt/plugin/#ganttdateformatoption), [`GanttDateParser`](/api/gantt/plugin/#ganttdateparser), [`TimelineDateFormatter`](/api/gantt/visuals/#timelinedateformatter)

## `GanttDateFormatContext`

<span class="api-kind">interface</span>

```ts
export interface GanttDateFormatContext {
  readonly surface: GanttDateFormatSurface;
  readonly field?: string;
  readonly locale: string;
  readonly timeZone: string;
  readonly levelId?: string;
  readonly rowId?: string;
  readonly unit?: string;
  readonly count?: number;
  readonly rowIndex?: number;
  readonly isLeafRow?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `surface` | `GanttDateFormatSurface` | Yes | — |  |
| `field` | `string \| undefined` | No | — |  |
| `locale` | `string` | Yes | — |  |
| `timeZone` | `string` | Yes | — |  |
| `levelId` | `string \| undefined` | No | — |  |
| `rowId` | `string \| undefined` | No | — |  |
| `unit` | `string \| undefined` | No | — |  |
| `count` | `number \| undefined` | No | — |  |
| `rowIndex` | `number \| undefined` | No | — |  |
| `isLeafRow` | `boolean \| undefined` | No | — |  |

**Related types:** [`GanttDateFormatSurface`](/api/gantt/plugin/#ganttdateformatsurface)

## `GanttDateFormatOption`

<span class="api-kind">type</span>

```ts
export type GanttDateFormatOption = Intl.DateTimeFormatOptions | GanttDateFormatter;
```

**Related types:** [`GanttDateFormatter`](/api/gantt/plugin/#ganttdateformatter)

## `GanttDateFormatSurface`

<span class="api-kind">type</span>

```ts
export type GanttDateFormatSurface = 'table' | 'tooltip' | 'editor' | 'timeline';
```

## `GanttDateFormatter`

<span class="api-kind">type</span>

```ts
export type GanttDateFormatter = (
  value: ISODateString | ISODateTimeString | string,
  context: GanttDateFormatContext,
) => string;
```

**Related types:** [`GanttDateFormatContext`](/api/gantt/plugin/#ganttdateformatcontext)

## `GanttDateParser`

<span class="api-kind">type</span>

```ts
export type GanttDateParser = (
  value: string,
  context: GanttDateFormatContext,
) => ISODateString | ISODateTimeString | null;
```

**Related types:** [`GanttDateFormatContext`](/api/gantt/plugin/#ganttdateformatcontext)

## `GanttDependencyDomainChangeDetail`

<span class="api-kind">interface</span>

Committed dependency mutation exposed through EventManager's `gridedit`.

```ts
export interface GanttDependencyDomainChangeDetail {
  readonly action: GanttBeforeDependencyChangeAction;
  readonly dependencyId: DependencyId;
  readonly previousDependency: DependencyEntity | null;
  readonly dependency: DependencyEntity | null;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `action` | `GanttBeforeDependencyChangeAction` | Yes | — |  |
| `dependencyId` | `string` | Yes | — |  |
| `previousDependency` | `DependencyEntity \| null` | Yes | — |  |
| `dependency` | `DependencyEntity \| null` | Yes | — |  |

**Related types:** [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`DependencyId`](/api/gantt/data-model/#dependencyid), [`GanttBeforeDependencyChangeAction`](/api/gantt/events/#ganttbeforedependencychangeaction)

## `ganttDependencyDropdownCellTemplate`

<span class="api-kind">constant</span>

```ts
export const ganttDependencyDropdownCellTemplate: CellTemplate<DataType<any, ColumnProp>> | undefined;
```

## `GanttDependencyDropdownEditor`

<span class="api-kind">class</span>

```ts
export class GanttDependencyDropdownEditor {
  element?: HTMLElement | null | undefined;
  editCell?: EditCell | undefined;
  constructor(private readonly data: ColumnDataSchemaModel, private readonly saveCallback: (value: unknown, preventFocus?: boolean) => void, private readonly closeCallback: (focusNext?: boolean) => void);
  componentDidRender(): Promise<void>;
  getValue(): readonly GanttDependencyDropdownValue[];
  disconnectedCallback(): void;
  render(createElement: HyperFunc<VNode>): VNode;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `element` | `HTMLElement \| null \| undefined` | No | — |  |
| `editCell` | `EditCell \| undefined` | No | — |  |
| `host` | `HTMLElement \| null \| undefined` | No | — |  |
| `value` | `readonly GanttDependencyDropdownValue[]` | Yes | — |  |
| `mounted` | `boolean` | Yes | `false` |  |
| `closed` | `boolean` | Yes | `false` |  |
| `componentDidRender()` | `Promise<void>` | Yes | — |  |
| `getValue()` | `readonly GanttDependencyDropdownValue[]` | Yes | — |  |
| `disconnectedCallback()` | `void` | Yes | — |  |
| `render(createElement: HyperFunc)` | `VNode` | Yes | — |  |
| `onChange(value: readonly GanttDependencyDropdownValue[])` | `void` | Yes | — |  |
| `closeEditor(focusNext?: boolean)` | `void` | Yes | — |  |

**Related types:** [`GanttDependencyDropdownValue`](/api/gantt/extensions/#ganttdependencydropdownvalue)

## `GanttDependencyErrorLabelKey`

<span class="api-kind">type</span>

```ts
export type GanttDependencyErrorLabelKey =
  | 'duplicate'
  | 'notFound'
  | 'taskNotFound'
  | 'tasksMustExist'
  | 'selfReference'
  | 'invalidType'
  | 'invalidReference'
  | 'unsupportedReferenceType'
  | 'taskReferenceNotFound'
  | 'invalidReferenceValue'
  | 'cycle'
  | 'readOnly'
  | 'replacementCanceled';
```

## `GanttDependencyTooltipContext`

<span class="api-kind">interface</span>

Context supplied when building dependency-arrow tooltip content.

```ts
export interface GanttDependencyTooltipContext {
  /** Dependency relationship under the pointer. */
  readonly dependency: DependencyEntity;
  /** Predecessor/source task when present in the current task store. */
  readonly predecessorTask: TaskEntity | null;
  /** Successor/target task when present in the current task store. */
  readonly successorTask: TaskEntity | null;
  /** Display label used for the From row. Falls back to the predecessor task id. */
  readonly predecessorName: string;
  /** Display label used for the To row. Falls back to the successor task id. */
  readonly successorName: string;
  /** Newline-delimited default tooltip body. */
  readonly defaultTooltip: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `dependency` | `DependencyEntity` | Yes | — | Dependency relationship under the pointer. |
| `predecessorTask` | `TaskEntity \| null` | Yes | — | Predecessor/source task when present in the current task store. |
| `successorTask` | `TaskEntity \| null` | Yes | — | Successor/target task when present in the current task store. |
| `predecessorName` | `string` | Yes | — | Display label used for the From row. Falls back to the predecessor task id. |
| `successorName` | `string` | Yes | — | Display label used for the To row. Falls back to the successor task id. |
| `defaultTooltip` | `string` | Yes | — | Newline-delimited default tooltip body. |

**Related types:** [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`TaskEntity`](/api/gantt/data-model/#taskentity)

## `GanttDependencyTooltipHook`

<span class="api-kind">type</span>

Callback that replaces dependency-arrow tooltip content.
Return `null` or `undefined` to keep the default From/To tooltip.

```ts
export type GanttDependencyTooltipHook = (context: GanttDependencyTooltipContext) => string | null | undefined;
```

**Related types:** [`GanttDependencyTooltipContext`](/api/gantt/plugin/#ganttdependencytooltipcontext)

## `GanttErrorLabelsConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttErrorLabelsConfig {
  readonly taskEdit?: Partial<Record<GanttTaskEditErrorLabelKey, GanttMessageTemplate>>;
  readonly taskMutation?: Partial<Record<GanttTaskMutationErrorLabelKey, GanttMessageTemplate>>;
  readonly assignment?: Partial<Record<GanttAssignmentErrorLabelKey, GanttMessageTemplate>>;
  readonly dependency?: Partial<Record<GanttDependencyErrorLabelKey, GanttMessageTemplate>>;
  readonly taskEditor?: Partial<Record<GanttTaskEditorErrorLabelKey, GanttMessageTemplate>>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskEdit` | `Partial<Record<GanttTaskEditErrorLabelKey, GanttMessageTemplate>> \| undefined` | No | — |  |
| `taskMutation` | `Partial<Record<GanttTaskMutationErrorLabelKey, GanttMessageTemplate>> \| undefined` | No | — |  |
| `assignment` | `Partial<Record<GanttAssignmentErrorLabelKey, GanttMessageTemplate>> \| undefined` | No | — |  |
| `dependency` | `Partial<Record<GanttDependencyErrorLabelKey, GanttMessageTemplate>> \| undefined` | No | — |  |
| `taskEditor` | `Partial<Record<GanttTaskEditorErrorLabelKey, GanttMessageTemplate>> \| undefined` | No | — |  |

**Related types:** [`GanttAssignmentErrorLabelKey`](/api/gantt/plugin/#ganttassignmenterrorlabelkey), [`GanttDependencyErrorLabelKey`](/api/gantt/plugin/#ganttdependencyerrorlabelkey), [`GanttMessageTemplate`](/api/gantt/plugin/#ganttmessagetemplate), [`GanttTaskEditErrorLabelKey`](/api/gantt/plugin/#gantttaskediterrorlabelkey), [`GanttTaskEditorErrorLabelKey`](/api/gantt/plugin/#gantttaskeditorerrorlabelkey), [`GanttTaskMutationErrorLabelKey`](/api/gantt/plugin/#gantttaskmutationerrorlabelkey)

## `GanttLabelsConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttLabelsConfig extends GanttRuntimeLabelsConfig {
  /** Packaged task-editor text inherited by `GanttTaskEditorDialogPlugin`. */
  readonly taskEditor?: GanttTaskEditorDialogLocaleTextOptions;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskEditor` | `GanttTaskEditorDialogLocaleTextOptions \| undefined` | No | — | Packaged task-editor text inherited by `GanttTaskEditorDialogPlugin`. |

**Related types:** [`GanttRuntimeLabelsConfig`](/api/gantt/plugin/#ganttruntimelabelsconfig), [`GanttTaskEditorDialogLocaleTextOptions`](/api/gantt/extensions/#gantttaskeditordialoglocaletextoptions), [`GanttTaskEditorDialogPlugin`](/api/gantt/extensions/#gantttaskeditordialogplugin)

## `GanttMessageContext`

<span class="api-kind">interface</span>

Values available to parameterized Gantt error and warning labels.

```ts
export interface GanttMessageContext {
  readonly action?: string;
  readonly allocatedUnits?: number;
  readonly assignmentId?: string;
  readonly calendarId?: string | number;
  readonly capacityUnits?: number;
  readonly constraintDate?: string;
  readonly constraintType?: string;
  readonly date?: string;
  readonly dependencyId?: string;
  readonly dependencyType?: string;
  readonly endDate?: string;
  readonly entityId?: string;
  readonly entityName?: string;
  readonly field?: string;
  readonly label?: string;
  readonly max?: number;
  readonly min?: number;
  readonly parentId?: string;
  readonly resourceId?: string;
  readonly resourceName?: string;
  readonly splitIndex?: number;
  readonly startDate?: string;
  readonly taskId?: string;
  readonly value?: unknown;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `action` | `string \| undefined` | No | — |  |
| `allocatedUnits` | `number \| undefined` | No | — |  |
| `assignmentId` | `string \| undefined` | No | — |  |
| `calendarId` | `string \| number \| undefined` | No | — |  |
| `capacityUnits` | `number \| undefined` | No | — |  |
| `constraintDate` | `string \| undefined` | No | — |  |
| `constraintType` | `string \| undefined` | No | — |  |
| `date` | `string \| undefined` | No | — |  |
| `dependencyId` | `string \| undefined` | No | — |  |
| `dependencyType` | `string \| undefined` | No | — |  |
| `endDate` | `string \| undefined` | No | — |  |
| `entityId` | `string \| undefined` | No | — |  |
| `entityName` | `string \| undefined` | No | — |  |
| `field` | `string \| undefined` | No | — |  |
| `label` | `string \| undefined` | No | — |  |
| `max` | `number \| undefined` | No | — |  |
| `min` | `number \| undefined` | No | — |  |
| `parentId` | `string \| undefined` | No | — |  |
| `resourceId` | `string \| undefined` | No | — |  |
| `resourceName` | `string \| undefined` | No | — |  |
| `splitIndex` | `number \| undefined` | No | — |  |
| `startDate` | `string \| undefined` | No | — |  |
| `taskId` | `string \| undefined` | No | — |  |
| `value` | `unknown` | No | — |  |

## `GanttMessageTemplate`

<span class="api-kind">type</span>

```ts
export type GanttMessageTemplate = string | ((context: GanttMessageContext) => string);
```

**Related types:** [`GanttMessageContext`](/api/gantt/plugin/#ganttmessagecontext)

## `GanttMilestoneLine`

<span class="api-kind">interface</span>

A vertical flag line pinned to a specific date on the gantt timeline.
Shows a cap/flag at the top of the canvas and a full-height vertical line.

```ts
export interface GanttMilestoneLine {
  /** Unique identifier. */
  readonly id: string;
  /** Date the line is pinned to. */
  readonly date: ISODateString;
  /** Label displayed on the flag cap. */
  readonly label?: string;
  /** Optional CSS color for the line and flag (defaults to CSS variable). */
  readonly color?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique identifier. |
| `date` | `ISODateString` | Yes | — | Date the line is pinned to. |
| `label` | `string \| undefined` | No | — | Label displayed on the flag cap. |
| `color` | `string \| undefined` | No | — | Optional CSS color for the line and flag (defaults to CSS variable). |

## `GanttPlugin`

<span class="api-kind">class</span>

```ts
export class GanttPlugin extends CorePlugin {
  [DATA_GRID_CONTEXT_MENU_EXTERNAL_ROW_OWNER]: true;
  pluginDependencies: PluginDependency[];
  constructor(revogrid: HTMLRevoGridElement, providers: PluginProviders);
  applyGantt(config?: GanttPluginConfig): void;
  clearGantt(): void;
  destroy(): void;
  zoomIn(): boolean;
  zoomOut(): boolean;
  setZoomLevel(levelId: string): boolean;
  getZoomLevel(): TimelineZoomLevel;
  canZoomIn(): boolean;
  canZoomOut(): boolean;
  getVisibleRange(): { startDate: ISODateString; endDate: ISODateString; } | null;
  captureBaseline(options?: CaptureBaselineOptions): BaselineSnapshot | null;
  createTask(options?: GanttCreateTaskOptions): TaskId | null;
  updateTask(taskId: TaskId, patch: TaskUpdate): boolean;
  updateTasks(taskIds: readonly TaskId[], patch: TaskUpdate): boolean;
  getProjectSnapshot(): ProjectSnapshot | null;
  finalizeTaskCreate(taskId: TaskId): boolean;
  discardTaskCreate(taskId: TaskId): boolean;
  indentTasks(taskIds?: readonly TaskId[]): readonly TaskId[];
  indentTask(taskId?: TaskId): TaskId | null;
  outdentTasks(taskIds?: readonly TaskId[]): readonly TaskId[];
  outdentTask(taskId?: TaskId): TaskId | null;
  convertTasksToMilestones(taskIds?: readonly TaskId[]): readonly TaskId[];
  convertTaskToMilestone(taskId?: TaskId): TaskId | null;
  deleteTasks(taskIds?: readonly TaskId[]): readonly TaskId[];
  deleteTask(taskId?: TaskId): TaskId | null;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `[DATA_GRID_CONTEXT_MENU_EXTERNAL_ROW_OWNER]` | `true` | Yes | `true as const` |  |
| `pluginDependencies` | `PluginDependency[]` | Yes | `[     {       kind: 'auto-installed',       target: { type: 'plugins', plugins: [() => OverlayPlugin, () => EventManagerPlugin, () => HistoryPlugin, () => TooltipPlugin, () => ContextMenuPlugin, () => DataGridContextMenuPlugin] },       description: 'Installs these Pro plugins internally when absent, including the shared semantic grid context menu used by Gantt.',     },     {       kind: 'auto-installed',       target: { type: 'plugins', plugins: [() => RowOrderPlugin, () => TreeDataPlugin, () => ColumnHidePlugin, () => ColumnDialogPlugin, () => GanttPanelResizePlugin, () => GanttTaskEditorDialogPlugin, () => GanttAddTaskRowPlugin, () => GanttTimelineHeaderPlugin] },       description: 'Installs these plugins internally for Gantt grid structure, row reordering, column visibility management, panel resizing, task editing, the pinned add-task row, and timeline header rendering.',     },     {       kind: 'auto-installed',       target: { type: 'plugin', plugin: () => AdvanceFilterPlugin },       description: 'Installs advanced filtering when Gantt enables task-table filters after RevoGrid core plugin bootstrap.',     },     {       kind: 'config-integration',       target: [         { type: 'contract', contract: 'direct-tree-config' },         { type: 'contract', contract: 'direct-event-manager-config' },         { type: 'contract', contract: 'direct-history-config' },       ],       description: 'Reads and writes direct plugin config props while synchronizing Gantt state.',     },   ]` |  |
| `tooltipSuppression` | `GanttTooltipSuppression` | Yes | — |  |
| `ganttConfig` | `GanttPluginConfig \| null` | Yes | `null` |  |
| `gridState` | `GanttGridState` | Yes | `new GanttGridState()` |  |
| `schedulerEngine` | `SchedulerEngine` | Yes | `createSchedulerEngine()` |  |
| `dependencyLayoutService` | `DependencyLayoutService` | Yes | `createDependencyLayoutService()` |  |
| `gridSync` | `GanttGridSync` | Yes | — |  |
| `timelineHeaderPlugin` | `GanttTimelineHeaderPlugin` | Yes | — |  |
| `rowOrderState` | `GanttRowOrderState` | Yes | — |  |
| `searchTool` | `GanttSearchTool` | Yes | — |  |
| `historyTool` | `GanttHistoryTool` | Yes | — |  |
| `taskMutationService` | `DefaultTaskMutationService` | Yes | `createTaskMutationService()` |  |
| `assignmentMutationService` | `AssignmentMutationService` | Yes | `createAssignmentMutationService()` |  |
| `dependencyMutationService` | `DependencyMutationService` | Yes | `createDependencyMutationService()` |  |
| `isApplyingGridRows` | `boolean` | Yes | `false` |  |
| `resourcePlanningNameColumnEnabled` | `boolean \| null` | Yes | `null` |  |
| `toolContext` | `GanttCoordinatorContext` | Yes | — |  |
| `taskBarsPlugin` | `GanttTaskBarsPlugin` | Yes | — |  |
| `addTaskRowPlugin` | `GanttAddTaskRowPlugin` | Yes | — |  |
| `timelineViewport` | `GanttTimelineViewportController` | Yes | — |  |
| `timelineBackgroundTool` | `TimelineBackgroundTool` | Yes | — |  |
| `taskSelectionTool` | `GanttTaskSelectionTool` | Yes | — |  |
| `selectionCoordinator` | `GanttSelectionCoordinator` | Yes | — |  |
| `calendarTool` | `CalendarTool` | Yes | `new CalendarTool()` |  |
| `timelineTool` | `TimelineTool` | Yes | — |  |
| `timelineState` | `TimelineViewState` | Yes | `new TimelineViewState()` |  |
| `baselineTool` | `BaselineTool` | Yes | `new BaselineTool()` |  |
| `criticalPathTool` | `CriticalPathTool` | Yes | `new CriticalPathTool()` |  |
| `assignmentsTool` | `AssignmentsTool` | Yes | — |  |
| `dependencyTool` | `DependencyTool` | Yes | — |  |
| `dependencyOverlayPlugin` | `GanttDependencyOverlayPlugin` | Yes | — |  |
| `contextMenuTool` | `GanttContextMenuTool` | Yes | — |  |
| `featureTools` | `readonly GanttFeatureTool[]` | Yes | — |  |
| `hasHydratedTaskRows` | `boolean` | Yes | `false` |  |
| `hasHydratedDependencies` | `boolean` | Yes | `false` |  |
| `hasHydratedAssignments` | `boolean` | Yes | `false` |  |
| `hasHydratedBaselines` | `boolean` | Yes | `false` |  |
| `externalDependencies` | `readonly DependencyEntity[] \| undefined` | Yes | — |  |
| `externalCalendars` | `readonly CalendarEntity[] \| undefined` | Yes | — |  |
| `externalResources` | `readonly ResourceEntity[] \| undefined` | Yes | — |  |
| `externalAssignments` | `readonly AssignmentEntity[] \| undefined` | Yes | — |  |
| `externalBaselines` | `readonly BaselineSnapshot[] \| undefined` | Yes | — |  |
| `pendingTaskCreateSnapshots` | `Map<string, { readonly sourceRows: readonly DataType[]; readonly tasks: readonly TaskEntity[]; }>` | Yes | `new Map<TaskId, {     readonly sourceRows: readonly DataType[];     readonly tasks: readonly TaskEntity[];   }>()` |  |
| `timelineHeaderRefreshFrame` | `number \| null` | Yes | `null` |  |
| `viewportScrollRefreshFrame` | `number \| null` | Yes | `null` |  |
| `rowOrderCommitTimer` | `number \| null` | Yes | `null` |  |
| `pluginsInitialized` | `boolean` | Yes | `false` |  |
| `disposeTooltipThemeVariables` | `(() => void) \| undefined` | No | — |  |
| `featureToolsSetup` | `boolean` | Yes | `false` |  |
| `hasObservedGanttConfigChange` | `boolean` | Yes | `false` |  |
| `sourceFields` | `ResolvedGanttFieldMap` | Yes | `resolveGanttFieldMap()` |  |
| `authoredSource` | `readonly DataType[]` | Yes | `[]` |  |
| `onGridKeyDown` | `(event: CustomEvent \| KeyboardEvent) => void` | Yes | `createKeyboardEventAdapter((event) => this.onKeyDown(event))` |  |
| `onGridWheel` | `(event: WheelEvent) => void` | Yes | `(event: WheelEvent) => this.onWheel(event)` |  |
| `onGridNativeScroll` | `(event: Event) => void` | Yes | `(event: Event) => this.onNativeViewportScroll(event)` |  |
| `applyGantt(config?: GanttPluginConfig)` | `void` | Yes | — |  |
| `clearGantt()` | `void` | Yes | — |  |
| `destroy()` | `void` | Yes | — |  |
| `applyInitialState(initialBindings: GanttObservableBindings)` | `void` | Yes | — |  |
| `enableRangeSelectionDefault()` | `void` | Yes | — |  |
| `initPlugins()` | `void` | Yes | — |  |
| `collectEdit(detail: EventManagerEvent)` | `void` | Yes | — |  |
| `setupFeatureTools()` | `void` | Yes | — |  |
| `registerEventListeners()` | `GanttObservableBindings` | Yes | — |  |
| `bootstrapProject(project: GanttPluginConfig)` | `void` | Yes | — |  |
| `handleSourceChange(source: DataType[] \| undefined, updateMode: GridUpdateMode = 'none')` | `GanttGridRenderResult \| null` | Yes | — |  |
| `scheduleRowOrderCommit(previousTasks: readonly DataType[], movedTaskIds: readonly TaskId[] = [], projectedRows: readonly DataType[] = [])` | `void` | Yes | — |  |
| `cancelRowOrderCommit()` | `void` | Yes | — |  |
| `commitRowOrder(previousTasks: readonly DataType[], movedTaskIds: readonly TaskId[] = [], projectedRows: readonly DataType[] = [])` | `void` | Yes | — |  |
| `refreshSearchAfterSourceSet()` | `void` | Yes | — |  |
| `handleDependenciesChange(dependencies: readonly DependencyEntity[] \| undefined)` | `void` | Yes | — |  |
| `handleCalendarsChange(calendars: readonly CalendarEntity[] \| undefined)` | `void` | Yes | — |  |
| `resolveConfiguredCalendars(config: GanttPluginConfig \| null)` | `readonly CalendarEntity[]` | Yes | — |  |
| `handleResourcesChange(resources: readonly ResourceEntity[] \| undefined)` | `void` | Yes | — |  |
| `handleAssignmentsChange(assignments: readonly AssignmentEntity[] \| undefined)` | `void` | Yes | — |  |
| `handleBaselinesChange(baselines: readonly BaselineSnapshot[] \| undefined)` | `void` | Yes | — |  |
| `emitDependencyHistoryIfChanged(previousDependencies: readonly DependencyEntity[], nextDependencies: readonly DependencyEntity[])` | `void` | Yes | — |  |
| `emitAssignmentHistoryIfChanged(previousAssignments: readonly AssignmentEntity[], nextAssignments: readonly AssignmentEntity[])` | `void` | Yes | — |  |
| `emitBaselineHistoryIfChanged(previousBaselines: readonly BaselineSnapshot[], nextBaselines: readonly BaselineSnapshot[])` | `void` | Yes | — |  |
| `renderGrid(updateMode: GridUpdateMode = 'structure', preserveAuthoredSource = false)` | `GanttGridRenderResult \| null` | Yes | — |  |
| `refreshGanttViewport(updateMode: GridUpdateMode = 'viewport')` | `GanttGridRenderResult \| null` | Yes | — |  |
| `syncGridRows(rows: readonly DataType[], updateMode: GridUpdateMode)` | `void` | Yes | — |  |
| `collectRenderContributions()` | `GanttRenderContributions` | Yes | — |  |
| `getTaskRowPatchContext(taskId: TaskId \| null, patch: Partial)` | `GanttSourcePatchContext` | Yes | — |  |
| `commitGridEdit(detail: EventManagerEvent)` | `boolean` | Yes | — |  |
| `commitRowStatusChange(detail: RowStatusChangeEvent)` | `void` | Yes | — |  |
| `replayHistoryEdit(detail: EventManagerEvent)` | `boolean` | Yes | — |  |
| `applyGridEditData(detail: EventManagerEvent, options: { emitBeforeTaskChange: boolean; preferRawTaskPatch: boolean })` | `boolean` | Yes | — |  |
| `applyDirectSourcePatch(taskId: TaskId, sourcePatch: Record<string, unknown>)` | `void` | Yes | — |  |
| `commitDerivedTaskStoreToSource()` | `void` | Yes | — |  |
| `normalizeGridEditValue(field: string, value: unknown)` | `unknown` | Yes | — |  |
| `onLayoutChanged()` | `void` | Yes | — |  |
| `onViewportScrollSource(event: CustomEvent)` | `void` | Yes | — |  |
| `onNativeViewportScroll(event: Event)` | `void` | Yes | — |  |
| `onViewportScrollApplied()` | `void` | Yes | — |  |
| `shouldSyncViewportFromScrollSource(event: CustomEvent)` | `boolean` | Yes | — |  |
| `shouldSyncViewportFromNativeScroll(event: Event)` | `boolean` | Yes | — |  |
| `scheduleViewportScrollRefresh()` | `void` | Yes | — |  |
| `cancelViewportScrollRefresh()` | `void` | Yes | — |  |
| `onViewportChanged()` | `void` | Yes | — |  |
| `scrollGanttViewport(position: { x?: number; y?: number })` | `Promise<void>` | Yes | — |  |
| `scheduleTimelineHeaderRefresh()` | `void` | Yes | — |  |
| `cancelTimelineHeaderRefresh()` | `void` | Yes | — |  |
| `syncTimelineBackground(viewport: GanttViewportSnapshot \| null = this.timelineViewport.syncFrame())` | `void` | Yes | — |  |
| `hasTimelineBackgroundHeaderStateChanged(state: TimelineBackgroundHeaderState)` | `boolean` | Yes | — |  |
| `onKeyDown(event: KeyboardEvent)` | `void` | Yes | — |  |
| `onWheel(event: WheelEvent)` | `void` | Yes | — |  |
| `zoomIn()` | `boolean` | Yes | — |  |
| `zoomOut()` | `boolean` | Yes | — |  |
| `setZoomLevel(levelId: string)` | `boolean` | Yes | — |  |
| `getZoomLevel()` | `TimelineZoomLevel` | Yes | — |  |
| `canZoomIn()` | `boolean` | Yes | — |  |
| `canZoomOut()` | `boolean` | Yes | — |  |
| `getVisibleRange()` | `{ startDate: ISODateString; endDate: ISODateString; } \| null` | Yes | — |  |
| `captureBaseline(options?: CaptureBaselineOptions)` | `BaselineSnapshot \| null` | Yes | — |  |
| `createTask(options?: GanttCreateTaskOptions)` | `TaskId \| null` | Yes | — |  |
| `createTaskFromPinnedRow(name: string)` | `TaskId \| null` | Yes | — |  |
| `updateTask(taskId: TaskId, patch: TaskUpdate)` | `boolean` | Yes | — |  |
| `updateTasks(taskIds: readonly TaskId[], patch: TaskUpdate)` | `boolean` | Yes | — |  |
| `getProjectSnapshot()` | `ProjectSnapshot \| null` | Yes | — | Return the project collections currently owned by the Gantt runtime. |
| `finalizeTaskCreate(taskId: TaskId)` | `boolean` | Yes | — |  |
| `discardTaskCreate(taskId: TaskId)` | `boolean` | Yes | — |  |
| `commitTaskCreate(options?: GanttCreateTaskOptions)` | `TaskId \| null` | Yes | — |  |
| `shouldDeferTaskCreateHistory(options?: GanttCreateTaskOptions)` | `boolean` | Yes | — |  |
| `syncPublicTaskRows(options: { createdTaskId?: TaskId; initialValues?: DataType } = {})` | `void` | Yes | — |  |
| `resolveBulkTaskIds(taskIds?: readonly TaskId[])` | `TaskId[]` | Yes | — |  |
| `validateTaskMutation(action: GanttBulkTaskAction, taskIds: readonly TaskId[], options: { startDate?: string } = {})` | `GanttBulkActionValidation` | Yes | — |  |
| `emitBulkBeforeTaskChanges(action: 'indent' \| 'outdent' \| 'delete' \| 'convert-to-milestone', taskIds: readonly TaskId[])` | `boolean` | Yes | — |  |
| `commitBulkTaskAction(action: 'indent' \| 'outdent' \| 'delete' \| 'convert-to-milestone', taskIds: readonly TaskId[])` | `readonly TaskId[]` | Yes | — |  |
| `syncTaskMutationService()` | `void` | Yes | — |  |
| `indentTasks(taskIds?: readonly TaskId[])` | `readonly TaskId[]` | Yes | — |  |
| `indentTask(taskId?: TaskId)` | `TaskId \| null` | Yes | — |  |
| `outdentTasks(taskIds?: readonly TaskId[])` | `readonly TaskId[]` | Yes | — |  |
| `outdentTask(taskId?: TaskId)` | `TaskId \| null` | Yes | — |  |
| `convertTasksToMilestones(taskIds?: readonly TaskId[])` | `readonly TaskId[]` | Yes | — |  |
| `convertTaskToMilestone(taskId?: TaskId)` | `TaskId \| null` | Yes | — |  |
| `deleteTasks(taskIds?: readonly TaskId[])` | `readonly TaskId[]` | Yes | — |  |
| `deleteTask(taskId?: TaskId)` | `TaskId \| null` | Yes | — |  |
| `refreshTree(parentId?: TaskId \| null)` | `void` | Yes | — |  |
| `translateGridEditDetailToAuthored(detail: EventManagerEvent)` | `void` | Yes | — |  |
| `normalizeHistoryTaskRows(rows: readonly DataType[])` | `readonly DataType[]` | Yes | — |  |
| `getTaskIdFromModel(model: unknown)` | `TaskId \| null` | Yes | — |  |
| `clearRowSelectSelection()` | `void` | Yes | — |  |

**Related types:** [`BaselineSnapshot`](/api/gantt/data-model/#baselinesnapshot), [`GanttCreateTaskOptions`](/api/gantt/plugin/#ganttcreatetaskoptions), [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`TaskId`](/api/gantt/data-model/#taskid), [`TaskUpdate`](/api/gantt/data-model/#taskupdate), [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `GanttPluginConfig`

<span class="api-kind">interface</span>

Top-level configuration for the {@link GanttPlugin}.
Pass this object to the grid element's `gantt` property.

```ts
export interface GanttPluginConfig {
  // Project metadata (required)
  /** Unique project identifier. */
  readonly id: EntityId;
  /** Project display name. */
  readonly name: string;
  /** Project data schema version. */
  readonly version: string;
  /** Currency code for cost calculations (e.g. `\"USD\"`). */
  readonly currency: string;
  /** Default IANA time zone (e.g. `\"America/New_York\"`). */
  readonly timeZone: string;
  /** Calendar used by default for new tasks. */
  readonly primaryCalendarId: CalendarId;
  /** Timestamp of last project modification. */
  readonly updatedAt: ISODateTimeString;
  /** Reporting date used for calculated task status. Defaults to today. */
  readonly statusDate?: ISODateString;
  /** Working calendars for tasks/resources, including optional intraday `workingHours`. */
  readonly calendars?: readonly CalendarEntity[];
  /** Duration display unit and working-time conversion settings. */
  readonly durationSettings?: DurationSettings;
  /** Maps shared view meanings to task properties in the grid source. */
  readonly fields?: ViewFieldMap;

  // Configuration (all optional)
  /** When `true`, packaged Gantt task, dependency, and assignment mutations are rejected. */
  readonly readOnly?: boolean;
  /**
   * Task kinds available in packaged Task Type editors.
   * Omit to allow `task`, `milestone`, and `summary`.
   */
  readonly allowedTaskTypes?: readonly TaskType[];
  /** Pre-defined zoom level — see {@link TimelineZoomPreset}. */
  readonly zoomPreset?: TimelineZoomPreset;
  /** Timeline precision used by the default zoom and when a timeline mode has no interaction snap unit. Defaults to `'day'`. */
  readonly timelinePrecision?: 'day' | 'hour';
  /** Timeline interaction snapping options for task move and resize. */
  readonly snap?: GanttSnapConfig;
  /** Advanced zoom configuration overriding the preset. */
  readonly zoom?: TimelineZoomConfig;
  /** First day of week for timeline week headers/ticks, where `0` is Sunday and `1` is Monday. Defaults to Sunday. */
  readonly weekStartsOn?: 0 | 1;
  /**
   * Scheduling engine options.
   * These are MSP-inspired policies, not display preferences: they decide
   * whether authored dates move, warn, or stay anchored during recalculation.
   */
  readonly scheduling?: GanttSchedulingConfig;
  /** When `true`, enables packaged task-creation controls such as the pinned add-task row. */
  readonly allowTaskCreate?: boolean;
  /** When `true`, shows a pinned bottom row for typing a new task name. Requires `allowTaskCreate`. */
  readonly taskCreateRow?: boolean;
  /**
   * When `true`, clicking or tapping a task-table cell horizontally reveals
   * that task's bar in the timeline. Disabled by default.
   */
  readonly scrollToTaskOnCellClick?: boolean;
  /**
   * Optional inclusive timeline bounds. When omitted, bounds are derived from
   * scheduled task dates with zoom-appropriate padding.
   */
  readonly timelineRange?: GanttTimelineRange;
  /**
   * Built-in Gantt context menu integration. Enabled by default. Set to `false`
   * to opt out of generated row, column, and timeline menu items while keeping
   * application-provided RevoGrid context menu configuration untouched.
   */
  readonly contextMenu?: GanttContextMenuConfig | false;
  /** Restricts which dependency types the user may create. */
  readonly allowedDependencyTypes?: readonly DependencyType[];
  /** Filters the resource list to only show selected resources. */
  readonly resourceFilterIds?: readonly ResourceId[];
  /** Resource planning row view and load bar options. */
  readonly resourcePlanning?: GanttResourcePlanningConfig;
  /** Project-level date display and parsing preferences. */
  readonly dateFormats?: GanttDateFormatConfig;
  /** Built-in Gantt UI label overrides for localization. */
  readonly labels?: GanttLabelsConfig;
  /** Visual appearance options — see {@link GanttVisualConfig}. */
  readonly visuals?: GanttVisualConfig;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique project identifier. |
| `name` | `string` | Yes | — | Project display name. |
| `version` | `string` | Yes | — | Project data schema version. |
| `currency` | `string` | Yes | — | Currency code for cost calculations (e.g. `\"USD\"`). |
| `timeZone` | `string` | Yes | — | Default IANA time zone (e.g. `\"America/New_York\"`). |
| `primaryCalendarId` | `CalendarId` | Yes | — | Calendar used by default for new tasks. |
| `updatedAt` | ``${number}-${number}-${number}T${string}`` | Yes | — | Timestamp of last project modification. |
| `statusDate` | `ISODateString \| undefined` | No | — | Reporting date used for calculated task status. Defaults to today. |
| `calendars` | `readonly CalendarEntity[] \| undefined` | No | — | Working calendars for tasks/resources, including optional intraday `workingHours`. |
| `durationSettings` | `DurationSettings \| undefined` | No | — | Duration display unit and working-time conversion settings. |
| `fields` | `ViewFieldMap \| undefined` | No | — | Maps shared view meanings to task properties in the grid source. |
| `readOnly` | `boolean \| undefined` | No | — | When `true`, packaged Gantt task, dependency, and assignment mutations are rejected. |
| `allowedTaskTypes` | `readonly TaskType[] \| undefined` | No | — | Task kinds available in packaged Task Type editors. Omit to allow `task`, `milestone`, and `summary`. |
| `zoomPreset` | `TimelineZoomPreset \| undefined` | No | — | Pre-defined zoom level — see {@link TimelineZoomPreset}. |
| `timelinePrecision` | `"hour" \| "day" \| undefined` | No | — | Timeline precision used by the default zoom and when a timeline mode has no interaction snap unit. Defaults to `'day'`. |
| `snap` | `GanttSnapConfig \| undefined` | No | — | Timeline interaction snapping options for task move and resize. |
| `zoom` | `TimelineZoomConfig \| undefined` | No | — | Advanced zoom configuration overriding the preset. |
| `weekStartsOn` | `0 \| 1 \| undefined` | No | — | First day of week for timeline week headers/ticks, where `0` is Sunday and `1` is Monday. Defaults to Sunday. |
| `scheduling` | `GanttSchedulingConfig \| undefined` | No | — | Scheduling engine options. These are MSP-inspired policies, not display preferences: they decide whether authored dates move, warn, or stay anchored during recalculation. |
| `allowTaskCreate` | `boolean \| undefined` | No | — | When `true`, enables packaged task-creation controls such as the pinned add-task row. |
| `taskCreateRow` | `boolean \| undefined` | No | — | When `true`, shows a pinned bottom row for typing a new task name. Requires `allowTaskCreate`. |
| `scrollToTaskOnCellClick` | `boolean \| undefined` | No | — | When `true`, clicking or tapping a task-table cell horizontally reveals that task's bar in the timeline. Disabled by default. |
| `timelineRange` | `GanttTimelineRange \| undefined` | No | — | Optional inclusive timeline bounds. When omitted, bounds are derived from scheduled task dates with zoom-appropriate padding. |
| `contextMenu` | `false \| GanttContextMenuConfig \| undefined` | No | — | Built-in Gantt context menu integration. Enabled by default. Set to `false` to opt out of generated row, column, and timeline menu items while keeping application-provided RevoGrid context menu configuration untouched. |
| `allowedDependencyTypes` | `readonly DependencyType[] \| undefined` | No | — | Restricts which dependency types the user may create. |
| `resourceFilterIds` | `readonly string[] \| undefined` | No | — | Filters the resource list to only show selected resources. |
| `resourcePlanning` | `GanttResourcePlanningConfig \| undefined` | No | — | Resource planning row view and load bar options. |
| `dateFormats` | `GanttDateFormatConfig \| undefined` | No | — | Project-level date display and parsing preferences. |
| `labels` | `GanttLabelsConfig \| undefined` | No | — | Built-in Gantt UI label overrides for localization. |
| `visuals` | `GanttVisualConfig \| undefined` | No | — | Visual appearance options — see {@link GanttVisualConfig}. |

**Related types:** [`DependencyType`](/api/gantt/data-model/#dependencytype), [`EntityId`](/api/gantt/data-model/#entityid), [`GanttContextMenuConfig`](/api/gantt/plugin/#ganttcontextmenuconfig), [`GanttDateFormatConfig`](/api/gantt/plugin/#ganttdateformatconfig), [`GanttLabelsConfig`](/api/gantt/plugin/#ganttlabelsconfig), [`GanttResourcePlanningConfig`](/api/gantt/plugin/#ganttresourceplanningconfig), [`GanttSchedulingConfig`](/api/gantt/plugin/#ganttschedulingconfig), [`GanttSnapConfig`](/api/gantt/plugin/#ganttsnapconfig), [`GanttTimelineRange`](/api/gantt/visuals/#gantttimelinerange), [`GanttVisualConfig`](/api/gantt/visuals/#ganttvisualconfig), [`ResourceId`](/api/gantt/data-model/#resourceid), [`TaskType`](/api/gantt/data-model/#tasktype), [`TimelineZoomConfig`](/api/gantt/visuals/#timelinezoomconfig), [`TimelineZoomPreset`](/api/gantt/columns/#timelinezoompreset)

## `GanttResourcePlanningConfig`

<span class="api-kind">interface</span>

Resource planning/load view configuration.

```ts
export interface GanttResourcePlanningConfig {
  /** When `true`, the grid projects one row per resource instead of one row per task. */
  readonly enabled?: boolean;
  /** Restrict the resource planning rows to these resources. */
  readonly visibleResourceIds?: readonly ResourceId[];
  /** Load bucket size. `day` shows one bar per day; `week` aggregates by calendar week. */
  readonly loadGranularity?: 'day' | 'week';
  /** Capacity threshold display. */
  readonly capacityDisplay?: 'line' | 'none';
  /** How over-allocation is shown on load bars. */
  readonly overAllocationDisplay?: 'highlight' | 'none';
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `enabled` | `boolean \| undefined` | No | — | When `true`, the grid projects one row per resource instead of one row per task. |
| `visibleResourceIds` | `readonly string[] \| undefined` | No | — | Restrict the resource planning rows to these resources. |
| `loadGranularity` | `"day" \| "week" \| undefined` | No | — | Load bucket size. `day` shows one bar per day; `week` aggregates by calendar week. |
| `capacityDisplay` | `"line" \| "none" \| undefined` | No | — | Capacity threshold display. |
| `overAllocationDisplay` | `"none" \| "highlight" \| undefined` | No | — | How over-allocation is shown on load bars. |

**Related types:** [`ResourceId`](/api/gantt/data-model/#resourceid)

## `GanttRuntimeLabelsConfig`

<span class="api-kind">interface</span>

Shared labels understood by the Gantt engine, mutation services, and grid.

```ts
export interface GanttRuntimeLabelsConfig {
  readonly taskMode?: Partial<Record<GanttTaskModeLabelValue, string>>;
  readonly status?: Partial<Record<TaskStatus, string>>;
  readonly workflowStatus?: Partial<Record<TaskWorkflowStatus, string>>;
  readonly effortMode?: Partial<Record<TaskEffortMode, string>>;
  readonly constraintType?: Partial<Record<GanttConstraintTypeLabelValue, string>>;
  readonly taskType?: Partial<Record<TaskType, string>>;
  readonly errors?: GanttErrorLabelsConfig;
  readonly warnings?: GanttWarningLabelsConfig;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskMode` | `Partial<Record<GanttTaskModeLabelValue, string>> \| undefined` | No | — |  |
| `status` | `Partial<Record<TaskStatus, string>> \| undefined` | No | — |  |
| `workflowStatus` | `Partial<Record<TaskWorkflowStatus, string>> \| undefined` | No | — |  |
| `effortMode` | `Partial<Record<TaskEffortMode, string>> \| undefined` | No | — |  |
| `constraintType` | `Partial<Record<GanttConstraintTypeLabelValue, string>> \| undefined` | No | — |  |
| `taskType` | `Partial<Record<TaskType, string>> \| undefined` | No | — |  |
| `errors` | `GanttErrorLabelsConfig \| undefined` | No | — |  |
| `warnings` | `GanttWarningLabelsConfig \| undefined` | No | — |  |

**Related types:** [`GanttConstraintTypeLabelValue`](/api/gantt/plugin/#ganttconstrainttypelabelvalue), [`GanttErrorLabelsConfig`](/api/gantt/plugin/#gantterrorlabelsconfig), [`GanttTaskModeLabelValue`](/api/gantt/plugin/#gantttaskmodelabelvalue), [`GanttWarningLabelsConfig`](/api/gantt/plugin/#ganttwarninglabelsconfig), [`TaskEffortMode`](/api/gantt/data-model/#taskeffortmode), [`TaskStatus`](/api/gantt/data-model/#taskstatus), [`TaskType`](/api/gantt/data-model/#tasktype), [`TaskWorkflowStatus`](/api/gantt/data-model/#taskworkflowstatus)

## `GanttSchedulerWarningLabelKey`

<span class="api-kind">type</span>

```ts
export type GanttSchedulerWarningLabelKey =
  | 'duplicateId'
  | 'calendarWithoutWorkingDay'
  | 'invalidWorkingCalendar'
  | 'invalidTaskConstraint'
  | 'missingTaskCalendar'
  | 'invalidTaskDateRange'
  | 'invalidTaskDuration'
  | 'invalidTaskProgress'
  | 'invalidTaskWork'
  | 'invalidTaskPriority'
  | 'missingDependencyTask'
  | 'missingResourceCalendar'
  | 'invalidResourceUnits'
  | 'invalidResourceCost'
  | 'missingAssignmentTask'
  | 'missingAssignmentResource'
  | 'invalidAssignmentUnits'
  | 'invalidAssignmentWork'
  | 'dependencyCycle'
  | 'dependencyConstraint'
  | 'hardConstraintOverride'
  | 'constraintWindowForward'
  | 'constraintWindowBackward'
  | 'autoDependencyAdjustment'
  | 'finishConstraint'
  | 'manualDependencyForward'
  | 'manualDependencyBackward'
  | 'deadlineMissed'
  | 'resourceOverallocation'
  | 'storedLevelingDelay'
  | 'resourceLevelingAdjustment';
```

## `GanttSchedulingConfig`

<span class="api-kind">interface</span>

Scheduling engine configuration.

```ts
export interface GanttSchedulingConfig {
  /**
   * When enabled, task duration is evaluated in working days only,
   * excluding calendar holidays and non-working weekdays.
   */
  readonly excludeHolidaysFromDuration?: boolean;
  /** Default task mode when a source row does not explicitly set `taskMode`. */
  readonly taskModeDefault?: 'auto' | 'manual';
  /**
   * Behaviour for dependency violations on auto-scheduled tasks.
   * Both modes keep effective dates dependency-valid; `warn` additionally
   * creates diagnostics so the UI can explain why the task moved.
   */
  readonly autoDependencyViolationBehavior?: 'clamp' | 'warn';
  /**
   * Behaviour for dependency violations on manually scheduled tasks.
   * Manual tasks preserve authored dates; this option controls whether the
   * violation is surfaced to users.
   */
  readonly manualDependencyViolationBehavior?: 'warn' | 'ignore';
  /** Calendar basis used for dependency lag/lead. */
  readonly lagCalendar?: 'calendar-days' | 'working-days';
  /** Direction of scheduling. */
  readonly scheduleFrom?: 'project-start' | 'project-finish';
  /** Optional project start anchor used by forward scheduling policies. */
  readonly projectStartDate?: ISODateString;
  /** Optional project finish anchor used by backward scheduling policies. */
  readonly projectFinishDate?: ISODateString;
  /**
   * Resource capacity policy.
   * `warn` reports over-allocation; `auto` shifts eligible forward-scheduled
   * auto tasks. Backward/project-finish schedules remain warning-only.
   */
  readonly resourceLeveling?: 'off' | 'warn' | 'auto';
  /** When true, auto-leveling only delays tasks up to their pre-leveling total slack. */
  readonly resourceLevelingWithinSlack?: boolean;
  /** Default task type used for work/duration/unit calculations. Defaults to `fixed-duration`. */
  readonly effortModeDefault?: TaskEffortMode;
  /** Progress-aware scheduling policy for actual start and remaining duration fields. Actual finish is always authoritative. */
  readonly progressRescheduling?: 'off' | 'remaining-duration';
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `excludeHolidaysFromDuration` | `boolean \| undefined` | No | — | When enabled, task duration is evaluated in working days only, excluding calendar holidays and non-working weekdays. |
| `taskModeDefault` | `"manual" \| "auto" \| undefined` | No | — | Default task mode when a source row does not explicitly set `taskMode`. |
| `autoDependencyViolationBehavior` | `"clamp" \| "warn" \| undefined` | No | — | Behaviour for dependency violations on auto-scheduled tasks. Both modes keep effective dates dependency-valid; `warn` additionally creates diagnostics so the UI can explain why the task moved. |
| `manualDependencyViolationBehavior` | `"warn" \| "ignore" \| undefined` | No | — | Behaviour for dependency violations on manually scheduled tasks. Manual tasks preserve authored dates; this option controls whether the violation is surfaced to users. |
| `lagCalendar` | `"calendar-days" \| "working-days" \| undefined` | No | — | Calendar basis used for dependency lag/lead. |
| `scheduleFrom` | `"project-start" \| "project-finish" \| undefined` | No | — | Direction of scheduling. |
| `projectStartDate` | `ISODateString \| undefined` | No | — | Optional project start anchor used by forward scheduling policies. |
| `projectFinishDate` | `ISODateString \| undefined` | No | — | Optional project finish anchor used by backward scheduling policies. |
| `resourceLeveling` | `"auto" \| "warn" \| "off" \| undefined` | No | — | Resource capacity policy. `warn` reports over-allocation; `auto` shifts eligible forward-scheduled auto tasks. Backward/project-finish schedules remain warning-only. |
| `resourceLevelingWithinSlack` | `boolean \| undefined` | No | — | When true, auto-leveling only delays tasks up to their pre-leveling total slack. |
| `effortModeDefault` | `TaskEffortMode \| undefined` | No | — | Default task type used for work/duration/unit calculations. Defaults to `fixed-duration`. |
| `progressRescheduling` | `"off" \| "remaining-duration" \| undefined` | No | — | Progress-aware scheduling policy for actual start and remaining duration fields. Actual finish is always authoritative. |

**Related types:** [`TaskEffortMode`](/api/gantt/data-model/#taskeffortmode)

## `GanttSnapConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttSnapConfig {
  /** Unit used for timeline interaction snapping. Overrides the active timeline mode's `interactionSnapUnit`. */
  readonly unit?: 'day' | 'hour' | 'minute';
  /** When `true`, snapping skips calendar holidays, closed weekdays, and closed working time. Defaults to `true`. */
  readonly workingTime?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `unit` | `"minute" \| "hour" \| "day" \| undefined` | No | — | Unit used for timeline interaction snapping. Overrides the active timeline mode's `interactionSnapUnit`. |
| `workingTime` | `boolean \| undefined` | No | — | When `true`, snapping skips calendar holidays, closed weekdays, and closed working time. Defaults to `true`. |

## `GanttTaskDomainChangeDetail`

<span class="api-kind">interface</span>

Committed task mutation exposed through EventManager's `gridedit`.

```ts
export interface GanttTaskDomainChangeDetail {
  readonly action: GanttBeforeTaskChangeAction;
  readonly taskId: TaskId;
  readonly previousTask: TaskEntity | null;
  readonly task: TaskEntity | null;
  /** Canonical source positions, present when ordering is part of the change. */
  readonly previousIndex?: number;
  readonly index?: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `action` | `GanttBeforeTaskChangeAction` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `previousTask` | `TaskEntity \| null` | Yes | — |  |
| `task` | `TaskEntity \| null` | Yes | — |  |
| `previousIndex` | `number \| undefined` | No | — | Canonical source positions, present when ordering is part of the change. |
| `index` | `number \| undefined` | No | — |  |

**Related types:** [`GanttBeforeTaskChangeAction`](/api/gantt/events/#ganttbeforetaskchangeaction), [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttTaskEditErrorLabelKey`

<span class="api-kind">type</span>

```ts
export type GanttTaskEditErrorLabelKey =
  | 'invalidField'
  | 'booleanRequired'
  | 'unsupportedConstraintType'
  | 'invalidDate'
  | 'summaryDatesDerived'
  | 'invalidScheduledDate'
  | 'startAfterEnd'
  | 'endBeforeStart'
  | 'invalidEffortMode'
  | 'taskNameEmpty'
  | 'invalidLevelingDelay'
  | 'invalidPriority'
  | 'summaryProgressDerived'
  | 'invalidPercentDone'
  | 'statusCalculated'
  | 'invalidWorkflowStatus'
  | 'invalidTaskMode'
  | 'unsupportedTaskType'
  | 'disallowedTaskType'
  | 'summaryDurationDerived'
  | 'invalidDuration'
  | 'invalidRemainingDuration'
  | 'milestoneDurationZero'
  | 'invalidWork';
```

## `GanttTaskEditorErrorLabelKey`

<span class="api-kind">type</span>

```ts
export type GanttTaskEditorErrorLabelKey =
  | 'invalidDate'
  | 'invalidNonNegativeNumber'
  | 'invalidRangeNumber'
  | 'invalidBoolean'
  | 'unsupportedField'
  | 'taskNameEmpty'
  | 'unsupportedWorkflowStatus'
  | 'disallowedTaskType'
  | 'summaryDurationDerived'
  | 'invalidDuration'
  | 'invalidDateRange'
  | 'unsupportedConstraintType'
  | 'invalidWork'
  | 'invalidRemainingDuration'
  | 'unsupportedEffortMode'
  | 'calendarUnavailable'
  | 'invalidTags';
```

## `GanttTaskHierarchyActionDetail`

<span class="api-kind">interface</span>

Detail payload for indent/outdent events.

```ts
export interface GanttTaskHierarchyActionDetail {
  /** Target task id (defaults to the currently selected task). */
  readonly taskId?: TaskId;
  /** Target task ids for bulk task actions. */
  readonly taskIds?: readonly TaskId[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskId` | `string \| undefined` | No | — | Target task id (defaults to the currently selected task). |
| `taskIds` | `readonly string[] \| undefined` | No | — | Target task ids for bulk task actions. |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttTaskModeLabelValue`

<span class="api-kind">type</span>

```ts
export type GanttTaskModeLabelValue = 'auto' | 'manual';
```

## `GanttTaskModeOption`

<span class="api-kind">type</span>

```ts
export type GanttTaskModeOption = 'auto' | 'manual';
```

## `GanttTaskMutationErrorLabelKey`

<span class="api-kind">type</span>

```ts
export type GanttTaskMutationErrorLabelKey =
  | 'readOnly'
  | 'lockedTask'
  | 'taskNotFound'
  | 'serviceNotConfigured'
  | 'invalidDate'
  | 'invalidRange'
  | 'invalidOptionalDate'
  | 'invalidNonNegativeNumber'
  | 'invalidBoolean'
  | 'summaryProgressDerived'
  | 'invalidDuration'
  | 'invalidPriority'
  | 'unsupportedEffortMode'
  | 'unsupportedTaskType'
  | 'nonWorkingDate'
  | 'actualDateRange'
  | 'firstTaskIndent'
  | 'firstSiblingIndent'
  | 'rootTaskOutdent'
  | 'taskOutdentFailed'
  | 'splitRangesArray'
  | 'invalidSplitStart'
  | 'invalidSplitEnd'
  | 'invalidSplitRange'
  | 'regularTaskSplitOnly'
  | 'splitOverlapRequired'
  | 'regularSplitMoveOnly'
  | 'splitNotFound'
  | 'summaryMove'
  | 'actualFinishMove'
  | 'resizeTaskOnly'
  | 'noWorkingDays'
  | 'alreadyMilestone'
  | 'summaryMilestone';
```

## `GanttTaskSourceRow`

<span class="api-kind">type</span>

Flat authored task row shape consumed from `grid.source` by Gantt.

```ts
export type GanttTaskSourceRow = GanttTaskSourceBase & (
  | { readonly duration: number | string }
  | { readonly endDate: ISODateString | ISODateTimeString }
);
```

## `GanttTaskTooltipContext`

<span class="api-kind">interface</span>

Context supplied when building task-bar tooltip content.
The task name is rendered as the tooltip title outside hook output.

```ts
export interface GanttTaskTooltipContext extends GanttTaskBarVisualContext {
  /** Current Gantt project/config, when available. */
  readonly project?: GanttPluginConfig | null;
  /** Built-in fields used by the fallback tooltip body. */
  readonly defaultFields: readonly GanttTaskTooltipField[];
  /** Newline-delimited fallback tooltip body, excluding the task title. */
  readonly defaultTooltip: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `GanttPluginConfig \| null \| undefined` | No | — | Current Gantt project/config, when available. |
| `defaultFields` | `readonly GanttTaskTooltipField[]` | Yes | — | Built-in fields used by the fallback tooltip body. |
| `defaultTooltip` | `string` | Yes | — | Newline-delimited fallback tooltip body, excluding the task title. |

**Related types:** [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig), [`GanttTaskBarVisualContext`](/api/gantt/visuals/#gantttaskbarvisualcontext), [`GanttTaskTooltipField`](/api/gantt/plugin/#gantttasktooltipfield)

## `GanttTaskTooltipField`

<span class="api-kind">type</span>

A built-in tooltip field id, or a field descriptor with a custom label.

```ts
export type GanttTaskTooltipField = GanttTaskTooltipFieldId | GanttTaskTooltipFieldConfig;
```

**Related types:** [`GanttTaskTooltipFieldConfig`](/api/gantt/plugin/#gantttasktooltipfieldconfig), [`GanttTaskTooltipFieldId`](/api/gantt/plugin/#gantttasktooltipfieldid)

## `GanttTaskTooltipFieldConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskTooltipFieldConfig {
  /** Built-in task field to render in the task-bar tooltip at this position. */
  readonly field: GanttTaskTooltipFieldId;
  /** Optional label override. Set to an empty string to render only the value. */
  readonly label?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `field` | `GanttTaskTooltipFieldId` | Yes | — | Built-in task field to render in the task-bar tooltip at this position. |
| `label` | `string \| undefined` | No | — | Optional label override. Set to an empty string to render only the value. |

**Related types:** [`GanttTaskTooltipFieldId`](/api/gantt/plugin/#gantttasktooltipfieldid)

## `GanttTaskTooltipFieldId`

<span class="api-kind">type</span>

```ts
export type GanttTaskTooltipFieldId =
  /** Legacy combined line: task name and completion percent. Prefer the always-visible tooltip title. */
  | 'summary'
  /** Task name. */
  | 'name'
  /** Completion percentage. */
  | 'percentDone'
  /** Human-readable task kind, such as Task, Summary, or Milestone. */
  | 'taskType'
  /** Human-readable task status. */
  | 'status'
  /** Scheduled task start date, formatted through `gantt.dateFormats.tooltip`. */
  | 'startDate'
  /** Scheduled task end date, formatted through `gantt.dateFormats.tooltip`. */
  | 'endDate'
  /** Duration in days with a singular/plural day suffix. */
  | 'duration'
  /** Scheduling mode label, either Auto Scheduled or Manually Scheduled. */
  | 'taskMode'
  /** Scheduling warnings joined into one tooltip line. Skipped when empty. */
  | 'schedulingWarnings'
  /** Formatted task cost. Skipped when empty. */
  | 'cost'
  /** Comma-separated assignee names. Skipped when empty. */
  | 'assignees';
```

## `GanttTaskTooltipHook`

<span class="api-kind">type</span>

Callback that replaces the task-bar tooltip body below the always-visible task title.
Return `null` or `undefined` to fall back to `taskTooltipFields` or the default tooltip.

```ts
export type GanttTaskTooltipHook = (context: GanttTaskTooltipContext) => string | null | undefined;
```

**Related types:** [`GanttTaskTooltipContext`](/api/gantt/plugin/#gantttasktooltipcontext)

## `GanttTimeRange`

<span class="api-kind">interface</span>

A highlighted date range rendered as a coloured band on the timeline.
Use to mark sprints, milestones windows, or other periods of interest.

```ts
export interface GanttTimeRange {
  /** Unique identifier. */
  readonly id: string;
  /** Range start date (inclusive). */
  readonly startDate: ISODateString;
  /** Range end date (inclusive). */
  readonly endDate: ISODateString;
  /** Optional label displayed inside the range band. */
  readonly label?: string;
  /** Optional CSS colour for the range band. */
  readonly color?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique identifier. |
| `startDate` | `ISODateString` | Yes | — | Range start date (inclusive). |
| `endDate` | `ISODateString` | Yes | — | Range end date (inclusive). |
| `label` | `string \| undefined` | No | — | Optional label displayed inside the range band. |
| `color` | `string \| undefined` | No | — | Optional CSS colour for the range band. |

## `GanttWarningLabelsConfig`

<span class="api-kind">interface</span>

```ts
export interface GanttWarningLabelsConfig {
  readonly scheduler?: Partial<Record<GanttSchedulerWarningLabelKey, GanttMessageTemplate>>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `scheduler` | `Partial<Record<GanttSchedulerWarningLabelKey, GanttMessageTemplate>> \| undefined` | No | — |  |

**Related types:** [`GanttMessageTemplate`](/api/gantt/plugin/#ganttmessagetemplate), [`GanttSchedulerWarningLabelKey`](/api/gantt/plugin/#ganttschedulerwarninglabelkey)

## `hasCustomGanttEditorDateFormat`

<span class="api-kind">function</span>

```ts
export function hasCustomGanttEditorDateFormat(project: Pick<GanttPluginConfig, 'dateFormats'> | null | undefined): boolean;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `Pick<GanttPluginConfig, "dateFormats"> \| null \| undefined` | Yes | — |  |

**Related types:** [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig)

## `parseGanttDateInput`

<span class="api-kind">function</span>

```ts
export function parseGanttDateInput(value: unknown, project: Pick<GanttPluginConfig, 'timeZone' | 'dateFormats'> | null | undefined, surface: GanttDateFormatSurface, field?: string): ISODateString | ISODateTimeString | null;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `value` | `unknown` | Yes | — |  |
| `project` | `Pick<GanttPluginConfig, "timeZone" \| "dateFormats"> \| null \| undefined` | Yes | — |  |
| `surface` | `GanttDateFormatSurface` | Yes | — |  |
| `field` | `string \| undefined` | No | — |  |

**Related types:** [`GanttDateFormatSurface`](/api/gantt/plugin/#ganttdateformatsurface), [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig)

## `resolveGanttErrorLabel`

<span class="api-kind">function</span>

```ts
export function resolveGanttErrorLabel<TCategory extends keyof typeof DEFAULT_GANTT_ERROR_LABELS, TKey extends keyof (typeof DEFAULT_GANTT_ERROR_LABELS)[TCategory]>(labels: GanttRuntimeLabelsConfig | null | undefined, category: TCategory, key: TKey, context: GanttMessageContext = {}): string;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `labels` | `GanttRuntimeLabelsConfig \| null \| undefined` | Yes | — |  |
| `category` | `TCategory` | Yes | — |  |
| `key` | `TKey` | Yes | — |  |
| `context` | `GanttMessageContext` | No | `{}` |  |

**Related types:** [`GanttMessageContext`](/api/gantt/plugin/#ganttmessagecontext), [`GanttRuntimeLabelsConfig`](/api/gantt/plugin/#ganttruntimelabelsconfig)

## `resolveGanttWarningLabel`

<span class="api-kind">function</span>

```ts
export function resolveGanttWarningLabel<TCategory extends keyof typeof DEFAULT_GANTT_WARNING_LABELS, TKey extends keyof (typeof DEFAULT_GANTT_WARNING_LABELS)[TCategory]>(labels: GanttRuntimeLabelsConfig | null | undefined, category: TCategory, key: TKey, context: GanttMessageContext = {}): string;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `labels` | `GanttRuntimeLabelsConfig \| null \| undefined` | Yes | — |  |
| `category` | `TCategory` | Yes | — |  |
| `key` | `TKey` | Yes | — |  |
| `context` | `GanttMessageContext` | No | `{}` |  |

**Related types:** [`GanttMessageContext`](/api/gantt/plugin/#ganttmessagecontext), [`GanttRuntimeLabelsConfig`](/api/gantt/plugin/#ganttruntimelabelsconfig)

## `shouldReplayRawGanttTaskPatch`

<span class="api-kind">function</span>

```ts
export function shouldReplayRawGanttTaskPatch(eventTypes: readonly string[], model: unknown, field: string): field is keyof TaskUpdate;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `eventTypes` | `readonly string[]` | Yes | — |  |
| `model` | `unknown` | Yes | — |  |
| `field` | `string` | Yes | — |  |

**Related types:** [`TaskUpdate`](/api/gantt/data-model/#taskupdate)

## `TaskGridConfig`

<span class="api-kind">interface</span>

Complete grid configuration bundle containing projected row data, the
timeline scale config, and scheduling results.

```ts
export interface TaskGridConfig {
  /** The projected grid rows (one per visible task). */
  readonly source: readonly DataType[];
  /** Timeline scale configuration for the gantt column. */
  readonly scale: TaskGridScaleConfig;
  /** Scheduling engine output. */
  readonly scheduling: SchedulingResult;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `source` | `readonly DataType[]` | Yes | — | The projected grid rows (one per visible task). |
| `scale` | `TaskGridScaleConfig` | Yes | — | Timeline scale configuration for the gantt column. |
| `scheduling` | `SchedulingResult` | Yes | — | Scheduling engine output. |

**Related types:** [`SchedulingResult`](/api/gantt/scheduling/#schedulingresult), [`TaskGridScaleConfig`](/api/gantt/plugin/#taskgridscaleconfig)

## `TaskGridScaleConfig`

<span class="api-kind">interface</span>

Pre-computed timeline scale and view-model for the gantt grid.

```ts
export interface TaskGridScaleConfig {
  /** The timeline scale instance used for coordinate calculations. */
  readonly scale: TimelineScale;
  /** The derived view-model consumed by the gantt column type renderer. */
  readonly timeline: GanttTimelineViewModel;
  /** ISO date string of the timeline start boundary. */
  readonly startDate: ISODateString;
  /** ISO date string of the timeline end boundary. */
  readonly endDate: ISODateString;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `scale` | `TimelineScale` | Yes | — | The timeline scale instance used for coordinate calculations. |
| `timeline` | `GanttTimelineViewModel` | Yes | — | The derived view-model consumed by the gantt column type renderer. |
| `startDate` | `ISODateString` | Yes | — | ISO date string of the timeline start boundary. |
| `endDate` | `ISODateString` | Yes | — | ISO date string of the timeline end boundary. |

**Related types:** [`TimelineScale`](/api/gantt/visuals/#timelinescale)

## `TaskGridScaleOptions`

<span class="api-kind">interface</span>

```ts
export interface TaskGridScaleOptions {
  /** First day of week for weekly timeline cells. `0` is Sunday and `1` is Monday. Defaults to Sunday. */
  readonly weekStartsOn?: 0 | 1;
  /** Optional inclusive bounds overriding the task-derived timeline range. */
  readonly timelineRange?: GanttTimelineRange;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `weekStartsOn` | `0 \| 1 \| undefined` | No | — | First day of week for weekly timeline cells. `0` is Sunday and `1` is Monday. Defaults to Sunday. |
| `timelineRange` | `GanttTimelineRange \| undefined` | No | — | Optional inclusive bounds overriding the task-derived timeline range. |

**Related types:** [`GanttTimelineRange`](/api/gantt/visuals/#gantttimelinerange)

---

# Scheduling And Diagnostics

URL: https://pro.rv-grid.com/api/gantt/scheduling/
Source: src/content/docs/api/gantt/scheduling.md
Description: Public RevoGrid Gantt API for scheduling and diagnostics.
Surface: gantt

This page documents 38 public symbols exported by `@revolist/gantt`.

## `AutoDependencyAdjustment`

<span class="api-kind">interface</span>

An auto-scheduled task was moved by dependencies while warning mode is enabled.

```ts
export interface AutoDependencyAdjustment {
  readonly code: 'auto-dependency-adjustment';
  readonly taskId: TaskId;
  readonly dependencyId: string;
  readonly dependencyType: DependencyEntity['type'];
  readonly requiredStartDate: ISODateString;
  readonly authoredStartDate: ISODateString;
  readonly resolvedStartDate: ISODateString;
  readonly message: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"auto-dependency-adjustment"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `dependencyId` | `string` | Yes | — |  |
| `dependencyType` | `DependencyType` | Yes | — |  |
| `requiredStartDate` | `ISODateString` | Yes | — |  |
| `authoredStartDate` | `ISODateString` | Yes | — |  |
| `resolvedStartDate` | `ISODateString` | Yes | — |  |
| `message` | `string` | Yes | — |  |

**Related types:** [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`TaskId`](/api/gantt/data-model/#taskid)

## `calculateTaskStatus`

<span class="api-kind">function</span>

Calculates Microsoft Project-style reporting status without changing schedule data.

```ts
export function calculateTaskStatus(task: ScheduledTask, statusDate: ISODateString, calendar: CalendarEntity | null, excludeHolidaysFromDuration: boolean): TaskStatus;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `task` | `ScheduledTask` | Yes | — |  |
| `statusDate` | `ISODateString` | Yes | — |  |
| `calendar` | `CalendarEntity \| null` | Yes | — |  |
| `excludeHolidaysFromDuration` | `boolean` | Yes | — |  |

**Related types:** [`ScheduledTask`](/api/gantt/scheduling/#scheduledtask), [`TaskStatus`](/api/gantt/data-model/#taskstatus)

## `ConstraintWindowConflict`

<span class="api-kind">interface</span>

A soft constraint (window-based) conflicted with a dependency requirement.

```ts
export interface ConstraintWindowConflict {
  readonly code: 'constraint-window-conflict';
  readonly taskId: TaskId;
  readonly constraintType: Exclude<
    TaskConstraintType,
    'must-start-on' | 'must-finish-on'
  >;
  readonly constraintDate: ISODateString;
  readonly requiredStartDate: ISODateString;
  readonly attemptedStartDate: ISODateString;
  readonly resolvedStartDate: ISODateString;
  readonly message: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"constraint-window-conflict"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `constraintType` | `"start-no-earlier-than" \| "start-no-later-than" \| "finish-no-earlier-than" \| "finish-no-later-than"` | Yes | — |  |
| `constraintDate` | `ISODateString` | Yes | — |  |
| `requiredStartDate` | `ISODateString` | Yes | — |  |
| `attemptedStartDate` | `ISODateString` | Yes | — |  |
| `resolvedStartDate` | `ISODateString` | Yes | — |  |
| `message` | `string` | Yes | — |  |

**Related types:** [`TaskConstraintType`](/api/gantt/data-model/#taskconstrainttype), [`TaskId`](/api/gantt/data-model/#taskid)

## `createDependencyGraph`

<span class="api-kind">function</span>

Builds a {@link DependencyGraph} from the given tasks and dependencies.
Dependencies that reference tasks not in `taskIds` are silently ignored.

```ts
export function createDependencyGraph(taskIds: readonly TaskId[], dependencies: readonly DependencyEntity[]): DependencyGraph;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `taskIds` | `readonly string[]` | Yes | — | - All task ids to include in the graph. |
| `dependencies` | `readonly DependencyEntity[]` | Yes | — | - Dependency links to process. |

**Returns:** A new dependency graph ready for topological sorting.

**Related types:** [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`DependencyGraph`](/api/gantt/scheduling/#dependencygraph), [`TaskId`](/api/gantt/data-model/#taskid)

## `createSchedulerEngine`

<span class="api-kind">function</span>

Creates the scheduler engine facade used by grid state, mutation services, tests, and demos.

```ts
export function createSchedulerEngine(): SchedulerEngine;
```

**Related types:** [`SchedulerEngine`](/api/gantt/scheduling/#schedulerengine)

## `DeadlineMissedConflict`

<span class="api-kind">interface</span>

A task finishes after its deadline date.

```ts
export interface DeadlineMissedConflict {
  readonly code: 'deadline-missed';
  readonly taskId: TaskId;
  readonly deadlineDate: ISODateString;
  readonly resolvedFinishDate: ISODateString;
  readonly message: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"deadline-missed"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `deadlineDate` | `ISODateString` | Yes | — |  |
| `resolvedFinishDate` | `ISODateString` | Yes | — |  |
| `message` | `string` | Yes | — |  |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `DependencyConstraintConflict`

<span class="api-kind">interface</span>

A dependency requirement conflicted with an explicit constraint on the same task.

```ts
export interface DependencyConstraintConflict {
  readonly code: 'dependency-constraint-conflict';
  readonly taskId: TaskId;
  readonly dependencyId: string;
  readonly dependencyType: DependencyEntity['type'];
  readonly constraintType: TaskConstraintType;
  readonly requiredStartDate: ISODateString;
  readonly resolvedStartDate: ISODateString;
  readonly message: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"dependency-constraint-conflict"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `dependencyId` | `string` | Yes | — |  |
| `dependencyType` | `DependencyType` | Yes | — |  |
| `constraintType` | `TaskConstraintType` | Yes | — |  |
| `requiredStartDate` | `ISODateString` | Yes | — |  |
| `resolvedStartDate` | `ISODateString` | Yes | — |  |
| `message` | `string` | Yes | — |  |

**Related types:** [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`TaskConstraintType`](/api/gantt/data-model/#taskconstrainttype), [`TaskId`](/api/gantt/data-model/#taskid)

## `DependencyCycle`

<span class="api-kind">interface</span>

Represents a cycle detected in the dependency graph.
Contains the task ids that form the cycle.

```ts
export interface DependencyCycle {
  /** Task ids involved in the cycle. */
  readonly taskIds: readonly TaskId[];
  /** Dependency ids that form the detected cycle path. */
  readonly dependencyIds: readonly DependencyId[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskIds` | `readonly string[]` | Yes | — | Task ids involved in the cycle. |
| `dependencyIds` | `readonly string[]` | Yes | — | Dependency ids that form the detected cycle path. |

**Related types:** [`DependencyId`](/api/gantt/data-model/#dependencyid), [`TaskId`](/api/gantt/data-model/#taskid)

## `DependencyGraph`

<span class="api-kind">interface</span>

A directed acyclic graph of task dependencies.
Maps each task to its outgoing dependencies and tracks in-degree counts
for topological sorting.

```ts
export interface DependencyGraph {
  /** All task ids participating in the graph. */
  readonly taskIds: readonly TaskId[];
  /** Outgoing dependencies keyed by predecessor task id. */
  readonly outgoingByTaskId: ReadonlyMap<TaskId, readonly DependencyEntity[]>;
  /** Number of incoming dependencies for each task. */
  readonly incomingCountByTaskId: ReadonlyMap<TaskId, number>;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskIds` | `readonly string[]` | Yes | — | All task ids participating in the graph. |
| `outgoingByTaskId` | `ReadonlyMap<string, readonly DependencyEntity[]>` | Yes | — | Outgoing dependencies keyed by predecessor task id. |
| `incomingCountByTaskId` | `ReadonlyMap<string, number>` | Yes | — | Number of incoming dependencies for each task. |

**Related types:** [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`TaskId`](/api/gantt/data-model/#taskid)

## `FinishConstraintConflict`

<span class="api-kind">interface</span>

Final resolved finish violates a finish-based constraint (commonly due to splits).

```ts
export interface FinishConstraintConflict {
  readonly code: 'finish-constraint-conflict';
  readonly taskId: TaskId;
  readonly constraintType: Extract<TaskConstraintType, 'must-finish-on' | 'finish-no-earlier-than' | 'finish-no-later-than'>;
  readonly constraintDate: ISODateString;
  readonly resolvedStartDate: ISODateString;
  readonly resolvedFinishDate: ISODateString;
  readonly message: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"finish-constraint-conflict"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `constraintType` | `"finish-no-earlier-than" \| "finish-no-later-than" \| "must-finish-on"` | Yes | — |  |
| `constraintDate` | `ISODateString` | Yes | — |  |
| `resolvedStartDate` | `ISODateString` | Yes | — |  |
| `resolvedFinishDate` | `ISODateString` | Yes | — |  |
| `message` | `string` | Yes | — |  |

**Related types:** [`TaskConstraintType`](/api/gantt/data-model/#taskconstrainttype), [`TaskId`](/api/gantt/data-model/#taskid)

## `HardConstraintConflict`

<span class="api-kind">interface</span>

A hard constraint (`must-start-on` / `must-finish-on`) could not be honoured.

```ts
export interface HardConstraintConflict {
  readonly code: 'hard-constraint-conflict';
  readonly taskId: TaskId;
  readonly constraintType: Extract<TaskConstraintType, 'must-start-on' | 'must-finish-on'>;
  readonly constraintDate: ISODateString;
  readonly resolvedStartDate: ISODateString;
  readonly message: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"hard-constraint-conflict"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `constraintType` | `"must-start-on" \| "must-finish-on"` | Yes | — |  |
| `constraintDate` | `ISODateString` | Yes | — |  |
| `resolvedStartDate` | `ISODateString` | Yes | — |  |
| `message` | `string` | Yes | — |  |

**Related types:** [`TaskConstraintType`](/api/gantt/data-model/#taskconstrainttype), [`TaskId`](/api/gantt/data-model/#taskid)

## `InvalidTaskConstraintIssue`

<span class="api-kind">interface</span>

A task constraint could not be satisfied as specified.

```ts
export interface InvalidTaskConstraintIssue {
  readonly code: 'invalid-task-constraint';
  readonly message: string;
  readonly taskIds: readonly TaskId[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"invalid-task-constraint"` | Yes | — |  |
| `message` | `string` | Yes | — |  |
| `taskIds` | `readonly string[]` | Yes | — |  |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `ManualDependencyViolation`

<span class="api-kind">interface</span>

A manually scheduled task violates an active dependency requirement.

```ts
export interface ManualDependencyViolation {
  readonly code: 'manual-dependency-violation';
  readonly taskId: TaskId;
  readonly dependencyId: string;
  readonly dependencyType: DependencyEntity['type'];
  readonly requiredStartDate: ISODateString;
  readonly authoredStartDate: ISODateString;
  readonly resolvedStartDate: ISODateString;
  readonly message: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"manual-dependency-violation"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `dependencyId` | `string` | Yes | — |  |
| `dependencyType` | `DependencyType` | Yes | — |  |
| `requiredStartDate` | `ISODateString` | Yes | — |  |
| `authoredStartDate` | `ISODateString` | Yes | — |  |
| `resolvedStartDate` | `ISODateString` | Yes | — |  |
| `message` | `string` | Yes | — |  |

**Related types:** [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`TaskId`](/api/gantt/data-model/#taskid)

## `MissingDependencyTaskIssue`

<span class="api-kind">interface</span>

A dependency references a task that does not exist in the project.

```ts
export interface MissingDependencyTaskIssue {
  readonly code: 'missing-dependency-task';
  readonly message: string;
  readonly taskIds: readonly TaskId[];
  readonly dependencyIds: readonly string[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"missing-dependency-task"` | Yes | — |  |
| `message` | `string` | Yes | — |  |
| `taskIds` | `readonly string[]` | Yes | — |  |
| `dependencyIds` | `readonly string[]` | Yes | — |  |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `ResolvedSchedulerOptions`

<span class="api-kind">interface</span>

```ts
export interface ResolvedSchedulerOptions {
  readonly labels?: GanttRuntimeLabelsConfig;
  readonly excludeHolidaysFromDuration: boolean;
  readonly taskModeDefault: 'auto' | 'manual';
  readonly autoDependencyViolationBehavior: 'clamp' | 'warn';
  readonly manualDependencyViolationBehavior: 'warn' | 'ignore';
  readonly lagCalendar: 'calendar-days' | 'working-days';
  readonly scheduleFrom: 'project-start' | 'project-finish';
  readonly projectStartDate?: ISODateString;
  readonly projectFinishDate?: ISODateString;
  readonly resourceLeveling: 'off' | 'warn' | 'auto';
  readonly resourceLevelingWithinSlack: boolean;
  readonly effortModeDefault: TaskEffortMode;
  readonly progressRescheduling: 'off' | 'remaining-duration';
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `labels` | `GanttRuntimeLabelsConfig \| undefined` | No | — |  |
| `excludeHolidaysFromDuration` | `boolean` | Yes | — |  |
| `taskModeDefault` | `"manual" \| "auto"` | Yes | — |  |
| `autoDependencyViolationBehavior` | `"clamp" \| "warn"` | Yes | — |  |
| `manualDependencyViolationBehavior` | `"warn" \| "ignore"` | Yes | — |  |
| `lagCalendar` | `"calendar-days" \| "working-days"` | Yes | — |  |
| `scheduleFrom` | `"project-start" \| "project-finish"` | Yes | — |  |
| `projectStartDate` | `ISODateString \| undefined` | No | — |  |
| `projectFinishDate` | `ISODateString \| undefined` | No | — |  |
| `resourceLeveling` | `"auto" \| "warn" \| "off"` | Yes | — |  |
| `resourceLevelingWithinSlack` | `boolean` | Yes | — |  |
| `effortModeDefault` | `TaskEffortMode` | Yes | — |  |
| `progressRescheduling` | `"off" \| "remaining-duration"` | Yes | — |  |

**Related types:** [`GanttRuntimeLabelsConfig`](/api/gantt/plugin/#ganttruntimelabelsconfig), [`TaskEffortMode`](/api/gantt/data-model/#taskeffortmode)

## `resolveTaskEdit`

<span class="api-kind">function</span>

Validates and resolves a user-initiated inline edit on a task field.
Handles parsing, schedule-aware validation, and derived-field protection.

```ts
export function resolveTaskEdit(task: TaskEntity, scheduledTask: ScheduledTask, field: string, value: unknown, options: TaskEditOptions = {}): TaskEditResult;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `task` | `TaskEntity` | Yes | — |  |
| `scheduledTask` | `ScheduledTask` | Yes | — |  |
| `field` | `string` | Yes | — |  |
| `value` | `unknown` | Yes | — |  |
| `options` | `TaskEditOptions` | No | `{}` |  |

**Related types:** [`ScheduledTask`](/api/gantt/scheduling/#scheduledtask), [`TaskEditOptions`](/api/gantt/scheduling/#taskeditoptions), [`TaskEditResult`](/api/gantt/scheduling/#taskeditresult), [`TaskEntity`](/api/gantt/data-model/#taskentity)

## `ResourceLevelingAdjustmentConflict`

<span class="api-kind">interface</span>

Optional resource leveling shifted a task from its dependency/constraint date.

```ts
export interface ResourceLevelingAdjustmentConflict {
  readonly code: 'resource-leveling-adjustment';
  readonly taskId: TaskId;
  readonly resourceId?: ResourceId;
  readonly previousStartDate: ISODateString;
  readonly previousEndDate: ISODateString;
  readonly resolvedStartDate: ISODateString;
  readonly resolvedEndDate: ISODateString;
  readonly message: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"resource-leveling-adjustment"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `resourceId` | `string \| undefined` | No | — |  |
| `previousStartDate` | `ISODateString` | Yes | — |  |
| `previousEndDate` | `ISODateString` | Yes | — |  |
| `resolvedStartDate` | `ISODateString` | Yes | — |  |
| `resolvedEndDate` | `ISODateString` | Yes | — |  |
| `message` | `string` | Yes | — |  |

**Related types:** [`ResourceId`](/api/gantt/data-model/#resourceid), [`TaskId`](/api/gantt/data-model/#taskid)

## `ResourceOverallocationConflict`

<span class="api-kind">interface</span>

One resource is assigned above capacity on a scheduled date.

```ts
export interface ResourceOverallocationConflict {
  readonly code: 'resource-overallocation';
  readonly taskId: TaskId;
  readonly resourceId: ResourceId;
  readonly date: ISODateString;
  readonly allocatedUnits: number;
  readonly capacityUnits: number;
  readonly taskIds: readonly TaskId[];
  readonly message: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"resource-overallocation"` | Yes | — |  |
| `taskId` | `string` | Yes | — |  |
| `resourceId` | `string` | Yes | — |  |
| `date` | `ISODateString` | Yes | — |  |
| `allocatedUnits` | `number` | Yes | — |  |
| `capacityUnits` | `number` | Yes | — |  |
| `taskIds` | `readonly string[]` | Yes | — |  |
| `message` | `string` | Yes | — |  |

**Related types:** [`ResourceId`](/api/gantt/data-model/#resourceid), [`TaskId`](/api/gantt/data-model/#taskid)

## `ScheduledTask`

<span class="api-kind">interface</span>

A task after being processed by the scheduling engine.
Extends the raw {@link TaskEntity} with computed scheduling metadata.

```ts
export interface ScheduledTask extends Omit<TaskEntity, 'type' | 'manuallyScheduled' | 'inactive'> {
  /** Resolved task type. */
  readonly type: ScheduledTaskKind;
  /** Whether the task was manually scheduled (bypassing auto-scheduling). */
  readonly manuallyScheduled: boolean;
  /** Whether the task is excluded from scheduling. */
  readonly inactive: boolean;
  /** Microsoft Project-style calculated task status. */
  readonly status: TaskStatus;
  /** How the scheduler determined this task's dates. */
  readonly scheduleOrigin: ScheduleOrigin;
  /** Earliest scheduled start after dependencies, constraints, actuals, and leveling are applied. */
  readonly earlyStartDate: ISODateString;
  /** Earliest scheduled finish after dependencies, constraints, actuals, and leveling are applied. */
  readonly earlyFinishDate: ISODateString;
  /** Latest start that preserves the computed project finish. */
  readonly lateStartDate: ISODateString;
  /** Latest finish that preserves the computed project finish. */
  readonly lateFinishDate: ISODateString;
  /** Total slack (float) in calendar days before the task delays the project end. */
  readonly totalSlackDays: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `type` | `ScheduledTaskKind` | Yes | — | Resolved task type. |
| `manuallyScheduled` | `boolean` | Yes | — | Whether the task was manually scheduled (bypassing auto-scheduling). |
| `inactive` | `boolean` | Yes | — | Whether the task is excluded from scheduling. |
| `status` | `TaskStatus` | Yes | — | Microsoft Project-style calculated task status. |
| `scheduleOrigin` | `ScheduleOrigin` | Yes | — | How the scheduler determined this task's dates. |
| `earlyStartDate` | `ISODateString` | Yes | — | Earliest scheduled start after dependencies, constraints, actuals, and leveling are applied. |
| `earlyFinishDate` | `ISODateString` | Yes | — | Earliest scheduled finish after dependencies, constraints, actuals, and leveling are applied. |
| `lateStartDate` | `ISODateString` | Yes | — | Latest start that preserves the computed project finish. |
| `lateFinishDate` | `ISODateString` | Yes | — | Latest finish that preserves the computed project finish. |
| `totalSlackDays` | `number` | Yes | — | Total slack (float) in calendar days before the task delays the project end. |

**Related types:** [`ScheduleOrigin`](/api/gantt/scheduling/#scheduleorigin), [`ScheduledTaskKind`](/api/gantt/scheduling/#scheduledtaskkind), [`TaskEntity`](/api/gantt/data-model/#taskentity), [`TaskStatus`](/api/gantt/data-model/#taskstatus)

## `ScheduledTaskKind`

<span class="api-kind">type</span>

Classification of a scheduled task's type after engine processing.

```ts
export type ScheduledTaskKind = 'task' | 'summary' | 'milestone';
```

## `ScheduleOrigin`

<span class="api-kind">type</span>

Indicates how the scheduler determined a task's dates.
This is intentionally user-facing: row/tooling code can explain whether a
task moved because of dependencies, a hard constraint, manual scheduling,
entered actuals, or optional resource leveling.

```ts
export type ScheduleOrigin = 'normalized' | 'dependency' | 'constraint' | 'manual' | 'rollup' | 'actual' | 'leveling';
```

## `SchedulerConflict`

<span class="api-kind">type</span>

Union of all conflict types the scheduler can report.

```ts
export type SchedulerConflict =
  | ConstraintWindowConflict
  | DependencyConstraintConflict
  | HardConstraintConflict
  | FinishConstraintConflict
  | ManualDependencyViolation
  | AutoDependencyAdjustment
  | DeadlineMissedConflict
  | ResourceOverallocationConflict
  | ResourceLevelingAdjustmentConflict;
```

**Related types:** [`AutoDependencyAdjustment`](/api/gantt/scheduling/#autodependencyadjustment), [`ConstraintWindowConflict`](/api/gantt/scheduling/#constraintwindowconflict), [`DeadlineMissedConflict`](/api/gantt/scheduling/#deadlinemissedconflict), [`DependencyConstraintConflict`](/api/gantt/scheduling/#dependencyconstraintconflict), [`FinishConstraintConflict`](/api/gantt/scheduling/#finishconstraintconflict), [`HardConstraintConflict`](/api/gantt/scheduling/#hardconstraintconflict), [`ManualDependencyViolation`](/api/gantt/scheduling/#manualdependencyviolation), [`ResourceLevelingAdjustmentConflict`](/api/gantt/scheduling/#resourcelevelingadjustmentconflict), [`ResourceOverallocationConflict`](/api/gantt/scheduling/#resourceoverallocationconflict)

## `SchedulerCycleIssue`

<span class="api-kind">interface</span>

A dependency cycle was detected during scheduling.

```ts
export interface SchedulerCycleIssue {
  readonly code: 'dependency-cycle';
  /** Human-readable description of the cycle. */
  readonly message: string;
  /** Task ids involved in the cycle. */
  readonly taskIds: readonly TaskId[];
  /** Dependency ids that form the detected cycle path. */
  readonly dependencyIds: readonly string[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `"dependency-cycle"` | Yes | — |  |
| `message` | `string` | Yes | — | Human-readable description of the cycle. |
| `taskIds` | `readonly string[]` | Yes | — | Task ids involved in the cycle. |
| `dependencyIds` | `readonly string[]` | Yes | — | Dependency ids that form the detected cycle path. |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `SchedulerDataValidationCode`

<span class="api-kind">type</span>

```ts
export type SchedulerDataValidationCode =
  | 'duplicate-task-id'
  | 'duplicate-dependency-id'
  | 'duplicate-resource-id'
  | 'duplicate-assignment-id'
  | 'missing-task-calendar'
  | 'missing-resource-calendar'
  | 'missing-assignment-task'
  | 'missing-assignment-resource'
  | 'invalid-working-calendar'
  | 'invalid-task-date-range'
  | 'invalid-task-progress'
  | 'invalid-task-work'
  | 'invalid-task-units'
  | 'invalid-assignment-work'
  | 'invalid-assignment-units'
  | 'invalid-resource-units'
  | 'invalid-resource-cost';
```

## `SchedulerDataValidationIssue`

<span class="api-kind">interface</span>

Data is structurally invalid but can usually still be rendered for correction.

```ts
export interface SchedulerDataValidationIssue {
  readonly code: SchedulerDataValidationCode;
  readonly message: string;
  readonly taskIds: readonly TaskId[];
  readonly dependencyIds: readonly string[];
  readonly resourceIds: readonly ResourceId[];
  readonly assignmentIds: readonly string[];
  readonly calendarIds: readonly CalendarId[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `code` | `SchedulerDataValidationCode` | Yes | — |  |
| `message` | `string` | Yes | — |  |
| `taskIds` | `readonly string[]` | Yes | — |  |
| `dependencyIds` | `readonly string[]` | Yes | — |  |
| `resourceIds` | `readonly string[]` | Yes | — |  |
| `assignmentIds` | `readonly string[]` | Yes | — |  |
| `calendarIds` | `readonly CalendarId[]` | Yes | — |  |

**Related types:** [`ResourceId`](/api/gantt/data-model/#resourceid), [`SchedulerDataValidationCode`](/api/gantt/scheduling/#schedulerdatavalidationcode), [`TaskId`](/api/gantt/data-model/#taskid)

## `SchedulerEngine`

<span class="api-kind">interface</span>

The scheduling engine recalculates task dates based on dependencies,
constraints, and calendar rules. It also performs validation and
computes the critical path.

```ts
export interface SchedulerEngine {
  /**
   * Recalculates the full project schedule.
   * @param project - Complete project snapshot.
   * @param options - Optional scheduling parameters.
   * @returns Computed schedule with issues and conflicts.
   */
  recalculate(project: ProjectSnapshot, options?: SchedulerOptions): SchedulingResult;
  /**
   * Validates task/dependency data without running a full schedule.
   * @returns Any structural issues found.
   */
  validate(
    tasks: readonly TaskEntity[],
    dependencies: readonly DependencyEntity[],
    calendars: readonly CalendarEntity[],
    resources?: readonly ResourceEntity[],
    assignments?: readonly AssignmentEntity[],
    labels?: GanttRuntimeLabelsConfig,
  ): readonly SchedulerIssue[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `recalculate(project: ProjectSnapshot, options?: SchedulerOptions)` | `SchedulingResult` | Yes | — | Recalculates the full project schedule. |
| `validate(tasks: readonly TaskEntity[], dependencies: readonly DependencyEntity[], calendars: readonly CalendarEntity[], resources?: readonly ResourceEntity[], assignments?: readonly AssignmentEntity[], labels?: GanttRuntimeLabelsConfig)` | `readonly SchedulerIssue[]` | Yes | — | Validates task/dependency data without running a full schedule. |

**Related types:** [`AssignmentEntity`](/api/gantt/data-model/#assignmententity), [`DependencyEntity`](/api/gantt/data-model/#dependencyentity), [`GanttRuntimeLabelsConfig`](/api/gantt/plugin/#ganttruntimelabelsconfig), [`ProjectSnapshot`](/api/gantt/data-model/#projectsnapshot), [`ResourceEntity`](/api/gantt/data-model/#resourceentity), [`SchedulerIssue`](/api/gantt/scheduling/#schedulerissue), [`SchedulerOptions`](/api/gantt/scheduling/#scheduleroptions), [`SchedulingResult`](/api/gantt/scheduling/#schedulingresult), [`TaskEntity`](/api/gantt/data-model/#taskentity)

## `SchedulerIssue`

<span class="api-kind">type</span>

Union of all issue types the scheduler can report.

```ts
export type SchedulerIssue =
  | SchedulerCycleIssue
  | MissingDependencyTaskIssue
  | InvalidTaskConstraintIssue
  | SchedulerDataValidationIssue;
```

**Related types:** [`InvalidTaskConstraintIssue`](/api/gantt/scheduling/#invalidtaskconstraintissue), [`MissingDependencyTaskIssue`](/api/gantt/scheduling/#missingdependencytaskissue), [`SchedulerCycleIssue`](/api/gantt/scheduling/#schedulercycleissue), [`SchedulerDataValidationIssue`](/api/gantt/scheduling/#schedulerdatavalidationissue)

## `SchedulerOptions`

<span class="api-kind">interface</span>

Options passed to {@link SchedulerEngine.recalculate}.

```ts
export interface SchedulerOptions {
  /** Labels used to resolve scheduler issue and conflict messages. */
  readonly labels?: GanttRuntimeLabelsConfig;
  /** When true, duration calculations skip holidays and non-working weekdays. */
  readonly excludeHolidaysFromDuration?: boolean;
  /** Default task mode when a source row does not explicitly set `taskMode`. */
  readonly taskModeDefault?: 'auto' | 'manual';
  /** Policy for auto dependency violations. Both modes keep effective dates dependency-valid; `warn` also emits adjustment conflicts. */
  readonly autoDependencyViolationBehavior?: 'clamp' | 'warn';
  /** Whether manually scheduled dependency violations should be reported. */
  readonly manualDependencyViolationBehavior?: 'warn' | 'ignore';
  /** Calendar basis used for dependency lag/lead. */
  readonly lagCalendar?: 'calendar-days' | 'working-days';
  /** Direction of scheduling. */
  readonly scheduleFrom?: 'project-start' | 'project-finish';
  /** Optional project start anchor used by forward scheduling policies. */
  readonly projectStartDate?: ISODateString;
  /** Optional project finish anchor used by backward scheduling policies. */
  readonly projectFinishDate?: ISODateString;
  /** Resource capacity policy. `warn` reports over-allocation; `auto` shifts eligible forward-scheduled auto tasks. */
  readonly resourceLeveling?: 'off' | 'warn' | 'auto';
  /** When true, auto-leveling only delays tasks up to their pre-leveling total slack. */
  readonly resourceLevelingWithinSlack?: boolean;
  /** Default task type used for effort calculations. */
  readonly effortModeDefault?: TaskEffortMode;
  /** Progress-aware scheduling policy for actual start and remaining work. Actual finish is always authoritative. */
  readonly progressRescheduling?: 'off' | 'remaining-duration';
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `labels` | `GanttRuntimeLabelsConfig \| undefined` | No | — | Labels used to resolve scheduler issue and conflict messages. |
| `excludeHolidaysFromDuration` | `boolean \| undefined` | No | — | When true, duration calculations skip holidays and non-working weekdays. |
| `taskModeDefault` | `"manual" \| "auto" \| undefined` | No | — | Default task mode when a source row does not explicitly set `taskMode`. |
| `autoDependencyViolationBehavior` | `"clamp" \| "warn" \| undefined` | No | — | Policy for auto dependency violations. Both modes keep effective dates dependency-valid; `warn` also emits adjustment conflicts. |
| `manualDependencyViolationBehavior` | `"warn" \| "ignore" \| undefined` | No | — | Whether manually scheduled dependency violations should be reported. |
| `lagCalendar` | `"calendar-days" \| "working-days" \| undefined` | No | — | Calendar basis used for dependency lag/lead. |
| `scheduleFrom` | `"project-start" \| "project-finish" \| undefined` | No | — | Direction of scheduling. |
| `projectStartDate` | `ISODateString \| undefined` | No | — | Optional project start anchor used by forward scheduling policies. |
| `projectFinishDate` | `ISODateString \| undefined` | No | — | Optional project finish anchor used by backward scheduling policies. |
| `resourceLeveling` | `"auto" \| "warn" \| "off" \| undefined` | No | — | Resource capacity policy. `warn` reports over-allocation; `auto` shifts eligible forward-scheduled auto tasks. |
| `resourceLevelingWithinSlack` | `boolean \| undefined` | No | — | When true, auto-leveling only delays tasks up to their pre-leveling total slack. |
| `effortModeDefault` | `TaskEffortMode \| undefined` | No | — | Default task type used for effort calculations. |
| `progressRescheduling` | `"off" \| "remaining-duration" \| undefined` | No | — | Progress-aware scheduling policy for actual start and remaining work. Actual finish is always authoritative. |

**Related types:** [`GanttRuntimeLabelsConfig`](/api/gantt/plugin/#ganttruntimelabelsconfig), [`TaskEffortMode`](/api/gantt/data-model/#taskeffortmode)

## `SchedulingResult`

<span class="api-kind">type</span>

Result of running the scheduler on a project.
Contains the computed task list, detected issues, conflicts,
and the set of dependency ids on the critical path.

```ts
export type SchedulingResult =
  | {
      readonly ok: true;
      readonly tasks: readonly ScheduledTask[];
      readonly tasksById: ReadonlyMap<TaskId, ScheduledTask>;
      readonly issues: readonly SchedulerIssue[];
      readonly conflicts: readonly SchedulerConflict[];
      readonly criticalDependencyIds: ReadonlySet<string>;
    }
  | {
      readonly ok: false;
      readonly tasks: readonly ScheduledTask[];
      readonly tasksById: ReadonlyMap<TaskId, ScheduledTask>;
      readonly issues: readonly SchedulerIssue[];
      readonly conflicts: readonly SchedulerConflict[];
      readonly criticalDependencyIds: ReadonlySet<string>;
    };
```

**Related types:** [`ScheduledTask`](/api/gantt/scheduling/#scheduledtask), [`SchedulerConflict`](/api/gantt/scheduling/#schedulerconflict), [`SchedulerIssue`](/api/gantt/scheduling/#schedulerissue), [`TaskId`](/api/gantt/data-model/#taskid)

## `TaskConstraintTypeEditValue`

<span class="api-kind">type</span>

```ts
export type TaskConstraintTypeEditValue = '' | TaskConstraintType;
```

**Related types:** [`TaskConstraintType`](/api/gantt/data-model/#taskconstrainttype)

## `TaskEditFailure`

<span class="api-kind">interface</span>

Failed task edit — contains the error code and a human-readable message.

```ts
export interface TaskEditFailure {
  readonly ok: false;
  /** Error classification: invalid field name, invalid value, or readonly derived field. */
  readonly code: 'invalid-field' | 'invalid-value' | 'readonly-derived-field';
  /** Explanation of why the edit was rejected. */
  readonly message: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `ok` | `false` | Yes | — |  |
| `code` | `"invalid-field" \| "invalid-value" \| "readonly-derived-field"` | Yes | — | Error classification: invalid field name, invalid value, or readonly derived field. |
| `message` | `string` | Yes | — | Explanation of why the edit was rejected. |

## `TaskEditLabelOverrides`

<span class="api-kind">type</span>

```ts
export type TaskEditLabelOverrides = Pick<
  GanttRuntimeLabelsConfig,
  'workflowStatus' | 'taskMode' | 'effortMode' | 'constraintType' | 'taskType' | 'errors'
>;
```

**Related types:** [`GanttRuntimeLabelsConfig`](/api/gantt/plugin/#ganttruntimelabelsconfig)

## `TaskEditOptions`

<span class="api-kind">interface</span>

```ts
export interface TaskEditOptions {
  readonly labels?: TaskEditLabelOverrides;
  readonly durationSettings?: ResolvedDurationSettings;
  readonly allowedTaskTypes?: readonly TaskType[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `labels` | `TaskEditLabelOverrides \| undefined` | No | — |  |
| `durationSettings` | `ResolvedDurationSettings \| undefined` | No | — |  |
| `allowedTaskTypes` | `readonly TaskType[] \| undefined` | No | — |  |

**Related types:** [`TaskEditLabelOverrides`](/api/gantt/scheduling/#taskeditlabeloverrides), [`TaskType`](/api/gantt/data-model/#tasktype)

## `TaskEditResult`

<span class="api-kind">type</span>

Check `ok` to distinguish a validated patch from a rejected edit.

```ts
export type TaskEditResult = TaskEditSuccess | TaskEditFailure;
```

**Related types:** [`TaskEditFailure`](/api/gantt/scheduling/#taskeditfailure), [`TaskEditSuccess`](/api/gantt/scheduling/#taskeditsuccess)

## `TaskEditSuccess`

<span class="api-kind">interface</span>

Successful task edit — contains the validated patch to apply.

```ts
export interface TaskEditSuccess {
  readonly ok: true;
  /** Validated partial update ready to be applied to the task. */
  readonly patch: TaskUpdate;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `ok` | `true` | Yes | — |  |
| `patch` | `Partial<Pick<TaskEntity, "type" \| "workflowStatus" \| "effortMode" \| "constraintType" \| "name" \| "color" \| "startDate" \| "endDate" \| "duration" \| "durationUnit" \| "durationIsElapsed" \| "workHours" \| "workUnit" \| "remainingDuration" \| "actualStartDate" \| "actualFinishDate" \| "splitRanges" \| "effortDriven" \| "progressPercent" \| "manuallyScheduled" \| "inactive" \| "priority" \| "canLevel" \| "levelingDelayDays" \| "constraintDate" \| "deadlineDate" \| "notes" \| "calendarId" \| "tags">>` | Yes | — | Validated partial update ready to be applied to the task. |

**Related types:** [`TaskUpdate`](/api/gantt/data-model/#taskupdate)

## `TaskModeEditValue`

<span class="api-kind">type</span>

```ts
export type TaskModeEditValue = 'auto' | 'manual';
```

## `topologicallySortDependencyGraph`

<span class="api-kind">function</span>

Performs a topological sort on the dependency graph using Kahn's algorithm.
If a cycle is detected, returns `ok: false` with the involved task ids.

```ts
export function topologicallySortDependencyGraph(graph: DependencyGraph): TopologicalSortResult;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `graph` | `DependencyGraph` | Yes | — | - The dependency graph to sort. |

**Returns:** Sorted task order on success, or cycle information on failure.

**Related types:** [`DependencyGraph`](/api/gantt/scheduling/#dependencygraph), [`TopologicalSortResult`](/api/gantt/scheduling/#topologicalsortresult)

## `TopologicalSortResult`

<span class="api-kind">type</span>

Result of a topological sort on a {@link DependencyGraph}.
When `ok` is `true`, `order` contains all tasks in dependency order.
When `ok` is `false`, `cycle` identifies the offending tasks.

```ts
export type TopologicalSortResult =
  | {
      readonly ok: true;
      readonly order: readonly TaskId[];
      readonly cycle: null;
    }
  | {
      readonly ok: false;
      readonly order: readonly TaskId[];
      readonly cycle: DependencyCycle;
    };
```

**Related types:** [`DependencyCycle`](/api/gantt/scheduling/#dependencycycle), [`TaskId`](/api/gantt/data-model/#taskid)

---

# Timeline And Visuals

URL: https://pro.rv-grid.com/api/gantt/visuals/
Source: src/content/docs/api/gantt/visuals.md
Description: Public RevoGrid Gantt API for timeline and visuals.
Surface: gantt

This page documents 80 public symbols exported by `@revolist/gantt`.

## `buildWbsMap`

<span class="api-kind">function</span>

Builds a map of task IDs to WBS (Work Breakdown Structure) codes based on
the canonical authored tree order and nesting depth.

```ts
export function buildWbsMap(rows: readonly TaskTreeRow[]): ReadonlyMap<TaskId, string>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `rows` | `readonly TaskTreeRow[]` | Yes | — | - Ordered rows with depth and task identity. |

**Returns:** A read-only map from task ID to its computed WBS string (e.g. "1.2.3").

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid), [`TaskTreeRow`](/api/gantt/data-model/#tasktreerow)

## `clampLevelIndex`

<span class="api-kind">function</span>

Clamps a level index to the allowed range defined by min/max level IDs.

```ts
export function clampLevelIndex(levels: readonly TimelineZoomLevel[], index: number, minLevelId: string, maxLevelId: string): number;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `levels` | `readonly TimelineZoomLevel[]` | Yes | — | - Available zoom levels. |
| `index` | `number` | Yes | — | - Proposed level index. |
| `minLevelId` | `string` | Yes | — | - Finest allowed level ID. |
| `maxLevelId` | `string` | Yes | — | - Coarsest allowed level ID. |

**Returns:** The clamped index.

**Related types:** [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `createBaselineBarLayout`

<span class="api-kind">function</span>

Computes the pixel layout for a baseline bar overlay.

```ts
export function createBaselineBarLayout(startDate: ISODateString, endDate: ISODateString, scale: TimelineScale): GanttBaselineLayout;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `startDate` | `ISODateString` | Yes | — | - Baseline start date (ISO string). |
| `endDate` | `ISODateString` | Yes | — | - Baseline end date (ISO string). |
| `scale` | `TimelineScale` | Yes | — | - The active timeline scale. |

**Returns:** A {@link GanttBaselineLayout} with x and width in pixels.

**Related types:** [`GanttBaselineLayout`](/api/gantt/visuals/#ganttbaselinelayout), [`TimelineScale`](/api/gantt/visuals/#timelinescale)

## `createGanttBarLayout`

<span class="api-kind">function</span>

Computes the pixel layout for a scheduled task's Gantt bar.

```ts
export function createGanttBarLayout(task: ScheduledTask, scale: TimelineScale, showCriticalPath = true): GanttBarLayout;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `task` | `ScheduledTask` | Yes | — | - The engine-scheduled task with dates, type, and progress. |
| `scale` | `TimelineScale` | Yes | — | - The active timeline scale used to convert dates to pixel positions. |
| `showCriticalPath` | `boolean` | No | `true` | - Whether to mark the bar as critical when the task is on the critical path. |

**Returns:** A {@link GanttBarLayout} with pixel coordinates and metadata.

**Related types:** [`GanttBarLayout`](/api/gantt/visuals/#ganttbarlayout), [`ScheduledTask`](/api/gantt/scheduling/#scheduledtask), [`TimelineScale`](/api/gantt/visuals/#timelinescale)

## `createIndicatorLayout`

<span class="api-kind">function</span>

Creates a layout descriptor for a point indicator on the Gantt row.

```ts
export function createIndicatorLayout(id: string, date: ISODateString, kind: GanttIndicatorLayout['kind'], scale: TimelineScale, label?: string, className?: string): GanttIndicatorLayout;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | - Unique identifier for the indicator. |
| `date` | `ISODateString` | Yes | — | - The date the indicator marks. |
| `kind` | `"constraint" \| "deadline" \| "custom"` | Yes | — | - Category of the indicator (deadline, constraint, or custom). |
| `scale` | `TimelineScale` | Yes | — | - The active timeline scale. |
| `label` | `string \| undefined` | No | — | - Optional display label. |
| `className` | `string \| undefined` | No | — | - Optional CSS class name. |

**Returns:** A {@link GanttIndicatorLayout} positioned on the timeline.

**Related types:** [`GanttIndicatorLayout`](/api/gantt/visuals/#ganttindicatorlayout), [`TimelineScale`](/api/gantt/visuals/#timelinescale)

## `createTimelineDateFormatContext`

<span class="api-kind">function</span>

```ts
export function createTimelineDateFormatContext(project: Pick<GanttPluginConfig, 'timeZone' | 'dateFormats'> | null | undefined, timelineContext: TimelineDateFormatterContext): GanttDateFormatContext;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `Pick<GanttPluginConfig, "timeZone" \| "dateFormats"> \| null \| undefined` | Yes | — |  |
| `timelineContext` | `TimelineDateFormatterContext` | Yes | — |  |

**Related types:** [`GanttDateFormatContext`](/api/gantt/plugin/#ganttdateformatcontext), [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig), [`TimelineDateFormatterContext`](/api/gantt/visuals/#timelinedateformattercontext)

## `createTimelineScale`

<span class="api-kind">function</span>

Creates a {@link TimelineScale} from the given configuration.

```ts
export function createTimelineScale(config: TimelineScaleConfig): TimelineScale;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `config` | `TimelineScaleConfig` | Yes | — | - Scale configuration specifying date range, tick unit, and header rows. |

**Returns:** A fully initialized timeline scale instance.

**Related types:** [`TimelineScale`](/api/gantt/visuals/#timelinescale), [`TimelineScaleConfig`](/api/gantt/visuals/#timelinescaleconfig)

## `DEFAULT_SMOOTH_WHEEL_THRESHOLD`

<span class="api-kind">constant</span>

Pixel threshold for accumulated smooth-wheel deltas before triggering a zoom step.

```ts
export const DEFAULT_SMOOTH_WHEEL_THRESHOLD: 96;
```

## `DEFAULT_TIMELINE_ZOOM_LEVELS`

<span class="api-kind">constant</span>

Default timeline zoom levels ordered from finest to coarsest. Minute-level zoom remains explicit/advanced.

```ts
export const DEFAULT_TIMELINE_ZOOM_LEVELS: readonly TimelineZoomLevel[];
```

**Related types:** [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `FALLBACK_ZOOM_LEVEL`

<span class="api-kind">constant</span>

Default zoom level used when no level is configured.

```ts
export const FALLBACK_ZOOM_LEVEL: TimelineZoomLevel;
```

**Related types:** [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `GanttBarKind`

<span class="api-kind">type</span>

Discriminator for the visual shape of a Gantt bar.

```ts
export type GanttBarKind = 'task' | 'summary' | 'milestone';
```

## `GanttBarLayout`

<span class="api-kind">interface</span>

Computed pixel layout for a single Gantt task bar, including progress and critical-path metadata.

```ts
export interface GanttBarLayout {
  /** Visual shape type of the bar. */
  readonly kind: GanttBarKind;
  /** Horizontal pixel offset from the timeline origin. */
  readonly x: number;
  /** Pixel width of the bar (minimum-clamped). */
  readonly width: number;
  /** Pixel width of the filled progress portion inside the bar. */
  readonly progressWidth: number;
  /** Horizontal center X used for milestone diamond rendering. */
  readonly milestoneCenterX: number;
  /** Whether this task lies on the critical path. */
  readonly isCritical: boolean;
  /** Total slack (float) available before the task delays the project. */
  readonly totalSlackDays: number;
  /** Visual task split gaps inside the bar. */
  readonly splitGaps: readonly GanttSplitGapLayout[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `kind` | `GanttBarKind` | Yes | — | Visual shape type of the bar. |
| `x` | `number` | Yes | — | Horizontal pixel offset from the timeline origin. |
| `width` | `number` | Yes | — | Pixel width of the bar (minimum-clamped). |
| `progressWidth` | `number` | Yes | — | Pixel width of the filled progress portion inside the bar. |
| `milestoneCenterX` | `number` | Yes | — | Horizontal center X used for milestone diamond rendering. |
| `isCritical` | `boolean` | Yes | — | Whether this task lies on the critical path. |
| `totalSlackDays` | `number` | Yes | — | Total slack (float) available before the task delays the project. |
| `splitGaps` | `readonly GanttSplitGapLayout[]` | Yes | — | Visual task split gaps inside the bar. |

**Related types:** [`GanttBarKind`](/api/gantt/visuals/#ganttbarkind), [`GanttSplitGapLayout`](/api/gantt/visuals/#ganttsplitgaplayout)

## `GanttBaselineLayout`

<span class="api-kind">interface</span>

Layout coordinates for a baseline bar overlay.

```ts
export interface GanttBaselineLayout {
  /** Horizontal pixel offset from the timeline origin. */
  readonly x: number;
  /** Pixel width of the baseline bar. */
  readonly width: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `x` | `number` | Yes | — | Horizontal pixel offset from the timeline origin. |
| `width` | `number` | Yes | — | Pixel width of the baseline bar. |

## `GanttIndicatorLayout`

<span class="api-kind">interface</span>

Layout descriptor for a single-point indicator (deadline, constraint, or custom marker) on the Gantt row.

```ts
export interface GanttIndicatorLayout {
  /** Unique identifier for this indicator instance. */
  readonly id: string;
  /** Category of the indicator. */
  readonly kind: 'deadline' | 'constraint' | 'custom';
  /** Horizontal pixel offset from the timeline origin. */
  readonly x: number;
  /** Optional display label shown on hover or beside the indicator. */
  readonly label?: string;
  /** Optional CSS class name applied to the indicator element. */
  readonly className?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique identifier for this indicator instance. |
| `kind` | `"constraint" \| "deadline" \| "custom"` | Yes | — | Category of the indicator. |
| `x` | `number` | Yes | — | Horizontal pixel offset from the timeline origin. |
| `label` | `string \| undefined` | No | — | Optional display label shown on hover or beside the indicator. |
| `className` | `string \| undefined` | No | — | Optional CSS class name applied to the indicator element. |

## `GanttSplitGapLayout`

<span class="api-kind">interface</span>

Visual gap inside a task bar where split work is paused.

```ts
export interface GanttSplitGapLayout {
  /** Stable gap id. */
  readonly id: string;
  /** Split index after scheduler normalization. */
  readonly index: number;
  /** Split start date. */
  readonly startDate: ISODateString;
  /** Split end date. */
  readonly endDate: ISODateString;
  /** Left offset relative to the task bar. */
  readonly x: number;
  /** Gap width in pixels. */
  readonly width: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Stable gap id. |
| `index` | `number` | Yes | — | Split index after scheduler normalization. |
| `startDate` | `ISODateString` | Yes | — | Split start date. |
| `endDate` | `ISODateString` | Yes | — | Split end date. |
| `x` | `number` | Yes | — | Left offset relative to the task bar. |
| `width` | `number` | Yes | — | Gap width in pixels. |

## `GanttTaskBarColor`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskBarColor {
  /** Optional class name applied to the rendered bar. */
  readonly className?: string;
  /** Main bar colour. */
  readonly barColor?: string;
  /** Progress fill colour. */
  readonly progressColor?: string;
  /** Label/content text colour. */
  readonly textColor?: string;
  /** Optional outline or border colour. */
  readonly borderColor?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `className` | `string \| undefined` | No | — | Optional class name applied to the rendered bar. |
| `barColor` | `string \| undefined` | No | — | Main bar colour. |
| `progressColor` | `string \| undefined` | No | — | Progress fill colour. |
| `textColor` | `string \| undefined` | No | — | Label/content text colour. |
| `borderColor` | `string \| undefined` | No | — | Optional outline or border colour. |

## `GanttTaskBarColorHook`

<span class="api-kind">type</span>

```ts
export type GanttTaskBarColorHook = (context: GanttTaskBarVisualContext) => GanttTaskBarColor | null | undefined;
```

**Related types:** [`GanttTaskBarColor`](/api/gantt/visuals/#gantttaskbarcolor), [`GanttTaskBarVisualContext`](/api/gantt/visuals/#gantttaskbarvisualcontext)

## `GanttTaskBarContentContext`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskBarContentContext extends GanttTaskBarVisualContext {
  readonly h: GanttCellTemplateCreateElement;
  readonly defaultContent: readonly unknown[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `h` | `HyperFunc` | Yes | — |  |
| `defaultContent` | `readonly unknown[]` | Yes | — |  |

**Related types:** [`GanttTaskBarVisualContext`](/api/gantt/visuals/#gantttaskbarvisualcontext)

## `GanttTaskBarContentHook`

<span class="api-kind">type</span>

```ts
export type GanttTaskBarContentHook = (context: GanttTaskBarContentContext) => unknown;
```

**Related types:** [`GanttTaskBarContentContext`](/api/gantt/visuals/#gantttaskbarcontentcontext)

## `GanttTaskBarVisualContext`

<span class="api-kind">interface</span>

```ts
export interface GanttTaskBarVisualContext {
  readonly row: GanttGridRow;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `row` | `GanttGridRow` | Yes | — |  |

**Related types:** [`GanttGridRow`](/api/gantt/columns/#ganttgridrow)

## `GanttTaskLabelMode`

<span class="api-kind">type</span>

```ts
export type GanttTaskLabelMode = 'none' | 'tasks' | 'all';
```

## `GanttTaskMarker`

<span class="api-kind">interface</span>

A visual marker pinned to a specific date on a task bar.
Use to flag deadlines, constraints, or custom indicators.

```ts
export interface GanttTaskMarker {
  /** Unique identifier. */
  readonly id: string;
  /** Date the marker is pinned to. */
  readonly date: ISODateString;
  /** Tooltip or label text. */
  readonly label?: string;
  /** Optional CSS class name for custom styling. */
  readonly className?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique identifier. |
| `date` | `ISODateString` | Yes | — | Date the marker is pinned to. |
| `label` | `string \| undefined` | No | — | Tooltip or label text. |
| `className` | `string \| undefined` | No | — | Optional CSS class name for custom styling. |

## `GanttTaskMarkerHook`

<span class="api-kind">type</span>

Callback that produces per-task markers for the timeline.
Invoked by the rendering pipeline for each visible task.

```ts
export type GanttTaskMarkerHook = (task: {
  readonly id: TaskId;
  readonly startDate: ISODateString;
  readonly endDate: ISODateString;
  readonly deadlineDate?: ISODateString;
  readonly constraintType?: string;
  readonly constraintDate?: ISODateString;
}) => readonly GanttTaskMarker[];
```

**Related types:** [`GanttTaskMarker`](/api/gantt/visuals/#gantttaskmarker), [`TaskId`](/api/gantt/data-model/#taskid)

## `GanttTimelineHeaderElementRenderer`

<span class="api-kind">type</span>

A runtime plugin contribution rendered after the built-in header layers.

```ts
export type GanttTimelineHeaderElementRenderer = (
  h: HyperFunc<VNode>,
  context: Readonly<GanttTimelineHeaderRenderOptions>,
) => VNodeResponse;
```

**Related types:** [`GanttTimelineHeaderRenderOptions`](/api/gantt/visuals/#gantttimelineheaderrenderoptions)

## `GanttTimelineHeaderPlugin`

<span class="api-kind">class</span>

Discoverable runtime coordinator for the Gantt timeline header.

It owns only ordered element contributions and native header invalidation;
timeline state and geometry remain owned by the Gantt timeline tools.

```ts
export class GanttTimelineHeaderPlugin extends CorePlugin {
  constructor(revogrid: HTMLRevoGridElement, providers: PluginProviders);
  createColumnTemplate(getOptions: () => GanttTimelineHeaderRenderOptions | undefined): ColumnTemplateFunc;
  render(h: HyperFunc<VNode>, options: GanttTimelineHeaderRenderOptions): VNode;
  registerElement(id: string, renderer: GanttTimelineHeaderElementRenderer): () => void;
  refresh(): void;
  destroy(): void;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `elements` | `Map<string, TimelineHeaderElementRegistration>` | Yes | `new Map<string, TimelineHeaderElementRegistration>()` |  |
| `createColumnTemplate(getOptions: () => GanttTimelineHeaderRenderOptions \| undefined)` | `ColumnTemplateFunc` | Yes | — |  |
| `render(h: HyperFunc, options: GanttTimelineHeaderRenderOptions)` | `VNode` | Yes | — |  |
| `registerElement(id: string, renderer: GanttTimelineHeaderElementRenderer)` | `() => void` | Yes | — |  |
| `refresh()` | `void` | Yes | — |  |
| `destroy()` | `void` | Yes | — |  |

**Related types:** [`GanttTimelineHeaderElementRenderer`](/api/gantt/visuals/#gantttimelineheaderelementrenderer), [`GanttTimelineHeaderRenderOptions`](/api/gantt/visuals/#gantttimelineheaderrenderoptions)

## `GanttTimelineHeaderRenderOptions`

<span class="api-kind">interface</span>

Resolved, immutable geometry consumed by the timeline header renderer.

```ts
export interface GanttTimelineHeaderRenderOptions {
  readonly totalWidth: number;
  readonly headerRows: readonly TimelineHeaderRowModel[];
  readonly nonWorkingHeaderRanges?: readonly TimelineHeaderHighlightRange[];
  readonly activeTaskInteractionRange?: TimelineTaskInteractionRange | null;
  readonly flagLines?: readonly TimelineFlagLine[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `totalWidth` | `number` | Yes | — |  |
| `headerRows` | `readonly TimelineHeaderRowModel[]` | Yes | — |  |
| `nonWorkingHeaderRanges` | `readonly TimelineHeaderHighlightRange[] \| undefined` | No | — |  |
| `activeTaskInteractionRange` | `TimelineTaskInteractionRange \| null \| undefined` | No | — |  |
| `flagLines` | `readonly TimelineFlagLine[] \| undefined` | No | — |  |

**Related types:** [`TimelineFlagLine`](/api/gantt/visuals/#timelineflagline), [`TimelineHeaderHighlightRange`](/api/gantt/visuals/#timelineheaderhighlightrange), [`TimelineHeaderRowModel`](/api/gantt/visuals/#timelineheaderrowmodel), [`TimelineTaskInteractionRange`](/api/gantt/visuals/#timelinetaskinteractionrange)

## `GanttTimelineRange`

<span class="api-kind">interface</span>

Inclusive user-selected timeline bounds.

```ts
export interface GanttTimelineRange {
  readonly startDate: ISODateString;
  readonly endDate: ISODateString;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `startDate` | `ISODateString` | Yes | — |  |
| `endDate` | `ISODateString` | Yes | — |  |

## `GanttVisualConfig`

<span class="api-kind">interface</span>

Controls visual overlays and decorations on the Gantt timeline.

```ts
export interface GanttVisualConfig {
  /** Percent Done task-table rendering. Defaults to `'bar'`. */
  readonly percentDoneMode?: GanttPercentDoneColumnMode;
  /** Show dependency arrows between task bars. Enabled by default. */
  readonly showDependencies?: boolean;
  /** Show baseline bars beneath task bars for comparison. */
  readonly showBaseline?: boolean;
  /** Highlight tasks on the critical path. */
  readonly showCriticalPath?: boolean;
  /**
   * Display task names as labels on timeline bars.
   * Omit for regular task/milestone labels only, set `false` to hide built-in labels,
   * and set `true` or `'all'` to include summary labels.
   */
  readonly showTaskLabels?: boolean | 'tasks' | 'all';
  /** Which baseline snapshot to display (defaults to the latest). */
  readonly baselineId?: BaselineId;
  /** Vertical "today" or status-date line on the timeline. */
  readonly projectLineDate?: ISODateString;
  /** Highlighted date ranges on the timeline background. */
  readonly timeRanges?: readonly GanttTimeRange[];
  /** Shade non-working days (weekends, holidays) on the timeline. */
  readonly shadeNonWorkingTime?: boolean;
  /**
   * Show a "today" flag line on the timeline.
   * Set to `false` to disable. Enabled by default when not specified.
   */
  readonly showTodayLine?: boolean;
  /** Custom vertical flag lines on the timeline (e.g. sprint starts, release dates). */
  readonly milestoneLines?: readonly GanttMilestoneLine[];
  /** Show configured milestone lines without removing their definitions. Defaults to `true`. */
  readonly showMilestoneLines?: boolean;
  /** Hook to produce custom markers on individual task bars. */
  readonly taskMarkerHook?: GanttTaskMarkerHook;
  /** Hook to provide per-task bar colours and classes. */
  readonly taskBarColorHook?: GanttTaskBarColorHook;
  /** Hook to replace or extend the inner content rendered inside task bars. */
  readonly taskBarContentHook?: GanttTaskBarContentHook;
  /**
   * Ordered list of built-in fields shown in task-bar tooltips.
   * Omit to show Start, End, Duration, and Complete under the task title.
   * An empty array intentionally renders only the task title.
   * Use `taskTooltipHook` to replace the body under the title.
   */
  readonly taskTooltipFields?: readonly GanttTaskTooltipField[];
  /** Hook to override the tooltip content shown for task bars. */
  readonly taskTooltipHook?: GanttTaskTooltipHook;
  /** Hook to override the tooltip content shown for dependency arrows. */
  readonly dependencyTooltipHook?: GanttDependencyTooltipHook;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `percentDoneMode` | `GanttPercentDoneColumnMode \| undefined` | No | — | Percent Done task-table rendering. Defaults to `'bar'`. |
| `showDependencies` | `boolean \| undefined` | No | — | Show dependency arrows between task bars. Enabled by default. |
| `showBaseline` | `boolean \| undefined` | No | — | Show baseline bars beneath task bars for comparison. |
| `showCriticalPath` | `boolean \| undefined` | No | — | Highlight tasks on the critical path. |
| `showTaskLabels` | `boolean \| "all" \| "tasks" \| undefined` | No | — | Display task names as labels on timeline bars. Omit for regular task/milestone labels only, set `false` to hide built-in labels, and set `true` or `'all'` to include summary labels. |
| `baselineId` | `string \| undefined` | No | — | Which baseline snapshot to display (defaults to the latest). |
| `projectLineDate` | `ISODateString \| undefined` | No | — | Vertical "today" or status-date line on the timeline. |
| `timeRanges` | `readonly GanttTimeRange[] \| undefined` | No | — | Highlighted date ranges on the timeline background. |
| `shadeNonWorkingTime` | `boolean \| undefined` | No | — | Shade non-working days (weekends, holidays) on the timeline. |
| `showTodayLine` | `boolean \| undefined` | No | — | Show a "today" flag line on the timeline. Set to `false` to disable. Enabled by default when not specified. |
| `milestoneLines` | `readonly GanttMilestoneLine[] \| undefined` | No | — | Custom vertical flag lines on the timeline (e.g. sprint starts, release dates). |
| `showMilestoneLines` | `boolean \| undefined` | No | — | Show configured milestone lines without removing their definitions. Defaults to `true`. |
| `taskMarkerHook` | `GanttTaskMarkerHook \| undefined` | No | — | Hook to produce custom markers on individual task bars. |
| `taskBarColorHook` | `GanttTaskBarColorHook \| undefined` | No | — | Hook to provide per-task bar colours and classes. |
| `taskBarContentHook` | `GanttTaskBarContentHook \| undefined` | No | — | Hook to replace or extend the inner content rendered inside task bars. |
| `taskTooltipFields` | `readonly GanttTaskTooltipField[] \| undefined` | No | — | Ordered list of built-in fields shown in task-bar tooltips. Omit to show Start, End, Duration, and Complete under the task title. An empty array intentionally renders only the task title. Use `taskTooltipHook` to replace the body under the title. |
| `taskTooltipHook` | `GanttTaskTooltipHook \| undefined` | No | — | Hook to override the tooltip content shown for task bars. |
| `dependencyTooltipHook` | `GanttDependencyTooltipHook \| undefined` | No | — | Hook to override the tooltip content shown for dependency arrows. |

**Related types:** [`BaselineId`](/api/gantt/data-model/#baselineid), [`GanttDependencyTooltipHook`](/api/gantt/plugin/#ganttdependencytooltiphook), [`GanttMilestoneLine`](/api/gantt/plugin/#ganttmilestoneline), [`GanttPercentDoneColumnMode`](/api/gantt/columns/#ganttpercentdonecolumnmode), [`GanttTaskBarColorHook`](/api/gantt/visuals/#gantttaskbarcolorhook), [`GanttTaskBarContentHook`](/api/gantt/visuals/#gantttaskbarcontenthook), [`GanttTaskMarkerHook`](/api/gantt/visuals/#gantttaskmarkerhook), [`GanttTaskTooltipField`](/api/gantt/plugin/#gantttasktooltipfield), [`GanttTaskTooltipHook`](/api/gantt/plugin/#gantttasktooltiphook), [`GanttTimeRange`](/api/gantt/plugin/#gantttimerange)

## `GanttZoomSetLevelDetail`

<span class="api-kind">interface</span>

Detail payload for zoom-set-level events.

```ts
export interface GanttZoomSetLevelDetail {
  /** The zoom level id to jump to. */
  readonly levelId: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `levelId` | `string` | Yes | — | The zoom level id to jump to. |

## `getAnchorOffset`

<span class="api-kind">function</span>

Computes the viewport-relative anchor offset based on the active anchor mode.

```ts
export function getAnchorOffset(anchorMode: string, context: TimelineZoomAnchorContext): number;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `anchorMode` | `string` | Yes | — | - The anchor strategy ('pointer', 'center', or 'start'). |
| `context` | `TimelineZoomAnchorContext` | Yes | — | - Current viewport and pointer context. |

**Returns:** Pixel offset from the viewport left edge.

**Related types:** [`TimelineZoomAnchorContext`](/api/gantt/visuals/#timelinezoomanchorcontext)

## `getLevelById`

<span class="api-kind">function</span>

Finds a zoom level by its ID.

```ts
export function getLevelById(levels: readonly TimelineZoomLevel[], levelId: string | undefined): TimelineZoomLevel | null;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `levels` | `readonly TimelineZoomLevel[]` | Yes | — | - Available zoom levels. |
| `levelId` | `string \| undefined` | Yes | — | - ID to search for. |

**Returns:** The matching level, or `null` if not found.

**Related types:** [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `getLevelIndex`

<span class="api-kind">function</span>

Returns the index of a zoom level by ID, or 0 if not found.

```ts
export function getLevelIndex(levels: readonly TimelineZoomLevel[], levelId: string): number;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `levels` | `readonly TimelineZoomLevel[]` | Yes | — | - Available zoom levels. |
| `levelId` | `string` | Yes | — | - ID to search for. |

**Returns:** Zero-based index into the levels array.

**Related types:** [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `getNextScrollLeft`

<span class="api-kind">function</span>

Computes the scroll-left position that places an anchor date at a given viewport offset.

```ts
export function getNextScrollLeft(scale: TimelineScale, anchorDate: ISODateString, anchorOffset: number): number;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `scale` | `TimelineScale` | Yes | — | - The timeline scale instance. |
| `anchorDate` | `ISODateString` | Yes | — | - ISO date string to anchor. |
| `anchorOffset` | `number` | Yes | — | - Desired pixel offset from the viewport left edge. |

**Returns:** The scroll-left value (minimum 0).

**Related types:** [`TimelineScale`](/api/gantt/visuals/#timelinescale)

## `getProjectTimelineRange`

<span class="api-kind">function</span>

Computes a start/end date range that encloses all provided dates with padding
appropriate for the given zoom level or preset.

```ts
export function getProjectTimelineRange(dates: readonly ISODateString[], zoomLevelOrPreset: TimelineZoomLevel | TimelineZoomPreset, options: Pick<TimelineScaleConfig, 'weekStartsOn'> = {}): Pick<TimelineScaleConfig, 'startDate' | 'endDate'>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `dates` | `readonly ISODateString[]` | Yes | — | - Array of ISO date strings to encompass. |
| `zoomLevelOrPreset` | `TimelineZoomLevel \| TimelineZoomPreset` | Yes | — | - A zoom level object or preset identifier. |
| `options` | `Pick<TimelineScaleConfig, "weekStartsOn">` | No | `{}` |  |

**Returns:** A `{ startDate, endDate }` range with timeline padding.

**Related types:** [`TimelineScaleConfig`](/api/gantt/visuals/#timelinescaleconfig), [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel), [`TimelineZoomPreset`](/api/gantt/columns/#timelinezoompreset)

## `getZoomAnchorDate`

<span class="api-kind">function</span>

Resolves the nearest date-only zoom anchor while preserving existing scale
snapping semantics for non-zoom interactions.

```ts
export function getZoomAnchorDate(scale: TimelineScale, anchorX: number): ISODateString;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `scale` | `TimelineScale` | Yes | — | - The active timeline scale. |
| `anchorX` | `number` | Yes | — | - Pixel offset from the timeline origin. |

**Returns:** ISO date string to preserve during zoom.

**Related types:** [`TimelineScale`](/api/gantt/visuals/#timelinescale)

## `normalizeTimelineHeaderLabel`

<span class="api-kind">function</span>

Normalizes a header label to the structured {@link TimelineHeaderLabelParts} form.

```ts
export function normalizeTimelineHeaderLabel(label: TimelineHeaderLabel): TimelineHeaderLabelParts;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `label` | `TimelineHeaderLabel` | Yes | — | - A plain string or structured label. |

**Returns:** The label as a `{ label, subLabel }` object.

**Related types:** [`TimelineHeaderLabel`](/api/gantt/visuals/#timelineheaderlabel), [`TimelineHeaderLabelParts`](/api/gantt/visuals/#timelineheaderlabelparts)

## `normalizeTimelineZoomConfig`

<span class="api-kind">function</span>

Normalizes a partial zoom config into a fully resolved configuration with defaults applied.

```ts
export function normalizeTimelineZoomConfig(config: TimelineZoomConfig | undefined, fallbackLevelId = FALLBACK_ZOOM_LEVEL.id): ResolvedTimelineZoomConfig;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `config` | `TimelineZoomConfig \| undefined` | Yes | — | - Optional user-supplied zoom configuration. |
| `fallbackLevelId` | `string` | No | `FALLBACK_ZOOM_LEVEL.id` | - Level ID to use as the default when the config does not specify one. |

**Returns:** A {@link ResolvedTimelineZoomConfig} with all fields populated.

**Related types:** [`ResolvedTimelineZoomConfig`](/api/gantt/visuals/#resolvedtimelinezoomconfig), [`TimelineZoomConfig`](/api/gantt/visuals/#timelinezoomconfig)

## `projectVisibleTaskBarAnchors`

<span class="api-kind">function</span>

Projects viewport-relative anchor points for every task bar visible in the current viewport.
Used to position dependency arrow endpoints.

```ts
export function projectVisibleTaskBarAnchors(projection: VisibleTaskBarProjection): readonly VisibleTaskBarAnchors[];
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `projection` | `VisibleTaskBarProjection` | Yes | — | - Viewport state and row data needed for the projection. |

**Returns:** An array of {@link VisibleTaskBarAnchors} for each visible task bar.

**Related types:** [`VisibleTaskBarAnchors`](/api/gantt/visuals/#visibletaskbaranchors), [`VisibleTaskBarProjection`](/api/gantt/visuals/#visibletaskbarprojection)

## `renderGanttTimelineHeader`

<span class="api-kind">function</span>

Render the complete Gantt timeline header with RevoGrid's native VNode factory.

The caller owns scale calculation, viewport slicing, and state. This function
only projects already-resolved geometry into the existing Gantt header DOM.

```ts
export function renderGanttTimelineHeader(h: HyperFunc<VNode>, options: GanttTimelineHeaderRenderOptions, additionalElements: readonly VNodeResponse[] = []): VNode;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `h` | `HyperFunc` | Yes | — |  |
| `options` | `GanttTimelineHeaderRenderOptions` | Yes | — |  |
| `additionalElements` | `readonly VNodeResponse[]` | No | `[]` |  |

**Related types:** [`GanttTimelineHeaderRenderOptions`](/api/gantt/visuals/#gantttimelineheaderrenderoptions)

## `ResolvedTimelineZoomConfig`

<span class="api-kind">interface</span>

Fully resolved zoom configuration with all defaults applied.

```ts
export interface ResolvedTimelineZoomConfig {
  /** Whether zoom functionality is enabled. */
  readonly enabled: boolean;
  /** Ordered list of available zoom levels. */
  readonly levels: readonly TimelineZoomLevel[];
  /** Active default level ID. */
  readonly defaultLevelId: string;
  /** Finest allowed level ID. */
  readonly minLevelId: string;
  /** Coarsest allowed level ID. */
  readonly maxLevelId: string;
  /** Resolved locale string. */
  readonly locale: string;
  /** Whether non-working time shading is enabled. */
  readonly shadeNonWorkingTime: boolean | undefined;
  /** Whether wheel zoom is enabled. */
  readonly wheelZoomEnabled: boolean;
  /** Required modifier key for wheel zoom. */
  readonly wheelZoomTrigger: WheelZoomTrigger;
  /** Zoom transition mode. */
  readonly wheelZoomMode: TimelineZoomMode;
  /** Anchor strategy during zoom. */
  readonly zoomAnchorMode: ZoomAnchorMode;
  /** Whether wheel direction is inverted. */
  readonly invertWheelDirection: boolean;
  /** Default header date formatter, if any. */
  readonly defaultHeaderFormatter: TimelineDateFormatter | undefined;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `enabled` | `boolean` | Yes | — | Whether zoom functionality is enabled. |
| `levels` | `readonly TimelineZoomLevel[]` | Yes | — | Ordered list of available zoom levels. |
| `defaultLevelId` | `string` | Yes | — | Active default level ID. |
| `minLevelId` | `string` | Yes | — | Finest allowed level ID. |
| `maxLevelId` | `string` | Yes | — | Coarsest allowed level ID. |
| `locale` | `string` | Yes | — | Resolved locale string. |
| `shadeNonWorkingTime` | `boolean \| undefined` | Yes | — | Whether non-working time shading is enabled. |
| `wheelZoomEnabled` | `boolean` | Yes | — | Whether wheel zoom is enabled. |
| `wheelZoomTrigger` | `WheelZoomTrigger` | Yes | — | Required modifier key for wheel zoom. |
| `wheelZoomMode` | `TimelineZoomMode` | Yes | — | Zoom transition mode. |
| `zoomAnchorMode` | `ZoomAnchorMode` | Yes | — | Anchor strategy during zoom. |
| `invertWheelDirection` | `boolean` | Yes | — | Whether wheel direction is inverted. |
| `defaultHeaderFormatter` | `TimelineDateFormatter \| undefined` | Yes | — | Default header date formatter, if any. |

**Related types:** [`TimelineDateFormatter`](/api/gantt/visuals/#timelinedateformatter), [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel), [`TimelineZoomMode`](/api/gantt/visuals/#timelinezoommode), [`WheelZoomTrigger`](/api/gantt/visuals/#wheelzoomtrigger), [`ZoomAnchorMode`](/api/gantt/visuals/#zoomanchormode)

## `resolveGanttTimelineDateFormatter`

<span class="api-kind">function</span>

```ts
export function resolveGanttTimelineDateFormatter(project: Pick<GanttPluginConfig, 'timeZone' | 'dateFormats'> | null | undefined, fallbackLocale: string, fallbackFormatter?: TimelineDateFormatter): TimelineDateFormatter | undefined;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `project` | `Pick<GanttPluginConfig, "timeZone" \| "dateFormats"> \| null \| undefined` | Yes | — |  |
| `fallbackLocale` | `string` | Yes | — |  |
| `fallbackFormatter` | `TimelineDateFormatter \| undefined` | No | — |  |

**Related types:** [`GanttPluginConfig`](/api/gantt/plugin/#ganttpluginconfig), [`TimelineDateFormatter`](/api/gantt/visuals/#timelinedateformatter)

## `resolveHighlightVisibility`

<span class="api-kind">function</span>

```ts
export function resolveHighlightVisibility(zoom: TimelineZoomLevel): Required<TimelineHighlightVisibility>;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `zoom` | `TimelineZoomLevel` | Yes | — |  |

**Related types:** [`TimelineHighlightVisibility`](/api/gantt/visuals/#timelinehighlightvisibility), [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `ResourceLoadSegment`

<span class="api-kind">interface</span>

```ts
export interface ResourceLoadSegment {
  readonly id: string;
  readonly startDate: string;
  readonly endDate: string;
  readonly x: number;
  readonly width: number;
  readonly allocatedUnits: number;
  readonly capacityUnits: number;
  readonly loadRatio: number;
  readonly taskIds: readonly TaskId[];
  readonly isOverallocated: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — |  |
| `startDate` | `string` | Yes | — |  |
| `endDate` | `string` | Yes | — |  |
| `x` | `number` | Yes | — |  |
| `width` | `number` | Yes | — |  |
| `allocatedUnits` | `number` | Yes | — |  |
| `capacityUnits` | `number` | Yes | — |  |
| `loadRatio` | `number` | Yes | — |  |
| `taskIds` | `readonly string[]` | Yes | — |  |
| `isOverallocated` | `boolean` | Yes | — |  |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `ResourcePlanningRowData`

<span class="api-kind">interface</span>

```ts
export interface ResourcePlanningRowData {
  readonly capacityUnits: number;
  readonly maxAllocatedUnits: number;
  readonly capacityDisplay: 'line' | 'none';
  readonly overAllocationDisplay: 'highlight' | 'none';
  readonly loadGranularity: 'day' | 'week';
  readonly segments: readonly ResourceLoadSegment[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `capacityUnits` | `number` | Yes | — |  |
| `maxAllocatedUnits` | `number` | Yes | — |  |
| `capacityDisplay` | `"line" \| "none"` | Yes | — |  |
| `overAllocationDisplay` | `"none" \| "highlight"` | Yes | — |  |
| `loadGranularity` | `"day" \| "week"` | Yes | — |  |
| `segments` | `readonly ResourceLoadSegment[]` | Yes | — |  |

**Related types:** [`ResourceLoadSegment`](/api/gantt/visuals/#resourceloadsegment)

## `shouldHandleWheelTrigger`

<span class="api-kind">function</span>

Determines whether a wheel event should trigger a zoom action based on the configured modifier key.

```ts
export function shouldHandleWheelTrigger(trigger: WheelZoomTrigger, input: TimelineWheelInput): boolean;
```

| Parameter | Type | Required | Default | Description |
|---|---|:---:|---|---|
| `trigger` | `WheelZoomTrigger` | Yes | — | - The required modifier key. |
| `input` | `TimelineWheelInput` | Yes | — | - Raw wheel event data. |

**Returns:** `true` if the trigger condition is met.

**Related types:** [`TimelineWheelInput`](/api/gantt/visuals/#timelinewheelinput), [`WheelZoomTrigger`](/api/gantt/visuals/#wheelzoomtrigger)

## `TaskBarAnchorPoint`

<span class="api-kind">interface</span>

A 2D point in viewport-relative coordinates.

```ts
export interface TaskBarAnchorPoint {
  /** Horizontal pixel coordinate. */
  readonly x: number;
  /** Vertical pixel coordinate. */
  readonly y: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `x` | `number` | Yes | — | Horizontal pixel coordinate. |
| `y` | `number` | Yes | — | Vertical pixel coordinate. |

## `TaskGridAssignee`

<span class="api-kind">interface</span>

```ts
export interface TaskGridAssignee {
  readonly id: ResourceId;
  readonly name: string;
  readonly avatarUrl?: string;
  readonly initials: string;
  readonly role: string;
  readonly allocationUnits: number;
  readonly color: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — |  |
| `name` | `string` | Yes | — |  |
| `avatarUrl` | `string \| undefined` | No | — |  |
| `initials` | `string` | Yes | — |  |
| `role` | `string` | Yes | — |  |
| `allocationUnits` | `number` | Yes | — |  |
| `color` | `string` | Yes | — |  |

**Related types:** [`ResourceId`](/api/gantt/data-model/#resourceid)

## `TaskRowDiagnostics`

<span class="api-kind">type</span>

```ts
export type TaskRowDiagnostics = Pick<SchedulingResult, 'conflicts' | 'issues'>;
```

**Related types:** [`SchedulingResult`](/api/gantt/scheduling/#schedulingresult)

## `TaskRowProjectionOptions`

<span class="api-kind">interface</span>

Options controlling which optional data layers are included in the task row projection.

```ts
export interface TaskRowProjectionOptions {
  /** Show baseline overlay bars when baseline data is available. */
  readonly showBaseline?: boolean;
  /** Highlight tasks on the critical path. */
  readonly showCriticalPath?: boolean;
  /** Render inline task name labels on Gantt bars. Defaults to regular task/milestone labels only. */
  readonly showTaskLabels?: GanttTaskLabelMode;
  /** Specific baseline snapshot to compare against. Uses the latest baseline when omitted. */
  readonly baselineId?: BaselineId;
  /** Hook to inject custom point markers onto task rows. */
  readonly taskMarkerHook?: GanttTaskMarkerHook;
  /** Resource filter ids are applied as grid trims, not during projection. */
  readonly resourceFilterIds?: readonly ResourceId[];
  /** When enabled, project resource rows and allocation load bars instead of task rows. */
  readonly resourcePlanning?: GanttResourcePlanningConfig;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `showBaseline` | `boolean \| undefined` | No | — | Show baseline overlay bars when baseline data is available. |
| `showCriticalPath` | `boolean \| undefined` | No | — | Highlight tasks on the critical path. |
| `showTaskLabels` | `GanttTaskLabelMode \| undefined` | No | — | Render inline task name labels on Gantt bars. Defaults to regular task/milestone labels only. |
| `baselineId` | `string \| undefined` | No | — | Specific baseline snapshot to compare against. Uses the latest baseline when omitted. |
| `taskMarkerHook` | `GanttTaskMarkerHook \| undefined` | No | — | Hook to inject custom point markers onto task rows. |
| `resourceFilterIds` | `readonly string[] \| undefined` | No | — | Resource filter ids are applied as grid trims, not during projection. |
| `resourcePlanning` | `GanttResourcePlanningConfig \| undefined` | No | — | When enabled, project resource rows and allocation load bars instead of task rows. |

**Related types:** [`BaselineId`](/api/gantt/data-model/#baselineid), [`GanttResourcePlanningConfig`](/api/gantt/plugin/#ganttresourceplanningconfig), [`GanttTaskLabelMode`](/api/gantt/visuals/#gantttasklabelmode), [`GanttTaskMarkerHook`](/api/gantt/visuals/#gantttaskmarkerhook), [`ResourceId`](/api/gantt/data-model/#resourceid)

## `TIMELINE_ZOOM_PRESET_LEVELS`

<span class="api-kind">constant</span>

Built-in set of zoom presets ordered from finest (15-minute) to coarsest (multi-year).

```ts
export const TIMELINE_ZOOM_PRESET_LEVELS: readonly TimelineZoomLevel[];
```

**Related types:** [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `TimelineBand`

<span class="api-kind">interface</span>

A grouping band cell on an upper row of the timeline header.

```ts
export interface TimelineBand {
  /** Unique key for reconciliation. */
  readonly key: string;
  /** Start date of the band interval (ISO string). */
  readonly startDate: ISODateString;
  /** End date of the band interval (ISO string). */
  readonly endDate: ISODateString;
  /** Horizontal pixel offset from the timeline origin. */
  readonly x: number;
  /** Pixel width of the band cell. */
  readonly width: number;
  /** Display label. */
  readonly label: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `key` | `string` | Yes | — | Unique key for reconciliation. |
| `startDate` | `ISODateString` | Yes | — | Start date of the band interval (ISO string). |
| `endDate` | `ISODateString` | Yes | — | End date of the band interval (ISO string). |
| `x` | `number` | Yes | — | Horizontal pixel offset from the timeline origin. |
| `width` | `number` | Yes | — | Pixel width of the band cell. |
| `label` | `string` | Yes | — | Display label. |

## `TimelineBandUnit`

<span class="api-kind">type</span>

Calendar unit used for the grouping band row (excludes 'day').

```ts
export type TimelineBandUnit = Exclude<TimelineUnit, 'minute'>;
```

## `TimelineDateFormatter`

<span class="api-kind">type</span>

Custom formatter function used to produce the label for a single timeline header cell.

```ts
export type TimelineDateFormatter = (
  startDate: ISODateString,
  endDate: ISODateString,
  context: TimelineDateFormatterContext,
) => TimelineHeaderLabel;
```

**Returns:** A label string or structured label parts.

**Related types:** [`TimelineDateFormatterContext`](/api/gantt/visuals/#timelinedateformattercontext), [`TimelineHeaderLabel`](/api/gantt/visuals/#timelineheaderlabel)

## `TimelineDateFormatterContext`

<span class="api-kind">interface</span>

Context passed to a custom date formatter when rendering a timeline header cell.

```ts
export interface TimelineDateFormatterContext {
  /** Zoom level identifier that owns this header. */
  readonly levelId: string;
  /** Identifier of the header row being rendered. */
  readonly rowId: string;
  /** Calendar unit of this header row. */
  readonly unit: TimelineUnit;
  /** Number of units each cell spans. */
  readonly count: number;
  /** Active locale string (e.g. "en-US"). */
  readonly locale: string;
  /** Zero-based index of this row within the header stack. */
  readonly rowIndex: number;
  /** Whether this is the bottom (leaf / tick) row. */
  readonly isLeafRow: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `levelId` | `string` | Yes | — | Zoom level identifier that owns this header. |
| `rowId` | `string` | Yes | — | Identifier of the header row being rendered. |
| `unit` | `TimelineUnit` | Yes | — | Calendar unit of this header row. |
| `count` | `number` | Yes | — | Number of units each cell spans. |
| `locale` | `string` | Yes | — | Active locale string (e.g. "en-US"). |
| `rowIndex` | `number` | Yes | — | Zero-based index of this row within the header stack. |
| `isLeafRow` | `boolean` | Yes | — | Whether this is the bottom (leaf / tick) row. |

## `TimelineFlagLine`

<span class="api-kind">interface</span>

A flag label positioned inside the timeline header.

```ts
export interface TimelineFlagLine {
  readonly id: string;
  /** Absolute X position in the full timeline (px from timeline start). */
  readonly dateX: number;
  readonly label: string;
  readonly color?: string;
  readonly kind: 'today' | 'milestone';
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — |  |
| `dateX` | `number` | Yes | — | Absolute X position in the full timeline (px from timeline start). |
| `label` | `string` | Yes | — |  |
| `color` | `string \| undefined` | No | — |  |
| `kind` | `"milestone" \| "today"` | Yes | — |  |

## `TimelineHeaderCell`

<span class="api-kind">interface</span>

A single rendered cell within a timeline header row.

```ts
export interface TimelineHeaderCell {
  /** Unique key for React/framework reconciliation. */
  readonly key: string;
  /** Start date of the interval this cell covers (ISO string). */
  readonly startDate: ISODateString;
  /** End date (inclusive) of the interval this cell covers (ISO string). */
  readonly endDate: ISODateString;
  /** Horizontal pixel offset from the timeline origin. */
  readonly x: number;
  /** Pixel width of the cell. */
  readonly width: number;
  /** Primary display text. */
  readonly label: string;
  /** Secondary display text (may be empty). */
  readonly subLabel: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `key` | `string` | Yes | — | Unique key for React/framework reconciliation. |
| `startDate` | `ISODateString` | Yes | — | Start date of the interval this cell covers (ISO string). |
| `endDate` | `ISODateString` | Yes | — | End date (inclusive) of the interval this cell covers (ISO string). |
| `x` | `number` | Yes | — | Horizontal pixel offset from the timeline origin. |
| `width` | `number` | Yes | — | Pixel width of the cell. |
| `label` | `string` | Yes | — | Primary display text. |
| `subLabel` | `string` | Yes | — | Secondary display text (may be empty). |

## `TimelineHeaderHighlightRange`

<span class="api-kind">interface</span>

Date interval marked as non-working for timeline header cells.

```ts
export interface TimelineHeaderHighlightRange {
  readonly id: string;
  readonly startDate: ISODateString;
  readonly endDate: ISODateString;
  readonly left: number;
  readonly width: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — |  |
| `startDate` | `ISODateString` | Yes | — |  |
| `endDate` | `ISODateString` | Yes | — |  |
| `left` | `number` | Yes | — |  |
| `width` | `number` | Yes | — |  |

## `TimelineHeaderLabel`

<span class="api-kind">type</span>

A header cell label — either a plain string or a structured label with sub-text.

```ts
export type TimelineHeaderLabel = string | TimelineHeaderLabelParts;
```

**Related types:** [`TimelineHeaderLabelParts`](/api/gantt/visuals/#timelineheaderlabelparts)

## `TimelineHeaderLabelParts`

<span class="api-kind">interface</span>

Structured label with an optional secondary line for timeline header cells.

```ts
export interface TimelineHeaderLabelParts {
  /** Primary display text. */
  readonly label: string;
  /** Optional secondary text rendered below or beside the label. */
  readonly subLabel?: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `label` | `string` | Yes | — | Primary display text. |
| `subLabel` | `string \| undefined` | No | — | Optional secondary text rendered below or beside the label. |

## `TimelineHeaderRowConfig`

<span class="api-kind">interface</span>

Configuration for a single row in the timeline header stack.

```ts
export interface TimelineHeaderRowConfig {
  /** Unique identifier for this header row. */
  readonly id: string;
  /** Calendar unit this row represents. */
  readonly unit: TimelineUnit;
  /** Number of units each cell spans (defaults to 1). */
  readonly count?: number;
  /** Optional custom formatter overriding the default label logic. */
  readonly formatter?: TimelineDateFormatter;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique identifier for this header row. |
| `unit` | `TimelineUnit` | Yes | — | Calendar unit this row represents. |
| `count` | `number \| undefined` | No | — | Number of units each cell spans (defaults to 1). |
| `formatter` | `TimelineDateFormatter \| undefined` | No | — | Optional custom formatter overriding the default label logic. |

**Related types:** [`TimelineDateFormatter`](/api/gantt/visuals/#timelinedateformatter)

## `TimelineHeaderRowModel`

<span class="api-kind">interface</span>

Fully resolved model for a single header row, including its computed cells.

```ts
export interface TimelineHeaderRowModel {
  /** Identifier matching the originating {@link TimelineHeaderRowConfig.id}. */
  readonly id: string;
  /** Calendar unit of this row. */
  readonly unit: TimelineUnit;
  /** Number of units each cell spans. */
  readonly count: number;
  /** Ordered array of rendered header cells. */
  readonly cells: readonly TimelineHeaderCell[];
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Identifier matching the originating {@link TimelineHeaderRowConfig.id}. |
| `unit` | `TimelineUnit` | Yes | — | Calendar unit of this row. |
| `count` | `number` | Yes | — | Number of units each cell spans. |
| `cells` | `readonly TimelineHeaderCell[]` | Yes | — | Ordered array of rendered header cells. |

**Related types:** [`TimelineHeaderCell`](/api/gantt/visuals/#timelineheadercell), [`TimelineHeaderRowConfig`](/api/gantt/visuals/#timelineheaderrowconfig)

## `TimelineHighlightVisibility`

<span class="api-kind">interface</span>

```ts
export interface TimelineHighlightVisibility {
  weekends?: boolean;
  holidays?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `weekends` | `boolean \| undefined` | No | — |  |
| `holidays` | `boolean \| undefined` | No | — |  |

## `TimelineScale`

<span class="api-kind">interface</span>

Core abstraction for converting between dates and pixel positions on the Gantt timeline.
Provides tick/band generation and header row models.

```ts
export interface TimelineScale {
  /** First date of the timeline range (ISO string). */
  readonly startDate: ISODateString;
  /** Last date of the timeline range (ISO string). */
  readonly endDate: ISODateString;
  /** Zoom level configuration that produced this scale. */
  readonly zoomLevel: TimelineZoomLevel;
  /** Calendar unit of the leaf tick row. */
  readonly tickUnit: TimelineTickUnit;
  /** Number of calendar units per tick cell. */
  readonly tickCount: number;
  /** Pixel width of a single tick cell. */
  readonly tickWidth: number;
  /** Total pixel width of the entire timeline. */
  readonly totalWidth: number;
  /**
   * Converts a date to a horizontal pixel offset.
   * @param date - ISO date string.
   */
  dateToX(date: ISODateString): number;
  /**
   * Converts a horizontal pixel offset to the nearest date.
   * @param x - Pixel offset from the timeline origin.
   */
  xToDate(x: number): ISODateString;
  /** Converts a horizontal pixel offset to a UTC datetime, retaining fractional tick positions. */
  xToDateTime?(x: number): ISODateString;
  /** Returns all tick cells across the full timeline range. */
  getTicks(): readonly TimelineTick[];
  /**
   * Returns tick cells visible within the given horizontal viewport slice.
   * @param startX - Left edge pixel offset.
   * @param viewportWidth - Width of the visible area.
   */
  getVisibleTicks(startX: number, viewportWidth: number, overscanPx?: number): readonly TimelineTick[];
  /** Returns all band (grouping) cells. */
  getBands(): readonly TimelineBand[];
  /** Returns the computed header row models for rendering. */
  getHeaderRows(): readonly TimelineHeaderRowModel[];
  /**
   * Returns header row models intersecting the given viewport slice.
   * @param startX - Left edge pixel offset.
   * @param viewportWidth - Width of the visible area.
   * @param overscanPx - Extra pixels to include on both sides.
   */
  getVisibleHeaderRows(startX: number, viewportWidth: number, overscanPx?: number): readonly TimelineHeaderRowModel[];
  /**
   * Returns the date range visible within the given horizontal viewport slice.
   * @param startX - Left edge pixel offset.
   * @param viewportWidth - Width of the visible area.
   */
  getVisibleRange(startX: number, viewportWidth: number): TimelineVisibleDateRange;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `startDate` | `ISODateString` | Yes | — | First date of the timeline range (ISO string). |
| `endDate` | `ISODateString` | Yes | — | Last date of the timeline range (ISO string). |
| `zoomLevel` | `TimelineZoomLevel` | Yes | — | Zoom level configuration that produced this scale. |
| `tickUnit` | `TimelineUnit` | Yes | — | Calendar unit of the leaf tick row. |
| `tickCount` | `number` | Yes | — | Number of calendar units per tick cell. |
| `tickWidth` | `number` | Yes | — | Pixel width of a single tick cell. |
| `totalWidth` | `number` | Yes | — | Total pixel width of the entire timeline. |
| `dateToX(date: ISODateString)` | `number` | Yes | — | Converts a date to a horizontal pixel offset. |
| `xToDate(x: number)` | `ISODateString` | Yes | — | Converts a horizontal pixel offset to the nearest date. |
| `xToDateTime(x: number)` | `ISODateString` | Yes | — | Converts a horizontal pixel offset to a UTC datetime, retaining fractional tick positions. |
| `getTicks()` | `readonly TimelineTick[]` | Yes | — | Returns all tick cells across the full timeline range. |
| `getVisibleTicks(startX: number, viewportWidth: number, overscanPx?: number)` | `readonly TimelineTick[]` | Yes | — | Returns tick cells visible within the given horizontal viewport slice. |
| `getBands()` | `readonly TimelineBand[]` | Yes | — | Returns all band (grouping) cells. |
| `getHeaderRows()` | `readonly TimelineHeaderRowModel[]` | Yes | — | Returns the computed header row models for rendering. |
| `getVisibleHeaderRows(startX: number, viewportWidth: number, overscanPx?: number)` | `readonly TimelineHeaderRowModel[]` | Yes | — | Returns header row models intersecting the given viewport slice. |
| `getVisibleRange(startX: number, viewportWidth: number)` | `TimelineVisibleDateRange` | Yes | — | Returns the date range visible within the given horizontal viewport slice. |

**Related types:** [`TimelineBand`](/api/gantt/visuals/#timelineband), [`TimelineHeaderRowModel`](/api/gantt/visuals/#timelineheaderrowmodel), [`TimelineTick`](/api/gantt/visuals/#timelinetick), [`TimelineTickUnit`](/api/gantt/visuals/#timelinetickunit), [`TimelineVisibleDateRange`](/api/gantt/visuals/#timelinevisibledaterange), [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `TimelineScaleConfig`

<span class="api-kind">interface</span>

Configuration used to construct a {@link TimelineScale} instance.

```ts
export interface TimelineScaleConfig {
  /** Project timeline start date (ISO string). */
  readonly startDate: ISODateString;
  /** Project timeline end date (ISO string). */
  readonly endDate: ISODateString;
  /** Optional zoom level identifier to look up in the default levels. */
  readonly levelId?: string;
  /** Fully resolved active zoom level, including interaction defaults for custom modes. */
  readonly zoomLevel?: TimelineZoomLevel;
  /** Calendar unit for the leaf tick row (overrides zoom level when set). */
  readonly tickUnit?: TimelineTickUnit;
  /** Number of tick units each cell spans. */
  readonly tickCount?: number;
  /** Calendar unit for the grouping band row. */
  readonly bandUnit?: TimelineBandUnit;
  /** Pixel width of a single tick cell. */
  readonly tickWidth: number;
  /** Header row definitions (overrides zoom level rows when set). */
  readonly headerRows?: readonly TimelineHeaderRowConfig[];
  /** Per-scale highlight overrides inherited by the resolved zoom level. */
  readonly highlightVisibility?: TimelineHighlightVisibility;
  /** Locale string for date formatting (defaults to "en-US"). */
  readonly locale?: string;
  /** Fallback date formatter applied when no row-level formatter is set. */
  readonly defaultHeaderFormatter?: TimelineDateFormatter;
  /** First day of week for weekly timeline cells. `0` is Sunday and `1` is Monday. Defaults to Sunday. */
  readonly weekStartsOn?: TimelineWeekStartsOn;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `startDate` | `ISODateString` | Yes | — | Project timeline start date (ISO string). |
| `endDate` | `ISODateString` | Yes | — | Project timeline end date (ISO string). |
| `levelId` | `string \| undefined` | No | — | Optional zoom level identifier to look up in the default levels. |
| `zoomLevel` | `TimelineZoomLevel \| undefined` | No | — | Fully resolved active zoom level, including interaction defaults for custom modes. |
| `tickUnit` | `TimelineUnit \| undefined` | No | — | Calendar unit for the leaf tick row (overrides zoom level when set). |
| `tickCount` | `number \| undefined` | No | — | Number of tick units each cell spans. |
| `bandUnit` | `TimelineBandUnit \| undefined` | No | — | Calendar unit for the grouping band row. |
| `tickWidth` | `number` | Yes | — | Pixel width of a single tick cell. |
| `headerRows` | `readonly TimelineHeaderRowConfig[] \| undefined` | No | — | Header row definitions (overrides zoom level rows when set). |
| `highlightVisibility` | `TimelineHighlightVisibility \| undefined` | No | — | Per-scale highlight overrides inherited by the resolved zoom level. |
| `locale` | `string \| undefined` | No | — | Locale string for date formatting (defaults to "en-US"). |
| `defaultHeaderFormatter` | `TimelineDateFormatter \| undefined` | No | — | Fallback date formatter applied when no row-level formatter is set. |
| `weekStartsOn` | `TimelineWeekStartsOn \| undefined` | No | — | First day of week for weekly timeline cells. `0` is Sunday and `1` is Monday. Defaults to Sunday. |

**Related types:** [`TimelineBandUnit`](/api/gantt/visuals/#timelinebandunit), [`TimelineDateFormatter`](/api/gantt/visuals/#timelinedateformatter), [`TimelineHeaderRowConfig`](/api/gantt/visuals/#timelineheaderrowconfig), [`TimelineHighlightVisibility`](/api/gantt/visuals/#timelinehighlightvisibility), [`TimelineTickUnit`](/api/gantt/visuals/#timelinetickunit), [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `TimelineTaskInteractionRange`

<span class="api-kind">interface</span>

Absolute timeline range occupied by an active task-bar focus/move/resize state.

```ts
export interface TimelineTaskInteractionRange {
  readonly taskId: TaskId;
  readonly interaction: 'focus' | 'move' | 'resize';
  readonly kind: 'task' | 'summary' | 'milestone';
  readonly left: number;
  readonly width: number;
  readonly valid: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskId` | `string` | Yes | — |  |
| `interaction` | `"move" \| "resize" \| "focus"` | Yes | — |  |
| `kind` | `"summary" \| "task" \| "milestone"` | Yes | — |  |
| `left` | `number` | Yes | — |  |
| `width` | `number` | Yes | — |  |
| `valid` | `boolean` | Yes | — |  |

**Related types:** [`TaskId`](/api/gantt/data-model/#taskid)

## `TimelineTick`

<span class="api-kind">interface</span>

A single tick cell on the leaf row of the timeline.

```ts
export interface TimelineTick {
  /** Unique key for reconciliation. */
  readonly key: string;
  /** Start date of the tick interval (ISO string). */
  readonly startDate: ISODateString;
  /** End date of the tick interval (ISO string). */
  readonly endDate: ISODateString;
  /** Horizontal pixel offset from the timeline origin. */
  readonly x: number;
  /** Pixel width of the tick cell. */
  readonly width: number;
  /** Primary display label. */
  readonly label: string;
  /** Secondary display label. */
  readonly subLabel: string;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `key` | `string` | Yes | — | Unique key for reconciliation. |
| `startDate` | `ISODateString` | Yes | — | Start date of the tick interval (ISO string). |
| `endDate` | `ISODateString` | Yes | — | End date of the tick interval (ISO string). |
| `x` | `number` | Yes | — | Horizontal pixel offset from the timeline origin. |
| `width` | `number` | Yes | — | Pixel width of the tick cell. |
| `label` | `string` | Yes | — | Primary display label. |
| `subLabel` | `string` | Yes | — | Secondary display label. |

## `TimelineTickUnit`

<span class="api-kind">type</span>

Calendar unit used for the leaf-level tick grid.

```ts
export type TimelineTickUnit = TimelineUnit;
```

## `TimelineVisibleDateRange`

<span class="api-kind">interface</span>

A start/end date range representing the currently visible portion of the timeline.

```ts
export interface TimelineVisibleDateRange {
  /** First visible date (ISO string). */
  readonly startDate: ISODateString;
  /** Last visible date (ISO string). */
  readonly endDate: ISODateString;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `startDate` | `ISODateString` | Yes | — | First visible date (ISO string). |
| `endDate` | `ISODateString` | Yes | — | Last visible date (ISO string). |

## `TimelineVisibleSpan`

<span class="api-kind">interface</span>

Describes a time span used for minimum/maximum visible range constraints.

```ts
export interface TimelineVisibleSpan {
  /** Calendar unit of the span. */
  readonly unit: 'minute' | 'hour' | 'day' | 'month' | 'year';
  /** Number of units. */
  readonly value: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `unit` | `"minute" \| "hour" \| "day" \| "month" \| "year"` | Yes | — | Calendar unit of the span. |
| `value` | `number` | Yes | — | Number of units. |

## `TimelineWheelInput`

<span class="api-kind">interface</span>

Raw wheel event data used to determine zoom direction and trigger eligibility.

```ts
export interface TimelineWheelInput {
  /** Vertical scroll delta from the wheel event. */
  readonly deltaY: number;
  /** Whether the Ctrl key was held. */
  readonly ctrlKey?: boolean;
  /** Whether the Meta (Cmd) key was held. */
  readonly metaKey?: boolean;
  /** Whether the Alt key was held. */
  readonly altKey?: boolean;
  /** Whether the Shift key was held. */
  readonly shiftKey?: boolean;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `deltaY` | `number` | Yes | — | Vertical scroll delta from the wheel event. |
| `ctrlKey` | `boolean \| undefined` | No | — | Whether the Ctrl key was held. |
| `metaKey` | `boolean \| undefined` | No | — | Whether the Meta (Cmd) key was held. |
| `altKey` | `boolean \| undefined` | No | — | Whether the Alt key was held. |
| `shiftKey` | `boolean \| undefined` | No | — | Whether the Shift key was held. |

## `TimelineZoomAnchorContext`

<span class="api-kind">interface</span>

Viewport and pointer context used to calculate the zoom anchor position.

```ts
export interface TimelineZoomAnchorContext {
  /** Active timeline scale instance. */
  readonly scale: TimelineScale;
  /** Current horizontal scroll offset in pixels. */
  readonly scrollLeft: number;
  /** Width of the visible viewport in pixels. */
  readonly viewportWidth: number;
  /** Left edge of the viewport element in client coordinates (for pointer anchor). */
  readonly viewportClientLeft?: number;
  /** Pointer X position in client coordinates (for pointer anchor). */
  readonly pointerClientX?: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `scale` | `TimelineScale` | Yes | — | Active timeline scale instance. |
| `scrollLeft` | `number` | Yes | — | Current horizontal scroll offset in pixels. |
| `viewportWidth` | `number` | Yes | — | Width of the visible viewport in pixels. |
| `viewportClientLeft` | `number \| undefined` | No | — | Left edge of the viewport element in client coordinates (for pointer anchor). |
| `pointerClientX` | `number \| undefined` | No | — | Pointer X position in client coordinates (for pointer anchor). |

**Related types:** [`TimelineScale`](/api/gantt/visuals/#timelinescale)

## `TimelineZoomConfig`

<span class="api-kind">interface</span>

User-facing zoom configuration. All fields are optional and fall back to sensible defaults.

```ts
export interface TimelineZoomConfig {
  /** Whether zoom functionality is enabled. */
  readonly enabled?: boolean;
  /** Ordered list of zoom levels from finest to coarsest. */
  readonly levels?: readonly TimelineZoomLevel[];
  /** Level ID to activate initially. */
  readonly defaultLevelId?: string;
  /** Finest (most detailed) level ID allowed. */
  readonly minLevelId?: string;
  /** Coarsest level ID allowed. */
  readonly maxLevelId?: string;
  /** Locale string for date formatting (e.g. "en-US"). */
  readonly locale?: string;
  /** Whether to shade non-working time columns. */
  readonly shadeNonWorkingTime?: boolean;
  /** Whether mouse wheel zoom is enabled. */
  readonly wheelZoomEnabled?: boolean;
  /** Modifier key required for wheel zoom. */
  readonly wheelZoomTrigger?: WheelZoomTrigger;
  /** Zoom transition mode. */
  readonly wheelZoomMode?: TimelineZoomMode;
  /** Anchor strategy during zoom transitions. */
  readonly zoomAnchorMode?: ZoomAnchorMode;
  /** Whether to invert the wheel scroll direction for zoom. */
  readonly invertWheelDirection?: boolean;
  /** Fallback date formatter for header cells. */
  readonly defaultHeaderFormatter?: TimelineDateFormatter;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `enabled` | `boolean \| undefined` | No | — | Whether zoom functionality is enabled. |
| `levels` | `readonly TimelineZoomLevel[] \| undefined` | No | — | Ordered list of zoom levels from finest to coarsest. |
| `defaultLevelId` | `string \| undefined` | No | — | Level ID to activate initially. |
| `minLevelId` | `string \| undefined` | No | — | Finest (most detailed) level ID allowed. |
| `maxLevelId` | `string \| undefined` | No | — | Coarsest level ID allowed. |
| `locale` | `string \| undefined` | No | — | Locale string for date formatting (e.g. "en-US"). |
| `shadeNonWorkingTime` | `boolean \| undefined` | No | — | Whether to shade non-working time columns. |
| `wheelZoomEnabled` | `boolean \| undefined` | No | — | Whether mouse wheel zoom is enabled. |
| `wheelZoomTrigger` | `WheelZoomTrigger \| undefined` | No | — | Modifier key required for wheel zoom. |
| `wheelZoomMode` | `TimelineZoomMode \| undefined` | No | — | Zoom transition mode. |
| `zoomAnchorMode` | `ZoomAnchorMode \| undefined` | No | — | Anchor strategy during zoom transitions. |
| `invertWheelDirection` | `boolean \| undefined` | No | — | Whether to invert the wheel scroll direction for zoom. |
| `defaultHeaderFormatter` | `TimelineDateFormatter \| undefined` | No | — | Fallback date formatter for header cells. |

**Related types:** [`TimelineDateFormatter`](/api/gantt/visuals/#timelinedateformatter), [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel), [`TimelineZoomMode`](/api/gantt/visuals/#timelinezoommode), [`WheelZoomTrigger`](/api/gantt/visuals/#wheelzoomtrigger), [`ZoomAnchorMode`](/api/gantt/visuals/#zoomanchormode)

## `TimelineZoomController`

<span class="api-kind">class</span>

Manages the active zoom level and zoom transitions for the Gantt timeline.
Provides discrete zoom-in/out operations, level selection, and anchor-based scroll
position computation to maintain visual continuity across zoom changes.

```ts
export class TimelineZoomController {
  constructor(config?: TimelineZoomConfig, fallbackLevelId?: string);
  setConfig(config?: TimelineZoomConfig, fallbackLevelId?: string): void;
  getConfig(): ResolvedTimelineZoomConfig;
  getZoomLevel(): TimelineZoomLevel;
  getVisibleRange(): { startDate: ISODateString; endDate: ISODateString } | null;
  updateVisibleRange(scale: TimelineScale, scrollLeft: number, viewportWidth: number): { startDate: ISODateString; endDate: ISODateString };
  canZoomIn(): boolean;
  canZoomOut(): boolean;
  zoomIn(): boolean;
  zoomOut(): boolean;
  setZoomLevel(levelId: string): boolean;
  createZoomTransition(nextLevelId: string, context: TimelineZoomAnchorContext): TimelineZoomTransition | null;
  resolveAnchoredScrollLeft(scale: TimelineScale, anchorDate: ISODateString, anchorOffset: number): number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `config` | `ResolvedTimelineZoomConfig` | Yes | — |  |
| `activeLevelId` | `string` | Yes | — |  |
| `visibleRange` | `{ startDate: ISODateString; endDate: ISODateString; } \| null` | Yes | `null` |  |
| `setConfig(config?: TimelineZoomConfig, fallbackLevelId?: string)` | `void` | Yes | — | Replaces the zoom configuration, preserving the current level when possible. |
| `getConfig()` | `ResolvedTimelineZoomConfig` | Yes | — | Returns the resolved zoom configuration. |
| `getZoomLevel()` | `TimelineZoomLevel` | Yes | — | Returns the currently active zoom level. |
| `getVisibleRange()` | `{ startDate: ISODateString; endDate: ISODateString } \| null` | Yes | — | Returns the last computed visible date range, or `null` if not yet updated. |
| `updateVisibleRange(scale: TimelineScale, scrollLeft: number, viewportWidth: number)` | `{ startDate: ISODateString; endDate: ISODateString }` | Yes | — | Recalculates and caches the visible date range from the current scroll position. |
| `canZoomIn()` | `boolean` | Yes | — | Returns `true` if zooming in (finer detail) is possible. |
| `canZoomOut()` | `boolean` | Yes | — | Returns `true` if zooming out (coarser detail) is possible. |
| `zoomIn()` | `boolean` | Yes | — | Zooms in one level. Returns `true` if the level changed. |
| `zoomOut()` | `boolean` | Yes | — | Zooms out one level. Returns `true` if the level changed. |
| `setZoomLevel(levelId: string)` | `boolean` | Yes | — | Jumps to a specific zoom level by ID. |
| `createZoomTransition(nextLevelId: string, context: TimelineZoomAnchorContext)` | `TimelineZoomTransition \| null` | Yes | — | Prepares a zoom transition descriptor that can be applied to update the scroll position so the anchor date stays visually stable. |
| `resolveAnchoredScrollLeft(scale: TimelineScale, anchorDate: ISODateString, anchorOffset: number)` | `number` | Yes | — | Computes the scroll-left position that keeps an anchor date at a fixed viewport offset. |
| `setLevelByIndex(index: number)` | `boolean` | Yes | — |  |

**Related types:** [`ResolvedTimelineZoomConfig`](/api/gantt/visuals/#resolvedtimelinezoomconfig), [`TimelineScale`](/api/gantt/visuals/#timelinescale), [`TimelineZoomAnchorContext`](/api/gantt/visuals/#timelinezoomanchorcontext), [`TimelineZoomConfig`](/api/gantt/visuals/#timelinezoomconfig), [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel), [`TimelineZoomTransition`](/api/gantt/visuals/#timelinezoomtransition)

## `TimelineZoomLevel`

<span class="api-kind">interface</span>

Definition of a single zoom level, specifying tick granularity and header layout.

```ts
export interface TimelineZoomLevel {
  /** Unique level identifier (e.g. "day-week"). */
  readonly id: string;
  /** Calendar unit for the leaf tick row. */
  readonly tickUnit: TimelineUnit;
  /** Number of tick units per cell (defaults to 1). */
  readonly tickCount?: number;
  /** Pixel width of a single tick cell. */
  readonly tickWidth: number;
  /** Default unit for task interactions in this timeline mode. When omitted, it derives from `tickUnit`; global `gantt.snap.unit` overrides it. */
  readonly interactionSnapUnit?: 'day' | 'hour' | 'minute';
  /** Header row definitions for this level. */
  readonly headerRows: readonly TimelineHeaderRowConfig[];
  /** Optional minimum visible time span constraint. */
  readonly minVisibleSpan?: TimelineVisibleSpan;
  /** Optional maximum visible time span constraint. */
  readonly maxVisibleSpan?: TimelineVisibleSpan;
  /** Human-readable label for UI display. */
  readonly label?: string;
  /**
   * Per-zoom-level highlight overrides.
   */
  highlightVisibility?: TimelineHighlightVisibility;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `id` | `string` | Yes | — | Unique level identifier (e.g. "day-week"). |
| `tickUnit` | `TimelineUnit` | Yes | — | Calendar unit for the leaf tick row. |
| `tickCount` | `number \| undefined` | No | — | Number of tick units per cell (defaults to 1). |
| `tickWidth` | `number` | Yes | — | Pixel width of a single tick cell. |
| `interactionSnapUnit` | `"minute" \| "hour" \| "day" \| undefined` | No | — | Default unit for task interactions in this timeline mode. When omitted, it derives from `tickUnit`; global `gantt.snap.unit` overrides it. |
| `headerRows` | `readonly TimelineHeaderRowConfig[]` | Yes | — | Header row definitions for this level. |
| `minVisibleSpan` | `TimelineVisibleSpan \| undefined` | No | — | Optional minimum visible time span constraint. |
| `maxVisibleSpan` | `TimelineVisibleSpan \| undefined` | No | — | Optional maximum visible time span constraint. |
| `label` | `string \| undefined` | No | — | Human-readable label for UI display. |
| `highlightVisibility` | `TimelineHighlightVisibility \| undefined` | No | — | Per-zoom-level highlight overrides. |

**Related types:** [`TimelineHeaderRowConfig`](/api/gantt/visuals/#timelineheaderrowconfig), [`TimelineHighlightVisibility`](/api/gantt/visuals/#timelinehighlightvisibility), [`TimelineVisibleSpan`](/api/gantt/visuals/#timelinevisiblespan)

## `TimelineZoomMode`

<span class="api-kind">type</span>

Strategy for transitioning between zoom levels.

```ts
export type TimelineZoomMode = 'discrete' | 'smooth-discrete';
```

## `TimelineZoomTransition`

<span class="api-kind">interface</span>

Describes a pending zoom level transition, including the anchor date used to preserve scroll position.

```ts
export interface TimelineZoomTransition {
  /** Zoom level before the transition. */
  readonly previousLevel: TimelineZoomLevel;
  /** Zoom level after the transition. */
  readonly nextLevel: TimelineZoomLevel;
  /** Date that should remain at the anchor offset after zoom. */
  readonly anchorDate: ISODateString;
  /** Pixel offset from the viewport left where the anchor date should appear. */
  readonly anchorOffset: number;
  /** Scroll-left at the time the transition was initiated. */
  readonly scrollLeft: number;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `previousLevel` | `TimelineZoomLevel` | Yes | — | Zoom level before the transition. |
| `nextLevel` | `TimelineZoomLevel` | Yes | — | Zoom level after the transition. |
| `anchorDate` | `ISODateString` | Yes | — | Date that should remain at the anchor offset after zoom. |
| `anchorOffset` | `number` | Yes | — | Pixel offset from the viewport left where the anchor date should appear. |
| `scrollLeft` | `number` | Yes | — | Scroll-left at the time the transition was initiated. |

**Related types:** [`TimelineZoomLevel`](/api/gantt/visuals/#timelinezoomlevel)

## `VisibleTaskBarAnchors`

<span class="api-kind">interface</span>

Viewport-relative anchor points and bounds for a visible task bar, used for dependency line routing.

```ts
export interface VisibleTaskBarAnchors {
  /** Identifier of the task this anchor set belongs to. */
  readonly taskId: TaskId;
  /** Row index of the task within the data source. */
  readonly rowIndex: number;
  /** Top edge of the row in viewport pixels. */
  readonly top: number;
  /** Bottom edge of the row in viewport pixels. */
  readonly bottom: number;
  /** Left edge of the bar in viewport pixels. */
  readonly left: number;
  /** Right edge of the bar in viewport pixels. */
  readonly right: number;
  /** Anchor point at the start (left) side of the bar, offset for dependency arrows. */
  readonly start: TaskBarAnchorPoint;
  /** Anchor point at the end (right) side of the bar, offset for dependency arrows. */
  readonly end: TaskBarAnchorPoint;
  /** Anchor point centered above the bar. */
  readonly topCenter: TaskBarAnchorPoint;
  /** Anchor point centered below the bar. */
  readonly bottomCenter: TaskBarAnchorPoint;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `taskId` | `string` | Yes | — | Identifier of the task this anchor set belongs to. |
| `rowIndex` | `number` | Yes | — | Row index of the task within the data source. |
| `top` | `number` | Yes | — | Top edge of the row in viewport pixels. |
| `bottom` | `number` | Yes | — | Bottom edge of the row in viewport pixels. |
| `left` | `number` | Yes | — | Left edge of the bar in viewport pixels. |
| `right` | `number` | Yes | — | Right edge of the bar in viewport pixels. |
| `start` | `TaskBarAnchorPoint` | Yes | — | Anchor point at the start (left) side of the bar, offset for dependency arrows. |
| `end` | `TaskBarAnchorPoint` | Yes | — | Anchor point at the end (right) side of the bar, offset for dependency arrows. |
| `topCenter` | `TaskBarAnchorPoint` | Yes | — | Anchor point centered above the bar. |
| `bottomCenter` | `TaskBarAnchorPoint` | Yes | — | Anchor point centered below the bar. |

**Related types:** [`TaskBarAnchorPoint`](/api/gantt/visuals/#taskbaranchorpoint), [`TaskId`](/api/gantt/data-model/#taskid)

## `VisibleTaskBarProjection`

<span class="api-kind">interface</span>

Input data required to project visible task bar anchors within the current viewport.

```ts
export interface VisibleTaskBarProjection {
  /** All task grid rows (full dataset). */
  readonly rows: readonly GanttGridRow[];
  /** Virtual position items describing which rows are currently visible. */
  readonly viewportRows: readonly VirtualPositionItem[];
  /** Current horizontal scroll offset in pixels. */
  readonly scrollLeft: number;
  /** Current vertical scroll offset in pixels. */
  readonly scrollTop: number;
  /** Width of the visible viewport in pixels. */
  readonly viewportWidth: number;
  /** Height of the visible viewport in pixels. */
  readonly viewportHeight: number;
  /** Keep anchors outside the viewport for overlay routes that cross the visible frame. */
  readonly includeOffscreenRows?: boolean;
  /** Optional transient task-bar geometry while a visible bar is actively moved or resized. */
  readonly activeTaskInteractionRange?: {
    readonly taskId: TaskId;
    readonly kind: 'task' | 'summary' | 'milestone';
    readonly left: number;
    readonly width: number;
  } | null;
}
```

| Member | Type / return | Required | Default | Description |
|---|---|:---:|---|---|
| `rows` | `readonly GanttGridRow[]` | Yes | — | All task grid rows (full dataset). |
| `viewportRows` | `readonly VirtualPositionItem[]` | Yes | — | Virtual position items describing which rows are currently visible. |
| `scrollLeft` | `number` | Yes | — | Current horizontal scroll offset in pixels. |
| `scrollTop` | `number` | Yes | — | Current vertical scroll offset in pixels. |
| `viewportWidth` | `number` | Yes | — | Width of the visible viewport in pixels. |
| `viewportHeight` | `number` | Yes | — | Height of the visible viewport in pixels. |
| `includeOffscreenRows` | `boolean \| undefined` | No | — | Keep anchors outside the viewport for overlay routes that cross the visible frame. |
| `activeTaskInteractionRange` | `{ readonly taskId: TaskId; readonly kind: "task" \| "summary" \| "milestone"; readonly left: number; readonly width: number; } \| null \| undefined` | No | — | Optional transient task-bar geometry while a visible bar is actively moved or resized. |

**Related types:** [`GanttGridRow`](/api/gantt/columns/#ganttgridrow), [`TaskId`](/api/gantt/data-model/#taskid)

## `WheelZoomTrigger`

<span class="api-kind">type</span>

Modifier key that must be held to trigger wheel-based zoom.

```ts
export type WheelZoomTrigger = 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey' | 'none';
```

## `ZoomAnchorMode`

<span class="api-kind">type</span>

Anchor strategy determining which viewport position stays fixed during zoom.

```ts
export type ZoomAnchorMode = 'pointer' | 'center' | 'start';
```

---

# Grid Notes

URL: https://pro.rv-grid.com/api/grid-notes/
Source: src/content/docs/api/grid-notes.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  gridNotes?: GridNotesConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /** @deprecated Use `grid.gridNotes`. */
      gridNotes?: GridNotesConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  gridnotechange: GridNoteChangeEvent;
  gridnotemention: GridNoteMentionEvent;
  gridnoteconflict: GridNoteConflictError;
  gridnoteerror: GridNoteErrorEvent;
  gridnotefilterchange: GridNoteFilterChangeEvent
}
```

## Plugin API

### `GridNoteSeverity`

```ts
export type GridNoteSeverity = 'none' | 'info' | 'warning' | 'blocker' | 'resolved';
```

---

### `GridNotePermissionAction`

```ts
export type GridNotePermissionAction = 'view' | 'create' | 'edit' | 'delete' | 'restore';
```

---

### `GridNoteTarget`

```ts
export type GridNoteTarget =
  | { readonly kind: 'row'; readonly rowKey: string }
  | { readonly kind: 'cell'; readonly rowKey: string; readonly colProp: ColumnProp };
```

---

### `GridNoteUser`

```ts
interface GridNoteUser {
  readonly id: string;
  readonly name: string;
  readonly email?: string;
  readonly avatarUrl?: string;
  readonly color?: string
}
```

---

### `GridNoteMention`

```ts
interface GridNoteMention {
  readonly userId: string;
  readonly label: string;
  readonly start: number;
  readonly end: number
}
```

---

### `GridNoteSummary`

```ts
interface GridNoteSummary {
  readonly id: string;
  readonly target: GridNoteTarget;
  readonly severity: GridNoteSeverity;
  readonly excerpt: string;
  readonly author: GridNoteUser;
  readonly createdAt: string;
  readonly updatedAt: string;
  readonly version: number;
  readonly versionCount: number;
  readonly pending?: boolean
}
```

---

### `GridNote` (Extended from `index.ts`)

```ts
interface GridNote {
  readonly body: string;
  readonly mentions: readonly GridNoteMention[]
}
```

---

### `GridNoteVersion`

```ts
interface GridNoteVersion {
  readonly id: string;
  readonly noteId: string;
  readonly version: number;
  readonly body: string;
  readonly severity: GridNoteSeverity;
  readonly mentions: readonly GridNoteMention[];
  readonly author: GridNoteUser;
  readonly createdAt: string;
  readonly changeSummary: string;
  readonly restoredFromVersionId?: string
}
```

---

### `GridNotePage`

```ts
interface GridNotePage {
  readonly items: readonly T[];
  readonly nextCursor?: string
}
```

---

### `GridNoteMutationInput`

```ts
interface GridNoteMutationInput {
  readonly target: GridNoteTarget;
  readonly body: string;
  readonly severity: GridNoteSeverity;
  readonly mentions: readonly GridNoteMention[];
  readonly actor: GridNoteUser;
  readonly expectedVersion?: number;
  readonly mutationId: string;
  readonly signal?: AbortSignal
}
```

---

### `GridNoteUpsertInput`

```ts
interface GridNoteUpsertInput {
  readonly target: GridNoteTarget;
  readonly body: string;
  readonly severity: GridNoteSeverity;
  readonly mentions?: readonly GridNoteMention[];
  readonly expectedVersion?: number
}
```

---

### `GridNoteStorageAdapter`

```ts
interface GridNoteStorageAdapter {
  init?(): void | Promise<void>;
  destroy?(): void | Promise<void>;
  loadSummaries(input: { rowKeys: readonly string[]; signal?: AbortSignal }): Promise<readonly GridNoteSummary[]>;
  getNote(input: { target: GridNoteTarget; signal?: AbortSignal }): Promise<GridNote | undefined>;
  listVersions(input: { noteId: string; cursor?: string; limit: number; signal?: AbortSignal }): Promise<GridNotePage<GridNoteVersion>>;
  upsert(input: GridNoteMutationInput): Promise<GridNote>;
  delete(input: { target: GridNoteTarget; actor: GridNoteUser; expectedVersion?: number; mutationId: string; signal?: AbortSignal }): Promise<void>;
  restoreVersion(input: { noteId: string; versionId: string; actor: GridNoteUser; expectedVersion: number; mutationId: string; signal?: AbortSignal }): Promise<GridNote>;
  queryRowKeysBySeverity(input: { severities: readonly GridNoteSeverity[]; signal?: AbortSignal }): Promise<readonly string[]>;
  listNotes(input: { cursor?: string; limit: number; signal?: AbortSignal }): Promise<GridNotePage<GridNote>>
}
```

---

### `GridNotePermissionContext`

```ts
interface GridNotePermissionContext {
  readonly action: GridNotePermissionAction;
  readonly target: GridNoteTarget;
  readonly row?: T;
  readonly note?: GridNote;
  readonly user: GridNoteUser
}
```

---

### `GridNotesLabels`

```ts
interface GridNotesLabels {
  addNote: string;
  addCell: string;
  editCell: string;
  addRow: string;
  editRow: string;
  filter: string;
  clearFilter: string;
  save: string;
  cancel: string;
  edit: string;
  close: string;
  history: string;
  restore: string;
  delete: string;
  color: string;
  none: string;
  info: string;
  warning: string;
  blocker: string;
  resolved: string;
  alsoOnRow: string
}
```

---

### `GridNotesConfig`

```ts
interface GridNotesConfig {
  readonly adapter: GridNoteStorageAdapter;
  readonly getRowId: (row: T, context: { rowIndex: number; rowType: DimensionRows }) => string | number | undefined;
  /** Optional human-readable row value for note titles. Stable row IDs remain internal. */
    readonly getRowLabel?: (row: T) => string | number | undefined | null;
  readonly getCurrentUser: () => GridNoteUser | Promise<GridNoteUser>;
  readonly can?: (context: GridNotePermissionContext<T>) => boolean | Promise<boolean>;
  readonly mentions?: { search(query: string, signal?: AbortSignal): Promise<readonly GridNoteUser[]> };
  readonly prefetchRows?: number;
  readonly coalesceMs?: number;
  readonly historyPageSize?: number;
  readonly draftStorageKey?: string;
  readonly retryMaxDelayMs?: number;
  readonly confirmDiscard?: (message: string) => boolean | Promise<boolean>;
  readonly confirmDelete?: (message: string) => boolean | Promise<boolean>;
  readonly labels?: Partial<GridNotesLabels>;
  readonly severityColors?: Partial<Record<GridNoteSeverity, string>>;
  readonly excel?: { readonly includeNotesSheet?: boolean; readonly sheetName?: string }
}
```

---

### `GridNoteOpenOptions`

```ts
interface GridNoteOpenOptions {
  readonly mode?: 'read' | 'edit';
  readonly anchor?: HTMLElement;
  readonly row?: DataType
}
```

---

### `GridNoteChangeEvent`

```ts
interface GridNoteChangeEvent {
  readonly type: 'upsert' | 'delete' | 'restore';
  readonly target: GridNoteTarget;
  readonly note?: GridNote;
  readonly pending?: boolean
}
```

---

### `GridNoteMentionEvent`

```ts
interface GridNoteMentionEvent {
  readonly note: GridNote;
  readonly users: readonly GridNoteUser[]
}
```

---

### `GridNoteFilterChangeEvent`

```ts
interface GridNoteFilterChangeEvent {
  readonly severities: readonly GridNoteSeverity[]
}
```

---

### `GridNoteErrorEvent`

```ts
interface GridNoteErrorEvent {
  readonly phase: string;
  readonly error: unknown;
  readonly target?: GridNoteTarget
}
```

---

### `GridNoteConflictError`

```ts
class GridNoteConflictError {}
```

---

### `gridNoteTargetKey`

```ts
export function gridNoteTargetKey(target: GridNoteTarget): string;
```

---

### `gridNotePopoverTitle`

Formats a human-readable popover title without leaking the stable row key.

```ts
export function gridNotePopoverTitle(
  target: GridNoteTarget,
  rowLabel: string | number | null | undefined,
  hasNote: boolean,
): string;
```

---

### `gridNoteExcerpt`

```ts
export function gridNoteExcerpt(body: string): string;
```

---

### `toGridNoteSummary`

```ts
export function toGridNoteSummary(note: GridNote, pending = note.pending): GridNoteSummary;
```

---

### `cloneGridNote`

```ts
export function cloneGridNote<T extends GridNote | GridNoteSummary>(note: T): T;
```

---

### `createGridNoteId`

```ts
export function createGridNoteId(prefix: string): string;
```

---

### `diffGridNoteMentionUserIds`

```ts
export function diffGridNoteMentionUserIds(
  previous: readonly { userId: string }[],
  next: readonly { userId: string }[],
): string[];
```

---

### `GRID_NOTE_EXCERPT_LENGTH`

```ts
GRID_NOTE_EXCERPT_LENGTH: 120;
```

---

### `GridNoteStoreListener`

```ts
export type GridNoteStoreListener = (rowKeys: readonly string[]) => void;
```

---

### `GridNoteStore`

```ts
class GridNoteStore {
  subscribe(listener: GridNoteStoreListener): () => void;

  get(target: GridNoteTarget): GridNoteSummary | undefined;

  getRow(rowKey: string): GridNoteSummary[];

  set(note: GridNote | GridNoteSummary): void;

  remove(target: GridNoteTarget): void;

  markPending(target: GridNoteTarget, pending: boolean): void;

  queueRows(rowKeys: readonly string[], force = false): Promise<void>;

  async flushRows(signal?: AbortSignal): Promise<void>;

  getNote(target: GridNoteTarget, signal?: AbortSignal): Promise<GridNote | undefined>;

  listVersions(noteId: string, cursor: string | undefined, limit: number, signal?: AbortSignal): Promise<GridNotePage<GridNoteVersion>>;

  queryRowKeysBySeverity(severities: readonly GridNoteSeverity[], signal?: AbortSignal): Promise<readonly string[]>;

  clear(): void;

  destroy(): void;
}
```

---

### `InMemoryGridNoteAdapter`

```ts
class InMemoryGridNoteAdapter {
  async loadSummaries({ rowKeys, signal }: { rowKeys: readonly string[]; signal?: AbortSignal }): Promise<readonly GridNoteSummary[]>;

  async getNote({ target, signal }: { target: GridNoteTarget; signal?: AbortSignal }): Promise<GridNote | undefined>;

  async listVersions({ noteId, cursor, limit, signal }: { noteId: string; cursor?: string; limit: number; signal?: AbortSignal }): Promise<GridNotePage<GridNoteVersion>>;

  async upsert(input: GridNoteMutationInput): Promise<GridNote>;

  async delete(input: { target: GridNoteTarget; actor: GridNoteUser; expectedVersion?: number; mutationId: string; signal?: AbortSignal }): Promise<void>;

  async restoreVersion(input: { noteId: string; versionId: string; actor: GridNoteUser; expectedVersion: number; mutationId: string; signal?: AbortSignal }): Promise<GridNote>;

  async queryRowKeysBySeverity({ severities, signal }: { severities: readonly GridNoteSeverity[]; signal?: AbortSignal }): Promise<readonly string[]>;

  async listNotes({ cursor, limit, signal }: { cursor?: string; limit: number; signal?: AbortSignal }): Promise<GridNotePage<GridNote>>;
}
```

---

### `createGridNotesWorksheet`

```ts
export function createGridNotesWorksheet(
  notes: readonly GridNote[],
  getColumnLabel: (prop: ColumnProp) => string,
  sheetName = 'Notes',
): ExcelExportWorksheetDescriptor;
```

---

### `GridNotesPlugin`

Cell and row notes backed by a host adapter and stable authored row ids.

#### Dependencies

- **Auto-installed** `ContextMenuPlugin`: Adds cell, row, and severity-filter commands to the shared low-level context menu.
- **Event integration** `ExportExcelPlugin`: Appends a Notes worksheet when Excel export is installed and notes-sheet export is enabled.
- **Auto-installed** `TooltipPlugin`: Shows note excerpts over pseudo-element marker hit areas without adding cell DOM.

```ts
class GridNotesPlugin {
  async openNote(target: GridNoteTarget, options: GridNoteOpenOptions = {}): Promise<void>;

  getNote(target: GridNoteTarget, signal?: AbortSignal): Promise<GridNote | undefined>;

  async upsertNote(input: GridNoteUpsertInput): Promise<GridNote>;

  async removeNote(target: GridNoteTarget): Promise<void>;

  async refreshNotes(rowKeys?: readonly string[]): Promise<void>;

  getSeverityFilter(): readonly GridNoteSeverity[];

  async setSeverityFilter(severities: readonly GridNoteSeverity[]): Promise<void>;

  destroy(): void;
}
```

---

# Grouping

URL: https://pro.rv-grid.com/api/grouping/
Source: src/content/docs/api/grouping.md

### `getGroupingData`

Extracts grouping data from the store for a specific row

**@param** store - The data store

**@param** itemIndex - The index of the current item

**@param** currentDepth - The current depth of the grouping

**@param** columnProp - The column property to aggregate

**@param** aggregator - The aggregation function to apply

**@returns** An object containing the count, values, and aggregation result

```ts
export function getGroupingData({
  store,
  itemIndex,
  currentDepth,
  columnProp,
  aggregator,
}: {
  store: Observable<any>,
  itemIndex: number,
  currentDepth: number,
  columnProp: ColumnProp,
  aggregator?: (values: any[]) => any
}): GroupingData;
```

---

### `GroupingAggregationTemplate`

The `GroupingAggregationTemplate` type defines the structure of aggregation functions
that can be used for grouping in a RevoGrid.

```ts
/**
 * The `GroupingAggregationTemplate` type defines the structure of aggregation functions
 * that can be used for grouping in a RevoGrid.
 */
export type GroupingAggregationTemplate = {
  aggregations?: { [key: string]: (values: any[]) => any };
}
```

---

### `GroupingData`

The `GroupingData` type defines the structure of data returned by the getGroupingData function

```ts
/**
 * The `GroupingData` type defines the structure of data returned by the getGroupingData function
 */
export type GroupingData = {
  count: number;
  values: DataType[];
  aggregationValue: any;
};
```

---

### `groupingAggregation`

The `groupingAggregation` function is a template for creating custom aggregation functions
that can be used for grouping in a RevoGrid.

This function takes a template object with an optional `aggregations` property, which is a
key-value pair where the key is the column property name and the value is an aggregation function.
The aggregation functions receive an array of values and return a single aggregated result.

### Example
```typescript
const aggregations = {
  'name': (values: string[]) => values.join(', ')
}

const template: GroupLabelTemplateFunc = (h, props) => {
  return groupingAggregation(h, props, aggregations);
}

const grid = document.createElement('revo-grid');
grid.columns = [
  { prop: 'name', name: 'Name', template: template }
]
```

```ts
groupingAggregation: GroupLabelTemplateFunc;
```

---

# GroupingRow

URL: https://pro.rv-grid.com/api/groupingrow/
Source: src/content/docs/api/groupingRow.md

## Module Extensions

### `HTMLRevoGridElementEventMap` (Extended from `global`)

grid.addEventListener(GROUP_EXPAND_EVENT, (e: OnExpandEvent) => {
 console.log(e)
})

```ts
interface HTMLRevoGridElementEventMap {
  [GROUP_EXPAND_EVENT]: OnExpandEvent
}
```

## Plugin API

### `GROUP_DEPTH`

```ts
GROUP_DEPTH: string;
```

---

### `PSEUDO_GROUP_ITEM`

```ts
PSEUDO_GROUP_ITEM: string;
```

---

### `PSEUDO_GROUP_ITEM_ID`

```ts
PSEUDO_GROUP_ITEM_ID: string;
```

---

### `PSEUDO_GROUP_ITEM_VALUE`

```ts
PSEUDO_GROUP_ITEM_VALUE: string;
```

---

### `PSEUDO_GROUP_COLUMN`

```ts
PSEUDO_GROUP_COLUMN: string;
```

---

### `GROUP_EXPANDED`

```ts
GROUP_EXPANDED: string;
```

---

### `GROUP_COLUMN_PROP`

```ts
GROUP_COLUMN_PROP: string;
```

---

### `GROUP_ORIGINAL_INDEX`

```ts
GROUP_ORIGINAL_INDEX: string;
```

---

### `GROUP_EXPAND_BTN`

```ts
GROUP_EXPAND_BTN: string;
```

---

### `GROUP_EXPAND_EVENT`

```ts
GROUP_EXPAND_EVENT: string;
```

---

### `GROUPING_ROW_TYPE`

```ts
GROUPING_ROW_TYPE: DimensionRows;
```

---

### `doCollapse`

```ts
export declare function doCollapse(pIndex: number, source: DataType[]): {
    trimmed: Record<number, boolean>;
};;
```

---

### `doExpand`

**@param** pIndex - physical index

**@param** vIndex - virtual index, need to update item collection

**@param** source - data source

**@param** rowItemsIndexes - rgRow indexes

```ts
export declare function doExpand(vIndex: number, source: DataType[], rowItemsIndexes: number[]): {
    trimmed: Record<number, boolean>;
    items?: number[];
};;
```

---

### `GroupingRowPlugin`

```ts
class GroupingRowPlugin {
  getStore(type?: DimensionRows): Observable<DSourceState<DataType, DimensionRows>>;;

  /**
       * External call to apply grouping. Called by revogrid when prop changed.
       */
  setGrouping(options: GroupingOptions): void;;

  clearGrouping(): void;;
}
```

---

### `RowGroupingProps` (Extended from `grouping.row.plugin.d.ts`)

```ts
export type RowGroupingProps = GroupRowPros & PositionItem & {
    /**
     * Visible columns in the grid, can be used to get the width of the column and position of the column
     * to calculate the position of the cells in the grouping row
     */
    columnItems: VirtualPositionItem[];
};
```

---

### `GroupRowPros` (Extended from `grouping.row.plugin.d.ts`)

```ts
interface GroupRowPros {
  model: DataType;
  hasExpand: boolean;
  providers: Providers;
  groupingCustomRenderer?: GroupLabelTemplateFunc | null;
  groupingCellRenderer?: GroupCellTemplateFunc | null;
  additionalData?: any
}
```

---

### `GroupLabelTemplateFunc`

```ts
export type GroupLabelTemplateFunc = (createElement: HyperFunc<VNode>, props: GroupTemplateProp & RowGroupingProps, ...args: any[]) => any;
```

---

### `GroupCellTemplateProp` (Extended from `grouping.row.plugin.d.ts`)

```ts
interface GroupCellTemplateProp {
  /**
       * Column viewport type that owns the cell.
       */
      colType: DimensionCols | 'rowHeaders';
  /**
       * Current virtual column position. Only columns rendered by the viewport are
       * passed to the group cell template.
       */
      columnItem: VirtualPositionItem;
  /**
       * Current virtual row position.
       */
      rowItem: VirtualPositionItem;
  /**
       * Semantic information about the synthetic group row.
       */
      group: {
          name: string;
          depth: number;
          expanded: boolean;
          prop: ColumnProp;
          isLabelColumn: boolean;
          canExpand: boolean;
          onExpand(event: MouseEvent): void;
      }
}
```

---

### `GroupCellTemplateFunc`

```ts
export type GroupCellTemplateFunc = (createElement: HyperFunc<VNode>, props: GroupCellTemplateProp, additionalData?: any) => any;
```

---

### `GroupingOptions` (Extended from `grouping.row.plugin.d.ts`)

```ts
export type GroupingOptions = {
    /**
     * Column props to which grouping will be applied
     */
    props?: ColumnProp[];
    /**
     * Should grouping be preserved on source update.
     * default: true
     */
    preserveGroupingOnUpdate?: boolean;
    /**
     * Custom group label template
     */
    groupLabelTemplate?: GroupLabelTemplateFunc;
    /**
     * Custom template for cells in synthetic group rows.
     * When provided, group rows render only the columns in the current horizontal
     * viewport and this template takes precedence over `groupLabelTemplate`.
     */
    groupCellTemplate?: GroupCellTemplateFunc;
} & ExpandedOptions;
```

---

### `BeforeSourceSetEvent`

```ts
export type BeforeSourceSetEvent = {
    type: DimensionRows;
    source: DataType[];
};
```

---

### `OnExpandEvent`

```ts
export type OnExpandEvent = {
    model: DataType;
    virtualIndex: number;
};
```

---

### `ExpandedOptions`

```ts
export type ExpandedOptions = {
    /**
     * Currently expanded items. to set expanded: '{ 'a': true, 'a,b': true, 'a,b,c': true }'
     */
    prevExpanded?: Record<string, boolean>;
    /**
     * Is expanded by default
     */
    expandedAll?: boolean;
    /**
     * Custom group label value parser
     */
    getGroupValue?(item: DataType, prop: string | number): any;
    /**
     * Replacement group value for `null` and `undefined` keys.
     * Used by the default group value resolver.
     * @default ''
     */
    emptyGroupValue?: any;
    /**
     * Custom group label template
     */
    groupLabelTemplate?: GroupLabelTemplateFunc;
    /**
     * Custom template for virtualized cells in synthetic group rows.
     */
    groupCellTemplate?: GroupCellTemplateFunc;
};
```

---

### `getSource`

```ts
export declare function getSource(source: DataType[], items: number[], withoutGrouping?: boolean): Required<SourceGather>;;
```

---

### `getExpanded`

```ts
export declare function getExpanded(model?: DataType): any;;
```

---

### `gatherGrouping`

Gather data for grouping

**@param** array - flat data array

**@param** columnProps - ids of groups

**@param** expanded - potentially expanded items if present

```ts
export declare function gatherGrouping(array: DataType[], columnProps: ColumnProp[], { prevExpanded, expandedAll, getGroupValue, emptyGroupValue, }: ExpandedOptions): {
    sourceWithGroups: DataType[];
    depth: number;
    trimmed: Record<number, boolean>;
    oldNewIndexMap: Record<number, number>;
};;
```

---

### `getGroupingName`

```ts
export declare function getGroupingName(rgRow?: DataType): any;;
```

---

### `isGrouping`

```ts
export declare function isGrouping(rgRow?: DataType): rgRow is GroupingItem;;
```

---

### `isGroupingColumn`

```ts
export declare function isGroupingColumn(column?: ColumnRegular): boolean;;
```

---

### `measureEqualDepth`

```ts
export declare function measureEqualDepth<T>(groupA: T[], groupB: T[]): number;;
```

---

### `getParsedGroup`

```ts
export declare function getParsedGroup(id: string): any[] | null;;
```

---

### `isSameGroup`

```ts
export declare function isSameGroup(currentGroup: any[], currentModel: DataType, nextModel: DataType): boolean;;
```

---

### `expandEvent`

```ts
export declare function expandEvent(e: MouseEvent, model: DataType, virtualIndex: number): void;;
```

---

### `renderGroupCells`

```ts
export declare function renderGroupCells(props: RowGroupingProps, { name, expanded, depth, }: {
    name: string;
    expanded: boolean;
    depth: number;
}): VNodeResponse[];;
```

---

### `GroupingRowRenderer`

```ts
GroupingRowRenderer: (props: RowGroupingProps) => any;
```

---

### `expandSvgIconVNode`

```ts
expandSvgIconVNode: (expanded?: boolean | undefined) => any;
```

---

### `default`

```ts
GroupingRowRenderer: (props: RowGroupingProps) => any;
```

---

# History

URL: https://pro.rv-grid.com/api/history/
Source: src/content/docs/api/history.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  history?: HistoryConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /**
         * Event for undo
         *
         * @example
         * ```typescript
         * grid.addEventListener(BEFORE_UNDO_EVENT, (e) => {
         *   console.log(e);
         * });
         */
        [BEFORE_UNDO_EVENT]: {
          data: BeforeRangeSaveDataDetails['data'];
          type: DimensionRows;
          lastChange: HistoryEntry;
        };
  /**
         * Event for redo
         *
         * @example
         * ```typescript
         * grid.addEventListener(BEFORE_REDO_EVENT, (e) => {
         *   console.log(e);
         * });
         */
        [BEFORE_REDO_EVENT]: {
          data: BeforeRangeSaveDataDetails['data'];
          type: DimensionRows;
          lastChange: HistoryEntry;
        };
  /**
         *
         */
        [BEFORE_HIST_EDIT_EVENT]: HistoryReplayDetail;
  [HISTORY_CHANGED_EVENT]: HistoryState;
  [HISTORY_ERROR_EVENT]: HistoryError
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
         * @deprecated Use the direct `grid.history` property instead.
         */
        history?: HistoryConfig
}
```

## Plugin API

### `createLocalStorageHistoryAdapter`

```ts
export function createLocalStorageHistoryAdapter(storageKey = DEFAULT_STORAGE_KEY): HistoryStorageAdapter;
```

---

### `HistoryPlugin`

The `HistoryPlugin` for RevoGrid provides undo and redo functionalities, allowing users to
navigate through their editing history within the grid. This plugin is essential for enhancing
user experience by offering flexibility to revert or reapply changes made during data manipulation.

**Key Features**:
- **Undo/Redo Stacks**: Maintains separate stacks for undo and redo operations, with a configurable
  (currently fixed at 200) maximum stack size to manage memory usage efficiently.
- **Event Handling**: Listens to `ON_EDIT_EVENT` to track changes and updates the undo stack
  accordingly. It also captures `Ctrl+Z` and `Ctrl+Y` (or `Cmd` on macOS) keystrokes via the
  `BEFORE_KEYDOWN_EVENT` to trigger undo and redo actions.
- **Event Emission**: Utilizes `BEFORE_UNDO_EVENT` and `BEFORE_REDO_EVENT` to allow pre-processing
  or cancellation of undo/redo actions. Replays accepted changes through `BEFORE_HIST_EDIT_EVENT`
  so EventManager integrations can apply them and downstream plugins can react consistently.
- **Disabling and Clearing**: Provides methods to disable the plugin (preventing changes from being
  added to stacks) and to clear both stacks, resetting the history.
- **Atomic Context-menu Mutations**: Tracks built-in Cut, Paste, Clear, row mutations, and column
  schema mutations as one entry per command when `DataGridContextMenuPlugin` is installed. Copy and
  application-provided command handlers remain untracked.

**Usage**:
- Integrate the `HistoryPlugin` within the RevoGrid to enable robust undo/redo capabilities.
  This involves adding the plugin to the grid's plugin list, allowing automatic management of
  editing actions.

### Example
```typescript
import { HistoryPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [HistoryPlugin];
```

`HistoryPlugin` automatically installs `EventManagerPlugin` when it is not
already registered so normal cell edits, paste, range edits, and Pro editors
enter the undo stack. History keyboard shortcuts are wired automatically.

This plugin is ideal for applications requiring reliable data editing workflows, providing users
with the ability to correct mistakes or revisit previous states seamlessly.

#### Dependencies

- **Auto-installed** `EventManagerPlugin`: Installs EventManagerPlugin when absent for normal edit history capture.

```ts
class HistoryPlugin {
  canUndo();

  canRedo();

  getUndoStackSize();

  getRedoStackSize();

  isDisabled();

  clear();

  disable(disable = true);

  undo();

  redo();

  replayChange(detail: HistoryReplayDetail): boolean;
}
```

---

### `HistoryReplayDetail` (Extended from `index.ts`)

```ts
export type HistoryReplayDetail = Pick<EventManagerEvent, 'data' | 'type' | 'models' | 'previousData' | 'history'>
  & Partial<Pick<EventManagerEvent, 'sourceMutation'>>
  & Partial<Pick<EventManagerEvent, 'eventTypes'>>
  & { historyDirection?: 'undo' | 'redo' };
```

---

### `RowOrderHistoryEntry` (Extended from `index.ts`)

```ts
export type RowOrderHistoryEntry = EventManagerEvent & {
  historyType: 'row-order';
  rowOrder: RowOrderHistoryChange;
};
```

---

### `DataGridFormattingHistoryEntry` (Extended from `index.ts`)

```ts
export type DataGridFormattingHistoryEntry = EventManagerEvent & {
  historyType: 'data-grid-formatting';
  formatting: {
    before: DataGridFormattingRuntimeState;
    after: DataGridFormattingRuntimeState;
  };
};
```

---

### `ContextMenuRowSourcesSnapshot`

```ts
export type ContextMenuRowSourcesSnapshot = Record<DimensionRows, DataType[]>;
```

---

### `ContextMenuTreeRowsSnapshot`

```ts
export type ContextMenuTreeRowsSnapshot = {
  sources: ContextMenuRowSourcesSnapshot;
  tree: TreeStructureSnapshot;
};
```

---

### `ContextMenuStructuralHistoryChange`

```ts
export type ContextMenuStructuralHistoryChange =
  | {
      kind: 'rows';
      before: ContextMenuRowSourcesSnapshot;
      after: ContextMenuRowSourcesSnapshot;
    }
  | {
      kind: 'columns';
      before: ColumnData;
      after: ColumnData;
    }
  | {
      kind: 'tree';
      before: TreeStructureSnapshot;
      after: TreeStructureSnapshot;
    }
  | {
      kind: 'tree-rows';
      before: ContextMenuTreeRowsSnapshot;
      after: ContextMenuTreeRowsSnapshot;
    };
```

---

### `ContextMenuHistoryEntry` (Extended from `index.ts`)

One built-in context-menu mutation and every edit it emitted.

```ts
/** One built-in context-menu mutation and every edit it emitted. */
export type ContextMenuHistoryEntry = EventManagerEvent & {
  historyType: 'context-menu';
  contextMenu: {
    commandId: HistoryTransactionCommandId;
    edits: EventManagerEvent[];
    structure?: ContextMenuStructuralHistoryChange;
  };
};
```

---

### `HistoryEntry`

```ts
export type HistoryEntry = EventManagerEvent
  | RowOrderHistoryEntry
  | DataGridFormattingHistoryEntry
  | ContextMenuHistoryEntry;
```

---

### `HistoryStorageState`

```ts
export type HistoryStorageState = {
  undoStack?: HistoryEntry[];
  redoStack?: HistoryEntry[];
  updatedAt?: string;
  sourceId?: string;
  disabled?: boolean;
};
```

---

### `HistoryStorageAdapter`

```ts
export type HistoryStorageAdapter = {
  load?: () => HistoryStorageState | undefined | null | Promise<HistoryStorageState | undefined | null>;
  save?: (state: HistoryStorageState) => void | Promise<void>;
  clear?: () => void | Promise<void>;
};
```

---

### `HistoryError`

```ts
export type HistoryError = {
  phase: 'storage-load' | 'storage-save' | 'storage-clear' | 'storage-source-mismatch' | 'replay';
  error: unknown;
  state?: HistoryStorageState;
  providerIndex?: number;
};
```

---

### `HistoryConfig`

```ts
export type HistoryConfig = {
  /**
   * Initial undo stack used by the plugin.
   *
   * Use this when restoring history from an application-owned state object.
   * New edits are appended to this stack and trimmed to `maxStackSize`.
   *
   * @default []
   */
  undoStack?: HistoryEntry[];
  /**
   * Initial redo stack used by the plugin.
   *
   * This stack is cleared when a new user edit is captured.
   *
   * @default []
   */
  redoStack?: HistoryEntry[];
  /**
   * Maximum number of entries kept in each history stack.
   *
   * When a stack grows beyond this limit, the oldest entry is removed.
   *
   * @default 200
   */
  maxStackSize?: number;
  /**
   * Starts the plugin in a disabled state.
   *
   * Disabled history does not capture edits and does not run undo or redo.
   * The runtime state can also be changed with `HistoryPlugin.disable()`.
   *
   * @default false
   */
  disabled?: boolean;
  /**
   * Stable identifier for the dataset whose history is being stored.
   *
   * When loaded storage state contains a different `sourceId`, the plugin skips
   * that state and emits `historyerror` with the `storage-source-mismatch` phase.
   */
  sourceId?: string;
  /**
   * Built-in storage mode for undo and redo stacks.
   *
   * Use `memory` for in-memory history only, `localStorage` for the built-in
   * browser adapter, or `custom` with `storageAdapter`.
   *
   * @default 'memory'
   */
  storage?: 'memory' | 'localStorage' | 'custom';
  /**
   * Key used by the built-in localStorage adapter.
   *
   * Only applies when `storage` is `localStorage`.
   *
   * @default 'revogrid-history'
   */
  storageKey?: string;
  /**
   * Custom storage adapter for loading, saving, and clearing history state.
   *
   * Used when `storage` is `custom`, and also accepted with `memory` as an
   * explicit adapter source.
   */
  storageAdapter?: HistoryStorageAdapter;
  /**
   * Ordered storage adapters for cache/server provider chains.
   *
   * When provided, this takes precedence over `storage` and `storageAdapter`.
   * Providers are loaded in order, and newer compatible states can replace
   * earlier loaded states.
   */
  storageProviders?: HistoryStorageAdapter[];
  /**
   * Clears undo and redo stacks when the grid source is replaced.
   *
   * Defaults to `false` when persistent storage is configured so restored
   * history is not erased by the initial source load. Otherwise defaults to
   * `true`.
   */
  clearOnSourceChange?: boolean;
  /**
   * Clears undo and redo stacks after filter topology changes.
   *
   * Initial filter events before the first grid render do not clear restored
   * history.
   *
   * @default true
   */
  clearOnFilterChange?: boolean;
  /**
   * Clears undo and redo stacks after sorting topology changes.
   *
   * Initial sorting events before the first grid render do not clear restored
   * history.
   *
   * @default true
   */
  clearOnSortingChange?: boolean;
  /**
   * Controls how successful `RowOrderPlugin` drops interact with history.
   *
   * `track` records each committed drop as one undo/redo entry. `clear`
   * clears both stacks after a committed drop. `preserve` leaves the stacks
   * unchanged so a domain integration such as Gantt can record its own entry.
   *
   * @default 'track'
   */
  rowOrderHistory?: 'track' | 'clear' | 'preserve';
  /**
   * Allows undo/redo keyboard shortcuts to run from document keydown events even
   * when the grid does not currently report a focused cell.
   *
   * @default true
   */
  keyboardShortcutsWithoutFocus?: boolean;
};
```

---

### `HistoryState`

```ts
export type HistoryState = {
  undoStackSize: number;
  redoStackSize: number;
  canUndo: boolean;
  canRedo: boolean;
  disabled: boolean;
};
```

---

### `isContextMenuHistoryEntry`

```ts
export function isContextMenuHistoryEntry(
  entry: HistoryEntry,
): entry is ContextMenuHistoryEntry;
```

---

### `replayContextMenuStructure`

Restore application-owned structural state without sharing mutable arrays.

```ts
export function replayContextMenuStructure(
  revogrid: HTMLRevoGridElement,
  providers: PluginProviders,
  change: ContextMenuStructuralHistoryChange,
  direction: 'undo' | 'redo',
): void;
```

---

### `isDataGridFormattingHistoryEntry`

```ts
export function isDataGridFormattingHistoryEntry(
  entry: HistoryEntry,
): entry is DataGridFormattingHistoryEntry;
```

---

### `replayDataGridFormatting`

```ts
export function replayDataGridFormatting(
  providers: PluginProviders,
  entry: DataGridFormattingHistoryEntry,
  direction: 'undo' | 'redo',
): boolean;
```

---

### `HistoryStorageController`

**@internal** Owns HistoryPlugin storage configuration, I/O, and load ordering.

```ts
class HistoryStorageController {
  configure(history: HistoryConfig | undefined): void;

  markLocalMutation(): void;

  save(): void;

  clear(): void;
}
```

---

### `cloneValue`

```ts
export function cloneValue<T>(value: T): T;
```

---

### `cloneStack`

```ts
export function cloneStack(stack: HistoryEntry[] | undefined): HistoryEntry[];
```

---

### `cloneStorageState`

```ts
export function cloneStorageState(state: HistoryStorageState): HistoryStorageState;
```

---

### `isPromiseLike`

```ts
export function isPromiseLike(value: unknown): value is Promise<unknown>;
```

---

### `toTime`

```ts
export function toTime(value: string | undefined, fallback: number);
```

---

### `isHistoryStorageState`

```ts
export function isHistoryStorageState(value: unknown): value is HistoryStorageState;
```

---

### `hasHistoryStorage`

```ts
export function hasHistoryStorage(history: HistoryConfig | undefined);
```

---

### `HISTORY_STORAGE_KEY`

```ts
HISTORY_STORAGE_KEY: string;
```

---

### `isRowOrderHistoryEntry`

```ts
export function isRowOrderHistoryEntry(
  entry: HistoryEntry,
): entry is RowOrderHistoryEntry;
```

---

### `replayRowOrder`

```ts
export function replayRowOrder(
  providers: PluginProviders,
  entry: RowOrderHistoryEntry,
  direction: 'undo' | 'redo',
): boolean;
```

---

# History Controls

URL: https://pro.rv-grid.com/api/history-controls/
Source: src/content/docs/api/history-controls.md

### `defineHistoryControls`

Renders the history undo/redo toolbar into `el` for the given RevoGrid element.

The grid must have `HistoryPlugin` installed. The toolbar shows undo/redo buttons
with count badges indicating how many steps are available in each direction.

### Example
```ts
import { defineHistoryControls } from '@revolist/revogrid-pro';

const toolbar = document.createElement('div');
container.prepend(toolbar);
defineHistoryControls(toolbar, grid);
```

```ts
export function defineHistoryControls(el: HTMLElement, grid: HTMLRevoGridElement): void;
```

---

# Icons

URL: https://pro.rv-grid.com/api/icons/
Source: src/content/docs/api/icons.md

### `chevronDownIcon`

```ts
src: string;
```

---

# Infinity Scroll

URL: https://pro.rv-grid.com/api/infinity-scroll/
Source: src/content/docs/api/infinity-scroll.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  infinityScroll?: Partial<InfinityScrollConfig>;
  'infinity-scroll'?: Partial<InfinityScrollConfig>
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /**
       * Event for scroll change
       *
       * @example
       * ```typescript
        * grid.addEventListener(SCROLL_CHANGE_EVENT, (e) => {
       *   console.log(e);
       * });
       */
      [SCROLL_CHANGE_EVENT]: ScrollChangeEvent
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data property for infinity scroll
       * @deprecated Use `grid.infinityScroll` instead.
       *
       * @example
       * ```typescript
       * const grid = document.createElement('revo-grid');
       * grid.infinityScroll = {
       *   chunkSize: 50,
       *   bufferSize: 100,
       *   preloadThreshold: 0.75,
       *   total: 1000,
       *   loadData: async (skip, limit) => fetch(`/api/data?skip=${skip}&limit=${limit}`).then(response => response.json()),
       * };
       * ```
       */
      infinityScroll?: Partial<InfinityScrollConfig>
}
```

## Plugin API

### `InfinityScrollPlugin`

The InfinityScrollPlugin enables dynamic data loading as users scroll through the RevoGrid.
It efficiently manages data chunks, loading new data when needed and cleaning up unused data
to optimize memory usage.

**Key Features**:
- Dynamic data loading based on scroll position with buffer zones
- Pre-loads data ahead of scroll direction
- Efficient memory management by cleaning up off-screen data
- Configurable chunk size and buffer sizes
- Support for both known and unknown total data sizes
- Visual loading state for unloaded rows

Usage Example:
```typescript
import { InfinityScrollPlugin } from './infinity-scroll';

const grid = document.createElement('revo-grid');
grid.plugins = [InfinityScrollPlugin];

grid.infinityScroll = {
  chunkSize: 50,
  bufferSize: 100, // How many rows to keep in buffer
  preloadThreshold: 0.75, // When to start loading more data (0-1)
  total: 1000, // optional
  loadData: async (skip, limit, order, singleConditionFilters) => {
    // Fetch data from your server
    const response = await fetch(`/api/data?skip=${skip}&limit=${limit}&order=${JSON.stringify(order)}`);
    return response.json();
  }
};
```

#### Dependencies

- **Optional** `sorting-capable-plugin`: Integrates with a plugin exposing sorting state for remote infinite-scroll sorting.
- **Event integration** `beforefilterapply`, `beforequickfilterapply`, `beforesortingapply`: Integrates with filter and quick-filter events to forward remote filter state to loadData.

```ts
class InfinityScrollPlugin {
  destroy();
}
```

---

### `InfinityScrollLoadDataResult`

```ts
interface InfinityScrollLoadDataResult {
  data: T[];
  hasMore?: boolean;
  total?: number
}
```

---

### `InfinityScrollLoadData`

```ts
export type InfinityScrollLoadData<T = any> = (
  skip: number,
  limit: number,
  order?: { [key: ColumnProp]: 'asc' | 'desc' },
  singleConditionFilters?: Record<ColumnProp, FilterCollectionItem>,
  multiConditionFilters?: MultiFilterItem,
  quickFilter?: QuickFilter,
  temporalContext?: TemporalFilterContext,
  /** Canonical filter tree, including nested groups and custom structured operators. */
  filterAst?: FilterAst,
  /** Captured clock and timezone context used to evaluate the canonical tree. */
  executionContext?: FilterExecutionContext,
) => Promise<T[] | InfinityScrollLoadDataResult<T>>;
```

---

### `InfinityScrollConfig`

```ts
interface InfinityScrollConfig {
  /**
     * Number of items to load per chunk
     */
    chunkSize: number;
  /**
     * Number of rows to keep in buffer before and after visible area
     */
    bufferSize: number;
  /**
     * When to start loading more data (0-1)
     * ### Example 0.75 means start loading when 75% of the current chunk is visible
     */
    preloadThreshold: number;
  /**
     * Total number of items available (if known)
     * Optional - set to undefined for unknown total
     */
    total?: number;
  /**
     * Function to load data from server
     * @param skip - Number of items to skip
     * @param limit - Number of items to load
     * @param order - Current remote sorting state
     * @param singleConditionFilters - Filter collection with at most one condition per column
     * @param multiConditionFilters - Complete advanced filter model, including multiple conditions per column
     * @returns Promise with loaded data array
     * or object with explicit pagination state
     */
    loadData: InfinityScrollLoadData<T>
}
```

---

### `ResolvedInfinityScrollConfig` (Extended from `index.ts`)

```ts
interface ResolvedInfinityScrollConfig {
  dynamicChunkSize?: boolean
}
```

---

### `ScrollChangeEvent`

```ts
interface ScrollChangeEvent {
  /**
     * Number of items to skip
     */
    skip: number;
  /**
     * Number of items to load
     */
    limit: number
}
```

---

### `SCROLL_CHANGE_EVENT`

```ts
SCROLL_CHANGE_EVENT: string;
```

---

### `INFINITY_SCROLL_ROW_SOURCE_OWNER`

```ts
INFINITY_SCROLL_ROW_SOURCE_OWNER: string;
```

---

### `INFINITY_SCROLL_UNLOADED_ROW`

```ts
INFINITY_SCROLL_UNLOADED_ROW: typeof INFINITY_SCROLL_UNLOADED_ROW;
```

---

# Info Panel

URL: https://pro.rv-grid.com/api/info-panel/
Source: src/content/docs/api/info-panel.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  infoPanel?: InfoPanelConfig;
  'info-panel'?: InfoPanelConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Legacy info panel configuration.
       * @deprecated Use `grid.infoPanel` instead.
       */
      infoPanel?: InfoPanelConfig
}
```

## Plugin API

### `InfoPanelConfig`

```ts
interface InfoPanelConfig {
  keys?: string[]
}
```

---

### `InfoPanelPlugin`

The `InfoPanelPlugin` enhances RevoGrid by providing a dynamic and customizable
information panel that displays detailed data about the selected row. The panel
appears when a row is clicked and can be populated with specific fields, making it
highly useful for displaying additional information without cluttering the main grid.

 **Features**:
- Listens for row selection events (`afterfocus`) and dynamically displays detailed
  information based on the selected row.
- Supports customization of displayed fields through the `infoPanel.keys` property
  in RevoGrid’s `additionalData`.
- Emits a `beforeinfopanelshow` event, allowing users to intercept and prevent
  the panel from being shown if necessary.
- Supports both plain text and HTML content rendering within the panel.
- Smoothly toggles visibility of the panel using the `hidden` attribute.

**Usage**:
- Import `InfoPanelPlugin` and add it to the RevoGrid's plugin list.
- Optionally, define which keys should be displayed in the info panel by setting
  `additionalData.infoPanel.keys`.

### Example
```typescript
import { InfoPanelPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.additionalData = {
  infoPanel: { keys: ['name', 'age', 'email'] } // Specify keys to display
};
grid.plugins = [InfoPanelPlugin]; // Add info panel functionality to the grid
```

This plugin is ideal for enhancing user interaction by providing a non-intrusive
way to display detailed information about grid entries, commonly used in data
visualization, management dashboards, and administrative tools.

#### Dependencies

- **Event integration** `afterfocus`: Integrates with row focus events to show selected row details.
- **Config integration** `additionalData.infoPanel`: Reads legacy panel configuration from additionalData.infoPanel.

```ts
class InfoPanelPlugin {}
```

---

# Kanban

URL: https://pro.rv-grid.com/api/kanban/
Source: src/content/docs/api/kanban.md

## Module Extensions

### `KanbanContextMenuConfig`

```ts
interface KanbanContextMenuConfig {
  /** Compose application-provided row context-menu items after Kanban actions. */
    readonly includeHostItems?: boolean;
  /** Hide built-ins globally or per invoked card/batch while preserving the rest. */
    readonly hidden?: Partial<Record<KanbanContextMenuItemId, KanbanContextMenuItemVisibility<T>>>
}
```

---

### `ResolveKanbanCardRuleOptions`

```ts
interface ResolveKanbanCardRuleOptions {
  readonly config: KanbanConfig<T> | ResolvedKanbanConfig<T>;
  readonly projectedCard: KanbanProjectedCard<T>;
  readonly column: KanbanColumnDefinition<T>;
  readonly swimlane: KanbanSwimlaneDefinition;
  readonly selected?: boolean;
  readonly dragging?: boolean;
  /** Internal validation can evaluate visual card rules separately from global callbacks. */
    readonly includeGlobalPermissions?: boolean
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [BEFORE_KANBAN_CARD_MOVE_EVENT]: KanbanBeforeCardMoveDetail;
  [KANBAN_CARD_MOVE_EVENT]: KanbanCardMoveDetail;
  [KANBAN_SELECTION_CHANGE_EVENT]: KanbanSelectionChangeDetail;
  [KANBAN_COLUMN_ORDER_CHANGE_EVENT]: KanbanColumnOrderChangeDetail;
  [KANBAN_DROP_STATE_CHANGE_EVENT]: KanbanDropStateChangeDetail;
  [KANBAN_DIAGNOSTICS_EVENT]: KanbanDiagnosticsDetail;
  [KANBAN_CARD_CREATE_REQUEST_EVENT]: KanbanCardRequestDetail;
  [KANBAN_CARD_OPEN_REQUEST_EVENT]: KanbanCardRequestDetail;
  [KANBAN_CARD_EDIT_REQUEST_EVENT]: KanbanCardRequestDetail;
  [KANBAN_CARD_DELETE_REQUEST_EVENT]: KanbanCardRequestDetail;
  [BEFORE_KANBAN_CARD_CREATE_EVENT]: KanbanCardCreateDetail;
  [KANBAN_CARD_CREATE_EVENT]: KanbanCardCreateDetail;
  [BEFORE_KANBAN_CARD_UPDATE_EVENT]: KanbanCardUpdateDetail;
  [KANBAN_CARD_UPDATE_EVENT]: KanbanCardUpdateDetail;
  [BEFORE_KANBAN_CARD_DELETE_EVENT]: KanbanCardDeleteDetail;
  [KANBAN_CARD_DELETE_EVENT]: KanbanCardDeleteDetail
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /** @deprecated Prefer the direct `grid.kanban` property. */
      kanban?: KanbanConfig | false
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  kanban?: KanbanConfig | false
}
```

## Plugin API

### `KanbanPlugin`

Kanban presentation for a canonical RevoGrid row source.

#### Dependencies

- **Auto-installed** `EventManagerPlugin`, `HistoryPlugin`: Installs shared edit and history services for atomic Kanban moves.
- **Auto-installed** `ContextMenuPlugin`: Uses the shared Pro context-menu surface for card actions.
- **Auto-installed** `KanbanCardEditorDialogPlugin`: Provides the packaged card editor by default while preserving the explicit false opt-out.
- **Auto-installed** `FilterPlugin`, `ColumnMovePlugin`: Uses core filtering for cards and core column movement for workflow columns.

```ts
class KanbanPlugin {
  getCards(): readonly T[];

  getProjection(): KanbanProjection<T> | null;

  getConfig(): ResolvedKanbanConfig<T> | null;

  createCard(card: T, options: KanbanCreateOptions = {}): KanbanMutationResult<T>;

  updateCard(cardId: KanbanCardId, patch: Partial<T>, options: KanbanUpdateOptions = {}): KanbanMutationResult<T>;

  deleteCards(cardIds: readonly KanbanCardId[], options: KanbanDeleteOptions = {}): KanbanMutationResult<T>;

  getSelectedCardIds(): readonly KanbanCardId[];

  setSelectedCardIds(cardIds: readonly KanbanCardId[]): void;

  revealCard(cardId: KanbanCardId): Promise<boolean>;

  getColumnOrder(): readonly KanbanColumnProp[];

  setColumnOrder(columnProps: readonly KanbanColumnProp[]): void;

  getCollapsedColumnProps(): readonly KanbanColumnProp[];

  setColumnCollapsed(columnProp: KanbanColumnProp, collapsed: boolean): void;

  getSwimlaneColumnCollapsed(): boolean;

  setSwimlaneColumnCollapsed(collapsed: boolean): void;

  getDiagnostics(): readonly KanbanDiagnostic<T>[];

  refresh(): void;

  moveCards(
    cardIds: readonly KanbanCardId[],
    target: KanbanMoveTarget,
    options: KanbanMoveOptions = {},
  ): boolean;

  requestCreateCard(detail: KanbanCardRequestDetail<T> = {}): void;

  requestOpenCard(cardId: KanbanCardId): void;

  requestEditCard(cardId: KanbanCardId): void;

  requestDeleteCards(cardIds: readonly KanbanCardId[]): void;
}
```

---

### `BEFORE_KANBAN_CARD_MOVE_EVENT`

```ts
BEFORE_KANBAN_CARD_MOVE_EVENT: string;
```

---

### `KANBAN_CARD_MOVE_EVENT`

```ts
KANBAN_CARD_MOVE_EVENT: string;
```

---

### `KANBAN_SELECTION_CHANGE_EVENT`

```ts
KANBAN_SELECTION_CHANGE_EVENT: string;
```

---

### `KANBAN_COLUMN_ORDER_CHANGE_EVENT`

```ts
KANBAN_COLUMN_ORDER_CHANGE_EVENT: string;
```

---

### `KANBAN_DROP_STATE_CHANGE_EVENT`

```ts
KANBAN_DROP_STATE_CHANGE_EVENT: string;
```

---

### `KANBAN_DIAGNOSTICS_EVENT`

```ts
KANBAN_DIAGNOSTICS_EVENT: string;
```

---

### `KANBAN_CARD_CREATE_REQUEST_EVENT`

```ts
KANBAN_CARD_CREATE_REQUEST_EVENT: string;
```

---

### `KANBAN_CARD_OPEN_REQUEST_EVENT`

```ts
KANBAN_CARD_OPEN_REQUEST_EVENT: string;
```

---

### `KANBAN_CARD_EDIT_REQUEST_EVENT`

```ts
KANBAN_CARD_EDIT_REQUEST_EVENT: string;
```

---

### `KANBAN_CARD_DELETE_REQUEST_EVENT`

```ts
KANBAN_CARD_DELETE_REQUEST_EVENT: string;
```

---

### `BEFORE_KANBAN_CARD_CREATE_EVENT`

```ts
BEFORE_KANBAN_CARD_CREATE_EVENT: string;
```

---

### `KANBAN_CARD_CREATE_EVENT`

```ts
KANBAN_CARD_CREATE_EVENT: string;
```

---

### `BEFORE_KANBAN_CARD_UPDATE_EVENT`

```ts
BEFORE_KANBAN_CARD_UPDATE_EVENT: string;
```

---

### `KANBAN_CARD_UPDATE_EVENT`

```ts
KANBAN_CARD_UPDATE_EVENT: string;
```

---

### `BEFORE_KANBAN_CARD_DELETE_EVENT`

```ts
BEFORE_KANBAN_CARD_DELETE_EVENT: string;
```

---

### `KANBAN_CARD_DELETE_EVENT`

```ts
KANBAN_CARD_DELETE_EVENT: string;
```

---

### `resolveKanbanLabels`

```ts
export function resolveKanbanLabels(labels?: Partial<KanbanLabels>): KanbanLabels;
```

---

### `DEFAULT_KANBAN_LABELS`

```ts
DEFAULT_KANBAN_LABELS: {
  unmappedColumn: string;
  implicitSwimlane: string;
  emptyColumn: string;
  dropCardHere: string;
  progress: string;
  schedule: string;
  assignees: string;
  cardCount: (visible: number, total: number) => string;
  wipLimit: (count: number, limit: number) => string;
  selectedCards: (count: number) => string;
  pickedUpCards: (count: number) => string;
  moveTarget: (column: string, swimlane: string, position: number) => string;
  moveCompleted: (count: number, column: string, swimlane: string) => string;
  moveCancelled: string;
  currentPosition: string;
  noDropTarget: string;
  moveBlocked: (reason: string) => string;
  noCardsSelected: string;
  boardReadOnly: string;
  invalidCardIdentity: string;
  cardCannotMove: string;
  transitionNotAllowed: string;
  dropRejected: string;
  wipExceeded: (limit: number, excess: number) => string;
  moveTargetMissing: string;
  selectedCardsMissing: string;
  invalidMove: string;
  projectionFailed: string;
  stackLabel: (column: string, swimlane: string) => string;
  readonlyCard: string;
  invalidCard: string;
  openCard: string;
  editCard: string;
  moveCard: string;
  moveCards: (count: number) => string;
  moveToColumn: string;
  moveToSwimlane: string;
  addCardHere: string;
  deleteCard: string;
  deleteCards: (count: number) => string;
  cardContextMenu: string;
  dragHandle: string;
  collapseColumn: string;
  expandColumn: string;
  collapseSwimlane: string;
  expandSwimlane: string;
  collapseSwimlaneColumn: string;
  expandSwimlaneColumn: string;
};
```

---

### `resolveKanbanHistoryConfig`

```ts
export function resolveKanbanHistoryConfig(history?: HistoryConfig): HistoryConfig;
```

---

### `isKanbanHistoryConfig`

```ts
export function isKanbanHistoryConfig(history?: HistoryConfig): boolean;
```

---

### `KANBAN_HISTORY_RECORD_EVENT`

```ts
KANBAN_HISTORY_RECORD_EVENT: string;
```

---

### `KanbanHistoryTool`

```ts
class KanbanHistoryTool {
  isHistoryRecord(detail: EventManagerEvent): boolean;

  collectMutation(
    previousCards: readonly T[],
    nextCards: readonly T[],
    hint?: KanbanMutationCollectionHint,
  ): boolean;

  replayPatch(detail: HistoryReplayDetail): boolean;
}
```

---

### `KanbanLabels`

```ts
interface KanbanLabels {
  readonly unmappedColumn: string;
  readonly implicitSwimlane: string;
  readonly emptyColumn: string;
  readonly dropCardHere: string;
  readonly progress: string;
  readonly schedule: string;
  readonly assignees: string;
  readonly cardCount: (visible: number, total: number) => string;
  readonly wipLimit: (count: number, limit: number) => string;
  readonly selectedCards: (count: number) => string;
  readonly pickedUpCards: (count: number) => string;
  readonly moveTarget: (column: string, swimlane: string, position: number) => string;
  readonly moveCompleted: (count: number, column: string, swimlane: string) => string;
  readonly moveCancelled: string;
  readonly currentPosition: string;
  readonly noDropTarget: string;
  readonly moveBlocked: (reason: string) => string;
  readonly noCardsSelected: string;
  readonly boardReadOnly: string;
  readonly invalidCardIdentity: string;
  readonly cardCannotMove: string;
  readonly transitionNotAllowed: string;
  readonly dropRejected: string;
  readonly wipExceeded: (limit: number, excess: number) => string;
  readonly moveTargetMissing: string;
  readonly selectedCardsMissing: string;
  readonly invalidMove: string;
  readonly projectionFailed: string;
  readonly stackLabel: (column: string, swimlane: string) => string;
  readonly readonlyCard: string;
  readonly invalidCard: string;
  readonly openCard: string;
  readonly editCard: string;
  readonly moveCard: string;
  readonly moveCards: (count: number) => string;
  readonly moveToColumn: string;
  readonly moveToSwimlane: string;
  readonly addCardHere: string;
  readonly deleteCard: string;
  readonly deleteCards: (count: number) => string;
  readonly cardContextMenu: string;
  /** @deprecated Cards use the whole managed shell as their drag surface. */
    readonly dragHandle: string;
  readonly collapseColumn: string;
  readonly expandColumn: string;
  readonly collapseSwimlane: string;
  readonly expandSwimlane: string;
  readonly collapseSwimlaneColumn: string;
  readonly expandSwimlaneColumn: string
}
```

---

### `KanbanCardRuleResult`

```ts
interface KanbanCardRuleResult {
  readonly className?: string;
  readonly style?: Readonly<Record<string, string | number>>;
  readonly badges?: readonly KanbanBadge[];
  readonly draggable?: boolean;
  readonly selectable?: boolean;
  readonly editable?: boolean
}
```

---

### `KanbanCardRule`

```ts
interface KanbanCardRule {
  readonly id: string;
  readonly when: (context: KanbanCardRenderContext<T>) => boolean;
  readonly result: KanbanCardRuleResult
}
```

---

### `KanbanDropRuleContext`

```ts
interface KanbanDropRuleContext {
  readonly cards: readonly T[];
  readonly sourceColumnProps: readonly KanbanColumnProp[];
  readonly targetColumn: KanbanColumnDefinition<T>;
  readonly targetSwimlane: KanbanSwimlaneDefinition
}
```

---

### `KanbanRules`

```ts
interface KanbanRules {
  readonly canDrag?: (card: T) => boolean | string;
  readonly canSelect?: (card: T) => boolean;
  readonly canEdit?: (card: T) => boolean;
  readonly canDrop?: (context: KanbanDropRuleContext<T>) => boolean | string
}
```

---

### `KanbanCardConfig`

```ts
interface KanbanCardConfig {
  readonly titleField?: ColumnProp;
  readonly descriptionField?: ColumnProp;
  readonly title?: (card: T) => string;
  readonly description?: (card: T) => string | undefined;
  readonly progressField?: ColumnProp;
  readonly progress?: (card: T) => number | null | undefined;
  readonly startDateField?: ColumnProp;
  readonly endDateField?: ColumnProp;
  readonly dateRange?: (card: T) => { readonly start: unknown; readonly end: unknown } | null | undefined;
  readonly dateTimeZone?: string;
  readonly assigneeField?: ColumnProp;
  readonly assigneeAvatarField?: ColumnProp;
  readonly assignees?: (card: T) => readonly KanbanCardAssignee[];
  readonly priorityField?: ColumnProp;
  readonly priority?: (card: T) => string | null | undefined;
  readonly tagsField?: ColumnProp;
  readonly tags?: (card: T) => readonly string[] | null | undefined;
  readonly dueDateField?: ColumnProp;
  readonly dueDate?: (card: T) => unknown;
  readonly colorField?: ColumnProp;
  readonly color?: (card: T) => string | null | undefined
}
```

---

### `KanbanFilterConfig`

```ts
interface KanbanFilterConfig {
  readonly query?: string;
  readonly fields?: readonly ColumnProp[];
  readonly predicate?: (card: T) => boolean
}
```

---

### `KanbanSelectionConfig`

```ts
interface KanbanSelectionConfig {
  readonly mode?: 'single' | 'multiple';
  readonly selectedIds?: readonly (string | number)[]
}
```

---

### `KanbanSwimlaneColumnConfig`

```ts
interface KanbanSwimlaneColumnConfig {
  readonly title?: string;
  readonly width?: number;
  readonly collapsedWidth?: number;
  readonly collapsible?: boolean;
  readonly collapsed?: boolean
}
```

---

### `KanbanSwimlaneLayout`

Placement of explicit swimlane identity and collapse controls.

```ts
/** Placement of explicit swimlane identity and collapse controls. */
export type KanbanSwimlaneLayout = 'column' | 'top';
```

---

### `KanbanContextMenuItemId`

```ts
export type KanbanContextMenuItemId =
  /** @deprecated Open is no longer rendered separately from Edit. */
  | 'open'
  | 'edit'
  | 'move'
  | 'create'
  | 'delete';
```

---

### `KanbanContextMenuItemContext`

```ts
interface KanbanContextMenuItemContext {
  /** Primary card whose shell opened the menu. */
    readonly card: T;
  /** Full invoked selection, or only the primary card when it was not selected. */
    readonly cardIds: readonly KanbanCardId[];
  readonly column: KanbanColumnDefinition<T>;
  readonly swimlane: KanbanSwimlaneDefinition
}
```

---

### `KanbanContextMenuItemVisibility`

```ts
export type KanbanContextMenuItemVisibility<T extends DataType = DataType> =
  | boolean
  | ((context: KanbanContextMenuItemContext<T>) => boolean);
```

---

### `KanbanConfig`

```ts
interface KanbanConfig {
  readonly columns?: readonly KanbanColumnDefinition<T>[];
  /** Shared source-property vocabulary used by Scheduler, Gantt, and Kanban. */
  readonly fields?: ViewFieldMap;
  readonly idField?: ColumnProp;
  readonly columnField?: ColumnProp;
  readonly orderField?: ColumnProp;
  readonly swimlaneField?: ColumnProp;
  readonly swimlanes?: readonly KanbanSwimlaneDefinition[];
  /** Render swimlane identity in a row-header column or above each lane. @default 'column' */
    readonly swimlaneLayout?: KanbanSwimlaneLayout;
  /** Swimlane row-header presentation. Set to `false` to hide it. */
    readonly swimlaneColumn?: KanbanSwimlaneColumnConfig | false;
  /** Built-in card context menu. Enabled by default. */
    readonly contextMenu?: KanbanContextMenuConfig<T> | false;
  readonly readOnly?: boolean;
  readonly wipBehavior?: 'warn' | 'block';
  readonly rules?: KanbanRules<T>;
  readonly cardRules?: readonly KanbanCardRule<T>[];
  readonly selection?: KanbanSelectionConfig;
  readonly card?: KanbanCardConfig<T>;
  readonly customization?: KanbanCustomization<T>;
  readonly filter?: KanbanFilterConfig<T>;
  readonly labels?: Partial<KanbanLabels>;
  readonly locale?: string;
  /** Uniform projected row height reserved for each card. */
    readonly cardRowHeight?: number;
  /** @deprecated Use `cardRowHeight`. Retained as a compatibility alias. */
    readonly laneHeight?: number;
  readonly collapsedLaneHeight?: number;
  readonly cardGap?: number;
  readonly unmappedColumn?: boolean
}
```

---

### `ResolvedKanbanConfig` (Extended from `index.ts`)

```ts
interface ResolvedKanbanConfig {
  readonly columns: readonly KanbanColumnDefinition<T>[];
  readonly idField: ColumnProp;
  readonly columnField: ColumnProp;
  readonly orderField: ColumnProp;
  readonly wipBehavior: 'warn' | 'block';
  readonly selection: Required<KanbanSelectionConfig>;
  readonly card: Required<Pick<KanbanCardConfig<T>, 'titleField'>> & KanbanCardConfig<T>;
  readonly locale: string;
  readonly cardRowHeight: number;
  readonly laneHeight: number;
  readonly collapsedLaneHeight: number;
  readonly swimlaneLayout: KanbanSwimlaneLayout;
  readonly swimlaneColumn: Required<KanbanSwimlaneColumnConfig> & { readonly enabled: boolean };
  readonly contextMenu: false | Required<Pick<KanbanContextMenuConfig<T>, 'includeHostItems'>> & KanbanContextMenuConfig<T>;
  readonly cardGap: number;
  readonly unmappedColumn: boolean
}
```

---

### `KanbanCardMoveDetail`

```ts
interface KanbanCardMoveDetail {
  readonly cardIds: readonly KanbanCardId[];
  readonly cards: readonly T[];
  /** Every canonical card changed by the move, including rank rebalances. */
    readonly changedCards: readonly T[];
  readonly previousCards: readonly T[];
  readonly previousLocations: readonly KanbanCardLocation[];
  readonly currentLocations: readonly KanbanCardLocation[];
  readonly target: KanbanMoveTarget;
  readonly reason: 'pointer' | 'keyboard' | 'api' | 'history';
  readonly rebalancedCardIds: readonly KanbanCardId[]
}
```

---

### `KanbanBeforeCardMoveDetail` (Extended from `index.ts`)

```ts
interface KanbanBeforeCardMoveDetail {
  readonly proposedCards: readonly T[]
}
```

---

### `KanbanSelectionChangeDetail`

```ts
interface KanbanSelectionChangeDetail {
  readonly cardIds: readonly KanbanCardId[];
  readonly cards: readonly T[];
  readonly mode: 'replace' | 'toggle' | 'range' | 'clear' | 'api'
}
```

---

### `KanbanColumnOrderChangeDetail`

```ts
interface KanbanColumnOrderChangeDetail {
  readonly columnProps: readonly KanbanColumnProp[];
  readonly reason: 'drag' | 'api'
}
```

---

### `KanbanDropStateChangeDetail`

```ts
interface KanbanDropStateChangeDetail {
  readonly cardIds: readonly KanbanCardId[];
  readonly target?: KanbanMoveTarget;
  readonly valid: boolean;
  /** Distinguishes actionable, blocked, and order-preserving pointer targets. */
    readonly state?: 'valid' | 'invalid' | 'noop';
  readonly reason?: string
}
```

---

### `KanbanDiagnosticsDetail`

```ts
interface KanbanDiagnosticsDetail {
  readonly diagnostics: readonly KanbanDiagnostic<T>[]
}
```

---

### `KanbanCardRequestDetail`

```ts
interface KanbanCardRequestDetail {
  readonly cardId?: KanbanCardId;
  readonly card?: T;
  readonly cardIds?: readonly KanbanCardId[];
  readonly cards?: readonly T[];
  readonly columnProp?: KanbanColumnProp;
  readonly swimlaneId?: KanbanSwimlaneId
}
```

---

### `KanbanMutationReason`

```ts
export type KanbanMutationReason = 'api' | 'editor' | 'history';
```

---

### `KanbanCardCreateDetail`

```ts
interface KanbanCardCreateDetail {
  readonly card: T;
  readonly cardId: KanbanCardId;
  readonly sourceIndex: number;
  readonly reason: KanbanMutationReason
}
```

---

### `KanbanCardUpdateDetail`

```ts
interface KanbanCardUpdateDetail {
  readonly card: T;
  readonly previousCard: T;
  readonly cardId: KanbanCardId;
  readonly sourceIndex: number;
  readonly reason: KanbanMutationReason
}
```

---

### `KanbanCardDeleteDetail`

```ts
interface KanbanCardDeleteDetail {
  readonly cards: readonly T[];
  readonly cardIds: readonly KanbanCardId[];
  readonly sourceIndexes: readonly number[];
  readonly reason: KanbanMutationReason
}
```

---

### `KanbanMutationResult`

```ts
export type KanbanMutationResult<T extends DataType = DataType> =
  | { readonly ok: true; readonly cards: readonly T[]; readonly cardIds: readonly KanbanCardId[] }
  | { readonly ok: false; readonly reason: string; readonly code: 'inactive' | 'readonly' | 'invalid' | 'duplicate' | 'missing' | 'rule' | 'cancelled' };
```

---

### `KanbanCardId`

```ts
export type KanbanCardId = string | number;
```

---

### `KanbanColumnProp`

```ts
export type KanbanColumnProp = ColumnProp;
```

---

### `KanbanSwimlaneId`

```ts
export type KanbanSwimlaneId = string | number;
```

---

### `KanbanCardLocation`

```ts
interface KanbanCardLocation {
  readonly columnProp: KanbanColumnProp;
  readonly swimlaneId: KanbanSwimlaneId;
  readonly index: number;
  readonly rank: number
}
```

---

### `KanbanColumnDefinition`

```ts
interface KanbanColumnDefinition {
  readonly prop: KanbanColumnProp;
  readonly name?: string;
  readonly size?: number;
  readonly minSize?: number;
  readonly maxSize?: number;
  readonly columnTemplate?: KanbanColumnTemplate<T>;
  readonly columnProperties?: KanbanColumnProperties<T>;
  readonly wipLimit?: number;
  readonly collapsed?: boolean;
  readonly collapsible?: boolean;
  readonly allowedFrom?: readonly KanbanColumnProp[];
  readonly metadata?: Readonly<Record<string, unknown>>;
  readonly cardFilter?: (card: T) => boolean
}
```

---

### `KanbanColumnHeaderRenderContext`

```ts
interface KanbanColumnHeaderRenderContext {
  readonly column: KanbanColumnDefinition<T>;
  readonly visibleCount: number;
  readonly totalCount: number;
  readonly overWipLimit: boolean;
  readonly toggleCollapsed: () => void
}
```

---

### `KanbanColumnTemplateProp` (Extended from `index.ts`)

```ts
interface KanbanColumnTemplateProp {
  readonly kanban: KanbanColumnHeaderRenderContext<T>
}
```

---

### `KanbanColumnTemplate`

```ts
export type KanbanColumnTemplate<T extends DataType = DataType> = (
  createElement: HyperFunc<VNode>,
  props: KanbanColumnTemplateProp<T>,
  additionalData?: any,
) => any;
```

---

### `KanbanColumnProperties`

```ts
export type KanbanColumnProperties<T extends DataType = DataType> = (
  props: KanbanColumnTemplateProp<T>,
) => CellProps | void | undefined;
```

---

### `KanbanSwimlaneTemplate`

```ts
export type KanbanSwimlaneTemplate = (
  createElement: HyperFunc<VNode>,
  context: KanbanSwimlaneHeaderRenderContext,
) => any;
```

---

### `KanbanSwimlaneDefinition`

```ts
interface KanbanSwimlaneDefinition {
  readonly id: KanbanSwimlaneId;
  readonly title: string;
  /** Fully replaces the managed title, count, and collapse control for this lane. */
  readonly swimlaneTemplate?: KanbanSwimlaneTemplate;
  readonly height?: number;
  readonly collapsed?: boolean;
  readonly collapsible?: boolean;
  readonly wipLimits?: Readonly<Record<string, number>>;
  readonly className?: string;
  readonly style?: Readonly<Record<string, string | number>>;
  readonly metadata?: Readonly<Record<string, unknown>>
}
```

---

### `KanbanDiagnosticCode`

```ts
export type KanbanDiagnosticCode =
  | 'duplicate-column-prop'
  | 'missing-card-id'
  | 'duplicate-card-id'
  | 'invalid-rank'
  | 'unknown-column'
  | 'unknown-swimlane';
```

---

### `KanbanDiagnostic`

```ts
interface KanbanDiagnostic {
  readonly code: KanbanDiagnosticCode;
  readonly message: string;
  readonly card?: T;
  readonly cardIndex?: number;
  readonly value?: unknown;
  readonly blocking: boolean
}
```

---

### `KanbanProjectedCard`

```ts
interface KanbanProjectedCard {
  readonly id: KanbanCardId;
  readonly card: T;
  readonly sourceIndex: number;
  readonly location: KanbanCardLocation;
  readonly mutable: boolean
}
```

---

### `KanbanGridRow` (Extended from `index.ts`)

```ts
interface KanbanGridRow {
  readonly __kanbanRow: true;
  readonly __kanbanLaneId: KanbanSwimlaneId;
  readonly __kanbanLaneTitle: string;
  readonly __kanbanLaneCollapsed: boolean;
  /** Dedicated lane identity row rendered across the workflow viewport. */
    readonly __kanbanLaneHeaderRow: boolean;
  readonly __kanbanLaneRowIndex: number;
  readonly __kanbanLaneRowCount: number;
  readonly __kanbanDropRow: boolean;
  readonly __kanbanCardsByColumn: Readonly<Record<string, readonly KanbanProjectedCard<T>[]>>
}
```

---

### `KanbanProjection`

```ts
interface KanbanProjection {
  readonly cards: readonly KanbanProjectedCard<T>[];
  readonly rows: readonly KanbanGridRow<T>[];
  readonly columns: readonly KanbanColumnDefinition<T>[];
  readonly swimlanes: readonly KanbanSwimlaneDefinition[];
  readonly diagnostics: readonly KanbanDiagnostic<T>[];
  readonly visibleCardIds: ReadonlySet<KanbanCardId>;
  readonly cardById: ReadonlyMap<KanbanCardId, KanbanProjectedCard<T>>;
  readonly totalCounts: ReadonlyMap<string, number>;
  readonly visibleCounts: ReadonlyMap<string, number>
}
```

---

### `KanbanMoveTarget`

```ts
interface KanbanMoveTarget {
  readonly columnProp: KanbanColumnProp;
  readonly swimlaneId?: KanbanSwimlaneId;
  /** Full-bucket insertion index. Omit to append. */
    readonly index?: number;
  /** Visible card before which the batch should be inserted. */
    readonly beforeCardId?: KanbanCardId
}
```

---

### `KanbanMoveOptions`

```ts
interface KanbanMoveOptions {
  readonly reason?: 'pointer' | 'keyboard' | 'api' | 'history';
  readonly skipHistory?: boolean
}
```

---

### `KanbanCreateOptions`

```ts
interface KanbanCreateOptions {
  readonly columnProp?: KanbanColumnProp;
  readonly swimlaneId?: KanbanSwimlaneId;
  readonly sourceIndex?: number;
  readonly reason?: 'api' | 'editor' | 'history';
  readonly skipHistory?: boolean
}
```

---

### `KanbanUpdateOptions`

```ts
interface KanbanUpdateOptions {
  readonly reason?: 'api' | 'editor' | 'history';
  readonly skipHistory?: boolean
}
```

---

### `KanbanDeleteOptions` (Extended from `index.ts`)

```ts
interface KanbanDeleteOptions {

}
```

---

### `KanbanField`

```ts
export type KanbanField = ColumnProp;
```

---

### `KanbanTemplateResult`

```ts
export type KanbanTemplateResult = VNode | string | number | null | undefined;
```

---

### `KanbanTemplateH`

```ts
export type KanbanTemplateH = (
  tag: string,
  props?: Record<string, unknown>,
  children?: unknown,
) => VNode;
```

---

### `KanbanBadge`

```ts
interface KanbanBadge {
  readonly label: string;
  readonly className?: string;
  readonly title?: string
}
```

---

### `KanbanCardAssignee`

```ts
interface KanbanCardAssignee {
  readonly id?: string | number;
  readonly label: string;
  readonly avatar?: unknown
}
```

---

### `KanbanProgressRenderOptions`

```ts
interface KanbanProgressRenderOptions {
  readonly value: number;
  readonly label: string;
  readonly className?: string;
  readonly showValue?: boolean
}
```

---

### `KanbanAssigneesRenderOptions`

```ts
interface KanbanAssigneesRenderOptions {
  readonly assignees: readonly KanbanCardAssignee[];
  readonly label: string;
  readonly className?: string;
  readonly maxVisible?: number;
  readonly avatarSize?: number
}
```

---

### `KanbanDateRangeRenderOptions`

```ts
interface KanbanDateRangeRenderOptions {
  readonly start: unknown;
  readonly end: unknown;
  readonly label: string;
  readonly locale?: string;
  readonly timeZone?: string;
  readonly className?: string
}
```

---

### `KanbanCardRenderContext`

```ts
interface KanbanCardRenderContext {
  readonly projectedCard: KanbanProjectedCard<T>;
  readonly card: T;
  readonly column: KanbanColumnDefinition<T>;
  readonly swimlane: KanbanSwimlaneDefinition;
  readonly selected: boolean;
  readonly dragging: boolean;
  readonly readonly: boolean;
  readonly badges: readonly KanbanBadge[]
}
```

---

### `KanbanSwimlaneHeaderRenderContext`

```ts
interface KanbanSwimlaneHeaderRenderContext {
  readonly swimlane: KanbanSwimlaneDefinition;
  readonly visibleCount: number;
  readonly totalCount: number;
  readonly swimlaneColumnCollapsed: boolean;
  readonly toggleCollapsed: () => void
}
```

---

### `KanbanSwimlaneColumnHeaderRenderContext`

```ts
interface KanbanSwimlaneColumnHeaderRenderContext {
  readonly collapsed: boolean
}
```

---

### `KanbanCustomization`

```ts
interface KanbanCustomization {
  readonly cardContent?: (h: KanbanTemplateH, context: KanbanCardRenderContext<T>) => KanbanTemplateResult;
  readonly cardProps?: (context: KanbanCardRenderContext<T>) => Record<string, unknown> | undefined;
  readonly dragPreview?: (h: KanbanTemplateH, context: KanbanCardRenderContext<T>) => KanbanTemplateResult;
  readonly swimlaneHeader?: (h: KanbanTemplateH, context: KanbanSwimlaneHeaderRenderContext) => KanbanTemplateResult;
  readonly swimlaneColumnHeader?: (h: KanbanTemplateH, context: KanbanSwimlaneColumnHeaderRenderContext) => KanbanTemplateResult;
  readonly emptyState?: (h: KanbanTemplateH, context: { column: KanbanColumnDefinition<T>; swimlane: KanbanSwimlaneDefinition }) => KanbanTemplateResult
}
```

---

### `cardMatchesKanbanFilter`

```ts
export function cardMatchesKanbanFilter<T extends DataType>(
  card: T,
  config: Pick<ResolvedKanbanConfig<T>, 'card' | 'filter' | 'locale'>,
): boolean;
```

---

### `filterKanbanCards`

```ts
export function filterKanbanCards<T extends DataType>(
  cards: readonly T[],
  config: Pick<ResolvedKanbanConfig<T>, 'card' | 'filter' | 'locale'>,
  externalPredicate?: (card: T, sourceIndex: number) => boolean,
): readonly T[];
```

---

### `withKanbanQuery`

```ts
export function withKanbanQuery<T extends DataType>(
  filter: KanbanFilterConfig<T> | undefined,
  query: string,
): KanbanFilterConfig<T>;
```

---

### `kanbanIdKey`

Keeps numeric and string identifiers distinct in maps and serialized row fields.

```ts
export function kanbanIdKey(id: KanbanIdentity): string;
```

---

### `kanbanBucketKey`

```ts
export function kanbanBucketKey(columnProp: KanbanColumnProp, swimlaneId: KanbanSwimlaneId): string;
```

---

### `resolveKanbanColumnName`

```ts
export function resolveKanbanColumnName<T extends DataType>(column: KanbanColumnDefinition<T>): string;
```

---

### `readKanbanField`

```ts
export function readKanbanField<T extends DataType>(card: T, field: ColumnProp): unknown;
```

---

### `writeKanbanFields`

```ts
export function writeKanbanFields<T extends DataType>(
  card: T,
  patch: ReadonlyMap<ColumnProp, unknown>,
): T;
```

---

### `isKanbanId`

```ts
export function isKanbanId(value: unknown): value is KanbanIdentity;
```

---

### `KanbanIdentity`

```ts
export type KanbanIdentity = KanbanCardId | KanbanColumnProp | KanbanSwimlaneId;
```

---

### `isKanbanMoveNoop`

Returns true when a proposed drop preserves the complete destination order.

```ts
export function isKanbanMoveNoop<T extends DataType>(
  options: IsKanbanMoveNoopOptions<T>,
): boolean;
```

---

### `moveKanbanCards`

Produces one immutable, all-or-nothing canonical card move.

```ts
export function moveKanbanCards<T extends DataType>(
  options: MoveKanbanCardsOptions<T>,
): KanbanMoveMutationResult<T>;
```

---

### `getKanbanMoveBucketKey`

```ts
export function getKanbanMoveBucketKey(target: KanbanMoveTarget): string;
```

---

### `MoveKanbanCardsOptions`

```ts
interface MoveKanbanCardsOptions {
  readonly cards: readonly T[];
  readonly projection: KanbanProjection<T>;
  readonly config: KanbanConfig<T> | ResolvedKanbanConfig<T>;
  readonly cardIds: readonly KanbanCardId[];
  readonly target: KanbanMoveTarget
}
```

---

### `KanbanMoveMutationSuccess`

```ts
interface KanbanMoveMutationSuccess {
  readonly ok: true;
  readonly cards: readonly T[];
  readonly movedCardIds: readonly KanbanCardId[];
  readonly movedCards: readonly T[];
  readonly previousCards: readonly T[];
  readonly previousLocations: readonly KanbanCardLocation[];
  readonly currentLocations: readonly KanbanCardLocation[];
  readonly changedCards: readonly T[];
  readonly rebalancedCardIds: readonly KanbanCardId[];
  readonly validation: KanbanDropValidation;
  readonly projection: KanbanProjection<T>
}
```

---

### `KanbanMoveMutationFailure`

```ts
interface KanbanMoveMutationFailure {
  readonly ok: false;
  readonly cards: readonly T[];
  readonly reason: string;
  readonly validation?: KanbanDropValidation
}
```

---

### `KanbanMoveMutationResult`

```ts
export type KanbanMoveMutationResult<T extends DataType = DataType> =
  | KanbanMoveMutationSuccess<T>
  | KanbanMoveMutationFailure<T>;
```

---

### `IsKanbanMoveNoopOptions`

```ts
export type IsKanbanMoveNoopOptions<T extends DataType = DataType> = Pick<
  MoveKanbanCardsOptions<T>,
  'projection' | 'cardIds' | 'target'
>;
```

---

### `resolveKanbanConfig`

```ts
export function resolveKanbanConfig<T extends DataType>(config: KanbanConfig<T>): ResolvedKanbanConfig<T>;
```

---

### `normalizeKanbanBoard`

```ts
export function normalizeKanbanBoard<T extends DataType>(
  cards: readonly T[],
  config: KanbanConfig<T>,
): NormalizedKanbanBoard<T>;
```

---

### `orderKanbanColumns`

Orders known workflow columns by runtime preference and appends omitted columns stably.

```ts
export function orderKanbanColumns<T extends DataType>(
  columns: readonly KanbanColumnDefinition<T>[],
  columnOrder: readonly KanbanColumnProp[],
): readonly KanbanColumnDefinition<T>[];
```

---

### `KANBAN_IMPLICIT_SWIMLANE_ID`

```ts
KANBAN_IMPLICIT_SWIMLANE_ID: string;
```

---

### `KANBAN_UNMAPPED_COLUMN_PROP`

```ts
KANBAN_UNMAPPED_COLUMN_PROP: string;
```

---

### `NormalizedKanbanBoard`

```ts
interface NormalizedKanbanBoard {
  readonly config: ResolvedKanbanConfig<T>;
  readonly columns: readonly KanbanColumnDefinition<T>[];
  readonly swimlanes: readonly KanbanSwimlaneDefinition[];
  readonly diagnostics: readonly KanbanDiagnostic<T>[]
}
```

---

### `createKanbanProjection`

```ts
export function createKanbanProjection<T extends DataType>(
  cards: readonly T[],
  config: KanbanConfig<T> | ResolvedKanbanConfig<T>,
  options: CreateKanbanProjectionOptions<T> = {},
): KanbanProjection<T>;
```

---

### `getKanbanBucketCards`

```ts
export function getKanbanBucketCards<T extends DataType>(
  projection: KanbanProjection<T>,
  columnProp: KanbanColumnProp,
  swimlaneId: string | number,
  visibleOnly = false,
): readonly KanbanProjectedCard<T>[];
```

---

### `getKanbanBoardOrder`

```ts
export function getKanbanBoardOrder<T extends DataType>(projection: KanbanProjection<T>): readonly KanbanCardId[];
```

---

### `CreateKanbanProjectionOptions`

```ts
interface CreateKanbanProjectionOptions {
  /** Physical canonical indexes that passed an external filter. */
    readonly externallyVisibleSourceIndexes?: ReadonlySet<number>;
  /** @deprecated Prefer source indexes so invalid and duplicate card ids remain distinguishable. */
    readonly externallyVisibleCardIds?: ReadonlySet<KanbanCardId>;
  readonly isExternallyVisible?: (card: T, sourceIndex: number) => boolean
}
```

---

### `allocateFractionalRanks`

Allocates ordered ranks in a gap, or returns undefined when the bucket must be rebalanced.

```ts
export function allocateFractionalRanks(options: AllocateKanbanRanksOptions): readonly number[] | undefined;
```

---

### `createRebalancedKanbanRanks`

```ts
export function createRebalancedKanbanRanks<T extends DataType>(
  cards: readonly Pick<KanbanProjectedCard<T>, 'id'>[],
  spacing = KANBAN_RANK_SPACING,
): ReadonlyMap<KanbanCardId, number>;
```

---

### `KANBAN_RANK_SPACING`

```ts
KANBAN_RANK_SPACING: 1024;
```

---

### `AllocateKanbanRanksOptions`

```ts
interface AllocateKanbanRanksOptions {
  readonly beforeRank?: number;
  readonly afterRank?: number;
  readonly count: number;
  readonly spacing?: number;
  readonly minimumGap?: number
}
```

---

### `resolveKanbanCardRuleState`

```ts
export function resolveKanbanCardRuleState<T extends DataType>(
  options: ResolveKanbanCardRuleOptions<T>,
): ResolvedKanbanCardRuleState;
```

---

### `validateKanbanDrop`

```ts
export function validateKanbanDrop<T extends DataType>(
  options: ValidateKanbanDropOptions<T>,
): KanbanDropValidation;
```

---

### `ResolvedKanbanCardRuleState`

```ts
interface ResolvedKanbanCardRuleState {
  readonly classNames: readonly string[];
  readonly style: Readonly<Record<string, string | number>>;
  readonly badges: readonly KanbanBadge[];
  readonly draggable: boolean;
  readonly selectable: boolean;
  readonly editable: boolean
}
```

---

### `ValidateKanbanDropOptions`

```ts
interface ValidateKanbanDropOptions {
  readonly config: KanbanConfig<T> | ResolvedKanbanConfig<T>;
  readonly cards: readonly KanbanProjectedCard<T>[];
  readonly targetColumn: KanbanColumnDefinition<T>;
  readonly targetSwimlane: KanbanSwimlaneDefinition;
  /** Canonical count in the target column across every swimlane. */
    readonly targetColumnTotalCount?: number;
  /** Canonical count in the target column/swimlane bucket. */
    readonly targetTotalCount: number
}
```

---

### `KanbanDropValidation`

```ts
interface KanbanDropValidation {
  readonly valid: boolean;
  readonly reason?: string;
  readonly warning?: string;
  readonly projectedCount: number;
  readonly wipLimit?: number
}
```

---

### `uniqueKanbanCardIds`

```ts
export function uniqueKanbanCardIds(ids: Iterable<KanbanCardId>): KanbanCardId[];
```

---

### `pruneKanbanSelection`

```ts
export function pruneKanbanSelection(
  selectedIds: readonly KanbanCardId[],
  allowedIds: ReadonlySet<KanbanCardId> | readonly KanbanCardId[],
): readonly KanbanCardId[];
```

---

### `updateKanbanSelection`

```ts
export function updateKanbanSelection(options: UpdateKanbanSelectionOptions): readonly KanbanCardId[];
```

---

### `KanbanSelectionMode`

```ts
export type KanbanSelectionMode = 'replace' | 'toggle' | 'range' | 'clear' | 'api';
```

---

### `UpdateKanbanSelectionOptions`

```ts
interface UpdateKanbanSelectionOptions {
  readonly currentIds: readonly KanbanCardId[];
  readonly cardId?: KanbanCardId;
  readonly mode: KanbanSelectionMode;
  readonly orderedCardIds: readonly KanbanCardId[];
  readonly anchorId?: KanbanCardId;
  readonly selectionMode?: 'single' | 'multiple'
}
```

---

### `renderKanbanDateRange`

Renders a compact locale-aware schedule shared by default and custom cards.

```ts
export function renderKanbanDateRange(
  h: KanbanTemplateH,
  options: KanbanDateRangeRenderOptions,
): KanbanTemplateResult;
```

---

### `renderKanbanProgress`

Renders compact, theme-aware progress content for managed or custom cards.

```ts
export function renderKanbanProgress(
  h: KanbanTemplateH,
  options: KanbanProgressRenderOptions,
): KanbanTemplateResult;
```

---

### `renderKanbanAssignees`

Renders assignees with the shared Pro avatar component.

```ts
export function renderKanbanAssignees(
  h: KanbanTemplateH,
  options: KanbanAssigneesRenderOptions,
): KanbanTemplateResult;
```

---

### `createKanbanColumns`

```ts
export function createKanbanColumns<T extends DataType>(
  projection: KanbanProjection<T>,
): KanbanGridColumn<T>[];
```

---

### `createKanbanColumnTypes`

```ts
export function createKanbanColumnTypes<T extends DataType>(
  options: KanbanColumnTypeOptions<T>,
): Record<string, ColumnType<DataType>>;
```

---

### `createKanbanRowHeaders`

```ts
export function createKanbanRowHeaders<T extends DataType>(
  options: KanbanColumnTypeOptions<T>,
): RowHeaders;
```

---

### `KANBAN_COLUMN_TYPE`

```ts
KANBAN_COLUMN_TYPE: string;
```

---

### `KanbanGridColumn` (Extended from `index.ts`)

```ts
interface KanbanGridColumn {

}
```

---

### `installKanbanDependencies`

```ts
export function installKanbanDependencies(
  grid: HTMLRevoGridElement,
  providers: PluginProviders,
): KanbanInstalledDependencies;
```

---

### `KanbanInstalledDependencies`

```ts
interface KanbanInstalledDependencies {
  activate(): void;
  deactivate(): void;
  destroy(): void
}
```

---

### `KanbanGridSync`

```ts
class KanbanGridSync {
  initialize(): void;

  applyProjection(
    projection: KanbanProjection<T>,
    options: { readonly applyColumns?: boolean } = {},
  ): void;

  captureSource(source: readonly T[]): void;

  captureColumns(columns: readonly (ColumnGrouping | ColumnRegular)[]): void;

  restore(source?: readonly T[]): void;

  isApplyingSource(): boolean;

  isApplyingColumns(): boolean;

  refresh(): void;
}
```

---

### `renderKanbanCard`

```ts
export function renderKanbanCard<T extends DataType>(
  h: KanbanTemplateH,
  projectedCard: KanbanProjectedCard<T>,
  column: KanbanColumnDefinition<T>,
  swimlane: KanbanSwimlaneDefinition,
  options: KanbanColumnTypeOptions<T>,
  index: number,
);
```

---

### `KanbanRendererActions`

```ts
interface KanbanRendererActions {
  readonly getSelectedCardIds: () => readonly KanbanCardId[];
  readonly getDraggingCardIds?: () => readonly KanbanCardId[];
  readonly onCardSelect: (event: MouseEvent | KeyboardEvent, cardId: KanbanCardId) => void;
  readonly onCardPointerDown: (event: PointerEvent, cardId: KanbanCardId, element: HTMLElement) => void;
  readonly onCardKeyDown: (event: KeyboardEvent, cardId: KanbanCardId) => void;
  readonly onCardEditRequest: (cardId: KanbanCardId) => void;
  readonly onColumnToggle?: (columnProp: KanbanColumnProp) => void;
  readonly onSwimlaneToggle?: (swimlaneId: string | number) => void;
  readonly isSwimlaneColumnCollapsed?: () => boolean;
  readonly onSwimlaneColumnToggle?: () => void;
  readonly onMoveRequest?: (cardIds: readonly KanbanCardId[], target: KanbanMoveTarget) => void
}
```

---

### `KanbanColumnTypeOptions`

```ts
interface KanbanColumnTypeOptions {
  readonly getProjection: () => KanbanProjection<T> | null;
  readonly getConfig: () => KanbanConfig<T> | ResolvedKanbanConfig<T>;
  readonly getLabels: () => KanbanLabels;
  readonly actions: KanbanRendererActions<T>
}
```

---

### `KanbanContextMenuControllerOptions`

```ts
interface KanbanContextMenuControllerOptions {
  readonly grid: HTMLRevoGridElement;
  readonly getProjection: () => KanbanProjection<T> | null;
  readonly getConfig: () => ResolvedKanbanConfig<T> | null;
  readonly getLabels: () => KanbanLabels;
  readonly getSelectedCardIds: () => readonly KanbanCardId[];
  readonly canEditCard: (cardId: KanbanCardId) => boolean;
  readonly validateMove: (
      cardIds: readonly KanbanCardId[],
      target: KanbanMoveTarget,
    ) => true | string | { readonly valid: true; readonly warning: string };
  readonly moveCards: (cardIds: readonly KanbanCardId[], target: KanbanMoveTarget) => void;
  readonly requestEditCard: (cardId: KanbanCardId) => void;
  readonly requestCreateCard: (detail: KanbanCardRequestDetail<T>) => void;
  readonly requestDeleteCards: (cardIds: readonly KanbanCardId[]) => void
}
```

---

### `KanbanContextMenuController`

Composes card actions into the shared Pro context-menu surface.

```ts
class KanbanContextMenuController {
  apply(): void;

  remove(): void;
}
```

---

### `toDomCardId`

```ts
export function toDomCardId(value: KanbanCardId): string;
```

---

### `KanbanDomDropTarget` (Extended from `index.ts`)

```ts
interface KanbanDomDropTarget {
  readonly element: HTMLElement;
  readonly anchorElement?: HTMLElement
}
```

---

### `KanbanDropVisualState`

```ts
export type KanbanDropVisualState = 'valid' | 'invalid' | 'noop';
```

---

### `KanbanDomLayer`

Owns the small amount of DOM state required by pointer drag and drop.

```ts
class KanbanDomLayer {
  hitTest(clientX: number, clientY: number): KanbanDomDropTarget | undefined;

  createPreview(source: HTMLElement, count: number): void;

  movePreview(clientX: number, clientY: number): void;

  showIndicator(target: KanbanDomDropTarget, state: KanbanDropVisualState): void;

  clearDropFeedback(): void;

  autoScroll(clientX: number, clientY: number, margin = 48, speed = 18): boolean;

  clear(): void;

  focusCardHandle(cardId: KanbanCardId, fallbackTarget?: KanbanMoveTarget): void;
}
```

---

### `KanbanKeyboardPosition` (Extended from `index.ts`)

```ts
interface KanbanKeyboardPosition {
  readonly columnName: string;
  readonly swimlaneTitle: string
}
```

---

### `KanbanKeyboardControllerOptions`

```ts
interface KanbanKeyboardControllerOptions {
  readonly getSelectedCardIds: () => readonly KanbanCardId[];
  readonly selectForDrag: (cardId: KanbanCardId) => void;
  readonly getPositions: () => readonly KanbanKeyboardPosition[];
  readonly announce: (message: string) => void;
  readonly pickedUpLabel: (count: number) => string;
  readonly targetLabel: (position: KanbanKeyboardPosition) => string;
  readonly cancelledLabel: () => string;
  readonly onStateChange?: () => void;
  readonly onMove: (cardIds: readonly KanbanCardId[], target: KanbanMoveTarget, reason: 'keyboard') => void | Promise<void>
}
```

---

### `KanbanKeyboardController`

```ts
class KanbanKeyboardController {
  keyDown(event: KeyboardEvent, cardId: KanbanCardId): boolean;

  cancel(): void;

  getActiveCardIds(): readonly KanbanCardId[];
}
```

---

### `KanbanLiveRegion`

```ts
class KanbanLiveRegion {
  mount(): void;

  announce(message: string): void;

  destroy(): void;
}
```

---

### `KanbanPointerDropState`

```ts
interface KanbanPointerDropState {
  readonly cardIds: readonly KanbanCardId[];
  readonly target?: KanbanMoveTarget;
  readonly valid: boolean;
  readonly state: KanbanDropVisualState;
  readonly reason?: string
}
```

---

### `KanbanPointerControllerOptions`

```ts
interface KanbanPointerControllerOptions {
  readonly getSelectedCardIds: () => readonly KanbanCardId[];
  readonly selectForDrag: (cardId: KanbanCardId) => void;
  readonly validateTarget?: (
      cardIds: readonly KanbanCardId[],
      target: KanbanMoveTarget,
    ) => true | string | { readonly valid: true; readonly warning: string };
  readonly isNoopTarget?: (cardIds: readonly KanbanCardId[], target: KanbanMoveTarget) => boolean;
  readonly getNoopReason?: () => string;
  readonly getNoTargetReason?: () => string;
  readonly onDropStateChange?: (state: KanbanPointerDropState) => void;
  readonly announceValidation?: (message: string) => void;
  readonly onMove: (cardIds: readonly KanbanCardId[], target: KanbanMoveTarget, reason: 'pointer') => void | Promise<void>
}
```

---

### `KanbanPointerController`

```ts
class KanbanPointerController {
  pointerDown(event: PointerEvent, cardId: KanbanCardId, source: HTMLElement): void;

  cancel(): void;

  getDraggingCardIds(): readonly KanbanCardId[];

  consumeSuppressedClick(cardId: KanbanCardId): boolean;

  destroy(): void;
}
```

---

### `KanbanSelectionUpdate`

```ts
interface KanbanSelectionUpdate {
  readonly cardIds: readonly KanbanCardId[];
  readonly mode: KanbanSelectionMode
}
```

---

### `KanbanSelectionController`

```ts
class KanbanSelectionController {
  get(): readonly KanbanCardId[];

  has(id: KanbanCardId): boolean;

  set(ids: readonly KanbanCardId[], mode: KanbanSelectionMode = 'api'): void;

  clear(mode: KanbanSelectionMode = 'clear'): void;

  select(
    id: KanbanCardId,
    orderedIds: readonly KanbanCardId[],
    modifiers: { readonly toggle?: boolean; readonly range?: boolean } = {},
  ): void;

  prune(visibleIds: ReadonlySet<KanbanCardId>): void;
}
```

---

### `KanbanSwimlaneGroupRowRendererOptions`

```ts
interface KanbanSwimlaneGroupRowRendererOptions {
  readonly getProjection: () => KanbanProjection<T> | null;
  readonly getConfig: () => ResolvedKanbanConfig<T>;
  readonly getLabels: () => KanbanLabels;
  readonly onSwimlaneToggle: (swimlaneId: KanbanSwimlaneId) => void
}
```

---

### `KanbanSwimlaneGroupRowRenderer`

Renders projected lane identity rows across the full workflow viewport.

```ts
class KanbanSwimlaneGroupRowRenderer {
  apply(detail: BeforeRowRenderEvent<KanbanGridRow<T>>): void;
}
```

---

### `renderKanbanToggleIcon`

```ts
export function renderKanbanToggleIcon(h: KanbanTemplateH);
```

---

### `getCoreFilteredKanbanCardIds`

```ts
export function getCoreFilteredKanbanCardIds<T extends DataType>(options: {
  readonly cards: readonly T[];
  readonly idField: ColumnProp;
  readonly filterPlugin?: FilterPlugin;
  readonly hostColumns: readonly (ColumnGrouping | ColumnRegular)[];
}): ReadonlySet<KanbanCardId> | undefined;
```

---

### `getCoreFilteredKanbanSourceIndexes`

Preserves physical identity for missing and duplicate card ids during core filtering.

```ts
export function getCoreFilteredKanbanSourceIndexes<T extends DataType>(options: {
  readonly cards: readonly T[];
  readonly filterPlugin?: FilterPlugin;
  readonly hostColumns: readonly (ColumnGrouping | ColumnRegular)[];
}): ReadonlySet<number> | undefined;
```

---

# Kanban Card Editor Dialog

URL: https://pro.rv-grid.com/api/kanban-card-editor-dialog/
Source: src/content/docs/api/kanban-card-editor-dialog.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  kanbanCardEditorDialog?: KanbanCardEditorDialogOptions | false;
  'kanban-card-editor-dialog'?: KanbanCardEditorDialogOptions | false
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [BEFORE_KANBAN_CARD_EDITOR_VALIDATE_EVENT]: KanbanCardEditorValidationStartDetail;
  [BEFORE_KANBAN_CARD_EDITOR_FIELD_VALIDATE_EVENT]: KanbanCardEditorBeforeFieldValidationDetail;
  [KANBAN_CARD_EDITOR_FIELD_VALIDATE_EVENT]: KanbanCardEditorFieldValidationDetail;
  [KANBAN_CARD_EDITOR_VALIDATE_EVENT]: KanbanCardEditorValidationCompleteDetail;
  [KANBAN_CARD_EDITOR_INVALID_EVENT]: KanbanCardEditorValidationCompleteDetail
}
```

## Plugin API

### `kanbanCardEditorDialogDependencies`

#### Dependencies

- **Required** `KanbanPlugin`: Uses Kanban canonical data, permissions, rules, events, and history-backed CRUD methods.

```ts
kanbanCardEditorDialogDependencies: PluginDependency[];
```

---

### `KanbanCardEditorDialogPlugin`

```ts
class KanbanCardEditorDialogPlugin {
  open(request: KanbanCardEditorOpenRequest<T>): void;

  close(): void;

  async validate(): Promise<KanbanCardEditorValidationResult>;
}
```

---

### `KanbanCardEditorMode`

```ts
export type KanbanCardEditorMode = 'create' | 'edit';
```

---

### `KanbanCardEditorFieldKind`

```ts
export type KanbanCardEditorFieldKind =
  | 'text' | 'textarea' | 'number' | 'select' | 'multiselect' | 'tags'
  | 'checkbox' | 'date' | 'datetime' | 'color' | 'assignees' | 'custom';
```

---

### `KanbanCardEditorOption`

```ts
interface KanbanCardEditorOption {
  readonly value: string | number;
  readonly label: string;
  readonly avatar?: unknown;
  readonly disabled?: boolean
}
```

---

### `KanbanCardEditorFieldContext`

```ts
interface KanbanCardEditorFieldContext {
  readonly grid: HTMLRevoGridElement;
  readonly mode: KanbanCardEditorMode;
  readonly card: T | null;
  readonly draft: T;
  readonly field: KanbanCardEditorField<T>
}
```

---

### `KanbanCardEditorFieldRendererLifecycle`

```ts
interface KanbanCardEditorFieldRendererLifecycle {
  update?(context: KanbanCardEditorFieldRendererContext<T>): void;
  destroy?(): void
}
```

---

### `KanbanCardEditorFieldRendererContext` (Extended from `index.tsx`)

```ts
interface KanbanCardEditorFieldRendererContext {
  readonly value: unknown;
  readonly error?: string;
  readonly disabled: boolean;
  readonly setValue: (value: unknown) => void
}
```

---

### `KanbanCardEditorDomRenderer`

```ts
interface KanbanCardEditorDomRenderer {
  mount(container: HTMLElement, context: KanbanCardEditorRendererContext<T>): void | KanbanCardEditorRendererLifecycle<T>
}
```

---

### `KanbanCardEditorRendererLifecycle`

```ts
interface KanbanCardEditorRendererLifecycle {
  update?(context: KanbanCardEditorRendererContext<T>): void;
  destroy?(): void
}
```

---

### `KanbanCardEditorFieldDomRenderer`

```ts
interface KanbanCardEditorFieldDomRenderer {
  mount(container: HTMLElement, context: KanbanCardEditorFieldRendererContext<T>): void | KanbanCardEditorFieldRendererLifecycle<T>
}
```

---

### `KanbanCardEditorField`

```ts
interface KanbanCardEditorField {
  readonly id: string;
  readonly label?: string;
  readonly kind?: KanbanCardEditorFieldKind;
  readonly field?: ColumnProp;
  readonly icon?: string;
  readonly order?: number;
  readonly hidden?: boolean | ((context: KanbanCardEditorFieldContext<T>) => boolean);
  readonly fullWidth?: boolean;
  readonly defaultValue?: unknown | ((context: Omit<KanbanCardEditorFieldContext<T>, 'field'>) => unknown);
  readonly options?: readonly KanbanCardEditorOption[] | ((context: KanbanCardEditorFieldContext<T>) => readonly KanbanCardEditorOption[]);
  readonly placeholder?: string;
  readonly readonly?: boolean | ((context: KanbanCardEditorFieldContext<T>) => boolean);
  readonly required?: boolean;
  readonly read?: (card: T, context: KanbanCardEditorFieldContext<T>) => unknown;
  readonly write?: (value: unknown, card: T, context: KanbanCardEditorFieldContext<T>) => Partial<T>;
  readonly format?: (value: unknown, context: KanbanCardEditorFieldContext<T>) => unknown;
  readonly parse?: (value: unknown, context: KanbanCardEditorFieldContext<T>) => unknown;
  readonly validate?: (value: unknown, context: KanbanCardEditorFieldContext<T>) => string | void | Promise<string | void>;
  readonly renderer?: KanbanCardEditorFieldDomRenderer<T>
}
```

---

### `KanbanCardEditorValidationReason`

```ts
export type KanbanCardEditorValidationReason = 'submit' | 'manual';
```

---

### `KanbanCardEditorValidationErrors`

```ts
export type KanbanCardEditorValidationErrors = Readonly<Record<string, string>>;
```

---

### `KanbanCardEditorFieldValidationStatus`

```ts
export type KanbanCardEditorFieldValidationStatus =
  | 'valid'
  | 'invalid'
  | 'skipped'
  | 'cancelled';
```

---

### `KanbanCardEditorValidationContext`

```ts
interface KanbanCardEditorValidationContext {
  readonly grid: HTMLRevoGridElement;
  readonly mode: KanbanCardEditorMode;
  readonly card: T | null;
  readonly draft: T;
  readonly fields: readonly KanbanCardEditorField<T>[];
  readonly reason: KanbanCardEditorValidationReason
}
```

---

### `KanbanCardEditorValidationResult`

```ts
interface KanbanCardEditorValidationResult {
  readonly valid: boolean;
  readonly cancelled: boolean;
  readonly errors: KanbanCardEditorValidationErrors
}
```

---

### `KanbanCardEditorValidationStartDetail` (Extended from `index.tsx`)

```ts
interface KanbanCardEditorValidationStartDetail {
  readonly errors: Record<string, string>;
  readonly setError: (fieldId: string, error?: string) => void
}
```

---

### `KanbanCardEditorBeforeFieldValidationDetail` (Extended from `index.tsx`)

```ts
interface KanbanCardEditorBeforeFieldValidationDetail {
  readonly field: KanbanCardEditorField<T>;
  readonly value: unknown;
  error?: string;
  readonly setError: (error?: string) => void
}
```

---

### `KanbanCardEditorFieldValidationDetail` (Extended from `index.tsx`)

```ts
interface KanbanCardEditorFieldValidationDetail {
  readonly field: KanbanCardEditorField<T>;
  readonly value: unknown;
  readonly error?: string;
  readonly status: KanbanCardEditorFieldValidationStatus
}
```

---

### `KanbanCardEditorValidationCompleteDetail` (Extended from `index.tsx`)

```ts
interface KanbanCardEditorValidationCompleteDetail {
  readonly result: KanbanCardEditorValidationResult
}
```

---

### `KanbanCardEditorFormValidationResult`

```ts
export type KanbanCardEditorFormValidationResult =
  | string
  | KanbanCardEditorValidationErrors
  | void;
```

---

### `KanbanCardEditorFormValidator`

```ts
export type KanbanCardEditorFormValidator<T extends DataType = DataType> = (
  context: KanbanCardEditorValidationContext<T>,
) => KanbanCardEditorFormValidationResult | Promise<KanbanCardEditorFormValidationResult>;
```

---

### `KanbanCardEditorDraftState`

```ts
interface KanbanCardEditorDraftState {
  readonly mode: KanbanCardEditorMode;
  readonly card: T | null;
  readonly draft: T;
  readonly dirty: boolean;
  readonly pending: boolean;
  readonly errors: Readonly<Record<string, string>>
}
```

---

### `KanbanCardEditorDraftController`

```ts
interface KanbanCardEditorDraftController {
  getState(): KanbanCardEditorDraftState<T>;
  setValue(fieldId: string, value: unknown): void;
  setDraft(patch: Partial<T>): void;
  setErrors(errors: Readonly<Record<string, string>>): void;
  reset(): void;
  close(): void;
  validate(): Promise<KanbanCardEditorValidationResult>;
  submit(): void;
  delete(): void
}
```

---

### `KanbanCardEditorRendererContext`

```ts
interface KanbanCardEditorRendererContext {
  readonly grid: HTMLRevoGridElement;
  readonly open: boolean;
  readonly fields: readonly KanbanCardEditorField<T>[];
  readonly state: KanbanCardEditorDraftState<T>;
  readonly controller: KanbanCardEditorDraftController<T>
}
```

---

### `KanbanCardEditorSubmitContext`

```ts
interface KanbanCardEditorSubmitContext {
  readonly grid: HTMLRevoGridElement;
  readonly mode: KanbanCardEditorMode;
  readonly card: T | null;
  readonly draft: T;
  readonly result?: KanbanMutationResult<T>
}
```

---

### `KanbanCardEditorDeleteContext`

```ts
interface KanbanCardEditorDeleteContext {
  readonly grid: HTMLRevoGridElement;
  readonly cards: readonly T[];
  readonly cardIds: readonly KanbanCardId[]
}
```

---

### `KanbanCardEditorDialogOptions`

```ts
interface KanbanCardEditorDialogOptions {
  readonly fields?: readonly KanbanCardEditorField<T>[];
  readonly hiddenFields?: readonly string[];
  readonly fieldOrder?: readonly string[];
  readonly createDraft?: (context: { readonly grid: HTMLRevoGridElement; readonly request: KanbanCardRequestDetail<T> }) => Partial<T> | Promise<Partial<T>>;
  readonly createCardId?: (context: { readonly grid: HTMLRevoGridElement; readonly cards: readonly T[] }) => KanbanCardId | Promise<KanbanCardId>;
  readonly validate?: KanbanCardEditorFormValidator<T>;
  readonly onSubmit?: (context: KanbanCardEditorSubmitContext<T>) => boolean | void | Promise<boolean | void>;
  readonly onDelete?: (context: KanbanCardEditorDeleteContext<T>) => boolean | void | Promise<boolean | void>;
  readonly confirmDelete?: boolean | ((context: KanbanCardEditorDeleteContext<T>) => boolean | Promise<boolean>);
  readonly confirmDiscard?: boolean | ((state: KanbanCardEditorDraftState<T>) => boolean | Promise<boolean>);
  readonly customization?: { readonly editor?: KanbanCardEditorDomRenderer<T> };
  readonly labels?: Partial<KanbanCardEditorLabels>
}
```

---

### `KanbanCardEditorLabels`

```ts
interface KanbanCardEditorLabels {
  readonly newCard: string;
  readonly untitledCard: string;
  readonly cancel: string;
  readonly save: string;
  readonly delete: string;
  readonly close: string;
  readonly deleteConfirm: string;
  readonly discardConfirm: string;
  readonly required: string;
  readonly validationSummary: string
}
```

---

### `KanbanCardEditorOpenRequest`

```ts
interface KanbanCardEditorOpenRequest {
  readonly mode: KanbanCardEditorMode;
  readonly card?: T;
  readonly cardId?: KanbanCardId;
  readonly cardIds?: readonly KanbanCardId[];
  readonly columnProp?: KanbanColumnProp;
  readonly swimlaneId?: KanbanSwimlaneId;
  readonly request?: KanbanCardRequestDetail<T>
}
```

---

### `resolveKanbanCardEditorFields`

```ts
export function resolveKanbanCardEditorFields<T extends DataType>(
  config: ResolvedKanbanConfig<T>,
  options: KanbanCardEditorDialogOptions<T> = {},
): readonly KanbanCardEditorField<T>[];
```

---

### `createKanbanCardId`

```ts
export function createKanbanCardId<T extends DataType>(cards: readonly T[], idField: ColumnProp): string;
```

---

### `KanbanCardEditorDialog`

```ts
export function KanbanCardEditorDialog<T extends DataType>(props: KanbanCardEditorDialogProps<T>);
```

---

### `KanbanCardEditorDialogProps`

```ts
interface KanbanCardEditorDialogProps {
  readonly grid: HTMLRevoGridElement;
  readonly fields: readonly KanbanCardEditorField<T>[];
  readonly state: KanbanCardEditorDraftState<T>;
  readonly labels: KanbanCardEditorLabels;
  readonly onValue: (field: KanbanCardEditorField<T>, value: unknown) => void;
  readonly onClose: () => void;
  readonly onSubmit: () => void;
  readonly onDelete: () => void
}
```

---

### `validateKanbanCardEditor`

Runs the shared packaged/replacement-editor validation and event pipeline.

```ts
export async function validateKanbanCardEditor<T extends DataType>(
  options: ValidateKanbanCardEditorOptions<T>,
): Promise<KanbanCardEditorValidationResult>;
```

---

### `BEFORE_KANBAN_CARD_EDITOR_VALIDATE_EVENT`

```ts
BEFORE_KANBAN_CARD_EDITOR_VALIDATE_EVENT: string;
```

---

### `BEFORE_KANBAN_CARD_EDITOR_FIELD_VALIDATE_EVENT`

```ts
BEFORE_KANBAN_CARD_EDITOR_FIELD_VALIDATE_EVENT: string;
```

---

### `KANBAN_CARD_EDITOR_FIELD_VALIDATE_EVENT`

```ts
KANBAN_CARD_EDITOR_FIELD_VALIDATE_EVENT: string;
```

---

### `KANBAN_CARD_EDITOR_VALIDATE_EVENT`

```ts
KANBAN_CARD_EDITOR_VALIDATE_EVENT: string;
```

---

### `KANBAN_CARD_EDITOR_INVALID_EVENT`

```ts
KANBAN_CARD_EDITOR_INVALID_EVENT: string;
```

---

### `KanbanCardEditorValidationEvent`

```ts
interface KanbanCardEditorValidationEvent {
  readonly defaultPrevented: boolean
}
```

---

### `ValidateKanbanCardEditorOptions`

```ts
interface ValidateKanbanCardEditorOptions {
  readonly grid: HTMLRevoGridElement;
  readonly mode: KanbanCardEditorValidationContext<T>['mode'];
  readonly card: T | null;
  readonly draft: T;
  readonly fields: readonly KanbanCardEditorField<T>[];
  readonly reason: KanbanCardEditorValidationReason;
  readonly requiredMessage: string;
  readonly validateForm?: KanbanCardEditorFormValidator<T>;
  readonly emit: (eventName: string, detail: unknown) => KanbanCardEditorValidationEvent
}
```

---

### `withKanbanCardEditorAssigneeOptions`

Adds board-backed options only when an assignee field has no explicit source.

```ts
export function withKanbanCardEditorAssigneeOptions<T extends DataType>({
  cards,
  config,
  fields,
}: KanbanCardEditorAssigneeFieldOptions<T>): readonly KanbanCardEditorField<T>[];
```

---

### `resolveKanbanCardEditorAssigneeOptions`

Builds a stable, de-duplicated resource catalog from canonical Kanban cards.

```ts
export function resolveKanbanCardEditorAssigneeOptions<T extends DataType>({
  cards,
  config,
}: KanbanCardEditorAssigneeCatalogOptions<T>): readonly KanbanCardEditorOption[];
```

---

### `resolveKanbanCardEditorAssigneeResources`

Keeps selected mapped values visible even before an application supplies a catalog.

```ts
export function resolveKanbanCardEditorAssigneeResources(
  options: readonly KanbanCardEditorOption[],
  value: unknown,
): readonly KanbanCardEditorOption[];
```

---

### `KanbanCardEditorCustomField`

```ts
export function KanbanCardEditorCustomField<T extends DataType>(
  props: KanbanCardEditorCustomFieldProps<T>,
);
```

---

### `KanbanCardEditorCustomFieldProps` (Extended from `kanban-card-editor-custom-field.tsx`)

```ts
interface KanbanCardEditorCustomFieldProps {
  readonly value: unknown;
  readonly disabled: boolean
}
```

---

### `KanbanCardEditorDialogHeader`

```ts
export function KanbanCardEditorDialogHeader<T extends DataType>(
  props: KanbanCardEditorDialogHeaderProps<T>,
);
```

---

### `KanbanCardEditorValidationMessage`

```ts
export function KanbanCardEditorValidationMessage<T extends DataType>(
  props: KanbanCardEditorDialogProps<T>,
);
```

---

### `KanbanCardEditorDialogBody`

```ts
export function KanbanCardEditorDialogBody<T extends DataType>(
  props: KanbanCardEditorDialogProps<T>,
);
```

---

### `KanbanCardEditorDialogFooter`

```ts
export function KanbanCardEditorDialogFooter<T extends DataType>(
  props: KanbanCardEditorDialogProps<T>,
);
```

---

### `KanbanCardEditorFieldProps` (Extended from `kanban-card-editor-dialog.props.ts`)

```ts
interface KanbanCardEditorFieldProps {
  readonly field: KanbanCardEditorField<T>
}
```

---

### `createKanbanEditorFieldContext`

```ts
export function createKanbanEditorFieldContext<T extends DataType>(
  field: KanbanCardEditorField<T>,
  props: KanbanCardEditorDialogProps<T>,
): KanbanCardEditorFieldContext<T>;
```

---

### `readKanbanEditorFieldValue`

```ts
export function readKanbanEditorFieldValue<T extends DataType>(
  field: KanbanCardEditorField<T>,
  props: KanbanCardEditorDialogProps<T>,
): unknown;
```

---

### `isKanbanEditorFieldReadonly`

```ts
export function isKanbanEditorFieldReadonly<T extends DataType>(
  field: KanbanCardEditorField<T>,
  props: KanbanCardEditorDialogProps<T>,
): boolean;
```

---

### `isKanbanEditorFieldVisible`

```ts
export function isKanbanEditorFieldVisible<T extends DataType>(
  field: KanbanCardEditorField<T>,
  props: KanbanCardEditorDialogProps<T>,
): boolean;
```

---

### `displayKanbanEditorFieldValue`

```ts
export function displayKanbanEditorFieldValue<T extends DataType>(
  value: unknown,
  field: KanbanCardEditorField<T>,
): string;
```

---

### `kanbanEditorInputType`

```ts
export function kanbanEditorInputType(kind: KanbanCardEditorField['kind']): string;
```

---

### `toKanbanEditorValueArray`

```ts
export function toKanbanEditorValueArray(value: unknown): readonly unknown[];
```

---

### `resolveKanbanEditorOptionValue`

```ts
export function resolveKanbanEditorOptionValue(
  options: readonly { readonly value: string | number }[],
  value: string,
): string | number;
```

---

### `KanbanCardEditorFieldControl`

```ts
export function KanbanCardEditorFieldControl<T extends DataType>(
  props: KanbanCardEditorFieldControlProps<T>,
);
```

---

### `KanbanCardEditorFieldControlProps` (Extended from `kanban-card-editor-field-control.tsx`)

```ts
interface KanbanCardEditorFieldControlProps {
  readonly value: unknown;
  readonly disabled: boolean;
  readonly options: readonly KanbanCardEditorOption[];
  readonly error?: string;
  readonly errorId?: string;
  readonly labelId: string
}
```

---

### `KanbanCardEditorFieldRow`

```ts
export function KanbanCardEditorFieldRow<T extends DataType>(
  props: KanbanCardEditorFieldProps<T>,
);
```

---

# License

URL: https://pro.rv-grid.com/api/license/
Source: src/content/docs/api/license.md

### `LicensePlugin`

The LicensePlugin is a RevoGrid plugin that displays trial version information
in the bottom-right corner of the grid.

```ts
class LicensePlugin {
  destroy(): void;
}
```

---

# Loader

URL: https://pro.rv-grid.com/api/loader/
Source: src/content/docs/api/loader.md

## Module Extensions

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /**
       * Event for loader
       *
       * @example
       * ```typescript
       * grid.addEventListener(LOADER_EVENT, (e) => {
       *   console.log(e);
       * });
       */
      [LOADER_EVENT]: boolean
}
```

## Plugin API

### `LoaderPlugin`

```ts
class LoaderPlugin {
  busy(isBusy: boolean);
}
```

---

# MoveColumn

URL: https://pro.rv-grid.com/api/movecolumn/
Source: src/content/docs/api/moveColumn.md

## Module Extensions

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [COLUMN_DRAG_START_EVENT]: ColumnDragStartEventData;
  [COLUMN_DRAG_MOVE_EVENT]: MouseEvent;
  [BEFORE_COLUMN_DRAG_END_EVENT]: BeforeColumnDragEndEventData;
  [COLUMN_DRAG_END_EVENT]: ColumnDragEventData
}
```

## Plugin API

### `getLeftRelative`

```ts
export declare function getLeftRelative(absoluteX: number, gridPos: number, offset: number): number;;
```

---

### `getColumnDragPosition`

```ts
export declare function getColumnDragPosition(targetItem: PositionItem, startItem: PositionItem, renderOffset: number, scrollOffset: number): number;;
```

---

### `COLUMN_DRAG_MOVE_EVENT`

```ts
COLUMN_DRAG_MOVE_EVENT: string;
```

---

### `COLUMN_DRAG_END_EVENT`

```ts
COLUMN_DRAG_END_EVENT: string;
```

---

### `BEFORE_COLUMN_DRAG_END_EVENT`

```ts
BEFORE_COLUMN_DRAG_END_EVENT: string;
```

---

### `COLUMN_DRAG_START_EVENT`

```ts
COLUMN_DRAG_START_EVENT: string;
```

---

### `DragStartEventDetails`

```ts
export type DragStartEventDetails = {
    event: MouseEvent;
    data: ColumnPropProp;
};
```

---

### `ColumnDragStartEventData`

```ts
export type ColumnDragStartEventData = ColumnPropProp;
```

---

### `StaticData`

```ts
export type StaticData = {
    startPos: number;
    startItem: PositionItem;
    pin?: DimensionColPin;
    dataEl: HTMLElement;
    scrollEl: Element;
    gridEl: HTMLElement;
    cols: DimensionSettingsState;
};
```

---

### `ColumnDragEventData`

```ts
export type ColumnDragEventData = {
    /**
     * Reordered columns for the affected column viewport.
     */
    columns: ColumnRegular[];
    elRect: DOMRect;
    gridRect: DOMRect;
    /**
     * Physical column indexes in their current visual order.
     */
    order: number[];
    scrollOffset: number;
    type: DimensionCols;
};
```

---

### `BeforeColumnDragEndEventData` (Extended from `column.drag.plugin.d.ts`)

```ts
export type BeforeColumnDragEndEventData = StaticData & {
    startPosition: PositionItem;
    newPosition: PositionItem;
    newItem?: ColumnRegular;
};
```

---

### `ColumnMovePlugin`

```ts
class ColumnMovePlugin {
  dragStart({ event, data }: DragStartEventDetails): void;;

  doMove(e: MouseEvent): void;;

  move(e: MouseEvent): void;;

  onMouseOut(_: MouseEvent): void;;

  onMouseUp(e: MouseEvent): void;;

  clearOrder(): void;;

  /**
       * Clearing subscription
       */
  clearSubscriptions(): void;;
}
```

---

### `ColumnOrderHandler`

```ts
class ColumnOrderHandler {
  renderAutoscroll(_: MouseEvent, parent: HTMLElement | null): void;;

  autoscroll(pos: number, dataContainerSize: number, direction?: string): void;;

  start(e: MouseEvent, { dataEl, gridRect, scrollEl, gridEl }: {
        dataEl: HTMLElement;
        gridRect: DOMRect;
        scrollEl: Element;
        gridEl: Element;
    }, dir?: 'top' | 'left'): void;;

  stop(gridEl: Element): void;;

  showHandler(pos: number, size: number, direction?: string): void;;

  render(): HTMLDivElement;;
}
```

---

# Multi Column

URL: https://pro.rv-grid.com/api/multi-column/
Source: src/content/docs/api/multi-column.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Configuration for multi-column type
       */
      multiColumn?: MultiColumnConfig
}
```

## Plugin API

### `isEditorCtrConstructible`

```ts
export function isEditorCtrConstructible(
  editor: any,
): editor is EditorCtrConstructible;
```

---

### `MultiColumn`

The MultiColumn type is a custom column type for RevoGrid that can apply different renderers
and editors based on the value type.
editors as well.

**Key Features**:
- **Multiple Renderers**: Applies different renderers based on conditions
- **Multiple Editors**: Applies different editors based on conditions
- **Default Fallbacks**: Uses default renderer and editor if no condition matches
- **Cell Properties**: Applies consistent styling for cells
- **Array Support**: Handles arrays of values using the array renderer

**Usage**:
- Import `MultiColumn` and use it to define different renderers and editors for different value types
- Configure the column with options like renderers and editors
- Use the `arrayOptions` to customize how arrays are rendered

### Example
```typescript
import { MultiColumn } from '@revolist/revogrid-pro';
import { editorSlider, editorCheckbox } from '@revolist/revogrid-pro';
import NumberColumnType from '@revolist/revogrid-column-numeral';
import DateColumnType from '@revolist/revogrid-column-date';

const numberType = new NumberColumnType('0.00');
const dateType = new DateColumnType();

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'data',
    name: 'Mixed Data',
    columnType: 'multi',
    multiColumn: {
      defaultRenderer: numberType.cellTemplate,
      defaultEditor: numberType.editor,
      renderers: [
        {
          condition: (value) => value instanceof Date ||
            (typeof value === 'string' && !isNaN(Date.parse(value))),
          renderer: dateType.cellTemplate,
          editor: dateType.editor,
        },
        {
          condition: (value) => typeof value === 'number' && value >= 0 && value <= 100,
          renderer: editorSlider,
          editor: editorSlider,
        },
        {
          condition: (value) => typeof value === 'boolean',
          renderer: editorCheckbox,
          editor: editorCheckbox,
        },
      ],
      // Array renderer options
      arrayOptions: {
        separator: ' | ',
        wrapper: 'div',
        wrapperClass: 'array-container',
      },
    },
  },
];
```

### Example with Array Values
```typescript
import { MultiColumn } from '@revolist/revogrid-pro';
import { linkRenderer } from '@revolist/revogrid-pro';
import NumberColumnType from '@revolist/revogrid-column-numeral';

const numberType = new NumberColumnType('0.00');

const grid = document.createElement('revo-grid');
grid.columns = [
  {
    prop: 'data',
    name: 'Mixed Data',
    columnType: 'multi',
    multiColumn: {
      defaultRenderer: numberType.cellTemplate,
      defaultEditor: numberType.editor,
      renderers: [
        {
          // Use linkRenderer for URLs
          condition: (value) => typeof value === 'string' &&
            (value.startsWith('http://') || value.startsWith('https://')),
          renderer: linkRenderer,
        },
        {
          // Use numberType for numbers
          condition: (value) => typeof value === 'number',
          renderer: numberType.cellTemplate,
          editor: numberType.editor,
        },
      ],
      // Array renderer options
      arrayOptions: {
        separator: ', ',
        wrapper: 'div',
        wrapperClass: 'array-container',
      },
    },
  },
];

// Example data with arrays
grid.source = [
  { data: [1, 2, 3] }, // Will be rendered as numbers
  { data: ['https://example.com', 'https://example.org'] }, // Will be rendered as links
  { data: [1, 'https://example.com', true] }, // Mixed types in array
];
```

```ts
MultiColumn: {
  cellTemplate: CellTemplate<DataType<any, ColumnProp>>;
  editor: typeof MultiColumnEditor;
};
```

---

### `createColumnGroupingExportHeaders`

Builds Excel-ready grouped header rows from the original `ColumnGrouping`
column tree and a flattened export column list.

```ts
export function createColumnGroupingExportHeaders({
  columns,
  exportColumns,
}: ColumnGroupingExportHeaderContext): ColumnGroupingExportHeaders;
```

---

### `ColumnGroupingExportColumn`

```ts
export type ColumnGroupingExportColumn = ColumnRegular;
```

---

### `ColumnGroupingExportSourceColumn`

```ts
export type ColumnGroupingExportSourceColumn =
  | ColumnGrouping
  | ColumnRegular;
```

---

### `ColumnGroupingExportMergeRange`

```ts
export type ColumnGroupingExportMergeRange = {
  start: {
    row: number;
    column: number;
  };
  end: {
    row: number;
    column: number;
  };
};
```

---

### `ColumnGroupingExportHeaderContext`

```ts
export type ColumnGroupingExportHeaderContext = {
  /**
   * Original column tree before RevoGrid flattens grouped columns.
   */
  columns: ColumnGroupingExportSourceColumn[];

  /**
   * Flattened columns in export order, for example from
   * `providers.column.getColumns('all')`.
   */
  exportColumns: ColumnGroupingExportColumn[];
};
```

---

### `ColumnGroupingExportHeaders`

```ts
export type ColumnGroupingExportHeaders = {
  /**
   * Group header rows only. Append the existing flattened leaf header row after
   * these rows in the export integration.
   */
  headerRows: string[][];

  /**
   * Zero-based merge ranges relative to `headerRows`.
   */
  merges: ColumnGroupingExportMergeRange[];
};
```

---

# Multi Range Selection

URL: https://pro.rv-grid.com/api/multi-range-selection/
Source: src/content/docs/api/multi-range-selection.md

## Module Extensions

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /** Fires after the active or inactive multi-range selection changes. */
      multirangeselectionchange: MultiRangeSelectionChangeEvent
}
```

---

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  /**
       * Multi-range selection configuration.
       */
      multiRangeSelection?: MultiRangeSelectionConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data property for multi-range selection configuration.
       * @deprecated Use `grid.multiRangeSelection` instead.
       */
      multiRangeSelection?: MultiRangeSelectionConfig
}
```

## Plugin API

### `MultiRangeSelectionChangeEvent`

Event payload emitted when active or inactive multi-range selection changes.

```ts
/**
 * Event payload emitted when active or inactive multi-range selection changes.
 */
export type MultiRangeSelectionChangeEvent = {
  ranges: MultiRangeSelectionRange[];
  inactiveRanges: MultiRangeSelectionRange[];
  activeRange: MultiRangeSelectionRange | null;
  activeIndex: number;
};
```

---

### `MultiRangeSelectionOrigin`

Identifies plugin-owned selection behavior without changing core ranges.

```ts
/** Identifies plugin-owned selection behavior without changing core ranges. */
export type MultiRangeSelectionOrigin = 'row-header' | null;
```

---

### `MultiRangeSelectionRange`

One selected range in a concrete RevoGrid row and column viewport.

Coordinates are local to the `rowType`/`colType` viewport stores.

```ts
/**
 * One selected range in a concrete RevoGrid row and column viewport.
 *
 * Coordinates are local to the `rowType`/`colType` viewport stores.
 */
export type MultiRangeSelectionRange = {
  rowType: DimensionRows;
  colType: DimensionCols;
  range: RangeArea;
};
```

---

### `MultiRangeRowHeaderProvider`

Runtime contract used when row-header selection replaces cell selection.

```ts
interface MultiRangeRowHeaderProvider {
  clearFromRowHeader(): void
}
```

---

### `MultiRangeSelectAllProvider`

Runtime contract used when select-all replaces plugin-owned row/column state.

```ts
interface MultiRangeSelectAllProvider {
  clearFromSelectAll(): void
}
```

---

### `buildMultiRangeClipboardData`

Builds text/html/custom clipboard output for the current multi-range
selection.

Ranges are first converted from viewport-local coordinates to whole-grid
visual coordinates, so pinned and regular selections preserve their copied
pattern when pasted into a regular viewport.

```ts
export function buildMultiRangeClipboardData(
  ranges: MultiRangeSelectionRange[],
  providers: PluginProviders,
  options: MultiRangeClipboardOptions = {},
): MultiRangeClipboardData | null;
```

---

### `MULTI_RANGE_CLIPBOARD_MIME`

Custom clipboard MIME type used to preserve sparse multi-range metadata for
RevoGrid-aware paste handlers while still writing standard text/html data.

```ts
MULTI_RANGE_CLIPBOARD_MIME: string;
```

---

### `MultiRangeClipboardData`

Serialized clipboard data for a multi-range copy operation.

`sparse` mode preserves the relative row/column gaps between selected cells.
`blocks` mode serializes each range as an independent table when sparse
output is disabled or exceeds configured limits.

```ts
/**
 * Serialized clipboard data for a multi-range copy operation.
 *
 * `sparse` mode preserves the relative row/column gaps between selected cells.
 * `blocks` mode serializes each range as an independent table when sparse
 * output is disabled or exceeds configured limits.
 */
export type MultiRangeClipboardData = {
  text: string;
  html: string;
  mode: 'sparse' | 'blocks';
  payload?: MultiRangeClipboardPayload;
};
```

---

### `MultiRangeClipboardPayload`

Structured representation of a sparse multi-range copy.

The payload keeps only selected cells plus the final clipboard dimensions,
allowing RevoGrid-aware consumers to distinguish intentionally empty cells
from cells that were never selected.

```ts
/**
 * Structured representation of a sparse multi-range copy.
 *
 * The payload keeps only selected cells plus the final clipboard dimensions,
 * allowing RevoGrid-aware consumers to distinguish intentionally empty cells
 * from cells that were never selected.
 */
export type MultiRangeClipboardPayload = {
  width: number;
  height: number;
  cells: MultiRangeClipboardCell[];
};
```

---

### `MultiRangeClipboardOptions`

Options controlling multi-range clipboard serialization.

```ts
/**
 * Options controlling multi-range clipboard serialization.
 */
export type MultiRangeClipboardOptions = {
  /** Maximum cells allowed in the sparse bounding box before using blocks. */
  maxSparseCells?: number;
  /**
   * Maximum sparse bounding-box expansion over selected cell count.
   *
   * Defaults to no expansion limit so copied patterns are preserved until
   * `maxSparseCells` is exceeded.
   */
  maxSparseExpansion?: number;
  /** Whether disjoint selections should keep their relative empty gaps. */
  preserveSparseGaps?: boolean;
  /** Converts cell values into clipboard-safe text before text/html output. */
  serializeValue?: (value: unknown) => string;
};
```

---

### `normalizeMultiTablePasteData`

Normalizes paste data from multi-table HTML clipboard content.

Some clipboard parsers flatten multiple HTML tables poorly. When the raw HTML
contains multiple tables and the parser did not already produce structured
values, this falls back to the plain text matrix that browsers place on the
clipboard alongside HTML.

```ts
export function normalizeMultiTablePasteData({
  raw,
  dataText,
  parsed,
  isHTML,
}: {
  raw?: string;
  dataText?: string;
  parsed: unknown[][];
  isHTML?: boolean;
});
```

---

### `buildMultiRangeClearEdits`

Builds `rangeeditapply` payloads that clear all selected multi-range cells.

Ranges are grouped by row viewport type because RevoGrid edit events apply to
one data store at a time.

```ts
export function buildMultiRangeClearEdits(
  ranges: MultiRangeSelectionRange[],
  providers: PluginProviders,
  value: DataFormat = '',
  options: MultiRangeClearOptions = {},
): MultiRangeClearEdit[] | null;
```

---

### `MultiRangeClipboardPlugin`

Clipboard companion for {@link MultiRangeSelectionPlugin}.

Keeps multi-range copy and paste behavior separate from selection state:
it serializes all selected ranges and normalizes RevoGrid multi-table HTML
paste back to the complete text payload.

#### Dependencies

- **Event integration** `CLIPBOARD_COPY_EVENT`, `CLIPBOARD_PASTE_EVENT`: Listens to RevoGrid clipboard events to copy and paste multi-range selections.

```ts
class MultiRangeClipboardPlugin {
  /**
     * Connects this companion to the active multi-range selection source.
     * Host-created instances are registered before the selection plugin exists,
     * so the adapter must be replaceable after construction.
     */
  setSelectedRangesAdapter(getSelectedRanges?: () => MultiRangeSelectionRange[]);

  /** Applies the selected cells of a rich sparse document without filling its gaps. */
  applySparsePayload(
    payload: MultiRangeClipboardPayload,
    operationId = createClipboardOperationId(),
  ): SparseClipboardApplyResult;
}
```

---

### `MultiRangeCrossViewportAutoFillPlugin`

Coordinates cross-viewport autofill preview and commit behavior.

```ts
class MultiRangeCrossViewportAutoFillPlugin {
  /**
     * Updates the final selection callback supplied by `MultiRangeSelectionPlugin`.
     */
  setSelectionAdapter(
    setSelectedRanges: MultiRangeCrossViewportAutoFillPluginOptions['setSelectedRanges'],
  );

  /**
     * Enables or disables cross-viewport gesture handling without removing the
     * auto-installed companion plugin.
     */
  setEnabled(enabled: boolean);

  /**
     * Starts or updates a cross-viewport session from core temporary autofill
     * range events.
     */
  handleBeforeTempRange(
    event: CustomEvent<HTMLRevogrOverlaySelectionElementEventMap['beforesettemprange']>,
  );

  /**
     * Intercepts core selection commit only when a cross-viewport result exists,
     * then commits segmented edits instead of a single clamped range.
     */
  handleSelectionChangeInit(event: Event);

  /**
     * Lets native mouseup reset its drag state while preventing the clamped
     * same-viewport range from becoming the final selection.
     */
  handleBeforeApplyRange(event: Event);

  /**
     * Lets the preview controller inject generated values into visible cells.
     */
  handleBeforeCellRender(
    event: CustomEvent<HTMLRevogrDataElementEventMap['beforecellrender']>,
  );

  /**
     * Clears any active session after source data changes.
     */
  handleAfterSource();

  /**
     * Releases preview state and active session data.
     */
  destroy();
}
```

---

### `multiRangeSelectionPluginDependencies`

#### Dependencies

- **Auto-installed** `MultiRangeClipboardPlugin`: Installs MultiRangeClipboardPlugin internally for multi-range copy and paste behavior.
- **Auto-installed** `MultiRangeCrossViewportAutoFillPlugin`: Installs MultiRangeCrossViewportAutoFillPlugin internally for drag autofill across pinned and main viewports.
- **Event integration** `MultiRangeClipboardPlugin`: Delegates multi-range clipboard serialization and paste normalization to MultiRangeClipboardPlugin.
- **Event integration** `MultiRangeCrossViewportAutoFillPlugin`: Delegates cross-viewport autofill preview and commit handling to MultiRangeCrossViewportAutoFillPlugin.
- **Config integration** `additionalData.multiRangeSelection`: Reads legacy multi-range selection configuration from additionalData.multiRangeSelection.

```ts
multiRangeSelectionPluginDependencies: PluginDependency[];
```

---

### `MultiRangeSelectionPlugin`

Enables spreadsheet-like multi-range cell selection in RevoGrid Pro.

Ctrl/Cmd+click stores the current active range and starts a new active range.
Shift interactions keep extending the active core range. Additional inactive
ranges are rendered by this plugin and included in multi-range copy output.

```ts
class MultiRangeSelectionPlugin {
  /**
     * Returns all selected ranges, including inactive ranges and the current core
     * active range.
     */
  getSelectedRanges(): MultiRangeSelectionRange[];

  /**
     * Replaces all selected ranges and applies one range as the active core
     * selection.
     */
  setSelectedRanges(
    ranges: MultiRangeSelectionRange[],
    activeIndex = ranges.length - 1,
    selectionOrigin: MultiRangeSelectionOrigin = null,
  );

  /**
     * Replaces selected ranges while keeping only a focus marker in the requested
     * viewport. Used for plugin-owned cross-viewport selection where the source
     * cell must keep focus without leaving an active expanded core range.
     */
  setSelectedRangesWithFocus(
    ranges: MultiRangeSelectionRange[],
    focusRange: MultiRangeSelectionRange,
  );

  /**
     * Clears inactive multi-range state and the current core selection.
     */
  clearSelectedRanges();

  /** Clears cell ranges before an interactive row header applies whole-row selection. */
  clearFromRowHeader();

  /**
     * Removes plugin state, visual classes, controllers, and event listeners.
     */
  destroy();
}
```

---

### `normalizeMultiRangeSelectionConfig`

Converts the public boolean/object config into the internal normalized form.

```ts
export function normalizeMultiRangeSelectionConfig(
  config?: MultiRangeSelectionConfig,
): NormalizedMultiRangeSelectionConfig;
```

---

### `isSameMultiRangeSelectionConfig`

Compares normalized configs so observable config updates can skip no-op work.

```ts
export function isSameMultiRangeSelectionConfig(
  previous: NormalizedMultiRangeSelectionConfig,
  next: NormalizedMultiRangeSelectionConfig,
);
```

---

### `MultiRangeSelectionOptions`

Object form of the multi-range selection configuration.

```ts
/**
 * Object form of the multi-range selection configuration.
 */
export type MultiRangeSelectionOptions = {
  /**
   * Enables autofill gestures across pinned/main viewport boundaries.
   *
   * The integration fills only visible viewport-scoped target segments and
   * represents the final result as multi-range selection.
   */
  crossViewportAutofill?: boolean;
};
```

---

### `MultiRangeSelectionConfig`

Public grid property shape for enabling multi-range selection options.

`true` enables the plugin with default optional integrations.

```ts
/**
 * Public grid property shape for enabling multi-range selection options.
 *
 * `true` enables the plugin with default optional integrations.
 */
export type MultiRangeSelectionConfig = boolean | MultiRangeSelectionOptions;
```

---

### `NormalizedMultiRangeSelectionConfig`

Internal normalized configuration used by the plugin runtime.

```ts
/**
 * Internal normalized configuration used by the plugin runtime.
 */
export type NormalizedMultiRangeSelectionConfig = {
  crossViewportAutofill: boolean;
};
```

---

### `normalizeSelectionRange`

Normalizes the coordinate bounds of a viewport-scoped selection.

```ts
export function normalizeSelectionRange(
  selection: MultiRangeSelectionRange,
): MultiRangeSelectionRange;
```

---

### `cloneSelectionRange`

Creates a clone of a viewport-scoped selection range.

```ts
export function cloneSelectionRange(
  selection: MultiRangeSelectionRange,
): MultiRangeSelectionRange;
```

---

### `rangeKey`

Builds a stable identity key for a normalized viewport-scoped range.

```ts
export function rangeKey(selection: MultiRangeSelectionRange);
```

---

### `dedupeRanges`

Normalizes ranges and removes duplicate viewport/range entries.

```ts
export function dedupeRanges(
  ranges: MultiRangeSelectionRange[],
): MultiRangeSelectionRange[];
```

---

### `sortRanges`

Returns ranges in deterministic viewport and row-major order.

```ts
export function sortRanges(
  ranges: MultiRangeSelectionRange[],
): MultiRangeSelectionRange[];
```

---

### `isCellInRange`

Checks whether a viewport-local cell coordinate is inside a range.

```ts
export function isCellInRange(cell: Cell, range: RangeArea);
```

---

### `findRangeForCell`

Finds the first range that contains the given viewport-scoped cell.

```ts
export function findRangeForCell(
  cell: MultiRangeSelectionCell,
  ranges: MultiRangeSelectionRange[],
);
```

---

### `getRangeBounds`

Computes the bounding box that contains all provided range coordinates.

```ts
export function getRangeBounds(ranges: MultiRangeSelectionRange[]): RangeArea | null;
```

---

### `groupRangesByDimension`

Groups ranges by their row and column viewport type pair.

```ts
export function groupRangesByDimension(ranges: MultiRangeSelectionRange[]);
```

---

### `getInactiveRangeCellClasses`

Builds the class map required to render inactive range body and edge styles
for a concrete cell.

```ts
export function getInactiveRangeCellClasses(
  cell: MultiRangeSelectionCell,
  selection: MultiRangeSelectionRange,
);
```

---

### `moveCellWithinRange`

Resolves the next focus cell inside a range for Tab or Enter traversal.

```ts
export function moveCellWithinRange(
  range: RangeArea,
  focus: Cell,
  key: string,
  backwards = false,
): Cell | null;
```

---

### `cloneRange`

Creates a shallow copy of a range.

```ts
export function cloneRange(range: Readonly<RangeArea>): RangeArea;
```

---

### `isSingleCellRange`

Checks whether a range contains exactly one cell.

```ts
export function isSingleCellRange(range: Readonly<RangeArea>): boolean;
```

---

### `normalizeRange`

Returns a range with its start coordinates at the minimum bounds and its end
coordinates at the maximum bounds.

```ts
export function normalizeRange(range: Readonly<RangeArea>): RangeArea;
```

---

### `rangeCellCount`

Counts cells covered by a possibly reversed range.

```ts
export function rangeCellCount(range: Readonly<RangeArea>): number;
```

---

### `MULTI_RANGE_SELECTION_GRID_CLASS`

Grid host class added while multi-range selection is active.

```ts
MULTI_RANGE_SELECTION_GRID_CLASS: string;
```

---

### `MULTI_RANGE_SELECTION_CELL_CLASS`

Cell class applied to inactive selected ranges.

```ts
MULTI_RANGE_SELECTION_CELL_CLASS: string;
```

---

### `MULTI_RANGE_SELECTION_ATTR`

Cell attribute applied to inactive selected ranges for styling hooks.

```ts
MULTI_RANGE_SELECTION_ATTR: string;
```

---

### `MULTI_RANGE_SELECTION_EDGE_TOP_CLASS`

Edge class applied to the top side of an inactive range.

```ts
MULTI_RANGE_SELECTION_EDGE_TOP_CLASS: string;
```

---

### `MULTI_RANGE_SELECTION_EDGE_RIGHT_CLASS`

Edge class applied to the right side of an inactive range.

```ts
MULTI_RANGE_SELECTION_EDGE_RIGHT_CLASS: string;
```

---

### `MULTI_RANGE_SELECTION_EDGE_BOTTOM_CLASS`

Edge class applied to the bottom side of an inactive range.

```ts
MULTI_RANGE_SELECTION_EDGE_BOTTOM_CLASS: string;
```

---

### `MULTI_RANGE_SELECTION_EDGE_LEFT_CLASS`

Edge class applied to the left side of an inactive range.

```ts
MULTI_RANGE_SELECTION_EDGE_LEFT_CLASS: string;
```

---

### `MultiRangeClipboardPluginOptions`

Dependencies supplied by the owning multi-range selection plugin.

```ts
/**
 * Dependencies supplied by the owning multi-range selection plugin.
 */
export type MultiRangeClipboardPluginOptions = {
  /** Returns the current selected ranges when a copy event is handled. */
  getSelectedRanges?: () => MultiRangeSelectionRange[];
};
```

---

### `SparseClipboardApplyResult`

```ts
export type SparseClipboardApplyResult = {
  /** At least one writable destination cell was resolved, so native fallback must not run. */
  handled: boolean;
  /** Every emitted range edit was accepted by the native edit pipeline. */
  accepted: boolean;
  /** Correlates EventManager completion with rich clipboard metadata. */
  operationId: string;
  /** Number of row-store edit groups emitted for this operation. */
  eventCount: number;
};
```

---

### `markClipboardDataAuthoritative`

Marks a clipboard event whose supplied data matrix already owns the copy
operation. Context-menu commands use this so ambient multi-range state does
not replace an explicitly requested row, column, or cell matrix.

```ts
export function markClipboardDataAuthoritative(event: Event);
```

---

### `isClipboardDataAuthoritative`

Returns whether a copy event carries an authoritative caller-owned matrix.

```ts
export function isClipboardDataAuthoritative(event: Event);
```

---

### `MultiRangeClipboardCell`

One copied cell inside the sparse multi-range clipboard payload.

`row` and `col` are zero-based offsets inside the normalized clipboard
bounding box, not viewport-local grid coordinates.

```ts
/**
 * One copied cell inside the sparse multi-range clipboard payload.
 *
 * `row` and `col` are zero-based offsets inside the normalized clipboard
 * bounding box, not viewport-local grid coordinates.
 */
export type MultiRangeClipboardCell = {
  row: number;
  col: number;
  value: unknown;
};
```

---

### `buildCrossViewportAutoFillTarget`

Builds the final visible target segment for a source/target drag pair.

```ts
export function buildCrossViewportAutoFillTarget(
  source: MultiRangeSelectionRange,
  target: MultiRangeSelectionRange,
  providers: Pick<PluginProviders, 'viewport'>,
  visibleIndexes?: CrossViewportAutoFillVisibleIndexes,
): CrossViewportAutoFillTarget | null;
```

---

### `buildCrossViewportAutoFillTargets`

Splits a cross-viewport drag into visible viewport-scoped target ranges.

V1 supports one changed axis only. Diagonal changes that alter both row and
column viewport types return no targets so core autofill can remain clamped.

```ts
export function buildCrossViewportAutoFillTargets(
  source: MultiRangeSelectionRange,
  target: MultiRangeSelectionRange,
  providers: Pick<PluginProviders, 'viewport'>,
  visibleIndexes?: CrossViewportAutoFillVisibleIndexes,
): CrossViewportAutoFillTarget[];
```

---

### `computeCrossViewportAutoFillData`

Computes edit data for visible cross-viewport autofill targets.

Strategies receive a synthetic continuous range so existing autofill
algorithms can continue sequences across visible segments, while mapping back
never includes hidden scroll-gap rows or columns.

```ts
export function computeCrossViewportAutoFillData({
  source,
  targets,
  providers,
  strategies,
  transformers = [],
}: CrossViewportAutoFillComputeOptions): CrossViewportAutoFillResult | null;
```

---

### `cellToSelection`

Converts a focused cell address into a single-cell selection range.

```ts
export function cellToSelection(cell: Cell & {
  rowType: DimensionRows;
  colType: DimensionCols;
}): MultiRangeSelectionRange;
```

---

### `CrossViewportAutoFillMode`

Axis that crosses viewport types during one autofill gesture.

```ts
/**
 * Axis that crosses viewport types during one autofill gesture.
 */
export type CrossViewportAutoFillMode = 'row' | 'column';
```

---

### `CrossViewportAutoFillTarget` (Extended from `cross-viewport-autofill.compute.ts`)

One visible target segment for a cross-viewport autofill gesture.

```ts
/**
 * One visible target segment for a cross-viewport autofill gesture.
 */
export type CrossViewportAutoFillTarget = MultiRangeSelectionRange & {
  direction: AutoFillDirection;
};
```

---

### `CrossViewportAutoFillVisibleIndexes`

Test or integration override for visible row/column indexes by viewport type.

```ts
/**
 * Test or integration override for visible row/column indexes by viewport type.
 */
export type CrossViewportAutoFillVisibleIndexes = Partial<Record<
  DimensionRows | DimensionCols,
  { start: number; end: number }
>>;
```

---

### `CrossViewportAutoFillComputeOptions`

Inputs required to compute autofill data across viewport boundaries.

```ts
/**
 * Inputs required to compute autofill data across viewport boundaries.
 */
export type CrossViewportAutoFillComputeOptions = {
  source: MultiRangeSelectionRange;
  targets: CrossViewportAutoFillTarget[];
  providers: PluginProviders;
  strategies: AutoFillStrategy[];
  transformers?: readonly AutoFillResultTransformer[];
};
```

---

### `CrossViewportAutoFillSegment`

One editable data segment generated for a visible target range.

```ts
/**
 * One editable data segment generated for a visible target range.
 */
export type CrossViewportAutoFillSegment = {
  selection: MultiRangeSelectionRange;
  data: DataLookup;
  models: Partial<DataLookup>;
};
```

---

### `CrossViewportAutoFillResult`

Full computed cross-viewport autofill result.

```ts
/**
 * Full computed cross-viewport autofill result.
 */
export type CrossViewportAutoFillResult = {
  source: MultiRangeSelectionRange;
  targets: CrossViewportAutoFillTarget[];
  segments: CrossViewportAutoFillSegment[];
};
```

---

### `isAutofillHandleEvent`

Checks whether the original event path started from a core autofill handle.

```ts
export function isAutofillHandleEvent(event: MouseEvent);
```

---

### `resolveRenderedCellAt`

Resolves the visible cell at viewport coordinates through browser hit-test.
The geometry fallback is intentionally ephemeral for this compatibility API;
active gestures should reuse `RenderedCellResolver` below.

```ts
export function resolveRenderedCellAt(
  revogrid: HTMLRevoGridElement,
  clientX: number,
  clientY: number,
): MultiRangeSelectionRange | null;
```

---

### `RenderedCellResolver`

Reusable pointer resolver for one plugin lifecycle.

Normal browsers resolve a cell without explicit layout reads. If browser hit
testing is unavailable, rendered-cell and clipping-ancestor geometry is read
once and reused until scroll/resize invalidates it.

```ts
class RenderedCellResolver {
  /** Resolves a cell from the dispatched target path before coordinate lookup. */
  resolveEvent(event: MouseEvent): MultiRangeSelectionRange | null;

  /** Resolves only the event path, without triggering fallback layout reads. */
  resolveEventTarget(event: MouseEvent): MultiRangeSelectionRange | null;

  /** Resolves a cell at pointer coordinates with a cached fallback. */
  resolveAt({ clientX, clientY }: PointerCoordinates): MultiRangeSelectionRange | null;

  /**
     * Resolves visible provider indexes from viewport-container geometry.
     * This measures a bounded number of data/clipping containers rather than
     * every rendered cell and reuses the result until scroll/resize invalidates it.
     */
  resolveVisibleIndexes(
    providers: Pick<PluginProviders, 'viewport'>,
  ): CrossViewportAutoFillVisibleIndexes;

  /** Invalidates fallback geometry after scroll or resize. */
  invalidate();

  destroy();
}
```

---

### `CrossViewportAutoFillPreviewController`

Renders and refreshes cross-viewport autofill preview cells.

```ts
class CrossViewportAutoFillPreviewController {
  /**
     * Injects preview value and styling into a rendered target cell.
     */
  renderCell(
    event: CustomEvent<HTMLRevogrDataElementEventMap['beforecellrender']>,
    result: CrossViewportAutoFillResult | null,
    showPreviewValues = true,
    renderRanges: MultiRangeSelectionRange[] | boolean = false,
    dashedRange = false,
    autofillRange = false,
  );

  /**
     * Replaces the active preview result and schedules refresh for changed cells.
     */
  setResult(
    result: CrossViewportAutoFillResult | null,
    renderRanges: MultiRangeSelectionRange[] | boolean = false,
  );

  /**
     * Cancels pending refresh work and clears tracked preview cells.
     */
  destroy();
}
```

---

### `buildSourceViewportOrthogonalTarget`

Builds the source-viewport part of a diagonal cross-viewport autofill target.

```ts
export function buildSourceViewportOrthogonalTarget({
  source,
  target,
  rowChanged,
  colChanged,
  visibleIndexes,
  direction,
}: {
  source: MultiRangeSelectionRange;
  target: MultiRangeSelectionRange;
  rowChanged: boolean;
  colChanged: boolean;
  visibleIndexes?: CrossViewportAutoFillVisibleIndexes;
  direction: CrossViewportAutoFillTarget['direction'];
}): CrossViewportAutoFillTarget | null;
```

---

### `getFinalSelectionRanges`

Builds final selected ranges while folding source-viewport fill extensions
into the visual source range.

```ts
export function getFinalSelectionRanges(
  result: CrossViewportAutoFillResult,
): MultiRangeSelectionRange[];
```

---

### `getPreviewRenderRanges`

Builds the visual temporary ranges. Value previews still come only from
generated edit segments; these ranges define ghost styling and edges.

```ts
export function getPreviewRenderRanges(
  result: CrossViewportAutoFillResult,
): MultiRangeSelectionRange[];
```

---

### `MultiRangeCrossViewportAutoFillPluginOptions`

Options supplied by `MultiRangeSelectionPlugin`.

```ts
/**
 * Options supplied by `MultiRangeSelectionPlugin`.
 */
export type MultiRangeCrossViewportAutoFillPluginOptions = {
  /** Applies source and target segments as the final multi-range selection. */
  setSelectedRanges?: (
    ranges: MultiRangeSelectionRange[],
    activeIndex?: number,
    options?: { focusRange?: MultiRangeSelectionRange },
  ) => void;
  /** Enables cross-viewport gesture handling. */
  enabled?: boolean;
};
```

---

### `MultiRangeClearEdit` (Extended from `edit.ts`)

```ts
export type MultiRangeClearEdit = BeforeRangeSaveDataDetails & {
  selectionOrigin?: 'row-header';
  /** Exact selected column occurrences keyed by visible row and data prop. */
  selectedColumns?: Record<number, Record<string, ColumnRegular[]>>;
};
```

---

### `MultiRangeClearOptions`

```ts
export type MultiRangeClearOptions = {
  selectionOrigin?: 'row-header';
  skipStrictValidation?: boolean;
};
```

---

### `handleMultiRangeSelectionKeyDown`

Handles multi-range keyboard behavior before core selection navigation.

```ts
export function handleMultiRangeSelectionKeyDown(
  event: MultiRangeSelectionKeyDownEvent,
  context: MultiRangeSelectionKeyboardContext,
);
```

---

### `buildWholeGridRanges`

```ts
export function buildWholeGridRanges(
  providers: PluginProviders,
): MultiRangeSelectionRange[];
```

---

### `MultiRangeSelectionKeyboardContext`

```ts
export type MultiRangeSelectionKeyboardContext = {
  revogrid: HTMLRevoGridElement;
  providers: PluginProviders;
  isReadOnly(): boolean;
  getActiveRange(): MultiRangeSelectionRange | null;
  getSelectedRanges(): MultiRangeSelectionRange[];
  getSelectionOrigin(): MultiRangeSelectionOrigin;
  clearSelectionOwners(): void;
  clearInactiveRanges(): void;
  setSelectedRanges(ranges: MultiRangeSelectionRange[], activeIndex?: number): void;
  emitRangeEditApply(detail: BeforeRangeSaveDataDetails): void;
  emitChange(): void;
};
```

---

### `createCellSchema`

```ts
export function createCellSchema({
  rowIndex,
  colIndex,
  rowType,
  colType,
  rowSource,
  model,
  column,
}: {
  rowIndex: number;
  colIndex: number;
  rowType: DimensionRows;
  colType: DimensionCols;
  rowSource: DataType[];
  model: DataType;
  column: ColumnRegular;
}): ColumnDataSchemaModel;
```

---

### `isReadOnlyColumn`

```ts
export function isReadOnlyColumn(
  column: ColumnRegular,
  schema: ColumnDataSchemaModel,
);
```

---

### `MultiRangeSelectionCell`

A cell address with explicit row and column viewport ownership.

```ts
/**
 * A cell address with explicit row and column viewport ownership.
 */
export type MultiRangeSelectionCell = {
  row: number;
  col: number;
  rowType: DimensionRows;
  colType: DimensionCols;
};
```

---

### `getColumnTypeOffset`

Returns the whole-grid visual offset of a column viewport.

```ts
export function getColumnTypeOffset(
  type: DimensionCols,
  providers: PluginProviders,
);
```

---

### `getRowTypeOffset`

Returns the whole-grid visual offset of a row viewport.

```ts
export function getRowTypeOffset(
  type: DimensionRows,
  providers: PluginProviders,
);
```

---

### `resolveRowViewportCoordinate`

Resolves a row offset across pinned and main row viewports.

```ts
export function resolveRowViewportCoordinate(
  providers: PluginProviders,
  sourceType: DimensionRows,
  sourceIndex: number,
  offset: number,
);
```

---

### `resolveColumnViewportCoordinate`

Resolves a column offset across pinned and main column viewports.

```ts
export function resolveColumnViewportCoordinate(
  providers: PluginProviders,
  sourceType: DimensionCols,
  sourceIndex: number,
  offset: number,
);
```

---

### `resolveViewportCellAddress`

Resolves a cell offset across pinned and main row/column viewports.

```ts
export function resolveViewportCellAddress(
  providers: PluginProviders,
  start: ViewportCellAddress,
  rowOffset: number,
  colOffset: number,
): ViewportCellAddress | null;
```

---

### `resolveViewportCell`

Resolves a provider-backed cell at an offset, including store item mappings.
Grouping rows and missing row/column destinations are not editable cells.

```ts
export function resolveViewportCell<T extends DataType = DataType>(
  providers: PluginProviders,
  start: ViewportCellAddress,
  rowOffset: number,
  colOffset: number,
): ResolvedViewportCell<T> | null;
```

---

### `getStoreSource`

Reads a typed source array from a provider store.

```ts
export function getStoreSource<T>(
  store: StoreLike,
);
```

---

### `getStoreItems`

Reads a store item map or creates the identity mapping.

```ts
export function getStoreItems<T>(
  store: StoreLike,
  source: T[],
);
```

---

### `ViewportCoordinate`

```ts
export type ViewportCoordinate<T extends string> = {
  type: T;
  index: number;
};
```

---

### `ViewportCellAddress`

```ts
export type ViewportCellAddress = {
  rowType: DimensionRows;
  colType: DimensionCols;
  rowIndex: number;
  colIndex: number;
};
```

---

### `ResolvedViewportCell` (Extended from `viewport-coordinates.ts`)

```ts
export type ResolvedViewportCell<T extends DataType = DataType> = ViewportCellAddress & {
  model: T;
  column: ColumnRegular;
};
```

---

# Multi Row Header

URL: https://pro.rv-grid.com/api/multi-row-header/
Source: src/content/docs/api/multi-row-header.md

## Module Extensions

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  multiRowHeader?: MultiRowHeaderConfig
}
```

---

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Fill unused multi-row header depth for this leaf even when global leaf
       * spanning is disabled.
       */
      spanHeaderHeight?: boolean;
  /**
       * Prevent this leaf header from spanning unused multi-row header depth.
       */
      suppressSpanHeaderHeight?: boolean
}
```

---

### `ColumnGrouping` (Extended from `@revolist/revogrid`)

```ts
interface ColumnGrouping {
  /**
       * Fill the remaining grouped-header depth with this group header when
       * `MultiRowHeaderPlugin` is enabled.
       */
      spanHeaderHeight?: boolean
}
```

---

### `Group` (Extended from `@revolist/revogrid`)

```ts
interface Group {
  /**
       * Runtime column-group counterpart of `ColumnGrouping.spanHeaderHeight`.
       */
      spanHeaderHeight?: boolean
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  multiRowHeader?: MultiRowHeaderConfig;
  'multi-row-header'?: MultiRowHeaderConfig
}
```

## Plugin API

### `MultiRowHeaderPlugin`

Enhances RevoGrid grouped column headers with AG Grid / DevExtreme-style
multi-row leaf header spanning while keeping the existing ColumnGrouping API.

#### Dependencies

- **Config integration** `grid.multiRowHeader`: Reads multi-row header configuration from the grid multiRowHeader DOM property.
- **Config integration** `additionalData.multiRowHeader`: Reads legacy multi-row header configuration from additionalData.multiRowHeader.

```ts
class MultiRowHeaderPlugin {
  destroy(): void;
}
```

---

### `getMultiRowHeaderLeafKey`

```ts
export function getMultiRowHeaderLeafKey(
  colType: DimensionCols,
  columnIndex: number,
): string;
```

---

### `createMultiRowHeaderLayout`

```ts
export function createMultiRowHeaderLayout(
  columns: MultiRowHeaderColumn[] = [],
): MultiRowHeaderLayout;
```

---

### `resolveMultiRowHeaderConfig`

```ts
export function resolveMultiRowHeaderConfig(
  config?: MultiRowHeaderConfig,
): ResolvedMultiRowHeaderConfig;
```

---

### `MultiRowHeaderConfig`

```ts
export type MultiRowHeaderConfig = boolean | {
  /**
   * Let shallow leaf headers fill unused group header depth.
   * Defaults to true.
   */
  spanLeafHeaders?: boolean;
};
```

---

### `ResolvedMultiRowHeaderConfig`

```ts
export type ResolvedMultiRowHeaderConfig = {
  enabled: boolean;
  spanLeafHeaders: boolean;
};
```

---

### `MultiRowHeaderColumn`

```ts
export type MultiRowHeaderColumn = ColumnRegular | ColumnGrouping;
```

---

### `MultiRowHeaderLeafInfo`

```ts
export type MultiRowHeaderLeafInfo = {
  colType: DimensionCols;
  columnIndex: number;
  depth: number;
  spanRows: number;
  spanHeaderHeight: boolean;
  suppressSpanHeaderHeight: boolean;
  coveredByGroupSpan: boolean;
};
```

---

### `MultiRowHeaderLayout`

```ts
export type MultiRowHeaderLayout = {
  maxDepth: number;
  maxDepthByType: Record<DimensionCols, number>;
  leaves: Map<string, MultiRowHeaderLeafInfo>;
};
```

---

# Observable Props

URL: https://pro.rv-grid.com/api/observable-props/
Source: src/content/docs/api/observable-props.md

### `bindObservableProp`

```ts
export function bindObservableProp<TInput, TValue = TInput>(
  plugin: ObservablePropHost,
  options: ObservablePropBindingOptions<TInput, TValue>,
): TValue;
```

---

### `ObservablePropHost`

```ts
interface ObservablePropHost {
  revogrid: HTMLRevoGridElement;
  addEventListener(eventName: any, callback: (event: CustomEvent<any>) => void): void
}
```

---

### `ObservablePropSource`

```ts
export type ObservablePropSource = 'initial' | 'property' | 'additionalData';
```

---

### `ObservablePropBindingOptions`

```ts
interface ObservablePropBindingOptions {
  prop: string;
  propAliases?: string[];
  additionalDataKey?: keyof AdditionalData & string;
  additionalDataAliases?: (keyof AdditionalData & string)[];
  defaultValue?: TInput;
  map?: (value: TInput | undefined, source: ObservablePropSource) => TValue;
  equals?: (previous: TValue, next: TValue) => boolean;
  apply?: (value: TValue, source: ObservablePropSource) => void
}
```

---

# Overlay

URL: https://pro.rv-grid.com/api/overlay/
Source: src/content/docs/api/overlay.md

## Module Extensions

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  overlaynode: OverlayRegisterEvent;
  overlayclearnode: OverlayUnRegisterEvent
}
```

## Plugin API

### `OverlayPlugin`

`OverlayPlugin`, a plugin for RevoGrid that manages overlay content
within the grid environment. It provides mechanisms to render, position, and update overlay elements
dynamically based on grid events and interactions.

**Key Features**:
- **Dynamic Overlay Management**: Utilizes virtual nodes (`VNode`) to manage overlay content, allowing
  for flexible rendering and updating of overlay elements as grid data or layout changes.
- **Position and Size Calculations**: Calculates and sets the position and height of overlay elements
  relative to grid scroll and dimension changes, ensuring overlays are correctly aligned with grid content.
- **Event Handling**: Listens for and responds to various grid events such as scroll, node updates,
  and dimension changes, refreshing overlay content and adjusting positions as needed.
- **Debounced Refreshing**: Integrates debouncing to optimize performance by reducing unnecessary
  updates during rapid event sequences.

**Usage**:
- Integrate this plugin into a RevoGrid instance to enable advanced overlay management, enhancing
  the ability to display additional, context-sensitive information or controls over grid content.

### Example
```typescript
import { OverlayPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [OverlayPlugin];
```

The `OverlayPlugin` is essential for applications that require dynamic and context-aware overlay
content within RevoGrid, providing a robust solution for managing additional grid features or
information layers.

#### Dependencies

- **Event integration** `overlay-producer`: Renders overlay nodes emitted through overlay registration events.

```ts
class OverlayPlugin {
  destroy();
}
```

---

### `OverlayRegisterEvent`

```ts
export type OverlayRegisterEvent = {
  nodeId: string;
  vnode: ReturnType<typeof h>;
};
```

---

### `OverlayUnRegisterEvent`

```ts
export type OverlayUnRegisterEvent = {
  nodeIds: string[];
};
```

---

# Pagination

URL: https://pro.rv-grid.com/api/pagination/
Source: src/content/docs/api/pagination.md

## Module Extensions

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [PAGE_CHANGE_EVENT]: PageChangeEvent
}
```

---

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  /**
       * Direct pagination configuration.
       */
      pagination?: Partial<PaginationFullConfig>
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * @deprecated Use `grid.pagination` instead.
       */
      pagination?: Partial<PaginationFullConfig>
}
```

## Plugin API

### `PaginationPlugin`

#### Dependencies

- **Optional** `sorting-capable-plugin`: Integrates with a plugin exposing sorting state for remote pagination sorting.
- **Event integration** `beforefilterapply`, `beforequickfilterapply`, `beforesortingapply`, `beforesourcesortingapply`: Integrates with filter and quick-filter events to forward remote filter state to loadData.

```ts
class PaginationPlugin {
  setConfig(config: Partial<PaginationConfig & PaginationPanelConfig> | undefined);

  setPage(page: number, emitChange = true);
}
```

---

### `PaginationLoadDataResult`

```ts
interface PaginationLoadDataResult {
  data: T[];
  count?: number;
  total?: number
}
```

---

### `PaginationLoadData`

```ts
export type PaginationLoadData<T = any> = (
  /** Number of remote rows to skip. */
  skip: number,
  /** Number of remote rows to request. */
  take: number,
  /** Current remote sorting state. */
  order?: SortingOrder,
  /** Backward-compatible model containing at most the first filter condition per column. */
  singleConditionFilters?: Record<ColumnProp, FilterCollectionItem>,
  /** Complete advanced filter model, including every same-column condition and relation. */
  multiConditionFilters?: MultiFilterItem,
  /** Normalized global quick-filter payload. */
  quickFilter?: QuickFilter,
  /** Resolved temporal semantics for this request. */
  temporalContext?: TemporalFilterContext,
  /** Canonical filter tree, including nested groups and custom structured operators. */
  filterAst?: FilterAst,
  /** Captured clock and timezone context used to evaluate the canonical tree. */
  executionContext?: FilterExecutionContext,
) => Promise<T[] | PaginationLoadDataResult<T>>;
```

---

### `PaginationConfig`

```ts
export type PaginationConfig = {
  itemsPerPage: number;
  initialPage: number;
  total: number;
  loadData?: PaginationLoadData;
};
```

---

### `PaginationLocales`

```ts
export type PaginationLocales = {
  previous?: string;
  next?: string;
  first?: string;
  last?: string;
  page?: string;
  of?: string;
  items?: string;
};
```

---

### `PaginationPanelConfig`

```ts
export type PaginationPanelConfig = {
  buttonCount?: number;
  info?: boolean;
  totalInfo?: boolean;
  pageSizes?: boolean | number[];
  position?: 'top' | 'bottom';
  navigation?: boolean;
  locales?: PaginationLocales;
};
```

---

### `PaginationFullConfig` (Extended from `index.ts`)

```ts
export type PaginationFullConfig = PaginationConfig & PaginationPanelConfig;
```

---

### `PageChangeEvent`

```ts
export type PageChangeEvent = {
  skip: number;
};
```

---

### `PaginationPanel`

The PaginationPanel class provides a UI component for navigating through data pages
in a RevoGrid instance. It generates a set of buttons and a select dropdown for
page navigation, allowing users to efficiently traverse large datasets.

**Key Features**:
- Supports customizable navigation with first, previous, next, and last buttons.
- Displays current page information and total number of pages.
- Configurable through `PaginationConfig` and `PaginationPanelConfig` for flexible
  pagination behavior.
- Localizable UI elements with default texts like 'Page', 'of', 'items', etc., which
  can be overridden through the `locales` property.
- Automatically updates the pagination panel on configuration changes, ensuring
  consistency with the dataset size and user preferences.

**Usage**:
- Instantiate the PaginationPanel by providing a configuration object and a callback
  for page changes. Integrate it into the RevoGrid by rendering it in the grid's
  additional nodes.

### Example
```typescript
const paginationConfig: PaginationConfig = {
  itemsPerPage: 10,
  initialPage: 0,
  total: 100,
};
const onPageChange = (page: number) => {
  console.log(`Page changed to: ${page}`);
};
const paginationPanel = new PaginationPanel(paginationConfig, onPageChange);

// Render method can be called to integrate into the UI
const panelNode = paginationPanel.render();
```

By integrating the PaginationPanel, RevoGrid users can enhance their data navigation
capabilities, offering an intuitive and responsive interface for interacting with
paginated datasets.

```ts
class PaginationPanel {
  setRefresh(refresh?: () => void);

  setPage(page: number, emitChange = true);

  render();

  update(config: Config);
}
```

---

# Pivot

URL: https://pro.rv-grid.com/api/pivot/
Source: src/content/docs/api/pivot.md

## Module Extensions

### `PivotConfigTotals`

```ts
interface PivotConfigTotals {
  /**
     * Show a grand total row and, when column dimensions exist, grand-total value columns.
     */
    grandTotal?: boolean;
  /**
     * Show subtotal rows and subtotal value columns for multi-level pivot hierarchies.
     */
    subtotals?: boolean;
  /**
     * Disable generated subtotal rows or columns for specific axis fields or
     * zero-based axis levels while keeping global subtotals enabled.
     */
    disabledSubtotals?: {
      rows?: PivotSubtotalDisableRule;
      columns?: PivotSubtotalDisableRule;
    };
  /**
     * Custom display label for the grand total row or value columns.
     */
    grandTotalLabel?: string;
  /**
     * Custom display label for subtotal rows or value columns.
     */
    subtotalLabel?: string;
  /**
     * Hide subtotal rows or columns when a branch contains only one
     * source-backed leaf and the subtotal would duplicate that leaf.
     */
    suppressSingleChildSubtotals?: boolean;
  /**
     * Hide the grand-total row when the pivot contains only one source-backed
     * leaf and the total would duplicate that leaf.
     */
    suppressGrandTotalWhenSingleLeaf?: boolean
}
```

---

### `PivotColumnLevelConfig`

```ts
interface PivotColumnLevelConfig {
  /**
     * Enable drill-down controls for generated groups at this zero-based level.
     * Falls back to `columnCollapse.enabled`.
     */
    collapsible?: boolean;
  /**
     * Start generated groups at this level collapsed.
     * Falls back to `columnCollapse.collapsed`.
     */
    collapsed?: boolean;
  /**
     * Show the parent subtotal column at this level while global subtotals are enabled.
     * Explicit level settings take precedence over `totals.disabledSubtotals.columns`.
     */
    subtotal?: boolean;
  /** Override the subtotal label at this level. */
    subtotalLabel?: string;
  /**
     * Place the subtotal before or after descendant columns.
     * Defaults to `before`.
     */
    subtotalPosition?: PivotColumnSubtotalPosition;
  /**
     * Ordered value fields to expose in this level's subtotal.
     * Defaults to every configured Pivot value field.
     */
    subtotalValues?: ColumnProp[];
  /**
     * Enable generated aggregate filters at this level.
     * Falls back to the value dimension and `columnCollapse.filterable`.
     */
    filterable?: boolean;
  /**
     * Enable generated aggregate sorting at this level.
     * Falls back to the value dimension's `sortable` setting.
     */
    sortable?: boolean
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [PIVOT_CONTEXT_MENU_COMMAND_EVENT]: PivotContextMenuCommandDetail
}
```

---

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  /**
       * Direct Pivot configuration.
       */
      pivot?: Partial<PivotConfig>
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Legacy additionalData property for Pivot.
       * @deprecated Use `grid.pivot` instead.
       *
       * @example
       * ```typescript
       * const grid = document.createElement('revo-grid');
       * grid.pivot = {
       *   dimensions: [
       *     { prop: 'name', aggregator: 'sum' },
       *   ],
       *   rows: ['name'],
       *   columns: ['age'],
       *   values: [{ prop: 'salary', aggregator: 'sum' }],
       * };
       * ```
       */
      pivot?: PivotConfig
}
```

## Plugin API

### `PivotPlugin`

The PivotPlugin is a RevoGrid plugin that enables dynamic creation and manipulation of pivot table structures
within the grid. It provides users with the ability to configure and apply pivot transformations on grid data
for enhanced reporting and analysis.

**Key Features**:
- **Configurable Pivot Table** – Allows users to define row, column, and value fields dynamically.
- **Interactive Configurator** – Integrates a pivot configurator panel to modify pivot settings in real-time.
- **Drag-and-Drop Support** – Enables users to rearrange fields via the configurator for a flexible pivot experience.
- **Efficient Data Transformation** – Utilizes optimized data processing to group and aggregate large datasets.
- **Custom Aggregations** – Supports multiple aggregation functions, including `sum`, `count`, `avg`, `min`, and `max`.
- **Dynamic Theme Adaptation** – Adjusts automatically to the applied RevoGrid theme.
- **State Persistence** – Observes direct `grid.pivot` and legacy `additionalData.pivot`
  configuration updates.

**Usage**:
- Instantiate the PivotPlugin in a RevoGrid instance and define a pivot configuration.
- Use `applyPivot` to generate a pivoted grid based on selected row, column, and value fields.
- Modify the pivot structure using the interactive configurator.
- Call `clearPivot` to restore the original grid state.

### Example
```typescript
import { PivotPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [PivotPlugin];

grid.pivot = {
     dimensions: [{ prop: 'Age' }, { prop: 'City' }, { prop: 'Gender' }, { prop: 'Total Spend' }],
     rows: ['City', 'Age'],
     columns: ['Gender'],
     values: [
       { prop: 'Total Spend', aggregator: 'sum' },
     ],
     hasConfigurator: true,
};
```

This plugin is essential for users who require advanced pivot table functionalities within RevoGrid, offering
comprehensive tools for data transformation and visualization.

#### Dependencies

- **Required** `CorePlugin`, `PIVOT_CFG_UPDATE_EVENT`, `LOADER_EVENT`: Uses Pro plugin infrastructure and events for lifecycle and loading state.
- **Config integration** `direct-pivot-config`: Reads direct pivot configuration from grid.pivot.
- **Config integration** `additionalData.pivot`: Reads legacy pivot configuration from additionalData.pivot.
- **Optional** `sorting-capable-plugin`: Integrates with sorting state when present for field panel and remote sorting.
- **Optional** `pagination-capable-plugin`: Integrates with pagination when present for remote pivot paging.
- **Auto-installed** `ContextMenuPlugin`, `PivotContextMenuPlugin`, `TooltipPlugin`: Installs the shared tooltip and context-menu infrastructure plus the Pivot-semantic menu workspace.
- **Event integration** `groupexpandclick`, `column-collapse`, `column-expand`, `beforefilterapply`, `beforefilteroptionsourcerow`, `beforesortingapply`: Listens to grid events to synchronize drill-down, collapsed groups, filter option rows, and server-mode requests.

```ts
class PivotPlugin {
  /**
     * Returns the last successfully committed Pivot model.
     *
     * A pending or failed remote load never replaces the previous snapshot.
     * Returned arrays and records are read-only references to the active Pivot
     * model rather than defensive copies.
     */
  getRuntimeSnapshot(): PivotRuntimeSnapshot | null;

  /** Returns the unprojected source owned by the active client Pivot session. */
  getPivotOriginalSource();

  getPivotEngineCapabilities(): PivotEngineCapabilities;

  async loadPivotFilterValues(input: {
    field: ColumnProp;
    search?: string;
    offset: number;
    limit: number;
    signal?: AbortSignal;
  }): Promise<PivotFilterValuesResponse>;

  async loadPivotDrilldown(input: {
    cell: PivotDrilldownCellRef;
    customColumns?: string[];
    offset: number;
    limit: number;
    signal?: AbortSignal;
  }): Promise<PivotDrilldownResponse>;

  /**
     * Applies one immutable Pivot configuration update through the public,
     * preventable config event used by configurator and context-menu actions.
     */
  async updatePivotConfig(nextConfig: Partial<PivotConfig>): Promise<boolean>;

  /** Applies an explicit menu sorting state for a field or generated value column. */
  async setPivotSorting(
    prop: ColumnProp,
    order?: 'asc' | 'desc',
    measure?: PivotMeasureMeta,
  ): Promise<void>;

  /**
     * Returns the immediate row-hierarchy children for one committed client
     * Pivot scope. The query only reads the aggregate index built during apply.
     */
  async querySemanticSlice(
    request: PivotSemanticSliceRequest,
    context: { signal?: AbortSignal } = {},
  ): Promise<PivotSemanticSlice>;

  /**
     * Applies a chart-owned semantic drill frontier to Pivot expansion state.
     * The operation uses the same config path for client and server engines, so
     * model revisions and cancellation remain observable through normal Pivot
     * lifecycle events.
     */
  async synchronizeChartDrill(
    detail: {
      from: {
        active: { row: { path: PivotPath }; column: { path: PivotPath } };
      };
      to: {
        active: { row: { path: PivotPath }; column: { path: PivotPath } };
      };
    },
    context: { signal?: AbortSignal } = {},
  ): Promise<void>;

  updateConfigurator(config?: Partial<PivotConfig>);

  updateFieldPanel(config?: Partial<PivotConfig>, resizedColumns?: ColumnResizeDetail);

  /**
     * Applies either the client or remote Pivot engine based on configuration.
     */
  applyPivot(config?: Partial<PivotConfig>);

  /**
     * Clears managed Pivot state and restores the original grid payload.
     */
  clearPivot();
}
```

---

### `PIVOT_VALUES_AXIS_FIELD`

```ts
PIVOT_VALUES_AXIS_FIELD: string;
```

---

### `PivotAxisField`

```ts
export type PivotAxisField = ColumnProp | typeof PIVOT_VALUES_AXIS_FIELD;
```

---

### `PivotConfigValue`

```ts
interface PivotConfigValue {
  /** Optional stable identity when the same source field is configured more than once. */
    id?: string;
  /** Source field used as the measure carrier. */
    prop: ColumnProp;
  /** Aggregator id resolved from the matching dimension definition. */
    aggregator: string;
  /** Optional display label used for generated measure row and column labels. */
    label?: string;
  /** Optional display name used when label is not provided. */
    name?: string;
  /** Optional post-aggregation analytical calculation. */
    calculation?: PivotValueCalculation;
  /** Optional Intl-backed display formatting. */
    format?: PivotValueFormatConfig;
  /** Optional measure-wide conditional formatting. */
    conditionalFormatting?: {
      match?: 'first' | 'all';
      rules: PivotConditionalFormatRule[];
    }
}
```

---

### `PivotSubtotalDisableRule`

```ts
interface PivotSubtotalDisableRule {
  /** Axis fields whose generated subtotal should be skipped. */
    fields?: ColumnProp[];
  /** Zero-based axis levels whose generated subtotal should be skipped. */
    levels?: number[]
}
```

---

### `PivotColumnCollapseConfig`

```ts
interface PivotColumnCollapseConfig {
  /**
     * Enable collapse for generated Pivot column groups.
     */
    enabled?: boolean;
  /**
     * Start all generated Pivot column groups collapsed or expanded by default.
     * Defaults to `true` when column collapse is enabled.
     * Persisted group-specific state in `collapsedColumns` still takes precedence.
     */
    collapsed?: boolean;
  /**
     * Show aggregate filters on collapsed columns and their expanded group
     * headers. Defaults to `true`.
     *
     * This does not affect ordinary filters on expanded leaf value columns.
     */
    filterable?: boolean;
  /**
     * Override the aggregator used for collapsed placeholder buckets.
     * A string applies to every value field, while a record can target a specific value prop.
     */
    aggregator?: string | Partial<Record<string, string>>;
  /**
     * Override the generated placeholder header or cell template used for collapsed groups.
     */
    placeholder?: string | ColumnTemplateFunc | ColumnCollapsePlaceholder
}
```

---

### `PivotColumnSubtotalPosition`

```ts
export type PivotColumnSubtotalPosition = 'before' | 'after';
```

---

### `PivotGroupLabelConfig`

```ts
interface PivotGroupLabelConfig {
  /** Display label for empty-string row and column group members. */
    empty?: string;
  /** Display label for null or undefined row and column group members. */
    null?: string
}
```

---

### `PivotGroupLabelColumnMode`

```ts
export type PivotGroupLabelColumnMode = 'grouped' | 'firstVisible';
```

---

### `PivotRowAxisLayout`

```ts
export type PivotRowAxisLayout = 'compact' | 'tabular';
```

---

### `PivotFieldPanelTexts` (Extended from `index.ts`)

```ts
interface PivotFieldPanelTexts {

}
```

---

### `PivotFieldPanelConfig`

```ts
interface PivotFieldPanelConfig {
  /** Shows the in-grid Pivot field panel. */
    visible?: boolean;
  /** Shows the Reset layout action in Pivot configuration UI. Hidden by default. */
    showResetLayout?: boolean;
  /** Enables drag-and-drop field movement between panel areas. */
    allowFieldDragging?: boolean;
  /** Enables removing fields from panel areas. Disabled by default to avoid losing recoverability in compact layout. */
    allowFieldRemoving?: boolean;
  /** Shows the Rows area. */
    showRowFields?: boolean;
  /** Shows the Columns area. */
    showColumnFields?: boolean;
  /** Shows the Values/Data area. */
    showDataFields?: boolean;
  /** Shows the Filters area. */
    showFilterFields?: boolean;
  /** UI strings for the field panel. */
    texts?: PivotFieldPanelTexts
}
```

---

### `PanelType`

The type of the panel

```ts
/** The type of the panel */
export type PanelType = 'dimensions' | 'rows' | 'columns' | 'values' | 'filters';
```

---

### `PivotFilterScalar`

```ts
export type PivotFilterScalar = string | number | boolean | null;
```

---

### `PivotFilterExclusionSelection`

Selects every value except the explicitly excluded members.

```ts
interface PivotFilterExclusionSelection {
  mode: 'exclude';
  values: PivotFilterScalar[]
}
```

---

### `PivotFilterSelection`

Arrays retain the original inclusive-selection contract.

```ts
/** Arrays retain the original inclusive-selection contract. */
export type PivotFilterSelection =
  | PivotFilterScalar[]
  | PivotFilterExclusionSelection;
```

---

### `PivotFilterSelectionMap`

```ts
export type PivotFilterSelectionMap =
  Partial<Record<string, PivotFilterSelection>>;
```

---

### `PivotConfigDimension` (Extended from `index.ts`)

```ts
interface PivotConfigDimension {
  prop: ColumnProp;
  /** Preferred destination when the field is enabled through configurator selection. */
    selectionTarget?: 'rows' | 'columns' | 'values';
  /** Optional group label or nested group path used to organize the configurator dimensions grid. */
    fieldGroup?: string | string[];
  /** Optional field description shown by Pivot configuration UI. */
    description?: string;
  /** Hides the field from Pivot field-list helpers unless show-hidden mode is enabled. */
    hidden?: boolean;
  /**
     * Custom aggregators or use common aggregators
     */
    aggregators?: { [name: string]: ((values: any[]) => any) };
  /** Values offered by the inline selector when this field is in Filters. */
    filterOptions?: PivotFilterScalar[];
  /**
     * Aggregator value for the column
     * set automatically
     */
    readonly aggregator?: string;
  /**
     * The type of the dimension: rows, values
     * set automatically
     */
    readonly dimension?: PanelType
}
```

---

### `PivotConfig`

```ts
interface PivotConfig {
  dimensions?: PivotConfigDimension[];
  /** Ordered row dimensions used to build the pivot row hierarchy. */
    rows: ColumnProp[];
  /** Ordered column dimensions used to build generated pivot headers. */
    columns?: ColumnProp[];
  /** Measures rendered in the generated pivot cells. */
    values: PivotConfigValue[];
  /** Ordered filter fields shown in the Pivot field panel. */
    filters?: ColumnProp[];
  /**
     * Canonical member selections for fields placed in Rows, Columns, or
     * Filters. Missing/empty entries mean All.
     */
    filterSelections?: PivotFilterSelectionMap;
  /**
     * Semantic post-aggregation filters for generated measures and totals.
     *
     * Member filters remain in `filterSelections` and execute before
     * aggregation. Result filters execute after aggregation (SQL HAVING).
     */
    resultFilters?: PivotAggregateFilterExpression;
  /** Enables the configurator side panel. */
    hasConfigurator?: boolean;
  /** Configures the in-grid Pivot field panel. */
    fieldPanel?: PivotFieldPanelConfig;
  /** Advanced semantic Pivot context menu, enabled by default. */
    contextMenu?: false | PivotContextMenuConfig;
  /** Optional external mount target for the configurator. */
    mountTo?: HTMLElement;
  /** Flattens hierarchical column groups into single-label headers. */
    flatHeaders?: boolean;
  /** Merges generated value headers into the terminal Pivot column headers. */
    mergeValueHeaders?: boolean;
  /**
     * Render Pivot value measures as row members instead of generated value columns.
     */
    valuesOnRows?: boolean;
  /**
     * Advanced row hierarchy order. Use `$values` to place the measure pseudo-field
     * at a specific position in the row tree.
     */
    rowTree?: PivotAxisField[];
  /**
     * Controls how an active multi-level row hierarchy is rendered.
     * `compact` uses one generated Rows column, while `tabular` keeps one
     * visible column per row field. Active drill-down defaults to `compact`.
     */
    rowAxisLayout?: PivotRowAxisLayout;
  /** Shows the legacy configurator columns zone. */
    showColumns?: boolean;
  /** Shows the legacy configurator rows zone. */
    showRows?: boolean;
  /** Shows the legacy configurator values zone. */
    showValues?: boolean;
  /** Shows the legacy configurator filters zone. */
    showFilters?: boolean;
  /** Configures grand totals and subtotals. */
    totals?: PivotConfigTotals;
  /** Configures display labels for empty or null row and column group members. */
    groupLabels?: PivotGroupLabelConfig;
  /**
     * Chooses which visible row cell renders the grouped-row label text.
     * `grouped` keeps label text in the grouped field column.
     * `firstVisible` renders label text in the first currently visible row cell.
     */
    groupLabelColumn?: PivotGroupLabelColumnMode;
  /**
     * Enable Pivot drill-down based on the current row hierarchy.
     * `true` starts collapsed, `false` starts expanded.
     * The feature is only applied when at least two row fields are configured.
     */
    collapsed?: boolean;
  /**
     * Persisted expand state for Pivot drill-down groups.
     * Keys use the same grouped path format as RevoGrid grouping rows.
     */
    expanded?: Record<string, boolean>;
  /**
     * Render aggregate values inside Pivot drill-down group rows.
     * The initial implementation applies to the client-side Pivot path.
     */
    groupAggregations?: boolean;
  /**
     * Configure built-in column drill-down on generated Pivot groups.
     * Omit this option or use `true` to start collapsible groups collapsed.
     * Use `false` or `{ enabled: false }` to disable column drill-down.
     * `{ collapsed: false }` explicitly starts them expanded.
     */
    columnCollapse?: boolean | PivotColumnCollapseConfig;
  /**
     * Per-level generated column behavior keyed by zero-based index in `columns`.
     * Global collapse, totals, filter, and sorting settings remain the defaults.
     */
    columnLevels?: Partial<Record<number, PivotColumnLevelConfig>>;
  /**
     * Initial or persisted collapsed state for generated pivot column groups.
     * `true` collapses all generated groups by default.
     */
    collapsedColumns?: boolean | Record<string, boolean>;
  /** UI strings for the configurator. */
    i18n?: typeof PIVOT_CONFIG_EN;
  /**
     * Optional engine selection. Omit it to keep the existing in-memory pivot behaviour.
     * Server mode uses the same row/column/value configuration but delegates computation
     * through an adapter or remote store.
     */
    engine?: {
      mode?: 'client' | 'server';
      adapter?: PivotEngineAdapter;
      remoteStore?: PivotRemoteStore;
      /** Explicit feature advertisement used by analytical UI commands. */
      capabilities?: PivotEngineCapabilities;
      viewId?: string;
      fieldsVersion?: string;
      rowAxis?: Partial<PivotAxisViewport>;
      columnAxis?: Partial<PivotAxisViewport>;
    }
}
```

---

### `createPivotPathId`

Creates a stable collision-safe id for a typed analytical path.

JSON contains tagged scalar tuples so equal display strings with different
primitive types remain distinct.

```ts
export function createPivotPathId(
  path: readonly (PivotAxisValue | undefined)[],
);
```

---

### `normalizePivotPath`

```ts
export function normalizePivotPath(
  path: readonly (PivotAxisValue | undefined)[],
): PivotAxisValue[];
```

---

### `normalizePivotRuntimeConfig`

```ts
export function normalizePivotRuntimeConfig(
  config: Partial<PivotConfig>,
): PivotConfig;
```

---

### `createPivotMeasureMeta`

```ts
export function createPivotMeasureMeta(
  value: Pick<PivotConfigValue, 'id' | 'prop' | 'aggregator' | 'label' | 'name'>,
  valueIndex?: number,
): PivotMeasureMeta;
```

---

### `createPivotRowMeta`

```ts
export function createPivotRowMeta(input: {
  path: readonly (PivotAxisValue | undefined)[];
  labels: readonly string[];
  kind: PivotRowKind;
  measure?: PivotMeasureMeta;
}): PivotRowMeta;
```

---

### `createPivotColumnMeta`

```ts
export function createPivotColumnMeta(input: {
  path: readonly (PivotAxisValue | undefined)[];
  labels: readonly string[];
  kind: PivotColumnKind;
  prop?: ColumnProp;
  measure?: PivotMeasureMeta;
}): PivotColumnMeta;
```

---

### `getPivotRowMeta`

```ts
export function getPivotRowMeta(row?: DataType): PivotRowMeta | undefined;
```

---

### `getPivotColumnMeta`

```ts
export function getPivotColumnMeta(
  column?: ColumnGrouping | ColumnRegular,
): PivotColumnMeta | undefined;
```

---

### `PIVOT_MODEL_CHANGED_EVENT`

```ts
PIVOT_MODEL_CHANGED_EVENT: string;
```

---

### `PIVOT_ROW_META`

```ts
PIVOT_ROW_META: typeof PIVOT_ROW_META;
```

---

### `PIVOT_COLUMN_META`

```ts
PIVOT_COLUMN_META: typeof PIVOT_COLUMN_META;
```

---

### `PivotEngineMode`

```ts
export type PivotEngineMode = 'client' | 'server';
```

---

### `PivotModelChangedReason`

```ts
export type PivotModelChangedReason = 'client-apply' | 'server-apply' | 'clear';
```

---

### `PivotAxisValue`

```ts
export type PivotAxisValue = string | number | boolean | null;
```

---

### `PivotRowKind`

```ts
export type PivotRowKind = 'leaf' | 'subtotal' | 'grandTotal' | 'group';
```

---

### `PivotColumnKind`

```ts
export type PivotColumnKind =
  | 'leaf'
  | 'subtotal'
  | 'grandTotal'
  | 'collapsed'
  | 'group';
```

---

### `PivotMeasureMeta`

```ts
interface PivotMeasureMeta {
  readonly id?: string;
  readonly valueIndex?: number;
  readonly prop: ColumnProp;
  readonly aggregator: string;
  readonly label: string
}
```

---

### `PivotRowMeta`

```ts
interface PivotRowMeta {
  readonly id: string;
  readonly path: readonly PivotAxisValue[];
  readonly labels: readonly string[];
  readonly depth: number;
  readonly kind: PivotRowKind;
  readonly measure?: PivotMeasureMeta
}
```

---

### `PivotColumnMeta`

```ts
interface PivotColumnMeta {
  readonly id: string;
  readonly path: readonly PivotAxisValue[];
  readonly labels: readonly string[];
  readonly depth: number;
  readonly kind: PivotColumnKind;
  /** Generated RevoGrid cell carrier property. Omitted for header groups. */
    readonly prop?: ColumnProp;
  /** Measure represented by a terminal value column. */
    readonly measure?: PivotMeasureMeta
}
```

---

### `PivotModelChangedEventDetail`

```ts
interface PivotModelChangedEventDetail {
  readonly revision: number;
  readonly reason: PivotModelChangedReason;
  readonly engine: PivotEngineMode
}
```

---

### `PivotRuntimeSnapshot`

```ts
interface PivotRuntimeSnapshot {
  readonly revision: number;
  readonly engine: PivotEngineMode;
  /** Active config with row, column, value, dimension, and filter arrays present. */
    readonly config: Readonly<PivotConfig>;
  readonly source: readonly DataType[];
  readonly columns: ReadonlyArray<ColumnGrouping | ColumnRegular>;
  readonly pinnedBottomSource: readonly DataType[];
  /** Group frontier aggregates keyed by collision-safe semantic row id. */
    readonly groupAggregates: Readonly<Record<string, DataType>>;
  /** Optional JSON-safe hierarchy metadata for semantic analytical slices. */
    readonly hierarchies?: PivotRuntimeHierarchies;
  readonly remoteRequest?: Readonly<PivotLoadRequest>
}
```

---

### `PivotRowWithMeta` (Extended from `index.ts`)

```ts
export type PivotRowWithMeta = DataType & {
  [PIVOT_ROW_META]?: PivotRowMeta;
};
```

---

### `PivotColumnWithMeta` (Extended from `index.ts`)

```ts
export type PivotColumnWithMeta = (ColumnGrouping | ColumnRegular) & {
  [PIVOT_COLUMN_META]?: PivotColumnMeta;
};
```

---

### `createPivotData`

Builds the full client-side Pivot result set from raw source rows.

```ts
export function createPivotData(
  originalData: DataType[],
  config: Partial<PivotConfig>,
);
```

---

### `createPivotDataModel`

Builds the full client-side Pivot result set together with grouped-row
aggregate payloads keyed by RevoGrid grouped path values.

```ts
export function createPivotDataModel(
  originalData: DataType[],
  config: Partial<PivotConfig>,
  options: PivotDataModelOptions = {},
): PivotDataModel;
```

---

### `PivotGroupAggregates`

```ts
export type PivotGroupAggregates = Record<string, DataType>;
```

---

### `PivotDataModel`

```ts
interface PivotDataModel {
  rows: DataType[];
  groupAggregatesByPath: PivotGroupAggregates;
  semanticGroupAggregatesById: PivotGroupAggregates;
  /** @internal Shared path metadata used to project the same visible column frontier. */
    columnAxis?: PivotColumnAxis;
  /** Runtime-only hierarchy index used by semantic Pivot slice queries. */
    semanticSliceIndex?: PivotSemanticSliceIndex
}
```

---

### `PivotDataModelOptions`

```ts
interface PivotDataModelOptions {
  /**
     * Collapsed aggregate paths that must remain materialized while their groups
     * are expanded because an active filter still targets those aggregates.
     */
    aggregateFilterPaths?: readonly (readonly PivotGroupValue[])[]
}
```

---

### `pivotColumns`

Builds the generated RevoGrid column model for the current Pivot config.
The source is only used to discover unique analytical column paths.

```ts
export function pivotColumns(
  config: Partial<PivotConfig>,
  source: DataType[] = [],
  columnAxis: PivotColumnAxis = createPivotColumnAxis(config, source),
);
```

---

### `withPivotTotalLabelTemplates`

```ts
export function withPivotTotalLabelTemplates(
  columns: Array<ColumnGrouping | ColumnRegular>,
  config: Partial<PivotConfig>,
  columnTypes: ColumnTypes = {},
): Array<ColumnGrouping | ColumnRegular>;
```

---

### `withPivotValuePresentation`

Applies measure-owned number and conditional formatting to generated value
columns after their semantic metadata has been materialized.

```ts
export function withPivotValuePresentation(
  columns: Array<ColumnGrouping | ColumnRegular>,
  config: Partial<PivotConfig>,
  columnTypes: ColumnTypes = {},
): Array<ColumnGrouping | ColumnRegular>;
```

---

### `pivotColumnsFromPaths`

```ts
export function pivotColumnsFromPaths(
  config: Partial<PivotConfig>,
  paths: Array<Array<string | number | boolean | null>>,
);
```

---

### `PIVOT_TOTAL_CELL_CLASS`

```ts
PIVOT_TOTAL_CELL_CLASS: string;
```

---

### `PIVOT_ROW_FILTER_ACTIVE_HEADER_CLASS`

```ts
PIVOT_ROW_FILTER_ACTIVE_HEADER_CLASS: string;
```

---

### `PivotSummaryType`

```ts
export type PivotSummaryType = 'sum' | 'min' | 'max' | 'avg' | 'count';
```

---

### `PivotFieldDataType`

```ts
export type PivotFieldDataType = 'string' | 'number' | 'date' | 'boolean';
```

---

### `PivotLogicalOperator`

```ts
export type PivotLogicalOperator = 'and' | 'or';
```

---

### `PivotSortDirection`

```ts
export type PivotSortDirection = 'asc' | 'desc';
```

---

### `PivotSortBySummaryType`

Stable result id of the summary used for analytical member sorting.

```ts
/** Stable result id of the summary used for analytical member sorting. */
export type PivotSortBySummaryType = string;
```

---

### `PivotDateGroupInterval`

```ts
export type PivotDateGroupInterval = 'year' | 'quarter' | 'month' | 'day' | 'dayOfWeek';
```

---

### `PivotGroupInterval`

```ts
export type PivotGroupInterval =
  | PivotDateGroupInterval
  | {
      /** Numeric bucket grouping for OLAP-style measure banding. */
      type: 'numericBucket';
      /** Bucket width. A size of `100` yields buckets such as `0-99`, `100-199`, and so on. */
      size: number;
    };
```

---

### `PivotFilterOperation`

```ts
export type PivotFilterOperation =
  | '='
  | '<>'
  | '>'
  | '>='
  | '<'
  | '<='
  | 'contains'
  | 'notcontains'
  | 'startswith'
  | 'endswith'
  | 'in'
  | 'notin';
```

---

### `PivotPath`

```ts
export type PivotPath = Array<string | number | boolean | null>;
```

---

### `PivotFilterValue`

```ts
export type PivotFilterValue =
  | string
  | number
  | boolean
  | null
  | Array<string | number | boolean | null>;
```

---

### `PivotFilterCondition`

```ts
export type PivotFilterCondition = [selector: string, operation: PivotFilterOperation, value: PivotFilterValue];
```

---

### `PivotFilterExpression`

```ts
export type PivotFilterExpression =
  | PivotFilterCondition
  | [left: PivotFilterExpression, operator: PivotLogicalOperator, right: PivotFilterExpression]
  | ['!', PivotFilterExpression];
```

---

### `PivotAggregateColumnKind`

```ts
export type PivotAggregateColumnKind =
  | 'leaf'
  | 'subtotal'
  | 'grandTotal'
  | 'collapsed';
```

---

### `PivotAggregateFilterDescriptor`

Post-aggregation predicate for one generated Pivot value column.

The semantic path and summary replace the grid's synthetic carrier prop so
remote stores can compile a stable HAVING expression.

```ts
interface PivotAggregateFilterDescriptor {
  columnPath: PivotPath;
  columnKind: PivotAggregateColumnKind;
  summary: PivotSummaryDescriptor;
  operation: PivotFilterOperation;
  value: PivotFilterValue
}
```

---

### `PivotAggregateFilterExpression`

Boolean post-aggregation filter tree.

Aggregate filters use semantic Pivot coordinates instead of generated grid
properties so the expression survives projection, saved-view, and server
round trips.

```ts
/**
 * Boolean post-aggregation filter tree.
 *
 * Aggregate filters use semantic Pivot coordinates instead of generated grid
 * properties so the expression survives projection, saved-view, and server
 * round trips.
 */
export type PivotAggregateFilterExpression =
  | PivotAggregateFilterDescriptor
  | [
      left: PivotAggregateFilterExpression,
      operator: PivotLogicalOperator,
      right: PivotAggregateFilterExpression,
    ]
  | ['!', PivotAggregateFilterExpression];
```

---

### `PivotGroupDescriptor`

```ts
interface PivotGroupDescriptor {
  /** Public field id resolved through the server-side field registry. */
    selector: string;
  /** Descending sort flag for the grouped members on this axis level. */
    desc?: boolean;
  /** Optional date or numeric-bucket grouping strategy for this selector. */
    groupInterval?: PivotGroupInterval
}
```

---

### `PivotSummaryDescriptor`

```ts
interface PivotSummaryDescriptor {
  /** Optional stable measure id, required when one selector is used more than once. */
    id?: string;
  /** Public field id of the measure being aggregated. */
    selector: string;
  /** Stable summary function id returned by the analytical engine. */
    summaryType: PivotSummaryType;
  /** Optional post-aggregation calculation advertised by the engine. */
    calculation?: PivotValueCalculation
}
```

---

### `PivotEngineCapabilities`

Optional server feature advertisement. Context-menu analytical commands stay
disabled until the backing engine explicitly opts into the corresponding
operation.

```ts
interface PivotEngineCapabilities {
  aggregation?: boolean;
  calculations?: boolean | PivotValueCalculationType[];
  filter?: boolean;
  filterValues?: boolean;
  sort?: boolean;
  drilldown?: boolean
}
```

---

### `PivotSortDescriptor`

```ts
interface PivotSortDescriptor {
  /** Public field id to sort by. */
    selector: string;
  /** Descending sort flag for the selector or summary. */
    desc?: boolean;
  /** Optional summary id used when the backend supports sort-by-summary semantics. */
    bySummary?: PivotSortBySummaryType
}
```

---

### `PivotAxisViewport`

```ts
interface PivotAxisViewport {
  /** Zero-based analytical offset for this axis window. */
    offset: number;
  /** Requested analytical window size for this axis. */
    limit: number;
  /** Expanded analytical members represented as paths, never as UI indexes. */
    expandedPaths?: PivotPath[];
  /** Collapsed analytical members represented as paths, never as UI indexes. */
    collapsedPaths?: PivotPath[]
}
```

---

### `PivotUiStateHints`

```ts
interface PivotUiStateHints {
  /** Preferred row-header presentation for engines that can shape tree metadata. */
    rowHeaderLayout?: 'tree' | 'flat';
  /** Preferred totals placement hint for the analytical engine. */
    showTotalsPrior?: 'rows' | 'columns' | 'none';
  /** Hint that the UI currently expects collapsed-by-default hierarchies. */
    collapsedByDefault?: boolean;
  /** Hint that generated column groups are collapsed by default. */
    columnGroupsCollapsedByDefault?: boolean
}
```

---

### `PivotLoadOptions`

```ts
interface PivotLoadOptions {
  /** Registry-backed filter expression tree. */
    filter?: PivotFilterExpression;
  /** Post-aggregation expression for generated Pivot value columns. */
    having?:
      | PivotAggregateFilterExpression
      | PivotAggregateFilterDescriptor[];
  /** Row-axis grouping descriptors. */
    rows?: PivotGroupDescriptor[];
  /** Column-axis grouping descriptors. */
    columns?: PivotGroupDescriptor[];
  /** Grand-total summary descriptors. */
    totalSummary?: PivotSummaryDescriptor[];
  /** Group-level summary descriptors. */
    groupSummary?: PivotSummaryDescriptor[];
  /** Analytical sorting directives. */
    sort?: PivotSortDescriptor[]
}
```

---

### `PivotLoadRequest`

```ts
interface PivotLoadRequest {
  /** Client-generated correlation id for logs, tracing, and stale-response protection. */
    requestId: string;
  /** Dataset or semantic view identifier understood by the backend. */
    viewId: string;
  /** Version or checksum of the published field registry for this view. */
    fieldsVersion: string;
  /** Analytical layout, filters, summaries, and sort instructions. */
    loadOptions: PivotLoadOptions;
  /** Independent analytical windows for the row and column axes. */
    viewport: {
      rowAxis: PivotAxisViewport;
      columnAxis: PivotAxisViewport;
    };
  /** Optional UI hints that let a backend align with current Pivot presentation preferences. */
    uiState?: PivotUiStateHints
}
```

---

### `PivotAxisWindowMeta`

```ts
interface PivotAxisWindowMeta {
  /** Total number of analytical members available on this axis. */
    totalCount?: number;
  /** Optional analytical paths used to materialize generated Pivot columns. */
    paths?: PivotPath[];
  /** Zero-based analytical offset for this axis window. */
    offset?: number;
  /** Requested analytical window size for this axis. */
    limit?: number;
  /** Expanded analytical members represented as paths. */
    expandedPaths?: PivotPath[];
  /** Collapsed analytical members represented as paths. */
    collapsedPaths?: PivotPath[];
  /** Actual number of members returned in this window. */
    returned?: number
}
```

---

### `PivotLoadResponseMeta`

```ts
interface PivotLoadResponseMeta {
  /** Cache outcome for observability and UI diagnostics. */
    cacheStatus: 'hit' | 'miss' | 'warm' | 'bypass';
  /** Correlation cache key. */
    cacheKey?: string;
  /** Server-side generation timestamp. */
    generatedAt?: string;
  /** Elapsed processing time in milliseconds. */
    elapsedMs?: number;
  /** Optional warnings or diagnostic messages. */
    warnings?: string[]
}
```

---

### `PivotLoadResponse`

```ts
interface PivotLoadResponse {
  /** Visible analytical payload or already materialized row records. */
    data: PivotMaterializedRow[];
  /** Total or pinned summary rows for the current analytical request. */
    summary: unknown[];
  /** Row-axis window metadata. */
    rowAxis: PivotAxisWindowMeta;
  /** Column-axis window metadata. */
    columnAxis: PivotAxisWindowMeta;
  /** Optional grouped-row aggregate payloads keyed by grouped path values. */
    groupAggregates?: Record<string, DataType>;
  /** Cache and timing metadata for diagnostics. */
    meta: PivotLoadResponseMeta;
  /** Correlation id. */
    requestId?: string;
  /** Response format version. */
    version?: number
}
```

---

### `PIVOT_MEASURE_ID_PROP`

Hidden stable measure identity accepted on already materialized values-on-rows
response records. It disambiguates measures that intentionally share labels.

```ts
PIVOT_MEASURE_ID_PROP: string;
```

---

### `PivotMaterializedRow` (Extended from `index.ts`)

```ts
export type PivotMaterializedRow = DataType & {
  [PIVOT_MEASURE_ID_PROP]?: string;
};
```

---

### `PivotDrilldownCellRef`

```ts
interface PivotDrilldownCellRef {
  /** Row-axis path for the visible summary cell. */
    rowPath: PivotPath;
  /** Column-axis path for the visible summary cell. */
    columnPath: PivotPath;
  /** Optional measure index when multiple values are present. */
    dataIndex?: number
}
```

---

### `PivotDrilldownRequest`

```ts
interface PivotDrilldownRequest {
  /** Client-generated correlation id for the drilldown request. */
    requestId: string;
  /** Dataset or semantic view identifier understood by the backend. */
    viewId: string;
  /** Version or checksum of the published field registry for this view. */
    fieldsVersion: string;
  /** Visible pivot cell that defines the drilldown scope. */
    cell: PivotDrilldownCellRef;
  /** Optional whitelist-validated columns to expose in the fact page. */
    customColumns?: string[];
  /** Zero-based fact-page offset. */
    offset: number;
  /** Requested fact-page size. */
    limit: number
}
```

---

### `PivotDrilldownResponse`

```ts
interface PivotDrilldownResponse {
  /** Matching fact rows for the requested summary cell. */
    data: DataType[];
  /** Total number of matching facts. */
    totalCount: number;
  /** Optional cache metadata for drilldown responses. */
    meta?: Partial<PivotLoadResponseMeta>;
  /** Correlation id. */
    requestId?: string
}
```

---

### `PivotFilterValuesRequest`

```ts
interface PivotFilterValuesRequest {
  /** Client-generated correlation id for cancellation and tracing. */
    requestId: string;
  /** Dataset or semantic view identifier understood by the backend. */
    viewId: string;
  /** Version or checksum of the published field registry. */
    fieldsVersion: string;
  /** Public field id whose distinct values are requested. */
    selector: string;
  /** Active report filters excluding the requested selector. */
    filter?: PivotFilterExpression;
  /** Optional search text applied by the engine before paging. */
    search?: string;
  /** Zero-based distinct-value page offset. */
    offset: number;
  /** Requested distinct-value page size. */
    limit: number
}
```

---

### `PivotFilterValuesResponse`

```ts
interface PivotFilterValuesResponse {
  requestId?: string;
  values: Array<string | number | boolean | null>;
  totalCount: number
}
```

---

### `PivotStateSaveRequest`

```ts
interface PivotStateSaveRequest {
  /** Client-generated correlation id for persistence. */
    requestId: string;
  /** View identifier whose UI state is being persisted. */
    viewId: string;
  /** User identifier that owns the saved state. */
    userId: string;
  /** Arbitrary persisted Pivot UI state payload. */
    state: Record<string, unknown>
}
```

---

### `PivotStateResponse`

```ts
interface PivotStateResponse {
  /** Optional echoed correlation id from the request. */
    requestId?: string;
  /** User identifier that owns the state. */
    userId: string;
  /** View identifier for the saved state. */
    viewId: string;
  /** Persisted Pivot UI state payload. */
    state: Record<string, unknown>;
  /** Optional schema version for persisted state. */
    version?: number
}
```

---

### `PivotCacheInvalidationRequest`

```ts
interface PivotCacheInvalidationRequest {
  /** Client-generated correlation id for invalidation requests. */
    requestId: string;
  /** Tenant scope to invalidate. */
    tenantId?: string;
  /** Optional view scope within the tenant. */
    viewId?: string;
  /** Dataset watermark to invalidate. */
    datasetWatermark?: string;
  /** Optional field-registry version scope. */
    fieldsVersion?: string
}
```

---

### `PivotLimits`

```ts
interface PivotLimits {
  /** Hard cap for row-axis windows. */
    maxRowWindowSize: number;
  /** Hard cap for column-axis windows. */
    maxColumnWindowSize: number;
  /** Hard cap for expanded analytical members. */
    maxExpandedPaths: number;
  /** Hard cap for analytical hierarchy depth. */
    maxExpansionDepth: number;
  /** Hard cap for drilldown page size. */
    maxDrilldownLimit: number;
  /** Hard cap for requested summary descriptors. */
    maxSummaryDescriptors: number;
  /** Hard cap for row or column grouping descriptors. */
    maxGroupDescriptors: number;
  /** Hard cap for nested filter-expression depth. */
    maxFilterDepth: number
}
```

---

### `PivotGridModel`

```ts
interface PivotGridModel {
  /** Generated RevoGrid columns for the visible Pivot window. */
    columns: Array<ColumnGrouping | ColumnRegular>;
  /** Visible body rows to render in the grid viewport. */
    source: DataType[];
  /** Optional pinned grand-total rows. */
    pinnedBottomSource?: DataType[];
  /** Optional grouped-row metadata for Pivot drill-down. */
    grouping?: GroupingOptions;
  /** Response metadata forwarded to UI diagnostics if needed. */
    meta?: Partial<PivotLoadResponseMeta>
}
```

---

### `PivotEngineAdapter`

Analytical engine boundary used by `PivotPlugin`.

Use this when your application wants to translate Pivot requests directly into
OLAP, warehouse, or semantic-layer queries without going through
`HttpPivotRemoteStore`.

```ts
interface PivotEngineAdapter {
  readonly capabilities?: PivotEngineCapabilities;
  load(request: PivotLoadRequest, signal?: AbortSignal): Promise<PivotLoadResponse>;
  drilldown?(request: PivotDrilldownRequest, signal?: AbortSignal): Promise<PivotDrilldownResponse>;
  filterValues?(
      request: PivotFilterValuesRequest,
      signal?: AbortSignal,
    ): Promise<PivotFilterValuesResponse>
}
```

---

### `PivotAuthProvider`

Async auth-header resolver used by HTTP-backed remote stores.

```ts
/** Async auth-header resolver used by HTTP-backed remote stores. */
export type PivotAuthProvider = () => Promise<Record<string, string>>;
```

---

### `PivotRemoteStore`

Framework-agnostic client contract for server-side Pivot operations.

In production this should usually talk to an application API that owns auth,
tenancy, selector validation, and query translation. It is not intended for
direct browser-to-database connections.

```ts
interface PivotRemoteStore {
  readonly capabilities?: PivotEngineCapabilities;
  load(request: PivotLoadRequest, signal?: AbortSignal): Promise<PivotLoadResponse>;
  drilldown(
      request: PivotDrilldownRequest,
      signal?: AbortSignal,
    ): Promise<PivotDrilldownResponse>;
  filterValues?(
      request: PivotFilterValuesRequest,
      signal?: AbortSignal,
    ): Promise<PivotFilterValuesResponse>;
  saveState(request: PivotStateSaveRequest, signal?: AbortSignal): Promise<void>;
  loadState(userId: string, viewId: string, signal?: AbortSignal): Promise<PivotStateResponse>
}
```

---

### `PivotRemoteStoreHooks`

```ts
interface PivotRemoteStoreHooks {
  requestStarted?: (event: { key: string; type: 'load' | 'drilldown' | 'saveState' | 'loadState' }) => void;
  requestSucceeded?: (
      event: { key: string; type: 'load' | 'drilldown' | 'saveState' | 'loadState'; cacheStatus?: string },
    ) => void;
  requestFailed?: (
      event: { key: string; type: 'load' | 'drilldown' | 'saveState' | 'loadState'; error: unknown },
    ) => void;
  cacheStatusChanged?: (event: { key: string; cacheStatus: string }) => void
}
```

---

### `PivotRemoteStoreOptions`

```ts
interface PivotRemoteStoreOptions {
  /** Base URL of the application API that exposes `/api/pivot/*` endpoints. */
    baseUrl?: string;
  /** Tenant scope used for cache keys and backend request routing. */
    tenantId?: string;
  /** Dataset or cube watermark used to separate stale and fresh cached results. */
    datasetWatermark?: string;
  /** Async auth-header provider, typically used for bearer tokens or session headers. */
    authProvider?: PivotAuthProvider;
  /** Custom fetch implementation for frameworks, SSR, tests, or mocked transports. */
    fetchImpl?: typeof fetch;
  /** Optional lifecycle hooks for request telemetry and cache diagnostics. */
    hooks?: PivotRemoteStoreHooks
}
```

---

### `HttpPivotRemoteStore`

Default remote store backed by `fetch` and the public Pivot HTTP contract.

```ts
class HttpPivotRemoteStore {
  load(request: PivotLoadRequest, signal?: AbortSignal): Promise<PivotLoadResponse>;

  drilldown(request: PivotDrilldownRequest, signal?: AbortSignal): Promise<PivotDrilldownResponse>;

  async saveState(request: PivotStateSaveRequest, signal?: AbortSignal): Promise<void>;

  loadState(userId: string, viewId: string, signal?: AbortSignal): Promise<PivotStateResponse>;
}
```

---

### `createPivotDrilldownRequest`

```ts
export function createPivotDrilldownRequest(
  input: PivotDrilldownRequestInput,
  createRequestId: () => string = createDefaultDrilldownRequestId,
): PivotDrilldownRequest;
```

---

### `createPivotDrilldownTableModel`

```ts
export function createPivotDrilldownTableModel(
  response: PivotDrilldownResponse,
  request?: PivotDrilldownRequest,
): PivotDrilldownTableModel;
```

---

### `createPivotDrilldownColumns`

```ts
export function createPivotDrilldownColumns(
  rows: DataType[],
  customColumns?: string[],
): ColumnRegular[];
```

---

### `PivotDrilldownStatus`

```ts
export type PivotDrilldownStatus = 'idle' | 'loading' | 'success' | 'error';
```

---

### `PivotDrilldownRequestInput`

```ts
interface PivotDrilldownRequestInput {
  /** Dataset or semantic view identifier understood by the adapter/backend. */
    viewId: string;
  /** Version or checksum of the field registry for this view. */
    fieldsVersion: string;
  /** Visible pivot cell that defines the source-row scope. */
    cell: PivotDrilldownCellRef;
  /** Optional whitelist-validated columns to expose in the fact page. */
    customColumns?: string[];
  /** Zero-based fact-page offset. Defaults to 0. */
    offset?: number;
  /** Requested fact-page size. Defaults to 100. */
    limit?: number;
  /** Optional caller-provided correlation id. */
    requestId?: string
}
```

---

### `PivotDrilldownTableModel`

```ts
interface PivotDrilldownTableModel {
  /** RevoGrid/table-ready fact columns. */
    columns: ColumnRegular[];
  /** Fact rows returned by the adapter. */
    rows: DataType[];
  /** Total matching facts across all pages. */
    totalCount: number
}
```

---

### `PivotDrilldownState` (Extended from `index.ts`)

```ts
interface PivotDrilldownState {
  status: PivotDrilldownStatus;
  loading: boolean;
  error?: unknown;
  request?: PivotDrilldownRequest;
  response?: PivotDrilldownResponse
}
```

---

### `PivotDrilldownControllerOptions`

```ts
interface PivotDrilldownControllerOptions {
  /** Default page size used when `load` does not specify a limit. */
    defaultLimit?: number;
  /** Correlation id generator used by the request builder. */
    createRequestId?: () => string
}
```

---

### `PivotDrilldownStateListener`

```ts
export type PivotDrilldownStateListener = (state: PivotDrilldownState) => void;
```

---

### `PivotDrilldownController`

```ts
class PivotDrilldownController {
  getState();

  subscribe(listener: PivotDrilldownStateListener);

  async load(input: PivotDrilldownRequestInput, signal?: AbortSignal);

  abort();

  reset();
}
```

---

### `savePivotView`

```ts
export async function savePivotView(
  store: PivotRemoteStore,
  options: PivotSaveViewOptions,
): Promise<PivotSavedView>;
```

---

### `loadPivotView`

```ts
export async function loadPivotView(
  store: PivotRemoteStore,
  options: PivotLoadViewOptions,
): Promise<PivotSavedView>;
```

---

### `createPivotSavedViewState`

```ts
export function createPivotSavedViewState(
  config: Partial<PivotConfig>,
  metadata: { name?: string; savedAt?: string } = {},
): PivotSavedViewState;
```

---

### `serializePivotConfig`

```ts
export function serializePivotConfig(config: Partial<PivotConfig>): Partial<PivotConfig>;
```

---

### `pivotSavedViewFromState`

```ts
export function pivotSavedViewFromState(response: PivotStateResponse): PivotSavedView;
```

---

### `renamePivotSavedView`

```ts
export function renamePivotSavedView(
  views: readonly PivotSavedViewRecord[],
  options: PivotRenameViewOptions,
): PivotSavedViewRecord[];
```

---

### `duplicatePivotSavedView`

```ts
export function duplicatePivotSavedView(
  views: readonly PivotSavedViewRecord[],
  options: PivotDuplicateViewOptions,
): PivotSavedViewRecord[];
```

---

### `deletePivotSavedView`

```ts
export function deletePivotSavedView(
  views: readonly PivotSavedViewRecord[],
  options: PivotDeleteViewOptions,
): PivotSavedViewRecord[];
```

---

### `PIVOT_SAVED_VIEW_STATE_KIND`

```ts
PIVOT_SAVED_VIEW_STATE_KIND: string;
```

---

### `PIVOT_SAVED_VIEW_STATE_VERSION`

```ts
PIVOT_SAVED_VIEW_STATE_VERSION: 2;
```

---

### `PivotSavedViewRef`

```ts
interface PivotSavedViewRef {
  /** User identifier that owns the saved view. */
    userId: string;
  /** View identifier used by the remote state store. */
    viewId: string
}
```

---

### `PivotSavedView` (Extended from `index.ts`)

```ts
interface PivotSavedView {
  /** Serializable Pivot configuration restored from the saved view payload. */
    config: Partial<PivotConfig>;
  /** Optional display name supplied by the application. */
    name?: string;
  /** Optional ISO timestamp supplied by the application or backend. */
    savedAt?: string;
  /** Persisted state schema version. */
    version: number;
  /** Optional echoed correlation id from the remote state response. */
    requestId?: string
}
```

---

### `PivotSavedViewDeleteIntent` (Extended from `index.ts`)

```ts
interface PivotSavedViewDeleteIntent {
  /** Marks a saved view for deletion by the application or remote state sync layer. */
    deleted: true;
  /** Optional ISO timestamp supplied by the application. */
    deletedAt?: string;
  /** Optional client-generated correlation id. */
    requestId?: string
}
```

---

### `PivotSavedViewRecord`

```ts
export type PivotSavedViewRecord = PivotSavedView | PivotSavedViewDeleteIntent;
```

---

### `PivotSaveViewOptions` (Extended from `index.ts`)

```ts
interface PivotSaveViewOptions {
  /** Active Pivot config to serialize into the remote state payload. */
    config: Partial<PivotConfig>;
  /** Optional display name supplied by the application. */
    name?: string;
  /** Optional client-generated correlation id. */
    requestId?: string;
  /** Optional ISO timestamp. Defaults to the current time. */
    savedAt?: string;
  /** Optional abort signal forwarded to the remote store. */
    signal?: AbortSignal
}
```

---

### `PivotRenameViewOptions` (Extended from `index.ts`)

```ts
interface PivotRenameViewOptions {
  /** Next display name for the saved view. */
    name: string
}
```

---

### `PivotDuplicateViewOptions` (Extended from `index.ts`)

```ts
interface PivotDuplicateViewOptions {
  /** Optional explicit identifier for the duplicated view. */
    newViewId?: string;
  /** Optional duplicated view name. Defaults to "<source name> Copy". */
    name?: string;
  /** Optional ISO timestamp copied into the duplicated view. */
    savedAt?: string;
  /** Optional client-generated correlation id. */
    requestId?: string;
  /** Stable id factory for deterministic tests and app-owned id schemes. */
    generateId?: (view: PivotSavedView, views: readonly PivotSavedViewRecord[]) => string
}
```

---

### `PivotDeleteViewOptions` (Extended from `index.ts`)

```ts
interface PivotDeleteViewOptions {
  /** Optional ISO timestamp supplied by the application. */
    deletedAt?: string;
  /** Optional client-generated correlation id. */
    requestId?: string
}
```

---

### `PivotLoadViewOptions` (Extended from `index.ts`)

```ts
interface PivotLoadViewOptions {
  /** Optional abort signal forwarded to the remote store. */
    signal?: AbortSignal
}
```

---

### `PivotSavedViewState` (Extended from `index.ts`)

```ts
interface PivotSavedViewState {
  kind: typeof PIVOT_SAVED_VIEW_STATE_KIND;
  version: typeof PIVOT_SAVED_VIEW_STATE_VERSION;
  config: Partial<PivotConfig>;
  name?: string;
  savedAt?: string
}
```

---

### `createFieldRegistry`

Converts a field entry list into an id-addressable registry map.

```ts
export function createFieldRegistry(entries: FieldRegistryEntry[]): PivotFieldRegistry;
```

---

### `getFieldRegistryEntry`

Resolves a public selector or throws the stable invalid-selector error.

```ts
export function getFieldRegistryEntry(
  registry: PivotFieldRegistry,
  selector: string,
): FieldRegistryEntry;
```

---

### `assertSummaryAllowed`

Validates that a requested summary is allowed for the selector.

```ts
export function assertSummaryAllowed(
  registry: PivotFieldRegistry,
  descriptor: PivotSummaryDescriptor,
);
```

---

### `assertGroupIntervalAllowed`

Validates that a requested grouping interval is allowed for the selector.

```ts
export function assertGroupIntervalAllowed(
  registry: PivotFieldRegistry,
  descriptor: PivotGroupDescriptor,
);
```

---

### `assertDrilldownColumnsAllowed`

Validates that requested drill-down columns are safe to expose.

```ts
export function assertDrilldownColumnsAllowed(
  registry: PivotFieldRegistry,
  columns: string[] = [],
);
```

---

### `BackendExpression`

```ts
interface BackendExpression {
  kind: 'column' | 'sql';
  value: string
}
```

---

### `FieldRegistryEntry`

```ts
interface FieldRegistryEntry {
  id: string;
  label: string;
  dataType: PivotFieldDataType;
  expression: BackendExpression;
  allowedOperations: PivotFilterOperation[];
  allowedSummaries?: PivotSummaryType[];
  allowedGroupIntervals?: PivotGroupInterval[];
  drilldownVisible?: boolean
}
```

---

### `PivotFieldRegistry`

```ts
export type PivotFieldRegistry = Record<string, FieldRegistryEntry>;
```

---

### `createPivotErrorResponse`

Serializes either a `PivotError` or a raw payload into the wire format.

```ts
export function createPivotErrorResponse(
  requestId: string,
  error: PivotError | PivotErrorPayload,
): PivotErrorResponse;
```

---

### `PivotErrorCode`

Pivot errors define the stable, serializable error contract shared by local
validation and remote endpoint implementations.

```ts
/**
 * Pivot errors define the stable, serializable error contract shared by local
 * validation and remote endpoint implementations.
 */

export type PivotErrorCode =
  | 'PIVOT_NOT_ACTIVE'
  | 'REVISION_MISMATCH'
  | 'INVALID_HIERARCHY_PATH'
  | 'HIERARCHY_UNAVAILABLE'
  | 'INVALID_SELECTOR'
  | 'INVALID_FILTER_OPERATION'
  | 'INVALID_SUMMARY_TYPE'
  | 'INVALID_GROUP_INTERVAL'
  | 'WINDOW_LIMIT_EXCEEDED'
  | 'EXPANSION_LIMIT_EXCEEDED'
  | 'AUTH_REQUIRED'
  | 'FORBIDDEN'
  | 'STATE_NOT_FOUND'
  | 'CACHE_INVALIDATION_FORBIDDEN'
  | 'INTERNAL_ERROR';
```

---

### `PivotErrorPayload`

```ts
interface PivotErrorPayload {
  code: PivotErrorCode;
  message: string;
  details?: Record<string, unknown>
}
```

---

### `PivotErrorResponse`

```ts
interface PivotErrorResponse {
  requestId: string;
  error: PivotErrorPayload
}
```

---

### `PivotError`

Error class carrying the public Pivot error code and optional details.

```ts
class PivotError {}
```

---

### `normalizePivotLoadRequest`

Normalizes and validates a pivot load request.

```ts
export function normalizePivotLoadRequest(
  request: PivotLoadRequest,
  registry: PivotFieldRegistry,
  limits: PivotLimits = DEFAULT_PIVOT_LIMITS,
): NormalizedPivotLoadRequest;
```

---

### `normalizeAggregateFilterExpression`

Validates both the semantic HAVING tree and the legacy flat descriptor list.

```ts
export function normalizeAggregateFilterExpression(
  expression:
    | PivotAggregateFilterExpression
    | PivotAggregateFilterDescriptor[]
    | undefined,
  registry: PivotFieldRegistry,
  limits: Pick<
    PivotLimits,
    'maxSummaryDescriptors' | 'maxExpansionDepth' | 'maxFilterDepth'
  > = DEFAULT_PIVOT_LIMITS,
):
  | PivotAggregateFilterExpression
  | PivotAggregateFilterDescriptor[]
  | undefined;
```

---

### `normalizeAggregateFilters`

Validates post-aggregation filters without treating generated props as fields.

```ts
export function normalizeAggregateFilters(
  filters: PivotAggregateFilterDescriptor[],
  registry: PivotFieldRegistry,
  limits: Pick<PivotLimits, 'maxSummaryDescriptors' | 'maxExpansionDepth'> = DEFAULT_PIVOT_LIMITS,
): PivotAggregateFilterDescriptor[] | undefined;
```

---

### `normalizePivotDrilldownRequest`

Normalizes and validates a drill-down request.

```ts
export function normalizePivotDrilldownRequest(
  request: PivotDrilldownRequest,
  registry: PivotFieldRegistry,
  limits: PivotLimits = DEFAULT_PIVOT_LIMITS,
): NormalizedPivotDrilldownRequest;
```

---

### `normalizeFilterExpression`

Validates and normalizes nested filter expressions recursively.

```ts
export function normalizeFilterExpression(
  filter: PivotFilterExpression,
  registry: PivotFieldRegistry,
  maxDepth: number,
  depth = 1,
): PivotFilterExpression;
```

---

### `normalizeExpandedPaths`

Sorts and validates analytical expansion paths.

```ts
export function normalizeExpandedPaths(
  expandedPaths: PivotPath[] = [],
  limits: Pick<PivotLimits, 'maxExpandedPaths' | 'maxExpansionDepth'> = DEFAULT_PIVOT_LIMITS,
);
```

---

### `normalizeViewportAxis`

Enforces viewport limits and normalized expansion state for one axis.

```ts
export function normalizeViewportAxis(
  viewport: PivotAxisViewport,
  maxWindowSize: number,
  limits: Pick<PivotLimits, 'maxExpandedPaths' | 'maxExpansionDepth'> = DEFAULT_PIVOT_LIMITS,
): PivotAxisViewport;
```

---

### `normalizeSummaries`

Validates and canonicalizes summary descriptors.

```ts
export function normalizeSummaries(
  descriptors: PivotSummaryDescriptor[],
  registry: PivotFieldRegistry,
  limits: Pick<PivotLimits, 'maxSummaryDescriptors'> = DEFAULT_PIVOT_LIMITS,
);
```

---

### `normalizeGroups`

Validates and canonicalizes grouping descriptors.

```ts
export function normalizeGroups(
  descriptors: PivotGroupDescriptor[],
  registry: PivotFieldRegistry,
  limits: Pick<PivotLimits, 'maxGroupDescriptors'> = DEFAULT_PIVOT_LIMITS,
);
```

---

### `getSummaryResultId`

Builds the stable result-field name for a summary descriptor.

```ts
export function getSummaryResultId(summary: PivotSummaryDescriptor);
```

---

### `NormalizedPivotLoadRequest`

```ts
export type NormalizedPivotLoadRequest = PivotLoadRequest;
```

---

### `NormalizedPivotDrilldownRequest`

```ts
export type NormalizedPivotDrilldownRequest = PivotDrilldownRequest;
```

---

### `DEFAULT_PIVOT_LIMITS`

```ts
DEFAULT_PIVOT_LIMITS: {
  maxRowWindowSize: number;
  maxColumnWindowSize: number;
  maxExpandedPaths: number;
  maxExpansionDepth: number;
  maxDrilldownLimit: number;
  maxSummaryDescriptors: number;
  maxGroupDescriptors: number;
  maxFilterDepth: number;
};
```

---

### `stableStringify`

Stringifies nested values with stable object key ordering.

```ts
export function stableStringify(value: unknown): string;
```

---

### `createPivotCacheKey`

Builds the canonical cache key for a pivot load window.

```ts
export function createPivotCacheKey(context: PivotCacheKeyContext): string;
```

---

### `PivotCacheKeyContext`

```ts
interface PivotCacheKeyContext {
  tenantId: string;
  viewId: string;
  fieldsVersion: string;
  datasetWatermark?: string;
  request: Omit<PivotLoadRequest, 'requestId' | 'viewId' | 'fieldsVersion'>
}
```

---

### `PlannedPivotSummary` (Extended from `index.ts`)

```ts
interface PlannedPivotSummary {
  resultId: string;
  execution:
      | {
          type: 'direct';
          field: FieldRegistryEntry;
        }
      | {
          type: 'composite';
          components: Array<{
            selector: string;
            summaryType: 'sum' | 'count';
          }>;
        }
}
```

---

### `PivotQueryPlan`

```ts
interface PivotQueryPlan {
  request: PivotLoadRequest;
  filteredBaseDataset: {
      viewId: string;
      fieldsVersion: string;
      filter?: PivotLoadRequest['loadOptions']['filter'];
    };
  rowAxis: {
      groups: PivotGroupDescriptor[];
      viewport: PivotLoadRequest['viewport']['rowAxis'];
    };
  columnAxis: {
      groups: PivotGroupDescriptor[];
      viewport: PivotLoadRequest['viewport']['columnAxis'];
    };
  summaries: PlannedPivotSummary[];
  /** Post-aggregation predicates compiled by the backend as HAVING clauses. */
    having: PivotLoadRequest['loadOptions']['having'];
  orderBy: PivotLoadRequest['loadOptions']['sort']
}
```

---

### `DrilldownQueryPlan`

```ts
interface DrilldownQueryPlan {
  request: PivotDrilldownRequest;
  visibleFields: FieldRegistryEntry[]
}
```

---

### `PivotQueryPlanner`

```ts
interface PivotQueryPlanner {
  planLoad(request: PivotLoadRequest): PivotQueryPlan;
  planDrilldown(request: PivotDrilldownRequest): DrilldownQueryPlan
}
```

---

### `SqlPivotQueryPlanner`

SQL-oriented logical planner that resolves field metadata and summaries.

```ts
class SqlPivotQueryPlanner {
  planLoad(request: PivotLoadRequest): PivotQueryPlan;

  planDrilldown(request: PivotDrilldownRequest): DrilldownQueryPlan;
}
```

---

### `getPivotColumnPaths`

Derives the visible analytical column paths used by the client adapter.

```ts
export function getPivotColumnPaths(
  source: DataType[],
  config: Partial<PivotConfig>,
);
```

---

### `ClientPivotEngineAdapter`

Client adapter keeps the existing client-side pivot behaviour behind the same
engine interface used by the remote path.

```ts
class ClientPivotEngineAdapter {
  async load(request: PivotLoadRequest): Promise<PivotLoadResponse>;

  async drilldown(request: PivotDrilldownRequest): Promise<PivotDrilldownResponse>;

  async filterValues(
    request: PivotFilterValuesRequest,
  ): Promise<PivotFilterValuesResponse>;
}
```

---

### `ServerPivotEngineAdapter`

Remote adapter forwards requests to a framework-agnostic `PivotRemoteStore`.

```ts
class ServerPivotEngineAdapter {
  load(request: PivotLoadRequest, signal?: AbortSignal);

  drilldown(request: PivotDrilldownRequest, signal?: AbortSignal);

  filterValues(request: PivotFilterValuesRequest, signal?: AbortSignal);
}
```

---

### `createGridModelFromPivotResponse`

Converts a pivot response into the visible source/columns payload consumed by
the plugin.

```ts
export function createGridModelFromPivotResponse(
  config: Partial<PivotConfig>,
  response: PivotLoadResponse,
): PivotGridModel;
```

---

### `materializePivotRows`

Materializes cell-level remote responses into row records keyed by row path.
Pre-materialized row records are shallow-copied to attach semantic metadata.

```ts
export function materializePivotRows(
  config: Partial<PivotConfig>,
  response: PivotLoadResponse,
  materializedColumnPaths?: PivotGroupValue[][],
);
```

---

### `materializePivotGroupAggregates`

Adds semantic group-path metadata to remote aggregate payloads without
changing their legacy grouped-path keys.

```ts
export function materializePivotGroupAggregates(
  config: Partial<PivotConfig>,
  groupAggregates: Record<string, DataType> = {},
);
```

---

### `materializePivotSemanticGroupAggregates`

Builds a collision-safe semantic aggregate index for analytical consumers.
The legacy keyed record above remains dedicated to RevoGrid's grouping UI.

```ts
export function materializePivotSemanticGroupAggregates(
  config: Partial<PivotConfig>,
  groupAggregates: Record<string, DataType> = {},
);
```

---

### `exportVisiblePivotToCsv`

Exports the currently visible Pivot grid model to CSV.

```ts
export function exportVisiblePivotToCsv(input: PivotCsvExportInput): string;
```

---

### `flattenPivotCsvColumns`

Flattens grouped Pivot headers into one leaf entry per visible value column.

```ts
export function flattenPivotCsvColumns(
  columns: Array<ColumnGrouping | ColumnRegular>,
  headerPathDelimiter = DEFAULT_HEADER_PATH_DELIMITER,
): PivotCsvLeafColumn[];
```

---

### `encodeDelimitedCell`

```ts
export function encodeDelimitedCell(
  value: unknown,
  options: PivotDelimitedFormatOptions,
  force = false,
);
```

---

### `PivotCsvExportOptions`

```ts
interface PivotCsvExportOptions {
  /** Cell delimiter. Defaults to comma. */
    columnDelimiter?: string;
  /** Row delimiter. Defaults to CRLF. */
    rowDelimiter?: string;
  /** Prefix the CSV with a UTF-8 BOM. Defaults to false. */
    bom?: boolean;
  /** Separator used when flattening grouped headers. Defaults to ` / `. */
    headerPathDelimiter?: string
}
```

---

### `PivotCsvExportInput` (Extended from `index.ts`)

```ts
interface PivotCsvExportInput {
  /** Current visible Pivot columns. Grouped columns are flattened to leaves. */
    columns: Array<ColumnGrouping | ColumnRegular>;
  /** Current visible body rows. */
    source?: DataType[];
  /** Current visible pinned bottom rows, appended after body rows. */
    pinnedBottomSource?: DataType[]
}
```

---

### `PivotDelimitedFormatOptions`

```ts
interface PivotDelimitedFormatOptions {
  columnDelimiter: string;
  rowDelimiter: string
}
```

---

### `buildPivotCopyTsv`

Builds clipboard-ready TSV for the visible Pivot model.

```ts
export function buildPivotCopyTsv(input: PivotTsvCopyInput): string;
```

---

### `flattenPivotCopyColumns`

```ts
export function flattenPivotCopyColumns(
  columns: Array<ColumnGrouping | ColumnRegular>,
): PivotCopyLeafColumn[];
```

---

### `PivotTsvCopyInput`

```ts
interface PivotTsvCopyInput {
  /** Current visible Pivot columns. Grouped columns are treated as header levels. */
    columns: Array<ColumnGrouping | ColumnRegular>;
  /** Current visible body rows. */
    source?: DataType[];
  /** Current visible pinned bottom rows, appended after body rows. */
    pinnedBottomSource?: DataType[];
  /** Optional leaf props to include, in the requested order. */
    selectedProps?: ColumnProp[];
  /** Optional absolute row indexes from source + pinnedBottomSource to include. */
    selectedRowIndexes?: number[];
  /** Optional rows to include instead of source + pinnedBottomSource. */
    selectedRows?: DataType[];
  /** Cell delimiter. Defaults to tab. */
    columnDelimiter?: string;
  /** Row delimiter. Defaults to LF, matching clipboard text conventions. */
    rowDelimiter?: string;
  /** Optional display transformation applied before TSV escaping. */
    formatValue?: (
      value: unknown,
      column: PivotCopyLeafColumn,
      row: DataType,
    ) => unknown
}
```

---

### `PivotCopyLeafColumn`

```ts
interface PivotCopyLeafColumn {
  prop: ColumnProp;
  headers: string[];
  rowAxis: boolean
}
```

---

### `createPivotFilterChips`

Converts RevoGrid and/or Pivot expression filters into render-ready chip models.

```ts
export function createPivotFilterChips(
  input: PivotFilterChipInput,
  options: PivotFilterChipOptions = {},
): PivotFilterChip[];
```

---

### `createPivotFilterChipsFromCollection`

Converts a RevoGrid filter collection into render-ready chip models.

```ts
export function createPivotFilterChipsFromCollection(
  collection?: Record<ColumnProp, FilterCollectionItem>,
  options: PivotFilterChipOptions = {},
): PivotFilterChip[];
```

---

### `createPivotFilterChipsFromExpression`

Converts a Pivot remote filter expression into render-ready chip models.

```ts
export function createPivotFilterChipsFromExpression(
  expression?: PivotFilterExpression,
  options: PivotFilterChipOptions = {},
): PivotFilterChip[];
```

---

### `createPivotFilterClearOneIntent`

Builds an intent payload for clearing a single visible filter chip.

```ts
export function createPivotFilterClearOneIntent(chip: PivotFilterChip): PivotFilterClearOneIntent;
```

---

### `createPivotFilterClearAllIntent`

Builds an intent payload for clearing every visible filter chip.

```ts
export function createPivotFilterClearAllIntent(chips: readonly PivotFilterChip[] = []): PivotFilterClearAllIntent;
```

---

### `applyPivotFilterClearIntentToCollection`

Applies clear intents to a RevoGrid filter collection without mutating caller state.

```ts
export function applyPivotFilterClearIntentToCollection(
  collection: Record<ColumnProp, FilterCollectionItem> | undefined,
  intent: PivotFilterClearIntent,
): Record<ColumnProp, FilterCollectionItem> | undefined;
```

---

### `PivotFilterChipSource`

```ts
export type PivotFilterChipSource = 'revo-grid' | 'pivot-expression';
```

---

### `PivotFilterChipLabelResolver`

```ts
interface PivotFilterChipLabelResolver {
  /** Optional field-label lookup used instead of raw field selectors. */
    fieldLabel?: (selector: string) => string | undefined;
  /** Optional operation-label lookup used instead of built-in operation labels. */
    operationLabel?: (operation: string) => string | undefined;
  /** Optional value formatter used instead of built-in value labels. */
    valueLabel?: (value: unknown, selector: string, operation: string) => string | undefined
}
```

---

### `PivotFilterChip`

```ts
interface PivotFilterChip {
  /** Stable id for rendering and clear-one actions. */
    id: string;
  /** Original field selector. */
    selector: string;
  /** Human-readable field label. */
    fieldLabel: string;
  /** Filter operation id from RevoGrid or Pivot remote filters. */
    operation: string;
  /** Human-readable operation label. */
    operationLabel: string;
  /** Raw filter value, kept for caller-owned editor or telemetry needs. */
    value: unknown;
  /** Human-readable value label. */
    valueLabel: string;
  /** Complete visible chip label. */
    label: string;
  /** Source filter model used to build the chip. */
    source: PivotFilterChipSource;
  /** Path of the condition inside a Pivot filter expression tree. */
    expressionPath?: readonly number[]
}
```

---

### `PivotFilterChipOptions` (Extended from `index.ts`)

```ts
interface PivotFilterChipOptions {
  /** Prefix included in generated chip ids when multiple Pivot views share UI. */
    idPrefix?: string
}
```

---

### `PivotFilterChipInput`

```ts
interface PivotFilterChipInput {
  /** RevoGrid filter collection from `beforefilterapply`. */
    collection?: Record<ColumnProp, FilterCollectionItem>;
  /** Remote Pivot filter expression tree. */
    expression?: PivotFilterExpression
}
```

---

### `PivotFilterClearOneIntent`

```ts
interface PivotFilterClearOneIntent {
  type: 'clear-one';
  chipId: string;
  selector: string;
  source: PivotFilterChipSource;
  expressionPath?: readonly number[]
}
```

---

### `PivotFilterClearAllIntent`

```ts
interface PivotFilterClearAllIntent {
  type: 'clear-all';
  selectors: string[];
  sources: PivotFilterChipSource[]
}
```

---

### `PivotFilterClearIntent`

```ts
export type PivotFilterClearIntent = PivotFilterClearOneIntent | PivotFilterClearAllIntent;
```

---

### `getInclusivePivotFilterValues`

```ts
export function getInclusivePivotFilterValues(
  selection: PivotFilterSelection | undefined,
): PivotFilterScalar[];
```

---

### `isPivotFilterExclusionSelection`

```ts
export function isPivotFilterExclusionSelection(
  selection: PivotFilterSelection | undefined,
): selection is Exclude<PivotFilterSelection, unknown[]>;
```

---

### `hasActivePivotFilterSelection`

```ts
export function hasActivePivotFilterSelection(
  selection: PivotFilterSelection | undefined,
): boolean;
```

---

### `clonePivotFilterSelectionMap`

```ts
export function clonePivotFilterSelectionMap(
  selections: PivotFilterSelectionMap,
): PivotFilterSelectionMap;
```

---

### `getPivotMemberFilterProps`

Fields whose member predicates participate in the current Pivot layout.

```ts
export function getPivotMemberFilterProps(
  config: PivotMemberFilterConfig,
): ColumnProp[];
```

---

### `prunePivotFilterSelections`

Drops hidden predicates after a field leaves every filterable layout role.

```ts
export function prunePivotFilterSelections(
  config: PivotMemberFilterConfig,
): PivotFilterSelectionMap;
```

---

### `filterPivotSource`

Filters raw client-side rows before Pivot grouping and aggregation.
Inclusive arrays use OR within a field; exclusion selections invert that
field predicate. Independent fields retain AND semantics.

```ts
export function filterPivotSource<T extends DataType>(
  source: T[],
  config: PivotMemberFilterConfig,
): T[];
```

---

### `PivotMemberFilterConfig`

```ts
export type PivotMemberFilterConfig = Pick<
  Partial<PivotConfig>,
  'rows' | 'columns' | 'filters' | 'filterSelections'
>;
```

---

### `createPivotDiagnosticsModel`

Converts remote Pivot response metadata into render-ready diagnostics rows and chips.

```ts
export function createPivotDiagnosticsModel(
  response: PivotDiagnosticsResponseInput,
  options: PivotDiagnosticsFormatterOptions = {},
): PivotDiagnosticsModel;
```

---

### `PivotDiagnosticTone`

```ts
export type PivotDiagnosticTone = 'neutral' | 'success' | 'warning';
```

---

### `PivotDiagnosticRow`

```ts
interface PivotDiagnosticRow {
  /** Stable id for row rendering and tests. */
    id: 'elapsed' | 'generatedAt' | 'visibleRows' | 'visibleColumns';
  /** Human-readable row label. */
    label: string;
  /** Human-readable row value. */
    value: string;
  /** Raw value kept for sorting, telemetry, or custom formatting. */
    rawValue?: string | number
}
```

---

### `PivotDiagnosticChip`

```ts
interface PivotDiagnosticChip {
  /** Stable id for chip rendering and tests. */
    id: string;
  /** Human-readable chip label. */
    label: string;
  /** Chip visual tone hint. */
    tone: PivotDiagnosticTone;
  /** Raw value kept for telemetry or custom rendering. */
    rawValue?: string
}
```

---

### `PivotDiagnosticsModel`

```ts
interface PivotDiagnosticsModel {
  rows: PivotDiagnosticRow[];
  chips: PivotDiagnosticChip[];
  warnings: string[];
  hasWarnings: boolean
}
```

---

### `PivotDiagnosticsFormatterLabels`

```ts
interface PivotDiagnosticsFormatterLabels {
  elapsed: string;
  cache: string;
  generatedAt: string;
  visibleRows: string;
  visibleColumns: string;
  warning: string
}
```

---

### `PivotDiagnosticsFormatterOptions`

```ts
interface PivotDiagnosticsFormatterOptions {
  labels?: Partial<PivotDiagnosticsFormatterLabels>;
  formatGeneratedAt?: (generatedAt: string) => string
}
```

---

### `createPivotValueFormatter`

Creates a reusable formatter for Pivot aggregate and axis values.

```ts
export function createPivotValueFormatter(config: PivotValueFormatConfig): PivotValueFormatter;
```

---

### `formatPivotValue`

Formats one Pivot value without keeping formatter state between calls.

```ts
export function formatPivotValue(value: unknown, config: PivotValueFormatConfig): string;
```

---

### `PivotValueFormatPreset`

```ts
export type PivotValueFormatPreset = 'number' | 'currency' | 'percent' | 'date' | 'datetime';
```

---

### `PivotValueFormatBase`

```ts
interface PivotValueFormatBase {
  /** Locale forwarded to the matching Intl formatter. */
    locale?: Intl.LocalesArgument;
  /** Display value for null or undefined input. Defaults to an empty string. */
    nullDisplay?: string;
  /** Display value for values that cannot be formatted by the selected preset. Defaults to an empty string. */
    invalidDisplay?: string
}
```

---

### `PivotNumberFormatConfig` (Extended from `index.ts`)

```ts
interface PivotNumberFormatConfig {
  preset: 'number';
  options?: Intl.NumberFormatOptions
}
```

---

### `PivotCurrencyFormatConfig` (Extended from `index.ts`)

```ts
interface PivotCurrencyFormatConfig {
  preset: 'currency';
  currency: string;
  options?: Omit<Intl.NumberFormatOptions, 'style' | 'currency'>
}
```

---

### `PivotPercentFormatConfig` (Extended from `index.ts`)

```ts
interface PivotPercentFormatConfig {
  preset: 'percent';
  options?: Omit<Intl.NumberFormatOptions, 'style'>
}
```

---

### `PivotDateFormatConfig` (Extended from `index.ts`)

```ts
interface PivotDateFormatConfig {
  preset: 'date';
  options?: Intl.DateTimeFormatOptions
}
```

---

### `PivotDateTimeFormatConfig` (Extended from `index.ts`)

```ts
interface PivotDateTimeFormatConfig {
  preset: 'datetime';
  options?: Intl.DateTimeFormatOptions
}
```

---

### `PivotValueFormatConfig`

```ts
export type PivotValueFormatConfig =
  | PivotNumberFormatConfig
  | PivotCurrencyFormatConfig
  | PivotPercentFormatConfig
  | PivotDateFormatConfig
  | PivotDateTimeFormatConfig;
```

---

### `PivotValueFormatter`

```ts
export type PivotValueFormatter = (value: unknown) => string;
```

---

### `serializePivotStateJson`

```ts
export function serializePivotStateJson(
  config: Partial<PivotConfig>,
  options: PivotStateJsonOptions = {},
): string;
```

---

### `createSerializablePivotConfig`

Removes runtime-only values before persisting Pivot state.

```ts
export function createSerializablePivotConfig(
  config: Partial<PivotConfig>,
): Partial<PivotConfig>;
```

---

### `createPivotStateJsonEnvelope`

```ts
export function createPivotStateJsonEnvelope(
  config: Partial<PivotConfig>,
  options: PivotStateJsonOptions = {},
): PivotStateJsonEnvelope;
```

---

### `parsePivotStateJson`

```ts
export function parsePivotStateJson(json: string): Partial<PivotConfig>;
```

---

### `parsePivotStateJsonEnvelope`

```ts
export function parsePivotStateJsonEnvelope(json: string): PivotStateJsonEnvelope;
```

---

### `stableJsonStringify`

```ts
export function stableJsonStringify(value: unknown): string;
```

---

### `PIVOT_STATE_JSON_KIND`

```ts
PIVOT_STATE_JSON_KIND: string;
```

---

### `PIVOT_STATE_JSON_VERSION`

```ts
PIVOT_STATE_JSON_VERSION: 1;
```

---

### `PivotStateJsonEnvelope`

```ts
interface PivotStateJsonEnvelope {
  kind: typeof PIVOT_STATE_JSON_KIND;
  version: typeof PIVOT_STATE_JSON_VERSION;
  config: Partial<PivotConfig>;
  exportedAt?: string
}
```

---

### `PivotStateJsonOptions`

```ts
interface PivotStateJsonOptions {
  /**
     * Timestamp to include in the exported state. Omit it for deterministic JSON
     * without a time field.
     */
    exportedAt?: string | Date;
  /**
     * Adds an export timestamp generated by this callback when `exportedAt` is
     * not provided. This keeps tests deterministic without mocking Date.
     */
    now?: () => string | Date
}
```

---

### `createPivotConditionalCellProperties`

```ts
export function createPivotConditionalCellProperties(
  rules: PivotConditionalFormatRule[],
  options: PivotConditionalCellPropertiesOptions = {},
): PropertiesFunc;
```

---

### `getPivotConditionalCellProperties`

```ts
export function getPivotConditionalCellProperties(
  params: CellTemplateProp,
  rules: PivotConditionalFormatRule[],
  options: PivotConditionalCellPropertiesOptions = {},
): CellProps | undefined;
```

---

### `evaluatePivotConditionalFormatRule`

```ts
export function evaluatePivotConditionalFormatRule(
  value: unknown,
  rule: PivotConditionalFormatRule,
): boolean;
```

---

### `isPivotAnalyticalCell`

```ts
export function isPivotAnalyticalCell(params: Pick<CellTemplateProp, 'column'>): boolean;
```

---

### `PivotConditionalFormatOperator`

```ts
export type PivotConditionalFormatOperator =
  | 'gt'
  | 'lt'
  | 'between'
  | 'equal'
  | 'contains';
```

---

### `PivotConditionalFormatRule`

```ts
interface PivotConditionalFormatRule {
  /** Comparison operation used against the rendered analytical cell value. */
    operator: PivotConditionalFormatOperator;
  /** Comparison value for `gt`, `lt`, `equal`, and `contains`; tuple bounds for `between`. */
    value?: unknown;
  /** Inclusive lower bound for `between` when `value` is not a tuple. */
    min?: unknown;
  /** Inclusive upper bound for `between` when `value` is not a tuple. */
    max?: unknown;
  /** Optional generated value field selector. Omit to target every analytical cell. */
    field?: ColumnProp | ColumnProp[];
  /** Optional class value merged into the returned RevoGrid cell props. */
    class?: CellClassValue;
  /** Optional style value merged into the returned RevoGrid cell props. */
    style?: CellStyleValue;
  /** Additional RevoGrid cell props to return when the rule matches. */
    props?: CellProps;
  /** Makes `equal` and `contains` string comparisons case-sensitive. */
    caseSensitive?: boolean
}
```

---

### `PivotConditionalCellPropertiesOptions`

```ts
interface PivotConditionalCellPropertiesOptions {
  /**
     * Return only the first matching rule or merge all matching rules.
     * Defaults to `first` for predictable conditional-formatting priority.
     */
    match?: 'first' | 'all';
  /** Allows applying rules to non-generated row fields. Defaults to false. */
    includeNonAnalytical?: boolean
}
```

---

### `pivotConditionalFormattingPresets`

```ts
pivotConditionalFormattingPresets: {
  gt: (value: unknown, props?: PivotConditionalFormatPresetProps) => PivotConditionalFormatRule;
  lt: (value: unknown, props?: PivotConditionalFormatPresetProps) => PivotConditionalFormatRule;
  between: (min: unknown, max: unknown, props?: PivotConditionalFormatPresetProps) => PivotConditionalFormatRule;
  equal: (value: unknown, props?: PivotConditionalFormatPresetProps) => PivotConditionalFormatRule;
  textContains: (value: unknown, props?: PivotConditionalFormatPresetProps) => PivotConditionalFormatRule;
};
```

---

### `createPivotSemanticSliceIndex`

Builds the runtime lookup from hierarchy membership discovered during the
original Pivot aggregation pass. Only `hierarchy` is committed publicly;
the Maps remain bound to the successful runtime revision.

```ts
export function createPivotSemanticSliceIndex({
  axis,
  fields,
  fieldLabels,
  nodes,
  rows,
}: CreatePivotSemanticSliceIndexOptions): PivotSemanticSliceIndex;
```

---

### `queryPivotSemanticSlice`

Resolves one immediate-child row slice without scanning or repivoting data.

```ts
export function queryPivotSemanticSlice(
  index: PivotSemanticSliceIndex,
  request: PivotSemanticSliceRequest,
): PivotSemanticSlice;
```

---

### `PivotHierarchyAxis`

```ts
export type PivotHierarchyAxis = 'row' | 'column';
```

---

### `PivotHierarchyLevel`

```ts
interface PivotHierarchyLevel {
  readonly id: string;
  readonly axis: PivotHierarchyAxis;
  readonly index: number;
  readonly prop: ColumnProp;
  readonly label: string
}
```

---

### `PivotHierarchyMember`

```ts
interface PivotHierarchyMember {
  readonly id: string;
  readonly axis: PivotHierarchyAxis;
  readonly hierarchyId: string;
  readonly levelId: string;
  readonly levelIndex: number;
  readonly path: readonly PivotAxisValue[];
  readonly labels: readonly string[];
  readonly parentId?: string;
  readonly hasChildren: boolean;
  readonly childCount: number
}
```

---

### `PivotHierarchyDescriptor`

```ts
interface PivotHierarchyDescriptor {
  readonly id: string;
  readonly axis: PivotHierarchyAxis;
  readonly levels: readonly PivotHierarchyLevel[];
  readonly members: readonly PivotHierarchyMember[]
}
```

---

### `PivotRuntimeHierarchies`

```ts
interface PivotRuntimeHierarchies {
  readonly row?: PivotHierarchyDescriptor;
  readonly column?: PivotHierarchyDescriptor
}
```

---

### `PivotSemanticSliceRequest`

```ts
interface PivotSemanticSliceRequest {
  readonly revision: number;
  /** Parent row path. The result contains its immediate children. */
    readonly rowPath: readonly PivotAxisValue[]
}
```

---

### `PivotSemanticSliceMember`

```ts
interface PivotSemanticSliceMember {
  readonly member: PivotHierarchyMember;
  /** Values-on-rows layouts return one aggregate row per measure. */
    readonly rows: readonly DataType[]
}
```

---

### `PivotSemanticSlice`

```ts
interface PivotSemanticSlice {
  readonly revision: number;
  readonly rowPath: readonly PivotAxisValue[];
  readonly members: readonly PivotSemanticSliceMember[]
}
```

---

### `PivotSemanticHierarchyNodeInput`

```ts
interface PivotSemanticHierarchyNodeInput {
  readonly path: readonly (PivotAxisValue | undefined)[];
  readonly labels: readonly string[];
  readonly childCount: number
}
```

---

### `PivotSemanticSliceIndex`

```ts
interface PivotSemanticSliceIndex {
  readonly hierarchy: PivotHierarchyDescriptor;
  readonly membersByPathId: ReadonlyMap<string, PivotHierarchyMember>;
  readonly childrenByParentPathId: ReadonlyMap<string, readonly PivotHierarchyMember[]>;
  readonly rowsByPathId: ReadonlyMap<string, readonly DataType[]>
}
```

---

### `CreatePivotSemanticSliceIndexOptions`

```ts
interface CreatePivotSemanticSliceIndexOptions {
  readonly axis: PivotHierarchyAxis;
  readonly fields: readonly ColumnProp[];
  readonly fieldLabels: readonly string[];
  readonly nodes: readonly PivotSemanticHierarchyNodeInput[];
  readonly rows: readonly DataType[]
}
```

---

### `applyPivotValueCalculations`

Applies configured show-values calculations to a fully aggregated client
cube. Callers may project hidden totals after this pass.

```ts
export function applyPivotValueCalculations(input: {
  rows: DataType[];
  config: Partial<PivotConfig>;
  columnAxis: PivotColumnAxis;
}): DataType[];
```

---

### `getPivotRawValue`

```ts
export function getPivotRawValue(
  row: DataType | undefined,
  prop: ColumnProp,
): unknown;
```

---

### `PivotValueCalculationType`

```ts
export type PivotValueCalculationType =
  | 'percentOfGrandTotal'
  | 'percentOfRowTotal'
  | 'percentOfColumnTotal'
  | 'percentOfParentRowTotal'
  | 'percentOfParentColumnTotal'
  | 'index'
  | 'differenceFrom'
  | 'percentDifferenceFrom'
  | 'runningTotal'
  | 'percentRunningTotal'
  | 'rank';
```

---

### `PivotValueCalculation`

```ts
export type PivotValueCalculation =
  | {
      type:
        | 'percentOfGrandTotal'
        | 'percentOfRowTotal'
        | 'percentOfColumnTotal'
        | 'percentOfParentRowTotal'
        | 'percentOfParentColumnTotal'
        | 'index';
    }
  | {
      type: 'differenceFrom' | 'percentDifferenceFrom';
      axis: 'rows' | 'columns';
      field: ColumnProp;
      base: 'previous' | 'next' | PivotFilterScalar;
    }
  | {
      type: 'runningTotal' | 'percentRunningTotal';
      axis: 'rows' | 'columns';
      field: ColumnProp;
    }
  | {
      type: 'rank';
      axis: 'rows' | 'columns';
      field: ColumnProp;
      order?: 'asc' | 'desc';
    };
```

---

### `PIVOT_RAW_VALUES`

Raw aggregate values retained when calculated display values replace them.

```ts
PIVOT_RAW_VALUES: typeof PIVOT_RAW_VALUES;
```

---

### `PivotRowWithRawValues` (Extended from `index.ts`)

```ts
export type PivotRowWithRawValues = DataType & {
  [PIVOT_RAW_VALUES]?: Readonly<Record<string, unknown>>;
};
```

---

### `PivotContextMenuPlugin`

#### Dependencies

- **Auto-installed** `ContextMenuPlugin`: Contributes semantic Pivot commands to the shared Pro context menu.
- **Auto-installed** `DialogPlugin`, `ConditionalFormattingDialogPlugin`, `ValueSelectionDialogPlugin`: Uses shared Pro dialog plugins for Pivot context-menu workflows.

```ts
class PivotContextMenuPlugin {
  handleHeaderClick(
    event: CustomEvent<ColumnRegular & { originalEvent?: MouseEvent }>,
  ): boolean;

  attach(host: PivotContextMenuHost): void;

  detach(host?: PivotContextMenuHost): void;
}
```

---

### `PivotContextMenuActionHost`

```ts
interface PivotContextMenuActionHost {
  updatePivotConfig(config: Partial<PivotConfig>): Promise<boolean>;
  setPivotSorting(
      prop: ColumnProp,
      order?: 'asc' | 'desc',
      measure?: PivotMeasureMeta,
    ): Promise<void>
}
```

---

### `PivotContextMenuActions`

```ts
class PivotContextMenuActions {
  moveField(
    context: PivotContextMenuContext,
    target: Exclude<PivotContextMenuFieldRole, 'filters'> | 'filters',
  );

  removeField(context: PivotContextMenuContext);

  setAggregation(context: PivotContextMenuContext, aggregator: string);

  setCalculation(
    context: PivotContextMenuContext,
    calculation?: PivotValueCalculation,
  );

  setFormat(
    context: PivotContextMenuContext,
    format?: PivotValueFormatConfig,
  );

  setValuesOnRows(context: PivotContextMenuContext, valuesOnRows: boolean);

  keepOnly(context: PivotContextMenuContext);

  clearFilter(context: PivotContextMenuContext);

  setFilterSelection(
    context: PivotContextMenuContext,
    selection: PivotFilterSelection,
  );

  setResultFilters(
    context: PivotContextMenuContext,
    resultFilters?: PivotAggregateFilterExpression,
  );

  setConditionalFormatting(
    context: PivotContextMenuContext,
    rules: PivotConditionalFormatRule[],
    match: 'first' | 'all' = 'first',
  );

  toggleGrandTotal(context: PivotContextMenuContext);

  toggleSubtotals(context: PivotContextMenuContext);

  setColumnCollapsed(
    context: PivotContextMenuContext,
    collapsed: boolean,
    all = false,
  );

  setRowsExpanded(
    context: PivotContextMenuContext,
    expanded: boolean,
    all = false,
  );

  sort(context: PivotContextMenuContext, order?: 'asc' | 'desc');
}
```

---

### `resolvePivotContextMenuContext`

```ts
export function resolvePivotContextMenuContext(
  menu: ContextMenuOpenContext,
  snapshot: PivotRuntimeSnapshot,
): PivotContextMenuContext | undefined;
```

---

### `PivotContextMenuHost` (Extended from `index.ts`)

```ts
interface PivotContextMenuHost {
  getRuntimeSnapshot(): PivotRuntimeSnapshot | null;
  getPivotOriginalSource(): readonly DataType[];
  getPivotEngineCapabilities(): PivotEngineCapabilities;
  loadPivotFilterValues(input: {
      field: ColumnProp;
      search?: string;
      offset: number;
      limit: number;
      signal?: AbortSignal;
    }): Promise<PivotFilterValuesResponse>;
  loadPivotDrilldown(input: {
      cell: PivotDrilldownCellRef;
      customColumns?: string[];
      offset: number;
      limit: number;
      signal?: AbortSignal;
    }): Promise<PivotDrilldownResponse>
}
```

---

### `createPivotContextMenuLocaleText`

```ts
export function createPivotContextMenuLocaleText(
  overrides?: Partial<PivotContextMenuLocaleText>,
): PivotContextMenuLocaleText;
```

---

### `formatPivotContextMenuText`

```ts
export function formatPivotContextMenuText(
  template: string,
  values: Record<string, string | number>,
): string;
```

---

### `resolvePivotCopyShortcut`

```ts
export function resolvePivotCopyShortcut(
  translatedShortcut?: string,
  platform = globalThis.navigator?.platform ?? '',
): string;
```

---

### `PIVOT_CONTEXT_MENU_EN`

```ts
PIVOT_CONTEXT_MENU_EN: {
  contextMenuAriaLabel: string;
  moveField: string;
  valuesAxis: string;
  rows: string;
  columns: string;
  sort: string;
  sortAscending: string;
  sortDescending: string;
  clearSort: string;
  filter: string;
  keepOnly: string;
  clearFilter: string;
  moveToRows: string;
  moveToColumns: string;
  moveToValues: string;
  moveToFilters: string;
  removeField: string;
  removeUnavailable: string;
  expand: string;
  collapse: string;
  expandAll: string;
  collapseAll: string;
  totals: string;
  grandTotal: string;
  subtotals: string;
  aggregation: string;
  aggregatorLabels: { sum: string; count: string; avg: string; min: string; max: string; median: string; mode: string; range: string; variance: string; stdDev: string; first: string; last: string; distinct: string; };
  showValuesAs: string;
  noCalculation: string;
  percentOfGrandTotal: string;
  percentOfRowTotal: string;
  percentOfColumnTotal: string;
  percentOfParentRowTotal: string;
  percentOfParentColumnTotal: string;
  index: string;
  runningTotal: string;
  rank: string;
  rankDescending: string;
  differenceFromPrevious: string;
  rowCalculationGroup: string;
  columnCalculationGroup: string;
  numberFormat: string;
  number: string;
  currency: string;
  percent: string;
  clearFormat: string;
  conditionalFormatting: string;
  conditionalFormattingDescription: string;
  rule: string;
  appearance: string;
  preview: string;
  sampleValue: string;
  drillThrough: string;
  drillThroughUnavailable: string;
  copy: string;
  copyWithHeaders: string;
  copyWithPivotHeaders: string;
  export: string;
  exportVisibleCsv: string;
  exportStateJson: string;
  valuesOnRows: string;
  valuesOnColumns: string;
  copyShortcut: string;
  clipboardError: string;
  filterValuesUnavailable: string;
  filterUnavailable: string;
  sortUnavailable: string;
  aggregationUnavailable: string;
  calculationUnavailable: string;
  filterDescription: string;
  resultFilter: string;
  resultFilterDescription: string;
  resultFilterAddCondition: string;
  resultFilterAnd: string;
  resultFilterOr: string;
  resultFilterValueRequired: string;
  searchValues: string;
  selectAllVisible: string;
  filterValuesLabel: string;
  selectedValues: string;
  noValues: string;
  blankValue: string;
  showingValues: string;
  valueCount: string;
  clear: string;
  cancel: string;
  apply: string;
  loadingValues: string;
  loadValuesError: string;
  greaterThan: string;
  lessThan: string;
  greaterThanOrEqual: string;
  lessThanOrEqual: string;
  notEqualTo: string;
  between: string;
  equalTo: string;
  contains: string;
  condition: string;
  value: string;
  secondValue: string;
  background: string;
  text: string;
  valuePlaceholder: string;
  maximumPlaceholder: string;
  clearRules: string;
  loadingRows: string;
  loadRowsError: string;
  close: string;
  closeDialog: string;
  rowCount: string;
};
```

---

### `PivotContextMenuConfig`

```ts
interface PivotContextMenuConfig {
  areas?: Partial<Record<PivotContextMenuSurface, boolean>>;
  items?: Partial<Record<PivotContextMenuItemId, boolean>>;
  allowFieldRemoving?: boolean;
  drillThrough?: false | {
      pageSize?: number;
      columns?: ColumnProp[];
    };
  filter?: false | {
      pageSize?: number;
    };
  clipboard?: false | {
      formatted?: boolean;
    };
  export?: false | {
      fileName?: string;
    };
  localeText?: Partial<PivotContextMenuLocaleText>
}
```

---

### `PivotContextMenuItemId`

```ts
export type PivotContextMenuItemId =
  | 'sort'
  | 'filter'
  | 'move'
  | 'remove'
  | 'expand'
  | 'collapse'
  | 'totals'
  | 'aggregation'
  | 'calculation'
  | 'numberFormat'
  | 'conditionalFormatting'
  | 'drillThrough'
  | 'copy'
  | 'export';
```

---

### `PivotContextMenuLocaleText`

```ts
interface PivotContextMenuLocaleText {
  contextMenuAriaLabel: string;
  moveField: string;
  valuesAxis: string;
  rows: string;
  columns: string;
  sort: string;
  sortAscending: string;
  sortDescending: string;
  clearSort: string;
  filter: string;
  keepOnly: string;
  clearFilter: string;
  moveToRows: string;
  moveToColumns: string;
  moveToValues: string;
  moveToFilters: string;
  removeField: string;
  removeUnavailable: string;
  expand: string;
  collapse: string;
  expandAll: string;
  collapseAll: string;
  totals: string;
  grandTotal: string;
  subtotals: string;
  aggregation: string;
  aggregatorLabels: Record<string, string>;
  showValuesAs: string;
  noCalculation: string;
  percentOfGrandTotal: string;
  percentOfRowTotal: string;
  percentOfColumnTotal: string;
  percentOfParentRowTotal: string;
  percentOfParentColumnTotal: string;
  index: string;
  runningTotal: string;
  rank: string;
  rankDescending: string;
  differenceFromPrevious: string;
  rowCalculationGroup: string;
  columnCalculationGroup: string;
  numberFormat: string;
  number: string;
  currency: string;
  percent: string;
  clearFormat: string;
  conditionalFormatting: string;
  conditionalFormattingDescription: string;
  rule: string;
  appearance: string;
  preview: string;
  sampleValue: string;
  drillThrough: string;
  drillThroughUnavailable: string;
  copy: string;
  copyWithHeaders: string;
  copyWithPivotHeaders: string;
  export: string;
  exportVisibleCsv: string;
  exportStateJson: string;
  valuesOnRows: string;
  valuesOnColumns: string;
  copyShortcut: string;
  clipboardError: string;
  filterValuesUnavailable: string;
  filterUnavailable: string;
  sortUnavailable: string;
  aggregationUnavailable: string;
  calculationUnavailable: string;
  filterDescription: string;
  resultFilter: string;
  resultFilterDescription: string;
  resultFilterAddCondition: string;
  resultFilterAnd: string;
  resultFilterOr: string;
  resultFilterValueRequired: string;
  searchValues: string;
  selectAllVisible: string;
  filterValuesLabel: string;
  selectedValues: string;
  noValues: string;
  blankValue: string;
  showingValues: string;
  valueCount: string;
  clear: string;
  cancel: string;
  apply: string;
  loadingValues: string;
  loadValuesError: string;
  greaterThan: string;
  lessThan: string;
  greaterThanOrEqual: string;
  lessThanOrEqual: string;
  notEqualTo: string;
  between: string;
  equalTo: string;
  contains: string;
  condition: string;
  value: string;
  secondValue: string;
  background: string;
  text: string;
  valuePlaceholder: string;
  maximumPlaceholder: string;
  clearRules: string;
  loadingRows: string;
  loadRowsError: string;
  close: string;
  closeDialog: string;
  rowCount: string
}
```

---

### `PivotContextMenuSurface`

```ts
export type PivotContextMenuSurface =
  | 'rowFieldHeader'
  | 'compactRowFieldHeader'
  | 'columnMemberHeader'
  | 'measureHeader'
  | 'rowMemberCell'
  | 'rowGroupCell'
  | 'valueCell'
  | 'subtotalCell'
  | 'grandTotalCell'
  | 'collapsedColumn';
```

---

### `PivotContextMenuFieldRole`

```ts
export type PivotContextMenuFieldRole =
  | 'rows'
  | 'columns'
  | 'values'
  | 'filters';
```

---

### `PivotContextMenuContext`

```ts
interface PivotContextMenuContext {
  readonly surface: PivotContextMenuSurface;
  readonly menu: ContextMenuOpenContext;
  readonly snapshot: PivotRuntimeSnapshot;
  readonly field?: ColumnProp;
  readonly fields?: readonly ColumnProp[];
  readonly fieldRole?: PivotContextMenuFieldRole;
  readonly valueIndex?: number;
  readonly measure?: PivotMeasureMeta;
  readonly row?: DataType;
  readonly rowMeta?: PivotRowMeta;
  readonly columnMeta?: PivotColumnMeta;
  /** Semantic row property used when the clicked surface has no sortable column. */
    readonly sortProp?: ColumnProp;
  /** Generated value column used to sort aggregated Pivot rows. */
    readonly sortColumnMeta?: PivotColumnMeta;
  readonly groupKey?: string;
  readonly member?: string | number | boolean | null
}
```

---

### `PivotContextMenuCommandDetail`

```ts
interface PivotContextMenuCommandDetail {
  readonly id: PivotContextMenuItemId | string;
  readonly context: PivotContextMenuContext
}
```

---

### `PIVOT_CONTEXT_MENU_COMMAND_EVENT`

```ts
PIVOT_CONTEXT_MENU_COMMAND_EVENT: string;
```

---

### `bindPivotPluginEvents`

Wires grid/plugin events to Pivot orchestration without owning UI rendering,
request mapping, or grid mutations.

**@param** host - Controller facade used to react to RevoGrid events while
  keeping UI lifecycle, grid mutation, and remote request state isolated.

```ts
export function bindPivotPluginEvents(host: PivotEventBindingHost);
```

---

### `createPivotColumnAxis`

Builds lightweight column-path metadata without generating hidden columns.

```ts
export function createPivotColumnAxis(
  config: Partial<PivotConfig>,
  source: DataType[],
): PivotColumnAxis;
```

---

### `PivotColumnAxisNode`

```ts
interface PivotColumnAxisNode {
  readonly path: readonly PivotGroupValue[];
  readonly depth: number;
  readonly key: string;
  readonly children: ReadonlyMap<string, PivotColumnAxisNode>;
  readonly sourceCount: number
}
```

---

### `PivotVisibleColumnBucket`

```ts
interface PivotVisibleColumnBucket {
  readonly kind: 'leaf' | 'collapsed';
  readonly path: readonly PivotGroupValue[];
  readonly key: string;
  /**
     * Subtotals are visible only for expanded ancestors shallower than this
     * depth. A leaf frontier uses the full analytical path depth.
     */
    readonly depth: number
}
```

---

### `PivotColumnAxis`

```ts
interface PivotColumnAxis {
  readonly root: PivotColumnAxisNode;
  readonly keyResolver: PivotColumnPathKeyResolver;
  getNode(path: readonly PivotGroupValue[]): PivotColumnAxisNode | undefined;
  isEffectivelyCollapsed(path: readonly PivotGroupValue[]): boolean;
  getHiddenLeafCount(path: readonly PivotGroupValue[]): number;
  resolveVisibleBucket(path: readonly PivotGroupValue[]): PivotVisibleColumnBucket
}
```

---

### `updatePivotColumnServerState`

Applies one column-group transition to the analytical frontier sent to a
Pivot server.

Expanded and collapsed paths are both explicit because either state can be
the configured default. Collapsing a parent removes descendant exceptions,
keeping request size proportional to the visible expansion frontier rather
than the hidden hierarchy.

```ts
export function updatePivotColumnServerState({
  axis,
  path,
  collapsed,
}: UpdatePivotColumnServerStateOptions): Partial<PivotAxisViewport>;
```

---

### `synchronizePivotColumnServerState`

Synchronizes a column drill frontier, collapsing paths left behind by the
previous frontier and expanding every prefix required by the next one.

```ts
export function synchronizePivotColumnServerState({
  axis,
  from,
  to,
}: SynchronizePivotColumnServerStateOptions): Partial<PivotAxisViewport>;
```

---

### `withPivotCompactCollapsedHeader`

Marks a generated Pivot column group as eligible for the compact,
single-row collapsed-header projection owned by ColumnCollapsePlugin.

Pivot owns this policy because its visible-frontier column generator omits
hidden descendants while a parent is collapsed. The Pro plugin owns only
the reusable rendering mechanism: when every marked top-level group is
collapsible and collapsed, it projects the group headers into their visible
carrier leaves and sets the reactive grouping depth to zero.

Keeping the marker at group creation time avoids a second traversal of the
Pivot hierarchy. The later compact-state check is bounded by the rendered
top-level groups and never materializes or aggregates hidden descendants.

```ts
export function withPivotCompactCollapsedHeader<
  T extends PivotColumnGroupShape,
>(
  group: T,
  config?: Partial<PivotConfig> | null,
): PivotCompactCollapsedHeaderGroup<T>;
```

---

### `getPivotRowProps`

Returns the effective leading row props, including values-on-rows metadata.

```ts
export function getPivotRowProps(config?: Partial<PivotConfig> | null): ColumnProp[];
```

---

### `isPivotRowDrillDownEnabled`

Checks whether Pivot should enable grouped row expansion metadata.

```ts
export function isPivotRowDrillDownEnabled(config?: Partial<PivotConfig> | null);
```

---

### `getPivotGrouping`

Converts Pivot row configuration into RevoGrid grouping options.

```ts
export function getPivotGrouping(config?: Partial<PivotConfig> | null): GroupingOptions | undefined;
```

---

### `isPivotColumnCollapseEnabled`

Returns whether generated Pivot column groups should be collapsible.

```ts
export function isPivotColumnCollapseEnabled(
  config?: Partial<PivotConfig> | null,
  level?: number,
);
```

---

### `isPivotColumnGroupFilteringEnabled`

Returns whether generated collapsed aggregates expose group-level filters.

```ts
export function isPivotColumnGroupFilteringEnabled(
  config?: Partial<PivotConfig> | null,
  level?: number,
);
```

---

### `getPivotColumnCollapsedDefault`

Returns the default collapsed state for enabled generated Pivot column groups.

```ts
export function getPivotColumnCollapsedDefault(
  config?: Partial<PivotConfig> | null,
  level?: number,
);
```

---

### `getPivotColumnCollapsed`

Resolves whether a generated Pivot column group should currently be collapsed.

```ts
export function getPivotColumnCollapsed(
  config: Partial<PivotConfig> | null | undefined,
  key: string,
  level?: number,
);
```

---

### `markPivotRowGenerated`

Marks synthetic Pivot rows so the plugin can distinguish managed source.

```ts
export function markPivotRowGenerated(row: DataType);
```

---

### `isPivotGeneratedSourceRow`

Checks whether a source row was generated by Pivot rather than provided by the caller.

```ts
export function isPivotGeneratedSourceRow(row?: DataType);
```

---

### `isPivotGrandTotalRow`

Checks whether a Pivot row is the synthetic grand total row.

```ts
export function isPivotGrandTotalRow(row?: DataType);
```

---

### `isPivotSubtotalRow`

Checks whether a Pivot row is a generated subtotal row.

```ts
export function isPivotSubtotalRow(row?: DataType);
```

---

### `isPivotTotalRow`

Checks whether a Pivot row is a generated subtotal or grand-total row.

```ts
export function isPivotTotalRow(row?: DataType);
```

---

### `isPivotLeafInSubtotal`

Checks whether a Pivot leaf row belongs under a subtotal row.

```ts
export function isPivotLeafInSubtotal(row: DataType | undefined, subtotalRow: DataType | undefined);
```

---

### `markPivotColumnsGenerated`

Marks all generated Pivot columns recursively.

```ts
export function markPivotColumnsGenerated(
  columns: Array<ColumnGrouping | ColumnRegular>,
): Array<ColumnGrouping | ColumnRegular>;
```

---

### `arePivotGeneratedColumns`

Checks whether an entire column tree was generated by Pivot.

```ts
export function arePivotGeneratedColumns(
  columns: Array<ColumnGrouping | ColumnRegular> = [],
): boolean;
```

---

### `createPivotColumnGroupMeta`

Adds column-collapse metadata to a generated Pivot group when it is useful.

```ts
export function createPivotColumnGroupMeta<T extends Record<string, any>>(
  group: T,
  key: ColumnProp,
  config?: Partial<PivotConfig> | null,
  collapsed = false,
  options: {
    force?: boolean;
    collapsedBucketKey?: ColumnProp;
    filterColumn?: ColumnRegular;
    level?: number;
  } = {},
);
```

---

### `getPivotCollapsedAggregator`

Resolves the measure aggregator used for collapsed placeholder cells.

```ts
export function getPivotCollapsedAggregator(
  config: Partial<PivotConfig> | null | undefined,
  prop: ColumnProp,
  fallback: string,
);
```

---

### `hasPivotMergeBoundary`

```ts
export function hasPivotMergeBoundary(
  items: number[],
  visibleIndex: number,
  source: DataType[],
  currentModel: DataType | undefined,
  prop: ColumnProp,
);
```

---

### `PIVOT_GENERATED`

```ts
PIVOT_GENERATED: string;
```

---

### `PIVOT_GROUP_KEY`

```ts
PIVOT_GROUP_KEY: string;
```

---

### `PIVOT_COLLAPSE_HIDDEN_COUNT`

```ts
PIVOT_COLLAPSE_HIDDEN_COUNT: string;
```

---

### `PIVOT_GRAND_TOTAL_ROW_KEY`

```ts
PIVOT_GRAND_TOTAL_ROW_KEY: string;
```

---

### `PIVOT_VALUE_LABEL`

```ts
PIVOT_VALUE_LABEL: string;
```

---

### `PIVOT_VALUE_PROP`

```ts
PIVOT_VALUE_PROP: string;
```

---

### `resolvePivotGroupLabels`

```ts
export function resolvePivotGroupLabels(
  config?: Partial<PivotConfig> | null,
): ResolvedPivotGroupLabels;
```

---

### `getPivotGroupKey`

```ts
export function getPivotGroupKey(value: PivotGroupValue);
```

---

### `getPivotGroupLabel`

```ts
export function getPivotGroupLabel(
  value: PivotGroupValue,
  labels: ResolvedPivotGroupLabels,
);
```

---

### `getPivotGroupDisplayValue`

```ts
export function getPivotGroupDisplayValue(
  value: PivotGroupValue,
  labels: ResolvedPivotGroupLabels,
);
```

---

### `createColumnLabelProp`

```ts
export function createColumnLabelProp(prop: ColumnProp);
```

---

### `PivotGroupValue`

```ts
export type PivotGroupValue = string | number | boolean | null | undefined;
```

---

### `DEFAULT_EMPTY_GROUP_LABEL`

```ts
DEFAULT_EMPTY_GROUP_LABEL: string;
```

---

### `DEFAULT_NULL_GROUP_LABEL`

```ts
DEFAULT_NULL_GROUP_LABEL: string;
```

---

### `ResolvedPivotGroupLabels`

```ts
interface ResolvedPivotGroupLabels {
  empty: string;
  null: string
}
```

---

### `resolvePivotRowLayout`

```ts
export function resolvePivotRowLayout(
  config?: Partial<PivotConfig> | null,
): PivotRowLayout;
```

---

### `getPivotValueLabel`

```ts
export function getPivotValueLabel({ prop, aggregator, label, name }: PivotConfigValue);
```

---

### `resolvePivotRowAxisLayout`

Resolves the visible row-axis presentation without changing the analytical
row fields used for aggregation, grouping, and remote requests.

```ts
export function resolvePivotRowAxisLayout(
  config?: Partial<PivotConfig> | null,
): PivotRowAxisLayout;
```

---

### `isPivotRowHierarchyEnabled`

Returns whether Pivot has enough row metadata to render a drill-down hierarchy.

```ts
export function isPivotRowHierarchyEnabled(
  config?: Partial<PivotConfig> | null,
);
```

---

### `getPivotCompactRowAxisColumn`

```ts
export function getPivotCompactRowAxisColumn(
  config?: Partial<PivotConfig> | null,
);
```

---

### `materializePivotRowAxisLabels`

Adds the generated compact row label while retaining every analytical row
field on the row record.

```ts
export function materializePivotRowAxisLabels(
  rows: DataType[],
  config?: Partial<PivotConfig> | null,
): DataType[];
```

---

### `PIVOT_ROW_LABEL_PROP`

```ts
PIVOT_ROW_LABEL_PROP: string;
```

---

### `PIVOT_ROW_DEPTH_PADDING`

```ts
PIVOT_ROW_DEPTH_PADDING: 10;
```

---

### `PIVOT_ROW_GROUP_CONTROL_INDENT`

Expand button width (25px), margin (2px), and label gap (4px).

```ts
PIVOT_ROW_GROUP_CONTROL_INDENT: 31;
```

---

### `PIVOT_ROW_AXIS_INSET`

```ts
PIVOT_ROW_AXIS_INSET: string;
```

---

### `PivotRowLayout`

```ts
interface PivotRowLayout {
  /** Source row fields used to aggregate the analytical row path. */
    rowFields: ColumnProp[];
  /** Visible row props rendered in RevoGrid, including the value pseudo-field. */
    props: ColumnProp[];
  /** Whether value measures are materialized as synthetic row members. */
    valuesOnRows: boolean;
  /** True when the advanced rowTree API is controlling placement. */
    explicitRowTree: boolean
}
```

---

### `resolvePivotTotals`

Resolves totals config into a complete object with defaults applied.

```ts
export function resolvePivotTotals(
  totals?: Partial<PivotConfig['totals']>,
): ResolvedPivotTotals;
```

---

### `isPivotSubtotalEnabled`

```ts
export function isPivotSubtotalEnabled(
  totals: ResolvedPivotTotals,
  axis: keyof ResolvedPivotTotals['disabledSubtotals'],
  field: ColumnProp | undefined,
  level: number,
);
```

---

### `getPivotColumnLevelConfig`

Returns the explicit configuration for a zero-based Pivot column level.

```ts
export function getPivotColumnLevelConfig(
  config: Partial<PivotConfig> | null | undefined,
  level: number | undefined,
): PivotColumnLevelConfig | undefined;
```

---

### `isPivotColumnSubtotalEnabled`

Resolves column subtotal visibility while preserving the global subtotal
gate and legacy field/level disable rules.

```ts
export function isPivotColumnSubtotalEnabled(
  config: Partial<PivotConfig> | null | undefined,
  totals: ResolvedPivotTotals,
  field: ColumnProp | undefined,
  level: number,
);
```

---

### `getPivotColumnSubtotalLabel`

```ts
export function getPivotColumnSubtotalLabel(
  config: Partial<PivotConfig> | null | undefined,
  totals: ResolvedPivotTotals,
  level: number,
);
```

---

### `getPivotColumnSubtotalPosition`

```ts
export function getPivotColumnSubtotalPosition(
  config: Partial<PivotConfig> | null | undefined,
  level: number,
): PivotColumnSubtotalPosition;
```

---

### `createPivotColumnPathKeyResolver`

Keeps every non-colliding legacy column key unchanged while assigning a
deterministic typed suffix when distinct analytical paths share that key.

```ts
export function createPivotColumnPathKeyResolver(
  paths: ReadonlyArray<readonly PivotGroupValue[]>,
): PivotColumnPathKeyResolver;
```

---

### `buildLeafColumnKey`

Builds the synthetic column key for a leaf analytical path.

```ts
export function buildLeafColumnKey(
  path: readonly PivotGroupValue[],
  resolver?: PivotColumnPathKeyResolver,
);
```

---

### `buildSubtotalColumnKey`

Builds the subtotal key for an intermediate analytical path.

```ts
export function buildSubtotalColumnKey(
  path: readonly PivotGroupValue[],
  resolver?: PivotColumnPathKeyResolver,
);
```

---

### `buildCollapsedColumnKey`

Builds the collapsed placeholder key for an intermediate analytical path.

```ts
export function buildCollapsedColumnKey(
  path: readonly PivotGroupValue[],
  resolver?: PivotColumnPathKeyResolver,
);
```

---

### `PIVOT_GRAND_TOTAL`

```ts
PIVOT_GRAND_TOTAL: string;
```

---

### `PIVOT_SUBTOTAL`

```ts
PIVOT_SUBTOTAL: string;
```

---

### `PIVOT_COLLAPSE`

```ts
PIVOT_COLLAPSE: string;
```

---

### `PIVOT_SEMANTIC_PATH`

```ts
PIVOT_SEMANTIC_PATH: string;
```

---

### `DEFAULT_GRAND_TOTAL_LABEL`

```ts
DEFAULT_GRAND_TOTAL_LABEL: string;
```

---

### `DEFAULT_SUBTOTAL_LABEL`

```ts
DEFAULT_SUBTOTAL_LABEL: string;
```

---

### `ResolvedPivotTotals`

```ts
interface ResolvedPivotTotals {
  grandTotal: boolean;
  subtotals: boolean;
  disabledSubtotals: {
      rows: ResolvedPivotSubtotalDisableRule;
      columns: ResolvedPivotSubtotalDisableRule;
    };
  grandTotalLabel: string;
  subtotalLabel: string;
  suppressSingleChildSubtotals: boolean;
  suppressGrandTotalWhenSingleLeaf: boolean
}
```

---

### `ResolvedPivotSubtotalDisableRule`

```ts
interface ResolvedPivotSubtotalDisableRule {
  fields: Set<ColumnProp>;
  levels: Set<number>
}
```

---

### `PivotColumnPathKeyResolver`

```ts
interface PivotColumnPathKeyResolver {
  resolve(path: readonly PivotGroupValue[]): string
}
```

---

### `PivotContextMenuDialog`

Pivot compatibility adapter around the shared Pro dialog runtime.

Pivot-specific dialogs keep their established classes while focus,
backdrop, keyboard, and lifecycle behavior remain shared.

```ts
class PivotContextMenuDialog {
  open(title: string, closeLabel: string);

  close(): void;

  createButton(
    label: string,
    action: () => void,
    primary = false,
  ): HTMLButtonElement;

  createElement<K extends keyof HTMLElementTagNameMap>(
    tag: K,
  ): HTMLElementTagNameMap[K];

  createTextNode(text: string): Text;
}
```

---

### `PivotContextMenuDialogs`

```ts
class PivotContextMenuDialogs {
  setRevision(revision: number): void;

  destroy(): void;

  openFilter(
    context: PivotContextMenuContext,
    config: PivotContextMenuConfig,
    locale: PivotContextMenuLocaleText,
  ): void;

  openResultFilter(
    context: PivotContextMenuContext,
    locale: PivotContextMenuLocaleText,
  ): boolean;

  openFilterFieldChooser(
    context: PivotContextMenuContext,
    fields: readonly ColumnProp[],
    config: PivotContextMenuConfig,
    locale: PivotContextMenuLocaleText,
  ): void;

  openConditionalFormatting(
    context: PivotContextMenuContext,
    locale: PivotContextMenuLocaleText,
  ): void;

  openError(
    title: string,
    message: string,
    closeLabel: string,
    closeDialogLabel: string,
  ): void;

  openDrillThrough(
    context: PivotContextMenuContext,
    config: PivotContextMenuConfig,
    locale: PivotContextMenuLocaleText,
  ): void;

  close(): void;

  closePivotDialog(): void;
}
```

---

### `getPivotRootMenuPresentation`

```ts
export function getPivotRootMenuPresentation(
  kind: PivotRootMenuKind,
): PivotRootMenuPresentation;
```

---

### `getPivotActionIcon`

```ts
export function getPivotActionIcon(
  id: PivotContextMenuItemId,
  semanticKey: string,
): string | undefined;
```

---

### `PivotRootMenuKind`

```ts
export type PivotRootMenuKind =
  | PivotContextMenuItemId
  | 'field'
  | 'hierarchy'
  | 'valuesAxis';
```

---

### `PivotRootMenuGroup`

```ts
export type PivotRootMenuGroup =
  | 'query'
  | 'analysis'
  | 'structure'
  | 'clipboard'
  | 'destructive';
```

---

### `createPivotItemId`

```ts
export function createPivotItemId(
  ...parts: Array<string | number>
): string;
```

---

### `PIVOT_CONTEXT_MENU_SEPARATOR`

```ts
PIVOT_CONTEXT_MENU_SEPARATOR: {
  kind: string;
  name: string;
};
```

---

### `PivotContextMenuItemFactory`

```ts
class PivotContextMenuItemFactory {
  root(item: ContextMenuItem, kind: PivotRootMenuKind): ContextMenuItem;

  command(options: PivotCommandOptions): ContextMenuItem;

  radio(options: PivotRadioCommandOptions): ContextMenuItem;

  checkbox(options: PivotCheckboxCommandOptions): ContextMenuItem;

  present(items: ContextMenuItem[]): ContextMenuItem[];
}
```

---

### `PivotContextMenuItems`

```ts
class PivotContextMenuItems {
  build(
    context: PivotContextMenuContext,
    config: PivotContextMenuConfig,
    locale: PivotContextMenuLocaleText,
  ): ContextMenuItem[];
}
```

---

### `copyPivotSelection`

```ts
export async function copyPivotSelection(
  context: PivotContextMenuContext,
  mode: PivotCopyMode,
  formatted = false,
): Promise<void>;
```

---

### `resolveClientDrillThrough`

```ts
export function resolveClientDrillThrough(
  source: DataType[],
  context: PivotContextMenuContext,
): DataType[];
```

---

### `uniquePivotFilterValues`

```ts
export function uniquePivotFilterValues(
  values: unknown[],
): Array<string | number | boolean | null>;
```

---

### `serializePivotScalar`

```ts
export function serializePivotScalar(value: unknown): string;
```

---

### `parsePivotDialogValue`

```ts
export function parsePivotDialogValue(value: string): string | number;
```

---

### `getPivotExportFileName`

```ts
export function getPivotExportFileName(config: PivotContextMenuConfig): string;
```

---

### `createPivotFilterValuesCacheKey`

```ts
export function createPivotFilterValuesCacheKey(
  context: PivotContextMenuContext,
  field: ColumnProp,
  limit: number,
): string;
```

---

### `samePivotCalculation`

```ts
export function samePivotCalculation(
  left: PivotValueCalculation | undefined,
  right: PivotValueCalculation | undefined,
): boolean;
```

---

### `PivotCopyMode`

```ts
export type PivotCopyMode = 'values' | 'headers' | 'pivotHeaders';
```

---

### `createPivotResultFilterEditor`

Reusable condition-list editor used by Pivot result-filter dialogs.

```ts
export function createPivotResultFilterEditor({
  document,
  initialItems,
  locale,
}: ResultFilterEditorOptions): PivotResultFilterEditor;
```

---

### `PivotResultFilterEditor`

```ts
interface PivotResultFilterEditor {
  element: HTMLElement;
  read(): FilterData[]
}
```

---

### `PivotRemoteController`

Owns server/client-adapter Pivot loads: request state, cancellation,
stale-response checks, and pagination synchronization.

#### Dependencies

- **Config integration** `additionalData.pagination`: Reads and writes legacy pagination config to synchronize remote pivot paging.
- **Config integration** `direct-pagination-config`: Reads and writes direct grid.pagination config to synchronize remote pivot paging.
- **Optional** `pagination-capable-plugin`: Calls setPage on a pagination-capable plugin when present.

```ts
class PivotRemoteController {
  setFilterCollection(collection?: Record<ColumnProp, FilterCollectionItem>);

  setFilterItems(filterItems?: MultiFilterItem);

  setResultFilters(filters?: PivotAggregateFilterExpression);

  setSorting(sorting?: SortingOrder, summaryResultId?: string);

  getDisplaySorting(localSorting?: SortingOrder, isRemote = false);

  createLoadRequest(config: Partial<PivotConfig>): PivotLoadRequest;

  getCapabilities(config: Partial<PivotConfig>): PivotEngineCapabilities;

  async loadFilterValues(
    config: Partial<PivotConfig>,
    request: PivotFilterValuesRequest,
    signal?: AbortSignal,
  ): Promise<PivotFilterValuesResponse>;

  async loadDrilldown(
    config: Partial<PivotConfig>,
    request: PivotDrilldownRequest,
    signal?: AbortSignal,
  ): Promise<PivotDrilldownResponse>;

  async apply(config: Partial<PivotConfig>, rowOffset?: number);

  resetPagination();

  invalidateLoad(clearDiagnostics = true);

  clearState();

  getPageRowOffset(detail: PageChangeEvent, config: Partial<PivotConfig>);

  createGridModel(
    config: Partial<PivotConfig>,
    response: PivotLoadResponse,
  ): PivotGridModel;
}
```

---

### `createPivotLoadRequest`

```ts
export function createPivotLoadRequest(overrides: Partial<PivotLoadRequest> = {}): PivotLoadRequest;
```

---

### `pivotFieldRegistry`

```ts
pivotFieldRegistry: PivotFieldRegistry;
```

---

### `flattenPivotAggregateFilterExpression`

Flattens semantic result-filter state for projection and editor adapters.

```ts
export function flattenPivotAggregateFilterExpression(
  expression:
    | PivotAggregateFilterExpression
    | PivotAggregateFilterDescriptor[]
    | undefined,
): FlattenedPivotAggregateFilter[];
```

---

### `getPivotAggregateFilterDescriptors`

Returns every analytical descriptor referenced by a result-filter tree.

```ts
export function getPivotAggregateFilterDescriptors(
  expression:
    | PivotAggregateFilterExpression
    | PivotAggregateFilterDescriptor[]
    | undefined,
): PivotAggregateFilterDescriptor[];
```

---

### `isSamePivotAggregateFilterTarget`

```ts
export function isSamePivotAggregateFilterTarget(
  descriptor: PivotAggregateFilterDescriptor,
  target: PivotAggregateFilterTarget,
): boolean;
```

---

### `pivotFilterOperationToCoreType`

```ts
export function pivotFilterOperationToCoreType(
  operation: PivotFilterOperation,
  negated = false,
): FilterData['type'];
```

---

### `assertPivotAggregateFilterExpression`

Validates serializable semantic HAVING state at persistence boundaries.

```ts
export function assertPivotAggregateFilterExpression(
  value: unknown,
  path = 'resultFilters',
  depth = 0,
): asserts value is PivotAggregateFilterExpression;
```

---

### `PivotAggregateFilterTarget`

```ts
interface PivotAggregateFilterTarget {
  columnPath: PivotAggregateFilterDescriptor['columnPath'];
  columnKind: PivotAggregateColumnKind;
  summary: PivotAggregateFilterDescriptor['summary']
}
```

---

### `FlattenedPivotAggregateFilter`

```ts
interface FlattenedPivotAggregateFilter {
  descriptor: PivotAggregateFilterDescriptor;
  relation?: PivotLogicalOperator;
  negated?: boolean
}
```

---

### `partitionPivotColumnFilters`

Separates ordinary field filters from generated Pivot aggregate filters.

The returned `having` descriptors remain valid independently of the
generated carrier prop used by the current expanded/collapsed projection.

```ts
export function partitionPivotColumnFilters(
  collection: Record<ColumnProp, FilterCollectionItem> | undefined,
  columns: readonly (ColumnGrouping | ColumnRegular)[] = [],
): PartitionedPivotColumnFilters;
```

---

### `partitionPivotColumnFilterItems`

Partitions the complete Core multi-filter model without reducing a column to
its first condition.

Conditions within one column retain their visible AND/OR connector chain.
Independent columns are joined with AND, matching Core and SQL semantics.

```ts
export function partitionPivotColumnFilterItems(
  filterItems: MultiFilterItem | undefined,
  columns: readonly (ColumnGrouping | ColumnRegular)[] = [],
): PartitionedPivotColumnFilterItems;
```

---

### `createPivotAggregateFilterExpression`

Converts Core condition rows for one generated column into a HAVING tree.

```ts
export function createPivotAggregateFilterExpression(
  prop: string,
  items: FilterData[],
  target: PivotAggregateFilterTarget,
): {
  expression?: PivotAggregateFilterExpression;
  unsupported: UnsupportedPivotColumnFilter[];
};
```

---

### `createCoreFilterItemsFromResultFilters`

Rebuilds the transient Core filter adapter for the current Pivot columns.

```ts
export function createCoreFilterItemsFromResultFilters(
  expression:
    | PivotAggregateFilterExpression
    | PivotAggregateFilterDescriptor[]
    | undefined,
  columns: readonly (ColumnGrouping | ColumnRegular)[],
): MultiFilterItem;
```

---

### `PartitionedPivotColumnFilters`

```ts
interface PartitionedPivotColumnFilters {
  baseFilters?: Record<ColumnProp, FilterCollectionItem>;
  having?: PivotAggregateFilterDescriptor[]
}
```

---

### `UnsupportedPivotColumnFilter`

```ts
interface UnsupportedPivotColumnFilter {
  prop: string;
  type: string
}
```

---

### `PartitionedPivotColumnFilterItems`

```ts
interface PartitionedPivotColumnFilterItems {
  /** Full Core filter rows for ordinary source fields. */
    baseFilterItems?: MultiFilterItem;
  /** Semantic HAVING expression for generated aggregate columns. */
    having?: PivotAggregateFilterExpression;
  /** Filters that cannot be represented by the analytical contract. */
    unsupported: UnsupportedPivotColumnFilter[]
}
```

---

### `getPivotDimensionAggregators`

```ts
export function getPivotDimensionAggregators(
  dimension?: PivotConfigDimension,
);
```

---

### `createPivotConfigValue`

```ts
export function createPivotConfigValue(
  prop: ColumnProp,
  dimension?: PivotConfigDimension,
): PivotConfigValue;
```

---

### `movePivotField`

Places one source field using Excel-compatible Pivot roles.
Rows and Columns are exclusive axis placements. Filters and Values are
independent roles, so a field can filter source data without disappearing
from an axis or the summarized values.

```ts
export function movePivotField(
  state: PivotFieldLayoutState,
  _source: PanelType,
  target: Exclude<PanelType, 'dimensions'>,
  prop: ColumnProp,
  options: {
    index?: number;
    createValue: (prop: ColumnProp) => PivotConfigValue;
  },
): PivotFieldLayoutState;
```

---

### `PivotFieldLayoutState`

```ts
interface PivotFieldLayoutState {
  rows: ColumnProp[];
  columns: ColumnProp[];
  values: PivotConfigValue[];
  filters: ColumnProp[]
}
```

---

### `PivotFilterCoordinatorSnapshot`

```ts
interface PivotFilterCoordinatorSnapshot {
  baseFilterItems?: MultiFilterItem;
  resultFilters?: PivotAggregateFilterExpression;
  unsupported: UnsupportedPivotColumnFilter[]
}
```

---

### `PivotFilterCoordinator`

Single Pivot-facing owner for Core filter adapters and semantic result
filters. Member selections stay in `PivotConfig.filterSelections`.

```ts
class PivotFilterCoordinator {
  captureCoreFilters(
    filterItems: MultiFilterItem | undefined,
    columns: readonly (ColumnGrouping | ColumnRegular)[],
  ): PivotFilterCoordinatorSnapshot;

  restoreResultFilters(resultFilters?: PivotAggregateFilterExpression): void;

  replaceResultTarget(
    prop: string,
    target: PivotAggregateFilterTarget,
    items: FilterData[],
  ): PivotFilterCoordinatorSnapshot;

  clearResultTarget(
    target: PivotAggregateFilterTarget,
  ): PivotFilterCoordinatorSnapshot;

  getResultItems(target: PivotAggregateFilterTarget): FilterData[];

  getSnapshot(): PivotFilterCoordinatorSnapshot;
}
```

---

### `PivotGridController`

Owns the RevoGrid-facing state transitions for Pivot mode.

This class deliberately avoids event wiring, remote request construction, and
panel rendering so grid mutation stays isolated from orchestration code.

```ts
class PivotGridController {
  setOriginalData(source: DataType[]);

  setOriginalColumns(columns: (ColumnRegular | ColumnGrouping)[]);

  isPivotManagedSource(source: DataType[] = []);

  isPivotManagedColumns(columns: (ColumnRegular | ColumnGrouping)[] = []);

  activate(config: Partial<PivotConfig>);

  clearGroupAggregates();

  setFilterCollection(
    collection?: Record<ColumnProp, FilterCollectionItem>,
  );

  setResultFilters(filters: PivotConfig['resultFilters']);

  setFilterItems(items?: MultiFilterItem);

  applyClientPivot(config: Partial<PivotConfig>);

  applyRemotePivotModel(
    config: Partial<PivotConfig>,
    gridModel: PivotGridModel,
    groupAggregates: PivotGroupAggregates = {},
    semanticGroupAggregates: PivotGroupAggregates = {},
  );

  clearPivot();

  renderOriginalGrid(
    columns: (ColumnRegular | ColumnGrouping)[] = [],
  );
}
```

---

### `getPivotMeasureCarrier`

```ts
export function getPivotMeasureCarrier(
  values: PivotConfig['values'],
  valueIndex: number,
): ColumnProp;
```

---

### `getPivotMeasureResultId`

```ts
export function getPivotMeasureResultId(
  value: Pick<PivotConfigValue, 'id' | 'prop' | 'aggregator'>,
): string;
```

---

### `createPivotLoadRequestFromConfig`

Builds a complete remote Pivot load request from config plus current UI state.

```ts
export function createPivotLoadRequestFromConfig({
  config,
  rowOffset = config.engine?.rowAxis?.offset ?? 0,
  rowLimit = config.engine?.rowAxis?.limit ?? 100,
  columnOffset = config.engine?.columnAxis?.offset ?? 0,
  columnLimit = config.engine?.columnAxis?.limit ?? 24,
  filters,
  filterItems,
  sorting,
  summaryResultId,
  having,
  requestId = `pivot-${Date.now()}`,
}: PivotLoadRequestMapperOptions): PivotLoadRequest;
```

---

### `toPivotFilterExpressionFromItems`

Converts the complete Core filter model to a server expression tree.

```ts
export function toPivotFilterExpressionFromItems(
  filterItems?: MultiFilterItem,
): PivotFilterExpression | undefined;
```

---

### `normalizePivotFilterCollection`

Removes empty filter entries so server requests only include active predicates.

```ts
export function normalizePivotFilterCollection(collection?: Record<ColumnProp, FilterCollectionItem>);
```

---

### `normalizePivotSorting`

Removes unset sort entries and returns undefined when no remote sorting remains.

```ts
export function normalizePivotSorting(sorting?: SortingOrder);
```

---

### `toPivotSummaryType`

Converts public Pivot aggregator ids into the server-supported summary enum.

```ts
export function toPivotSummaryType(aggregator: string): PivotSummaryType;
```

---

### `toPivotFilterPredicates`

Converts one RevoGrid filter item into transport-neutral predicates.
Both base-field filters and generated aggregate filters use this mapping.

```ts
export function toPivotFilterPredicates(
  filter: FilterCollectionItem,
): PivotFilterPredicate[];
```

---

### `PivotLoadRequestMapperOptions`

```ts
interface PivotLoadRequestMapperOptions {
  /** Pivot configuration from direct `grid.pivot` or the active plugin state. */
    config: Partial<PivotConfig>;
  /** Current row-axis offset, usually derived from pagination. */
    rowOffset?: number;
  /** Current row-axis window size, usually pagination `itemsPerPage`. */
    rowLimit?: number;
  /** Current column-axis offset for server-side column virtualization. */
    columnOffset?: number;
  /** Current column-axis window size for server-side column virtualization. */
    columnLimit?: number;
  /** Normalized RevoGrid filter collection to forward as a Pivot filter tree. */
    filters?: Record<ColumnProp, FilterCollectionItem>;
  /** Complete Core filter rows, including every condition and connector. */
    filterItems?: MultiFilterItem;
  /** Normalized RevoGrid sorting state to forward as Pivot sort descriptors. */
    sorting?: SortingOrder;
  /** Stable result id when the active value-field sort targets one summary. */
    summaryResultId?: string;
  /** Semantic post-aggregation filters for generated Pivot value columns. */
    having?:
      | PivotAggregateFilterExpression
      | PivotAggregateFilterDescriptor[];
  /** Optional stable request id for tests, tracing, or caller-managed correlation. */
    requestId?: string
}
```

---

### `PivotFilterPredicate`

```ts
interface PivotFilterPredicate {
  operation: PivotFilterOperation;
  value: PivotFilterValue
}
```

---

### `createPivotGroupLabelTemplate`

```ts
export function createPivotGroupLabelTemplate(
  groupAggregatesByPath: PivotGroupAggregates,
  options: { subtotalLabel?: string; labelColumnMode?: PivotGroupLabelColumnMode } = {},
): GroupLabelTemplateFunc;
```

---

### `PV_PARENT_CL`

```ts
PV_PARENT_CL: string;
```

---

### `PV_PARENT_CFG_CL`

```ts
PV_PARENT_CFG_CL: string;
```

---

### `PV_PARENT_FIELD_PANEL_CL`

```ts
PV_PARENT_FIELD_PANEL_CL: string;
```

---

### `PivotUiController`

Owns the optional Pivot configurator and compact field-panel DOM lifecycle.

```ts
class PivotUiController {
  attachRootClass();

  detachRootClass();

  setTheme(theme: GridTheme = 'default');

  clear();

  setDiagnostics(diagnostics?: PivotUiDiagnostics);

  updateConfigurator(config?: Partial<PivotConfig>);

  updateFieldPanel(
    config?: Partial<PivotConfig>,
    resizedColumns?: ColumnResizeDetail,
  );
}
```

---

# Pivot Charts

URL: https://pro.rv-grid.com/api/pivot-charts/
Source: src/content/docs/api/pivot-charts.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /**
       * Renderer, complete-data provider, defaults, and safety limits for
       * renderer-neutral Pivot Charts.
       */
      pivotCharts?: PivotChartsConfig;
  /**
       * Optional modeless-dialog and context-menu integration for Pivot Charts.
       */
      pivotChartsUi?: PivotChartsUiConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  'pivot-chart-created': PivotChartCreatedEventDetail;
  'pivot-chart-updated': PivotChartUpdatedEventDetail;
  'pivot-chart-destroyed': PivotChartDestroyedEventDetail;
  'pivot-chart-node-click': PivotChartNodeClickEventDetail;
  'pivot-chart-error': PivotChartErrorEventDetail;
  'pivot-chart-before-drill': PivotChartDrillEventDetail;
  'pivot-chart-drill-start': PivotChartDrillEventDetail;
  'pivot-chart-drilled': PivotChartDrilledEventDetail;
  'pivot-chart-drill-error': PivotChartDrillErrorEventDetail;
  'pivot-chart-drill-reset': PivotChartDrilledEventDetail;
  'pivot-chart-drill-sync': PivotChartDrillSyncEventDetail
}
```

## Plugin API

### `toPivotChartError`

```ts
export function toPivotChartError(
  error: unknown,
  fallbackCode: PivotChartErrorCode = 'CHART_UPDATE_FAILED',
);
```

---

### `PivotChartErrorCode`

```ts
export type PivotChartErrorCode =
  | 'PIVOT_NOT_ACTIVE'
  | 'RENDERER_REQUIRED'
  | 'UNSUPPORTED_CHART_TYPE'
  | 'INVALID_DATA_SHAPE'
  | 'INVALID_SERIES_SELECTION'
  | 'LIMIT_EXCEEDED'
  | 'SERVER_PROVIDER_REQUIRED'
  | 'SERVER_RESPONSE_INCOMPLETE'
  | 'CAPABILITY_UNAVAILABLE'
  | 'CHART_ID_CONFLICT'
  | 'CHART_UPDATE_FAILED';
```

---

### `PivotChartError`

```ts
class PivotChartError {}
```

---

### `PIVOT_CHART_CREATED_EVENT`

```ts
PIVOT_CHART_CREATED_EVENT: string;
```

---

### `PIVOT_CHART_UPDATED_EVENT`

```ts
PIVOT_CHART_UPDATED_EVENT: string;
```

---

### `PIVOT_CHART_DESTROYED_EVENT`

```ts
PIVOT_CHART_DESTROYED_EVENT: string;
```

---

### `PIVOT_CHART_NODE_CLICK_EVENT`

```ts
PIVOT_CHART_NODE_CLICK_EVENT: string;
```

---

### `PIVOT_CHART_ERROR_EVENT`

```ts
PIVOT_CHART_ERROR_EVENT: string;
```

---

### `PIVOT_CHART_BEFORE_DRILL_EVENT`

```ts
PIVOT_CHART_BEFORE_DRILL_EVENT: string;
```

---

### `PIVOT_CHART_DRILL_START_EVENT`

```ts
PIVOT_CHART_DRILL_START_EVENT: string;
```

---

### `PIVOT_CHART_DRILLED_EVENT`

```ts
PIVOT_CHART_DRILLED_EVENT: string;
```

---

### `PIVOT_CHART_DRILL_ERROR_EVENT`

```ts
PIVOT_CHART_DRILL_ERROR_EVENT: string;
```

---

### `PIVOT_CHART_DRILL_RESET_EVENT`

```ts
PIVOT_CHART_DRILL_RESET_EVENT: string;
```

---

### `PIVOT_CHART_DRILL_SYNC_EVENT`

```ts
PIVOT_CHART_DRILL_SYNC_EVENT: string;
```

---

### `createPivotChartAnalyticalFrame`

Produces the renderer-neutral, tidy analytical frame for a projected Pivot
dataset. Each matrix cell becomes one observation with stable category,
series, and measure field IDs.

```ts
export function createPivotChartAnalyticalFrame(
  dataset: Pick<
    PivotChartDataset,
    'categories' | 'series' | 'values' | 'displayValues' | 'hierarchies'
  >,
  labels: {
    category: string;
    series: string;
  } = {
    category: PIVOT_CHART_CATEGORY_FIELD_ID,
    series: PIVOT_CHART_SERIES_FIELD_ID,
  },
): PivotChartAnalyticalFrame;
```

---

### `ensurePivotChartAnalyticalFrame`

```ts
export function ensurePivotChartAnalyticalFrame(
  dataset: PivotChartDataset,
): PivotChartDataset;
```

---

### `PIVOT_CHART_CATEGORY_FIELD_ID`

```ts
PIVOT_CHART_CATEGORY_FIELD_ID: string;
```

---

### `PIVOT_CHART_SERIES_FIELD_ID`

```ts
PIVOT_CHART_SERIES_FIELD_ID: string;
```

---

### `getPivotChartDefinition`

```ts
export function getPivotChartDefinition(
  chartType: PivotChartType,
): PivotChartDefinition<PivotChartType>;
```

---

### `PivotChartFamily`

```ts
export type PivotChartFamily =
  | 'column'
  | 'bar'
  | 'line'
  | 'area'
  | 'partToWhole'
  | 'relationship'
  | 'hierarchical'
  | 'combination'
  | 'statistical'
  | 'specialized'
  | 'kpi'
  | 'polar'
  | 'distribution'
  | 'matrix'
  | 'process'
  | 'flow'
  | 'financial';
```

---

### `PivotChartDataChannel`

```ts
export type PivotChartDataChannel =
  | 'category'
  | 'series'
  | 'value'
  | 'x'
  | 'y'
  | 'size'
  | 'hierarchy'
  | 'weight'
  | 'source'
  | 'target'
  | 'start'
  | 'end'
  | 'low'
  | 'high'
  | 'open'
  | 'close'
  | 'volume'
  | 'actual'
  | 'target'
  | 'variance'
  | 'color'
  | 'shape'
  | 'angle'
  | 'radius'
  | 'parent'
  | 'child'
  | 'facetRow'
  | 'facetColumn'
  | 'label'
  | 'tooltip';
```

---

### `PivotChartChannelRequirement`

```ts
interface PivotChartChannelRequirement {
  channel: PivotChartDataChannel;
  min: number;
  max?: number
}
```

---

### `PivotChartDefinition`

```ts
interface PivotChartDefinition {
  type: TType;
  localization: {
      labelKey: TType;
      descriptionKey: TType;
    };
  family: PivotChartFamily;
  order: number;
  dataView:
      | 'matrix'
      | 'xy'
      | 'hierarchy'
      | 'binned'
      | 'distribution'
      | 'statistical'
      | 'range'
      | 'flow'
      | 'financial'
      | 'kpi'
      | 'calendar';
  channels: readonly PivotChartChannelRequirement[];
  constraints: {
      nonNegative: boolean;
      rowHierarchy: boolean;
      seriesSelection: 'all' | 'firstAvailable';
    };
  interactions: {
      drill: boolean;
      selection: boolean;
      zoom: boolean;
      pan: boolean;
      labels: boolean;
      stacking: boolean;
    };
  presentation: {
      axes: boolean;
      legend: 'series' | 'category' | 'none';
    };
  preview: {
      dataset: PivotChartDataset;
      bindings: PivotChartBindings;
      presentation: PivotChartPresentation;
      aspectRatio: number;
    };
  options: PivotChartOptionsSchema;
  renderer: PivotChartRenderFunction;
  documentationSlug: string
}
```

---

### `PIVOT_CHART_DEFINITIONS`

```ts
PIVOT_CHART_DEFINITIONS: readonly [PivotChartDefinition<"groupedColumn">, PivotChartDefinition<"stackedColumn">, PivotChartDefinition<"normalizedColumn">, PivotChartDefinition<"groupedBar">, PivotChartDefinition<"stackedBar">, PivotChartDefinition<"normalizedBar">, PivotChartDefinition<"line">, PivotChartDefinition<"smoothLine">, PivotChartDefinition<"steppedLine">, PivotChartDefinition<"area">, PivotChartDefinition<"steppedArea">, PivotChartDefinition<"stackedArea">, PivotChartDefinition<"normalizedArea">, PivotChartDefinition<"pie">, PivotChartDefinition<"donut">, PivotChartDefinition<"treemap">, PivotChartDefinition<"sunburst">, PivotChartDefinition<"scatter">, PivotChartDefinition<"bubble">, PivotChartDefinition<"columnLine">, PivotChartDefinition<"areaLine">, PivotChartDefinition<"rangeColumn">, PivotChartDefinition<"rangeBar">, PivotChartDefinition<"rangeArea">, PivotChartDefinition<"confidenceBand">, PivotChartDefinition<"errorInterval">, PivotChartDefinition<"waterfall">, PivotChartDefinition<"lollipop">, PivotChartDefinition<"bullet">, PivotChartDefinition<"semiDonut">, PivotChartDefinition<"rose">, PivotChartDefinition<"radarLine">, PivotChartDefinition<"radarArea">, PivotChartDefinition<"polarColumn">, PivotChartDefinition<"stackedPolarColumn">, PivotChartDefinition<"normalizedPolarColumn">, PivotChartDefinition<"radialBar">, PivotChartDefinition<"multiRingRadialBar">, PivotChartDefinition<"histogram">, PivotChartDefinition<"stripDot">, PivotChartDefinition<"heatmap">, PivotChartDefinition<"calendarHeatmap">, PivotChartDefinition<"densityScatter">, PivotChartDefinition<"icicle">, PivotChartDefinition<"circlePacking">, PivotChartDefinition<"funnel">, PivotChartDefinition<"pyramid">, PivotChartDefinition<"boxPlot">, PivotChartDefinition<"violin">, PivotChartDefinition<"rangeInterval">, PivotChartDefinition<"sankey">, PivotChartDefinition<"chord">, PivotChartDefinition<"candlestick">, PivotChartDefinition<"ohlc">, PivotChartDefinition<"volumePrice">, PivotChartDefinition<"gauge">, PivotChartDefinition<"kpi">, PivotChartDefinition<"progressGauge">, PivotChartDefinition<"connectedScatter">, PivotChartDefinition<"waffle">, PivotChartDefinition<"smallMultiples">, PivotChartDefinition<"annotatedTimeSeries">, PivotChartDefinition<"timelineRange">];
```

---

### `PivotChartType`

```ts
export type PivotChartType =
  typeof PIVOT_CHART_DEFINITIONS[number]['type'];
```

---

### `PIVOT_CHART_TYPES`

```ts
PIVOT_CHART_TYPES: readonly ("line" | "area" | "kpi" | "groupedColumn" | "stackedColumn" | "normalizedColumn" | "groupedBar" | "stackedBar" | "normalizedBar" | "smoothLine" | "steppedLine" | "steppedArea" | "stackedArea" | "normalizedArea" | "pie" | "donut" | "treemap" | "sunburst" | "scatter" | "bubble" | "densityScatter" | "connectedScatter" | "columnLine" | "areaLine" | "rangeColumn" | "rangeBar" | "rangeArea" | "confidenceBand" | "errorInterval" | "waterfall" | "lollipop" | "bullet" | "semiDonut" | "rose" | "radarLine" | "radarArea" | "polarColumn" | "stackedPolarColumn" | "normalizedPolarColumn" | "radialBar" | "multiRingRadialBar" | "histogram" | "stripDot" | "heatmap" | "calendarHeatmap" | "icicle" | "circlePacking" | "funnel" | "pyramid" | "boxPlot" | "violin" | "rangeInterval" | "sankey" | "chord" | "candlestick" | "ohlc" | "volumePrice" | "gauge" | "progressGauge" | "waffle" | "smallMultiples" | "annotatedTimeSeries" | "timelineRange")[];
```

---

### `getPivotChartCatalogExtensionDefinitions`

Resolves definitions for a standalone geographic capability host.

Geographic types are intentionally not accepted by `PivotChartModel` or the
built-in Pivot Charts gallery/renderer. Applications render them explicitly
through `pack.render(...)`, which keeps provider assets and asynchronous map
projection outside the core plugin lifecycle.

```ts
export function getPivotChartCatalogExtensionDefinitions(
  pack?: PivotChartGeographicCapabilityPack,
): readonly PivotChartCatalogExtensionDefinition[];
```

---

### `PivotChartCatalogExtensionDefinition`

```ts
export type PivotChartCatalogExtensionDefinition =
  PivotChartGeographicDefinition;
```

---

### `evaluatePivotChartCatalog`

```ts
export function evaluatePivotChartCatalog(
  context: PivotChartCompatibilityContext,
): PivotChartCompatibility[];
```

---

### `evaluatePivotChartCompatibility`

```ts
export function evaluatePivotChartCompatibility(
  chartType: PivotChartType,
  context: PivotChartCompatibilityContext,
): PivotChartCompatibility;
```

---

### `resolveRelationshipBindings`

```ts
export function resolveRelationshipBindings(
  channels: readonly Extract<PivotChartBindingChannel, 'x' | 'y' | 'size'>[],
  dataset: PivotChartDataset,
  current: PivotChartBindings,
  rebindWhenIncomplete = false,
): PivotChartBindings | undefined;
```

---

### `PivotChartCompatibilityStatus`

```ts
export type PivotChartCompatibilityStatus =
  | 'recommended'
  | 'compatible'
  | 'needsFields'
  | 'unsupported';
```

---

### `PivotChartCompatibilityReason`

```ts
export type PivotChartCompatibilityReason =
  | { code: 'rendererUnsupported' }
  | { code: 'categoriesRequired'; minimum: number }
  | { code: 'seriesRequired'; minimum: number }
  | { code: 'seriesLimit'; maximum: number }
  | { code: 'singleSeriesRequired' }
  | { code: 'rowHierarchyRequired' }
  | { code: 'dateCategoriesRequired' }
  | { code: 'distributionViewRequired' }
  | { code: 'nonNegativeValuesRequired' }
  | {
      code: 'channelRequired';
      channel: Extract<
        PivotChartBindingChannel,
        | 'x'
        | 'y'
        | 'size'
        | SpecializedSeriesChannel
        | 'source'
        | 'target'
        | 'weight'
      >;
    }
  | { code: 'noCompletePoints' }
  | { code: 'nonNegativeSizeRequired' };
```

---

### `PivotChartCompatibility`

```ts
interface PivotChartCompatibility {
  chartType: PivotChartType;
  status: PivotChartCompatibilityStatus;
  reasons: readonly PivotChartCompatibilityReason[];
  score: number;
  inferredPatch?: PivotChartUpdatePatch
}
```

---

### `PivotChartCompatibilityContext`

```ts
interface PivotChartCompatibilityContext {
  dataset?: PivotChartDataset;
  model: PivotChartModel;
  supportedTypes: readonly PivotChartType[]
}
```

---

### `createInitialRowDrillState`

```ts
export function createInitialRowDrillState(
  scope: PivotChartInitialScope,
  revision: number | null = null,
): PivotChartDrillState;
```

---

### `canDrillIntoCategory`

```ts
export function canDrillIntoCategory(category: PivotChartCategory);
```

---

### `canDrillIntoSeries`

```ts
export function canDrillIntoSeries(series: PivotChartSeries);
```

---

### `canDrillIntoTarget`

```ts
export function canDrillIntoTarget(target: PivotChartDrillTarget);
```

---

### `createRowDrillFrame`

```ts
export function createRowDrillFrame(
  category: PivotChartCategory,
): PivotChartDrillFrame;
```

---

### `appendRowDrillFrame`

```ts
export function appendRowDrillFrame(
  state: PivotChartDrillState,
  category: PivotChartCategory,
  revision: number,
): PivotChartDrillState;
```

---

### `appendDrillFrame`

```ts
export function appendDrillFrame(
  state: PivotChartDrillState,
  target: PivotChartDrillTarget,
  revision: number,
): PivotChartDrillState;
```

---

### `drillToFrame`

```ts
export function drillToFrame(
  state: PivotChartDrillState,
  frameIndex: number,
  revision: number,
): PivotChartDrillState;
```

---

### `getParentDrillState`

```ts
export function getParentDrillState(
  state: PivotChartDrillState,
  revision: number,
);
```

---

### `reconcileDrillState`

```ts
export function reconcileDrillState(
  state: PivotChartDrillState,
  pathDepth: number,
  revision: number,
);
```

---

### `createRootPivotChartDrillState`

```ts
export function createRootPivotChartDrillState(
  revision: number | null = null,
): PivotChartDrillState;
```

---

### `parsePivotChartModel`

Parses untrusted JSON into a validated, deeply owned V2 model.

```ts
export function parsePivotChartModel(input: unknown): PivotChartModel;
```

---

### `clonePivotChartModel`

```ts
export function clonePivotChartModel(model: PivotChartModel): PivotChartModel;
```

---

### `mountPivotChart`

Mounts a Pivot Chart into an application-owned container.

Call this after the container exists (for example, in Vue `onMounted`) and
call `destroy()` on the returned ref during application cleanup. The
built-in renderer observes the existing container, so a container that is
initially hidden can become visible later.

**Example:**
```typescript
const chart = await mountPivotChart(grid, {
  container: document.querySelector('#sales-chart')!,
  presentation: { title: 'Sales by region' },
});

// Or embed the built-in configuration UI:
const configurableChart = await mountPivotChart(grid, {
  container: document.querySelector('#chart-editor')!,
  controls: 'standard',
});
```

```ts
export async function mountPivotChart(
  grid: HTMLRevoGridElement,
  {
    controls = 'none',
    ...params
  }: PivotChartMountParams,
): Promise<PivotChartRef>;
```

---

### `PivotChartMountControls`

```ts
export type PivotChartMountControls = 'none' | 'standard';
```

---

### `PivotChartMountParams` (Extended from `index.ts`)

```ts
interface PivotChartMountParams {
  /**
     * `none` renders only the chart. `standard` embeds the built-in gallery,
     * data, customization, drill, table, and export controls.
     *
     * @defaultValue `'none'`
     */
    controls?: PivotChartMountControls
}
```

---

### `createPivotChartOptionsSchema`

```ts
export function createPivotChartOptionsSchema({
  family,
  axes,
  chartType,
}: PivotChartOptionSchemaContext): PivotChartOptionsSchema;
```

---

### `parsePivotChartOptions`

```ts
export function parsePivotChartOptions(
  value: unknown,
  schema: PivotChartOptionsSchema,
): PivotChartOptions;
```

---

### `resolvePivotChartOption`

```ts
export function resolvePivotChartOption(
  options: PivotChartOptions | undefined,
  schema: PivotChartOptionsSchema,
  key: PivotChartOptionKey,
): PivotChartJsonValue | undefined;
```

---

### `PivotChartOptionKey`

```ts
export type PivotChartOptionKey =
  | 'showGridLines'
  | 'markOpacity'
  | 'strokeWidth'
  | 'fillOpacity';
```

---

### `PivotChartBooleanOptionDefinition`

```ts
interface PivotChartBooleanOptionDefinition {
  key: PivotChartOptionKey;
  control: 'boolean';
  defaultValue: boolean
}
```

---

### `PivotChartRangeOptionDefinition`

```ts
interface PivotChartRangeOptionDefinition {
  key: PivotChartOptionKey;
  control: 'range';
  defaultValue: number;
  min: number;
  max: number;
  step: number
}
```

---

### `PivotChartOptionDefinition`

```ts
export type PivotChartOptionDefinition =
  | PivotChartBooleanOptionDefinition
  | PivotChartRangeOptionDefinition;
```

---

### `PivotChartOptionsSchema`

```ts
interface PivotChartOptionsSchema {
  fields: readonly PivotChartOptionDefinition[];
  defaults: Readonly<PivotChartOptions>
}
```

---

### `projectPivotChartDataset`

```ts
export function projectPivotChartDataset(
  snapshot: PivotRuntimeSnapshot,
  context: PivotChartProjectorContext,
  options: PivotChartDataOptions = {},
): PivotChartDataset;
```

---

### `projectPivotChartSemanticSlice`

Projects one already-aggregated semantic child slice through the same matrix
adapter as the root chart. The Pivot query owns hierarchy navigation; this
adapter only maps its committed rows into renderer data.

```ts
export function projectPivotChartSemanticSlice(
  snapshot: PivotRuntimeSnapshot,
  slice: PivotSemanticSlice,
  context: Omit<PivotChartProjectorContext, 'visibleRows'>,
  options: PivotChartDataOptions = {},
): PivotChartDataset;
```

---

### `PIVOT_CHART_MODEL_VERSION`

```ts
PIVOT_CHART_MODEL_VERSION: 2;
```

---

### `PivotChartTotalsMode`

```ts
export type PivotChartTotalsMode = 'none' | 'grand' | 'subtotals' | 'all';
```

---

### `PivotChartTheme`

```ts
export type PivotChartTheme = 'auto' | string;
```

---

### `PivotChartUpdateReason`

```ts
export type PivotChartUpdateReason =
  | 'data'
  | 'options'
  | 'theme'
  | 'relink'
  | 'drill';
```

---

### `PivotChartLegendPosition`

```ts
export type PivotChartLegendPosition = 'top' | 'right' | 'bottom' | 'left' | 'none';
```

---

### `PivotChartAxis`

```ts
export type PivotChartAxis = 'row' | 'column';
```

---

### `PivotChartDrillSyncMode`

```ts
export type PivotChartDrillSyncMode = 'chart' | 'pivot' | 'both' | 'event';
```

---

### `PivotChartLimits`

```ts
interface PivotChartLimits {
  maxCategories: number;
  maxSeries: number;
  maxDataPoints: number
}
```

---

### `DEFAULT_PIVOT_CHART_LIMITS`

```ts
DEFAULT_PIVOT_CHART_LIMITS: Readonly<PivotChartLimits>;
```

---

### `PivotChartMeasure`

```ts
interface PivotChartMeasure {
  prop: ColumnProp;
  aggregator: string;
  label: string
}
```

---

### `PivotChartMeasureSelection`

```ts
export type PivotChartMeasureSelection = Pick<
  PivotChartMeasure,
  'prop' | 'aggregator'
>;
```

---

### `PivotChartMemberKind`

```ts
export type PivotChartMemberKind =
  | 'leaf'
  | 'group'
  | 'subtotal'
  | 'grandTotal'
  | 'collapsed';
```

---

### `PivotChartHierarchyLevel`

```ts
interface PivotChartHierarchyLevel {
  id: string;
  field: ColumnProp;
  label: string;
  index: number
}
```

---

### `PivotChartHierarchyDefinition`

```ts
interface PivotChartHierarchyDefinition {
  id: string;
  axis: PivotChartAxis;
  levels: PivotChartHierarchyLevel[]
}
```

---

### `PivotChartMemberHierarchy`

```ts
interface PivotChartMemberHierarchy {
  axis: PivotChartAxis;
  hierarchyId: string;
  levelId: string;
  levelIndex: number;
  maxLevelIndex: number;
  hasChildren: boolean;
  childCount?: number
}
```

---

### `PivotChartCategory`

```ts
interface PivotChartCategory {
  id: string;
  label: string;
  path: PivotPath;
  labels: string[];
  depth: number;
  kind: PivotChartMemberKind;
  measure?: PivotChartMeasure;
  /** Optional row-axis hierarchy metadata used by drill-aware datasets. */
    hierarchy?: PivotChartMemberHierarchy
}
```

---

### `PivotChartSeries`

```ts
interface PivotChartSeries {
  id: string;
  label: string;
  columnPath: PivotPath;
  labels: string[];
  kind: PivotChartMemberKind;
  prop: ColumnProp;
  /** Fixed measure for values-on-columns layouts; the category owns it for values-on-rows. */
    measure?: PivotChartMeasure;
  /** Optional column-axis hierarchy metadata used by drill-aware datasets. */
    hierarchy?: PivotChartMemberHierarchy
}
```

---

### `PivotChartDataset`

```ts
interface PivotChartDataset {
  revision: number;
  source: 'client' | 'server';
  categories: PivotChartCategory[];
  series: PivotChartSeries[];
  /** Row-major matrix: values[categoryIndex][seriesIndex]. */
    values: Array<Array<number | null>>;
  /** Optional row-major strings for labels and tooltips. */
    displayValues?: Array<Array<string | null>>;
  /** Ordered hierarchy definitions supplied by drill-aware data providers. */
    hierarchies?: {
      row?: PivotChartHierarchyDefinition;
      column?: PivotChartHierarchyDefinition;
    };
  /**
     * Canonical long-form analytical frame. The matrix above is a renderer view
     * retained for efficient Cartesian drawing, while every semantic channel
     * resolves against stable field IDs in this frame.
     */
    analyticalFrame?: PivotChartAnalyticalFrame
}
```

---

### `PivotChartSemanticType`

```ts
export type PivotChartSemanticType =
  | 'category'
  | 'number'
  | 'date'
  | 'geographic'
  | 'identifier';
```

---

### `PivotChartFieldDescriptor`

```ts
interface PivotChartFieldDescriptor {
  id: string;
  label: string;
  role: 'dimension' | 'measure';
  semanticType: PivotChartSemanticType;
  sourceField?: ColumnProp;
  aggregator?: string;
  format?: string
}
```

---

### `PivotChartDimensionValue`

```ts
interface PivotChartDimensionValue {
  value: string | number | boolean | null;
  label: string;
  path?: PivotPath;
  labels?: string[]
}
```

---

### `PivotChartObservation`

```ts
interface PivotChartObservation {
  id: string;
  dimensions: Record<string, PivotChartDimensionValue>;
  measures: Record<string, number | null>;
  displayMeasures?: Record<string, string | null>
}
```

---

### `PivotChartDerivedViews`

```ts
interface PivotChartDerivedViews {
  bins?: PivotChartJsonValue[];
  quantiles?: PivotChartJsonValue[];
  ranges?: PivotChartJsonValue[];
  flowEdges?: PivotChartJsonValue[];
  financial?: PivotChartJsonValue[];
  geographicFeatures?: PivotChartJsonValue[]
}
```

---

### `PivotChartAnalyticalFrame`

```ts
interface PivotChartAnalyticalFrame {
  fields: PivotChartFieldDescriptor[];
  observations: PivotChartObservation[];
  hierarchies?: PivotChartDataset['hierarchies'];
  derived?: PivotChartDerivedViews
}
```

---

### `PivotChartPresentation`

```ts
interface PivotChartPresentation {
  title?: string;
  subtitle?: string;
  legendPosition?: PivotChartLegendPosition;
  dataLabels?: boolean;
  xAxisTitle?: string;
  yAxisTitle?: string
}
```

---

### `PivotChartDataOptions`

```ts
interface PivotChartDataOptions {
  chartType?: PivotChartType;
  seriesIds?: string[];
  /** Measure carried by categories when Pivot values are placed on rows. */
    categoryMeasure?: PivotChartMeasureSelection;
  totals?: PivotChartTotalsMode;
  limits?: Partial<PivotChartLimits>;
  bindings?: PivotChartBindings
}
```

---

### `PivotChartDataScope`

```ts
interface PivotChartDataScope {
  rowPath: PivotPath;
  columnPath?: PivotPath
}
```

---

### `PivotChartDataQueryOptions` (Extended from `index.ts`)

```ts
interface PivotChartDataQueryOptions {
  /** Optional committed semantic scope used for an initial or explicit slice. */
    scope?: PivotChartDataScope
}
```

---

### `PivotChartInitialScope`

```ts
interface PivotChartInitialScope {
  /** Parent row member whose immediate children form the initial categories. */
    rowPath: PivotPath;
  /** Display labels aligned one-to-one with `rowPath` for breadcrumbs. */
    rowLabels: string[];
  /** Parent column member whose immediate children form the initial series. */
    columnPath?: PivotPath;
  /** Display labels aligned one-to-one with `columnPath` for breadcrumbs. */
    columnLabels?: string[]
}
```

---

### `PivotChartCreateParams` (Extended from `index.ts`)

```ts
interface PivotChartCreateParams {
  container: HTMLElement;
  linked?: boolean;
  /** Creation-only semantic scope, persisted as the chart's drill state. */
    initialScope?: PivotChartInitialScope;
  presentation?: PivotChartPresentation;
  theme?: PivotChartTheme;
  chartOptions?: PivotChartOptions;
  /** Controls whether drill navigation is local, Pivot-owned, synchronized, or application-owned. */
    drillSyncMode?: PivotChartDrillSyncMode
}
```

---

### `PivotChartUpdatePatch` (Extended from `index.ts`)

```ts
interface PivotChartUpdatePatch {
  linked?: boolean;
  presentation?: Partial<PivotChartPresentation>;
  theme?: PivotChartTheme;
  chartOptions?: PivotChartOptions;
  drillSyncMode?: PivotChartDrillSyncMode
}
```

---

### `PivotChartJsonValue`

```ts
export type PivotChartJsonValue =
  | null
  | boolean
  | number
  | string
  | PivotChartJsonValue[]
  | { [key: string]: PivotChartJsonValue };
```

---

### `PivotChartBindingChannel`

```ts
export type PivotChartBindingChannel =
  | 'category'
  | 'geographic'
  | 'series'
  | 'value'
  | 'x'
  | 'y'
  | 'size'
  | 'color'
  | 'shape'
  | 'angle'
  | 'radius'
  | 'hierarchy'
  | 'parent'
  | 'child'
  | 'weight'
  | 'source'
  | 'target'
  | 'start'
  | 'end'
  | 'low'
  | 'high'
  | 'open'
  | 'close'
  | 'volume'
  | 'actual'
  | 'target'
  | 'variance'
  | 'facetRow'
  | 'facetColumn'
  | 'label'
  | 'tooltip';
```

---

### `PivotChartBindings`

Stable analytical field IDs assigned to semantic renderer channels.
Empty and omitted channels are equivalent.

```ts
/**
 * Stable analytical field IDs assigned to semantic renderer channels.
 * Empty and omitted channels are equivalent.
 */
export type PivotChartBindings = Partial<
  Record<PivotChartBindingChannel, string[]>
>;
```

---

### `PivotChartOptions`

```ts
export type PivotChartOptions = Record<string, PivotChartJsonValue>;
```

---

### `PivotChartDrillAxisState`

```ts
interface PivotChartDrillAxisState {
  path: PivotPath;
  /** Selected hierarchy level, or `-1` at the hierarchy root. */
    levelIndex: number
}
```

---

### `PivotChartDrillScope`

```ts
interface PivotChartDrillScope {
  row: PivotChartDrillAxisState;
  column: PivotChartDrillAxisState
}
```

---

### `PivotChartDrillFrame` (Extended from `index.ts`)

```ts
interface PivotChartDrillFrame {
  rowLabels: string[];
  columnLabels: string[]
}
```

---

### `PivotChartDrillState`

```ts
interface PivotChartDrillState {
  active: PivotChartDrillScope;
  /** Ordered root-to-current breadcrumb frames. */
    frames: PivotChartDrillFrame[];
  /** Dataset revision that produced the active frame; null until rebound. */
    revision: number | null
}
```

---

### `PivotChartModel`

```ts
interface PivotChartModel {
  version: typeof PIVOT_CHART_MODEL_VERSION;
  chartId: string;
  chartType: PivotChartType;
  linked: boolean;
  totals: PivotChartTotalsMode;
  seriesIds?: string[];
  categoryMeasure?: PivotChartMeasureSelection;
  presentation: PivotChartPresentation;
  theme: PivotChartTheme;
  /** Captured only for an unlinked chart. */
    dataset?: PivotChartDataset;
  bindings: PivotChartBindings;
  chartOptions: PivotChartOptions;
  drill: PivotChartDrillState;
  drillSyncMode: PivotChartDrillSyncMode
}
```

---

### `PivotChartRestoreOptions`

```ts
interface PivotChartRestoreOptions {
  container: HTMLElement;
  chartId?: string
}
```

---

### `PivotChartDownloadFormat`

```ts
export type PivotChartDownloadFormat = 'png' | 'pdf';
```

---

### `PivotChartDownloadOptions`

```ts
interface PivotChartDownloadOptions {
  fileName?: string;
  width?: number;
  height?: number;
  fileFormat?: PivotChartDownloadFormat
}
```

---

### `PivotChartImageOptions`

```ts
interface PivotChartImageOptions {
  width?: number;
  height?: number;
  fileFormat?: 'png'
}
```

---

### `PivotChartNodeClick`

```ts
interface PivotChartNodeClick {
  category: PivotChartCategory;
  series: PivotChartSeries;
  value: number | null;
  /** Bound relationship-channel values for scatter/bubble points. */
    channelValues?: Partial<Record<'x' | 'y' | 'size', number>>;
  /** Series descriptors that own relationship-channel values. */
    channelSeries?: Partial<Record<'x' | 'y' | 'size', PivotChartSeries>>;
  originalEvent?: Event
}
```

---

### `PivotChartTooltipChannel`

```ts
export type PivotChartTooltipChannel = 'x' | 'y' | 'size';
```

---

### `PivotChartTooltipContext`

```ts
interface PivotChartTooltipContext {
  chartId: string;
  chartType: PivotChartType;
  category: PivotChartCategory;
  series: PivotChartSeries;
  value: number | null;
  displayValue: string;
  color: string;
  drillable: boolean;
  channelValues?: Partial<Record<PivotChartTooltipChannel, number>>;
  channelSeries?: Partial<
      Record<PivotChartTooltipChannel, PivotChartSeries>
    >;
  channelDisplayValues?: Partial<
      Record<PivotChartTooltipChannel, string>
    >
}
```

---

### `PivotChartTooltipRow`

```ts
interface PivotChartTooltipRow {
  label: string;
  value: string;
  color?: string
}
```

---

### `PivotChartTooltipContent`

```ts
interface PivotChartTooltipContent {
  title?: string;
  rows?: readonly PivotChartTooltipRow[];
  footer?: string;
  ariaLabel?: string
}
```

---

### `PivotChartTooltipResult`

```ts
export type PivotChartTooltipResult =
  | PivotChartTooltipContent
  | string
  | HTMLElement
  | null
  | undefined;
```

---

### `PivotChartTooltipFormatter`

```ts
export type PivotChartTooltipFormatter = (
  context: PivotChartTooltipContext,
  defaultContent: PivotChartTooltipContent,
) => PivotChartTooltipResult;
```

---

### `PivotChartRenderInput`

```ts
interface PivotChartRenderInput {
  chartId: string;
  container: HTMLElement;
  chartType: PivotChartType;
  dataset: PivotChartDataset;
  bindings: PivotChartBindings;
  presentation: PivotChartPresentation;
  /** Validated chart-specific overrides; omitted keys use catalog defaults. */
    chartOptions?: PivotChartOptions;
  theme: PivotChartTheme;
  localeText: PivotChartsLocaleText;
  /** Preview mode renders decorative, non-interactive compact chart marks. */
    renderMode?: 'chart' | 'preview';
  onNodeClick: (detail: PivotChartNodeClick) => void
}
```

---

### `PivotChartRendererCapabilities`

```ts
interface PivotChartRendererCapabilities {
  supportedTypes: readonly PivotChartType[];
  download?: boolean;
  downloadFormats?: readonly PivotChartDownloadFormat[];
  imageDataUrl?: boolean
}
```

---

### `PivotChartRenderer`

```ts
interface PivotChartRenderer {
  readonly capabilities: PivotChartRendererCapabilities;
  create(
      input: PivotChartRenderInput,
    ): PivotChartRendererInstance | Promise<PivotChartRendererInstance>
}
```

---

### `PivotChartRendererInstance`

```ts
interface PivotChartRendererInstance {
  update(input: PivotChartRenderInput): void | Promise<void>;
  destroy(): void;
  focus?(): void;
  download?(options?: PivotChartDownloadOptions): Promise<void>;
  getImageDataURL?(options?: PivotChartImageOptions): Promise<string>
}
```

---

### `PivotChartDataRequest`

```ts
interface PivotChartDataRequest {
  requestId: string;
  viewId: string;
  fieldsVersion: string;
  loadOptions: PivotLoadOptions;
  uiState?: PivotUiStateHints;
  axisState: {
      rowExpandedPaths?: PivotPath[];
      columnExpandedPaths?: PivotPath[];
    };
  chart: {
      seriesIds?: string[];
      categoryMeasure?: PivotChartMeasureSelection;
      totals: PivotChartTotalsMode;
      limits: PivotChartLimits;
      bindings: PivotChartBindings;
      scope: PivotChartSemanticScope;
    }
}
```

---

### `PivotChartSemanticScope`

```ts
interface PivotChartSemanticScope {
  /** Committed Pivot revision the provider must echo in its response. */
    revision: number;
  /** Active parent row member. The response contains its immediate children. */
    rowPath: PivotPath;
  /** Active parent column member. Reserved for column-axis drill navigation. */
    columnPath: PivotPath;
  /** Absolute immediate-child row depth requested for this frame. */
    rowDepth: number;
  /** Absolute immediate-child column depth requested for this frame. */
    columnDepth: number
}
```

---

### `PivotChartDataResponse`

```ts
interface PivotChartDataResponse {
  requestId: string;
  scope: PivotChartSemanticScope;
  categories: PivotChartCategory[];
  series: PivotChartSeries[];
  values: Array<Array<number | null>>;
  displayValues?: Array<Array<string | null>>;
  hierarchies: {
      row?: PivotChartHierarchyDefinition;
      column?: PivotChartHierarchyDefinition;
    };
  totalCategoryCount: number;
  totalSeriesCount: number
}
```

---

### `PivotChartDataProvider`

```ts
interface PivotChartDataProvider {
  load(
      request: PivotChartDataRequest,
      context: { signal: AbortSignal },
    ): Promise<PivotChartDataResponse>
}
```

---

### `PivotChartsConfig`

```ts
interface PivotChartsConfig {
  renderer?: PivotChartRenderer;
  dataProvider?: PivotChartDataProvider;
  defaultChartType?: PivotChartType;
  defaultTotals?: PivotChartTotalsMode;
  limits?: Partial<PivotChartLimits>;
  localeText?: PivotChartsLocaleTextOptions;
  defaultDrillSyncMode?: PivotChartDrillSyncMode;
  /**
     * Optional application adapter for Pivot synchronization. When omitted,
     * the active Pivot plugin applies the semantic frontier directly.
     */
    synchronizeDrill?: (
      detail: PivotChartDrillSyncEventDetail,
      context: { signal: AbortSignal },
    ) => void | Promise<void>
}
```

---

### `PivotChartsUiConfig`

```ts
interface PivotChartsUiConfig {
  contextMenu?: boolean;
  dialogParent?: HTMLElement
}
```

---

### `PivotChartRef`

```ts
interface PivotChartRef {
  readonly id: string;
  readonly container: HTMLElement;
  readonly model: PivotChartModel;
  update(patch: PivotChartUpdatePatch): Promise<void>;
  canDrillDown(target: PivotChartDrillTarget | PivotChartCategory): boolean;
  drillDown(target: PivotChartDrillTarget | PivotChartCategory): Promise<void>;
  drillUp(): Promise<void>;
  drillTo(frameIndex: number): Promise<void>;
  resetDrill(): Promise<void>;
  retryDrill(): Promise<void>;
  getDrillState(): PivotChartDrillState;
  focus(): void;
  destroy(): void
}
```

---

### `PivotChartDrillTarget`

```ts
export type PivotChartDrillTarget =
  | { axis: 'row'; category: PivotChartCategory }
  | { axis: 'column'; series: PivotChartSeries }
  | {
      axis: 'both';
      category: PivotChartCategory;
      series: PivotChartSeries;
    };
```

---

### `PivotChartDrillAction`

```ts
export type PivotChartDrillAction = 'down' | 'up' | 'to' | 'reset' | 'retry';
```

---

### `PivotChartDrillEventDetail`

```ts
interface PivotChartDrillEventDetail {
  chartId: string;
  action: PivotChartDrillAction;
  from: PivotChartDrillState;
  to: PivotChartDrillState
}
```

---

### `PivotChartDrilledEventDetail` (Extended from `index.ts`)

```ts
interface PivotChartDrilledEventDetail {
  model: PivotChartModel;
  dataset: PivotChartDataset
}
```

---

### `PivotChartDrillErrorEventDetail` (Extended from `index.ts`)

```ts
interface PivotChartDrillErrorEventDetail {
  error: Error
}
```

---

### `PivotChartDrillSyncEventDetail` (Extended from `index.ts`)

```ts
interface PivotChartDrillSyncEventDetail {
  mode: Exclude<PivotChartDrillSyncMode, 'chart'>
}
```

---

### `PivotChartCreatedEventDetail`

```ts
interface PivotChartCreatedEventDetail {
  chartId: string;
  ref: PivotChartRef
}
```

---

### `PivotChartUpdatedEventDetail`

```ts
interface PivotChartUpdatedEventDetail {
  chartId: string;
  reason: PivotChartUpdateReason;
  model: PivotChartModel
}
```

---

### `PivotChartDestroyedEventDetail`

```ts
interface PivotChartDestroyedEventDetail {
  chartId: string
}
```

---

### `PivotChartNodeClickEventDetail` (Extended from `index.ts`)

```ts
interface PivotChartNodeClickEventDetail {
  chartId: string;
  categoryPath: PivotPath;
  columnPath: PivotPath;
  measure?: ColumnProp;
  aggregator?: string
}
```

---

### `PivotChartErrorEventDetail`

```ts
interface PivotChartErrorEventDetail {
  chartId?: string;
  error: Error
}
```

---

### `PivotChartProjectorContext`

```ts
interface PivotChartProjectorContext {
  /** Visible logical body rows after grouping, filtering, and sorting. */
    visibleRows: DataType[];
  /** Grid column types used to preserve measure display formatting. */
    columnTypes?: ColumnTypes;
  localeText?: PivotChartsLocaleText
}
```

---

### `isPivotChartType`

```ts
export function isPivotChartType(value: unknown): value is PivotChartType;
```

---

### `resolvePivotChartLimits`

```ts
export function resolvePivotChartLimits(
  limits?: Partial<PivotChartLimits>,
): PivotChartLimits;
```

---

### `assertPivotChartLimits`

```ts
export function assertPivotChartLimits(
  dataset: Pick<PivotChartDataset, 'categories' | 'series'>,
  limits: PivotChartLimits,
);
```

---

### `selectPivotChartSeries`

```ts
export function selectPivotChartSeries(
  series: PivotChartSeries[],
  seriesIds?: readonly string[],
);
```

---

### `assertPivotChartTypeShape`

```ts
export function assertPivotChartTypeShape(
  chartType: PivotChartType,
  dataset: PivotChartDataset,
  localeText?: PivotChartsLocaleText,
  bindings: PivotChartBindings = {},
);
```

---

### `assertRelationshipChartBindings`

```ts
export function assertRelationshipChartBindings(
  chartType: PivotChartType,
  dataset: PivotChartDataset,
  bindings: PivotChartBindings,
  localeText?: PivotChartsLocaleText,
);
```

---

### `validatePivotChartDataResponse`

```ts
export function validatePivotChartDataResponse(
  response: PivotChartDataResponse,
  request: PivotChartDataRequest,
  limits: PivotChartLimits,
): PivotChartDataset;
```

---

### `assertPivotChartDataset`

```ts
export function assertPivotChartDataset(dataset: PivotChartDataset);
```

---

### `validatePivotChartModel`

```ts
export function validatePivotChartModel(model: unknown): PivotChartModel;
```

---

### `createPivotChartGeographicCapabilityPack`

Creates an opt-in geographic capability. Merely importing Pivot Charts does
not install geographic types or load projection/map data.

```ts
export function createPivotChartGeographicCapabilityPack(
  provider: PivotChartGeographicProvider,
): PivotChartGeographicCapabilityPack;
```

---

### `getAvailablePivotChartGeographicTypes`

```ts
export function getAvailablePivotChartGeographicTypes(
  pack?: PivotChartGeographicCapabilityPack,
): readonly PivotChartGeographicType[];
```

---

### `getPivotChartGeographicDefinitions`

Catalog-extension hook used by gallery hosts. The base catalog remains
unchanged; a host receives no geographic entries until a pack is installed.

```ts
export function getPivotChartGeographicDefinitions(
  pack?: PivotChartGeographicCapabilityPack,
): readonly PivotChartGeographicDefinition[];
```

---

### `isPivotChartGeographicType`

```ts
export function isPivotChartGeographicType(
  value: unknown,
): value is PivotChartGeographicType;
```

---

### `assertGeographicRequest`

```ts
export function assertGeographicRequest(
  request: PivotChartGeographicRequest,
): void;
```

---

### `assertGeographicData`

```ts
export function assertGeographicData(
  data: PivotChartGeographicData,
  request: Pick<PivotChartGeographicRequest, 'chartType' | 'dataset'>,
): void;
```

---

### `PIVOT_CHART_GEOGRAPHIC_DEFINITIONS`

```ts
PIVOT_CHART_GEOGRAPHIC_DEFINITIONS: readonly PivotChartGeographicDefinition[];
```

---

### `PivotChartGeographicDataError`

```ts
class PivotChartGeographicDataError {}
```

---

### `PivotChartGeographicType`

Geographic charts are intentionally not part of the base chart catalog.
Import and install a geographic capability pack to make these types
available.

```ts
/**
 * Geographic charts are intentionally not part of the base chart catalog.
 * Import and install a geographic capability pack to make these types
 * available.
 */
export type PivotChartGeographicType =
  | 'choropleth'
  | 'proportionalSymbolMap'
  | 'geographicHeatmap';
```

---

### `PivotChartGeographicPosition`

```ts
export type PivotChartGeographicPosition = readonly [
  longitude: number,
  latitude: number,
];
```

---

### `PivotChartGeographicViewport`

```ts
interface PivotChartGeographicViewport {
  width: number;
  height: number;
  pixelRatio?: number
}
```

---

### `PivotChartGeographicRequest`

```ts
interface PivotChartGeographicRequest {
  chartId: string;
  chartType: PivotChartGeographicType;
  dataset: PivotChartDataset;
  bindings: PivotChartBindings;
  theme: PivotChartTheme;
  viewport: PivotChartGeographicViewport
}
```

---

### `PivotChartGeographicRegion`

```ts
interface PivotChartGeographicRegion {
  id: string;
  label: string;
  /**
     * Provider-projected SVG path. Projection and map assets remain owned by the
     * provider, keeping them out of the Pivot bundle.
     */
    path: string;
  categoryId: string;
  seriesId: string;
  value: number | null;
  properties?: Record<string, PivotChartJsonValue>
}
```

---

### `PivotChartGeographicSymbol`

```ts
interface PivotChartGeographicSymbol {
  id: string;
  label: string;
  position: PivotChartGeographicPosition;
  /** Provider-projected viewport coordinate used by the optional renderer. */
    projectedPosition: readonly [x: number, y: number];
  categoryId: string;
  seriesId: string;
  value: number | null;
  size: number | null;
  properties?: Record<string, PivotChartJsonValue>
}
```

---

### `PivotChartGeographicHeatPoint`

```ts
interface PivotChartGeographicHeatPoint {
  id: string;
  position: PivotChartGeographicPosition;
  /** Provider-projected viewport coordinate used by the optional renderer. */
    projectedPosition: readonly [x: number, y: number];
  categoryId?: string;
  seriesId?: string;
  value: number;
  radius?: number;
  properties?: Record<string, PivotChartJsonValue>
}
```

---

### `PivotChartChoroplethData` (Extended from `index.ts`)

```ts
interface PivotChartChoroplethData {
  chartType: 'choropleth';
  regions: PivotChartGeographicRegion[]
}
```

---

### `PivotChartProportionalSymbolData` (Extended from `index.ts`)

```ts
interface PivotChartProportionalSymbolData {
  chartType: 'proportionalSymbolMap';
  symbols: PivotChartGeographicSymbol[]
}
```

---

### `PivotChartGeographicHeatmapData` (Extended from `index.ts`)

```ts
interface PivotChartGeographicHeatmapData {
  chartType: 'geographicHeatmap';
  points: PivotChartGeographicHeatPoint[]
}
```

---

### `PivotChartGeographicData`

```ts
export type PivotChartGeographicData =
  | PivotChartChoroplethData
  | PivotChartProportionalSymbolData
  | PivotChartGeographicHeatmapData;
```

---

### `PivotChartGeographicProvider`

```ts
interface PivotChartGeographicProvider {
  readonly id: string;
  readonly supportedTypes: readonly PivotChartGeographicType[];
  /**
     * Loads map data and applies the provider-owned projection. The operation
     * must observe the supplied signal and avoid mutating the request.
     */
    load(
      request: Readonly<PivotChartGeographicRequest>,
      context: { signal: AbortSignal },
    ): Promise<PivotChartGeographicData>
}
```

---

### `PivotChartGeographicDefinition`

```ts
interface PivotChartGeographicDefinition {
  type: PivotChartGeographicType;
  family: 'geographic';
  localization: {
      labelKey: PivotChartGeographicType;
      descriptionKey: PivotChartGeographicType;
    };
  channels: readonly {
      channel: 'geographic' | 'value' | 'size';
      min: number;
      max?: number;
    }[];
  documentationSlug: string
}
```

---

### `PivotChartGeographicCapabilityPack`

```ts
interface PivotChartGeographicCapabilityPack {
  readonly id: string;
  readonly provider: PivotChartGeographicProvider;
  readonly definitions: readonly PivotChartGeographicDefinition[];
  readonly supportedTypes: readonly PivotChartGeographicType[];
  load(
      request: PivotChartGeographicRequest,
      context: { signal: AbortSignal },
    ): Promise<PivotChartGeographicData>;
  /**
     * Starts an asset-free SVG render lifecycle backed by this pack's provider.
     * Provider loads are cancelled when superseded or destroyed.
     */
    render(
      input: PivotChartGeographicRenderInput,
    ): PivotChartGeographicRendererInstance
}
```

---

### `PivotChartGeographicLocaleText`

```ts
interface PivotChartGeographicLocaleText {
  chartAriaLabel(type: PivotChartGeographicType): string;
  loading: string;
  loadError(error: Error): string;
  regionAriaLabel(label: string, value: string): string;
  symbolAriaLabel(label: string, value: string, size: string): string;
  heatPointAriaLabel(value: string): string;
  formatValue(value: number | null): string
}
```

---

### `PivotChartGeographicDatum`

```ts
export type PivotChartGeographicDatum =
  | PivotChartGeographicRegion
  | PivotChartGeographicSymbol
  | PivotChartGeographicHeatPoint;
```

---

### `PivotChartGeographicRenderInput`

```ts
interface PivotChartGeographicRenderInput {
  container: HTMLElement;
  request: PivotChartGeographicRequest;
  localeText: PivotChartGeographicLocaleText;
  onNodeClick?: (
      detail: {
        chartType: PivotChartGeographicType;
        datum: PivotChartGeographicDatum;
        originalEvent: Event;
      },
    ) => void;
  onError?: (error: Error) => void
}
```

---

### `PivotChartGeographicRendererInstance`

```ts
interface PivotChartGeographicRendererInstance {
  readonly ready: Promise<void>;
  update(input: PivotChartGeographicRenderInput): Promise<void>;
  focus(): void;
  destroy(): void
}
```

---

### `PivotChartsPlugin`

Headless Pivot plugin for creating and managing charts from the active
Pivot result.

The plugin owns chart data projection, renderer lifecycle, linked refreshes,
semantic drill-down, persistence, and export. It does not create the chart
dialog; add `PivotChartsUiPlugin` when the standard modeless chart UI
and Pivot context-menu action are required.

Configure the renderer through `grid.pivotCharts` before creating a chart.
Public methods can be called on the installed plugin instance returned by
`grid.getPlugins()`. A `PivotChartRef` offers the same common lifecycle
operations scoped to one chart.

`PivotPlugin` is required. Linked charts read committed Pivot
snapshots and refresh after Pivot data, filter, sorting, grouping, source,
and grid-theme changes. Unlinked charts retain a serializable dataset in
their model and do not follow later Pivot changes.

**Example: Create a linked chart with the built-in renderer.**
```typescript
import {
  PivotChartsPlugin,
  PivotPlugin,
  createPivotChartsRenderer,
  mountPivotChart,
} from '@revolist/pivot';

const grid = document.querySelector('revo-grid')!;
grid.plugins = [PivotPlugin, PivotChartsPlugin];
grid.pivotCharts = {
  renderer: createPivotChartsRenderer(),
  defaultChartType: 'groupedColumn',
};

const chart = await mountPivotChart(grid, {
  container: document.querySelector<HTMLElement>('#sales-chart')!,
  presentation: { title: 'Sales by region' },
});

await chart.update({ chartType: 'stackedColumn' });
```

#### Dependencies

- **Required** `PivotPlugin`: Consumes committed Pivot runtime snapshots and semantic result metadata.
- **Event integration** `PIVOT_MODEL_CHANGED_EVENT`, `afterfilterapply`, `aftersortingapply`, `groupexpandclick`, `aftersourceset`, `afterthemechanged`: Keeps linked charts synchronized with the logical Pivot view.
- **Config integration** `grid.pivotCharts`: Reads the renderer, complete-data provider, defaults, and safety limits.

```ts
class PivotChartsPlugin {
  /**
     * Projects the current committed Pivot result into a renderer-neutral chart
     * dataset.
     *
     * Use this method for custom chart pickers, data previews, compatibility
     * checks, or application renderers. The returned dataset is an immutable
     * cached snapshot; request a new dataset after the Pivot revision changes.
     * `scope` selects a semantic row/column parent and returns its immediate
     * children, which is useful for opening a chart around a Pivot cell.
     *
     * @param options - Series, totals, bindings, limits, chart compatibility, and
     * optional semantic scope for the projection.
     * @returns A validated chart dataset for the active Pivot revision.
     * @throws {@link PivotChartError} When Pivot data is unavailable, a provider
     * response is invalid, safety limits are exceeded, or `chartType` is
     * incompatible with the projected fields.
     *
     * @example Read a scoped dataset before presenting chart choices.
     * ```ts
     * const dataset = await charts.getChartData({
     *   chartType: 'groupedColumn',
     *   totals: 'none',
     *   scope: {
     *     rowPath: ['Canada'],
     *     columnPath: [2024],
     *   },
     * });
     *
     * console.log(dataset.categories, dataset.series, dataset.values);
     * ```
     */
  async getChartData(
    options: PivotChartDataQueryOptions = {},
  ): Promise<PivotChartDataset>;

  /**
     * Creates a chart in an application-owned container.
     *
     * By default the chart is linked to the active Pivot, excludes totals, and
     * uses the configured default chart type. Set `linked: false` to capture the
     * initial projected dataset as a standalone chart that ignores later Pivot
     * changes. Use `initialScope` to start at a semantic hierarchy level while
     * preserving breadcrumb and drill state.
     *
     * @param params - Container, chart type, data selection, presentation,
     * bindings, theme, drill mode, and chart-specific options.
     * @returns A chart reference for updates, drill navigation, focus, and
     * destruction.
     * @throws {TypeError} When `params.container` is not an `HTMLElement`.
     * @throws {@link PivotChartError} When no renderer is configured, the chart
     * type is unsupported, the data is incompatible, or the requested chart ID
     * conflicts with an active or pending chart.
     *
     * @example Create a linked chart at a row hierarchy scope.
     * ```ts
     * const chart = await charts.createChart({
     *   container: document.querySelector<HTMLElement>('#chart')!,
     *   chartType: 'line',
     *   initialScope: {
     *     rowPath: ['Europe'],
     *     rowLabels: ['Europe'],
     *   },
     *   presentation: {
     *     title: 'European performance',
     *     legendPosition: 'bottom',
     *   },
     * });
     * ```
     */
  async createChart(params: PivotChartCreateParams): Promise<PivotChartRef>;

  /**
     * Applies a validated partial update to an existing chart.
     *
     * Renderer updates are serialized so overlapping calls cannot overwrite one
     * another. Changes to totals, series, bindings, or linked state reload chart
     * data; presentation, theme, and chart options update the existing renderer
     * instance when possible.
     *
     * @param chartId - ID returned by {@link createChart} or {@link restoreChart}.
     * @param patch - Chart type, data selection, presentation, theme, bindings,
     * drill mode, or chart-specific options to change.
     * @returns A promise that resolves after the renderer and stored model agree.
     * @throws {@link PivotChartError} When the chart does not exist, the patch is
     * invalid, relinking fails, or the resulting data is incompatible.
     *
     * @example Change the visualization without recreating its container.
     * ```ts
     * await charts.updateChart(chart.id, {
     *   chartType: 'stackedBar',
     *   presentation: {
     *     title: 'Sales contribution',
     *     dataLabels: true,
     *   },
     * });
     * ```
     */
  async updateChart(
    chartId: string,
    patch: PivotChartUpdatePatch,
  ): Promise<void>;

  /**
     * Retries the current chart data/render operation without changing options.
     * UI integrations use this after a transient provider or renderer failure.
     *
     * @param chartId - ID of the chart to reload.
     * @returns A promise that resolves after data and rendering are current.
     * @throws {@link PivotChartError} When the chart does not exist or the retry
     * fails. Aborted superseded refreshes resolve without changing the chart.
     *
     * @example Retry after showing an application-level error state.
     * ```ts
     * try {
     *   await charts.refreshChart(chart.id);
     * } catch (error) {
     *   console.error('Chart refresh failed', error);
     * }
     * ```
     */
  async refreshChart(chartId: string): Promise<void>;

  /**
     * Reports whether a category or explicit semantic target can navigate to a
     * deeper hierarchy level in the current chart frame.
     *
     * The result is `false` for unlinked charts, non-drillable chart types,
     * targets outside the current dataset, and leaf members.
     *
     * @param chartId - ID of the chart to inspect.
     * @param input - A category for row drill-down or an explicit row, column, or
     * two-axis drill target.
     * @returns `true` when {@link drillDownChart} can navigate the target.
     * @throws {@link PivotChartError} When the chart does not exist.
     *
     * @example Enable a custom drill action only for expandable marks.
     * ```ts
     * const category = dataset.categories[0];
     * if (category && charts.canDrillDown(chart.id, category)) {
     *   await charts.drillDownChart(chart.id, category);
     * }
     * ```
     */
  canDrillDown(
    chartId: string,
    input: PivotChartDrillTarget | PivotChartCategory,
  ): boolean;

  /**
     * Navigates a linked chart into the children of a row, column, or combined
     * hierarchy target.
     *
     * Drill behavior follows the chart's `drillSyncMode`: chart-local, Pivot-only,
     * synchronized chart and Pivot, or application-event mode. The operation is
     * cancellable through `pivot-chart-before-drill`.
     *
     * @param chartId - ID of the chart to navigate.
     * @param input - Category or explicit semantic target selected by the user.
     * @returns A promise that resolves after synchronization, data loading, and
     * rendering complete.
     * @throws {@link PivotChartError} When the chart is missing, the target is not
     * drillable, synchronization is unavailable, or scoped data loading fails.
     *
     * @example Drill both chart axes from a relationship-chart point.
     * ```ts
     * await charts.drillDownChart(chart.id, {
     *   axis: 'both',
     *   category: selectedCategory,
     *   series: selectedSeries,
     * });
     * ```
     */
  async drillDownChart(
    chartId: string,
    input: PivotChartDrillTarget | PivotChartCategory,
  ): Promise<void>;

  /**
     * Navigates a chart to the parent of its current drill frame.
     *
     * Calling this method at the root is a no-op and cancels pending drill work.
     *
     * @param chartId - ID of the chart to navigate.
     * @returns A promise that resolves after the parent frame is rendered.
     * @throws {@link PivotChartError} When the chart does not exist or parent
     * synchronization/data loading fails.
     *
     * @example
     * ```ts
     * await charts.drillUpChart(chart.id);
     * ```
     */
  async drillUpChart(chartId: string): Promise<void>;

  /**
     * Navigates directly to an existing breadcrumb frame.
     *
     * Frame indexes use the root-to-current order returned by
     * `chart.getDrillState().frames`; index `0` is the root. Selecting the current
     * frame is a no-op.
     *
     * @param chartId - ID of the chart to navigate.
     * @param frameIndex - Zero-based breadcrumb frame index.
     * @returns A promise that resolves after the selected frame is rendered.
     * @throws {@link PivotChartError} When the chart is missing, the frame index
     * is invalid, or synchronization/data loading fails.
     *
     * @example Return to the first drilled level.
     * ```ts
     * await charts.drillToChart(chart.id, 1);
     * ```
     */
  async drillToChart(chartId: string, frameIndex: number): Promise<void>;

  /**
     * Returns a drilled chart to its root semantic scope.
     *
     * Calling this method at the root is a no-op and cancels pending drill work.
     *
     * @param chartId - ID of the chart to reset.
     * @returns A promise that resolves after the root frame is rendered.
     * @throws {@link PivotChartError} When the chart does not exist or reset
     * synchronization/data loading fails.
     *
     * @example
     * ```ts
     * await charts.resetChartDrill(chart.id);
     * ```
     */
  async resetChartDrill(chartId: string): Promise<void>;

  /**
     * Retries the last failed drill operation for a chart.
     *
     * If no failed drill state exists, this method falls back to
     * {@link refreshChart} without changing the current frame.
     *
     * @param chartId - ID of the chart whose drill should be retried.
     * @returns A promise that resolves after retry or refresh completes.
     * @throws {@link PivotChartError} When the chart does not exist or the retry
     * fails again.
     *
     * @example
     * ```ts
     * grid.addEventListener('pivot-chart-drill-error', async event => {
     *   await charts.retryChartDrill(event.detail.chartId);
     * });
     * ```
     */
  async retryChartDrill(chartId: string): Promise<void>;

  /**
     * Destroys one chart and releases its renderer and pending drill resources.
     *
     * Unknown chart IDs are ignored. The chart's application-owned container is
     * not removed.
     *
     * @param chartId - ID of the chart to destroy.
     *
     * @example
     * ```ts
     * charts.destroyChart(chart.id);
     * ```
     */
  destroyChart(chartId: string): void;

  /**
     * Destroys every chart owned by this plugin instance.
     *
     * Pending creations are invalidated before and after destruction so
     * re-entrant lifecycle handlers cannot leave an untracked chart behind.
     *
     * @example
     * ```ts
     * charts.destroyAllCharts();
     * ```
     */
  destroyAllCharts(): void;

  /**
     * Returns defensive copies of all active chart models.
     *
     * Persist these models to restore linked chart configuration or complete
     * unlinked chart snapshots later. Mutating the returned objects does not
     * change active charts.
     *
     * @returns Serializable chart models in creation order.
     *
     * @example Save chart state.
     * ```ts
     * localStorage.setItem(
     *   'pivot-charts',
     *   JSON.stringify(charts.getChartModels()),
     * );
     * ```
     */
  getChartModels(): PivotChartModel[];

  /**
     * Restores a validated chart model into a new container.
     *
     * Linked models reload the current Pivot data and retain the deepest valid
     * drill ancestor. Unlinked models render their captured dataset. Pass
     * `options.chartId` to override the persisted ID when restoring multiple
     * copies of the same model.
     *
     * @param model - Previously persisted chart model.
     * @param options - Destination container and optional replacement chart ID.
     * @returns A new chart reference managed by this plugin.
     * @throws {@link PivotChartError} When the model is invalid, its chart ID is
     * already active or pending, or current data cannot satisfy the model.
     *
     * @example Restore persisted charts into application containers.
     * ```ts
     * const [saved] = JSON.parse(
     *   localStorage.getItem('pivot-charts') ?? '[]',
     * );
     *
     * if (saved) {
     *   await charts.restoreChart(saved, {
     *     container: document.querySelector<HTMLElement>('#restored-chart')!,
     *   });
     * }
     * ```
     */
  async restoreChart(
    model: PivotChartModel,
    options: PivotChartRestoreOptions,
  ): Promise<PivotChartRef>;

  /**
     * Downloads a rendered chart through the configured renderer.
     *
     * The built-in renderer supports PNG and PDF. Custom renderers advertise
     * their formats through `capabilities.downloadFormats`.
     *
     * @param chartId - ID of the chart to export.
     * @param options - File name, dimensions, and output format.
     * @returns A promise that resolves after the renderer starts or completes the
     * download.
     * @throws {@link PivotChartError} When the chart is missing or the renderer
     * does not support downloads or the requested format.
     *
     * @example Export the current chart as PDF.
     * ```ts
     * await charts.downloadChart(chart.id, {
     *   fileName: 'quarterly-sales',
     *   fileFormat: 'pdf',
     *   width: 1600,
     *   height: 900,
     * });
     * ```
     */
  async downloadChart(
    chartId: string,
    options?: PivotChartDownloadOptions,
  ): Promise<void>;

  /**
     * Encodes a chart as an image data URL without triggering a download.
     *
     * Use this for application previews, reports, clipboard workflows, or custom
     * persistence. Renderer support is optional and declared by
     * `capabilities.imageDataUrl`.
     *
     * @param chartId - ID of the chart to encode.
     * @param options - Optional output width, height, and PNG format.
     * @returns A PNG data URL generated by the renderer.
     * @throws {@link PivotChartError} When the chart is missing or its renderer
     * cannot create image data URLs.
     *
     * @example Show a chart image in an application-owned preview.
     * ```ts
     * const image = document.querySelector<HTMLImageElement>('#chart-preview')!;
     * image.src = await charts.getChartImageDataURL(chart.id, {
     *   width: 1200,
     *   height: 675,
     * });
     * ```
     */
  async getChartImageDataURL(
    chartId: string,
    options?: PivotChartImageOptions,
  ): Promise<string>;
}
```

---

### `createPivotChartsLocaleText`

```ts
export function createPivotChartsLocaleText(
  localeText?: PivotChartsLocaleTextOptions,
): PivotChartsLocaleText;
```

---

### `PivotChartDatumLocaleContext`

```ts
interface PivotChartDatumLocaleContext {
  category: PivotChartCategory;
  series: PivotChartSeries;
  value: number | null;
  displayValue: string
}
```

---

### `PivotChartRelationshipDatumLocaleContext`

```ts
interface PivotChartRelationshipDatumLocaleContext {
  category: PivotChartCategory;
  x: { series: PivotChartSeries; value: number; displayValue: string };
  y: { series: PivotChartSeries; value: number; displayValue: string };
  size?: { series: PivotChartSeries; value: number; displayValue: string }
}
```

---

### `PivotChartsLocaleText`

```ts
interface PivotChartsLocaleText {
  dialog: {
      kicker: string;
      untitledChart: string;
      chartAriaLabel: (title: string | undefined) => string;
      settingsAriaLabel: string;
    };
  actions: {
      exportChart: string;
      downloadPng: string;
      downloadPdf: string;
      close: string;
      closeButtonText: string;
      retry: string;
      viewData: string;
      viewChart: string;
    };
  status: {
      loading: string;
      empty: string;
      formatError: (error: Error) => string;
    };
  drill: {
      toolbarAriaLabel: string;
      breadcrumbAriaLabel: string;
      root: string;
      currentLevel: (label: string) => string;
      loading: (label: string) => string;
      loaded: (label: string) => string;
      retry: string;
      formatError: (error: Error) => string;
      drillableDatum: (context: PivotChartDatumLocaleContext) => string;
      relationshipDrillableDatum:
        (context: PivotChartRelationshipDatumLocaleContext) => string;
    };
  controls: {
      chartType: string;
      valueSeries: string;
      xMeasure: string;
      yMeasure: string;
      sizeMeasure: string;
      title: string;
      subtitle: string;
      legend: string;
      dataLabels: string;
      xAxisTitle: string;
      yAxisTitle: string;
      totals: string;
      drillSyncMode: string;
      theme: string;
      keepLinked: string;
    };
  chartOptions: {
      heading: string;
      description: string;
      resetAll: string;
      resetOption: (label: string) => string;
      valueLabel: (label: string, value: number) => string;
      labels: Record<PivotChartOptionKey, string>;
      descriptions: Record<PivotChartOptionKey, string>;
    };
  gallery: {
      tabs: {
        chart: string;
        data: string;
        customize: string;
      };
      searchPlaceholder: string;
      searchAriaLabel: string;
      recommended: string;
      families: Record<PivotChartFamily, string>;
      noResults: string;
      compatibilityReason: (reason: PivotChartCompatibilityReason) => string;
    };
  chartTypes: Record<PivotChartType, string>;
  chartDescriptions: Record<PivotChartType, string>;
  legendPositions: {
      automatic: string;
      top: string;
      right: string;
      bottom: string;
      left: string;
      none: string;
    };
  totals: Record<PivotChartTotalsMode, string>;
  drillSyncModes: Record<PivotChartDrillSyncMode, string>;
  themes: {
      auto: string;
      default: string;
      material: string;
      compact: string;
      darkMaterial: string;
      darkCompact: string;
      custom: (theme: string) => string;
    };
  contextMenu: {
      createChart: string;
      pluginRequired: string;
      rendererRequired: string;
      serverProviderRequired: string;
    };
  uiErrors: {
      destroyed: string;
      containerMissing: string;
      mountContainerRequired: string;
      creationClosed: string;
      pluginRequired: string;
      uiPluginRequired: string;
    };
  data: {
      total: string;
      hierarchySeparator: string;
    };
  dataTable: {
      regionAriaLabel: string;
      tableCaption: string;
      categoryHeader: string;
      emptyValue: string;
      sortAscending: (columnLabel: string) => string;
      sortDescending: (columnLabel: string) => string;
      sortedAscending: (columnLabel: string) => string;
      sortedDescending: (columnLabel: string) => string;
    };
  renderer: {
      chartAriaLabel: (title: string | undefined) => string;
      legendAriaLabel: string;
      legendItemAriaLabel: (series: PivotChartSeries) => string;
      legendCategoryItemAriaLabel: (category: PivotChartCategory) => string;
      legendOverflow: (hiddenCount: number) => string;
      datumAriaLabel: (context: PivotChartDatumLocaleContext) => string;
      datumTitle: (context: PivotChartDatumLocaleContext) => string;
      relationshipDatumAriaLabel:
        (context: PivotChartRelationshipDatumLocaleContext) => string;
      relationshipDatumTitle:
        (context: PivotChartRelationshipDatumLocaleContext) => string;
      tooltipDrillHint: string;
      missingValue: string;
      formatNumber: (value: number) => string;
      formatPercent: (value: number) => string;
      downloadFileName: string;
      pngUnavailable: string;
      pdfUnavailable: string;
      pdfEncodeError: string;
      rasterizeError: string;
      canvasRequired: string;
      destroyedRenderer: string;
      unsupportedChartType: (chartType: string) => string;
      valueSeriesRequired: (chartType: string) => string;
      singleSeriesRequired: (chartType: string) => string;
      rowHierarchyRequired: string;
      dateCategoriesRequired: string;
      distributionViewRequired: string;
      nonNegativeValuesRequired: string;
      relationshipBindingsRequired: (chartType: string) => string;
      relationshipDataRequired: (chartType: string) => string;
      nonNegativeSizeRequired: string;
      minimumSeriesRequired: (chartType: string, minimum: number) => string;
      maximumSeriesRequired: (chartType: string, maximum: number) => string;
    }
}
```

---

### `PivotChartsLocaleTextOptions`

```ts
interface PivotChartsLocaleTextOptions {
  dialog?: Partial<PivotChartsLocaleText['dialog']>;
  actions?: Partial<PivotChartsLocaleText['actions']>;
  status?: Partial<PivotChartsLocaleText['status']>;
  drill?: Partial<PivotChartsLocaleText['drill']>;
  controls?: Partial<PivotChartsLocaleText['controls']>;
  chartOptions?: {
      heading?: string;
      description?: string;
      resetAll?: string;
      resetOption?: PivotChartsLocaleText['chartOptions']['resetOption'];
      valueLabel?: PivotChartsLocaleText['chartOptions']['valueLabel'];
      labels?: Partial<PivotChartsLocaleText['chartOptions']['labels']>;
      descriptions?: Partial<
        PivotChartsLocaleText['chartOptions']['descriptions']
      >;
    };
  gallery?: {
      tabs?: Partial<PivotChartsLocaleText['gallery']['tabs']>;
      searchPlaceholder?: string;
      searchAriaLabel?: string;
      recommended?: string;
      families?: Partial<PivotChartsLocaleText['gallery']['families']>;
      noResults?: string;
      compatibilityReason?: PivotChartsLocaleText['gallery']['compatibilityReason'];
    };
  chartTypes?: Partial<PivotChartsLocaleText['chartTypes']>;
  chartDescriptions?: Partial<PivotChartsLocaleText['chartDescriptions']>;
  legendPositions?: Partial<PivotChartsLocaleText['legendPositions']>;
  totals?: Partial<PivotChartsLocaleText['totals']>;
  drillSyncModes?: Partial<PivotChartsLocaleText['drillSyncModes']>;
  themes?: Partial<PivotChartsLocaleText['themes']>;
  contextMenu?: Partial<PivotChartsLocaleText['contextMenu']>;
  uiErrors?: Partial<PivotChartsLocaleText['uiErrors']>;
  data?: Partial<PivotChartsLocaleText['data']>;
  dataTable?: Partial<PivotChartsLocaleText['dataTable']>;
  renderer?: Partial<PivotChartsLocaleText['renderer']>
}
```

---

### `DEFAULT_PIVOT_CHARTS_LOCALE_TEXT`

```ts
DEFAULT_PIVOT_CHARTS_LOCALE_TEXT: {
  dialog: { kicker: string; untitledChart: string; chartAriaLabel: (title: string | undefined) => string; settingsAriaLabel: string; };
  actions: { exportChart: string; downloadPng: string; downloadPdf: string; close: string; closeButtonText: string; retry: string; viewData: string; viewChart: string; };
  status: { loading: string; empty: string; formatError: (error: Error) => string; };
  drill: { toolbarAriaLabel: string; breadcrumbAriaLabel: string; root: string; currentLevel: (label: string) => string; loading: (label: string) => string; loaded: (label: string) => string; retry: string; formatError: (error: Error) => string; drillableDatum: ({ category, series, displayValue }: PivotChartDatumLocaleContext) => string; relationshipDrillableDatum: ({ category, x, y, size }: PivotChartRelationshipDatumLocaleContext) => string; };
  controls: { chartType: string; valueSeries: string; xMeasure: string; yMeasure: string; sizeMeasure: string; title: string; subtitle: string; legend: string; dataLabels: string; xAxisTitle: string; yAxisTitle: string; totals: string; drillSyncMode: string; theme: string; keepLinked: string; };
  chartOptions: { heading: string; description: string; resetAll: string; resetOption: (label: string) => string; valueLabel: (label: string, value: number) => string; labels: { showGridLines: string; markOpacity: string; strokeWidth: string; fillOpacity: string; }; descriptions: { showGridLines: string; markOpacity: string; strokeWidth: string; fillOpacity: string; }; };
  gallery: { tabs: { chart: string; data: string; customize: string; }; searchPlaceholder: string; searchAriaLabel: string; recommended: string; families: { column: string; bar: string; line: string; area: string; partToWhole: string; relationship: string; hierarchical: string; combination: string; statistical: string; specialized: string; kpi: string; polar: string; distribution: string; matrix: string; process: string; flow: string; financial: string; }; noResults: string; compatibilityReason: (reason: PivotChartCompatibilityReason) => string; };
  chartTypes: { groupedColumn: string; stackedColumn: string; normalizedColumn: string; groupedBar: string; stackedBar: string; normalizedBar: string; line: string; smoothLine: string; steppedLine: string; area: string; steppedArea: string; stackedArea: string; normalizedArea: string; pie: string; donut: string; treemap: string; sunburst: string; scatter: string; bubble: string; columnLine: string; areaLine: string; rangeColumn: string; rangeBar: string; rangeArea: string; confidenceBand: string; errorInterval: string; waterfall: string; lollipop: string; bullet: string; semiDonut: string; rose: string; radarLine: string; radarArea: string; polarColumn: string; stackedPolarColumn: string; normalizedPolarColumn: string; radialBar: string; multiRingRadialBar: string; histogram: string; stripDot: string; heatmap: string; calendarHeatmap: string; densityScatter: string; icicle: string; circlePacking: string; funnel: string; pyramid: string; boxPlot: string; violin: string; rangeInterval: string; sankey: string; chord: string; candlestick: string; ohlc: string; volumePrice: string; gauge: string; kpi: string; progressGauge: string; connectedScatter: string; waffle: string; smallMultiples: string; annotatedTimeSeries: string; timelineRange: string; };
  chartDescriptions: { groupedColumn: string; stackedColumn: string; normalizedColumn: string; groupedBar: string; stackedBar: string; normalizedBar: string; line: string; smoothLine: string; steppedLine: string; area: string; steppedArea: string; stackedArea: string; normalizedArea: string; pie: string; donut: string; treemap: string; sunburst: string; scatter: string; bubble: string; columnLine: string; areaLine: string; rangeColumn: string; rangeBar: string; rangeArea: string; confidenceBand: string; errorInterval: string; waterfall: string; lollipop: string; bullet: string; semiDonut: string; rose: string; radarLine: string; radarArea: string; polarColumn: string; stackedPolarColumn: string; normalizedPolarColumn: string; radialBar: string; multiRingRadialBar: string; histogram: string; stripDot: string; heatmap: string; calendarHeatmap: string; densityScatter: string; icicle: string; circlePacking: string; funnel: string; pyramid: string; boxPlot: string; violin: string; rangeInterval: string; sankey: string; chord: string; candlestick: string; ohlc: string; volumePrice: string; gauge: string; kpi: string; progressGauge: string; connectedScatter: string; waffle: string; smallMultiples: string; annotatedTimeSeries: string; timelineRange: string; };
  legendPositions: { automatic: string; top: string; right: string; bottom: string; left: string; none: string; };
  totals: { none: string; grand: string; subtotals: string; all: string; };
  drillSyncModes: { chart: string; pivot: string; both: string; event: string; };
  themes: { auto: string; default: string; material: string; compact: string; darkMaterial: string; darkCompact: string; custom: (theme: string) => string; };
  contextMenu: { createChart: string; pluginRequired: string; rendererRequired: string; serverProviderRequired: string; };
  uiErrors: { destroyed: string; containerMissing: string; mountContainerRequired: string; creationClosed: string; pluginRequired: string; uiPluginRequired: string; };
  data: { total: string; hierarchySeparator: string; };
  dataTable: { regionAriaLabel: string; tableCaption: string; categoryHeader: string; emptyValue: string; sortAscending: (columnLabel: string) => string; sortDescending: (columnLabel: string) => string; sortedAscending: (columnLabel: string) => string; sortedDescending: (columnLabel: string) => string; };
  renderer: { chartAriaLabel: (title: string | undefined) => string; legendAriaLabel: string; legendItemAriaLabel: (series: PivotChartSeries) => string; legendCategoryItemAriaLabel: (category: PivotChartCategory) => string; legendOverflow: (hiddenCount: number) => string; datumAriaLabel: ({ category, series, displayValue }: PivotChartDatumLocaleContext) => string; datumTitle: ({ category, series, displayValue }: PivotChartDatumLocaleContext) => string; relationshipDatumAriaLabel: ({ category, x, y, size }: PivotChartRelationshipDatumLocaleContext) => string; relationshipDatumTitle: ({ category, x, y, size }: PivotChartRelationshipDatumLocaleContext) => string; tooltipDrillHint: string; missingValue: string; formatNumber: (value: number) => string; formatPercent: (value: number) => string; downloadFileName: string; pngUnavailable: string; pdfUnavailable: string; pdfEncodeError: string; rasterizeError: string; canvasRequired: string; destroyedRenderer: string; unsupportedChartType: (chartType: string) => string; valueSeriesRequired: (chartType: string) => string; singleSeriesRequired: (chartType: string) => string; rowHierarchyRequired: string; dateCategoriesRequired: string; distributionViewRequired: string; nonNegativeValuesRequired: string; relationshipBindingsRequired: (chartType: string) => string; relationshipDataRequired: (chartType: string) => string; nonNegativeSizeRequired: string; minimumSeriesRequired: (chartType: string, minimum: number) => string; maximumSeriesRequired: (chartType: string, maximum: number) => string; };
};
```

---

### `createPivotChartsRenderer`

Creates the built-in RevoGrid Pivot Charts SVG renderer.

```ts
export function createPivotChartsRenderer(
  options: PivotChartsRendererOptions = {},
): PivotChartRenderer;
```

---

### `ChartTheme`

```ts
interface ChartTheme {
  background: string;
  foreground: string;
  muted: string;
  grid: string
}
```

---

### `PivotChartLabelContext`

```ts
interface PivotChartLabelContext {
  chartId: string;
  chartType: PivotChartType;
  kind: PivotChartLabelKind;
  defaultText: string;
  renderMode: 'chart' | 'preview';
  axis?: 'x' | 'y';
  category?: PivotChartCategory;
  series?: PivotChartSeries;
  categoryIndex?: number;
  seriesIndex?: number;
  value?: number | null;
  formattedValue?: string
}
```

---

### `PivotChartLabelFormatter`

```ts
export type PivotChartLabelFormatter = (
  context: PivotChartLabelContext,
) => string | PivotChartLabelResult | null | undefined;
```

---

### `PivotChartLabelKind`

```ts
export type PivotChartLabelKind =
  | 'title'
  | 'subtitle'
  | 'axisTitle'
  | 'axisTick'
  | 'category'
  | 'legend'
  | 'data'
  | 'annotation'
  | 'summary'
  | 'specialized';
```

---

### `PivotChartLabelResult`

```ts
interface PivotChartLabelResult {
  text?: string;
  ariaLabel?: string;
  className?: string;
  style?: PivotChartLabelStyle;
  hidden?: boolean
}
```

---

### `PivotChartLabelsOptions`

```ts
interface PivotChartLabelsOptions {
  /** Refines, replaces, or suppresses any visible SVG chart label. */
    formatter?: PivotChartLabelFormatter;
  /** Reusable typography overrides applied before formatter-specific styles. */
    styles?: Partial<Record<PivotChartLabelKind, PivotChartLabelStyle>>
}
```

---

### `PivotChartLabelStyle`

```ts
interface PivotChartLabelStyle {
  fill?: string;
  fontFamily?: string;
  fontSize?: number | string;
  fontWeight?: number | string;
  fontStyle?: string;
  letterSpacing?: number | string;
  textDecoration?: string;
  opacity?: number;
  textAnchor?: 'start' | 'middle' | 'end'
}
```

---

### `PivotChartRendererTheme`

```ts
export type PivotChartRendererTheme =
  | Partial<ChartTheme>
  | ((context: PivotChartRendererThemeContext) => Partial<ChartTheme>);
```

---

### `PivotChartRendererThemeContext`

```ts
interface PivotChartRendererThemeContext {
  input: PivotChartRenderInput;
  theme: ChartTheme
}
```

---

### `PivotChartsRendererOptions`

```ts
interface PivotChartsRendererOptions {
  /** Additional application class names applied to the chart SVG. */
    className?: string;
  palette?: readonly string[];
  categorySeparator?: string;
  fontFamily?: string;
  /** Overrides the resolved light or dark chart theme. */
    theme?: PivotChartRendererTheme;
  /** Customizes all chart text through one semantic label pipeline. */
    labels?: PivotChartLabelsOptions;
  imageEncoder?: (
      svg: SVGSVGElement,
      options: Required<Pick<PivotChartImageOptions, 'width' | 'height'>>,
    ) => Promise<string>;
  pdfEncoder?: (
      svg: SVGSVGElement,
      options: Required<Pick<PivotChartDownloadOptions, 'width' | 'height'>>,
    ) => Promise<string>;
  /** Disable tooltips or customize the built-in semantic tooltip renderer. */
    tooltip?: false | PivotChartTooltipOptions
}
```

---

### `PivotChartUiOpenParams`

```ts
export type PivotChartUiOpenParams = Omit<PivotChartCreateParams, 'container'>;
```

---

### `PivotChartUiMountParams`

```ts
export type PivotChartUiMountParams = PivotChartCreateParams;
```

---

### `PivotChartsUiPlugin`

#### Dependencies

- **Required** `PivotChartsPlugin`: Uses the headless Pivot Charts lifecycle and data APIs.
- **Optional** `ContextMenuPlugin`: Contributes the optional Pivot Chart row-menu action.
- **Config integration** `grid.pivotChartsUi`: Reads UI mounting and context-menu behavior from grid.pivotChartsUi.

```ts
class PivotChartsUiPlugin {
  /**
     * Opens a UI-owned modeless Pivot chart. The returned chart ref remains
     * managed by the headless plugin; closing the dialog destroys that ref.
     * If this grid already has an open chart dialog, it is focused and its
     * existing chart ref is returned.
     */
  async openChart(
    params: PivotChartUiOpenParams = {},
  ): Promise<PivotChartRef>;

  /**
     * Mounts the standard Pivot Chart controls inside an application-owned
     * container. Multiple embedded charts may coexist with the modeless dialog.
     * Destroying the returned chart ref removes the embedded UI.
     */
  async mountChart({
    container,
    ...params
  }: PivotChartUiMountParams): Promise<PivotChartRef>;
}
```

---

### `PivotChartDialog`

```ts
export function PivotChartDialog({
  mode = 'dialog',
  model,
  series,
  dataset,
  renderer,
  supportedTypes,
  loading,
  empty,
  error,
  drillLoading = false,
  drillError,
  drillPendingLabel,
  drillCompletedLabel,
  downloadFormats,
  localeText,
  onUpdate,
  onRetry,
  onDrillBack = () => {},
  onDrillHome = () => {},
  onDrillNavigate = () => {},
  onDrillRetry = () => {},
  onDownload,
  onClose,
}: PivotChartDialogProps);
```

---

### `PivotChartDialogProps`

```ts
interface PivotChartDialogProps {
  readonly mode?: 'dialog' | 'embedded';
  readonly model: PivotChartModel;
  readonly series: readonly PivotChartSeries[];
  readonly dataset?: PivotChartDataset;
  readonly renderer?: PivotChartRenderer;
  readonly supportedTypes: readonly PivotChartType[];
  readonly loading: boolean;
  readonly empty: boolean;
  readonly error?: Error;
  readonly drillLoading?: boolean;
  readonly drillError?: Error;
  readonly drillPendingLabel?: string;
  readonly drillCompletedLabel?: string;
  readonly downloadFormats: readonly PivotChartDownloadFormat[];
  readonly localeText: PivotChartsLocaleText;
  readonly onUpdate: (patch: PivotChartUpdatePatch) => void;
  readonly onRetry: () => void;
  readonly onDrillBack?: () => void;
  readonly onDrillHome?: () => void;
  readonly onDrillNavigate?: (frameIndex: number) => void;
  readonly onDrillRetry?: () => void;
  readonly onDownload: (format: PivotChartDownloadFormat) => void;
  readonly onClose?: () => void
}
```

---

### `chartRenderers`

```ts
chartRenderers: Record<"line" | "area" | "kpi" | "groupedColumn" | "stackedColumn" | "normalizedColumn" | "groupedBar" | "stackedBar" | "normalizedBar" | "smoothLine" | "steppedLine" | "steppedArea" | "stackedArea" | "normalizedArea" | "pie" | "donut" | "treemap" | "sunburst" | "scatter" | "bubble" | "densityScatter" | "connectedScatter" | "columnLine" | "areaLine" | "rangeColumn" | "rangeBar" | "rangeArea" | "confidenceBand" | "errorInterval" | "waterfall" | "lollipop" | "bullet" | "semiDonut" | "rose" | "radarLine" | "radarArea" | "polarColumn" | "stackedPolarColumn" | "normalizedPolarColumn" | "radialBar" | "multiRingRadialBar" | "histogram" | "stripDot" | "heatmap" | "calendarHeatmap" | "icicle" | "circlePacking" | "funnel" | "pyramid" | "boxPlot" | "violin" | "rangeInterval" | "sankey" | "chord" | "candlestick" | "ohlc" | "volumePrice" | "gauge" | "progressGauge" | "waffle" | "smallMultiples" | "annotatedTimeSeries" | "timelineRange", PivotChartRenderFunction>;
```

---

### `renderWaffle`

```ts
renderWaffle: PivotChartRenderFunction;
```

---

### `renderHistogram`

```ts
renderHistogram: PivotChartRenderFunction;
```

---

### `renderDotPlot`

```ts
renderDotPlot: PivotChartRenderFunction;
```

---

### `renderStripDot`

```ts
renderStripDot: PivotChartRenderFunction;
```

---

### `renderStripPlot`

```ts
renderStripPlot: PivotChartRenderFunction;
```

---

### `renderSmallMultiples`

```ts
renderSmallMultiples: PivotChartRenderFunction;
```

---

### `renderCandlestick`

```ts
renderCandlestick: PivotChartRenderFunction;
```

---

### `renderOhlc`

```ts
renderOhlc: PivotChartRenderFunction;
```

---

### `renderVolumePrice`

```ts
renderVolumePrice: PivotChartRenderFunction;
```

---

### `renderChord`

```ts
renderChord: PivotChartRenderFunction;
```

---

### `createFlowGraph`

The current Pivot dataset is a category-by-series matrix rather than an
explicit edge list. Until a provider supplies the normalized flow view,
this deterministic projection treats those two matrix axes as adjacent
graph partitions: each positive finite cell becomes one directed edge from
its category to its series. Aggregate categories and unconnected nodes are
omitted, while original matrix indexes are retained for exact interaction.

```ts
export function createFlowGraph(
  dataset: PivotChartDataset,
  bindings: PivotChartBindings,
): PivotChartFlowGraph;
```

---

### `PivotChartFlowEdge`

```ts
interface PivotChartFlowEdge {
  readonly id: string;
  readonly sourceId: string;
  readonly targetId: string;
  readonly value: number;
  readonly category: PivotChartCategory;
  readonly categoryIndex: number;
  readonly series: PivotChartSeries;
  readonly seriesIndex: number
}
```

---

### `PivotChartFlowGraph`

```ts
interface PivotChartFlowGraph {
  readonly nodes: readonly PivotChartFlowNode[];
  readonly edges: readonly PivotChartFlowEdge[];
  readonly total: number
}
```

---

### `PivotChartFlowNode`

```ts
interface PivotChartFlowNode {
  readonly id: string;
  readonly label: string;
  readonly kind: 'category' | 'series';
  readonly value: number;
  readonly category?: PivotChartCategory;
  readonly categoryIndex?: number;
  readonly series?: PivotChartSeries;
  readonly seriesIndex?: number
}
```

---

### `renderSankey`

```ts
renderSankey: PivotChartRenderFunction;
```

---

### `renderCirclePacking`

```ts
renderCirclePacking: PivotChartRenderFunction;
```

---

### `renderIcicle`

```ts
renderIcicle: PivotChartRenderFunction;
```

---

### `renderSunburst`

```ts
export function renderSunburst(context: RenderContext);
```

---

### `renderTreemap`

```ts
export function renderTreemap(context: RenderContext);
```

---

### `renderGauge`

```ts
renderGauge: PivotChartRenderFunction;
```

---

### `renderKpi`

```ts
renderKpi: PivotChartRenderFunction;
```

---

### `renderProgressGauge`

```ts
renderProgressGauge: PivotChartRenderFunction;
```

---

### `renderCalendarHeatmap`

```ts
renderCalendarHeatmap: PivotChartRenderFunction;
```

---

### `renderHeatmap`

```ts
renderHeatmap: PivotChartRenderFunction;
```

---

### `renderMultiRingRadialBar`

```ts
renderMultiRingRadialBar: PivotChartRenderFunction;
```

---

### `renderNormalizedPolarColumn`

```ts
renderNormalizedPolarColumn: PivotChartRenderFunction;
```

---

### `renderPolarColumn`

```ts
renderPolarColumn: PivotChartRenderFunction;
```

---

### `renderRadarArea`

```ts
renderRadarArea: PivotChartRenderFunction;
```

---

### `renderRadarLine`

```ts
renderRadarLine: PivotChartRenderFunction;
```

---

### `renderRadialBar`

```ts
renderRadialBar: PivotChartRenderFunction;
```

---

### `renderRose`

```ts
renderRose: PivotChartRenderFunction;
```

---

### `renderStackedPolarColumn`

```ts
renderStackedPolarColumn: PivotChartRenderFunction;
```

---

### `renderFunnel`

```ts
renderFunnel: PivotChartRenderFunction;
```

---

### `renderPyramid`

```ts
renderPyramid: PivotChartRenderFunction;
```

---

### `renderBullet`

```ts
renderBullet: PivotChartRenderFunction;
```

---

### `renderConfidenceBand`

```ts
renderConfidenceBand: PivotChartRenderFunction;
```

---

### `renderErrorInterval`

```ts
renderErrorInterval: PivotChartRenderFunction;
```

---

### `renderLollipop`

```ts
renderLollipop: PivotChartRenderFunction;
```

---

### `renderRangeArea`

```ts
renderRangeArea: PivotChartRenderFunction;
```

---

### `renderRangeBar`

```ts
renderRangeBar: PivotChartRenderFunction;
```

---

### `renderRangeColumn`

```ts
renderRangeColumn: PivotChartRenderFunction;
```

---

### `renderWaterfall`

```ts
renderWaterfall: PivotChartRenderFunction;
```

---

### `renderBubble`

```ts
export function renderBubble(context: RenderContext);
```

---

### `renderConnectedScatter`

```ts
renderConnectedScatter: PivotChartRenderFunction;
```

---

### `renderDensityScatter`

```ts
renderDensityScatter: PivotChartRenderFunction;
```

---

### `renderHexbin`

```ts
renderHexbin: PivotChartRenderFunction;
```

---

### `renderScatter`

```ts
export function renderScatter(context: RenderContext);
```

---

### `renderBoxPlot`

```ts
renderBoxPlot: PivotChartRenderFunction;
```

---

### `renderRangeInterval`

```ts
renderRangeInterval: PivotChartRenderFunction;
```

---

### `renderViolin`

```ts
renderViolin: PivotChartRenderFunction;
```

---

### `collectStatisticalData`

```ts
export function collectStatisticalData(
  dataset: PivotChartDataset,
  seriesIds?: readonly string[],
): StatisticalDatum[];
```

---

### `createDensitySamples`

```ts
export function createDensitySamples(
  observations: readonly StatisticalObservation[],
  requestedSampleCount = 33,
): DensitySample[];
```

---

### `DensitySample`

```ts
interface DensitySample {
  readonly value: number;
  readonly density: number
}
```

---

### `StatisticalDatum`

```ts
interface StatisticalDatum {
  readonly category: PivotChartCategory;
  readonly categoryIndex: number;
  readonly observations: readonly StatisticalObservation[];
  readonly count: number;
  readonly minimum: number;
  readonly lowerQuartile: number;
  readonly median: number;
  readonly upperQuartile: number;
  readonly maximum: number;
  readonly mean: number;
  readonly lowerWhisker: number;
  readonly upperWhisker: number;
  readonly outliers: readonly StatisticalObservation[];
  readonly representativeSeriesIndex: number
}
```

---

### `StatisticalObservation`

```ts
interface StatisticalObservation {
  readonly value: number;
  readonly seriesIndex: number
}
```

---

### `renderTimelineRange`

```ts
renderTimelineRange: PivotChartRenderFunction;
```

---

### `renderAnnotatedTimeSeries`

```ts
renderAnnotatedTimeSeries: PivotChartRenderFunction;
```

---

### `resolvePivotChartCellContext`

```ts
export function resolvePivotChartCellContext(
  cell?: ContextMenuCellContext,
): PivotChartCellContext | undefined;
```

---

### `PivotChartCellContext`

```ts
interface PivotChartCellContext {
  initialScope: PivotChartInitialScope;
  seriesIds: string[];
  columnPath: PivotPath;
  measure: PivotChartMeasure;
  totals?: PivotChartTotalsMode;
  categoryMeasure?: Pick<PivotChartMeasure, 'prop' | 'aggregator'>
}
```

---

### `resolveSpecializedSeriesBindings`

Resolves specialized measure channels only from explicit stable IDs or
unambiguous semantic labels. Series position is deliberately never used.

```ts
export function resolveSpecializedSeriesBindings(
  dataset: PivotChartDataset,
  current: PivotChartBindings,
  requirements: readonly SpecializedBindingRequirement[],
): SpecializedBindingResolution;
```

---

### `resolveMatrixFlowBindings`

```ts
export function resolveMatrixFlowBindings(
  dataset: PivotChartDataset,
  current: PivotChartBindings,
): {
  bindings: PivotChartBindings;
  missing: Array<'source' | 'target' | 'weight'>;
};
```

---

### `boundSeriesIndex`

```ts
export function boundSeriesIndex(
  dataset: PivotChartDataset,
  bindings: PivotChartBindings,
  channel: PivotChartBindingChannel,
): number | undefined;
```

---

### `SpecializedSeriesChannel`

```ts
export type SpecializedSeriesChannel =
  | 'low'
  | 'high'
  | 'open'
  | 'close'
  | 'volume'
  | 'actual'
  | 'target'
  | 'variance'
  | 'start'
  | 'end';
```

---

### `SpecializedBindingRequirement`

```ts
interface SpecializedBindingRequirement {
  channel: SpecializedSeriesChannel;
  required: boolean
}
```

---

### `SpecializedBindingResolution`

```ts
interface SpecializedBindingResolution {
  bindings: PivotChartBindings;
  missing: SpecializedSeriesChannel[]
}
```

---

### `createPivotChartGeographicRendererInstance`

```ts
export function createPivotChartGeographicRendererInstance(
  pack: Pick<PivotChartGeographicCapabilityPack, 'load'>,
  initialInput: PivotChartGeographicRenderInput,
): PivotChartGeographicRendererInstance;
```

---

### `PivotChartDataControls`

```ts
export function PivotChartDataControls({
  model,
  localeText,
  onUpdate,
}: PivotChartDataControlsProps);
```

---

### `PivotChartDataTable`

```ts
export function PivotChartDataTable({
  dataset,
  labels,
}: PivotChartDataTableProps);
```

---

### `PivotChartDataTableLabels`

```ts
interface PivotChartDataTableLabels {
  readonly regionAriaLabel: string;
  readonly tableCaption: string;
  readonly categoryHeader: string;
  readonly hierarchySeparator: string;
  readonly emptyValue: string;
  readonly formatNumber: (value: number) => string;
  readonly sortAscending: (columnLabel: string) => string;
  readonly sortDescending: (columnLabel: string) => string;
  readonly sortedAscending: (columnLabel: string) => string;
  readonly sortedDescending: (columnLabel: string) => string
}
```

---

### `PivotChartDataTableProps`

```ts
interface PivotChartDataTableProps {
  readonly dataset: PivotChartDataset;
  readonly labels: PivotChartDataTableLabels
}
```

---

### `PivotChartDialogHeader`

```ts
export function PivotChartDialogHeader({
  headerRef,
  closable = true,
  title,
  loading,
  downloadFormats,
  showingData,
  localeText,
  onToggleData,
  onDownload,
  onClose,
}: PivotChartDialogHeaderProps);
```

---

### `PivotChartDialogSettings`

```ts
export function PivotChartDialogSettings({
  model,
  series,
  dataset,
  renderer,
  theme,
  visibleChartTypes,
  presentation,
  themeOptions,
  disabled,
  localeText,
  onPresentationChange,
  onPresentationCommit,
  onUpdate,
}: PivotChartDialogSettingsProps);
```

---

### `PivotChartDialogTabs`

```ts
export function PivotChartDialogTabs({
  active,
  chartId,
  localeText,
  onChange,
}: PivotChartDialogTabsProps);
```

---

### `PivotChartDialogTab`

```ts
export type PivotChartDialogTab = 'chart' | 'data' | 'customize';
```

---

### `PivotChartDialogVisual`

```ts
export function PivotChartDialogVisual({
  loading,
  empty,
  error,
  dataset,
  showingData,
  drillState,
  drillLoading,
  drillError,
  drillPendingLabel,
  drillCompletedLabel,
  localeText,
  onRetry,
  onDrillNavigate,
  onDrillRetry,
}: PivotChartDialogVisualProps);
```

---

### `PIVOT_CHART_THEME_VALUES`

```ts
PIVOT_CHART_THEME_VALUES: readonly ["auto", "default", "material", "compact", "darkMaterial", "darkCompact"];
```

---

### `PivotChartPresentationChangeHandler`

```ts
export type PivotChartPresentationChangeHandler = <
  K extends keyof PivotChartPresentation,
>(
  key: K,
  value: PivotChartPresentation[K],
) => void;
```

---

### `PivotChartThemeOption`

```ts
export type PivotChartThemeOption = readonly [value: string, label: string];
```

---

### `PivotChartDrillToolbar`

```ts
export function PivotChartDrillToolbar({
  state,
  loading,
  error,
  pendingLabel,
  completedLabel,
  localeText,
  onNavigate,
  onRetry,
}: PivotChartDrillToolbarProps);
```

---

### `PivotChartExportMenu`

```ts
export function PivotChartExportMenu({
  formats,
  disabled,
  localeText,
  onDownload,
}: PivotChartExportMenuProps);
```

---

### `PivotChartGallery`

```ts
export function PivotChartGallery({
  model,
  dataset,
  series,
  renderer,
  supportedTypes,
  theme,
  localeText,
  onUpdate,
}: PivotChartGalleryProps);
```

---

### `PivotChartOptionsControls`

```ts
export function PivotChartOptionsControls({
  model,
  localeText,
  onUpdate,
}: PivotChartOptionsControlsProps);
```

---

### `PivotChartPresentationControls`

```ts
export function PivotChartPresentationControls({
  chartType,
  presentation,
  localeText,
  onChange,
  onCommit,
}: PivotChartPresentationControlsProps);
```

---

### `PivotChartPreview`

```ts
export function PivotChartPreview({
  definition,
  renderer,
  theme,
  localeText,
}: PivotChartPreviewProps);
```

---

### `clearPivotChartPreviewCache`

```ts
export function clearPivotChartPreviewCache();
```

---

### `PivotChartRelationshipControls`

```ts
export function PivotChartRelationshipControls({
  model,
  series,
  localeText,
  onUpdate,
}: PivotChartRelationshipControlsProps);
```

---

### `PivotChartSeriesControl`

```ts
export function PivotChartSeriesControl({
  model,
  series,
  localeText,
  onUpdate,
}: PivotChartSeriesControlProps);
```

---

### `PivotChartThemeControl`

```ts
export function PivotChartThemeControl({
  model,
  themeOptions,
  localeText,
  onUpdate,
}: PivotChartThemeControlProps);
```

---

### `PivotChartTypeControl`

```ts
export function PivotChartTypeControl({
  model,
  dataset,
  series,
  renderer,
  theme,
  visibleChartTypes,
  localeText,
  onUpdate,
}: PivotChartTypeControlProps);
```

---

### `renderAxes`

```ts
export function renderAxes(
  context: RenderContext,
  scale: Scale,
  horizontal: boolean,
  percentage = false,
);
```

---

### `renderXYAxes`

```ts
export function renderXYAxes(
  context: RenderContext,
  xScale: Scale,
  yScale: Scale,
  defaultTitles?: { x: string; y: string },
);
```

---

### `appendCategoryLabel`

```ts
export function appendCategoryLabel(
  context: RenderContext,
  category: PivotChartCategory,
  categoryIndex: number,
  categorySize: number,
  horizontal: boolean,
  origin?: number,
);
```

---

### `DEFAULT_WIDTH`

```ts
DEFAULT_WIDTH: 960;
```

---

### `DEFAULT_HEIGHT`

```ts
DEFAULT_HEIGHT: 540;
```

---

### `DEFAULT_PALETTE`

```ts
DEFAULT_PALETTE: readonly ["#4f8fdc", "#f59e42", "#49a35a", "#38b6d4", "#e7c900", "#8b6fc0", "#e66b77", "#5aa69a"];
```

---

### `shouldRenderCategoryLabel`

```ts
export function shouldRenderCategoryLabel(
  categoryIndex: number,
  categoryCount: number,
  categorySize: number,
  horizontal: boolean,
): boolean;
```

---

### `shouldRenderDataLabel`

```ts
export function shouldRenderDataLabel(
  categoryIndex: number,
  seriesIndex: number,
  categoryCount: number,
  seriesCount: number,
): boolean;
```

---

### `encodeChartImage`

```ts
export async function encodeChartImage(
  svg: SVGSVGElement,
  options: ChartExportSizeOptions,
  rendererOptions: PivotChartsRendererOptions,
  localeText: PivotChartsLocaleText,
);
```

---

### `encodeChartPdf`

```ts
export async function encodeChartPdf(
  svg: SVGSVGElement,
  options: ChartExportSizeOptions,
  rendererOptions: PivotChartsRendererOptions,
  localeText: PivotChartsLocaleText,
);
```

---

### `normalizeFileName`

```ts
export function normalizeFileName(
  fileName: string | undefined,
  fallback: string,
  format: PivotChartDownloadFormat,
);
```

---

### `initializeDatumInteractions`

Starts a fresh delegated interaction scope for one SVG render.

Dense charts use a roving tab stop so the chart remains reachable without
placing hundreds or thousands of marks in the document tab order.

```ts
export function initializeDatumInteractions(
  svg: SVGSVGElement,
  input: PivotChartRenderInput,
);
```

---

### `makeDatumInteractive`

```ts
export function makeDatumInteractive(
  element: SVGElement,
  input: PivotChartRenderInput,
  category: PivotChartCategory,
  series: PivotChartSeries,
  value: number | null,
  label: string,
  description?: {
    ariaLabel: string;
    title: string;
    channelValues?: PivotChartNodeClick['channelValues'];
    channelSeries?: PivotChartNodeClick['channelSeries'];
    channelDisplayValues?: DatumDescription['channelDisplayValues'];
  },
);
```

---

### `getDatumDescription`

```ts
export function getDatumDescription(element: SVGElement);
```

---

### `DatumDescription`

```ts
interface DatumDescription {
  readonly category: PivotChartCategory;
  readonly series: PivotChartSeries;
  readonly value: number | null;
  readonly displayValue: string;
  readonly title: string;
  readonly categoryIndex?: number;
  readonly seriesIndex?: number;
  readonly channelValues?: PivotChartNodeClick['channelValues'];
  readonly channelSeries?: PivotChartNodeClick['channelSeries'];
  readonly channelDisplayValues?: Partial<
      Record<'x' | 'y' | 'size', string>
    >
}
```

---

### `applyChartLabelCustomization`

```ts
export function applyChartLabelCustomization(
  svg: SVGSVGElement,
  input: PivotChartRenderInput,
  options: PivotChartsRendererOptions,
  legendKind: 'series' | 'category' | 'none',
);
```

---

### `resolveLegendLayout`

```ts
export function resolveLegendLayout(
  width: number,
  height: number,
  itemCount: number,
  position: LegendLayout['position'],
): LegendLayout;
```

---

### `renderLegend`

```ts
export function renderLegend(
  context: RenderContext,
  width: number,
  height: number,
  layout: LegendLayout,
  kind: 'series' | 'category',
);
```

---

### `LegendLayout`

```ts
interface LegendLayout {
  readonly position: 'top' | 'right' | 'bottom' | 'left';
  readonly columns: number;
  readonly itemWidth: number;
  readonly visibleItemCount: number;
  readonly reservedHeight: number;
  readonly reservedWidth: number
}
```

---

### `arcPath`

```ts
export function arcPath(
  centerX: number,
  centerY: number,
  innerRadius: number,
  outerRadius: number,
  startAngle: number,
  endAngle: number,
): string;
```

---

### `polarPoint`

```ts
export function polarPoint(
  centerX: number,
  centerY: number,
  radius: number,
  angle: number,
);
```

---

### `polarAngle`

```ts
export function polarAngle(
  index: number,
  count: number,
  offset = -Math.PI / 2,
): number;
```

---

### `renderChart`

```ts
export function renderChart(
  svg: SVGSVGElement,
  input: PivotChartRenderInput,
  options: PivotChartsRendererOptions,
);
```

---

### `createSvg`

```ts
export function createSvg<K extends keyof SVGElementTagNameMap>(
  document: Document,
  name: K,
  attributes: Record<string, string | number> = {},
);
```

---

### `setAttributes`

```ts
export function setAttributes(
  element: Element,
  attributes: Record<string, string | number>,
);
```

---

### `appendRect`

```ts
export function appendRect(
  svg: SVGElement,
  x: number,
  y: number,
  width: number,
  height: number,
  fill: string,
  radius = 0,
);
```

---

### `appendLine`

```ts
export function appendLine(
  svg: SVGElement,
  x1: number,
  y1: number,
  x2: number,
  y2: number,
  stroke: string,
);
```

---

### `appendText`

```ts
export function appendText(
  svg: SVGElement,
  x: number,
  y: number,
  value: string,
  attributes: Record<string, string | number>,
);
```

---

### `resolveTheme`

```ts
export function resolveTheme(
  input: PivotChartRenderInput,
  override?: PivotChartRendererTheme,
): ChartTheme;;
```

---

### `initializeChartTooltip`

```ts
export function initializeChartTooltip(
  svg: SVGSVGElement,
  input: PivotChartRenderInput,
  options: PivotChartsRendererOptions,
  categorySeparator: string,
);
```

---

### `destroyChartTooltip`

```ts
export function destroyChartTooltip(svg: SVGSVGElement);
```

---

### `ChartBounds`

```ts
interface ChartBounds {
  left: number;
  top: number;
  width: number;
  height: number
}
```

---

### `Scale`

```ts
interface Scale {
  min: number;
  max: number;
  position(value: number): number
}
```

---

### `RenderContext`

```ts
interface RenderContext {
  input: PivotChartRenderInput;
  svg: SVGSVGElement;
  bounds: ChartBounds;
  theme: ChartTheme;
  palette: readonly string[];
  categorySeparator: string
}
```

---

### `PivotChartRenderFunction`

```ts
export type PivotChartRenderFunction = (context: RenderContext) => void;
```

---

### `PivotChartTooltipOptions`

```ts
interface PivotChartTooltipOptions {
  /** Delay before a pointer tooltip opens. Keyboard tooltips open immediately. */
    showDelayMs?: number;
  /** Delay before a pointer tooltip closes. */
    hideDelayMs?: number;
  /** Keep an open pointer tooltip near the cursor. */
    followPointer?: boolean;
  /** Additional application class names applied to the tooltip root. */
    className?: string;
  /** Replaces or refines the default semantic tooltip content. */
    formatter?: PivotChartTooltipFormatter
}
```

---

### `assertSupportedType`

```ts
export function assertSupportedType(
  chartType: PivotChartType,
  localeText: PivotChartsLocaleText,
);
```

---

### `assertChartShape`

```ts
export function assertChartShape(
  chartType: PivotChartType,
  dataset: PivotChartDataset,
  localeText: PivotChartsLocaleText,
  bindings = {},
);
```

---

### `assertAlive`

```ts
export function assertAlive(
  destroyed: boolean,
  localeText: PivotChartsLocaleText,
);
```

---

### `createValueScale`

```ts
export function createValueScale(
  rows: Array<Array<number | null>>,
  stacked: boolean,
  length: number,
  normalized = false,
): Scale;
```

---

### `createContinuousScale`

```ts
export function createContinuousScale(
  values: readonly number[],
  length: number,
): Scale;
```

---

### `normalizeRows`

```ts
export function normalizeRows(rows: Array<Array<number | null>>);
```

---

### `cumulativeRows`

```ts
export function cumulativeRows(rows: Array<Array<number | null>>);
```

---

### `createStackedRows`

```ts
export function createStackedRows(rows: Array<Array<number | null>>);
```

---

### `displayValue`

```ts
export function displayValue(
  dataset: PivotChartDataset,
  categoryIndex: number,
  seriesIndex: number,
  localeText: PivotChartsLocaleText,
);
```

---

### `flattenCategory`

```ts
export function flattenCategory(
  category: PivotChartCategory,
  separator: string,
);
```

---

### `formatNumber`

```ts
export function formatNumber(
  value: number | null,
  localeText: PivotChartsLocaleText,
);
```

---

### `renderAreaLine`

```ts
renderAreaLine: PivotChartRenderFunction;
```

---

### `renderArea`

```ts
renderArea: PivotChartRenderFunction;
```

---

### `renderBarChart`

```ts
export function renderBarChart(
  context: RenderContext,
  options: BarChartOptions,
);
```

---

### `BarChartOptions`

```ts
interface BarChartOptions {
  readonly orientation: 'horizontal' | 'vertical';
  readonly stacking: 'grouped' | 'stacked' | 'normalized'
}
```

---

### `renderColumnLine`

```ts
renderColumnLine: PivotChartRenderFunction;
```

---

### `renderCombinationChart`

```ts
export function renderCombinationChart(
  context: RenderContext,
  options: CombinationChartOptions,
);
```

---

### `CombinationChartOptions`

```ts
interface CombinationChartOptions {
  readonly primary: 'column' | 'area'
}
```

---

### `renderDonut`

```ts
renderDonut: PivotChartRenderFunction;
```

---

### `renderGroupedBar`

```ts
renderGroupedBar: PivotChartRenderFunction;
```

---

### `renderGroupedColumn`

```ts
renderGroupedColumn: PivotChartRenderFunction;
```

---

### `renderLineAreaChart`

```ts
export function renderLineAreaChart(
  context: RenderContext,
  options: LineAreaChartOptions,
);
```

---

### `LineAreaChartOptions`

```ts
interface LineAreaChartOptions {
  readonly area: boolean;
  readonly interpolation: LineAreaInterpolation;
  readonly stacking: 'none' | 'stacked' | 'normalized'
}
```

---

### `createLinePath`

```ts
export function createLinePath(
  points: readonly LineAreaPoint[],
  interpolation: LineAreaInterpolation,
): string;
```

---

### `createAreaPath`

```ts
export function createAreaPath(
  top: readonly LineAreaPoint[],
  baseline: readonly LineAreaPoint[],
  interpolation: LineAreaInterpolation,
): string;
```

---

### `LineAreaPoint`

```ts
interface LineAreaPoint {
  readonly x: number;
  readonly y: number
}
```

---

### `LineAreaInterpolation`

```ts
export type LineAreaInterpolation = 'linear' | 'smooth' | 'step';
```

---

### `renderLine`

```ts
renderLine: PivotChartRenderFunction;
```

---

### `renderNormalizedArea`

```ts
renderNormalizedArea: PivotChartRenderFunction;
```

---

### `renderNormalizedBar`

```ts
renderNormalizedBar: PivotChartRenderFunction;
```

---

### `renderNormalizedColumn`

```ts
renderNormalizedColumn: PivotChartRenderFunction;
```

---

### `renderPie`

```ts
renderPie: PivotChartRenderFunction;
```

---

### `renderPolarChart`

```ts
export function renderPolarChart(
  context: RenderContext,
  options: PolarChartOptions,
);
```

---

### `PolarChartOptions`

```ts
interface PolarChartOptions {
  readonly donut: boolean;
  readonly startAngle?: number;
  readonly sweepAngle?: number;
  readonly mark?: string
}
```

---

### `renderSemiDonut`

```ts
renderSemiDonut: PivotChartRenderFunction;
```

---

### `renderSmoothLine`

```ts
renderSmoothLine: PivotChartRenderFunction;
```

---

### `renderStackedArea`

```ts
renderStackedArea: PivotChartRenderFunction;
```

---

### `renderStackedBar`

```ts
renderStackedBar: PivotChartRenderFunction;
```

---

### `renderStackedColumn`

```ts
renderStackedColumn: PivotChartRenderFunction;
```

---

### `renderSteppedArea`

```ts
renderSteppedArea: PivotChartRenderFunction;
```

---

### `renderSteppedLine`

```ts
renderSteppedLine: PivotChartRenderFunction;
```

---

### `createWaffleSlices`

```ts
export function createWaffleSlices(
  dataset: PivotChartDataset,
  seriesId?: string,
  cellCount = 100,
): WaffleSlice[];
```

---

### `WaffleSlice`

```ts
interface WaffleSlice {
  readonly category: PivotChartCategory;
  readonly categoryIndex: number;
  readonly series: PivotChartSeries;
  readonly seriesIndex: number;
  readonly value: number;
  readonly cells: number
}
```

---

### `collectDistributionData`

```ts
export function collectDistributionData(
  dataset: PivotChartDataset,
  seriesId?: string,
): DistributionDatum[];
```

---

### `createHistogramBins`

```ts
export function createHistogramBins(
  data: readonly DistributionDatum[],
  requestedBinCount?: number,
): HistogramBin[];
```

---

### `DistributionDatum`

```ts
interface DistributionDatum {
  category: PivotChartCategory;
  categoryIndex: number;
  series: PivotChartSeries;
  seriesIndex: number;
  value: number
}
```

---

### `HistogramBin`

```ts
interface HistogramBin {
  index: number;
  start: number;
  end: number;
  count: number;
  mean: number;
  data: DistributionDatum[]
}
```

---

### `renderPriceSeries`

```ts
export function renderPriceSeries(
  context: RenderContext,
  options: PriceRenderOptions,
);
```

---

### `PriceMarkKind`

```ts
export type PriceMarkKind = 'candlestick' | 'ohlc';
```

---

### `PriceRenderOptions`

```ts
interface PriceRenderOptions {
  readonly kind: PriceMarkKind;
  readonly bounds?: ChartBounds;
  readonly attributePrefix: string;
  readonly renderAxes?: boolean;
  readonly renderCategoryLabels?: boolean
}
```

---

### `collectFinancialData`

```ts
export function collectFinancialData(
  dataset: PivotChartDataset,
  bindings: PivotChartBindings,
  requireVolume = false,
): FinancialDatum[];
```

---

### `FinancialDatum`

```ts
interface FinancialDatum {
  readonly categoryIndex: number;
  readonly open: number;
  readonly high: number;
  readonly low: number;
  readonly close: number;
  readonly volume?: number;
  readonly openSeriesIndex: number;
  readonly highSeriesIndex: number;
  readonly lowSeriesIndex: number;
  readonly closeSeriesIndex: number;
  readonly volumeSeriesIndex?: number
}
```

---

### `collectHierarchyValues`

```ts
export function collectHierarchyValues(
  dataset: PivotChartDataset,
): readonly HierarchyCategoryValue[];
```

---

### `commonCategoryPrefix`

```ts
export function commonCategoryPrefix(
  categories: readonly PivotChartCategory[],
): readonly string[];
```

---

### `HierarchySeriesValue`

```ts
interface HierarchySeriesValue {
  readonly category: PivotChartCategory;
  readonly categoryIndex: number;
  readonly series: PivotChartSeries;
  readonly seriesIndex: number;
  readonly value: number
}
```

---

### `HierarchyCategoryValue`

```ts
interface HierarchyCategoryValue {
  readonly category: PivotChartCategory;
  readonly categoryIndex: number;
  readonly total: number;
  readonly values: readonly HierarchySeriesValue[]
}
```

---

### `renderGaugeChart`

```ts
export function renderGaugeChart(
  context: RenderContext,
  options: GaugeOptions,
);
```

---

### `GaugeOptions`

```ts
interface GaugeOptions {
  readonly kind: 'semi' | 'radial';
  readonly attributePrefix: string
}
```

---

### `resolveKpiLayouts`

```ts
export function resolveKpiLayouts(
  bounds: ChartBounds,
  count: number,
): KpiLayout[];
```

---

### `KpiLayout` (Extended from `kpi-layout.ts`)

```ts
interface KpiLayout {
  readonly index: number
}
```

---

### `collectKpiData`

```ts
export function collectKpiData(
  dataset: PivotChartDataset,
  bindings: PivotChartBindings,
): KpiDatum[];
```

---

### `KpiDatum`

```ts
interface KpiDatum {
  readonly categoryIndex: number;
  readonly actual: number;
  readonly target: number;
  readonly variance: number;
  readonly progress: number;
  readonly actualSeriesIndex: number;
  readonly targetSeriesIndex: number;
  readonly varianceSeriesIndex?: number
}
```

---

### `createHeatmapBuckets`

```ts
export function createHeatmapBuckets(
  dataset: PivotChartDataset,
  maximumRows: number,
  maximumColumns: number,
): HeatmapBucket[];
```

---

### `collectCalendarData`

```ts
export function collectCalendarData(
  dataset: PivotChartDataset,
  seriesId?: string,
): CalendarDatum[];
```

---

### `HeatmapBucket`

```ts
interface HeatmapBucket {
  row: number;
  column: number;
  rowStart: number;
  rowEnd: number;
  columnStart: number;
  columnEnd: number;
  count: number;
  value: number;
  category: PivotChartCategory;
  series: PivotChartSeries
}
```

---

### `CalendarDatum`

```ts
interface CalendarDatum {
  category: PivotChartCategory;
  categoryIndex: number;
  series: PivotChartSeries;
  seriesIndex: number;
  value: number;
  epochDay: number;
  day: number;
  week: number
}
```

---

### `renderPolarColumnChart`

```ts
export function renderPolarColumnChart(
  context: RenderContext,
  options: PolarColumnOptions,
);
```

---

### `PolarColumnMode`

```ts
export type PolarColumnMode = 'grouped' | 'stacked' | 'normalized';
```

---

### `PolarColumnOptions`

```ts
interface PolarColumnOptions {
  mode: PolarColumnMode
}
```

---

### `resolvePolarLayout`

```ts
export function resolvePolarLayout(
  context: RenderContext,
  labelPadding = 26,
): PolarLayout;
```

---

### `finitePositiveMaximum`

```ts
export function finitePositiveMaximum(
  values: ReadonlyArray<ReadonlyArray<number | null>>,
  categoryIndexes?: readonly number[],
): number;
```

---

### `appendPolarGrid`

```ts
export function appendPolarGrid(
  context: RenderContext,
  layout: PolarLayout,
  axes = true,
);
```

---

### `valueAt`

```ts
export function valueAt(
  context: RenderContext,
  categoryIndex: number,
  seriesIndex: number,
): number | null;
```

---

### `PolarLayout`

```ts
interface PolarLayout {
  centerX: number;
  centerY: number;
  radius: number;
  categoryIndexes: number[]
}
```

---

### `renderRadarChart`

```ts
export function renderRadarChart(
  context: RenderContext,
  options: RadarOptions,
);
```

---

### `RadarOptions`

```ts
interface RadarOptions {
  area: boolean
}
```

---

### `renderRadialBarChart`

```ts
export function renderRadialBarChart(
  context: RenderContext,
  options: RadialBarOptions,
);
```

---

### `RadialBarOptions`

```ts
interface RadialBarOptions {
  multiRing: boolean
}
```

---

### `renderProcessChart`

```ts
export function renderProcessChart(
  context: RenderContext,
  shape: ProcessShape,
);
```

---

### `createProcessBands`

```ts
export function createProcessBands(
  values: readonly number[],
  bounds: ProcessBounds,
  shape: ProcessShape,
): readonly ProcessBand[];
```

---

### `ProcessShape`

```ts
export type ProcessShape = 'funnel' | 'pyramid';
```

---

### `ProcessBounds`

```ts
interface ProcessBounds {
  readonly left: number;
  readonly top: number;
  readonly width: number;
  readonly height: number
}
```

---

### `ProcessBand`

```ts
interface ProcessBand {
  readonly index: number;
  readonly value: number;
  readonly top: number;
  readonly bottom: number;
  readonly topWidth: number;
  readonly bottomWidth: number;
  readonly points: string
}
```

---

### `collectProcessStages`

```ts
export function collectProcessStages(
  dataset: PivotChartDataset,
): readonly ProcessStage[];
```

---

### `ProcessStage`

```ts
interface ProcessStage {
  readonly category: PivotChartCategory;
  readonly categoryIndex: number;
  readonly series: PivotChartSeries;
  readonly seriesIndex: number;
  readonly value: number
}
```

---

### `renderRangeChart`

```ts
export function renderRangeChart(
  context: RenderContext,
  options: RangeChartOptions,
);
```

---

### `RangeChartOptions`

```ts
interface RangeChartOptions {
  readonly kind: 'bar' | 'area' | 'interval';
  readonly orientation?: 'horizontal' | 'vertical';
  readonly valueMode?: RangeValueMode;
  readonly attribute: string
}
```

---

### `collectRangeData`

```ts
export function collectRangeData(
  dataset: PivotChartDataset,
  bindings: PivotChartBindings,
  mode: RangeValueMode = 'bounds',
): RangeDatum[];
```

---

### `RangeDatum`

```ts
interface RangeDatum {
  readonly categoryIndex: number;
  readonly lower: number;
  readonly upper: number;
  readonly center?: number;
  readonly lowerSeriesIndex: number;
  readonly upperSeriesIndex: number;
  readonly centerSeriesIndex?: number
}
```

---

### `RangeValueMode`

```ts
export type RangeValueMode = 'bounds' | 'centerBounds';
```

---

### `createDensityBins`

```ts
export function createDensityBins(
  points: readonly DensityPoint[],
  radius: number,
): DensityBin[];
```

---

### `DensityPoint`

```ts
interface DensityPoint {
  category: PivotChartCategory;
  categoryIndex: number;
  xSeries: PivotChartSeries;
  xSeriesIndex: number;
  ySeries: PivotChartSeries;
  ySeriesIndex: number;
  x: number;
  y: number;
  plotX: number;
  plotY: number
}
```

---

### `DensityBin`

```ts
interface DensityBin {
  column: number;
  row: number;
  count: number;
  x: number;
  y: number;
  plotX: number;
  plotY: number;
  points: DensityPoint[]
}
```

---

### `renderRelationshipChart`

```ts
export function renderRelationshipChart(
  context: RenderContext,
  options: RelationshipChartOptions,
);
```

---

### `RelationshipChartOptions`

```ts
interface RelationshipChartOptions {
  bubble: boolean
}
```

---

### `prepareStatisticalChart`

```ts
export function prepareStatisticalChart(
  context: RenderContext,
  options?: {
    valueExtent?: (datum: StatisticalDatum) => readonly [number, number];
  },
): StatisticalChartLayout | undefined;
```

---

### `appendStatisticalCategoryLabels`

```ts
export function appendStatisticalCategoryLabels(
  context: RenderContext,
  categorySize: number,
);
```

---

### `statisticalCategoryCenter`

```ts
export function statisticalCategoryCenter(
  context: RenderContext,
  categoryIndex: number,
  categorySize: number,
);
```

---

### `statisticalValueY`

```ts
export function statisticalValueY(
  context: RenderContext,
  scale: StatisticalChartLayout['scale'],
  value: number,
);
```

---

### `StatisticalChartLayout`

```ts
interface StatisticalChartLayout {
  readonly data: StatisticalDatum[];
  readonly scale: ReturnType<typeof createValueScale>;
  readonly categorySize: number
}
```

---

# Pivot Config

URL: https://pro.rv-grid.com/api/pivot-config/
Source: src/content/docs/api/pivot-config.md

### `DimensionsPanel`

Owns the shared search control and the empty state around the dimensions grid.

```ts
DimensionsPanel: ({ dimensions, selection, allowFieldDragging, onDragStart, onDragEnd, onSelectionChange, search, onSearch, i18n, }: DimensionsPanelProps) => preact.JSX.Element;
```

---

### `filterPivotDimensions`

```ts
export function filterPivotDimensions(
  dimensions: PivotConfigDimension[],
  query = '',
  options: PivotFieldSearchOptions = {},
);
```

---

### `PivotFieldSearchOptions`

```ts
interface PivotFieldSearchOptions {
  /** Include dimensions marked hidden in the returned field list. */
    showHidden?: boolean
}
```

---

### `pivotConfigUiDependencies`

#### Dependencies

- **Required** `aggregators`: Uses Pro aggregation definitions for built-in value aggregation options.
- **Required** `pro-ui`: Uses Pro UI helper components and styles for configurator controls.

```ts
pivotConfigUiDependencies: PluginDependency[];
```

---

### `definePivotConfigurator`

The `PivotConfigurator` component provides a flexible configuration interface
for managing pivot table layouts. It allows users to drag and drop dimensions,
rows, columns, and values into designated zones, facilitating dynamic pivot
table setup.

 **Features**:
- Supports drag-and-drop functionality for configuring rows, columns, and values.
- Enables dynamic selection and removal of dimensions, rows, columns, and values.
- Includes built-in aggregator selection for values based on dimensions.
- Provides customizable i18n support for localization of UI labels and messages.

**Usage**:
- Import `PivotConfigurator` and pass in the required dimensions, columns, rows,
  and values as props.
- Optionally, provide callbacks for `onUpdateColumns`, `onUpdateRows`, and
  `onUpdateValues` to handle configuration changes.

### Example
```ts
import { definePivotConfigurator } from '@revolist/revogrid-pro'

definePivotConfigurator(yourElement, {
  dimensions: [...],
  rows: [...],
  columns: [...],
  values: [...],
}, {
  onUpdateColumns: (updatedColumns) => {
    // Handle column configuration changes
  },
  onUpdateRows: (updatedRows) => {
    // Handle row configuration changes
  },
  onUpdateValues: (updatedValues) => {
    // Handle value configuration changes
  },
}, undefined, {
  columnTypes: grid.columnTypes,
  additionalData: grid.additionalData,
})
```

The `PivotConfigurator` component is ideal for applications that require
flexible, user-driven pivot table customization, especially in data management,
reporting, and analytics tools.

Mounts the standalone Pivot configurator into any host element.

Use this when you want the drag-and-drop Pivot field panel outside of the
default `PivotPlugin` wrapper, or when you need to drive Pivot state from an
external UI shell.

```ts
definePivotConfigurator: (el: HTMLElement, config?: Partial<PivotConfig>, actions?: Partial<PivotConfigurationActions>, diagnostics?: PivotUiDiagnostics | undefined, templateContext?: { columnTypes?: ColumnTypes; additionalData?: unknown }) => () => void;
```

---

### `disposePivotConfigurator`

Unmounts a standalone configurator and removes classes added by its mount helper.

```ts
disposePivotConfigurator: (el: HTMLElement) => void;
```

---

### `definePivotFieldPanel`

Mounts the compact in-grid Pivot field panel into a host element.

Unlike the standalone configurator, this panel is intended to sit above the
Pivot grid and expose the active filter, data, row, and column field areas.

```ts
definePivotFieldPanel: (el: HTMLElement, config?: Partial<PivotConfig>, actions?: Partial<PivotConfigurationActions>, layout?: { columns?: (ColumnRegular<ColumnProp, DataType<any, ColumnProp>> | ColumnGrouping<any>)[] | undefined; colSize?: number | undefined; resizedColumns?: ColumnResizeDetail; } | undefined, diagnostics?: PivotUiDiagnostics | undefined, templateContext?: { columnTypes?: ColumnTypes; additionalData?: unknown }) => () => void;
```

---

### `disposePivotFieldPanel`

Unmounts a compact field panel and removes mount-helper presentation state.

```ts
disposePivotFieldPanel: (el: HTMLElement) => void;
```

---

### `PivotConfigurationActions`

```ts
interface PivotConfigurationActions {
  /** Applies several related layout changes as one Pivot regeneration. */
    onUpdateConfiguration?: (patch: PivotConfigurationPatch) => void;
  /** Called whenever the configurator updates the ordered column dimension list. */
    onUpdateColumns?: (cols: ColumnProp[]) => void;
  /** Called whenever the configurator updates the ordered row dimension list. */
    onUpdateRows?: (rows: ColumnProp[]) => void;
  /** Called whenever the configurator updates the selected measures or aggregators. */
    onUpdateValues?: (values: PivotConfigValue[]) => void;
  /** Called whenever the configurator updates the ordered filter field list. */
    onUpdateFilters?: (filters: ColumnProp[]) => void;
  /** Called whenever the configurator changes selected filter values. */
    onUpdateFilterSelections?: (selections: PivotFilterSelectionMap) => void;
  /** Current sorting order used by the field panel. */
    sorting?: SortingOrder;
  /** Called when a field-panel sort control is toggled. */
    onToggleSort?: (prop: ColumnProp) => void;
  /** Called when the user clears the active Pivot layout. */
    onResetLayout?: () => void
}
```

---

### `PivotConfigurationPatch`

```ts
export type PivotConfigurationPatch = Pick<
  Partial<PivotConfig>,
  'columns' | 'rows' | 'values' | 'filters'
>;
```

---

### `PivotConfigurator`

```ts
PivotConfigurator: ({ dimensions, columns, rows, values, filters, filterSelections, i18n, fieldPanel, showColumns, showRows, showValues, showFilters, onUpdateConfiguration, onUpdateColumns: onUpdateColumnsCallback, onUpdateRows: onUpdateRowsCallback, onUpdateValues: onUpdateValuesCallback, onUpdateFilters: onUpdateFiltersCallback, onUpdateFilterSelections, onResetLayout, diagnostics, }?: Partial<PivotConfigurationComponentProps>) => preact.JSX.Element;
```

---

### `PivotFieldPanel`

```ts
PivotFieldPanel: ({ dimensions, columns, rows, values, filters, filterSelections, fieldPanel, i18n, showColumns, showRows, showValues, showFilters, onUpdateConfiguration, onUpdateColumns, onUpdateRows, onUpdateValues, onUpdateFilters, onUpdateFilterSelections, sorting, onToggleSort, onResetLayout, diagnostics, }?: Partial<PivotFieldPanelProps>) => preact.JSX.Element;
```

---

### `DropZone`

```ts
DropZone: ({ title, panel, items, dimensions, placeholder, i18n, renderItem, onRemove, onDrop, onDragOver, onDragEnter, onItemDragStart, onItemDragEnd, allowFieldDragging, }: DropZoneProps) => preact.JSX.Element;
```

---

### `ValueSelector`

```ts
ValueSelector: ({ value, aggregators, ariaLabel, onUpdateValue, }: ValueSelectorProps) => preact.JSX.Element;
```

---

### `FilterSelector`

```ts
FilterSelector: ({ allLabel, ariaLabel, options, selected, onUpdateSelection, }: FilterSelectorProps) => preact.JSX.Element;
```

---

### `PIVOT_DIMENSION_DRAG_MIME`

```ts
PIVOT_DIMENSION_DRAG_MIME: string;
```

---

### `DraggingItem`

The item being dragged

```ts
interface DraggingItem {
  /** The source panel of the dragging item */
    source: PanelType;
  /** The index of the dragging item in the source panel */
    index: number;
  /** Dragging item */
    prop: ColumnProp;
  /** Ordered field bundle when a dimensions group is dragged. */
    props?: ColumnProp[];
  /** The drag originated from a synthetic dimensions group row. */
    isGroup?: boolean
}
```

---

### `PIVOT_CONFIG_EN`

```ts
PIVOT_CONFIG_EN: {
  fields: string;
  rows: string;
  columns: string;
  values: string;
  filters: string;
  fieldPanel: string;
  rowsPanelHint: string;
  columnsPanelHint: string;
  valuesPanelHint: string;
  filtersPanelHint: string;
  dropFilterFieldsHere: string;
  dragHereRows: string;
  dragHereColumns: string;
  dragHereValues: string;
  dragHereFilters: string;
  dragDimension: (label: string) => string;
  dragDimensionGroup: (label: string) => string;
  searchFields: string;
  noFieldsFound: string;
  otherFields: string;
  swapRowsColumns: string;
  resetLayout: string;
  sortField: (label: string) => string;
  filterValue: (label: string) => string;
  all: string;
  pivotWarnings: string;
  pivotError: string;
  remove: string;
};
```

---

### `getPivotFieldPanelRowsWidth`

Resolves the pixel width of the Pivot "rows" section based on current grid
columns and optional live resize payload.

```ts
export function getPivotFieldPanelRowsWidth(
  config: Partial<PivotConfig> | null | undefined,
  columns: (ColumnGrouping | ColumnRegular)[] = [],
  defaultSize = 100,
  resizedColumns?: ColumnResizeDetail,
);
```

---

### `ColumnResizeDetail`

```ts
export type ColumnResizeDetail = Record<number, ColumnRegular> | undefined;
```

---

### `hasPivotDiagnostics`

```ts
export function hasPivotDiagnostics(diagnostics?: PivotUiDiagnostics);
```

---

### `PivotUiDiagnostics`

```ts
interface PivotUiDiagnostics {
  warnings?: string[];
  error?: string
}
```

---

### `PivotDiagnostics`

```ts
PivotDiagnostics: ({ diagnostics, i18n, }: { diagnostics?: PivotUiDiagnostics | undefined; i18n?: { fields: string; rows: string; columns: string; values: string; filters: string; fieldPanel: string; rowsPanelHint: string; columnsPanelHint: string; valuesPanelHint: string; filtersPanelHint: string; dropFilterFieldsHere: string; dragHereRows: string; dragHereColumns: string; dragHereValues: string; dragHereFilters: string; dragDimension: (label: string) => string; dragDimensionGroup: (label: string) => string; searchFields: string; noFieldsFound: string; otherFields: string; swapRowsColumns: string; resetLayout: string; sortField: (label: string) => string; filterValue: (label: string) => string; all: string; pivotWarnings: string; pivotError: string; remove: string; } | undefined; }) => preact.JSX.Element | null;
```

---

### `PivotAxes`

```ts
interface PivotAxes {
  rows: ColumnProp[];
  columns: ColumnProp[]
}
```

---

### `transposePivotAxes`

```ts
transposePivotAxes: (rows: readonly ColumnProp[], columns: readonly ColumnProp[]) => PivotAxes;
```

---

### `PivotAxisSwap`

```ts
PivotAxisSwap: ({ disabled, label, onClick, }: PivotAxisSwapProps) => preact.JSX.Element;
```

---

### `usePivotDimensionColumns`

```ts
export function usePivotDimensionColumns({
  allowFieldDragging,
  nested,
  selectionRef,
  groupPropsRef,
  i18n,
}: PivotDimensionColumnsOptions);
```

---

### `usePivotDimensionDrag`

```ts
export function usePivotDimensionDrag({
  boundaryRef,
  allDimensions,
  groupPropsRef,
  nativeDraggingRef,
  suppressSelectionEventsRef,
  cancelPendingSelection,
  restoreSelectionAfterDragGesture,
  onDragStartRef,
  onDragEndRef,
}: PivotDimensionDragOptions);
```

---

### `PivotDimensionEventController`

Owns DOM subscriptions and adjacent resources for one dimensions-grid scope.
Keeping teardown here prevents listener options and cleanup order from
drifting across hooks as interactions evolve.

```ts
class PivotDimensionEventController {
  listen<TEvent extends Event>(
    target: EventTarget,
    type: string,
    listener: (event: TEvent) => void,
    options?: boolean | AddEventListenerOptions,
  );

  addCleanup(cleanup: EventCleanup);

  dispose();
}
```

---

### `usePivotDimensionGridLifecycle`

```ts
export function usePivotDimensionGridLifecycle({
  boundaryRef,
  gridRef,
  rows,
  columns,
  plugins,
  grouped,
  nested,
  search,
  groupLabelTemplate,
  searchRef,
  expandedGroupsRef,
  nativeDraggingRef,
  suppressSelectionEventsRef,
  syncSelection,
}: PivotDimensionGridLifecycleOptions);
```

---

### `usePivotDimensionSelection`

```ts
export function usePivotDimensionSelection({
  gridRef,
  rows,
  selection,
  nativeDraggingRef,
  onSelectionChange,
}: PivotDimensionSelectionOptions);
```

---

### `createExpandedGroupOverlay`

```ts
export function createExpandedGroupOverlay(): ExpandedGroupOverlay;
```

---

### `readExpandedGroups`

```ts
export function readExpandedGroups(
  source: Record<string, unknown>[],
  overlay: ExpandedGroupOverlay,
);
```

---

### `resolvePivotDimensionGrouping`

```ts
export function resolvePivotDimensionGrouping(
  rows: PivotDimensionGridRow[],
  search: string,
  overlay: ExpandedGroupOverlay,
  groupLabelTemplate: GroupLabelTemplateFunc,
): GroupingOptions;
```

---

### `getPivotDimensionRowSelectPlugin`

```ts
export function getPivotDimensionRowSelectPlugin(plugins: unknown[]);
```

---

### `isPivotDimensionsGridReady`

```ts
export function isPivotDimensionsGridReady(grid: HTMLRevoGridElement);
```

---

### `getPivotDimensionsViewportHeight`

```ts
export function getPivotDimensionsViewportHeight(
  dimensions: PivotConfigDimension[],
  grouped: boolean,
  otherFieldsLabel: string,
);
```

---

### `createPivotDimensionGroupProps`

```ts
export function createPivotDimensionGroupProps(
  dimensions: PivotConfigDimension[],
  nested: boolean,
  otherFieldsLabel: string,
  getGroupId: (path: string[]) => string,
);
```

---

### `PIVOT_DIMENSION_GROUP_PROP`

```ts
PIVOT_DIMENSION_GROUP_PROP: string;
```

---

### `PIVOT_DIMENSION_ROW_TYPE`

```ts
PIVOT_DIMENSION_ROW_TYPE: string;
```

---

### `PIVOT_DIMENSION_COMPACT_ROW_SIZE`

```ts
PIVOT_DIMENSION_COMPACT_ROW_SIZE: 24;
```

---

### `CurrentRef`

```ts
interface CurrentRef {
  current: T
}
```

---

### `ExpandedGroupOverlay`

```ts
interface ExpandedGroupOverlay {
  expanded: Set<string>;
  collapsed: Set<string>;
  known: Set<string>
}
```

---

### `renderPivotDimensionIcon`

```ts
export function renderPivotDimensionIcon(
  createElement: HyperFunc<VNode> | typeof import('preact').h,
  dimension?: Pick<PivotConfigDimension, 'columnType'>,
);
```

---

### `createPivotDimensionGroupLabelTemplate`

```ts
export function createPivotDimensionGroupLabelTemplate(): GroupLabelTemplateFunc;
```

---

### `createPivotDimensionDragCellTemplate`

```ts
export function createPivotDimensionDragCellTemplate({
  allowFieldDragging,
  selectionRef,
  groupPropsRef,
  i18n,
}: PivotDimensionTemplateOptions): DimensionCellTemplate;
```

---

### `createPivotDimensionFieldCellTemplate`

```ts
export function createPivotDimensionFieldCellTemplate(): DimensionCellTemplate;
```

---

### `createPivotDimensionFieldCellProperties`

```ts
export function createPivotDimensionFieldCellProperties(): DimensionCellProperties;
```

---

### `PivotDimensionsGrid`

```ts
PivotDimensionsGrid: ({ dimensions, allDimensions, selection, allowFieldDragging, search, otherFieldsLabel, i18n, onDragStart, onDragEnd, onSelectionChange, }: PivotDimensionsGridProps) => preact.JSX.Element;
```

---

### `getPivotDimensionLabel`

```ts
export function getPivotDimensionLabel(dimension: PivotConfigDimension);
```

---

### `indexPivotDimensionsByProp`

```ts
export function indexPivotDimensionsByProp(
  dimensions: readonly PivotConfigDimension[],
);
```

---

### `getUniquePivotDimensions`

```ts
export function getUniquePivotDimensions(
  dimensions: readonly PivotConfigDimension[],
);
```

---

### `hasPivotDimensionGroups`

```ts
export function hasPivotDimensionGroups(
  dimensions: readonly PivotConfigDimension[],
);
```

---

### `getPivotDimensionGroupPath`

```ts
export function getPivotDimensionGroupPath(
  dimension: PivotConfigDimension,
): string[];
```

---

### `hasNestedPivotDimensionGroups`

```ts
export function hasNestedPivotDimensionGroups(
  dimensions: readonly PivotConfigDimension[],
);
```

---

### `createPivotDimensionGridRows`

```ts
export function createPivotDimensionGridRows(
  dimensions: readonly PivotConfigDimension[],
  options: {
    grouped: boolean;
    otherFieldsLabel: string;
    allDimensions?: readonly PivotConfigDimension[];
  },
): PivotDimensionGridRow[];
```

---

### `getPivotDimensionGroupId`

```ts
export function getPivotDimensionGroupId(path: readonly string[]);
```

---

### `createPivotDimensionTreeRows`

Projects variable-depth group paths into a flat source for TreeDataPlugin.

```ts
export function createPivotDimensionTreeRows(
  dimensions: readonly PivotConfigDimension[],
  options: {
    otherFieldsLabel: string;
    allDimensions?: readonly PivotConfigDimension[];
  },
): PivotDimensionGridRow[];
```

---

### `getSelectedPivotDimensionProps`

```ts
export function getSelectedPivotDimensionProps(
  state: PivotDimensionSelectionState,
);
```

---

### `resolvePivotDimensionSelectionTarget`

Resolves where a newly checked dimension should be placed.

```ts
export function resolvePivotDimensionSelectionTarget(
  dimension: PivotConfigDimension,
): NonNullable<PivotConfigDimension['selectionTarget']>;
```

---

### `reconcilePivotDimensionSelection`

Reconciles checkbox state for only the rows currently represented by the
dimensions grid. Fields hidden by search are deliberately left untouched.

```ts
export function reconcilePivotDimensionSelection(
  state: PivotDimensionSelectionState,
  visibleDimensions: readonly PivotConfigDimension[],
  selectedVisibleProps: ReadonlySet<ColumnProp>,
): PivotDimensionSelectionState;
```

---

### `movePivotDimensionBundle`

Places an ordered field-group bundle using the same role rules as a single
field: axes are exclusive while Filters and Values remain independent.

```ts
export function movePivotDimensionBundle(
  state: PivotDimensionLayoutState,
  target: Exclude<PanelType, 'dimensions'>,
  props: readonly ColumnProp[],
  options: {
    index?: number;
    createValue: (prop: ColumnProp) => PivotConfigValue;
  },
): PivotDimensionLayoutState;
```

---

### `areColumnPropArraysEqual`

```ts
export function areColumnPropArraysEqual(
  left: readonly ColumnProp[],
  right: readonly ColumnProp[],
);
```

---

### `arePivotValuesEqual`

```ts
export function arePivotValuesEqual(
  left: readonly PivotConfigValue[],
  right: readonly PivotConfigValue[],
);
```

---

### `createPivotConfigValue`

```ts
export function createPivotConfigValue(
  prop: ColumnProp,
  dimension?: PivotConfigDimension,
): PivotConfigValue;
```

---

### `getPivotDimensionAggregators`

```ts
export function getPivotDimensionAggregators(
  dimension?: PivotConfigDimension,
);
```

---

### `movePivotField`

Places one source field using Excel-compatible Pivot roles.
Rows and Columns are exclusive axis placements. Filters and Values are
independent roles, so a field can filter source data without disappearing
from an axis or the summarized values.

```ts
export function movePivotField(
  state: PivotFieldLayoutState,
  _source: PanelType,
  target: Exclude<PanelType, 'dimensions'>,
  prop: ColumnProp,
  options: {
    index?: number;
    createValue: (prop: ColumnProp) => PivotConfigValue;
  },
): PivotFieldLayoutState;
```

---

### `PIVOT_DIMENSION_MODEL`

```ts
PIVOT_DIMENSION_MODEL: string;
```

---

### `PIVOT_DIMENSION_INDEX`

```ts
PIVOT_DIMENSION_INDEX: string;
```

---

### `PIVOT_DIMENSION_LABEL`

```ts
PIVOT_DIMENSION_LABEL: string;
```

---

### `PIVOT_DIMENSION_TREE_ID`

```ts
PIVOT_DIMENSION_TREE_ID: string;
```

---

### `PIVOT_DIMENSION_TREE_PARENT_ID`

```ts
PIVOT_DIMENSION_TREE_PARENT_ID: string;
```

---

### `PIVOT_DIMENSION_ROW_CLASS`

```ts
PIVOT_DIMENSION_ROW_CLASS: string;
```

---

### `PIVOT_DIMENSION_GROUP_PATH`

```ts
PIVOT_DIMENSION_GROUP_PATH: string;
```

---

### `PivotDimensionGridRow` (Extended from `pivot.config.dimension.model.ts`)

```ts
interface PivotDimensionGridRow {
  [PIVOT_DIMENSION_MODEL]?: PivotConfigDimension;
  [PIVOT_DIMENSION_INDEX]: number;
  [PIVOT_DIMENSION_LABEL]: string;
  [PIVOT_DIMENSION_TREE_ID]?: string;
  [PIVOT_DIMENSION_TREE_PARENT_ID]?: string | null;
  [PIVOT_DIMENSION_ROW_CLASS]?: string;
  [PIVOT_DIMENSION_GROUP_PATH]?: string[];
  fieldGroup?: string
}
```

---

### `PivotDimensionSelectionState`

```ts
interface PivotDimensionSelectionState {
  rows: ColumnProp[];
  columns: ColumnProp[];
  values: PivotConfigValue[]
}
```

---

### `PivotDimensionLayoutState` (Extended from `pivot.config.dimension.model.ts`)

```ts
interface PivotDimensionLayoutState {
  filters: ColumnProp[]
}
```

---

### `PivotDimensionSelectionChangeDetail`

```ts
interface PivotDimensionSelectionChangeDetail {
  /** More than one visible leaf changed in the same RowSelect event. */
    bulk: boolean
}
```

---

# Plugin Dependencies

URL: https://pro.rv-grid.com/api/plugin-dependencies/
Source: src/content/docs/api/plugin-dependencies.md

### `ensurePlugin`

Return an existing plugin instance by class, or create and register one.

Use this for auto-installed plugin dependencies so host-provided plugin
instances are reused and duplicate runtime plugins are not added. On Core
runtimes, dependencies declared through `pluginDependencies` are retained
while any configured owner needs them and removed after their final owner.
The owning plugin must declare the same class as an `auto-installed` target
so runtime `grid.plugins` updates can resolve the ownership graph.

```ts
export function ensurePlugin<T extends PluginBaseComponent>(
  providers: PluginProviders,
  pluginClass: RuntimePluginConstructor & (new (...args: any[]) => T),
  createPlugin: () => T,
): T;
```

---

### `PluginDependencyKind`

```ts
export type PluginDependencyKind =
  | 'required'
  | 'optional'
  | 'auto-installed'
  | 'event-integration'
  | 'config-integration'
  | 'ordering';
```

---

### `PluginDependencyPluginConstructor`

```ts
export type PluginDependencyPluginConstructor = abstract new (...args: any[]) => unknown;
```

---

### `PluginDependencyPluginRef`

```ts
export type PluginDependencyPluginRef =
  | PluginDependencyPluginConstructor
  | (() => PluginDependencyPluginConstructor);
```

---

### `PluginDependencyContract`

```ts
export type PluginDependencyContract =
  | 'aggregators'
  | 'auto-size-column'
  | 'column-types'
  | 'column-selection-handoff'
  | 'core-grouping'
  | 'direct-event-manager-config'
  | 'direct-history-config'
  | 'filtering'
  | 'direct-pagination-config'
  | 'direct-pivot-config'
  | 'direct-tree-config'
  | 'gantt-runtime'
  | 'json-clipboard'
  | 'multi-range-selection'
  | 'overlay-producer'
  | 'pagination-capable-plugin'
  | 'pro-plugin-infrastructure'
  | 'pro-ui'
  | 'row-order'
  | 'row-select'
  | 'sorting-capable-plugin'
  | 'tree-data';
```

---

### `PluginDependencyAdditionalDataKey` (Extended from `index.ts`)

```ts
export type PluginDependencyAdditionalDataKey = keyof AdditionalData & string;
```

---

### `PluginDependencyTarget`

```ts
export type PluginDependencyTarget =
  | {
    readonly type: 'plugin';
    readonly plugin: PluginDependencyPluginRef;
  }
  | {
    readonly type: 'plugins';
    readonly plugins: readonly PluginDependencyPluginRef[];
    readonly mode?: 'all' | 'one-of';
  }
  | {
    readonly type: 'additionalData';
    readonly key: PluginDependencyAdditionalDataKey;
    readonly path?: readonly string[];
  }
  | {
    readonly type: 'event';
    readonly event: keyof HTMLRevoGridElementEventMap & string;
  }
  | {
    readonly type: 'events';
    readonly events: readonly (keyof HTMLRevoGridElementEventMap & string)[];
  }
  | {
    readonly type: 'contract';
    readonly contract: PluginDependencyContract;
  }
  | {
    readonly type: 'property';
    readonly property: keyof HTMLRevoGridElement & string;
    readonly path?: readonly string[];
  }
  | {
    readonly type: 'ordering';
    readonly relativeTo: 'other-grid-plugins';
    readonly position: 'before' | 'after';
  };
```

---

### `PluginDependency`

```ts
interface PluginDependency {
  kind: PluginDependencyKind;
  target: PluginDependencyTarget | readonly PluginDependencyTarget[];
  description: string
}
```

---

### `warnRequiredPluginDependencies`

Warns when required plugin class dependencies are missing.

Metadata remains descriptive: this does not auto-install, reorder, or block plugin execution.

```ts
warnRequiredPluginDependencies: (plugin: unknown, providers: PluginProviders, dependencies?: readonly PluginDependency[] | undefined) => void;
```

---

# Range Copy Preview

URL: https://pro.rv-grid.com/api/range-copy-preview/
Source: src/content/docs/api/range-copy-preview.md

### `computeRangeCopyPreviewData`

Computes the exact range-copy values for a temporary drag target.

**@param** options Source range, target range, row/column types, and providers.

**@returns** Preview matrix and row/prop lookup, or `null` when no copy preview can be computed.

```ts
export function computeRangeCopyPreviewData({
  oldRange,
  newRange,
  type,
  colType,
  providers,
}: RangeCopyPreviewComputeOptions): RangeCopyPreviewComputedData | null;
```

---

### `mapRangeCopyMatrixToData`

Maps a copied source matrix onto a target range using RevoGrid range-copy semantics.

**@param** matrix Source values ordered row-major.

**@param** source Source range to exclude from target writes.

**@param** target Target range to preview.

**@param** providers Plugin providers used to resolve target columns.

**@param** colType Column dimension type.

**@returns** Row/prop lookup for preview rendering.

```ts
export function mapRangeCopyMatrixToData(
  matrix: unknown[][],
  source: RangeArea,
  target: RangeArea,
  providers: Pick<PluginProviders, 'column'>,
  colType: DimensionCols,
): Record<number, DataType>;
```

---

### `isInRange`

```ts
export function isInRange(row: number, col: number, range: RangeArea);
```

---

### `RangeCopyPreviewComputedData`

```ts
export type RangeCopyPreviewComputedData = {
  matrix: unknown[][];
  data: Record<number, DataType>;
};
```

---

### `RangeCopyPreviewComputeOptions` (Extended from `index.ts`)

```ts
export type RangeCopyPreviewComputeOptions = Pick<ChangedRange, 'oldRange' | 'newRange'> & {
  type: DimensionRows;
  colType: DimensionCols;
  providers: PluginProviders;
};
```

---

### `RangeCopyPreviewPlugin`

The `RangeCopyPreviewPlugin` renders ghost values for the exact range copy
that RevoGrid will apply when the user drops an autofill/range-copy drag.

**Features**:
- Shows copied source values while dragging the fill handle.
- Uses copy semantics only; it does not infer AutoFill sequences.
- Keeps preview view-only and never writes to the data store.
- Clears preview on drop, cancel, source changes, and plugin destruction.

### Example
```typescript
import { RangeCopyPreviewPlugin } from '@revolist/revogrid-pro';

grid.plugins = [RangeCopyPreviewPlugin];
```

```ts
class RangeCopyPreviewPlugin {
  destroy();
}
```

---

# Range Selection Limit

URL: https://pro.rv-grid.com/api/range-selection-limit/
Source: src/content/docs/api/range-selection-limit.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  /**
       * Direct range selection limit configuration.
       */
      rangeSelectionLimit?: RangeSelectionLimitConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data property for range selection limiting.
       * @deprecated Use `grid.rangeSelectionLimit` instead.
       */
      rangeSelectionLimit?: RangeSelectionLimitConfig
}
```

## Plugin API

### `RangeSelectionLimitPlugin`

Constrains interactive range selection to a single row or column.

The plugin intercepts `beforeapplyrange`, normalizes the pending range, and
lets the regular RevoGrid `setrange` flow continue. It does not change data,
create a render layer, or block single-cell focus.

### Example
```ts
import { RangeSelectionLimitPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.range = true;
grid.plugins = [RangeSelectionLimitPlugin];
grid.rangeSelectionLimit = { mode: 'column' };
```

### Row-only selection
```ts
grid.rangeSelectionLimit = { mode: 'row' };
```

### Boolean shorthand
```ts
grid.rangeSelectionLimit = true; // same as { mode: 'column' }
grid.rangeSelectionLimit = false; // disabled
```

#### Dependencies

- **Config integration** `additionalData.rangeSelectionLimit`: Reads legacy range selection limit configuration from additionalData.rangeSelectionLimit.

```ts
class RangeSelectionLimitPlugin {
  destroy();
}
```

---

### `limitRangeSelection`

Normalizes a pending RevoGrid range to match the configured range limit mode.

`column` mode pins `x` and `x1` to the focused column so the range can only
expand vertically. `row` mode pins `y` and `y1` to the focused row so the
range can only expand horizontally. Disabled config returns a cloned range.

**@param** range Pending range emitted by `beforeapplyrange`.

**@param** focus Current focused cell used as the range anchor.

**@param** config Normalized range selection limit configuration.

**@returns** A range constrained to the configured mode.

**Example:**
```typescript
limitRangeSelection(
  { x: 0, y: 0, x1: 5, y1: 8 },
  { x: 2, y: 1 },
  { mode: 'column' },
);
// { x: 2, y: 0, x1: 2, y1: 8 }
```

**Example:**
```typescript
limitRangeSelection(
  { x: 0, y: 0, x1: 5, y1: 8 },
  { x: 2, y: 1 },
  { mode: 'row' },
);
// { x: 0, y: 1, x1: 5, y1: 1 }
```

```ts
export function limitRangeSelection(
  range: RangeArea,
  focus: Cell | null | undefined,
  config: NormalizedRangeSelectionLimitConfig,
): RangeArea;
```

---

### `normalizeRangeSelectionLimitConfig`

Converts public `rangeSelectionLimit` shorthand into the internal plugin shape.

**@param** config Public grid or `additionalData` configuration.

**@returns** Normalized configuration with `mode: null` when disabled.

**Example:**
```typescript
normalizeRangeSelectionLimitConfig(true);
// { mode: 'column' }

normalizeRangeSelectionLimitConfig('row');
// { mode: 'row' }
```

```ts
export function normalizeRangeSelectionLimitConfig(
  config?: RangeSelectionLimitConfig,
): NormalizedRangeSelectionLimitConfig;
```

---

### `RangeSelectionLimitMode`

Built-in range selection limit modes.

**Example:**
```typescript
grid.rangeSelectionLimit = 'column';
grid.rangeSelectionLimit = 'row';
```

```ts
/**
 * Built-in range selection limit modes.
 *
 * @example
 * ```ts
 * grid.rangeSelectionLimit = 'column';
 * grid.rangeSelectionLimit = 'row';
 * ```
 */
export type RangeSelectionLimitMode = 'column' | 'row';
```

---

### `RangeSelectionLimitOptions`

Object form for range selection limit configuration.

Use the object form when you want a stable extension point for future options,
such as validator-backed shapes.

**Example:**
```typescript
grid.rangeSelectionLimit = {
  mode: 'column',
};
```

```ts
/**
 * Object form for range selection limit configuration.
 *
 * Use the object form when you want a stable extension point for future options,
 * such as validator-backed shapes.
 *
 * @example
 * ```ts
 * grid.rangeSelectionLimit = {
 *   mode: 'column',
 * };
 * ```
 */
export type RangeSelectionLimitOptions = {
  /**
   * Selection shape limit.
   * - `column` keeps the focused column fixed and allows row expansion.
   * - `row` keeps the focused row fixed and allows column expansion.
   */
  mode: RangeSelectionLimitMode;
};
```

---

### `RangeSelectionLimitConfig`

Public plugin configuration for `RangeSelectionLimitPlugin`.

Supported shorthand:
- `true` enables the default `column` mode.
- `false` disables the plugin behavior.
- `'column'` or `'row'` enables the matching built-in mode.

**Example:**
```typescript
import { RangeSelectionLimitPlugin } from '@revolist/revogrid-pro';

grid.range = true;
grid.plugins = [RangeSelectionLimitPlugin];
grid.rangeSelectionLimit = { mode: 'row' };
```

**Example:**
```typescript
grid.rangeSelectionLimit = true; // same as { mode: 'column' }
grid.rangeSelectionLimit = false; // disabled
```

```ts
/**
 * Public plugin configuration for `RangeSelectionLimitPlugin`.
 *
 * Supported shorthand:
 * - `true` enables the default `column` mode.
 * - `false` disables the plugin behavior.
 * - `'column'` or `'row'` enables the matching built-in mode.
 *
 * @example
 * ```ts
 * import { RangeSelectionLimitPlugin } from '@revolist/revogrid-pro';
 *
 * grid.range = true;
 * grid.plugins = [RangeSelectionLimitPlugin];
 * grid.rangeSelectionLimit = { mode: 'row' };
 * ```
 *
 * @example
 * ```ts
 * grid.rangeSelectionLimit = true; // same as { mode: 'column' }
 * grid.rangeSelectionLimit = false; // disabled
 * ```
 */
export type RangeSelectionLimitConfig =
  | boolean
  | RangeSelectionLimitMode
  | RangeSelectionLimitOptions;
```

---

### `NormalizedRangeSelectionLimitConfig`

```ts
export type NormalizedRangeSelectionLimitConfig = {
  mode: RangeSelectionLimitMode | null;
};
```

---

# Resource Picker

URL: https://pro.rv-grid.com/api/resource-picker/
Source: src/content/docs/api/resource-picker.md

### `ResourcePickerClassNames`

```ts
interface ResourcePickerClassNames {
  readonly root?: string;
  readonly search?: string;
  readonly list?: string;
  readonly option?: string;
  readonly avatar?: string;
  readonly details?: string;
  readonly muted?: string
}
```

---

### `ResourcePickerId`

```ts
export type ResourcePickerId = ResourceIdentityId;
```

---

### `ResourcePickerItem` (Extended from `index.ts`)

```ts
interface ResourcePickerItem {
  readonly color?: string
}
```

---

### `ResourcePickerText`

```ts
interface ResourcePickerText {
  readonly groupAriaLabel: string;
  readonly searchPlaceholder: string;
  readonly searchAriaLabel: string;
  readonly emptyResources: string;
  readonly emptySearch: string
}
```

---

### `ResourcePickerUnassignedOption`

```ts
interface ResourcePickerUnassignedOption {
  readonly label: string;
  readonly dataAttribute?: string
}
```

---

### `SharedResourcePickerProps`

```ts
interface SharedResourcePickerProps {
  readonly resources: readonly Resource[];
  readonly selectedResourceIds: readonly Id[];
  readonly text: ResourcePickerText;
  readonly onChange: (resourceIds: readonly Id[]) => void;
  readonly classNames?: ResourcePickerClassNames;
  readonly disabled?: boolean;
  /** Keeps the full list visible or presents it as a compact combobox. */
    readonly presentation?: 'inline' | 'dropdown';
  /** Allows more than one selected resource. Defaults to true. */
    readonly multiple?: boolean;
  /** Keeps resources in caller-provided order instead of sorting by name. */
    readonly preserveOrder?: boolean;
  readonly unassigned?: ResourcePickerUnassignedOption;
  readonly resourceDataAttribute?: string;
  readonly isResourceDisabled?: (resource: Resource) => boolean;
  readonly getAvatarColor?: (resource: Resource) => string | undefined
}
```

---

### `SharedResourcePicker`

```ts
export function SharedResourcePicker<
  Id extends ResourcePickerId,
  Resource extends ResourcePickerItem<Id>,
>({
  resources,
  selectedResourceIds,
  text,
  onChange,
  classNames,
  disabled = false,
  presentation = 'inline',
  multiple = true,
  preserveOrder = false,
  unassigned,
  resourceDataAttribute,
  isResourceDisabled,
  getAvatarColor,
}: SharedResourcePickerProps<Id, Resource>);
```

---

### `getResourcePickerInitials`

```ts
export function getResourcePickerInitials(name: string): string;
```

---

### `getResourcePickerColor`

```ts
export function getResourcePickerColor(id: ResourcePickerId): string;
```

---

### `getResourcePickerForegroundColor`

Chooses readable initials for hex avatar colors. Unknown CSS color formats
retain the picker's dark foreground fallback instead of guessing.

```ts
export function getResourcePickerForegroundColor(background: string): string;
```

---

### `ResourcePickerAvatar`

```ts
export function ResourcePickerAvatar<Id extends ResourcePickerId>({
  resource,
  className,
  color,
}: ResourcePickerAvatarProps<Id>);
```

---

### `ResourcePickerAvatarProps`

```ts
interface ResourcePickerAvatarProps {
  readonly resource: ResourcePickerItem<Id>;
  readonly className?: string;
  readonly color?: string
}
```

---

### `ResourcePickerOption`

```ts
export function ResourcePickerOption<
  Id extends ResourcePickerId,
  Resource extends ResourcePickerItem<Id>,
>({
  resource,
  selected,
  selectedResourceIds,
  disabled,
  multiple,
  resourceDataAttribute,
  classNames,
  isResourceDisabled,
  getAvatarColor,
  optionId,
  focused = false,
  onFocus,
  onChange,
}: ResourcePickerOptionProps<Id, Resource>);
```

---

### `ResourcePickerOptionProps`

```ts
interface ResourcePickerOptionProps {
  readonly resource: Resource;
  readonly selected: boolean;
  readonly selectedResourceIds: readonly Id[];
  readonly disabled: boolean;
  readonly multiple: boolean;
  readonly resourceDataAttribute?: string;
  readonly classNames?: ResourcePickerClassNames;
  readonly isResourceDisabled?: (resource: Resource) => boolean;
  readonly getAvatarColor?: (resource: Resource) => string | undefined;
  readonly optionId?: string;
  readonly focused?: boolean;
  readonly onFocus?: () => void;
  readonly onChange: (resourceIds: readonly Id[]) => void
}
```

---

### `ResourcePickerPopup`

Resource-picker-local portal.

Enterprise and Pro are shipped as separate bundles. Keeping the portal in
this bundle ensures its VNodes and hooks use the same Preact runtime as the
picker that owns them.

```ts
export function ResourcePickerPopup({
  triggerRef,
  portalTarget,
  popupId,
  children,
}: ResourcePickerPopupProps);
```

---

### `resourcePickerIdKey`

```ts
export function resourcePickerIdKey(id: ResourcePickerId): string;
```

---

### `uniqueResourcePickerIds`

```ts
export function uniqueResourcePickerIds<Id extends ResourcePickerId>(
  ids: readonly Id[],
): readonly Id[];
```

---

### `resourcePickerDataAttribute`

```ts
export function resourcePickerDataAttribute(
  attribute: string | undefined,
  value: string,
): Record<string, string>;
```

---

### `resourcePickerClasses`

```ts
export function resourcePickerClasses(
  ...values: readonly (string | undefined)[]
): string;
```

---

# Row Autosize

URL: https://pro.rv-grid.com/api/row-autosize/
Source: src/content/docs/api/row-autosize.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /**
       * Direct row auto-size configuration.
       */
      rowAutoSize?: RowAutoSizeConfig;
  /**
       * Template-friendly alias for `rowAutoSize`.
       */
      'row-auto-size'?: RowAutoSizeConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /**
       * Event triggered when the row auto size is updated
       *
       * @example
       * ```typescript
       * grid.addEventListener(ROW_AUTO_SIZE_CONFIG_UPDATE_EVENT, (e) => {
       *   console.log(e);
       * });
       */
      [ROW_AUTO_SIZE_CONFIG_UPDATE_EVENT]: RowAutoSizeConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data property for row auto size
       * @deprecated Use `grid.rowAutoSize` instead.
       */
      rowAutoSize?: RowAutoSizeConfig
}
```

## Plugin API

### `RowAutoSizePlugin`

The RowAutoSizePlugin enables dynamic row height calculation based on cell content.
It efficiently manages row heights by calculating them before rendering and updating
the grid's dimension store accordingly.

**Key Features**:
- Pre-calculates row heights based on cell content
- Supports dynamic content updates
- Efficient caching mechanism for calculated heights
- Configurable minimum and maximum row heights
- Support for both sync and async height calculations

Usage Example:
```typescript
import { RowAutoSizePlugin } from './row-autosize';

const grid = document.createElement('revo-grid');
grid.plugins = [RowAutoSizePlugin];

grid.rowAutoSize = {
  minHeight: 24,
  maxHeight: 200,
  // Optional: Custom height calculator
  calculateHeight: (rowData, columns) => {
    // Custom logic to calculate row height
    return 50;
  }
};
```

#### Dependencies

- **Config integration** `additionalData.rowAutoSize`: Reads legacy row auto-size configuration from additionalData.rowAutoSize.

```ts
class RowAutoSizePlugin {
  /** Recalculate specific virtual body-row indexes immediately. */
  async recalculateRows(rowIndexes: readonly number[]): Promise<void>;

  destroy(): void;
}
```

---

### `DEFAULT_MIN_HEIGHT`

Default lower bound for automatically calculated row heights.

Used when no `rowAutoSize.minHeight` is configured and as the fallback height
for approximate or unavailable measurements.

```ts
DEFAULT_MIN_HEIGHT: 24;
```

---

### `DEFAULT_MAX_HEIGHT`

Default upper bound for automatically calculated row heights.

Used when no `rowAutoSize.maxHeight` is configured.

```ts
DEFAULT_MAX_HEIGHT: 200;
```

---

### `CALCULATION_DEBOUNCE`

Debounce interval, in milliseconds, for viewport-triggered recalculations.

```ts
CALCULATION_DEBOUNCE: 10;
```

---

### `PRECALCULATE_ROWS_BATCH_SIZE`

Number of non-precise rows to pre-calculate per frame.

Approximate row sizing is CPU-only, so processing all rows at once can block
initial render or column resize on large datasets. Batching keeps the UI
responsive while still warming the cache ahead of scroll.

```ts
PRECALCULATE_ROWS_BATCH_SIZE: 500;
```

---

### `AUTO_SIZE_CLASS`

Host class applied to grids that have `RowAutoSizePlugin` installed.

The plugin stylesheet scopes row wrapping and measurement styles under this
class so the visual change is opt-in per grid instance.

```ts
AUTO_SIZE_CLASS: string;
```

---

### `CALCULATION_CLASS`

Class for the hidden DOM element used to measure precise wrapped content.

Static layout and wrapping styles for this element live in
`row-autosize.style.scss`; runtime code only sets dynamic width and copied
text metrics.

```ts
CALCULATION_CLASS: string;
```

---

### `MEASURED_CELL_STYLE_PROPS`

Computed style properties copied from a rendered cell to the hidden
measurement element before precise measurement.

Keep this list focused on properties that affect text flow, padding, and
measured content height. Structural measurement styles belong in SCSS.

```ts
MEASURED_CELL_STYLE_PROPS: readonly ["boxSizing", "font", "fontFamily", "fontSize", "fontStyle", "fontWeight", "letterSpacing", "lineHeight", "paddingTop", "paddingRight", "paddingBottom", "paddingLeft", "textIndent", "textTransform", "textWrap", "whiteSpace", "wordBreak", "overflowWrap"];
```

---

### `RowAutoSizeMeasurer`

Manages the hidden measurement element used by `RowAutoSizePlugin`.

The measurer owns DOM setup/teardown for precise row sizing. It does not
decide which rows or columns should be measured; callers provide row/column
coordinates and an effective column width. Static styles are supplied by
`row-autosize.style.scss`, while dynamic width and copied text metrics are
applied inline for each measurement.

```ts
class RowAutoSizeMeasurer {
  /**
     * Create or remove the hidden calculation element to match precise sizing.
     *
     * @param enabled - Whether precise DOM measurement should be available.
     */
  sync(enabled: boolean);

  /**
     * Measure an already-rendered grid cell by cloning its child nodes into the
     * hidden calculation element.
     *
     * This is the most accurate path because it inherits rendered cell content,
     * nested markup, and computed text metrics. Returns `null` when the target
     * cell is not currently rendered or the measurement element is not available.
     *
     * @param rowIndex - Source row index rendered in the viewport.
     * @param colIndex - Visual column index within the column type.
     * @param colType - RevoGrid column region.
     * @param columnWidth - Fallback width used when the rendered cell has no
     * measurable layout width.
     * @returns Measured content height in pixels, or `null` when the rendered cell
     * cannot be measured.
     */
  measureRenderedCellContentHeight({
    rowIndex,
    colIndex,
    colType,
    columnWidth,
  }: {
    rowIndex: number;
    colIndex: number;
    colType: DimensionCols;
    columnWidth: number;
  }): number | null;

  /**
     * Measure plain text using the hidden calculation element.
     *
     * This is the precise fallback used when a cell is not rendered but the plugin
     * still has content and column width available.
     *
     * @param content - Text content to measure.
     * @param columnWidth - Width in pixels to apply before measuring.
     * @returns Measured content height in pixels, or the default minimum height
     * when the calculation element is unavailable.
     */
  measureTextContentHeight(content: string, columnWidth: number): number;

  /**
     * Remove the hidden calculation element and release DOM references.
     */
  destroy();
}
```

---

### `RowAutoSizeCalculationState`

Tracks row height calculation cache, in-flight calculations, and invalidation
versions for `RowAutoSizePlugin`.

The version token protects against async races: callers capture the version
before starting a calculation and compare it again before writing the result.
Any row invalidation or full reset changes the token and makes stale
calculations harmless.

```ts
class RowAutoSizeCalculationState {
  /**
     * Get a cached calculated height for a source row.
     *
     * @param rowIndex - Source row index.
     * @returns Cached height, or `undefined` when the row needs calculation.
     */
  getCached(rowIndex: number): number | undefined;

  /**
     * Store the calculated height for a source row.
     *
     * @param rowIndex - Source row index.
     * @param height - Clamped row height in pixels.
     */
  setCached(rowIndex: number, height: number);

  /**
     * Check whether a row already has an active calculation.
     *
     * @param rowIndex - Source row index.
     * @returns `true` when calculation is in flight.
     */
  isPending(rowIndex: number): boolean;

  /**
     * Mark a source row as currently being calculated.
     *
     * @param rowIndex - Source row index.
     */
  markPending(rowIndex: number);

  /**
     * Clear the in-flight marker for a source row.
     *
     * @param rowIndex - Source row index.
     */
  clearPending(rowIndex: number);

  /**
     * Invalidate specific rows after content, width, or rendered DOM changes.
     *
     * Cached heights and pending markers are removed, and each row version is
     * incremented so older async calculations cannot write stale heights.
     *
     * @param rowIndexes - Source row indexes to invalidate.
     */
  invalidateRows(rowIndexes: number[]);

  /**
     * Clear all row state and advance the global calculation epoch.
     *
     * Use when source data, config, or column sizing changes invalidate every
     * cached height.
     */
  reset();

  /**
     * Clear all row state without advancing the epoch.
     *
     * Intended for plugin teardown when no future calculation result should be
     * observed.
     */
  clear();

  /**
     * Return a stable version token for the current row calculation state.
     *
     * Callers should capture this value before starting async work and compare it
     * with a fresh value before committing the result.
     *
     * @param rowIndex - Source row index.
     * @returns Token containing the global epoch and row-specific version.
     */
  getVersion(rowIndex: number): string;
}
```

---

### `RowAutoSizeConfig`

```ts
export type RowAutoSizeConfig = {
  /**
   * Minimum row height in pixels
   * @default 24
   */
  minHeight?: number;

  /**
   * Maximum row height in pixels
   * @default 200
   */
  maxHeight?: number;

  /**
   * Custom height calculator function
   * If provided, will be used instead of the default calculator
   */
  calculateHeight?: (
    rowData: DataType,
    columns: ColumnRegular[],
  ) => number | Promise<number>;

  /**
   * Whether to warm row height cache for all rows in non-precise mode.
   *
   * Enabled by default and processed in chunks to avoid blocking large grids.
   * Disable to calculate only visible rows and preserve the older demand-driven
   * behavior.
   *
   * @default true
   */
  precalculate?: boolean;

  /**
   * Number of non-precise rows to pre-calculate per animation frame.
   *
   * Larger values warm the cache faster but can make each frame heavier. Values
   * lower than 1 fall back to the default batch size.
   *
   * @default 500
   */
  precalculateBatchSize?: number;
};
```

---

### `clampRowHeight`

Clamp a measured or custom row height to the active row auto-size bounds.

**@param** height - Raw height calculated by the plugin or supplied by
`rowAutoSize.calculateHeight`.

**@param** config - Active row auto-size configuration.

**@returns** Height constrained by configured or default min/max limits.

```ts
export function clampRowHeight(height: number, config: RowAutoSizeConfig): number;
```

---

### `calculateApproximateContentHeight`

Estimate wrapped text height without reading rendered cell DOM.

This path is used when precise measurement is disabled or unavailable. It is
intentionally simple and deterministic: text is split by line breaks, each
line is wrapped using an approximate character width, and the result is
converted to pixels with a fixed approximate line height.

**@param** content - Cell text content.

**@param** columnWidth - Effective column width in pixels.

**@returns** Estimated content height in pixels, never lower than the default
minimum row height.

```ts
export function calculateApproximateContentHeight(content: string, columnWidth: number): number;
```

---

### `getEditedRowIndexes`

Resolve affected source row indexes from RevoGrid edit events.

Supports both single-cell edits and range edits so callers can invalidate and
recalculate only rows whose content changed.

**@param** event - `afteredit` detail for a single edit or range edit.

**@returns** Source row indexes that need recalculation.

```ts
export function getEditedRowIndexes(
  event: BeforeSaveDataDetails | BeforeRangeSaveDataDetails,
): number[];
```

---

# Row Expand

URL: https://pro.rv-grid.com/api/row-expand/
Source: src/content/docs/api/row-expand.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Enables expand template on cells
       */
      expand?: boolean
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  rowExpand?: RowExpandConfig;
  'row-expand'?: RowExpandConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data for row expand
       * @deprecated Use `grid.rowExpand` instead.
       *
       * @example
       * ```typescript
       * const grid = document.createElement('revo-grid');
       * grid.additionalData = {
       *   rowExpand: {
       *     expandedRows: new Set([1, 2, 3]),
       *   },
       * };
       * ```
       */
      rowExpand?: RowExpandConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [ROW_EXPAND]: { rowIndex: number };
  [ROW_COLLAPSE]: { rowIndex: number };
  [ROW_EXPAND_ALL]?: undefined;
  [ROW_COLLAPSE_ALL]?: undefined
}
```

## Plugin API

### `RowExpandPlugin`

The `RowExpandPlugin` is a lightweight row-detail plugin for RevoGrid.
It expands a regular row by inserting a second virtual row that points to the same physical row
and renders custom content from `rowExpand.template`. Use it when the detail content can live
as an inline row inside the regular grid flow, such as a nested grid, row form, compact detail
panel, or any row-local custom content.

**Key Features**:
- Expand/collapse individual rows
- Expand all rows at once
- Support for default expanded rows through config
- Events for row expansion state changes
- Extensible design for inline row-detail content

#### RowExpandPlugin vs MasterRowPlugin

Both plugins support expandable row details, but they solve different layout problems:

- `RowExpandPlugin` renders an inline expanded row in the normal row viewport. It is the simpler
  option when the expanded content should stay inside the regular grid columns and scroll with the rows.
- `MasterRowPlugin` renders master-detail content through its auto-installed `OverlayPlugin`, tracks
  viewport scrolling, and can span the detail area across the grid, including pinned areas. Use it for
  full-width, overlay-based master-detail layouts that need richer alignment behavior.

For master-detail rows, see the [Master Rows guide](/guides/data-manage/row-master/) and
[Row Master API](/api/row-master/).

Usage Example:
```ts
import { RowExpandPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [RowExpandPlugin];
grid.columns = [
  { prop: 'name', name: 'Name', expand: true },
  { prop: 'status', name: 'Status' },
];

grid.rowExpand = {
  // Physical row indexes to expand by default
  expandedRows: new Set([1, 2, 3]),
  // Height for expanded rows (optional)
  expandedRowHeight: 200,
  // Template for expanded content
  template: (h, props) => h('div', null, `Details for ${props.model.name}`)
};
```

#### Dependencies

- **Event integration** `EVENT_BEFORE_SORTING`, `EVENT_AFTER_SORTING`, `BEFORE_FILTER_EVENT`, `AFTER_FILTER_EVENT`, `AFTER_SOURCE_SET_EVENT`: Integrates with grid lifecycle events to preserve expanded row state.
- **Config integration** `additionalData.rowExpand`: Reads legacy row expansion configuration from additionalData.rowExpand.

```ts
class RowExpandPlugin {
  /**
     * Expand a specific row
     */
  public expandRow(rowIndex: number);

  /**
     * Collapse a specific row
     */
  public collapseRow(rowIndex: number);

  /**
     * Expand all rows
     */
  public expandAllRows();

  /**
     * Collapse all rows
     */
  public collapseAllRows();
}
```

---

### `ExpandCellTemplate`

Template function for rendering expand toggle in cells

```ts
ExpandCellTemplate: (toggleRowExpanded: (rowIndex: number) => void, isExpanded: (rowIndex: number) => boolean, config: RowExpandConfig | undefined, getRowModel: (rowIndex: number) => any) => CellTemplate<DataType<any, ColumnProp>>;
```

---

### `RowExpandConfig`

Configuration for row expansion

```ts
interface RowExpandConfig {
  /**
     * Set of row IDs that should be expanded by default
     */
    expandedRows?: Set<number>;
  /**
     * Height for expanded rows (optional)
     */
    expandedRowHeight?: number;
  /**
     * Controls visibility of expand toggle button on rows
     * - If boolean: hides expand toggle for all rows when true
     * - If function: allows conditional hiding based on row data
     * @param rowIndex The index of the row
     * @param model The row data model
     * @returns true to hide expand toggle, false to show it
     */
    hideExpand?: boolean | ((rowIndex: number, model: any) => boolean);
  /**
     * Template function for rendering expanded row content
     */
    template?: (h: any, props: any) => VNode
}
```

---

### `ExpansionConfig` (Extended from `row-expand.types.ts`)

Configuration for expansion operation

```ts
interface ExpansionConfig {
  /**
     * Type of expansion operation to perform
     */
    operation: 'expand' | 'collapse' | 'toggle';
  target: ExpansionTarget;
  skipStateCheck?: boolean
}
```

---

# Row Header

URL: https://pro.rv-grid.com/api/row-header/
Source: src/content/docs/api/row-header.md

## Module Extensions

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /** Requests a whole-grid cell selection across every row/column viewport. */
      [SELECT_ALL_CELLS_EVENT]: undefined
}
```

## Plugin API

### `RowHeaderPlugin`

The `RowHeaderPlugin` is a RevoGrid plugin that enhances the grid with interactive row headers,
allowing users to focus, select, and manage row-specific actions effectively. This plugin integrates
various event handlers to facilitate rich interactions and maintain state consistency across the grid.

**Key Features**:
- **Header Interaction**: Listens for events such as `EVENT_ROW_FOCUS`, `EVENT_ROW_FOCUS_SIMPLE`, and
  `ROW_MENU_EVENT` to handle row selection and focus, enabling users to click on row headers to trigger
  specific actions or selections.
- **Selection Management**: Owns row-header selection independently from checkbox selection and
  projects selected rows as full-width multi-ranges for clipboard and range-edit operations.
- **Event Handling**: Integrates with a variety of grid events (`EVENT_BEFORE_CELL_FOCUS`, `EVENT_BEFORE_FOCUS_LOST`,
  `DRAG_START_EVENT`) to modify selection states, drop focus, and handle custom row click actions.
- **Range and Focus Handling**: Provides utility methods to apply focus and selection ranges within rows,
  ensuring that selections are visually and functionally consistent across the grid.

**Usage**:
- Integrate this plugin into a RevoGrid instance to enable row header functionalities. Add the plugin
  to the grid's plugins array to activate its features.

### Example
```typescript
import { RowHeaderPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [RowHeaderPlugin];
```

This plugin is ideal for applications that require advanced row header interactions, offering
a robust solution for managing row-based data actions within a RevoGrid component.

#### Dependencies

- **Event integration** `RowOrderPlugin`: Integrates with RowOrderPlugin when row headers are configured with row drag support.
- **Auto-installed** `MultiRangeSelectionPlugin`: Uses MultiRangeSelectionPlugin for full-width row ranges, multi-range operations, and clipboard behavior.

```ts
class RowHeaderPlugin {
  /** Clears interactive row-header state before whole-column selection takes over. */
  clearFromColumnHeader();

  /** Clears private row-header state before select-all takes ownership. */
  clearFromSelectAll();

  /** Lets rendering integrations query row-header-owned selection only. */
  isRowHeaderSelected(type: DimensionRows, visibleRowIndex: number);

  /** Returns row-header-owned physical indexes without exposing mutable state. */
  getSelectedPhysicalIndexes(type: DimensionRows): ReadonlySet<number>;

  getRowOrderSelection(
    context: RowOrderSelectionContext,
  ): RowOrderSelection | null;

  destroy();
}
```

---

### `RowHeadersOptions`

```ts
export type RowHeadersOptions = {
  showHeaderFocusBtn?: boolean;
  /** Shows an accessible spreadsheet-style Select All control in the corner header. */
  showSelectAllButton?: boolean;
  rowDrag?: RowDrag;
};
```

---

### `rowHeaders`

Returns the row header column configuration.

```ts
rowHeaders: ({ showHeaderFocusBtn, showSelectAllButton, rowDrag, }?: RowHeadersOptions) => ColumnRegular<ColumnProp, DataType<any, ColumnProp>>;
```

---

### `selectAllCellsTemplate`

Renders the optional row-header corner action without coupling it to demo markup.

```ts
selectAllCellsTemplate: (h: HyperFunc<VNode>) => VNode;
```

---

### `rowHeaderTemplate`

```ts
rowHeaderTemplate: (h: HyperFunc<VNode>, params: CellTemplateProp<DataType<any, ColumnProp>, ColumnRegular<ColumnProp, DataType<any, ColumnProp>>, ColumnProp>, showHeaderFocusBtn: boolean, rowDrag: RowDrag) => VNode[];
```

---

### `RowFocusDetails`

```ts
export type RowFocusDetails = {
  dataItem: CellTemplateProp;
  models: any[];
};
```

---

### `RowHeaderFocusEvent` (Extended from `index.ts`)

```ts
export type RowHeaderFocusEvent = CellTemplateProp & {
  originalEvent?: MouseEvent | KeyboardEvent;
};
```

---

### `RowHeaderSelectionProvider`

Read-only query surface for row-header-owned physical selection.

```ts
interface RowHeaderSelectionProvider {
  getSelectedPhysicalIndexes(type: DimensionRows): ReadonlySet<number>
}
```

---

### `DragStartEventDetails`

```ts
export type DragStartEventDetails = {
  event: MouseEvent;
  data: DragEventsData;
};
```

---

### `ROW_HEADER_SELECTED_ATTR`

```ts
ROW_HEADER_SELECTED_ATTR: string;
```

---

### `RowHeaderSelection`

Owns selection state created exclusively through the interactive row header.
Checkbox and programmatic row selection remain private to RowSelectPlugin.

```ts
class RowHeaderSelection {
  select(
    params: CellTemplateProp,
    originalEvent: MouseEvent | KeyboardEvent,
  ): boolean;

  selectVisibleRow(
    type: DimensionRows,
    visibleRowIndex: number,
    originalEvent: MouseEvent | KeyboardEvent,
  ): boolean;

  isSelected(type: DimensionRows, visibleRowIndex: number): boolean;

  getSelectedVisibleIndexes(type: DimensionRows): number[];

  /** Returns a snapshot so consumers cannot mutate row-header-owned state. */
  getSelectedPhysicalIndexes(type: DimensionRows): ReadonlySet<number>;

  clear(): void;

  reconcile(type: DimensionRows): void;

  getRowOrderSelection(
    context: RowOrderSelectionContext,
  ): RowOrderSelection | null;
}
```

---

# Row Master

URL: https://pro.rv-grid.com/api/row-master/
Source: src/content/docs/api/row-master.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  masterRow?: RowMasterConfig;
  'master-row'?: RowMasterConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /**
       * Toggles one master detail row from a cell payload, or applies desired states for multiple rows.
       */
      [ROW_MASTER]: RowMasterEvent;
  /**
       * Fired before automatic master-row cleanup collapses expanded rows. Call preventDefault() to keep rows expanded.
       */
      [BEFORE_ROW_MASTER_COLLAPSE]: RowMasterBeforeCollapseEvent
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
      * Additional data property for row master configuration
      * @example
      * {
      *   masterRow: {
      *     prop: 'masterDetail',
      *     name: 'Details',
      *     cellTemplate: (h, data) => {
      *       // Custom rendering logic for master rows
      *       return h('div', { class: 'detail-content' }, 'Detail view content');
      *     },
      *   },
      * }
      * @deprecated Use the direct `grid.masterRow` property instead.
      */
      masterRow?: RowMasterConfig
}
```

## Plugin API

### `EXPAND_COLUMN`

```ts
EXPAND_COLUMN: {
  size: number;
  readonly: true;
  cellProperties: () => { class: string; };
  cellTemplate: (h: HyperFunc<VNode>, data: CellTemplateProp<DataType<any, ColumnProp>, ColumnRegular<ColumnProp, DataType<any, ColumnProp>>, ColumnProp>) => VNode;
};
```

---

### `MasterRowPlugin`

The `MasterRowPlugin` is a RevoGrid plugin designed to manage and render master-detail rows within the grid.
It provides functionalities to expand and collapse rows, offering a detailed view for selected rows, enhancing
data presentation and interaction in scenarios where hierarchical data representation is required.

**Key Features**:
- **Row Expansion/Collapse**: Allows users to expand or collapse master rows to reveal or hide additional
  details, facilitating a hierarchical view of the data.
- **Event-Driven Interactions**: Subscribes to and dispatches a range of events, including `ROW_MASTER`,
  `AFTER_GRID_RENDER_EVENT`, `BEFORE_ROW_RENDER_EVENT`, and more, to maintain and update row states and visuals.
- **Customizable Templates**: Supports configurable templates for rendering detailed row content using
  the `RowMasterConfig`, providing flexibility in how detail views are presented.
- **Efficient DOM Management**: Handles overlay nodes for expanded rows, ensuring that DOM manipulation
  is optimized for performance.
- **Viewport Synchronization**: Continuously verifies and updates the expansion state of rows in response
  to viewport changes, ensuring consistency with user interactions and data state.

**Usage**:
- Integrate this plugin into a RevoGrid instance to enable master-detail row functionalities. Add the plugin
  to the grid's plugins array to activate its features.

### Example
```typescript
import { MasterRowPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [MasterRowPlugin];
```

This plugin is ideal for applications that require complex data presentation with nested details, providing
a robust solution for managing detailed data views efficiently within a grid structure.

#### MasterRowPlugin vs RowExpandPlugin

Use `MasterRowPlugin` when detail content needs a master-detail overlay that stays aligned with the viewport
and can span across the grid, including pinned areas. It auto-installs `OverlayPlugin` for that overlay rendering.

Use `RowExpandPlugin` when you only need inline row details in the normal row flow. `RowExpandPlugin`
duplicates the row's physical index in the row item list and renders the expanded content as a regular
virtual row, which is lighter and better suited for nested grids, row forms, and compact detail panels.

For inline row expansion, see the [Row Expand guide](/guides/data-manage/row-expand/) and
[Row Expand API](/api/row-expand/).

#### Dependencies

- **Auto-installed** `OverlayPlugin`: Auto-installs or reuses OverlayPlugin to render master-detail overlay content.
- **Auto-installed** `RowMasterAccessibilityPlugin`: Auto-installs or reuses RowMasterAccessibilityPlugin to isolate nested grid keyboard and focus behavior.
- **Event integration** `RowHeaderPlugin`: Integrates with RowHeaderPlugin row focus events when present.

```ts
class MasterRowPlugin {
  isMasterRowExpanded(
    itemVIndexes: number[],
    rowType: DimensionRows,
    virtualRowIndex: number,
  );

  isExpandedRow(
    itemVIndexes: number[],
    rowType: DimensionRows,
    virtualRowIndex: number,
  );

  /**
     * This method checks if a row is expanded by verifying two conditions:
     * 1. The row's ID (nodeId) is present in the expandedMasters collection.
     * 2. The physical row index (physRowIndex) is the same as the neighoring physical row index (sibPhysRowIndex).
     */
  getExpandedId(
    rowType: DimensionRows,
    physRowIndex: number,
    sibPhysRowIndex: number,
  );

  clearDimensions(type: DimensionRows, rowVIndexes: number[]);

  collapseRow(type: DimensionRows, rowVIndexes: number[]);

  expandRow(type: DimensionRows, virtRowIndex: number);

  destroy();
}
```

---

### `RowMasterConfig`

```ts
export type RowMasterConfig = {
  prop?: ColumnProp;
  rowHeight?: number;
  template?: (h: any, data: BeforeRowRenderEvent, additionalData?: any) => ReturnType<typeof RenderFunc>;
  /**
   * Restores expanded detail rows after replacing a source when the same row objects are present.
   * Rows are matched by object identity, so recreated records are treated as new rows.
   */
  preserveExpandedOnSourceChange?: boolean;
  /**
   * Event names from master-detail content that are allowed to bubble to the parent grid.
   * By default all RevoGrid events emitted inside the detail area are stopped.
   */
  allowDetailEvents?: readonly string[];
};
```

---

### `RowMasterBatchTarget`

```ts
export type RowMasterBatchTarget = {
  /**
   * Row collection where the target row lives.
   */
  rowType: DimensionRows;
  /**
   * Current virtual row index. It is normalized before the batch mutates row data.
   */
  rowIndex: number;
  /**
   * Desired master-row state for this row.
   */
  expanded: boolean;
};
```

---

### `RowMasterBatchEvent`

```ts
export type RowMasterBatchEvent = {
  rows: RowMasterBatchTarget[];
};
```

---

### `RowMasterEvent`

```ts
export type RowMasterEvent = CellTemplateProp | RowMasterBatchEvent;
```

---

### `RowMasterCollapseReason`

```ts
export type RowMasterCollapseReason = 'source' | 'filter' | 'drag';
```

---

### `RowMasterCollapseRow`

```ts
export type RowMasterCollapseRow = {
  nodeId: string;
  rowType: DimensionRows;
  physIndex: number;
  rowIndex: number;
};
```

---

### `RowMasterBeforeCollapseEvent`

```ts
export type RowMasterBeforeCollapseEvent = {
  reason: RowMasterCollapseReason;
  rows: RowMasterCollapseRow[];
};
```

---

### `ROW_MASTER_DETAIL_NODE_ATTR`

```ts
ROW_MASTER_DETAIL_NODE_ATTR: string;
```

---

### `RowMasterAccessibilityPlugin`

```ts
class RowMasterAccessibilityPlugin {
  handleDetailEvent(event: Event);
}
```

---

### `isRowMasterBatchEvent`

```ts
export function isRowMasterBatchEvent(detail: RowMasterEvent): detail is RowMasterBatchEvent;
```

---

### `getRowMasterNodeId`

```ts
export function getRowMasterNodeId(type: DimensionRows, physIndex: number);
```

---

### `normalizeRowMasterTargets`

```ts
export function normalizeRowMasterTargets(
  targets: RowMasterBatchTarget[],
  getItems: (rowType: DimensionRows) => number[],
): NormalizedRowMasterTarget[];
```

---

### `groupRowMasterTargets`

```ts
export function groupRowMasterTargets(
  targets: NormalizedRowMasterTarget[],
): Map<DimensionRows, Map<number, boolean>>;
```

---

### `getExpandedPhysIndexes`

```ts
export function getExpandedPhysIndexes(expandedMasters: Set<string>, type: DimensionRows);
```

---

### `removeDetailDuplicates`

```ts
export function removeDetailDuplicates(items: number[], physIndexes: Set<number>);
```

---

### `reconcileRowMasterBatch`

```ts
export function reconcileRowMasterBatch({
  type,
  targetStates,
  items,
  proxyItems,
  expandedMasters,
  sizes,
  rowHeight,
}: RowMasterBatchReconcileInput): RowMasterBatchReconcileResult;
```

---

### `applyRowMasterBatch`

```ts
export function applyRowMasterBatch({
  detail,
  providers,
  expandedMasters,
  rowHeight,
}: ApplyRowMasterBatchInput): ApplyRowMasterBatchResult;
```

---

### `NormalizedRowMasterTarget`

```ts
export type NormalizedRowMasterTarget = {
  rowType: DimensionRows;
  physIndex: number;
  expanded: boolean;
};
```

---

### `RowMasterBatchReconcileInput`

```ts
export type RowMasterBatchReconcileInput = {
  type: DimensionRows;
  targetStates: Map<number, boolean>;
  items: number[];
  proxyItems: number[];
  expandedMasters: Set<string>;
  sizes?: ViewSettingSizeProp;
  rowHeight?: number;
};
```

---

### `RowMasterBatchReconcileResult`

```ts
export type RowMasterBatchReconcileResult = {
  items: number[];
  proxyItems: number[];
  expandedMasters: Set<string>;
  clearNodeIds: string[];
  sizes?: ViewSettingSizeProp;
};
```

---

### `ApplyRowMasterBatchInput`

```ts
export type ApplyRowMasterBatchInput = {
  detail: RowMasterBatchEvent;
  providers: PluginProviders;
  expandedMasters: Set<string>;
  rowHeight?: number;
};
```

---

### `ApplyRowMasterBatchResult`

```ts
export type ApplyRowMasterBatchResult = {
  expandedMasters: Set<string>;
  clearNodeIds: string[];
  applied: boolean;
};
```

---

### `RowMasterDetailRenderer`

```ts
class RowMasterDetailRenderer {
  beforeRowRender(detail: BeforeRowRenderDetail, handlers: EventHandlers, getScrollableViewportEl: () => HTMLElement | null);
}
```

---

### `isKeyboardEventFromNestedGrid`

```ts
export function isKeyboardEventFromNestedGrid(
  event: KeyboardEvent,
  parentGrid: HTMLRevoGridElement,
): boolean;
```

---

### `isEventFromNestedGrid`

```ts
export function isEventFromNestedGrid(
  event: Event,
  parentGrid: HTMLRevoGridElement,
): boolean;
```

---

### `RowMasterProjectionController`

Owns the duplicated virtual detail row and its dimension bookkeeping.

```ts
class RowMasterProjectionController {
  getExpandedId(type: DimensionRows, physIndex: number, siblingPhysIndex: number): string | null;

  isMasterRowExpanded(items: number[], type: DimensionRows, index: number);

  isExpandedRow(items: number[], type: DimensionRows, index: number);

  applyBatch(detail: RowMasterBatchEvent): boolean;

  expand(type: DimensionRows, virtualIndex: number);

  collapse(type: DimensionRows, virtualIndexes: number[]);

  clearDimensions(type: DimensionRows, rowIndexes: number[]);

  restoreExpandedRowHeights();
}
```

---

### `getRowMasterTreeConfig`

```ts
export function getRowMasterTreeConfig(revogrid: HTMLRevoGridElement): RowMasterTreeConfig | undefined;
```

---

### `getRowMasterTreeIdField`

```ts
export function getRowMasterTreeIdField(
  revogrid: HTMLRevoGridElement,
  providers: PluginProviders,
): string | undefined;
```

---

### `isRowMasterTreeParent`

```ts
export function isRowMasterTreeParent(
  row: DataType | undefined,
  source: DataType[],
  config: RowMasterTreeConfig | undefined,
): boolean;
```

---

### `isRowMasterVisibleInTree`

```ts
export function isRowMasterVisibleInTree(
  source: DataType[],
  physIndex: number,
  expandedRowIds: Set<unknown>,
  config: RowMasterTreeConfig | undefined,
): boolean;
```

---

### `RowMasterTreeConfig`

```ts
export type RowMasterTreeConfig = {
  animation?: boolean;
  idField?: string;
  parentIdField?: string;
  rootParentId?: unknown;
};
```

---

# Row Next Focus

URL: https://pro.rv-grid.com/api/row-next-focus/
Source: src/content/docs/api/row-next-focus.md

### `RowKeyboardNextLineFocusPlugin`

The `RowKeyboardNextLineFocusPlugin` enhances keyboard navigation within the RevoGrid by automatically
shifting focus to the next or previous row when the user tabs past the last or first cell of a row.
This functionality is crucial for improving user experience during data entry or navigation.

 **Features**:
- Listens to the `BEFORE_KEYDOWN_EVENT` to intercept keyboard events, specifically the 'Tab' key.
- Automatically moves focus to the first cell of the next row when tabbing past the last cell.
- Moves focus to the first cell of the previous row when shift-tabbing from the first cell.
- Ensures that focus navigation respects the grid boundaries and does not move beyond available rows.

**Usage**:
- This plugin should be added to the RevoGrid to enable enhanced keyboard navigation.
- It can be instantiated with a reference to the RevoGrid element and associated plugin providers.

### Example
```typescript
import { RowKeyboardNextLineFocusPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [RowKeyboardNextLineFocusPlugin]; // Add keyboard navigation plugin
```

Events:
- Intercepts keydown events to manage focus transitions and prevent default browser behavior where necessary.

This plugin is ideal for users who rely heavily on keyboard navigation, ensuring efficient and seamless data entry across grid rows.

```ts
class RowKeyboardNextLineFocusPlugin {}
```

---

# Row Odd

URL: https://pro.rv-grid.com/api/row-odd/
Source: src/content/docs/api/row-odd.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  /**
       * Direct row striping configuration.
       */
      rowOdd?: RowOddInput
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Row striping configuration.
       * @deprecated Use `grid.rowOdd` instead.
       */
      rowOdd?: RowOddInput
}
```

## Plugin API

### `RowOddPlugin`

The `RowOddPlugin` is a RevoGrid plugin designed to enhance the visual styling of grid rows by
applying configurable row striping attributes during row rendering.

Functionality:
- **Backward-compatible odd rows**: The default behavior still marks rows `1, 3, 5...` with `[odd]`.
- **Configurable striping**: Supports direct `grid.rowOdd` and legacy `additionalData.rowOdd` config.
- **Stable CSS hooks**: Adds `odd`, `even`, `row-stripe`, `data-row-stripe-index`, and
  `data-row-source-index` attributes to striped rows.

**Usage**:
- Add `RowOddPlugin` to the grid plugins array.
- Optionally set `grid.rowOdd = { mode: 'custom', interval: 3, offset: 0 }`.

### Example
```typescript
import { RowOddPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [RowOddPlugin];
```

This plugin is useful for alternating row styles, grouped visual rhythm, and domain-specific
row highlighting without changing source data.

#### Dependencies

- **Config integration** `additionalData.rowOdd`: Reads legacy row striping configuration from additionalData.rowOdd.

```ts
class RowOddPlugin {}
```

---

### `RowOddMode`

```ts
export type RowOddMode = 'odd' | 'even' | 'custom';
```

---

### `RowOddContext`

```ts
interface RowOddContext {
  model: T;
  visualIndex: number;
  sourceIndex: number;
  stripeIndex: number;
  mode: RowOddMode
}
```

---

### `RowOddConfig`

```ts
interface RowOddConfig {
  /**
     * Enables or disables row striping.
     * @default true
     */
    enabled?: boolean;
  /**
     * Built-in striping mode. Use `custom` with `interval` and `offset`.
     * @default 'odd'
     */
    mode?: RowOddMode;
  /**
     * Stripe every N rows when `mode` is `custom`.
     * @default 2
     */
    interval?: number;
  /**
     * First matching modulo offset when `mode` is `custom`.
     * @default 1
     */
    offset?: number;
  /**
     * Optional class name appended to striped row VNodes.
     */
    className?: string;
  /**
     * Declarative row matcher. All provided fields must equal the row model value.
     */
    match?: Partial<T>;
  /**
     * Optional row predicate. Returning `true` stripes the row, returning `false`
     * keeps it unstriped.
     */
    shouldStripe?: (context: RowOddContext<T>) => boolean
}
```

---

### `RowOddInput`

```ts
export type RowOddInput<T extends DataType = DataType> = boolean | RowOddConfig<T>;
```

---

# Row Order

URL: https://pro.rv-grid.com/api/row-order/
Source: src/content/docs/api/row-order.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `@revolist/revogrid`)

```ts
interface HTMLRevoGridElement {
  /**
       * Direct row-order configuration.
       * Set to `false` to disable RowOrderPlugin without removing the plugin.
       */
      rowOrder?: RowOrderPluginConfig | false
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data property rowOrder
       * @deprecated Use `grid.rowOrder` instead.
       *
       * @example
       * ```typescript
       * const grid = document.createElement('revo-grid');
       * grid.plugins = [RowOrderPlugin];
       * grid.additionalData = {
       *   rowOrder: {
       *     prop: 'name', // column prop, used for drag and drop text information
       *   },
       * };
       * ```
       */
      rowOrder?: RowOrderPluginConfig | false
}
```

---

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Column prop, used for drag and drop text information
       */
      rowDrag?: RowDrag<TModel>
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [ORDER_CHANGED_EVENT]: RowOrderChange;
  [ROW_ORDER_APPLIED_EVENT]: RowOrderAppliedEvent;
  [DRAG_START_EVENT]: RowDragStartEvent;
  [BEFORE_ROW_DROP_VALIDATE_EVENT]: RowOrderDropValidationEvent;
  [ROW_DROP_STATE_CHANGE_EVENT]: RowOrderDropStateChange
}
```

## Plugin API

### `RowOrderPlugin`

The `RowOrderPlugin` is a sophisticated plugin for the RevoGrid framework, providing users with the ability
to reorder rows through an intuitive drag-and-drop interface. This plugin enhances user interactivity
by allowing smooth row rearrangement while maintaining data integrity and grid performance.

**Key Features**:
- **Row Drag and Drop**: Users can drag one or multiple rows and reposition them within the grid.
- **Auto-scroll Support**: Automatically scrolls the grid, viewport, or container when rows are dragged
  near the edges, ensuring a seamless drag-and-drop experience.
- **Row Highlighting**: Highlights rows that are being dragged or trimmed, providing visual feedback.
- **Multiple Row Handling**: Supports dragging and selecting multiple rows, enhancing batch operations.
- **Event Integration**: Listens to and dispatches various drag-related events, such as `DRAG_START_EVENT`,
  `DRAG_END_EVENT`, `ORDER_CHANGED_EVENT`, and more, allowing for extensive customization and integration
  with other components.
- **Trimmed Row Management**: Manages trimmed rows by automatically clearing and updating them as necessary
  during drag operations.

**Usage**:
- Integrate `RowOrderPlugin` into a RevoGrid instance to enable advanced row reordering capabilities.
- Customize behavior and appearance through configuration options and event listeners.

### Example
```typescript
import { RowOrderPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [RowOrderPlugin];
```

This plugin is ideal for applications requiring dynamic, user-driven row management, such as task
prioritization tools, data manipulation applications, or any scenario where row order is significant.

```ts
class RowOrderPlugin {
  /**
     * Drop trigger event
     */
  onMouseOut(_: MouseEvent): void;

  /**
     * Final event
     */
  onMouseUp(e: MouseEvent): void;

  /**
     * Initial event when drag begins
     */
  dragStart({ originalEvent: e, model: dataItem }: RowDragStartEvent);

  /**
     * Initial row move
     */
  move(e: MouseEvent);

  clearOrder(): void;

  /**
     * Start grid reordering
     */
  orderStart(e: MouseEvent): void;

  applyHistoryChange(
    change: RowOrderHistoryChange,
    direction: 'undo' | 'redo',
  ): boolean;

  /**
     * Clearing local subscription
     */
  clearSubscriptions();

  clearHighlight();
}
```

---

### `RowOrderChangedDetail`

```ts
export type RowOrderChangedDetail = {
  from: number;
  targetRow?: number;
  to: number;
  type: DimensionRows;
};
```

---

### `RowDragStartEvent` (Extended from `index.ts`)

```ts
interface RowDragStartEvent {
  model: CellTemplateProp
}
```

---

### `RowOrderSelection`

```ts
interface RowOrderSelection {
  items: Map<number, DataType>;
  rowIndexes: number[]
}
```

---

### `RowOrderSelectionContext`

```ts
interface RowOrderSelectionContext {
  type: DimensionRows;
  draggedVisibleRowIndex: number;
  selectionOrigin: 'row-header' | 'body';
  /** Present only for the initial pointer press that starts row ordering. */
    originalEvent?: MouseEvent
}
```

---

### `RowOrderSelectionProvider`

Origin-scoped row selection supplied to RowOrderPlugin by other plugins.

```ts
interface RowOrderSelectionProvider {
  getRowOrderSelection(
      context: RowOrderSelectionContext,
    ): RowOrderSelection | null
}
```

---

### `RowOrderDropValidationResult`

```ts
export type RowOrderDropValidationResult =
  | { valid: true; warning?: string }
  | { valid: false; reason?: string };
```

---

### `RowOrderPreviewContext`

```ts
export type RowOrderPreviewContext = {
  dataItem: CellTemplateProp;
  firstItem?: DataType;
  itemCount: number;
  items: DataType[];
  prop?: ColumnProp;
  type: DimensionRows;
};
```

---

### `RowOrderPreviewContent`

```ts
export type RowOrderPreviewContent = string | number | HTMLElement | undefined;
```

---

### `RowOrderPreviewRenderer`

```ts
export type RowOrderPreviewRenderer = (
  context: RowOrderPreviewContext,
) => RowOrderPreviewContent;
```

---

### `RowOrderDropValidationContext`

```ts
export type RowOrderDropValidationContext = {
  dataItem: CellTemplateProp;
  dropPosition: RowOrderDropPosition;
  from: number;
  items: Map<number, DataType>;
  originalEvent: MouseEvent;
  targetIndex: number;
  targetRow: number;
  to: number;
  type: DimensionRows;
  /**
   * Visible row indexes that are part of the active drag selection.
   */
  visibleRowIndexes?: number[];
};
```

---

### `RowOrderDropValidationEvent` (Extended from `index.ts`)

```ts
export type RowOrderDropValidationEvent = RowOrderDropValidationContext & {
  result: RowOrderDropValidationResult;
};
```

---

### `RowOrderDropStateChange` (Extended from `index.ts`)

```ts
export type RowOrderDropStateChange = RowOrderDropValidationContext & {
  previous?: RowOrderDropValidationResult;
  result: RowOrderDropValidationResult;
};
```

---

### `RowOrderDropPosition`

```ts
export type RowOrderDropPosition = 'before' | 'inside' | 'after';
```

---

### `RowOrderPluginConfig`

```ts
interface RowOrderPluginConfig {
  prop?: ColumnProp;
  // column prop, used for drag and drop text information
    preview?: 'compact' | 'none' | RowOrderPreviewRenderer;
  previewProp?: ColumnProp | RowOrderPreviewRenderer;
  validateDrop?: (
      context: RowOrderDropValidationContext,
    ) => RowOrderDropValidationResult | boolean | void;
  allowPinnedRows?: boolean;
  allowCrossRowType?: boolean;
  /**
     * Flashes moved rows after a successful reorder when `CellFlashPlugin` is
     * installed. Enabled by default. Set to `false` to keep `CellFlashPlugin`
     * active for other grid changes without flashing row-order drops.
     */
    flashOnDrop?: boolean;
  /**
     * When grouped rows are reordered into another group, apply the target group
     * values to the moved rows and emit regular beforeedit/afteredit events.
     * Disabled by default, so grouped rows can only be reordered inside the same
     * group path.
     */
    applyTargetGroupOnDrop?: boolean
}
```

---

### `RowOrderHistorySnapshot`

```ts
export type RowOrderHistorySnapshot = {
  items: number[];
  proxyItems: number[];
};
```

---

### `RowOrderHistoryPatch`

```ts
export type RowOrderHistoryPatch = {
  beforePhysicalIndex: number;
  afterPhysicalIndex: number;
  beforeModel: DataType;
  afterModel: DataType;
  prop: ColumnProp;
  previousValue: unknown;
  value: unknown;
};
```

---

### `RowOrderHistoryChange`

```ts
export type RowOrderHistoryChange = {
  type: DimensionRows;
  before: RowOrderHistorySnapshot;
  after: RowOrderHistorySnapshot;
  movedPhysicalIndexes: number[];
  groupedPatches: RowOrderHistoryPatch[];
};
```

---

### `RowOrderAppliedEvent` (Extended from `index.ts`)

```ts
export type RowOrderAppliedEvent = RowOrderHistoryChange & {
  replay?: 'undo' | 'redo';
};
```

---

### `RowOrderHistoryRuntime`

```ts
interface RowOrderHistoryRuntime {
  applyHistoryChange(
      change: RowOrderHistoryChange,
      direction: 'undo' | 'redo',
    ): boolean
}
```

---

### `RowOrderServiceConfig`

```ts
interface RowOrderServiceConfig {
  dimension: PluginProviders['dimension'];
  orderStart(e: MouseEvent): void;
  positionChanged(e: MouseEvent, detail: RowOrderChangedDetail): void
}
```

---

### `DragEventsData` (Extended from `index.ts`)

```ts
interface DragEventsData {
  text?: string | number
}
```

---

### `RowOrderChange` (Extended from `index.ts`)

```ts
interface RowOrderChange {
  // ; // models
    dropPosition?: RowOrderDropPosition;
  originalEvent: MouseEvent;
  /**
     * Visible row index that the pointer resolved to before row-order target-index
     * normalization. Tree integrations use it to resolve the insertion boundary
     * against the current hierarchy.
     */
    targetRow?: number;
  /**
     * Visible row indexes that are part of the active drag selection.
     */
    visibleRowIndexes?: number[];
  /** Domain-owned source patches captured before the proxy mutation. */
    historyPatches?: RowOrderHistoryPatch[];
  /** Domain-corrected proxy order to persist in the atomic history entry. */
    historyProxyItemsAfter?: number[]
}
```

---

### `LocalSubscription`

```ts
export type LocalSubscription = {
  target: Element | Document;
  callback(...params: any[]): void;
};
```

---

### `StaticData`

```ts
export type StaticData = {
  dataItem: CellTemplateProp;
  dataEl: HTMLElement;
  scrollEl: Element;
  gridEl: HTMLElement;
  items: Map<number, DataType>;
};
```

---

### `draggableRender`

```ts
export function draggableRender(
  h: HyperFunc<VNode>,
  data: DragEventsData,
  _?: any
);
```

---

### `OrderHandler`

```ts
class OrderHandler {
  renderAutoscroll(_: MouseEvent, parent: HTMLElement | null): void;

  autoscroll(y: number, dataContainerHeight: number): void;

  start(
    e: MouseEvent,
    { el, gridRect, elScroll }: EventData,
    hint?: RowOrderPreviewContent,
  ): void;

  stop(): void;

  moveTip({ x, y }: Cell);

  showHandler(y: number, gridHeight: number): void;

  showValidationAt(y: number, gridHeight: number): void;

  setValidation(validation: RowOrderDropValidationResult): void;

  render(h: HyperFunc<VNode>, pluginId: string);
}
```

---

### `getTopRelative`

Get coordinate relative to the grid

```ts
export function getTopRelative(
  absoluteY: number,
  { yOffset, gridRect }: EventData
): number;
```

---

### `getRow`

Calculate cell based on x, y position

```ts
export function getRow(y: number, e: EventData): PositionItem;
```

---

### `getRowContentEnd`

```ts
export function getRowContentEnd(rows: DimensionSettingsState): number;
```

---

### `isRowInsideContent`

```ts
export function isRowInsideContent(y: number, e: EventData): boolean;
```

---

### `clampRowToContent`

```ts
export function clampRowToContent(row: number, e: EventData): number;
```

---

### `getDropRow`

```ts
export function getDropRow(row: number, y: number, e: EventData): number;
```

---

### `getCell`

Calculate cell based on x, y position

```ts
export function getCell({ y }: Cell, e: EventData): Cell;
```

---

### `EventData`

```ts
export type EventData = {
  el: HTMLElement;
  elScroll: Element;
  elRect: DOMRect;
  gridRect: DOMRect;
  yOffset: number;
  dataItem: DragEventsData;
  type: DimensionRows;
  rows: DimensionSettingsState;
  cols: DimensionSettingsState;
};
```

---

### `default`

```ts
class RowOrderService {
  /** Drag finished, calculate and apply changes */
  endOrder(e: MouseEvent, data: EventData): void;

  start(e: MouseEvent): void;

  /** Drag started, reserve initial cell for farther use */
  startOrder(cell: Cell);

  move(e: MouseEvent, data: EventData): PositionItem | null;

  /** Drag stopped, probably cursor outside of document area */
  clear(): void;
}
```

---

### `isRowOrderConfigEnabled`

```ts
export function isRowOrderConfigEnabled(
  config: RowOrderPluginConfig | false | undefined,
): boolean;
```

---

### `resolveRowDrag`

```ts
export function resolveRowDrag(
  rowDrag: RowDrag | undefined,
  model: CellTemplateProp,
): boolean;
```

---

### `normalizeDropRow`

```ts
export function normalizeDropRow(from: number, hoverRow: number): number;
```

---

### `getTargetIndex`

```ts
export function getTargetIndex(
  from: number,
  to: number,
  itemCount: number,
): number;
```

---

### `isNoopDrop`

```ts
export function isNoopDrop(
  range: RowOrderRange,
  targetIndex: number,
  rowIndexes?: RowOrderVisibleRowIndex[],
): boolean;
```

---

### `normalizeRowOrderIndexes`

```ts
export function normalizeRowOrderIndexes(
  rowIndexes: RowOrderVisibleRowIndex[],
  itemCount: number,
): RowOrderVisibleRowIndex[];
```

---

### `rangeToRowOrderIndexes`

```ts
export function rangeToRowOrderIndexes(
  range: RowOrderRange,
): RowOrderVisibleRowIndex[];
```

---

### `getRowOrderSelectionRange`

```ts
export function getRowOrderSelectionRange(
  rowIndexes: RowOrderVisibleRowIndex[],
): RowOrderRange;
```

---

### `getRowOrderTargetIndex`

```ts
export function getRowOrderTargetIndex({
  rowIndexes,
  to,
}: {
  rowIndexes: RowOrderVisibleRowIndex[];
  to: number;
}): number;
```

---

### `resolveRowOrderEditColumn`

```ts
export function resolveRowOrderEditColumn(
  columns: ColumnRegular[],
  prop: ColumnProp,
): RowOrderEditColumnResolution;
```

---

### `buildRowOrderMutation`

```ts
export function buildRowOrderMutation({
  from,
  to,
  itemCount,
  itemsOrder,
  proxyItemsOrder,
  rowIndexes,
}: {
  from: number;
  to: number;
  itemCount: number;
  itemsOrder: number[];
  proxyItemsOrder: number[];
  rowIndexes?: RowOrderVisibleRowIndex[];
}): RowOrderMutation | null;
```

---

### `resolveMovedRowFlashTargets`

```ts
export function resolveMovedRowFlashTargets({
  itemsOrder,
  movedPhysicalIndexes,
  type,
}: {
  itemsOrder: number[];
  movedPhysicalIndexes: Iterable<number>;
  type: DimensionRows;
}): RowOrderFlashRowTarget[];
```

---

### `normalizeValidationResult`

```ts
export function normalizeValidationResult(
  result: RowOrderDropValidationResult | boolean | void,
): RowOrderDropValidationResult;
```

---

### `buildPreviewContext`

```ts
export function buildPreviewContext({
  items,
  dataItem,
  type,
  prop,
}: {
  items: Map<number, DataType>;
  dataItem: CellTemplateProp;
  type: DimensionRows;
  prop?: ColumnProp;
}): RowOrderPreviewContext;
```

---

### `resolvePreviewContent`

```ts
export function resolvePreviewContent({
  context,
  legacyProp,
  preview,
  previewProp,
}: {
  context: RowOrderPreviewContext;
  legacyProp?: ColumnProp;
  preview?: 'compact' | 'none' | RowOrderPreviewRenderer;
  previewProp?: ColumnProp | RowOrderPreviewRenderer;
}): RowOrderPreviewContent;
```

---

### `buildDropValidationContext`

```ts
export function buildDropValidationContext({
  range,
  targetRow,
  targetIndex,
  type,
  items,
  dataItem,
  dropPosition,
  originalEvent,
  visibleRowIndexes,
}: {
  range: RowOrderRange;
  dropPosition?: RowOrderDropValidationContext['dropPosition'];
  targetRow: number;
  targetIndex: number;
  type: DimensionRows;
  items: Map<number, DataType>;
  dataItem: CellTemplateProp;
  originalEvent: MouseEvent;
  visibleRowIndexes?: RowOrderVisibleRowIndex[];
}): RowOrderDropValidationContext;
```

---

### `getRowDimensionState`

```ts
export function getRowDimensionState(
  stores: RowDimensionStateStores,
  type: DimensionRows,
): DimensionSettingsState;
```

---

### `resolveGroupedDrop`

```ts
export function resolveGroupedDrop({
  groupProps,
  items,
  movedItems,
  source,
  targetIndex,
  applyTargetGroupOnDrop = false,
  isGroupingRow,
  getGroupPath,
}: GroupedDropOptions): GroupedDropResolution;
```

---

### `RowOrderRange`

```ts
export type RowOrderRange = {
  from: number;
  to: number;
};
```

---

### `RowOrderVisibleRowIndex`

```ts
export type RowOrderVisibleRowIndex = number;
```

---

### `RowOrderMutation`

```ts
export type RowOrderMutation = {
  targetIndex: number;
  itemsOrder: number[];
  prevItems: number[];
  proxyItems: number[];
};
```

---

### `RowOrderFlashRowTarget`

```ts
export type RowOrderFlashRowTarget = {
  rowIndex: number;
  type: DimensionRows;
  direction: 'changed';
};
```

---

### `RowDimensionStateStores`

```ts
export type RowDimensionStateStores = Record<DimensionRows, {
  getCurrentState(): DimensionSettingsState;
}>;
```

---

### `GroupedDropEdit`

```ts
export type GroupedDropEdit = {
  physicalIndex: number;
  prop: ColumnProp;
  value: unknown;
};
```

---

### `GroupedDropResolution`

```ts
export type GroupedDropResolution =
  | { valid: true; edits: GroupedDropEdit[]; targetValues?: Record<string, unknown> }
  | { valid: false; reason: string };
```

---

### `GroupedDropOptions`

```ts
export type GroupedDropOptions = {
  groupProps: ColumnProp[];
  items: number[];
  movedItems: Map<number, DataType>;
  source: DataType[];
  targetIndex: number;
  applyTargetGroupOnDrop?: boolean;
  isGroupingRow(model?: DataType): boolean;
  getGroupPath(model: DataType): unknown[] | null;
};
```

---

### `RowOrderEditColumnResolution`

```ts
export type RowOrderEditColumnResolution = {
  column: ColumnRegular;
  index: number;
};
```

---

# Row Select

URL: https://pro.rv-grid.com/api/row-select/
Source: src/content/docs/api/row-select.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Enables checkbox on cells and columns
       */
      rowSelect?: boolean | ((model: CellTemplateProp) => boolean)
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Row selection plugin configuration.
       *
       * @deprecated Prefer the direct `grid.rowSelect` property.
       */
      rowSelect?: RowSelectConfig
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  /**
       * Row selection plugin configuration.
       */
      rowSelect?: RowSelectConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /**
       * Header cell with checkbox clicked
       */
      [ROW_ALL_SELECT_EVENT]: RowSelectAllEvent;
  /**
       * Cell with checkbox clicked in the row
       */
      [ROW_SELECT_EVENT]: RowSelectEvent;
  /**
       * When row selection happened. Returns selected objects.
       */
      [ROW_SELECTED_EVENT]: {
        selected: Map<DimensionRows, Set<number>>;
        visibleCount: number;
        visibleRowsCount: number;
        count: number;
        allRowsCount: number;
      }
}
```

## Plugin API

### `DEFAULT_SEL_PROP`

```ts
DEFAULT_SEL_PROP: string;
```

---

### `RowSelectPlugin`

The `RowSelectPlugin` enables checkbox-based row selection.

Quick setup:

```ts
import { RowSelectPlugin } from '@revolist/revogrid-pro';

grid.plugins = [RowSelectPlugin];
grid.columns = [
  { prop: 'select', name: '', rowSelect: true, size: 56 },
  { prop: 'name', name: 'Name' },
];
```

Public configuration:

| API | Default | Meaning |
| --- | --- | --- |
| `ColumnRegular.rowSelect` | `false` | Renders a row checkbox for normal data cells in that column. A function can hide the checkbox for specific cells. |
| `grid.rowSelect` | `{ grouping: false, rowOrder: false }` | Configures optional row-select behavior. Use this for grouping checkboxes and checkbox-driven row ordering. |
| `additionalData.rowSelect` | none | Legacy alias for `grid.rowSelect`. Prefer the direct grid property. |
| `rowSelect.grouping` | `false` | Opt-in checkbox support for RevoGrid grouping rows. Use `true` or `{ enabled: true }`. |
| `rowSelect.rowOrder` | `false` | Opt-in RowOrderPlugin integration. When enabled, a drag handle selects its row and dragging a selected row moves visible selected rows as a compact block. |

Index and count semantics:

| Term | Meaning |
| --- | --- |
| Data row | A real row from the user source data. |
| Synthetic grouping row | A row generated by RevoGrid grouping. It can render a group checkbox, but it is never stored as selected data. |
| Physical row index | The index stored in `rowselected.detail.selected`. For grouped rows this maps back to the original data row index, not the synthetic group source position. |
| Visible rows | Rows currently visible after filtering, sorting, grouping expansion/collapse, tree expansion/collapse, and row ordering. |
| `count` | Number of selected real data rows across the full data set. |
| `allRowsCount` | Number of selectable real data rows across the full data set. Synthetic grouping rows are excluded. |
| `visibleCount` | Number of selected real data rows currently visible. |
| `visibleRowsCount` | Number of selectable real data rows currently visible. |

Behavior matrix:

| Case | Behavior |
| --- | --- |
| Flat rows | A plain checkbox click independently toggles that row. Ctrl/Cmd-click toggles one row, Shift-click replaces with an anchored visible range, and Ctrl/Cmd+Shift-click adds the range. Header select-all toggles all currently matching data rows. |
| Shift-click | Uses the most recent non-Shift row input as a fixed anchor. Synthetic group rows are skipped. |
| Row header + RowHeaderPlugin | Uses independent row-header-owned state and never changes checkbox or programmatic selection. |
| Filtering | Selection stays attached to physical data rows. `rowselected` is re-emitted so visible counts reflect the filtered view. |
| Sorting | Selection stays attached to physical data rows after sort order changes. `rowselected` is re-emitted. |
| Row drag | Selection stays attached to physical data rows after row order changes. `rowselected` is re-emitted. |
| Grouping disabled | Group rows do not render checkboxes, even when a row-select column exists. |
| Grouping enabled | Group rows render checkboxes only when a visible row-select column exists. |
| Group checkbox click | Selects or clears all descendant real data rows in that group. Group rows themselves are not selected. |
| Group child roll-up | Some selected children make the group checkbox indeterminate. All selected children make it checked. Ancestor groups update the same way. |
| Collapsed groups | Header select-all toggles matching real data rows, including descendants hidden by collapsed groups. |
| Tree parent click | When `TreeDataPlugin` is registered, clicking a tree parent checkbox toggles that parent and all descendants. |
| Tree child click | Clicking a tree leaf/child without descendants toggles only that row. |
| Checkbox row-order | When `rowSelect.rowOrder` is enabled, dragging a selected row moves visible selected rows as a compact block. A drag handle on an unselected row replaces selection with that row. |

Events:

| Event | Constant | Use it for |
| --- | --- | --- |
| `rowselectclick` | `ROW_SELECT_EVENT` | Internal/plugin integration point for toggling one row. |
| `rowallselectclick` | `ROW_ALL_SELECT_EVENT` | Internal/plugin integration point for toggling all matching selectable rows. |
| `rowselected` | `ROW_SELECTED_EVENT` | Public application event. Read `selected`, `count`, `allRowsCount`, `visibleCount`, and `visibleRowsCount`. |

`rowselected.detail.selected` is a `Map<DimensionRows, Set<number>>` keyed by row type.
The set contains physical indexes for real data rows only.

#### Dependencies

- **Event integration** `tree-data`: Integrates with TreeDataPlugin descendant selection events when present.

```ts
class RowSelectPlugin {
  /**
     * Returns physical selected row indexes
     */
  getSelectedIndexes();

  /**
     * Replaces checkbox row selection for a row dimension.
     */
  setSelectedIndexes(type: DimensionRows, indexes: Iterable<number>): void;

  /**
     * Clears checkbox row selection and updates row/header checkbox state.
     */
  clearSelection(type?: DimensionRows): void;

  /**
     * Returns visible checkbox-selected rows for RowOrderPlugin integration.
     */
  getRowOrderSelection(
    context: RowOrderSelectionContext,
  ): RowOrderSelection | null;

  /** Whether checkbox row selection is exposed by an untrimmed grid column. */
  hasVisibleCheckboxColumn(): boolean;

  destroy();
}
```

---

### `RowSelectColumnType`

```ts
class RowSelectColumnType {}
```

---

### `normalizeRowSelectConfig`

Normalizes public row selection configuration to the internal shape.

```ts
export function normalizeRowSelectConfig(
  config?: boolean | RowSelectConfig,
): NormalizedRowSelectConfig;
```

---

### `RowSelectGroupingConfig`

Grouped row checkbox configuration for the row selection plugin.

```ts
interface RowSelectGroupingConfig {
  /**
     * Enables checkbox rendering on RevoGrid grouping rows.
     *
     * Disabled by default. When enabled, selecting a group checkbox selects or
     * clears all descendant data rows while synthetic group rows stay out of the
     * selected index set.
     */
    enabled?: boolean
}
```

---

### `RowSelectRowOrderConfig`

Checkbox-selected row-order integration configuration.

```ts
interface RowSelectRowOrderConfig {
  /**
     * Enables RowOrderPlugin integration with checkbox-selected rows.
     *
     * Disabled by default. When enabled, dragging a checked row moves all
     * visible checked rows in the same row viewport as a compact block.
     */
    enabled?: boolean
}
```

---

### `RowSelectConfig`

Row selection plugin configuration.

Set this on `grid.rowSelect`. `additionalData.rowSelect` is supported as a
compatibility alias, but the direct grid property is preferred.

Examples:

```ts
grid.rowSelect = { grouping: true };
grid.rowSelect = { grouping: { enabled: true } };
grid.rowSelect = { grouping: false };
grid.rowSelect = { rowOrder: true };
grid.rowSelect = { rowOrder: { enabled: true } };
```

```ts
interface RowSelectConfig {
  /**
     * Enables row selection integration with RevoGrid grouping.
     *
     * Defaults to `false`. Use `true` for the compact form or
     * `{ enabled: true }` for the future-compatible object form.
     */
    grouping?: boolean | RowSelectGroupingConfig;
  /**
     * Enables checkbox-selected row drag integration with RowOrderPlugin.
     *
     * Defaults to `false`. Use `true` for the compact form or
     * `{ enabled: true }` for the future-compatible object form.
     */
    rowOrder?: boolean | RowSelectRowOrderConfig
}
```

---

### `NormalizedRowSelectConfig`

Internal normalized row selection configuration.

```ts
interface NormalizedRowSelectConfig {
  grouping: {
      enabled: boolean;
    };
  rowOrder: {
      enabled: boolean;
    }
}
```

---

### `DEFAULT_ROW_SELECT_CONFIG`

Default row selection configuration.

Group row checkboxes are opt-in and disabled by default.

```ts
DEFAULT_ROW_SELECT_CONFIG: {
  grouping: { enabled: false; };
  rowOrder: { enabled: false; };
};
```

---

### `isRowSelectGroupingRow`

```ts
export function isRowSelectGroupingRow(row: DataType | undefined): boolean;
```

---

### `getRowSelectIndex`

```ts
export function getRowSelectIndex(
  source: DataType[],
  physicalIndex: number,
): number;
```

---

### `collectGroupLeafIndexes`

```ts
export function collectGroupLeafIndexes(
  source: DataType[],
  groupIndex: number,
  matchesGroupValue: GroupValueMatcher = defaultGroupValueMatcher,
  orderedIndexes?: number[],
): number[];
```

---

### `getGroupSelectionState`

```ts
export function getGroupSelectionState(
  selected: Set<number>,
  source: DataType[],
  groupIndex: number,
): GroupSelectionState;
```

---

### `createGroupSelectionStateLookup`

```ts
export function createGroupSelectionStateLookup(
  selected: Set<number>,
  source: DataType[],
  matchesGroupValue: GroupValueMatcher = defaultGroupValueMatcher,
  orderedIndexes?: number[],
): Map<number, GroupSelectionState>;
```

---

### `getVisibleSelectableIndexes`

```ts
export function getVisibleSelectableIndexes(
  source: DataType[],
  items: number[],
): number[];
```

---

### `countSelectableIndexes`

```ts
export function countSelectableIndexes(
  source: DataType[],
  items: number[],
): number;
```

---

### `countSelectedIndexes`

```ts
export function countSelectedIndexes(
  selected: Set<number>,
  source: DataType[],
): number;
```

---

### `countSelectedVisibleIndexes`

```ts
export function countSelectedVisibleIndexes(
  selected: Set<number>,
  source: DataType[],
  items: number[],
): number;
```

---

### `applySelectionToIndexes`

```ts
export function applySelectionToIndexes(
  selected: Set<number>,
  indexes: number[],
  shouldSelect: boolean,
);
```

---

### `getVisibleSelectionRange`

```ts
export function getVisibleSelectionRange(
  source: DataType[],
  items: number[],
  fromPhysicalIndex: number,
  toPhysicalIndex: number,
): number[];
```

---

### `GroupSelectionState`

```ts
interface GroupSelectionState {
  selected: boolean;
  indeterminate: boolean;
  selectedCount: number;
  totalCount: number
}
```

---

### `ROW_SELECT_ORIGINAL_INDEX`

```ts
ROW_SELECT_ORIGINAL_INDEX: string;
```

---

### `GroupValueMatcher`

```ts
export type GroupValueMatcher = (
  row: DataType,
  prop: ColumnProp,
  value: unknown,
) => boolean;
```

---

### `resolveRowSelectRowOrderSelection`

```ts
export function resolveRowSelectRowOrderSelection({
  draggedVisibleRowIndex,
  enabled,
  selected,
  source,
  visibleItems,
}: ResolveRowSelectRowOrderSelectionOptions): RowOrderSelection | null;
```

---

### `ResolveRowSelectRowOrderSelectionOptions`

```ts
interface ResolveRowSelectRowOrderSelectionOptions {
  draggedVisibleRowIndex: number;
  enabled: boolean;
  selected: Set<number> | undefined;
  source: DataType[];
  visibleItems: number[]
}
```

---

### `RowSelectEvent` (Extended from `index.ts`)

```ts
export type RowSelectEvent = CellTemplateProp & { originalEvent: MouseEvent };
```

---

### `RowSelectAllEvent` (Extended from `index.ts`)

```ts
export type RowSelectAllEvent = ColumnTemplateProp & {
  selected: boolean;
  type: DimensionCols;
};
```

---

### `defaultGroupValueMatcher`

```ts
export function defaultGroupValueMatcher(
  row: DataType,
  prop: ColumnProp,
  value: unknown,
  emptyGroupValue: unknown = '',
): boolean;
```

---

# Row Status

URL: https://pro.rv-grid.com/api/row-status/
Source: src/content/docs/api/row-status.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Renders a source-backed row-status checkbox for this column.
       *
       * The column `prop` stores a strict boolean. When it is `true`, the plugin
       * applies the configured attribute and the common `row-status` attribute
       * to the rendered row.
       */
      rowStatus?: RowStatusColumnConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  /** Emitted after a row-status edit and all hierarchy propagation finishes. */
      [ROW_STATUS_CHANGE_EVENT]: RowStatusChangeEvent
}
```

## Plugin API

### `isValidRowStatusAttribute`

Returns whether a row-status attribute can safely be rendered.

```ts
export function isValidRowStatusAttribute(attribute: unknown): attribute is string;
```

---

### `ROW_STATUS_ACTIVE_ATTRIBUTE`

```ts
ROW_STATUS_ACTIVE_ATTRIBUTE: string;
```

---

### `ROW_STATUS_CELL_CLASS`

```ts
ROW_STATUS_CELL_CLASS: string;
```

---

### `RowStatusPlugin`

Adds source-backed todo/status checkboxes to RevoGrid columns.

A status column is configured with `rowStatus: { attribute: 'data-done' }`.
The column `prop` stores a strict boolean, active rows receive both the
configured attribute and `[row-status]`, and the default stylesheet strikes
through non-checkbox cells. Multiple status columns are independent.

When `TreeDataPlugin` and `grid.tree` are active, editing a parent cascades
to all descendants. Child edits recompute ancestors and mixed subtrees render
an indeterminate parent checkbox. Filtering, sorting, collapsing, pinned rows,
and virtualization remain stable because updates use physical source indexes.
Classic grouping rows render one checkbox per status column in the synthetic
group label. Group edits update every real descendant, while checked and
indeterminate state is derived from those descendants without persisting
values on synthetic group rows. Derived attributes are placed on the
`.row-status-group-label` element because core grouping headers do not pass
through the normal data-row renderer.

The direct checkbox uses RevoGrid's normal `beforeedit`/`afteredit` lifecycle.
After the complete hierarchy batch, the plugin emits `rowstatuschange`.

```ts
import { RowStatusPlugin, TreeDataPlugin } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [TreeDataPlugin, RowStatusPlugin];
grid.tree = {
  idField: 'id',
  parentIdField: 'parentId',
  rootParentId: null,
  expandAll: true,
};
grid.columns = [
  { prop: 'done', name: 'Done', rowStatus: { attribute: 'data-done' } },
  { prop: 'archived', name: 'Archived', rowStatus: { attribute: 'data-archived' } },
  { prop: 'task', name: 'Task', tree: true },
];
grid.source = [
  { id: 1, parentId: null, task: 'Release', done: false, archived: false },
  { id: 2, parentId: 1, task: 'Write notes', done: false, archived: false },
];
grid.addEventListener('rowstatuschange', event => {
  console.log(event.detail.physicalIndexes, event.detail.models);
});
```

```ts
class RowStatusPlugin {
  destroy();
}
```

---

### `RowStatusColumnConfig`

Configures a source-backed checkbox status column.

```ts
interface RowStatusColumnConfig {
  /**
     * Attribute applied to the rendered row when the column value is `true`.
     * Use a safe semantic `data-*` or `aria-*` attribute such as `data-done`.
     */
    attribute: string
}
```

---

### `RowStatusChangeEvent`

Complete source update emitted after a row-status edit and tree propagation.

```ts
interface RowStatusChangeEvent {
  /** Row viewport containing the changed models. */
    type: DimensionRows;
  /** Status column property written to the source models. */
    prop: ColumnProp;
  /** Configured row attribute for the status column. */
    attribute: string;
  /** Boolean value requested by the direct checkbox edit. */
    value: boolean;
  /**
     * Physical application-source indexes changed by the edit and hierarchy roll-up.
     * Synthetic classic-grouping rows are excluded.
     */
    physicalIndexes: number[];
  /** Updated real source models in the same order as `physicalIndexes`. */
    models: DataType[]
}
```

---

# Row Transpose

URL: https://pro.rv-grid.com/api/row-transpose/
Source: src/content/docs/api/row-transpose.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  rowTranspose?: TransposeConfig;
  'row-transpose'?: TransposeConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
         * Additional data property transpose
         * @deprecated Use the direct `grid.rowTranspose` property instead.
         */
        transpose?: TransposeConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [ROW_TRANSPOSE_EVENT]: undefined
}
```

## Plugin API

### `RowTransposePlugin`

The `RowTransposePlugin` is a plugin for the RevoGrid that enables transposing
grid data, switching rows and columns while preserving data integrity. This plugin
enhances the grid's versatility by allowing users to view and manipulate data
from different perspectives. It supports customizable transposed row and column
headers and ensures seamless toggling between original and transposed views.

**Key Features**:
- Transposing functionality: Toggles between original and transposed grid views.
- Configurable headers: Customize transposed row and column headers.
- Event-driven: Listens for `ROW_TRANSPOSE_EVENT` to trigger the transpose action.
- Data integrity: Preserves original data and column configurations for easy restoration.

**Usage**:
- Integrate the `RowTransposePlugin` with your RevoGrid instance to enable transposing.
- Configure transposed headers using `TransposeConfig` if needed.
- Trigger the transposition via `ROW_TRANSPOSE_EVENT`.

### Example
```typescript
import { RowTransposePlugin, ROW_TRANSPOSE_EVENT } from '@revolist/revogrid-pro';

const grid = document.createElement('revo-grid');
grid.plugins = [RowTransposePlugin];

// Trigger transpose event
const event = new CustomEvent(ROW_TRANSPOSE_EVENT);
grid.dispatchEvent(event);
```

This plugin is ideal for applications requiring flexible data presentation,
offering users a dynamic method to interact with complex datasets.

#### Dependencies

- **Event integration** `ROW_TRANSPOSE_EVENT`: Listens to row transpose events to toggle between original and transposed grid state.
- **Config integration** `additionalData.transpose`: Reads legacy transpose configuration from additionalData.transpose.

```ts
class RowTransposePlugin {
  transpose();
}
```

---

### `TransposedRow`

The `TransposedRow` class is a utility class for transposing a grid. It is
used internally by the `RowTransposePlugin`.

When an instance of `TransposedRow` is created, it dynamically defines
properties on itself for each row in the original source. The property
names are in the format `colX`, where `X` is the index of the row in the
original source. The property values are the values of the field in the
original source that the `TransposedRow` was created with.

The `defineProperties` method is used to define the properties on the
`TransposedRow` instance. It is called automatically by the constructor.

```ts
class TransposedRow {
  getOriginalModels(props: ColumnProp[]);
}
```

---

### `TransposeConfig`

```ts
export type TransposeConfig = {
  // By default, it will transpose column header to additional column
  transposedRowHeader?: Partial<ColumnRegular> | false;
  // By default, it will transpose row header to additional row
  transposedColumnHeader?: Partial<ColumnRegular>;
  // By default, it will show row header
  hideRowHeader?: boolean;
  // By default, it will show column header
  hideColumnHeader?: boolean;
};
```

---

# Same Value Merge

URL: https://pro.rv-grid.com/api/same-value-merge/
Source: src/content/docs/api/same-value-merge.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Enables same-value merging for this column.
       *
       * `true` keeps the legacy behavior: adjacent comparable rows merge when
       * this column's value matches. Object config enables grouped merge
       * boundaries where follower columns inherit a leader column's row run.
       */
      merge?: boolean | SameValueMergeConfig
}
```

## Plugin API

### `SameValueMergeConfig`

```ts
export type SameValueMergeConfig = {
  /**
   * Shared identifier for columns that should use the same merge boundaries.
   * Columns in the same group look for a column with `mergeLeader: true`.
   */
  mergeGroup?: string;

  /**
   * Marks this column as the boundary source for its `mergeGroup`.
   * Follower columns still compare their own values, but cannot merge beyond
   * the leader column's comparable row run.
   */
  mergeLeader?: boolean;

  /**
   * Additional row fields that must match before this column can merge.
   * This is most useful on the merge leader to split equal leader values by
   * business keys such as material, operation number, or route id.
   */
  mergeDependsOn?: ColumnProp[];

  /**
   * Marks merge-run start cells as sticky through StickyCellsPlugin.
   *
   * SameValueMergePlugin auto-registers StickyCellsPlugin when this option is
   * enabled on at least one merge column.
   */
  sticky?: boolean;
};
```

---

### `SameValueMergePlugin`

The `SameValueMergePlugin` is a RevoGrid plugin designed to merge cells with the same values in a column.
It adds visual merge markers to cells that have the same value as the nearest comparable visible row
above or below them.

**Key Features**:
- Visible row comparison: Checks nearest comparable visible rows above and below the current cell
- Grouping support: Group rows are comparable when they carry the current column value
- Column Configuration: Supports a 'merge' property on columns to enable/disable merging
- Grouped boundaries: Columns can share a `mergeGroup` and follow a `mergeLeader` run
- Visual Styling: Adds an `auto-merge` marker used by CSS to hide repeated values

**Usage**:
- This plugin should be included in the grid's plugin array to enable same-value merging functionality.
- Configure columns with the 'merge' property to enable merging for specific columns.

### Example
```typescript
import { SameValueMergePlugin } from './same-value-merge-plugin';

const grid = document.createElement('revo-grid');
grid.plugins = [SameValueMergePlugin]; // Add merge plugin
grid.columns = [
  { prop: 'name', name: 'Name' },
  { prop: 'category', name: 'Category', merge: true }, // Enable merging for this column
];
```

### Grouped merge example
```typescript
grid.columns = [
  { prop: 'material', name: 'Material' },
  { prop: 'operationNo', name: 'Operation' },
  {
    prop: 'workcenter',
    name: 'Work Center',
    merge: {
      mergeGroup: 'operation',
      mergeLeader: true,
      mergeDependsOn: ['material', 'operationNo'],
    },
  },
  { prop: 'quantity', name: 'Quantity', merge: { mergeGroup: 'operation' } },
];
```

```ts
class SameValueMergePlugin {
  destroy(): void;
}
```

---

### `isSameValueMergeConfig`

```ts
export function isSameValueMergeConfig(merge: ColumnRegular['merge']): merge is SameValueMergeConfig;
```

---

### `getMergeConfig`

```ts
export function getMergeConfig(column: ColumnRegular | undefined): SameValueMergeConfig | undefined;
```

---

### `isMergeEnabled`

```ts
export function isMergeEnabled(column: ColumnRegular | undefined): column is ColumnRegular;
```

---

### `resolveSameValueMergeState`

```ts
export function resolveSameValueMergeState({
  column,
  model,
  rowIndex,
  rowType,
  providers,
  getAllColumns,
}: {
  column: ColumnRegular;
  model: DataType;
  rowIndex: number;
  rowType: keyof PluginProviders['data']['stores'];
  providers: PluginProviders;
  getAllColumns: () => ColumnRegular[];
}): MergeCellState | undefined;
```

---

### `MergeCellState`

```ts
export type MergeCellState = {
  autoMerge: 'main' | 'child' | 'last';
  endsBeforeGroup: boolean;
};
```

---

### `applySameValueMergeStickyColumns`

```ts
export function applySameValueMergeStickyColumns(
  columnsByType: ColumnCollection['columns'],
  resolveMergeStickyCell: (
    model: CellTemplateProp,
    stickyCell: StickyCellPredicate | undefined,
  ) => boolean,
): boolean;
```

---

### `isPivotGeneratedRow`

```ts
export function isPivotGeneratedRow(model?: DataType);
```

---

### `isPivotTotalRow`

```ts
export function isPivotTotalRow(model?: DataType);
```

---

### `hasPivotMergeBoundary`

```ts
export function hasPivotMergeBoundary(
  items: number[],
  visibleIndex: number,
  source: DataType[],
  currentModel: DataType | undefined,
  prop: ColumnProp,
);
```

---

# Search Input

URL: https://pro.rv-grid.com/api/search-input/
Source: src/content/docs/api/search-input.md

### `SearchInput`

```ts
export function SearchInput({
  value = '',
  inputRef,
  rootClassName = '',
  inputClassName = '',
  iconClassName = '',
  shortcutClassName = '',
  shortcut,
  icon,
  leading,
  hideIcon = false,
  trailing,
  testId,
  onValueChange,
  onInput,
  type = 'search',
  ...inputProps
}: SearchInputProps): any;
```

---

### `SearchInputRenderable`

```ts
export type SearchInputRenderable = any;
```

---

### `SearchInputRef`

```ts
export type SearchInputRef<T> = { current: T | null } | ((instance: T | null) => void) | null;
```

---

### `SearchInputEvent` (Extended from `index.tsx`)

```ts
export type SearchInputEvent<T extends EventTarget> = Event & { currentTarget: T };
```

---

### `SearchInputProps`

```ts
export type SearchInputProps = {
  value?: string;
  inputRef?: SearchInputRef<HTMLInputElement>;
  rootClassName?: string;
  inputClassName?: string;
  iconClassName?: string;
  shortcutClassName?: string;
  shortcut?: SearchInputRenderable;
  icon?: SearchInputRenderable;
  leading?: SearchInputRenderable;
  hideIcon?: boolean;
  trailing?: SearchInputRenderable;
  testId?: string;
  onValueChange?: (value: string, event: SearchInputEvent<HTMLInputElement>) => void;
  onInput?: (event: SearchInputEvent<HTMLInputElement>) => void;
  type?: 'search' | 'text';
  [attribute: string]: any;
};
```

---

# Segmented Switch

URL: https://pro.rv-grid.com/api/segmented-switch/
Source: src/content/docs/api/segmented-switch.md

### `SegmentedSwitch`

```ts
export function SegmentedSwitch<T extends SegmentedSwitchValue = SegmentedSwitchValue>({
  value,
  options,
  onChange,
  ariaLabel,
  className = '',
  itemClassName = '',
  countClassName = '',
  activeClassName = 'on',
  disabled = false,
  role = 'tablist',
  testId,
  renderOption,
  renderCount,
}: SegmentedSwitchProps<T>): any;
```

---

### `SegmentedSwitchRenderable`

```ts
export type SegmentedSwitchRenderable = any;
```

---

### `SegmentedSwitchValue`

```ts
export type SegmentedSwitchValue = string | number;
```

---

### `SegmentedSwitchOption`

```ts
export type SegmentedSwitchOption<T extends SegmentedSwitchValue = SegmentedSwitchValue> = {
  value: T;
  label: SegmentedSwitchRenderable;
  count?: number | string;
  title?: string;
  ariaLabel?: string;
  disabled?: boolean;
  className?: string;
  testId?: string;
  id?: string;
  ariaControls?: string;
};
```

---

### `SegmentedSwitchRole`

```ts
export type SegmentedSwitchRole = 'tablist' | 'radiogroup' | 'group';
```

---

### `SegmentedSwitchProps`

```ts
export type SegmentedSwitchProps<T extends SegmentedSwitchValue = SegmentedSwitchValue> = {
  value: T;
  options: SegmentedSwitchOption<T>[];
  onChange: (value: T, option: SegmentedSwitchOption<T>) => void;
  ariaLabel?: string;
  className?: string;
  itemClassName?: string;
  countClassName?: string;
  activeClassName?: string;
  disabled?: boolean;
  role?: SegmentedSwitchRole;
  testId?: string;
  renderOption?: (option: SegmentedSwitchOption<T>, state: { active: boolean; disabled: boolean }) => SegmentedSwitchRenderable;
  renderCount?: (option: SegmentedSwitchOption<T>, state: { active: boolean; disabled: boolean }) => SegmentedSwitchRenderable;
};
```

---

# Selection

URL: https://pro.rv-grid.com/api/selection/
Source: src/content/docs/api/selection.md

### `selectionPluginDependencies`

Dependency metadata for the complete Pro selection suite.

#### Dependencies

- **Auto-installed** `MultiRangeSelectionPlugin`: Provides disjoint cell ranges, shared range rendering, clipboard behavior, and range edits.
- **Auto-installed** `RowHeaderPlugin`: Provides spreadsheet-style whole-row selection through row headers.
- **Auto-installed** `ColumnSelectionPlugin`: Provides spreadsheet-style whole-column selection through column headers.
- **Auto-installed** `RowSelectPlugin`: Provides independent checkbox-based row selection for rowSelect columns.
- **Auto-installed** `RangeSelectionLimitPlugin`: Provides optional row-only or column-only range constraints when configured.

```ts
selectionPluginDependencies: PluginDependency[];
```

---

### `SelectionPlugin`

Installs the complete compatible Pro selection stack with one grid plugin.

Each child keeps ownership of its existing configuration, events, state, and
public methods. Existing child instances are reused, so the suite can safely
coexist with explicitly registered selection plugins without duplicate
listeners or competing state owners.

**Example:**
```typescript
import { SelectionPlugin, rowHeaders } from '@revolist/revogrid-pro';

grid.range = true;
grid.rowHeaders = rowHeaders({ showHeaderFocusBtn: false });
grid.plugins = [SelectionPlugin];
```

```ts
class SelectionPlugin {}
```

---

# Server Side Grouping

URL: https://pro.rv-grid.com/api/server-side-grouping/
Source: src/content/docs/api/server-side-grouping.md

## Module Extensions

### `ServerSideGroupingLoadRowsRequest`

```ts
interface ServerSideGroupingLoadRowsRequest {
  /**
     * Group route being loaded. The root route is an empty array.
     */
    route: ServerSideGroupRoute;
  /**
     * Route depth. Root is level 0, first-level groups are level 1.
     */
    level: number;
  /**
     * Active grouping columns in server request order.
     */
    groupBy: ColumnProp[];
  /**
     * Offset inside this route, aligned to the configured block size.
     */
    start: number;
  /**
     * Maximum number of direct route children requested.
     */
    limit: number;
  /**
     * Active remote sort model.
     */
    sort?: ServerSideGroupingSort;
  /**
     * Active remote column filter model.
     */
    filter?: ServerSideGroupingFilter;
  /**
     * Optional global quick-filter payload forwarded to the server.
     */
    quickFilter?: ServerSideGroupingQuickFilter;
  /** Canonical filter tree for expressions that cannot be represented per column. */
    filterAst?: FilterAst;
  /** Clock and timezone captured for canonical filter evaluation. */
    executionContext?: FilterExecutionContext;
  temporalContext?: TemporalFilterContext;
  levelParams?: unknown;
  parent?: ServerSideGroupRow
}
```

---

### `ServerSideGroupingLoadExpandedGroupsRequest`

```ts
interface ServerSideGroupingLoadExpandedGroupsRequest {
  /**
     * Active grouping columns in server request order.
     */
    groupBy: ColumnProp[];
  /**
     * Active remote sort model.
     */
    sort?: ServerSideGroupingSort;
  /**
     * Active remote column filter model.
     */
    filter?: ServerSideGroupingFilter;
  /**
     * Optional global quick-filter payload forwarded to the server.
     */
    quickFilter?: ServerSideGroupingQuickFilter;
  /** Canonical filter tree for expressions that cannot be represented per column. */
    filterAst?: FilterAst;
  /** Clock and timezone captured for canonical filter evaluation. */
    executionContext?: FilterExecutionContext;
  temporalContext?: TemporalFilterContext
}
```

---

### `ServerSideGroupingConfig`

```ts
interface ServerSideGroupingConfig {
  /**
     * Column props used as grouping levels. The server decides returned groups for each level.
     */
    groupBy: ColumnProp[];
  /**
     * Loads one block of groups or rows for a route. The AbortSignal is cancelled on refresh/config changes.
     */
    loadRows: ServerSideGroupingLoadRows<T>;
  /**
     * Optional one-shot datasource used by `expandAllGroups`.
     *
     * Return every group row that should be expanded with its full `route`. This
     * avoids recursive route loading for backends that can compute the group tree
     * in one request.
     */
    loadExpandedGroups?: ServerSideGroupingLoadExpandedGroups;
  /**
     * Number of direct route children requested per block.
     */
    blockSize?: number;
  /**
     * Purge child route cache when a group is collapsed.
     */
    purgeClosedGroups?: boolean;
  /**
     * @deprecated Use `purgeClosedGroups`.
     */
    purgeOnCollapse?: boolean;
  /**
     * Expands routes unless the user explicitly collapses them. A predicate can target selected routes.
     */
    openGroupsByDefault?: boolean | ((route: ServerSideGroupRoute) => boolean);
  /**
     * Initial externally controlled expanded routes.
     */
    expandedRoutes?: ServerSideGroupRoute[] | Set<string>;
  /**
     * Limits simultaneous remote block loads.
     */
    maxConcurrentRequests?: number;
  /**
     * Debounces block load execution. Useful when virtualization emits several scroll updates quickly.
     */
    blockLoadDebounceMs?: number;
  /**
     * Optional global quick-filter payload included in every request.
     */
    quickFilter?: ServerSideGroupingQuickFilter;
  getLevelParams?: (
      route: ServerSideGroupRoute,
      level: number,
      parent?: ServerSideGroupRow,
    ) => unknown;
  formatAggregate?: (
      key: string,
      value: unknown,
      group: ServerSideGroupRow,
    ) => string;
  formatGroupRow?: (
      group: ServerSideGroupRow,
      context: {
        route: ServerSideGroupRoute;
        level: number;
        expanded: boolean;
        groupBy: ColumnProp[];
      },
    ) => string;
  groupRowRenderer?: GroupLabelTemplateFunc;
  /**
     * Receives the imperative API while the plugin is active and `null` on cleanup.
     */
    api?: (api: ServerSideGroupingApi | null) => void
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  serverSideGrouping?: Partial<ServerSideGroupingConfig>;
  'server-side-grouping'?: Partial<ServerSideGroupingConfig>
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * @deprecated Use `grid.serverSideGrouping` instead.
       */
      serverSideGrouping?: Partial<ServerSideGroupingConfig>
}
```

## Plugin API

### `ServerSideGroupingPlugin`

#### Dependencies

- **Event integration** `groupexpandclick`, `viewportscroll`: Uses core grouping row rendering and viewport events to load grouped server-side blocks.
- **Event integration** `beforefilterapply`, `beforequickfilterapply`, `beforesortingapply`: Forwards sorting, filtering, and quick-filter metadata to server-side grouping requests.

```ts
class ServerSideGroupingPlugin {
  /** Expands one loaded server-side group and loads its visible descendants. */
  async expandGroup(id: ServerSideGroupId);

  /** Expands every currently loaded server-side group. */
  async expandAllGroups();

  /** Collapses one server-side group. */
  collapseGroup(id: ServerSideGroupId);

  /** Collapses every loaded server-side group. */
  collapseAllGroups();

  destroy();
}
```

---

### `normalizeServerSideGroupingConfig`

Resolves user config into a complete internal config object.

This is the single place for defaults and deprecated alias handling, including
`purgeOnCollapse` -> `purgeClosedGroups`.

```ts
export function normalizeServerSideGroupingConfig<T extends DataType>(
  config: Partial<ResolvedServerSideGroupingConfig<T>> = {},
): ResolvedServerSideGroupingConfig<T>;
```

---

### `normalizeServerSideGroupingFilter`

Builds the server request filter model from the RevoGrid filter event.

The advanced `filterItems` model is preferred because the legacy collection
only contains the first filter per column. Values are cloned into a stable,
serializable shape so request logs, cache keys, and REST bodies can represent
Set-backed selection filters and nested slider ranges consistently.

```ts
export function normalizeServerSideGroupingFilter(
  detail?: RemoteFilterEventDetail,
): ServerSideGroupingFilter | undefined;
```

---

### `ServerSideGroupingModel`

```ts
class ServerSideGroupingModel {
  configure(config: ResolvedServerSideGroupingConfig<T>, preserveExpanded = true);

  setSort(sort?: ServerSideGroupingSort);

  setFilter(filter?: ServerSideGroupingFilter);

  setFilterAst(filterAst?: FilterAst);

  setExecutionContext(executionContext?: FilterExecutionContext);

  setQuickFilter(quickFilter?: ServerSideGroupingQuickFilter);

  setTemporalContext(temporalContext?: TemporalFilterContext);

  reset(preserveExpanded = true);

  async loadRoot();

  async expand(routeOrId: ServerSideGroupId);

  async expandAllGroups();

  collapse(routeOrId: ServerSideGroupId);

  collapseAllLoadedGroups();

  async refreshServerSide();

  async refreshRoute(routeOrId: ServerSideGroupId);

  purgeRoute(routeOrId: ServerSideGroupId = ROOT_ROUTE);

  destroy();

  async retryRoute(routeOrId: ServerSideGroupId);

  async loadRouteBlock(routeOrId: ServerSideGroupId, start = 0, force = false): Promise<boolean>;

  getMissingBlockRequests(rows: DataType[]);

  materialize(displayProp?: ColumnProp): DataType[];

  getCacheState(): ServerSideGroupingCacheState;

  getRouteKey(route: ServerSideGroupRoute);
}
```

---

### `createServerSideGroupRouteKey`

Builds a stable cache key for a route. Route keys are intentionally JSON strings so
they round-trip through the public API and can distinguish nested values safely.

```ts
export function createServerSideGroupRouteKey(route: ServerSideGroupRoute): string;
```

---

### `parseServerSideGroupId`

Converts a public group id into a route array. Accepts real route arrays,
serialized route keys returned by `createServerSideGroupRouteKey`, or a single key.

```ts
export function parseServerSideGroupId(id: ServerSideGroupId): ServerSideGroupRoute;
```

---

### `ServerSideGroupKey`

```ts
export type ServerSideGroupKey = string | number | boolean | null;
```

---

### `ServerSideGroupRoute`

```ts
export type ServerSideGroupRoute = ServerSideGroupKey[];
```

---

### `ServerSideGroupId`

```ts
export type ServerSideGroupId = string | ServerSideGroupRoute;
```

---

### `ServerSideGroupKind`

```ts
export type ServerSideGroupKind = 'group' | 'row' | 'loading' | 'skeleton' | 'error';
```

---

### `ServerSideGroupingStatus`

```ts
export type ServerSideGroupingStatus = 'idle' | 'loading' | 'loaded' | 'error';
```

---

### `ServerSideGroupingSort`

```ts
export type ServerSideGroupingSort = Record<ColumnProp, Exclude<Order, undefined>>;
```

---

### `ServerSideGroupingFilterItem`

Serializable server-side filter item forwarded to `loadRows`.

It intentionally mirrors RevoGrid filter metadata while replacing runtime-only
values such as `Set` with JSON-friendly arrays. Pro filters such as selection
and slider can therefore be sent directly to REST/SQL backends.

```ts
/**
 * Serializable server-side filter item forwarded to `loadRows`.
 *
 * It intentionally mirrors RevoGrid filter metadata while replacing runtime-only
 * values such as `Set` with JSON-friendly arrays. Pro filters such as selection
 * and slider can therefore be sent directly to REST/SQL backends.
 */
export type ServerSideGroupingFilterItem =
  | FilterCollectionItem
  | Pick<FilterData, 'id' | 'type' | 'value' | 'relation' | 'hidden'>;
```

---

### `ServerSideGroupingFilter`

Server filter model keyed by column prop. A prop can contain one item for the
legacy filter collection path or multiple items for the advanced filter panel.

```ts
/**
 * Server filter model keyed by column prop. A prop can contain one item for the
 * legacy filter collection path or multiple items for the advanced filter panel.
 */
export type ServerSideGroupingFilter = Record<
  ColumnProp,
  ServerSideGroupingFilterItem | ServerSideGroupingFilterItem[]
>;
```

---

### `ServerSideGroupingTotals`

```ts
export type ServerSideGroupingTotals = Record<string, unknown>;
```

---

### `ServerSideGroupingQuickFilter`

```ts
export type ServerSideGroupingQuickFilter = string | QuickFilter | Record<string, unknown>;
```

---

### `ServerSideGroupRow`

```ts
interface ServerSideGroupRow {
  key: ServerSideGroupKey;
  /**
     * Optional display label. Falls back to `key`.
     */
    label?: string;
  /**
     * Count displayed on the group row. Usually total descendant leaf rows.
     */
    count?: number;
  /**
     * Known number of direct children for this group route. At the final grouping
     * level this is usually the number of leaf rows.
     */
    childCount?: number;
  /**
     * Whether this group can be expanded. Defaults to true while there are
     * more grouping columns, and false at leaf level unless explicitly set.
     */
    hasChildren?: boolean;
  /**
     * Totals or aggregates associated with this group row.
     */
    aggregates?: ServerSideGroupingTotals;
  totals?: ServerSideGroupingTotals;
  /**
     * Server-provided params forwarded when this group route is loaded.
     */
    levelParams?: unknown
}
```

---

### `ServerSideExpandedGroupRow` (Extended from `index.ts`)

```ts
interface ServerSideExpandedGroupRow {
  /**
     * Full route for this group row. For example `['Germany', 'Swimming']`.
     */
    route: ServerSideGroupRoute
}
```

---

### `ServerSideGroupingLoadExpandedGroupsResult`

```ts
interface ServerSideGroupingLoadExpandedGroupsResult {
  /**
     * Flattened list of all group rows that should be expanded.
     *
     * Parent routes are inferred from each route. The plugin rebuilds route
     * blocks from this list and keeps leaf-row blocks unloaded.
     */
    groups: ServerSideExpandedGroupRow[];
  grandTotals?: ServerSideGroupingTotals
}
```

---

### `ServerSideGroupingLoadRowsResult`

```ts
interface ServerSideGroupingLoadRowsResult {
  groups?: ServerSideGroupRow[];
  rows?: T[];
  /**
     * Known direct child count for this route. For grouped routes this is the
     * number of direct child groups. For leaf routes this is the number of rows.
     */
    rowCount?: number;
  /**
     * Alias for `rowCount` for server APIs that return `total`.
     */
    total?: number;
  /**
     * Whether more direct children can be requested after this block.
     */
    hasMore?: boolean;
  totals?: ServerSideGroupingTotals;
  grandTotals?: ServerSideGroupingTotals
}
```

---

### `ServerSideGroupingLoadRows`

```ts
export type ServerSideGroupingLoadRows<T extends DataType = DataType> = (
  request: ServerSideGroupingLoadRowsRequest,
  signal?: AbortSignal,
) => Promise<ServerSideGroupingLoadRowsResult<T> | T[] | ServerSideGroupRow[]>;
```

---

### `ServerSideGroupingLoadExpandedGroups`

```ts
export type ServerSideGroupingLoadExpandedGroups = (
  request: ServerSideGroupingLoadExpandedGroupsRequest,
  signal?: AbortSignal,
) => Promise<ServerSideGroupingLoadExpandedGroupsResult | ServerSideExpandedGroupRow[]>;
```

---

### `ServerSideGroupingCacheRouteState`

```ts
interface ServerSideGroupingCacheRouteState {
  route: ServerSideGroupRoute;
  status: ServerSideGroupingStatus;
  rowCount?: number;
  hasMore?: boolean;
  loadingBlocks: number[];
  loadedBlocks: number[];
  error?: unknown
}
```

---

### `ServerSideGroupingCacheState`

```ts
interface ServerSideGroupingCacheState {
  groupBy: ColumnProp[];
  expandedRoutes: ServerSideGroupRoute[];
  routeCount: number;
  routes: ServerSideGroupingCacheRouteState[];
  grandTotals?: ServerSideGroupingTotals;
  activeRequests: number;
  queuedRequests: number
}
```

---

### `ServerSideGroupingApi`

```ts
interface ServerSideGroupingApi {
  /**
     * Expands a group route and lazily loads the first child block when needed.
     */
    expandGroup(id: ServerSideGroupId): Promise<void>;
  /**
     * Expands all server group routes.
     *
     * If `loadExpandedGroups` is configured this uses one backend request to
     * hydrate all group routes. Otherwise it recursively loads group blocks.
     * Leaf-row routes are opened but not fully loaded; normal viewport loading
     * fetches visible row blocks.
     */
    expandAllGroups(): Promise<void>;
  /**
     * Collapses a group route. Cache retention is controlled by `purgeClosedGroups`.
     */
    collapseGroup(id: ServerSideGroupId): void;
  /**
     * Collapses all group routes currently known by the cache.
     */
    collapseAllGroups(): void;
  /**
     * Clears the server-side grouping cache and reloads the root route.
     */
    refreshServerSide(): Promise<void>;
  /**
     * Clears and reloads one route branch without resetting the whole grid.
     */
    refreshRoute(route: ServerSideGroupId): Promise<void>;
  /**
     * Purges all cached blocks or the requested route branch.
     */
    purgeServerSideCache(route?: ServerSideGroupId): void;
  /**
     * Returns a serializable snapshot of routes, loaded blocks, and queue state.
     */
    getServerSideCacheState(): ServerSideGroupingCacheState
}
```

---

### `ResolvedServerSideGroupingConfig` (Extended from `index.ts`)

```ts
interface ResolvedServerSideGroupingConfig {
  blockSize: number;
  purgeClosedGroups: boolean;
  purgeOnCollapse: boolean;
  openGroupsByDefault: boolean | ((route: ServerSideGroupRoute) => boolean);
  expandedRoutes?: ServerSideGroupRoute[] | Set<string>;
  maxConcurrentRequests: number;
  blockLoadDebounceMs: number
}
```

---

### `ServerSideGroupingSyntheticRow` (Extended from `index.ts`)

```ts
interface ServerSideGroupingSyntheticRow {
  __serverSideGrouping?: true;
  __serverSideGroupingKind: ServerSideGroupKind;
  __serverSideGroupingRoute: ServerSideGroupRoute;
  __serverSideGroupingRouteKey: string;
  __serverSideGroupingIndex?: number;
  __serverSideGroupingBlockStart?: number;
  __serverSideGroupingError?: unknown
}
```

---

### `createServerSideGroupingApi`

Creates the public imperative API from plugin-local handlers.

```ts
export function createServerSideGroupingApi(
  handlers: ServerSideGroupingApiHandlers,
): ServerSideGroupingApi;
```

---

### `ServerSideGroupingApiHandlers`

Plugin methods used to construct the public server-side grouping API.

```ts
interface ServerSideGroupingApiHandlers {
  /** Expands and loads a route when needed. */
    expandGroup(id: ServerSideGroupId): Promise<void>;
  /** Expands every server group route, loading group blocks recursively. */
    expandAllGroups(): Promise<void>;
  /** Collapses a route and optionally purges child cache based on config. */
    collapseGroup(id: ServerSideGroupId): void;
  /** Collapses every loaded group route. */
    collapseAllGroups(): void;
  /** Clears all route blocks and reloads the root route. */
    refreshServerSide(): Promise<void>;
  /** Clears one route branch and reloads it when visible/expanded. */
    refreshRoute(route: ServerSideGroupId): Promise<void>;
  /** Purges all cache or one route branch without forcing an immediate load. */
    purgeServerSideCache(route?: ServerSideGroupId): void;
  /** Returns a serializable cache snapshot for diagnostics. */
    getServerSideCacheState(): ServerSideGroupingCacheState
}
```

---

### `markServerSideGroupingColumn`

Marks the first visible column as grouping-capable so RevoGrid's core grouping
row renderer can draw server-side synthetic group rows.

```ts
export function markServerSideGroupingColumn(
  columnsByType: Record<string, ColumnRegular[]> | undefined,
  refreshByType: (type: ColumnType) => void,
);
```

---

### `addServerSideGroupingExcelExportTransformer`

Prepends the grouping export transformer to a one-off export config.

```ts
export function addServerSideGroupingExcelExportTransformer<T extends { exportTransformers?: ExcelExportContextTransformer[] } | undefined>(
  config: T,
): T;
```

---

### `transformServerSideGroupingExcelExport`

Normalizes server-side grouping rows before Excel providers receive them.

Group rows are exportable, but loading/skeleton/error placeholders are UI
state and should not become workbook rows. Group labels are copied into the
first visible export column so exports match what users see in the grid.

```ts
transformServerSideGroupingExcelExport: ExcelExportContextTransformer;
```

---

### `ServerSideGroupingFilterEventDetail`

**@deprecated** Use the shared `RemoteFilterEventDetail` type.

```ts
/** @deprecated Use the shared `RemoteFilterEventDetail` type. */
export type ServerSideGroupingFilterEventDetail = RemoteFilterEventDetail;
```

---

### `applyServerSideGroupingLoadResult`

Applies a loaded block to a route and returns optional grand totals.

This function owns response normalization, group-vs-leaf child shaping,
known/unknown count inference, and `hasMore` calculation.

```ts
export function applyServerSideGroupingLoadResult<T extends DataType>({
  state,
  blockStart,
  response,
  config,
  ensureRoute,
}: ApplyLoadResultOptions<T>): ServerSideGroupingTotals | undefined;
```

---

### `ApplyLoadResultOptions`

Inputs required to merge one datasource response into a route block.

```ts
interface ApplyLoadResultOptions {
  /** Route state receiving the loaded block. */
    state: RouteState<T>;
  /** Route-local block start offset. */
    blockStart: number;
  /** Raw datasource response, including legacy array-only forms. */
    response: ServerSideGroupingLoadRowsResult<T> | T[] | ServerSideGroupRow[];
  /** Resolved plugin config used to infer grouping level and block size. */
    config: ResolvedServerSideGroupingConfig<T>;
  /** Route creator callback used when returned group rows introduce child routes. */
    ensureRoute(route: ServerSideGroupRoute, parent?: ServerSideGroupRow): RouteState<T>
}
```

---

### `materializeServerSideGroupingRoute`

Converts one route plus any expanded descendants into RevoGrid source rows.

The output includes synthetic core grouping rows, loading rows, skeleton rows,
error rows, and final leaf rows. It does not perform network loading.

```ts
export function materializeServerSideGroupingRoute<T extends DataType>(
  state: RouteState<T>,
  displayProp: ColumnProp,
  includeGroupRows: boolean,
  context: ServerSideGroupingMaterializeContext<T>,
): DataType[];
```

---

### `ServerSideGroupingMaterializeContext`

Callbacks and config required to convert route state into grid rows.

```ts
interface ServerSideGroupingMaterializeContext {
  /** Resolved grouping config used for row labels, block size, and grouping depth. */
    config: ResolvedServerSideGroupingConfig<T>;
  /** Ensures nested routes exist when expanded group rows are materialized. */
    ensureRoute(route: ServerSideGroupRoute, parent?: ServerSideGroupRow): RouteState<T>;
  /** Returns the current expansion state for a serialized route key. */
    isRouteExpanded(routeKey: string): boolean
}
```

---

### `getMissingServerSideGroupingBlockRequests`

Scans currently visible materialized rows and returns unloaded route blocks.

The plugin uses this after scroll/render events to lazily load only blocks
represented by visible loading or skeleton rows.

```ts
export function getMissingServerSideGroupingBlockRequests(
  rows: DataType[],
  routes: Map<string, RouteState>,
);
```

---

### `SERVER_SIDE_GROUPING_PLUGIN`

```ts
SERVER_SIDE_GROUPING_PLUGIN: string;
```

---

### `isAbortError`

Normalizes AbortError detection across browser DOMException and plain error objects.

```ts
export function isAbortError(error: unknown);
```

---

### `ServerSideGroupingRequestQueue`

Coordinates block request concurrency, debounce, and cancellation for a model instance.

The queue is intentionally independent from route state. It answers only:
"when may a request run?" and "which currently running requests should be aborted?"

```ts
class ServerSideGroupingRequestQueue {
  /**
     * Aborts all active requests and releases queued waiters so stale model work
     * can exit through generation checks.
     */
  cancelPendingRequests();

  /**
     * Creates and tracks an AbortController for one datasource call.
     */
  createAbortController();

  /**
     * Stops tracking a controller after its datasource call settles.
     */
  releaseAbortController(controller: AbortController);

  /**
     * Waits until a concurrency slot is available and returns an idempotent release function.
     */
  async acquireRequestSlot();

  /**
     * Applies configured debounce before a block request reaches the datasource.
     */
  async waitForBlockLoadDebounce();
}
```

---

### `isDescendantRouteKey`

Checks whether a serialized route belongs to a route branch. Used by partial
refresh and purge so those operations can target one group without clearing siblings.

```ts
export function isDescendantRouteKey(routeKey: string, parentRoute: ServerSideGroupRoute);
```

---

### `toServerSideGroupingBlockStart`

Aligns any child index to the start offset for its server block.

```ts
export function toServerSideGroupingBlockStart(index: number, blockSize: number);
```

---

### `ROOT_ROUTE`

Canonical route for top-level group rows. All server-side grouping loads start here.

```ts
ROOT_ROUTE: ServerSideGroupRoute;
```

---

### `MESSAGE_PROP`

Internal fallback cell property used when the grid has no visible grouping column.

```ts
MESSAGE_PROP: string;
```

---

### `createRouteState`

Creates empty route state and seeds known child counts from parent metadata.

```ts
export function createRouteState<T extends DataType>(
  route: ServerSideGroupRoute,
  config: ResolvedServerSideGroupingConfig<T>,
  parent?: ServerSideGroupRow,
): RouteState<T>;
```

---

### `clearRouteState`

Clears loaded data and error/loading metadata while keeping the route object
and parent metadata alive for partial refreshes.

```ts
export function clearRouteState(state: RouteState);
```

---

### `getMaterializedChildCount`

Returns the number of child slots to materialize for a route.
Known-count routes render exactly `rowCount`; unknown-count routes render up
to the largest loaded block and may add a tail loader separately.

```ts
export function getMaterializedChildCount(state: RouteState);
```

---

### `getChildAt`

Resolves a child at an absolute route-local index from the block cache.

```ts
export function getChildAt<T extends DataType>(
  state: RouteState<T>,
  index: number,
  blockSize: number,
);
```

---

### `toCacheRouteState`

Converts mutable internal route state into the public serializable cache view.

```ts
export function toCacheRouteState(route: RouteState): ServerSideGroupingCacheRouteState;
```

---

### `MaterializedChild`

A direct child materialized for a route block. Group children point to their
child route, while row children are final leaf records from the backend.

```ts
/**
 * A direct child materialized for a route block. Group children point to their
 * child route, while row children are final leaf records from the backend.
 */
export type MaterializedChild<T extends DataType = DataType> =
  | { kind: 'group'; group: ServerSideGroupRow; route: ServerSideGroupRoute }
  | { kind: 'row'; row: T };
```

---

### `RouteState`

Mutable cache state for one route.

A route is the unit of loading, expansion, retry, purge, and refresh. Blocks
are keyed by their start offset and contain only direct children for this route.

```ts
interface RouteState {
  /** Route represented by this state. Root is an empty array. */
    route: ServerSideGroupRoute;
  /** Stable serialized route key used in maps and synthetic row metadata. */
    routeKey: string;
  /** Parent group row returned by the backend, if this is not root. */
    parent?: ServerSideGroupRow;
  /** Server-provided params forwarded when this route is loaded. */
    levelParams?: unknown;
  /** Loaded blocks of direct child groups or leaf rows keyed by block start. */
    blocks: Map<number, MaterializedChild<T>[]>;
  /** Block starts that currently have in-flight load requests. */
    loadingBlocks: Set<number>;
  /** Per-block request versions used to ignore stale responses. */
    blockVersions: Map<number, number>;
  /** Monotonic route request version. Incrementing invalidates previous block loads. */
    requestVersion: number;
  /** Current route loading state used by materialization. */
    status: 'idle' | 'loading' | 'loaded' | 'error';
  /** Known direct child count. Undefined means unknown count. */
    rowCount?: number;
  /** Unknown-count continuation flag from the backend. */
    hasMore?: boolean;
  /** Route-level totals returned by the backend. */
    totals?: ServerSideGroupingTotals;
  /** Last route/block load error. */
    error?: unknown;
  /** Failed block start. Retry targets this block only. */
    errorBlockStart?: number
}
```

---

# Shared

URL: https://pro.rv-grid.com/api/shared/
Source: src/content/docs/api/shared.md

### `useDialogDrag`

Keeps Preact hooks inside product bundles while reusing the shared
framework-neutral drag behavior from Pro.

```ts
export function useDialogDrag<
  Target extends HTMLElement,
  Handle extends HTMLElement,
>({
  targetRef,
  handleRef,
  enabled = true,
}: UseDialogDragOptions<Target, Handle>): void;
```

---

# Smart Panel

URL: https://pro.rv-grid.com/api/smart-panel/
Source: src/content/docs/api/smart-panel.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  smartPanel?: SmartPanelConfig | boolean;
  'smart-panel'?: SmartPanelConfig | boolean
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  smartpanelchange: SmartPanelChangeDetail;
  smartpanelerror: SmartPanelErrorDetail
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /** @deprecated Use `grid.smartPanel` instead. */
      smartPanel?: SmartPanelConfig | boolean
}
```

## Plugin API

### `SmartPanelComponent`

Presentation-only Smart Panel renderer. It can be hosted independently from the plugin.

```ts
class SmartPanelComponent {
  setHost(host: HTMLElement);

  setConfig(config: NormalizedSmartPanelConfig<T>);

  getHost();

  render(items: SmartPanelResolvedItem<T>[]);

  destroy(clear = true);
}
```

---

### `normalizeSmartPanelConfig`

```ts
export function normalizeSmartPanelConfig<T extends DataType = DataType>(
  config?: SmartPanelConfig<T> | boolean,
): NormalizedSmartPanelConfig<T>;
```

---

### `defaultSmartPanelItems`

```ts
defaultSmartPanelItems: SmartPanelItem<DataType>[];
```

---

### `SmartPanelPlugin`

Provider-backed, formula-capable status panel for RevoGrid.

#### Dependencies

- **Event integration** `...REFRESH_EVENTS`: Keeps panel summaries synchronized with grid state changes.
- **Config integration** `additionalData.smartPanel`: Reads the legacy additionalData.smartPanel configuration.

```ts
class SmartPanelPlugin {
  getSnapshot();

  getItems();

  getComponent();

  setHost(host: HTMLElement | null);

  async refresh();

  destroy();
}
```

---

### `resolveSmartPanelItems`

```ts
export async function resolveSmartPanelItems<T extends DataType>(
  grid: HTMLRevoGridElement,
  providers: PluginProviders,
  snapshot: SmartPanelSnapshot<T>,
  config: NormalizedSmartPanelConfig<T>,
  onError: (error: unknown, item?: SmartPanelItem<T>) => void,
): Promise<SmartPanelResolvedItem<T>[]>;
```

---

### `evaluateValuesFormula`

```ts
export function evaluateValuesFormula(formula: string, values: unknown[]);
```

---

### `resolveMetric`

```ts
export function resolveMetric<T extends DataType>(metric: SmartPanelMetric, snapshot: SmartPanelSnapshot<T>);
```

---

### `createSmartPanelSnapshot`

```ts
export function createSmartPanelSnapshot<T extends DataType = DataType>(
  providers: PluginProviders,
  revision = Date.now(),
): SmartPanelSnapshot<T>;
```

---

### `getSelectedRanges`

```ts
export function getSelectedRanges(providers: PluginProviders): SmartPanelRange[];
```

---

### `SmartPanelAlignment`

```ts
export type SmartPanelAlignment = 'left' | 'center' | 'right';
```

---

### `SmartPanelValueScope`

```ts
export type SmartPanelValueScope = 'selection' | 'visibleRows' | 'allRows';
```

---

### `SmartPanelMetric`

```ts
export type SmartPanelMetric =
  | 'selectedCells'
  | 'selectedRows'
  | 'visibleSelectedRows'
  | 'selectedColumns'
  | 'visibleRows'
  | 'totalRows'
  | 'hiddenRows'
  | 'visibleNodes'
  | 'totalNodes'
  | 'focusedCell'
  | 'focusedColumn'
  | 'rangeAddress'
  | 'numericCount'
  | 'sum'
  | 'average'
  | 'min'
  | 'max'
  | 'distinct';
```

---

### `SmartPanelRange`

```ts
interface SmartPanelRange {
  rowType: DimensionRows;
  colType: DimensionCols;
  range: RangeArea
}
```

---

### `SmartPanelCell`

```ts
interface SmartPanelCell {
  model: T;
  column: ColumnRegular;
  rowType: DimensionRows;
  colType: DimensionCols;
  rowIndex: number;
  columnIndex: number;
  value: unknown;
  rawValue: unknown
}
```

---

### `SmartPanelFocus`

```ts
interface SmartPanelFocus {
  model: T;
  column: ColumnRegular;
  rowType: DimensionRows;
  colType: DimensionCols;
  rowIndex: number;
  columnIndex: number;
  address: string;
  value: unknown;
  rawValue: unknown
}
```

---

### `SmartPanelSnapshot`

```ts
interface SmartPanelSnapshot {
  ranges: SmartPanelRange[];
  rangeAddress: string;
  selectedCells: SmartPanelCell<T>[];
  selectedRows: T[];
  selectedRowCount: number;
  visibleSelectedRowCount: number;
  rangeRows: T[];
  selectedColumns: ColumnRegular[];
  selectedValues: unknown[];
  selectedNumericValues: number[];
  visibleRows: T[];
  allRows: T[];
  visibleGridRows: T[];
  allGridRows: T[];
  visibleRowCount: number;
  totalRowCount: number;
  hiddenRowCount: number;
  visibleNodeCount: number;
  totalNodeCount: number;
  focus?: SmartPanelFocus<T>;
  revision: number
}
```

---

### `SmartPanelContext`

```ts
interface SmartPanelContext {
  grid: HTMLRevoGridElement;
  providers: PluginProviders;
  snapshot: SmartPanelSnapshot<T>;
  item: SmartPanelItem<T>;
  values: unknown[]
}
```

---

### `SmartPanelItemValue`

```ts
export type SmartPanelItemValue<T extends DataType = DataType> =
  | SmartPanelMetric
  | ((context: SmartPanelContext<T>) => unknown | Promise<unknown>);
```

---

### `SmartPanelItem`

```ts
interface SmartPanelItem {
  id: string;
  label?: string;
  metric?: SmartPanelMetric;
  formula?: string;
  resolve?: (context: SmartPanelContext<T>) => unknown | Promise<unknown>;
  scope?: SmartPanelValueScope;
  column?: ColumnProp;
  align?: SmartPanelAlignment;
  order?: number;
  priority?: number;
  className?: string;
  title?: string | ((context: SmartPanelContext<T>) => string | undefined);
  visible?: boolean | ((context: SmartPanelContext<T>) => boolean);
  format?: (value: unknown, context: SmartPanelContext<T>) => string;
  render?: (value: unknown, context: SmartPanelContext<T>) => Node | string | null | undefined
}
```

---

### `SmartPanelResolvedItem`

```ts
interface SmartPanelResolvedItem {
  id: string;
  label?: string;
  value: unknown;
  text: string;
  align: SmartPanelAlignment;
  order: number;
  priority: number;
  className?: string;
  title?: string;
  node?: Node | null;
  source: SmartPanelItem<T>
}
```

---

### `SmartPanelConfig`

```ts
interface SmartPanelConfig {
  /** A user-owned container. When omitted the plugin inserts one after the grid. */
    host?: HTMLElement | (() => HTMLElement | null | undefined) | null;
  /** Omit to use the built-in spreadsheet-style row and selection insights. */
    items?: SmartPanelItem<T>[];
  className?: string;
  ariaLabel?: string;
  hiddenWhenEmpty?: boolean;
  locale?: string | string[];
  numberFormat?: Intl.NumberFormatOptions;
  formatValue?: (value: unknown, context: SmartPanelContext<T>) => string;
  onError?: (error: SmartPanelErrorDetail<T>) => void;
  schedule?: 'microtask' | 'animationFrame'
}
```

---

### `NormalizedSmartPanelConfig` (Extended from `index.ts`)

```ts
interface NormalizedSmartPanelConfig {
  items: SmartPanelItem<T>[];
  ariaLabel: string;
  hiddenWhenEmpty: boolean;
  numberFormat: Intl.NumberFormatOptions;
  schedule: 'microtask' | 'animationFrame'
}
```

---

### `SmartPanelChangeDetail`

```ts
interface SmartPanelChangeDetail {
  snapshot: SmartPanelSnapshot<T>;
  items: SmartPanelResolvedItem<T>[]
}
```

---

### `SmartPanelErrorDetail`

```ts
interface SmartPanelErrorDetail {
  error: unknown;
  item?: SmartPanelItem<T>
}
```

---

# Sorting

URL: https://pro.rv-grid.com/api/sorting/
Source: src/content/docs/api/sorting.md

### `hasActiveSorting`

Checks whether a sorting map contains at least one active order.

Empty maps and properties with `undefined` order are treated as inactive.

```ts
export declare function hasActiveSorting(sorting?: SortingOrder): boolean;;
```

---

### `getSortingIndex`

Returns one-based additive sorting rank for a column.

A single active sort does not need a visible rank, so it returns undefined.

```ts
export declare function getSortingIndex(sorting: SortingOrder | undefined, prop: ColumnProp, sortingOrder?: SortingColumnOrder): SortingColumnRender['sortIndex'];;
```

---

### `sortIndexByItems`

Sorts row indexes against a source collection.

**@param** indexes - Current proxy row indexes to sort.

**@param** source - Full source collection addressed by the indexes.

**@param** sortingFunc - Comparator functions by column property.

**@param** sorting - Active sorting order by column property.

**@param** sortingColumns - Column metadata by property for default-comparer optimization.

**@param** sortingOrder - Active sorting priority in click/config insertion order.

**@returns** Sorted proxy indexes. With no sorting function keys, returns source-order indexes.

```ts
export declare function sortIndexByItems(indexes: number[], source: DataType[], sortingFunc?: SortingOrderFunction, sorting?: SortingOrder, sortingColumns?: SortingColumnMap, sortingOrder?: SortingColumnOrder): number[];;
```

---

### `defaultCellCompare`

```ts
export declare function defaultCellCompare(this: {
    column?: ColumnRegular;
}, prop: ColumnProp, a: DataType, b: DataType): 0 | 1 | -1;;
```

---

### `descCellCompare`

```ts
export declare function descCellCompare(cmp: CellCompareFunc): (prop: ColumnProp, a: DataType, b: DataType) => number;;
```

---

### `getNextOrder`

```ts
export declare function getNextOrder(currentOrder: Order): Order;;
```

---

### `getComparer`

```ts
export declare function getComparer(column: Partial<ColumnRegular> | undefined, order: Order): CellCompareFunc | undefined;;
```

---

### `SortingPlugin`

Lifecycle
1.

**@event** `beforesorting` - Triggered when sorting just starts. Nothing has happened yet. This can be triggered from a column or from the source. If the type is from rows, the column will be undefined.
2.

**@event** `beforesourcesortingapply` - Triggered before the sorting data is applied to the data source. You can prevent this event, and the data will not be sorted.
3.

**@event** `beforesortingapply` - Triggered before the sorting data is applied to the data source. You can prevent this event, and the data will not be sorted. This event is only called from a column sorting click.
4.

**@event** `aftersortingapply` - Triggered after sorting has been applied and completed. The event detail includes the final sorting state and sorting column metadata when available.

Note: If you prevent an event, it will not proceed to the subsequent steps.

```ts
class SortingPlugin {
  /**
       * Schedules sorting before the next render.
       *
       * @param order - Active sorting order by column property.
       * @param sortingFunc - Comparator functions by column property.
       * @param sortingColumns - Column metadata by property.
       * @param sortingOrder - Active sorting priority in click/config insertion order.
       * @param ignoreViewportUpdate - Skips dimension position recalculation when true.
       */
  startSorting(order?: SortingOrder, sortingFunc?: SortingOrderFunction, ignoreViewportUpdate?: boolean): void;;

  startSorting(order?: SortingOrder, sortingFunc?: SortingOrderFunction, sortingColumns?: SortingColumnMap, sortingOrder?: SortingColumnOrder, ignoreViewportUpdate?: boolean): void;;

  /**
       * Applies sorting requested by a sortable header click.
       *
       * @param column - Column that initiated sorting.
       * @param additive - If true, add/remove this column from the current multi-sort state.
       */
  headerclick(column: ColumnRegular, additive: boolean): void;;

  /**
       * Runs a scheduled sort and resolves the render-blocking sorting promise.
       *
       * @param order - Active sorting order by column property.
       * @param comparison - Comparator functions by column property.
       * @param sortingColumns - Column metadata by property.
       * @param sortingOrder - Active sorting priority in click/config insertion order.
       * @param ignoreViewportUpdate - Skips dimension position recalculation when true.
       */
  runSorting(order?: SortingOrder, comparison?: SortingOrderFunction, ignoreViewportUpdate?: boolean): void;;

  runSorting(order?: SortingOrder, comparison?: SortingOrderFunction, sortingColumns?: SortingColumnMap, sortingOrder?: SortingColumnOrder, ignoreViewportUpdate?: boolean): void;;

  /**
       * Sorts row proxy indexes by sorting functions.
       *
       * @requires proxyItems applied to row store
       * @requires source applied to row store
       *
       * @param sorting - per column sorting
       * @param sortingFunc - Comparator functions by column property.
       * @param sortingColumns - Column metadata by property.
       * @param sortingOrder - Active sorting priority in click/config insertion order.
       * @param types - Row stores to sort.
       * @param ignoreViewportUpdate - Skips dimension position recalculation when true.
       */
  sort(sorting?: SortingOrder, sortingFunc?: SortingOrderFunction, types?: DimensionRows[], ignoreViewportUpdate?: boolean): void;;

  sort(sorting?: SortingOrder, sortingFunc?: SortingOrderFunction, sortingColumns?: SortingColumnMap, sortingOrder?: SortingColumnOrder, types?: DimensionRows[], ignoreViewportUpdate?: boolean): void;;
}
```

---

### `SortingOrder`

Current sorting order per column property.

```ts
/**
 * Current sorting order per column property.
 */
export type SortingOrder = Record<ColumnProp, Order>;
```

---

### `SortingOrderFunction`

Comparator functions indexed by column property.

Undefined comparator entries are treated as inactive sorting entries.

```ts
/**
 * Comparator functions indexed by column property.
 *
 * Undefined comparator entries are treated as inactive sorting entries.
 */
export type SortingOrderFunction = Record<ColumnProp, CellCompareFunc | undefined>;
```

---

### `SortingColumnMap`

Column metadata indexed by column property.

This is an internal companion map for `SortingOrderFunction`. It lets the
sorting helper detect the default comparer path without mutating
`CellCompareFunc` instances or changing the public comparator contract.

```ts
/**
 * Column metadata indexed by column property.
 *
 * This is an internal companion map for `SortingOrderFunction`. It lets the
 * sorting helper detect the default comparer path without mutating
 * `CellCompareFunc` instances or changing the public comparator contract.
 */
export type SortingColumnMap = Record<ColumnProp, Partial<ColumnRegular> | undefined>;
```

---

### `SortingColumnOrder`

Active sorting priority in click/config insertion order.

This is stored separately from `SortingOrder` because JavaScript object keys
that look like integers are enumerated in numeric order, not insertion order.

```ts
/**
 * Active sorting priority in click/config insertion order.
 *
 * This is stored separately from `SortingOrder` because JavaScript object keys
 * that look like integers are enumerated in numeric order, not insertion order.
 */
export type SortingColumnOrder = ColumnProp[];
```

---

### `SortingColumnRender`

Header metadata used to display additive sort priority.

```ts
/**
 * Header metadata used to display additive sort priority.
 */
export type SortingColumnRender = {
    /**
     * One-based additive sorting rank.
     */
    sortIndex?: number;
};
```

---

### `AfterSortingApplyEvent`

Sorting information emitted after sorting is applied.

```ts
/**
 * Sorting information emitted after sorting is applied.
 */
export type AfterSortingApplyEvent = {
    /**
     * Final active sorting order per column property.
     */
    sorting?: SortingOrder;
    /**
     * Column metadata indexed by sorted column property.
     */
    sortingColumns?: SortingColumnMap;
    /**
     * Active sorting priority in click/config insertion order.
     */
    sortingOrder?: SortingColumnOrder;
    /**
     * Row stores affected by the sorting run.
     */
    types: DimensionRows[];
};
```

---

### `ColumnSetEvent`

Sorting information emitted after columns are set.

```ts
/**
 * Sorting information emitted after columns are set.
 */
export type ColumnSetEvent = {
    order: SortingOrder;
};
```

---

### `SortingConfig`

External sorting configuration.

```ts
/**
 * External sorting configuration.
 */
export type SortingConfig = {
    /**
     * Columns to sort by.
     */
    columns?: {
        prop: ColumnProp;
        order: Order;
        cellCompare?: CellCompareFunc;
    }[];
    /**
     * If true, merge provided columns with the current sorting state.
     * If false or omitted, replace current sorting state.
     */
    additive?: boolean;
};
```

---

### `SortingSign`

Renders sorting direction and optional additive sorting rank.

```ts
SortingSign: ({ column }: Props) => any;
```

---

# Sticky Cells

URL: https://pro.rv-grid.com/api/sticky-cells/
Source: src/content/docs/api/sticky-cells.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Defines whether a cell participates in StickyCellsPlugin row discovery.
       *
       * Use this for sticky behavior and keep `cellProperties` focused on cell
       * styling, attributes, and event props.
       */
      stickyCell?: StickyCellPredicate
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Sticky cells plugin configuration.
       *
       * ```ts
       * grid.additionalData = {
       *   stickyCells: { maxRows: 2 },
       * };
       * ```
       */
      stickyCells?: StickyCellsConfig
}
```

## Plugin API

### `StickyCellsConfig`

```ts
interface StickyCellsConfig {
  /**
     * Maximum amount of active sticky rows appended to `pinnedTopSource`.
     *
     * The nearest sticky row is appended last, so it renders closest to the
     * scrollable body after any user-defined pinned top rows.
     *
     * @default 1
     */
    maxRows?: number;
  /**
     * Makes plugin-managed sticky pinned rows readonly.
     *
     * This only affects the cloned rows rendered in `rowPinStart`; original source
     * rows and user-provided pinned top rows keep their normal readonly behavior.
     *
     * @default true
     */
    readonlyPinnedRows?: boolean
}
```

---

### `StickyCellPredicate`

```ts
export type StickyCellPredicate = boolean | ((params: CellTemplateProp) => boolean);
```

---

### `StickyCellsPlugin`

The `StickyCellsPlugin` keeps marked rows visible by appending the active
sticky rows to RevoGrid's pinned top row source.

Sticky cells are configured through a column `stickyCell` predicate. If any
visible cell in a row resolves `stickyCell` to `true`, that row can become an
active sticky row. The row is cloned into `rowPinStart` once it starts
crossing above the visible row viewport.

**Key Features**:
- Uses a dedicated column `stickyCell` predicate; no separate sticky row data source is required.
- Supports one or more active sticky rows pinned at the top of the scrolling row viewport.
- Activates only after the bottom edge of the source row crosses above the visible viewport.
- Preserves user-defined `pinnedTopSource` rows and removes only plugin-managed sticky rows.
- Reuses normal pinned row rendering, including `cellTemplate` and `beforecellrender` integrations.

**Behavior**:
- The last `stickyCells.maxRows` sticky rows at or above the scroll position stay active.
- User pinned top rows render first; plugin-managed sticky rows are appended after them.

### Example
```ts
import { StickyCellsPlugin } from '@revolist/revogrid-pro';

const stickyCell = ({ model }) => model.isCheckpoint === true;

const grid = document.createElement('revo-grid');
grid.plugins = [StickyCellsPlugin];
grid.columns = [
  {
    name: 'Account',
    prop: 'account',
    stickyCell,
  },
  {
    name: 'Status',
    prop: 'status',
    stickyCell,
  },
];
```

```ts
class StickyCellsPlugin {}
```

---

### `resolveActiveStickyRows`

```ts
export function resolveActiveStickyRows(
  rowIndex: number,
  context: ActiveStickyRowsContext,
): number[];
```

---

### `resolveBottomStableTreeRows`

```ts
export function resolveBottomStableTreeRows(
  rowIndex: number,
  rowCount: number,
  context: ActiveStickyRowsContext,
): number[];
```

---

### `findIndexedStickyRowsAtOrBefore`

```ts
export function findIndexedStickyRowsAtOrBefore(
  indexedStickyRows: number[],
  rowIndex: number,
  maxRows: number,
): number[];
```

---

### `filterVisibleBottomRows`

```ts
export function filterVisibleBottomRows(
  rowIndexes: number[],
  providers: PluginProviders,
  isAtBottom: () => boolean = () => isScrolledToBottom(providers),
): number[];
```

---

### `filterVisibleRows`

```ts
export function filterVisibleRows(
  rowIndexes: number[],
  providers: PluginProviders,
): number[];
```

---

### `isScrolledToBottom`

```ts
export function isScrolledToBottom(providers: PluginProviders): boolean;
```

---

### `isSameRowIndexes`

```ts
export function isSameRowIndexes(a: number[], b: number[]): boolean;
```

---

### `ActiveStickyRowsContext`

```ts
interface ActiveStickyRowsContext {
  maxRows: number;
  providers: PluginProviders;
  revogrid: HTMLRevoGridElement;
  indexedStickyRows: number[];
  includeTreeRow?: boolean;
  isAtBottom(): boolean;
  resolveStickyColumns(rowIndex: number): boolean
}
```

---

### `markCellOnlyStickyColumn`

```ts
export function markCellOnlyStickyColumn(column: ColumnRegular);
```

---

### `unmarkCellOnlyStickyColumn`

```ts
export function unmarkCellOnlyStickyColumn(column: ColumnRegular);
```

---

### `isCellOnlyStickyColumn`

```ts
export function isCellOnlyStickyColumn(column: ColumnRegular | undefined): boolean;
```

---

### `normalizeStickyCellsConfig`

```ts
export function normalizeStickyCellsConfig(
  config: StickyCellsConfig | undefined,
): Required<StickyCellsConfig>;
```

---

### `STICKY_GRID_CLASS`

```ts
STICKY_GRID_CLASS: string;
```

---

### `STICKY_ACTIVE_CLASS`

```ts
STICKY_ACTIVE_CLASS: string;
```

---

### `STICKY_PIN_ANIMATING_CLASS`

```ts
STICKY_PIN_ANIMATING_CLASS: string;
```

---

### `STICKY_PINNED_ROW_CLASS`

```ts
STICKY_PINNED_ROW_CLASS: string;
```

---

### `STICKY_PIN_ANIMATION_MS`

```ts
STICKY_PIN_ANIMATION_MS: 180;
```

---

### `STICKY_INDEX_SLICE_MS`

```ts
STICKY_INDEX_SLICE_MS: 4;
```

---

### `STICKY_INDEX_SLICE_ROWS`

```ts
STICKY_INDEX_SLICE_ROWS: 2500;
```

---

### `DEFAULT_MAX_STICKY_ROWS`

```ts
DEFAULT_MAX_STICKY_ROWS: 1;
```

---

### `StickyRowsIndexer`

```ts
class StickyRowsIndexer {
  reset();

  cancel();

  schedule(rowIndex: number, callback: () => void);

  indexSlice(): {
    discoveredStickyRow: boolean;
    indexedThroughRow: number;
    needsMore: boolean;
    startedThroughRow: number;
  };

  add(rowIndex: number);
}
```

---

### `createPinnedStickyRow`

```ts
export function createPinnedStickyRow(
  rowStore: RowStore,
  rowIndex: number,
  stickyColumns: StickyRowCache | null = null,
  cellOnly = false,
): StickyPinnedRow | null;
```

---

### `stripPluginPinnedRows`

```ts
export function stripPluginPinnedRows(source: DataType[]): DataType[];
```

---

### `isPluginPinnedRow`

```ts
export function isPluginPinnedRow(row: DataType): row is StickyPinnedRow;
```

---

### `getPluginPinnedRowStickyColumns`

```ts
export function getPluginPinnedRowStickyColumns(row: DataType): StickyRowCache | null;
```

---

### `getPluginPinnedRowSourceIndex`

```ts
export function getPluginPinnedRowSourceIndex(row: DataType): number | undefined;
```

---

### `isPluginPinnedRowCellOnly`

```ts
export function isPluginPinnedRowCellOnly(row: DataType): boolean;
```

---

### `isPluginPinnedCell`

```ts
export function isPluginPinnedCell(
  row: DataType,
  colType: DimensionCols,
  columnIndex: number,
): boolean;
```

---

### `isSamePinnedTopSource`

```ts
export function isSamePinnedTopSource(current: DataType[], next: DataType[]): boolean;
```

---

### `StickyPinnedRow` (Extended from `sticky-cells.pinned.ts`)

```ts
export type StickyPinnedRow = DataType & {
  [STICKY_PINNED_ROW_SOURCE_INDEX]?: number;
  [STICKY_PINNED_ROW_COLUMNS]?: StickyRowCache;
};
```

---

### `isStickyCell`

```ts
export function isStickyCell(model: CellTemplateProp): boolean;
```

---

### `StickyRowCache`

```ts
export type StickyRowCache = Map<DimensionCols, Set<number>>;
```

---

### `StickyCellResolver`

```ts
class StickyCellResolver {
  clear();

  resolveStickyColumns(rowIndex: number): StickyRowCache | null;

  rememberStickyCell(rowIndex: number, colType: DimensionCols, columnIndex: number);
}
```

---

### `captureVerticalScrollAnchor`

Captures the main vertical scroll state before Sticky Cells mutates
`rowPinStart`.

The returned callback must run after the pinned source update. It restores the
user's visual scroll anchor once RevoGrid has had a chance to lay out the new
pinned top height.

```ts
export function captureVerticalScrollAnchor(
  revogrid: HTMLRevoGridElement,
  options: ScrollAnchorOptions = {},
): (() => void) | null;
```

---

### `resolveStickyCellPredicate`

```ts
export function resolveStickyCellPredicate(
  stickyCell: StickyCellPredicate | undefined,
  model: CellTemplateProp,
): boolean;
```

---

# Summary Header

URL: https://pro.rv-grid.com/api/summary-header/
Source: src/content/docs/api/summary-header.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Add summaryVNode property to ColumnRegular interface
       */
      summaryVNode?(h: HyperFunc<VNode>, summary: Record<string, number>): VNode
}
```

## Plugin API

### `SummaryChartHeaderPlugin`

The `SummaryChartHeaderPlugin` is a RevoGrid plugin that enhances the grid's column headers by
allowing custom summary visualizations to be displayed. This plugin leverages a custom property
`summaryVNode` added to the `ColumnRegular` interface, enabling developers to inject summary
charts or visual indicators based on column data summaries.

**Key Features**:
- **Custom Header Augmentation**: Modifies the default column header template to include a summary
  chart or visualization as defined by the `summaryVNode` property in the column configuration.
- **Event-Driven Rendering**: Listens to the `BEFORE_HEADER_RENDER_EVENT` to dynamically wrap and
  modify header templates, ensuring seamless integration with existing grid structures.
- **Summary Calculation**: Provides a mechanism to calculate summary data for each column, allowing
  for flexible and dynamic summary representations based on the grid's row data.
- **Styling Support**: Automatically adds a CSS class for plugin-specific styling, enabling custom
  styles to be applied to headers enhanced by this plugin.

**Usage**:
- Integrate this plugin into a RevoGrid instance's `plugins` array to enable summary chart headers.
- Define `summaryVNode` in column configurations to specify the chart or visualization logic.

### Example
```typescript
import { SummaryChartHeaderPlugin } from '@revolist/revogrid-pro'

const grid = document.createElement('revo-grid');
grid.plugins = [SummaryChartHeaderPlugin];
grid.columns = [
  {
    prop: 'sales',
    name: 'Sales',
    summaryVNode: (h, summary) => h('div', {}, `Total: ${summary['Total'] || 0}`),
  },
];
```

By using the `SummaryChartHeaderPlugin`, developers can enhance their RevoGrid instances with
visually informative headers, improving data insights and user experience within the grid.

```ts
class SummaryChartHeaderPlugin {}
```

---

# Switch

URL: https://pro.rv-grid.com/api/switch/
Source: src/content/docs/api/switch.md

### `Switch`

Shared compact binary control for Pro UI.

```ts
export function Switch({
  checked,
  onChange,
  label,
  ariaLabel,
  className = '',
  disabled = false,
  labelPosition = 'before',
  title,
  testId,
}: SwitchProps): any;
```

---

### `SwitchRenderable`

```ts
export type SwitchRenderable = any;
```

---

### `SwitchProps`

```ts
export type SwitchProps = {
  checked: boolean;
  onChange: (checked: boolean) => void;
  label: SwitchRenderable;
  ariaLabel?: string;
  className?: string;
  disabled?: boolean;
  labelPosition?: 'before' | 'after';
  title?: string;
  testId?: string;
};
```

---

# Tooltip

URL: https://pro.rv-grid.com/api/tooltip/
Source: src/content/docs/api/tooltip.md

## Module Extensions

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  tooltip?: TooltipPluginConfig
}
```

## Plugin API

### `TooltipThemeVariable`

```ts
export type TooltipThemeVariable = `--${string}`;
```

---

### `TooltipPluginConfig`

```ts
interface TooltipPluginConfig {
  /** Enables or disables all tooltip hover behavior. */
    enabled?: boolean;
  /** Delay before showing the tooltip. Defaults to TooltipPlugin.SHOW_DELAY_MS. */
    showDelayMs?: number;
  /** Enables the subtle tooltip entrance/exit animation. */
    animation?: boolean;
  /** Keeps the tooltip attached to the cursor while it is open. Defaults to true. */
    followCursor?: boolean;
  /** Additional CSS custom properties copied from the grid to the portal-mounted tooltip. */
    themeVariables?: readonly TooltipThemeVariable[];
  /** Element that receives the managed tooltip node. Overrides automatic top-layer targeting. */
    appendTo?: HTMLElement
}
```

---

### `TooltipPlugin`

The TooltipPlugin is a RevoGrid plugin that provides interactive tooltip functionality
for grid cells, enhancing user experience by displaying additional information on hover.
This plugin automatically creates and manages tooltips based on element attributes,
allowing for seamless integration and customization.

**Key Features**:
- Dynamic tooltip creation and positioning triggered by mouse events (`mouseover`, `mouseout`, `mousemove`).
- Tooltip content sourced from `data-tooltip` or `title` attributes.
- Customizable tooltip appearance based on `tooltip-type` and `tooltip-position` attributes.
- Optional cursor-following or fixed-position behavior after opening.
- Automatic active dialog/fullscreen mounting keeps tooltips in the browser top layer.
- Body fallback prevents grid and ancestor overflow containers from clipping tooltips.
- Ensures tooltips remain within viewport boundaries, including for grid UI that overflows the grid.

**Usage**:
- Instantiate the TooltipPlugin with a RevoGrid element and required providers.
- Ensure grid elements have `data-tooltip` or `title` attributes set for tooltip content.
- Optionally, use `tooltip-type` for styling variations and `tooltip-position` to specify position ('top', 'bottom', 'left', 'right').

### Example
```typescript
import { TooltipPlugin } from './tooltip-plugin';

const grid = document.createElement('revo-grid');
grid.plugins = [TooltipPlugin];

grid.columns = [
  {
    prop: 'num',
    name: 'Linear',
    cellTemplate: (createElement, props) => {
      return createElement('div', {
        title: 'Number value',
        'data-tooltip': 'This is a number',
        'tooltip-type': 'info',
        'tooltip-position': 'right',
      }, props.index);
    },
  },
];
```

This plugin is ideal for providing additional data insights directly within the grid
interface, offering flexible tooltip management and presentation.

```ts
class TooltipPlugin {
  /**
     * Registers CSS custom properties owned by another plugin for portal theme copying.
     * The returned disposer removes only this registration.
     */
  registerThemeVariables(variables: readonly TooltipThemeVariable[]): () => void;

  /** Show a tooltip for a hit-tested target that has no tooltip DOM node of its own. */
  showForOwner(
    owner: object,
    content: string,
    event: MouseEvent,
    options: { type?: string; position?: string; target?: Element | null } = {},
  ): void;

  /** Hide only when the caller still owns the programmatic tooltip. */
  hideForOwner(owner: object, immediate = false): void;

  destroy(): void;
}
```

---

# Tree

URL: https://pro.rv-grid.com/api/tree/
Source: src/content/docs/api/tree.md

## Module Extensions

### `ColumnRegular` (Extended from `@revolist/revogrid`)

```ts
interface ColumnRegular {
  /**
       * Enables tree template on cells
       */
      tree?: boolean
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  tree?: TreeConfig
}
```

---

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
       * Additional data property tree
       * @deprecated Use `grid.tree` instead.
       *
       * @example
       * ```typescript
       * const grid = document.createElement('revo-grid');
       * grid.additionalData = {
       *   tree: {
       *     idField: 'id',
       *     parentIdField: 'parentId',
       *     rootParentId: null,
       *     expandAll: true,
       *     expandedRowIds: new Set(),
       *   },
       * };
       * ```
       */
      tree?: TreeConfig
}
```

---

### `HTMLRevoGridElementEventMap` (Extended from `global`)

```ts
interface HTMLRevoGridElementEventMap {
  [TREE_ROW_SELECT_EVENT]: TreeRowSelectEvent;
  [TREE_TOGGLE_EVENT]: { rowId: any };
  [TREE_EXPAND_ALL_EVENT]: undefined;
  [TREE_COLLAPSE_ALL_EVENT]: undefined;
  [TREE_STATE_CHANGED_EVENT]: { expandedRowIds: Set<any> };
  [TREE_PROJECTION_APPLIED_EVENT]: { type: DimensionRows; sourceToken?: DataType[] }
}
```

## Plugin API

### `TreeDataPlugin`

The TreeDataPlugin now uses Revogrid's row trimming mechanism without modifying the original data.

All tree metadata (level, expanded, hasChildren, visible) is computed separately and stored in a Map.
The plugin builds a parent→children mapping from the original flat data and then recursively computes,
for each row, its tree level and whether it should be visible based on the expanded/collapsed state
of its ancestors.

The cell template uses a supplied "getMeta" function to look up computed tree metadata for rendering
(indentation and expand/collapse icons) without changing the underlying row.

Usage Example:
```ts
import { TreeDataPlugin } from './tree/index';

const grid = document.createElement('revo-grid');
grid.plugins = [TreeDataPlugin];

grid.columns = [
  {
    prop: 'treeColumn',
    name: 'Hierarchy',
    tree: true,
    cellTemplate: TreeCellTemplate, // or you can let the plugin override it
  },
];
```

#### Dependencies

- **Event integration** `row-order`: Integrates with RowOrderPlugin row order events to reparent tree rows after drag and drop.
- **Event integration** `row-select`: Integrates with RowSelectPlugin row selection events for parent and descendant selection.
- **Event integration** `DimensionAnimationPlugin`: Auto-installs DimensionAnimationPlugin when tree.animation is enabled to animate tree collapse and expand trim changes.

```ts
class TreeDataPlugin {
  /** Whether tree configuration or tree-enabled columns currently activate this plugin. */
  isActive(): boolean;

  /** Active structural properties used by tree-safe editing integrations. */
  getStructuralProps(): ReadonlySet<string>;

  /** Resolve stable node identity and computed hierarchy state for a source row. */
  getNodeContext<T extends DataType = DataType>(
    model: T,
    type: DimensionRows = 'rgRow',
  ): TreeNodeContext<T> | undefined;

  /** Resolve whether a hierarchy mutation is valid without changing source state. */
  getMutationState<T extends DataType = DataType>(
    request: TreeMutationRequest<T>,
  ): TreeMutationState<T>;

  /**
     * Validate and commit one tree hierarchy mutation. Existing moved rows retain
     * object identity; row creation is completed and validated before any write.
     */
  async mutate<T extends DataType = DataType>(
    request: TreeMutationRequest<T>,
  ): Promise<TreeMutationResult<T>>;

  /** Capture stable ID-based hierarchy state for HistoryPlugin replay. */
  getStructureSnapshot(type: DimensionRows = 'rgRow'): TreeStructureSnapshot;

  /** Restore a stable ID-based hierarchy snapshot without replacing row objects. */
  applyStructureSnapshot(snapshot: TreeStructureSnapshot): boolean;

  /**
     * Recomputes the tree metadata for every row in the original data and builds a trimmed map.
     * Call this method after the original data/order/visibility/set changes
     *
     * This method builds a parent→children mapping (without modifying the original data) and then
     * recursively computes for each row:
     *  - its level (indentation),
     *  - whether it is expanded (based on the expandedRowIds set),
     *  - whether it has children,
     *  - and whether it should be visible (i.e. none of its ancestors are collapsed).
     *
     * The trimmed map is then applied via providers.data.setTrimmed().
     */
  async updateTree(type?: DimensionRows, animate = true, sourceToken?: DataType[]);

  /**
     * Toggle the expanded state for a row and then re-calculate tree metadata.
     */
  toggleRowExpanded(row: DataType);

  getExpandedRowIds();

  toggleRowExpandedById(rowId: any);

  expandAll();

  collapseAll();

  /**
     * Gets all descendant row IDs (children, grandchildren, etc.) for a given row
     * @param rowId - The ID of the row to get descendants for
     * @returns Array of physical indices of all descendant rows
     */
  public getAllDescendantPhysicalIndices(rowId: any, type: DimensionRows = 'rgRow'): number[];
}
```

---

### `TreeMeta`

This is the shape of computed tree metadata.
Notice that nothing is stored on the row itself.

```ts
interface TreeMeta {
  level: number;
  expanded: boolean;
  hasChildren: boolean;
  visible: boolean;
  parentId: any
}
```

---

### `TreeConfig`

```ts
interface TreeConfig {
  idField?: string;
  parentIdField?: string;
  rootParentId?: any;
  expandAll?: boolean;
  expandedRowIds?: Set<any>;
  /**
     * Mark tree parent rows as sticky through StickyCellsPlugin.
     *
     * Parent detection uses the row model fields configured by `idField` and
     * `parentIdField`, plus tree metadata computed by TreeDataPlugin. It does not
     * depend on virtual row indexes.
     *
     * This option only adds sticky behavior to tree-enabled columns. Register
     * StickyCellsPlugin separately to render those parent rows in pinned top rows.
     *
     * @default false
     */
    stickyParents?: boolean;
  /**
     * Animate tree collapse and expand through DimensionAnimationPlugin.
     *
     * TreeDataPlugin auto-registers DimensionAnimationPlugin when this option is
     * enabled and the dimension animation plugin is not already registered.
     *
     * @default false
     */
    animation?: boolean
}
```

---

### `TreeRowSelectEvent`

Event emitted when a tree row with children is selected.
This event allows for custom handling of parent-child selection relationships.

```ts
interface TreeRowSelectEvent {
  /** The row type (e.g., 'rgRow') */
    type: DimensionRows;
  /** The physical index of the parent row in the source data */
    parentIndex: number;
  /** Array of physical indices of all descendant rows */
    childrenIndices: number[];
  /** The original row selection event that triggered this tree selection */
    originalEvent?: any
}
```

---

### `TreeSelectionProvider`

Runtime contract exposed by TreeDataPlugin for plugins that need tree
descendant lookup without depending on the TreeDataPlugin class.

```ts
interface TreeSelectionProvider {
  getAllDescendantPhysicalIndices(rowId: unknown, type: DimensionRows): number[]
}
```

---

### `TreeMutationAction`

```ts
export type TreeMutationAction =
  | 'moveUp'
  | 'moveDown'
  | 'indent'
  | 'outdent'
  | 'insertSiblingAbove'
  | 'insertSiblingBelow'
  | 'insertChild'
  | 'duplicate'
  | 'delete';
```

---

### `TreeMutationUnavailableReason`

```ts
export type TreeMutationUnavailableReason =
  | 'inactive'
  | 'invalid-tree'
  | 'invalid-selection'
  | 'mixed-parent'
  | 'missing-factory'
  | 'first-sibling'
  | 'last-sibling'
  | 'no-previous-sibling'
  | 'root-level'
  | 'cancelled';
```

---

### `TreeNodeContext` (Extended from `index.ts`)

```ts
interface TreeNodeContext {
  readonly type: DimensionRows;
  readonly model: T;
  readonly physicalIndex: number;
  readonly id: unknown
}
```

---

### `TreeMutationCreateContext`

```ts
interface TreeMutationCreateContext {
  readonly action: Extract<
      TreeMutationAction,
      'insertSiblingAbove' | 'insertSiblingBelow' | 'insertChild' | 'duplicate'
    >;
  readonly anchorRow: T;
  readonly sourceRow?: T;
  readonly parentRow?: T;
  readonly depth: number
}
```

---

### `TreeMutationRowFactory`

```ts
export type TreeMutationRowFactory<T extends DataType = DataType> = (
  context: TreeMutationCreateContext<T>,
) => T | null | undefined | Promise<T | null | undefined>;
```

---

### `TreeMutationRequest`

```ts
interface TreeMutationRequest {
  readonly action: TreeMutationAction;
  readonly type: DimensionRows;
  readonly models: readonly T[];
  readonly createRow?: TreeMutationRowFactory<T>
}
```

---

### `TreeMutationState`

```ts
interface TreeMutationState {
  readonly available: boolean;
  readonly reason?: TreeMutationUnavailableReason;
  readonly roots: readonly T[]
}
```

---

### `TreeMutationResult` (Extended from `index.ts`)

```ts
interface TreeMutationResult {
  readonly applied: boolean;
  readonly createdRows?: readonly T[];
  readonly deletedRows?: readonly T[]
}
```

---

### `TreeStructureSnapshot`

```ts
interface TreeStructureSnapshot {
  readonly type: DimensionRows;
  readonly orderedRowIds: readonly unknown[];
  readonly parentByRowId: readonly (readonly [unknown, unknown])[];
  readonly expandedRowIds: readonly unknown[]
}
```

---

### `composeTreeCellTemplate`

Compose the structural tree affordance with a replaceable value renderer.
Other plugins may replace the value renderer without removing indentation or
the expand/collapse control.

```ts
export function composeTreeCellTemplate(
  treeTemplate: CellTemplate,
  valueTemplate: CellTemplate,
): CellTemplate;
```

---

### `getTreeCellValueTemplate`

Return the application/value renderer wrapped by a tree template.

```ts
export function getTreeCellValueTemplate(
  template: CellTemplate | undefined,
): CellTemplate | undefined;
```

---

### `replaceTreeCellValueTemplate`

Replace only the value renderer when the supplied template is tree-composed.

```ts
export function replaceTreeCellValueTemplate(
  template: CellTemplate | undefined,
  valueTemplate: CellTemplate,
): CellTemplate;
```

---

### `TREE_CELL_TEMPLATE`

```ts
TREE_CELL_TEMPLATE: typeof TREE_CELL_TEMPLATE;
```

---

### `TreeCellTemplate`

The TreeCellTemplate now receives an extra "getMeta" callback that provides the computed
tree metadata for the given row. It does not assume that any tree information has been stored
on the row itself.

```ts
TreeCellTemplate: (toggleRowExpanded: (data: DataType) => void, getMeta: (row: DataType) => TreeMeta) => CellTemplate<DataType<any, ColumnProp>>;
```

---

### `analyzeTreeMutation`

```ts
export function analyzeTreeMutation<T extends DataType>(
  options: TreeMutationOptions<T>,
): TreeMutationState<T>;
```

---

### `planTreeMutation`

```ts
export async function planTreeMutation<T extends DataType>(
  options: TreeMutationOptions<T>,
): Promise<TreeMutationPlan<T>>;
```

---

### `TreeMutationPlan` (Extended from `index.ts`)

```ts
interface TreeMutationPlan {
  readonly source: readonly T[];
  readonly parentChanges: readonly {
      readonly model: T;
      readonly previousParentId: unknown;
      readonly parentId: unknown;
    }[];
  readonly expandedRowIds: readonly unknown[]
}
```

---

### `TreeAnimationUpdate`

```ts
export type TreeAnimationUpdate = {
  cancelledIndexes: number[];
  reused: boolean;
  version: number;
};
```

---

### `TreeAnimationCoordinator`

```ts
class TreeAnimationCoordinator {
  beginUpdate({
    type,
    nextTrimmed,
    source,
    proxyItems,
  }: BeginTreeAnimationUpdateOptions): TreeAnimationUpdate;

  reset(type: DimensionRows): number[];

  isCurrent(type: DimensionRows, version: number): boolean;

  canAnimate(type: DimensionRows, dimensionAnimation?: DimensionAnimationPlugin): dimensionAnimation is DimensionAnimationPlugin;

  markInitialized(type: DimensionRows, sourceLength: number);

  hasTrimChanges(
    currentTrimmed: Record<number, boolean>,
    nextTrimmed: Record<number, boolean>,
  ): boolean;

  async applyAnimatedTrim({
    applyTrim,
    currentTrimmed,
    dimensionAnimation,
    nextTrimmed,
    proxyItems,
    source,
    type,
    version,
  }: {
    applyTrim: (trimmed: Record<number, boolean>) => void;
    currentTrimmed: Record<number, boolean>;
    dimensionAnimation: DimensionAnimationPlugin;
    nextTrimmed: Record<number, boolean>;
    proxyItems: number[];
    source: DataType[];
    type: DimensionRows;
    version: number;
  }): Promise<boolean>;
}
```

---

### `resolveTreeFilterTypes`

```ts
export function resolveTreeFilterTypes(detail: TreeFilterEventDetail): string[];
```

---

### `resolveTreeFilterTrim`

Keeps complete hierarchy context around rows that match an active filter.

The filter plugin marks non-matching physical row indexes as trimmed.
Positive filtering closes the matching set in both directions: ancestors
remain as the path to a deep match, and descendants remain as the branch
owned by a matching parent. Exclusion-only filters instead prune complete
subtrees rooted at excluded rows. Unrelated branches keep the filter
plugin's trim decisions.

```ts
export function resolveTreeFilterTrim({
  filterTrimmed,
  filterTypes,
  idField,
  parentIdField,
  rootParentId,
  source,
}: TreeFilterTrimOptions): TrimmedEntity;
```

---

### `TreeFilterTrimOptions`

```ts
export type TreeFilterTrimOptions = {
  filterTrimmed: TrimmedEntity;
  filterTypes?: readonly string[];
  idField: string;
  parentIdField: string;
  rootParentId: any;
  source: DataType[];
};
```

---

### `TreeFilterEventDetail`

```ts
interface TreeFilterEventDetail {
  collection?: Record<string, { type?: string }>;
  filterItems?: Record<string, Array<{ type?: string }>>
}
```

---

### `TreeRowOrderController`

```ts
class TreeRowOrderController {
  isParentUpdatePending(type: DimensionRows): boolean;

  handleDragEnd();

  handleDropValidation(context: RowOrderDropValidationContext): TreeDropValidation;

  handleRowDrop(e: CustomEvent<RowOrderChange>);

  highlightDropTarget(context: RowOrderDropStateChange);

  clearDropTarget();
}
```

---

### `isTreeRowType`

```ts
export function isTreeRowType(type: unknown): type is DimensionRows;
```

---

### `buildTreeChildIndex`

```ts
export function buildTreeChildIndex({
  idField,
  parentIdField,
  rootParentId,
  source,
}: {
  idField: string;
  parentIdField: string;
  rootParentId: any;
  source: DataType[];
}): TreeChildIndex;
```

---

### `collectDescendantPhysicalIndices`

```ts
export function collectDescendantPhysicalIndices(
  childrenByParent: TreeChildIndex,
  rowId: any,
): number[];
```

---

### `resolveTreeTrimState`

```ts
export function resolveTreeTrimState(
  allTrimmed: Record<string, Record<number, boolean>> = {},
): TreeTrimState;
```

---

### `computeTreeState`

```ts
export function computeTreeState({
  expandedRowIds,
  idField,
  items,
  outsideTrimmed,
  parentIdField,
  rootParentId,
  source,
}: {
  expandedRowIds: Set<any>;
  idField: string;
  items: number[];
  outsideTrimmed: TrimmedEntity;
  parentIdField: string;
  rootParentId: any;
  source: DataType[];
}): TreeState;
```

---

### `collectExpandableRowIds`

```ts
export function collectExpandableRowIds({
  idField,
  parentIdField,
  rootParentId,
  source,
}: {
  idField: string;
  parentIdField: string;
  rootParentId: any;
  source: DataType[];
}): Set<any>;
```

---

### `TRIMMED_COLLAPSED`

```ts
TRIMMED_COLLAPSED: string;
```

---

### `TREE_ROW_TYPES`

```ts
TREE_ROW_TYPES: DimensionRows[];
```

---

### `TreeState`

```ts
export type TreeState = {
  itemParentOrder: number[];
  metaData: Map<any, TreeMeta>;
  rowMetaEntries: Array<[DataType, TreeMeta]>;
  trimmed: Record<number, boolean>;
};
```

---

### `TreeChildIndex`

```ts
export type TreeChildIndex = Map<any, Array<{
  id: any;
  physicalIndex: number;
}>>;
```

---

### `TreeTrimState`

```ts
export type TreeTrimState = {
  currentTreeTrimmed: Record<number, boolean>;
  outsideTrimmed: TrimmedEntity;
};
```

---

### `TreeRuntimeState`

```ts
class TreeRuntimeState {
  setConfig(options: TreeConfig = {});

  snapshotExpandedRowIds(): Set<any>;

  toggleExpanded(rowId: any);

  setExpandedRowIds(expandedRowIds: Set<any>);

  clearExpandedRowIds();

  setExpandAllPending(pending: boolean);
}
```

---

### `isNoopTreeDrop`

```ts
export function isNoopTreeDrop({
  dropPosition,
  from,
  itemCount,
  targetIndex,
  targetRow,
  visibleRowIndexes,
}: {
  dropPosition?: RowOrderDropValidationContext['dropPosition'];
  from: number;
  itemCount: number;
  targetIndex: number;
  targetRow?: number;
  visibleRowIndexes?: number[];
}): boolean;
```

---

### `resolveTreeDropParentId`

```ts
export function resolveTreeDropParentId({
  dropPosition,
  expandedRowIds,
  from,
  idField,
  itemCount,
  parentIdField,
  rootParentId,
  store,
  targetIndex,
  targetRow,
  visibleRowIndexes,
}: {
  dropPosition?: RowOrderDropValidationContext['dropPosition'];
  expandedRowIds: Set<unknown>;
  from: number;
  idField: string;
  itemCount?: number;
  parentIdField: string;
  rootParentId: unknown;
  store: DataStore<DataType, DimensionRows>['store'];
  targetIndex: number;
  targetRow?: number;
  visibleRowIndexes?: number[];
}): unknown;
```

---

### `validateTreeRowDrop`

```ts
export function validateTreeRowDrop({
  context,
  idField,
  metaData,
  newParentId,
  rootParentId,
}: {
  context: RowOrderDropValidationContext;
  idField: string;
  metaData: Map<unknown, { parentId?: unknown }>;
  newParentId: unknown;
  rootParentId: unknown;
}): RowOrderDropValidationResult;
```

---

### `resolveTreeDropValidation`

```ts
export function resolveTreeDropValidation({
  context,
  expandedRowIds,
  idField,
  metaData,
  parentIdField,
  rootParentId,
  store,
}: {
  context: RowOrderDropValidationContext;
  expandedRowIds: Set<unknown>;
  idField: string;
  metaData: Map<unknown, { parentId?: unknown }>;
  parentIdField: string;
  rootParentId: unknown;
  store: DataStore<DataType, DimensionRows>['store'];
}): {
  newParentId: unknown;
  result: RowOrderDropValidationResult;
} | null;
```

---

### `moveProxySubtreesAfterTarget`

```ts
export function moveProxySubtreesAfterTarget({
  idField,
  movedPhysicalIndexes,
  parentIdField,
  proxyItems,
  source,
  targetPhysicalIndex,
}: {
  idField: string;
  movedPhysicalIndexes: number[];
  parentIdField: string;
  proxyItems: number[];
  source: DataType[];
  targetPhysicalIndex: number;
}): number[];
```

---

### `moveProxySubtreesToTarget`

```ts
export function moveProxySubtreesToTarget({
  idField,
  insert,
  movedPhysicalIndexes,
  parentIdField,
  proxyItems,
  source,
  targetPhysicalIndex,
}: {
  idField: string;
  insert: 'before' | 'after' | 'after-subtree';
  movedPhysicalIndexes: number[];
  parentIdField: string;
  proxyItems: number[];
  source: DataType[];
  targetPhysicalIndex: number;
}): number[];
```

---

### `applyTreeStickyParentColumns`

```ts
export function applyTreeStickyParentColumns(
  columnsByType: ColumnCollection['columns'],
  resolveStickyCell: (model: CellTemplateProp, stickyCell: StickyCellPredicate | undefined) => boolean,
);
```

---

### `resolveTreeStickyCell`

```ts
export function resolveTreeStickyCell(
  model: CellTemplateProp,
  stickyCell: StickyCellPredicate | undefined,
  context: TreeStickyCellContext,
): boolean;
```

---

### `getStickyTreeConfig`

```ts
export function getStickyTreeConfig(revogrid: HTMLRevoGridElement): TreeConfig | undefined;
```

---

### `resolveActiveTreeStickyRows`

```ts
export function resolveActiveTreeStickyRows({
  rowIndex,
  maxRows,
  config,
  includeRow = true,
  rowStore,
  resolveStickyColumns,
}: ActiveTreeStickyRowsContext): number[];
```

---

### `TreeStickyCellContext`

```ts
interface TreeStickyCellContext {
  config: TreeConfig | undefined;
  getMeta(row: DataType): TreeMeta
}
```

---

### `ActiveTreeStickyRowsContext`

```ts
interface ActiveTreeStickyRowsContext {
  rowIndex: number;
  maxRows: number;
  config: TreeConfig;
  includeRow?: boolean;
  rowStore: {
      get(key: 'source'): DataType[];
      get(key: 'items'): number[];
    };
  resolveStickyColumns(rowIndex: number): boolean
}
```

---

# Value Selection Dialog

URL: https://pro.rv-grid.com/api/value-selection-dialog/
Source: src/content/docs/api/value-selection-dialog.md

### `ValueSelectionDialogPlugin`

#### Dependencies

- **Auto-installed** `DialogPlugin`: Uses the shared Pro dialog runtime for searchable value selection.

```ts
class ValueSelectionDialogPlugin {
  open<T = ValueSelectionDialogValue>(
    options: ValueSelectionDialogOpenOptions<T>,
  ): void;

  close(): void;
}
```

---

### `createValueSelectionDialogEditor`

```ts
export function createValueSelectionDialogEditor<T>({
  document,
  localeText,
  initialSelection,
  getKey,
  getLabel,
  itemTemplate,
  onSearch,
}: ValueSelectionDialogEditorOptions<T>): ValueSelectionDialogEditor<T>;
```

---

### `formatValueSelectionText`

```ts
export function formatValueSelectionText(
  template: string,
  values: Record<string, string | number>,
): string;
```

---

### `ValueSelectionDialogEditor`

```ts
interface ValueSelectionDialogEditor {
  readonly element: HTMLElement;
  readonly searchInput: HTMLInputElement;
  setValues(values: readonly T[], totalCount: number): void;
  setLoading(): void;
  setError(message: string): void;
  getSelection(): ValueSelectionDialogSelection<T>;
  destroy(): void
}
```

---

### `ValueSelectionDialogValue`

```ts
export type ValueSelectionDialogValue =
  string | number | boolean | null;
```

---

### `ValueSelectionDialogSelection`

```ts
interface ValueSelectionDialogSelection {
  readonly mode: 'include' | 'exclude';
  readonly values: readonly T[]
}
```

---

### `ValueSelectionDialogPage`

```ts
interface ValueSelectionDialogPage {
  readonly values: readonly T[];
  readonly totalCount: number
}
```

---

### `ValueSelectionDialogLoadContext`

```ts
interface ValueSelectionDialogLoadContext {
  readonly search: string;
  readonly signal: AbortSignal
}
```

---

### `ValueSelectionDialogItemTemplateContext`

```ts
interface ValueSelectionDialogItemTemplateContext {
  readonly value: T;
  readonly label: string
}
```

---

### `ValueSelectionDialogItemTemplate`

```ts
export type ValueSelectionDialogItemTemplate<
  T = ValueSelectionDialogValue,
> = (
  createElement: HyperFunc<VNode>,
  context: ValueSelectionDialogItemTemplateContext<T>,
) => unknown;
```

---

### `ValueSelectionDialogLocaleText`

```ts
interface ValueSelectionDialogLocaleText {
  readonly description: string;
  readonly searchPlaceholder: string;
  readonly selectAllVisible: string;
  readonly valuesLabel: string;
  readonly resultCount: string;
  readonly selectedCount: string;
  readonly loading: string;
  readonly empty: string;
  readonly loadError: string;
  readonly clear: string;
  readonly cancel: string;
  readonly apply: string
}
```

---

### `ValueSelectionDialogOpenOptions`

```ts
interface ValueSelectionDialogOpenOptions {
  readonly title: string;
  readonly closeLabel: string;
  readonly localeText: ValueSelectionDialogLocaleText;
  readonly initialSelection: ValueSelectionDialogSelection<T>;
  readonly loadValues: (
      context: ValueSelectionDialogLoadContext,
    ) => Promise<ValueSelectionDialogPage<T>> | ValueSelectionDialogPage<T>;
  readonly getKey: (value: T) => string;
  readonly getLabel: (value: T) => string;
  /** Optional rich content for each value; labels remain the text fallback. */
    readonly itemTemplate?: ValueSelectionDialogItemTemplate<T>;
  readonly searchDebounceMs?: number;
  readonly onApply: (selection: ValueSelectionDialogSelection<T>) => void;
  readonly onClear: () => void
}
```

---

# View Fields

URL: https://pro.rv-grid.com/api/view-fields/
Source: src/content/docs/api/view-fields.md

### `ViewFieldMap`

Shared semantic field names used by data-backed Pro views.

```ts
interface ViewFieldMap {
  readonly id?: ColumnProp;
  readonly title?: ColumnProp;
  readonly status?: ColumnProp;
  readonly start?: ColumnProp;
  readonly end?: ColumnProp;
  readonly color?: ColumnProp;
  readonly progress?: ColumnProp;
  readonly resourceId?: ColumnProp
}
```

---

# WCAG

URL: https://pro.rv-grid.com/api/wcag/
Source: src/content/docs/api/wcag.mdx

### `WCAGPlugin`

WCAG Plugin is responsible for enhancing the accessibility features of the RevoGrid component.
It ensures that the grid is fully compliant with Web Content Accessibility Guidelines (WCAG) 2.1.
This plugin should be the last plugin you add, as it modifies the grid's default behavior.

The WCAG Plugin performs the following tasks:
- Sets the 'dir' attribute to 'ltr' for left-to-right text direction.
- Sets the 'role' attribute to 'treegrid' for treelike hierarchical structure.
- Sets the 'aria-keyshortcuts' attribute to 'Enter' and 'Esc' for keyboard shortcuts.
- Adds event listeners for keyboard navigation and editing.
- Creates an optional `aria-live` region for saved edit and validation rejection announcements.

By default, the plugin adds ARIA roles and properties to the grid elements, providing semantic information
for assistive technologies. These roles include 'grid', 'row', and 'gridcell'. The plugin also sets
ARIA attributes such as 'aria-rowindex', 'aria-colindex', and 'aria-selected'.

The WCAG Plugin ensures that the grid is fully functional and usable for users with various disabilities,
including visual impairments, deaf-blindness, and cognitive disabilities.

Note: The WCAG Plugin should be added as the last plugin in the list of plugins, as it modifies the grid's
default behavior and may conflict with other plugins if added earlier.

#### Dependencies

- **Ordering** `after other-grid-plugins`: Register this plugin last because it modifies grid accessibility props after other plugins.

```ts
import { WCAGPlugin, type WCAGConfig } from '@revolist/revogrid-pro';

const wcag: WCAGConfig = {
  announcements: {
    live: 'polite',
    labels: {
      edit: context =>
        'prop' in context
          ? `Saved ${context.columnName} on row ${context.rowNumber}: ${context.value}`
          : `Saved ${context.cellCount} cells`,
      error: context =>
        'prop' in context
          ? `${context.columnName} on row ${context.rowNumber} was not updated`
          : `${context.cellCount} cells were not updated`,
    },
  },
};

const grid = document.createElement('revo-grid');
grid.plugins = [WCAGPlugin];
grid.wcag = wcag;
```

#### Configuration

`grid.wcag` is the preferred configuration API. `additionalData.wcag` is still supported for framework integrations that pass plugin options through a shared `additionalData` object.

```ts
grid.wcag = {
  announcements: {
    enabled: true,
    edit: true,
    error: true,
    live: 'polite',
    atomic: true,
    liveRegionClassName: 'rv-wcag-live-region',
  },
};
```

Set `announcements: false` to disable the live region.