Row Order

Module Extensions

HTMLRevoGridElement (Extended from @revolist/revogrid)

interface HTMLRevoGridElement {
  /**
       * Direct row-order configuration.
       */
      rowOrder?: RowOrderPluginConfig
}

---

AdditionalData (Extended from @revolist/revogrid)

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
}

---

ColumnRegular (Extended from @revolist/revogrid)

interface ColumnRegular {
  /**
       * Column prop, used for drag and drop text information
       */
      rowDrag?: RowDrag<TModel>
}

---

HTMLRevoGridElementEventMap (Extended from global)

interface HTMLRevoGridElementEventMap {
  [ORDER_CHANGED_EVENT]: RowOrderChange;
  [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.
• Cell Flash Integration: When CellFlashPlugin is installed, successfully moved rows flash at their new visible positions after the reorder is committed.
• 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

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.

class RowOrderPlugin {
  /**
     * Drop trigger event
     */
  onMouseOut(_: MouseEvent): void;

  /**
     * Final event
     */
  onMouseUp(e: MouseEvent): void;

  /**
     * Initial event when drag begins
     */
  dragStart(;

  /**
     * Initial row move
     */
  move(e: MouseEvent);

  clearOrder(): void;

  /**
     * Start grid reordering
     */
  orderStart(e: MouseEvent): void;

  /**
     * Clearing local subscription
     */
  clearSubscriptions();

  clearHighlight();
}

---

RowOrderChangedDetail

export type RowOrderChangedDetail = {
  from: number;
  targetRow?: number;
  to: number;
  type: DimensionRows;
};

---

RowDragStartEvent (Extended from index.ts)

interface RowDragStartEvent {
  model: CellTemplateProp
}

---

RowOrderDropValidationResult

export type RowOrderDropValidationResult =
  | { valid: true; warning?: string }
  | { valid: false; reason?: string };

---

RowOrderPreviewContext

export type RowOrderPreviewContext = {
  dataItem: CellTemplateProp;
  firstItem?: DataType;
  itemCount: number;
  items: DataType[];
  prop?: ColumnProp;
  type: DimensionRows;
};

---

RowOrderPreviewContent

export type RowOrderPreviewContent = string | number | HTMLElement | undefined;

---

RowOrderPreviewRenderer

export type RowOrderPreviewRenderer = (
  context: RowOrderPreviewContext,
) => RowOrderPreviewContent;

---

RowOrderDropValidationContext

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)

export type RowOrderDropValidationEvent = RowOrderDropValidationContext & {
  result: RowOrderDropValidationResult;
};

---

RowOrderDropStateChange (Extended from index.ts)

export type RowOrderDropStateChange = RowOrderDropValidationContext & {
  previous?: RowOrderDropValidationResult;
  result: RowOrderDropValidationResult;
};

---

RowOrderDropPosition

export type RowOrderDropPosition = 'before' | 'inside' | 'after';

---

RowOrderPluginConfig

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
}

---

RowOrderServiceConfig

interface RowOrderServiceConfig {
  dimension: PluginProviders['dimension'];
  orderStart(e: MouseEvent): void;
  positionChanged(e: MouseEvent, detail: RowOrderChangedDetail): void
}

---

DragEventsData (Extended from index.ts)

interface DragEventsData {
  text?: string | number
}

---

RowOrderChange (Extended from index.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[]
}

---

LocalSubscription

export type LocalSubscription = {
  target: Element | Document;
  callback(...params: any[]): void;
};

---

StaticData

export type StaticData = {
  dataItem: CellTemplateProp;
  dataEl: HTMLElement;
  scrollEl: Element;
  gridEl: HTMLElement;
  items: Map<number, DataType>;
};

---

draggableRender

export function draggableRender(
  h: HyperFunc<VNode>,
  data: DragEventsData,
  _?: any
);

---

OrderHandler

class OrderHandler {
  renderAutoscroll(_: MouseEvent, parent: HTMLElement | null): void;

