Data Grid Formatting

DataGridFormattingPlugin

Dependencies

• Auto-installed DataGridFormatDialogPlugin: Uses the Format Cells dialog for advanced formatting.

class DataGridFormattingPlugin {
  configure(config: DataGridFormattingConfig<T> = {}): void;

  apply(selection: DataGridFormattingSelection<T>, format: DataGridCellFormat): void;

  /** Replace only the value-format layer while retaining font, fill, and alignment. */
  applyValueFormat(
    selection: DataGridFormattingSelection<T>,
    value: DataGridCellFormat['value'],
  ): void;

  clear(selection: DataGridFormattingSelection<T>): void;

  getFormat(
    model: T | undefined,
    prop: ColumnProp,
    rowType?: DimensionRows,
  ): DataGridCellFormat | undefined;

  openDialog(
    selection: DataGridFormattingSelection<T>,
    valueKind: DataGridFormattingValueKind,
    valueFormatting = true,
  ): void;
}

---

resolveDataGridFormattingLocale

export function resolveDataGridFormattingLocale(
  localeText?: DataGridFormattingDialogConfig['localeText'],
): DataGridFormattingLocaleText;

---

DATA_GRID_FORMATTING_LOCALE

DATA_GRID_FORMATTING_LOCALE: {
  title: string;
  close: string;
  description: string;
  valueSection: string;
  automaticDescription: string;
  numberSection: string;
  category: string;
  locale: string;
  browserDefault: string;
  decimals: string;
  grouping: string;
  currency: string;
  negativeNumbers: string;
  dateStyle: string;
  timeStyle: 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; };
  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; };
};

---

DataGridFormatDialogPlugin

Dependencies

• Auto-installed DialogPlugin: Uses the shared Pro dialog runtime for Format Cells.

class DataGridFormatDialogPlugin {
  open(options: DataGridFormattingDialogOpenOptions<T>): void;

  close(): void;
}

---

createDataGridFormattingEditor

export function createDataGridFormattingEditor(
  document: Document,
  options: DataGridFormattingDialogOpenOptions,
  locale: DataGridFormattingLocaleText,
): DataGridFormattingEditor;

---

DataGridFormattingEditor

interface DataGridFormattingEditor {
  readonly element: HTMLElement;
  readonly preview: HTMLElement;
  readonly descriptionId: string;
  getDraft(): DataGridCellFormat;
  destroy(): void
}

---

createDataGridValueFormat

export function createDataGridValueFormat(
  preset: DataGridValueFormatPreset,
  locale?: string,
  currency = 'USD',
): DataGridCellFormat;

---

inferDataGridFormattingKind

export function inferDataGridFormattingKind<T extends DataType>(
  selection: DataGridFormattingSelection<T>,
  columnTypeKinds: Readonly<Record<string, DataGridFormattingValueKind>> = {},
): DataGridFormattingValueKind;

---

formatDataGridValue

export function formatDataGridValue(
  value: unknown,
  format?: DataGridValueFormat,
): string;

---

isDataGridNumberPreset

export function isDataGridNumberPreset(preset: DataGridValueFormatPreset): boolean;

---

isDataGridDatePreset

export function isDataGridDatePreset(preset: DataGridValueFormatPreset): boolean;

---

normalizeDataGridLocale

export function normalizeDataGridLocale(locale?: string): string | undefined;

---

normalizeDataGridCurrency

export function normalizeDataGridCurrency(currency?: string): string;

---

toDataGridDate

export function toDataGridDate(value: unknown): Date | undefined;

---

isDataGridFormattingRuntime

export function isDataGridFormattingRuntime(
  value: unknown,
): value is DataGridFormattingRuntime;

---

DATA_GRID_FORMATTING_PLUGIN

DATA_GRID_FORMATTING_PLUGIN: string;

---

DataGridFormattingRuntime

interface DataGridFormattingRuntime {
  readonly [DATA_GRID_FORMATTING_PLUGIN]: true;
  getFormat(
      model: DataType | undefined,
      prop: ColumnProp,
      rowType?: DimensionRows,
    ): DataGridCellFormat | undefined
}

---

DataGridValueFormatPreset

export type DataGridValueFormatPreset =
  | 'automatic'
  | 'number'
  | 'currency'
  | 'accounting'
  | 'percent'
  | 'scientific'
  | 'date'
  | 'datetime'
  | 'time'
  | 'text';

---

DataGridFormattingValueKind

export type DataGridFormattingValueKind =
  | 'number'
  | 'date'
  | 'text'
  | 'boolean'
  | 'mixed'
  | 'unknown';

---

DataGridValueFormat

interface DataGridValueFormat {
  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'
}

---

DataGridCellAppearance

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';
  readonly vertical?: 'top' | 'middle' | 'bottom';
  readonly wrap?: boolean;
  readonly borderStyle?: 'none' | 'solid' | 'dashed' | 'dotted' | 'double';
  readonly borderColor?: string
}

---

DataGridCellFormat

interface DataGridCellFormat {
  readonly value?: DataGridValueFormat;
  readonly appearance?: DataGridCellAppearance
}

---

DataGridFormattingSelection

interface DataGridFormattingSelection {
  readonly scope: 'cells' | 'columns';
  readonly columns: readonly ColumnRegular[];
  readonly cells: readonly DataGridFormattingCell<T>[];
  /** Useful for type resolution and dialog preview in column scope. */
    readonly rows: readonly T[]
}

---

DataGridFormattingCell

