Smart Panel

Module Extensions

HTMLRevoGridElement (Extended from global)

interface HTMLRevoGridElement {
  smartPanel?: SmartPanelConfig | boolean;
  'smart-panel'?: SmartPanelConfig | boolean
}

---

HTMLRevoGridElementEventMap (Extended from global)

interface HTMLRevoGridElementEventMap {
  smartpanelchange: SmartPanelChangeDetail;
  smartpanelerror: SmartPanelErrorDetail
}

---

AdditionalData (Extended from @revolist/revogrid)

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.

class SmartPanelComponent {
  setHost(host: HTMLElement);

  setConfig(config: NormalizedSmartPanelConfig<T>);

  getHost();

  render(items: SmartPanelResolvedItem<T>[]);

  destroy(clear = true);
}

---

normalizeSmartPanelConfig

export function normalizeSmartPanelConfig<T extends DataType = DataType>(
  config?: SmartPanelConfig<T> | boolean,
): NormalizedSmartPanelConfig<T>;

---

defaultSmartPanelItems

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.

class SmartPanelPlugin {
  getSnapshot();

  getItems();

  getComponent();

  setHost(host: HTMLElement | null);

  async refresh();

  destroy();
}

---

resolveSmartPanelItems

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

export function evaluateValuesFormula(formula: string, values: unknown[]);

---

resolveMetric

export function resolveMetric<T extends DataType>(metric: SmartPanelMetric, snapshot: SmartPanelSnapshot<T>);

---

createSmartPanelSnapshot

export function createSmartPanelSnapshot<T extends DataType = DataType>(
  providers: PluginProviders,
  revision = Date.now(),
): SmartPanelSnapshot<T>;

---

getSelectedRanges

export function getSelectedRanges(providers: PluginProviders): SmartPanelRange[];

---

SmartPanelAlignment

export type SmartPanelAlignment = 'left' | 'center' | 'right';

---

SmartPanelValueScope

export type SmartPanelValueScope = 'selection' | 'visibleRows' | 'allRows';

---

SmartPanelMetric

export type SmartPanelMetric =
  | 'selectedCells'
  | 'selectedRows'
  | 'visibleSelectedRows'
  | 'selectedColumns'
  | 'visibleRows'
  | 'totalRows'
  | 'hiddenRows'
  | 'visibleNodes'
  | 'totalNodes'
  | 'focusedCell'
  | 'focusedColumn'
  | 'rangeAddress'
  | 'numericCount'
  | 'sum'
  | 'average'
  | 'min'
  | 'max'
  | 'distinct';

---

SmartPanelRange

interface SmartPanelRange {
  rowType: DimensionRows;
  colType: DimensionCols;
  range: RangeArea
}

---

SmartPanelCell

interface SmartPanelCell {
  model: T;
  column: ColumnRegular;
  rowType: DimensionRows;
  colType: DimensionCols;
  rowIndex: number;
  columnIndex: number;
  value: unknown;
  rawValue: unknown
}

---

SmartPanelFocus

interface SmartPanelFocus {
  model: T;
  column: ColumnRegular;
  rowType: DimensionRows;
  colType: DimensionCols;
  rowIndex: number;
  columnIndex: number;
  address: string;
  value: unknown;
  rawValue: unknown
}

---

SmartPanelSnapshot

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

interface SmartPanelContext {
  grid: HTMLRevoGridElement;
  providers: PluginProviders;
  snapshot: SmartPanelSnapshot<T>;
  item: SmartPanelItem<T>;
  values: unknown[]
}

---

SmartPanelItemValue

export type SmartPanelItemValue<T extends DataType = DataType> =
  | SmartPanelMetric
  | ((context: SmartPanelContext<T>) => unknown | Promise<unknown>);

---

SmartPanelItem

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

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

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)

interface NormalizedSmartPanelConfig {
  items: SmartPanelItem<T>[];
  ariaLabel: string;
  hiddenWhenEmpty: boolean;
  numberFormat: Intl.NumberFormatOptions;
  schedule: 'microtask' | 'animationFrame'
}

---

SmartPanelChangeDetail

interface SmartPanelChangeDetail {
  snapshot: SmartPanelSnapshot<T>;
  items: SmartPanelResolvedItem<T>[]
}

---

SmartPanelErrorDetail

interface SmartPanelErrorDetail {
  error: unknown;
  item?: SmartPanelItem<T>
}