Styling

Add borders, colours, stroke styles or custom gradients very easily

CellData supports cell formatting via the uf field (short form of userEnteredFormat). New writes should set uf; the effective format used at render time is derived on the fly.

type CellData = {
  ... // Omitted for brevity
  uf?: CellFormat | StyleReference;
};

export type CellFormat = {
  backgroundColor?: Color | string;
  borders?: Borders;
  textFormat?: TextFormat;
  numberFormat?: NumberFormat;
  horizontalAlignment?: HorizontalAlign;
  verticalAlignment?: VerticalAlign;
  wrapStrategy?: WrapStrategy;
  indent?: number;
  relativeIndent?: number;
  textRotation?: number | "vertical";
  shrinkToFit?: boolean;
  // Pattern fill (OOXML 18 patterns: solid, mediumGray, darkGrid,
  // lightTrellis, etc.). When set to a non-"none" value the renderer
  // tiles foregroundColor over backgroundColor.
  fillPattern?: FillPattern;
  foregroundColor?: Color | string;
  // OOXML <gradientFill>. When present the renderer paints the
  // gradient instead of the solid / pattern fill.
  gradient?: GradientFill;
};

export type WrapStrategy = "overflow" | "wrap" | "clip";

export type NumberFormat = {
  type: NumberFormatType;
  pattern?: string;
};

export type NumberFormatType =
  | "TEXT"
  | "NUMBER"
  | "PERCENT"
  | "CURRENCY"
  | "DATE"
  | "TIME"
  | "DATE_TIME"
  | "FRACTION"
  | "SCIENTIFIC"
  | "SPECIAL";

export type HorizontalAlign = "left" | "right" | "center";
export type VerticalAlign = "top" | "middle" | "bottom";

export type Borders = {
  top?: Border;
  right?: Border;
  bottom?: Border;
  left?: Border;
  diagonalUp?: Border;
  diagonalDown?: Border;
};

export type Border = {
  // All 13 OOXML border styles supported.
  style: BorderStyle;
  width: number;
  color?: Color | string | null;
};

export type BorderStyle =
  | "dotted"
  | "dashed"
  | "solid"
  | "thin"
  | "solid_medium"
  | "solid_thick"
  | "double"
  | "hair"
  | "mediumDashed"
  | "mediumDashDot"
  | "dashDot"
  | "dashDotDot"
  | "slantDashDot";

export type TextFormat = {
  color?: Color | string;
  fontFamily?: string;
  fontSize?: number;
  bold?: boolean;
  italic?: boolean;
  strikethrough?: boolean;
  underline?: boolean;
  vertAlign?: "superscript" | "subscript";
};

export type GradientFill = {
  type: "linear" | "path";
  degree?: number;
  left?: number;
  right?: number;
  top?: number;
  bottom?: number;
  stops: Array<{ position: number; color: string }>;
};

Effective format is no longer persisted on CellData. The renderer derives it on the fly from uf, the cell's effective value, and (for formula cells) precedent formats via useSheetProperties.getEffectiveFormat. The legacy effectiveFormat / ef fields are accepted when loading older saved data but should not be written.