# Grid Preset
URL: https://pro.rv-grid.com/api/grid-preset/
Source: src/content/docs/api/grid-preset.md
## Plugin API

### `GridPresetPlugin`

Aggregate Pro plugin that installs a named set of existing Pro plugins and
applies only missing default grid props for that preset.

`GridPresetPlugin` does not replace the individual plugin APIs. Runtime
configuration stays on the normal direct grid properties:

- `grid.tree`
- `grid.rowOrder`
- `grid.rowContextMenu`
- `grid.columnContextMenu`
- `grid.masterRow`
- `grid.stretch`
- `grid.columnTypes`

```ts
import { GridPresetPlugin } from '@revolist/revogrid-presets';

const grid = document.createElement('revo-grid');
grid.plugins = [GridPresetPlugin];
grid.gridPreset = 'project-pipeline';
```

### `GridPresetName`

```ts
export type GridPresetName =
  | 'common-column-types'
  | 'project-pipeline'
  | 'operations'
  | 'tree';
```

- `common-column-types` registers reusable column type keys for date, number,
  select, dropdown, progress, rating, selection, multi-value, and common editor
  cells, plus project-oriented visual cells such as avatars, badges, change
  indicators, progress lines, sparklines, and heatmaps.
- `project-pipeline` combines event management, tree rows, row drag and drop, row selection,
  master rows, overlays, row headers, context menus, column stretch, cell focus
  verification, dimension animation, advanced filtering, filter headers, column
  hiding, tooltips, and column add popup. It installs tree capability, but
  hierarchy remains opt-in through `grid.tree`.
- `operations` combines event management, selection, row headers, row and column context menus,
  column stretch, odd row styling, column hiding, and tooltips.
- `tree` combines event management, tree rows, row drag and drop, row selection, row headers,
  context menus, column stretch, and dimension animation.

### `GridPresetConfig`

```ts
export type GridPresetConfig =
  | GridPresetName
  | readonly GridPresetName[]
  | {
      preset: GridPresetName | readonly GridPresetName[];
      plugins?: GridPresetPluginOverrides;
      conflictPolicy?: 'warn' | 'silent';
      contextMenus?: GridPresetContextMenuOverrides;
    }
  | {
      presets: readonly GridPresetName[];
      plugins?: GridPresetPluginOverrides;
      conflictPolicy?: 'warn' | 'silent';
      contextMenus?: GridPresetContextMenuOverrides;
    }
  | {
      plugins: GridPresetPluginOverrides;
      conflictPolicy?: 'warn' | 'silent';
      contextMenus?: GridPresetContextMenuOverrides;
    };
```

Use a string for the common case:

```ts
grid.gridPreset = 'project-pipeline';
```

Merge presets by passing an array. Presets are merged in order, duplicate plugin
classes are skipped, and later preset defaults override earlier preset defaults
before user direct props are considered.

```ts
grid.gridPreset = ['common-column-types', 'project-pipeline'];
```

Use the object form for plugin list overrides or warning policy:

```ts
grid.gridPreset = {
  presets: ['tree', 'operations'],
  conflictPolicy: 'warn',
  plugins: {
    prepend: [MyAuditPlugin],
    append: [MyStatusPlugin],
    remove: ['TooltipPlugin'],
  },
};
```

Omit `preset`/`presets` to use `GridPresetPlugin` as a reusable custom plugin
pack installer without applying any built-in preset defaults:

```ts
grid.gridPreset = {
  plugins: {
    append: [MyStatusPlugin, MyAuditPlugin],
  },
};
```

### `GridPresetContextMenuOverrides`

`operations` ships default row and column menus. Direct
`grid.rowContextMenu` / `grid.columnContextMenu` still replace those defaults.
Use `contextMenus` in object preset config when you want preset-owned menus that
extend or replace defaults without setting separate direct menu props.

```ts
grid.gridPreset = {
  preset: 'operations',
  contextMenus: {
    row: {
      mode: 'extend',
      items: [{ name: 'Copy row' }],
    },
    column: {
      mode: 'extend',
      items: [{ name: 'Audit column' }],
    },
  },
};
```