  autoscroll(y: number, dataContainerHeight: number): void;

  start(
    e: MouseEvent,;

  stop(): void;

  moveTip(;

  showHandler(y: number, gridHeight: number): void;

  setValidation(validation: RowOrderDropValidationResult): void;

  render(h: HyperFunc<VNode>, pluginId: string);
}

---

getTopRelative

Get coordinate relative to the grid

export function getTopRelative(
  absoluteY: number,;

---

getRow

Calculate cell based on x, y position

export function getRow(y: number, e: EventData): PositionItem;

---

getCell

Calculate cell based on x, y position

export function getCell(;

---

EventData

export type EventData = {
  el: HTMLElement;
  elScroll: Element;
  elRect: DOMRect;
  gridRect: DOMRect;
  yOffset: number;
  dataItem: DragEventsData;
  type: DimensionRows;
  rows: DimensionSettingsState;
  cols: DimensionSettingsState;
};

---

default

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;
}

---

resolveRowDrag

export function resolveRowDrag(
  rowDrag: RowDrag | undefined,
  model: CellTemplateProp,
): boolean;

---

normalizeDropRow

export function normalizeDropRow(from: number, hoverRow: number): number;

---

getTargetIndex

export function getTargetIndex(
  from: number,
  to: number,
  itemCount: number,
): number;

---

isNoopDrop

export function isNoopDrop(
  range: RowOrderRange,
  targetIndex: number,
  rowIndexes?: RowOrderVisibleRowIndex[],
): boolean;

---

normalizeRowOrderIndexes

export function normalizeRowOrderIndexes(
  rowIndexes: RowOrderVisibleRowIndex[],
  itemCount: number,
): RowOrderVisibleRowIndex[];

---

rangeToRowOrderIndexes

export function rangeToRowOrderIndexes(
  range: RowOrderRange,
): RowOrderVisibleRowIndex[];

---

getRowOrderSelectionRange

export function getRowOrderSelectionRange(
  rowIndexes: RowOrderVisibleRowIndex[],
): RowOrderRange;

---

getRowOrderTargetIndex

export function getRowOrderTargetIndex(;

---

resolveRowOrderEditColumn

export function resolveRowOrderEditColumn(
  columns: ColumnRegular[],
  prop: ColumnProp,
): RowOrderEditColumnResolution;

---

buildRowOrderMutation

export function buildRowOrderMutation(;

---

normalizeValidationResult

export function normalizeValidationResult(
  result: RowOrderDropValidationResult | boolean | void,
): RowOrderDropValidationResult;

---

buildPreviewContext

export function buildPreviewContext(;

---

resolvePreviewContent

export function resolvePreviewContent(;

---

buildDropValidationContext

export function buildDropValidationContext(;

---

getRowDimensionState

export function getRowDimensionState(
  stores: RowDimensionStateStores,
  type: DimensionRows,
): DimensionSettingsState;

---

resolveGroupedDrop

export function resolveGroupedDrop(;

---

RowOrderRange

export type RowOrderRange = {
  from: number;
  to: number;
};

---

RowOrderVisibleRowIndex

export type RowOrderVisibleRowIndex = number;

---

RowOrderMutation

export type RowOrderMutation = {
  targetIndex: number;
  itemsOrder: number[];
  prevItems: number[];
  proxyItems: number[];
};

---

RowDimensionStateStores

export type RowDimensionStateStores = Record<DimensionRows, {
  getCurrentState(): DimensionSettingsState;
}>;

---

GroupedDropEdit

export type GroupedDropEdit = {
  physicalIndex: number;
  prop: ColumnProp;
  value: unknown;
};

---

GroupedDropResolution

export type GroupedDropResolution =
  | { valid: true; edits: GroupedDropEdit[]; targetValues?: Record<string, unknown> }
  | { valid: false; reason: string };

---

GroupedDropOptions

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

export type RowOrderEditColumnResolution = {
  column: ColumnRegular;
  index: number;
};