interface DataGridFormattingCell {
  readonly model: T;
  readonly column: ColumnRegular;
  readonly rowType?: DimensionRows
}

---

DataGridFormattingConfig (Extended from index.ts)

interface DataGridFormattingConfig {
  readonly getRowKey?: (
      model: T,
      context: { readonly rowType?: DimensionRows },
    ) => PropertyKey;
  readonly resolveValueKind?: (
      selection: DataGridFormattingSelection<T>,
    ) => DataGridFormattingValueKind;
  readonly columnTypeKinds?: Readonly<Record<string, DataGridFormattingValueKind>>;
  readonly scopes?: readonly ('cell' | 'columnHeader')[]
}

---

DataGridFormattingLocaleText

interface DataGridFormattingLocaleText {
  readonly title: string;
  readonly close: string;
  readonly description: string;
  readonly valueSection: 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 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>>;
  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
}

---

DataGridFormattingOptionLocaleText

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

interface DataGridFormattingDialogConfig {
  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'
    >> & {
      readonly presetLabels?: Partial<DataGridFormattingLocaleText['presetLabels']>;
      readonly optionLabels?: Partial<DataGridFormattingOptionLocaleText>;
      readonly colorLabels?: Readonly<Record<string, string>>;
    }
}

---

DataGridFormattingDialogOpenOptions (Extended from index.ts)

interface DataGridFormattingDialogOpenOptions {
  readonly selection: DataGridFormattingSelection<T>;
  readonly initialValue?: DataGridCellFormat;
  readonly sampleValue?: unknown;
  readonly valueKind: DataGridFormattingValueKind;
  /** False when selected columns own interactive templates that must be preserved. */
    readonly valueFormatting?: boolean;
  readonly onApply: (format: DataGridCellFormat) => void;
  readonly onClear: () => void
}

---

AlignmentSection

export function AlignmentSection({ appearance, locale, onChange }: SectionProps);

---

AppearancePanel

export function AppearancePanel({ appearance, options, locale, onChange }: {
  readonly appearance: DataGridCellAppearance;
  readonly options: DataGridFormattingDialogOpenOptions;
  readonly locale: DataGridFormattingLocaleText;
  readonly onChange: (value: DataGridCellAppearance) => void;
});

---

BordersSection

export function BordersSection({ appearance, locale, onChange }: SectionProps);

---

FormattingColorPicker

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

export function normalizeHexColor(value: string | undefined): string | undefined;

---

ColorsSection

export function ColorsSection({ appearance, locale, onChange }: SectionProps);

---

useControlTooltip

export function useControlTooltip(text: string);

---

ControlTooltip

export function ControlTooltip({ id, text, visible }: {
  readonly id: string;
  readonly text: string;
  readonly visible: boolean;
});

---

FormatPreview

export function FormatPreview({ sampleValue, format, locale }: {
  readonly sampleValue: unknown;
  readonly format: DataGridCellFormat;
  readonly locale: DataGridFormattingLocaleText;
});

---

FormatIcon

export function FormatIcon({ icon, className = 'rv-format-icon' }: {
  readonly icon: string;
  readonly className?: string;
});

---

FORMAT_ICONS

FORMAT_ICONS: { readonly accounting: string; readonly alignCenter: string; readonly alignLeft: string; readonly alignRight: 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 eraser: 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; };

---

InspectorSection

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

export function resolveDataGridFormattingLocaleOptions(
  configuredLocales?: readonly string[],
  selectedLocale?: string,
): readonly DataGridFormattingLocaleOption[];

---

DataGridFormattingLocaleOption

interface DataGridFormattingLocaleOption {
  readonly value: string;
  readonly label: string
}

---

DEFAULT_DATA_GRID_FORMATTING_LOCALES

DEFAULT_DATA_GRID_FORMATTING_LOCALES: readonly string[];

---

formatLocaleTemplate

export function formatLocaleTemplate(
  template: string,
  values: Readonly<Record<string, string>>,
): string;

---

SegmentedControl

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

export function ToggleIconButton({
  value,
  label,
  icon,
  onChange,
}: {
  readonly value: boolean;
  readonly label: string;
  readonly icon: string;
  readonly onChange: (value: boolean) => void;
});

---

SegmentedOption

interface SegmentedOption {
  readonly value: Value;
  readonly label: string;
  readonly icon: string
}

---

TypographySection

export function TypographySection({ appearance, options, locale, onChange }: SectionProps);

---

SectionProps

interface SectionProps {
  readonly appearance: DataGridCellAppearance;
  readonly options: DataGridFormattingDialogOpenOptions;
  readonly locale: DataGridFormattingLocaleText;
  readonly onChange: (value: Partial<DataGridCellAppearance>) => void
}

---

ValueFormatPanel

export function ValueFormatPanel({
  value,
  options,
  locale,
  onChange,
}: {
  readonly value: DataGridValueFormat;
  readonly options: DataGridFormattingDialogOpenOptions;
  readonly locale: DataGridFormattingLocaleText;
  readonly onChange: (value: DataGridValueFormat) => void;
});

---

ValueFormatPresets

export function ValueFormatPresets({
  value,
  formatLocale,
  currency,
  locale,
  onChange,
}: {
  readonly value: DataGridValueFormatPreset;
  readonly formatLocale?: string;
  readonly currency?: string;
  readonly locale: DataGridFormattingLocaleText;
  readonly onChange: (value: DataGridValueFormatPreset) => void;
});