```ts
export interface GridPresetContextMenuOverrides {
  row?: 'replace' | 'extend' | (Partial<ContextMenuConfig> & { mode?: 'replace' | 'extend' });
  column?: 'replace' | 'extend' | (Partial<ContextMenuConfig> & { mode?: 'replace' | 'extend' });
}
```

### `GridPresetPluginOverrides`

```ts
export interface GridPresetPluginOverrides {
  prepend?: readonly GridPlugin[];
  append?: readonly GridPlugin[];
  remove?: readonly (GridPlugin | string)[];
}
```

- `prepend` installs plugin classes before the preset defaults.
- `append` installs plugin classes after the preset defaults.
- `remove` removes matching classes or class names from the final preset list.
- Duplicate plugin classes are skipped.
- Already installed plugin classes are skipped through `providers.plugins.getByClass()`.

## Module Extensions

### `HTMLRevoGridElement`

```ts
interface HTMLRevoGridElement {
  /** Aggregate Pro preset selected by GridPresetPlugin. */
  gridPreset?: GridPresetConfig;
  /** Kebab-case alias for framework/native custom element bindings. */
  'grid-preset'?: GridPresetConfig;
}
```

### `AdditionalData`

```ts
interface AdditionalData {
  /**
   * Aggregate Pro preset selected by GridPresetPlugin.
   *
   * @deprecated Use the direct grid.gridPreset property instead.
   */
  gridPreset?: GridPresetConfig;
}
```

## Defaults

Defaults are applied only when the corresponding direct prop and legacy
`additionalData` key are missing. User-provided direct props always win.

```ts
grid.gridPreset = 'tree';
grid.tree = { idField: 'taskId', parentIdField: 'parentTaskId', rootParentId: null };
```

Because `grid.tree` exists, the preset will not overwrite it.

The `operations` preset applies these missing menu defaults:

- Row menu: `Add new row before`, `Add new row after`, `Delete row`.
- Column menu: sort ascending/descending, clear sorting, open/clear filtering,
  group by column, clear grouping, hide column, pin left/right, and unpin for
  pinned columns. Sort/filter entries are capability-aware.
- Grouped column header menu: clear sorting/filtering, group by group columns,
  clear grouping, hide the whole group, pin the group left/right, and unpin
  pinned groups.

### `COMMON_COLUMN_TYPE_KEYS`

```ts
export const COMMON_COLUMN_TYPE_KEYS = [
  'date',
  'number',
  'integer',
  'percent',
  'currency',
  'select',
  'dropdown',
  'progress',
  'rating',
  'rowSelect',
  'multi',
  'checkbox',
  'counter',
  'slider',
  'timeline',
  'textarea',
  'link',
  'avatar',
  'avatarText',
  'badge',
  'thumbs',
  'change',
  'progressLine',
  'progressLineValue',
  'circularProgress',
  'timelineRange',
  'sparkline',
  'heatmap',
] as const;
```

### `createCommonColumnTypes`

```ts
import { createCommonColumnTypes, GridPresetPlugin } from '@revolist/revogrid-presets';

grid.plugins = [GridPresetPlugin];
grid.gridPreset = 'project-pipeline';
grid.columnTypes = {
  ...createCommonColumnTypes(),
  customStatus: { readonly: true },
};
```

Project and operations grids can use the visual keys without importing the
renderers directly:

```ts
grid.plugins = [GridPresetPlugin];
grid.gridPreset = 'common-column-types';
grid.columns = [
  { prop: 'owner', columnType: 'avatarText' },
  {
    prop: 'status',
    columnType: 'badge',
    badgeStyles: {
      Blocked: { backgroundColor: '#fee2e2', color: '#991b1b' },
    },
  },
  { prop: 'progress', columnType: 'progressLine' },
];
```

## Verification Commands

```sh
pnpm docs:api
pnpm --filter @revolist/revogrid-presets test:ssr-import
pnpm --filter @revolist/revogrid-presets test
pnpm --filter @revolist/revogrid-presets lint
pnpm --filter @revolist/revogrid-presets build
pnpm --filter @revolist/revogrid-portal build
```
