chore: consolidate table cell formatting (#345)

jan-kubica · web-flow · commit 9c8dc8b0d22b · 2026-07-14T23:36:32.000+02:00
* chore: consolidate table cell formatting

* fix: satisfy formatting provenance lint

* fix: model optional formatting inputs explicitly
diff --git a/.changeset/five-otters-bet.md b/.changeset/five-otters-bet.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/core/src/prosemirror/conversion/effectiveTableCellFormatting.test.ts b/packages/core/src/prosemirror/conversion/effectiveTableCellFormatting.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+
+import type { Theme } from "../../types/document";
+import { resolveEffectiveTableCellFormatting } from "./effectiveTableCellFormatting";
+
+type ResolveOptions = Parameters<typeof resolveEffectiveTableCellFormatting>[0];
+
+const resolveFormatting = (overrides: Partial<ResolveOptions>) =>
+  resolveEffectiveTableCellFormatting({
+    directFormatting: undefined,
+    styleFormatting: undefined,
+    tableBorders: undefined,
+    position: {},
+    gridWidthPercent: undefined,
+    defaultMargins: undefined,
+    theme: undefined,
+    ...overrides,
+  });
+
+const theme: Theme = {
+  colorScheme: {
+    dk1: "000000",
+    lt1: "FFFFFF",
+    dk2: "44546A",
+    lt2: "E7E6E6",
+    accent1: "4472C4",
+    accent2: "ED7D31",
+    accent3: "A5A5A5",
+    accent4: "FFC000",
+    accent5: "5B9BD5",
+    accent6: "70AD47",
+    hlink: "0563C1",
+    folHlink: "954F72",
+  },
+};
+
+describe("resolveEffectiveTableCellFormatting", () => {
+  test("keeps a direct no-fill distinct from an absent or inherited background", () => {
+    const result = resolveFormatting({
+      directFormatting: { shading: { pattern: "nil" } },
+      styleFormatting: {
+        shading: { pattern: "clear", fill: { themeColor: "accent1" } },
+      },
+      theme,
+    });
+
+    expect(result.background).toEqual({ type: "none", source: "direct" });
+  });
+
+  test("records whether width came from the authored cell or table grid", () => {
+    const direct = resolveFormatting({
+      directFormatting: { width: { value: 1440, type: "dxa" } },
+      gridWidthPercent: 50,
+    });
+    const grid = resolveFormatting({ gridWidthPercent: 50 });
+
+    expect(direct.width).toEqual({
+      type: "value",
+      source: "direct",
+      value: 1440,
+      widthType: "dxa",
+    });
+    expect(grid.width).toEqual({
+      type: "value",
+      source: "grid",
+      value: 50,
+      widthType: "pct",
+    });
+  });
+
+  test("applies direct, style, and table border precedence before resolving theme colors", () => {
+    const result = resolveFormatting({
+      directFormatting: {
+        borders: { left: { style: "dashed", color: { rgb: "123456" } } },
+      },
+      styleFormatting: {
+        borders: { top: { style: "double", color: { themeColor: "accent2" } } },
+      },
+      tableBorders: {
+        top: { style: "single", color: { themeColor: "accent1" } },
+        bottom: { style: "single", color: { themeColor: "accent1" } },
+      },
+      position: { isFirstRow: true, isLastRow: true },
+      theme,
+    });
+
+    expect(result.borders?.top).toEqual({ style: "double", color: { rgb: "ED7D31" } });
+    expect(result.borders?.bottom).toEqual({ style: "single", color: { rgb: "4472C4" } });
+    expect(result.borders?.left).toEqual({ style: "dashed", color: { rgb: "123456" } });
+  });
+
+  test("uses direct margins before style and table defaults", () => {
+    const result = resolveFormatting({
+      directFormatting: { margins: { left: { value: 120, type: "dxa" } } },
+      styleFormatting: { margins: { left: { value: 240, type: "dxa" } } },
+      defaultMargins: { left: 360 },
+    });
+
+    expect(result.margins).toEqual({ left: 120 });
+  });
+});
diff --git a/packages/core/src/prosemirror/conversion/effectiveTableCellFormatting.ts b/packages/core/src/prosemirror/conversion/effectiveTableCellFormatting.ts
@@ -0,0 +1,252 @@
+import type {
+  CellMargins,
+  ShadingProperties,
+  TableBorders,
+  TableCellBorders,
+  TableCellFormatting,
+  TableWidthType,
+  Theme,
+} from "../../types/document";
+import { resolveColor } from "../../utils/colorResolver";
+import { resolveShadingFill } from "../../utils/formatToStyle";
+
+export type TableCellMarginsAttrs = {
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+};
+
+type EffectiveTableCellWidth =
+  | { type: "none" }
+  | {
+      type: "value";
+      source: "direct" | "grid";
+      value: number;
+      widthType: TableWidthType;
+    };
+
+type EffectiveTableCellBackground =
+  | { type: "none"; source: "none" | "direct" | "style" }
+  | { type: "color"; source: "direct" | "style"; rgb: string };
+
+type EffectiveTableCellFormatting = Readonly<{
+  width: EffectiveTableCellWidth;
+  background: EffectiveTableCellBackground;
+  borders: TableCellBorders | undefined;
+  margins: TableCellMarginsAttrs | undefined;
+}>;
+
+export type TableCellPosition = {
+  isFirstRow?: boolean;
+  isLastRow?: boolean;
+  isFirstColumn?: boolean;
+  isLastColumn?: boolean;
+};
+
+type ResolveEffectiveTableCellFormattingOptions = {
+  directFormatting: TableCellFormatting | undefined;
+  styleFormatting: TableCellFormatting | undefined;
+  tableBorders: TableBorders | undefined;
+  position: TableCellPosition;
+  gridWidthPercent: number | undefined;
+  defaultMargins: TableCellMarginsAttrs | undefined;
+  theme: Theme | null | undefined;
+};
+
+const TABLE_BORDER_SIDES = [
+  "top",
+  "bottom",
+  "left",
+  "right",
+  "insideH",
+  "insideV",
+  "topLeftToBottomRight",
+  "topRightToBottomLeft",
+] as const satisfies readonly (keyof TableCellBorders)[];
+
+/**
+ * Resolve the display-facing table-cell cascade without mutating authored
+ * OOXML formatting. Source discriminators keep inherited values distinct from
+ * direct values that the editor may later override.
+ */
+export const resolveEffectiveTableCellFormatting = ({
+  directFormatting,
+  styleFormatting,
+  tableBorders,
+  position,
+  gridWidthPercent,
+  defaultMargins,
+  theme,
+}: ResolveEffectiveTableCellFormattingOptions): EffectiveTableCellFormatting => {
+  const width = resolveEffectiveWidth(directFormatting, gridWidthPercent);
+  const background = resolveEffectiveBackground({ directFormatting, styleFormatting, theme });
+  const borders = resolveEffectiveBorders({
+    directFormatting,
+    styleFormatting,
+    tableBorders,
+    position,
+    theme,
+  });
+  const margins = resolveEffectiveMargins({
+    directFormatting,
+    styleFormatting,
+    defaultMargins,
+  });
+
+  return { width, background, borders, margins };
+};
+
+const resolveEffectiveWidth = (
+  directFormatting: TableCellFormatting | undefined,
+  gridWidthPercent: number | undefined,
+): EffectiveTableCellWidth => {
+  const directWidth = directFormatting?.width;
+  if (directWidth) {
+    return {
+      type: "value",
+      source: "direct",
+      value: directWidth.value,
+      widthType: directWidth.type,
+    };
+  }
+  if (gridWidthPercent !== undefined) {
+    return { type: "value", source: "grid", value: gridWidthPercent, widthType: "pct" };
+  }
+  return { type: "none" };
+};
+
+type ResolveEffectiveBackgroundOptions = Pick<
+  ResolveEffectiveTableCellFormattingOptions,
+  "directFormatting" | "styleFormatting" | "theme"
+>;
+
+const resolveEffectiveBackground = ({
+  directFormatting,
+  styleFormatting,
+  theme,
+}: ResolveEffectiveBackgroundOptions): EffectiveTableCellBackground => {
+  const directShading = directFormatting?.shading;
+  if (directShading !== undefined) {
+    return resolveBackgroundColor({ shading: directShading, source: "direct", theme });
+  }
+
+  const styleShading = styleFormatting?.shading;
+  if (styleShading !== undefined) {
+    return resolveBackgroundColor({ shading: styleShading, source: "style", theme });
+  }
+
+  return { type: "none", source: "none" };
+};
+
+type ResolveBackgroundColorOptions = {
+  shading: ShadingProperties;
+  source: "direct" | "style";
+  theme: Theme | null | undefined;
+};
+
+const resolveBackgroundColor = ({
+  shading,
+  source,
+  theme,
+}: ResolveBackgroundColorOptions): EffectiveTableCellBackground => {
+  const rgb = resolveShadingFill(shading, theme).replace(/^#/u, "");
+
+  if (!rgb) {
+    return { type: "none", source };
+  }
+  return { type: "color", source, rgb };
+};
+
+type ResolveEffectiveBordersOptions = Pick<
+  ResolveEffectiveTableCellFormattingOptions,
+  "directFormatting" | "styleFormatting" | "tableBorders" | "position" | "theme"
+>;
+
+const resolveEffectiveBorders = ({
+  directFormatting,
+  styleFormatting,
+  tableBorders,
+  position,
+  theme,
+}: ResolveEffectiveBordersOptions): TableCellBorders | undefined => {
+  const baseBorders = tableBorders
+    ? {
+        top: position.isFirstRow ? tableBorders.top : tableBorders.insideH,
+        bottom: position.isLastRow ? tableBorders.bottom : tableBorders.insideH,
+        left: position.isFirstColumn ? tableBorders.left : tableBorders.insideV,
+        right: position.isLastColumn ? tableBorders.right : tableBorders.insideV,
+      }
+    : undefined;
+  const styleBorders = styleFormatting?.borders;
+  const directBorders = directFormatting?.borders;
+  const borders =
+    baseBorders || styleBorders || directBorders
+      ? { ...baseBorders, ...styleBorders, ...directBorders }
+      : undefined;
+
+  return resolveThemedBorderColors(borders, theme);
+};
+
+type ResolveEffectiveMarginsOptions = Pick<
+  ResolveEffectiveTableCellFormattingOptions,
+  "directFormatting" | "styleFormatting" | "defaultMargins"
+>;
+
+const resolveEffectiveMargins = ({
+  directFormatting,
+  styleFormatting,
+  defaultMargins,
+}: ResolveEffectiveMarginsOptions): TableCellMarginsAttrs | undefined => {
+  if (directFormatting?.margins) {
+    return cellMarginsToAttrs(directFormatting.margins);
+  }
+  if (styleFormatting?.margins) {
+    return cellMarginsToAttrs(styleFormatting.margins);
+  }
+  return defaultMargins;
+};
+
+const cellMarginsToAttrs = (margins: CellMargins): TableCellMarginsAttrs => {
+  const result: TableCellMarginsAttrs = {};
+  if (margins.top?.value !== undefined) {
+    result.top = margins.top.value;
+  }
+  if (margins.bottom?.value !== undefined) {
+    result.bottom = margins.bottom.value;
+  }
+  if (margins.left?.value !== undefined) {
+    result.left = margins.left.value;
+  }
+  if (margins.right?.value !== undefined) {
+    result.right = margins.right.value;
+  }
+  return result;
+};
+
+const resolveThemedBorderColors = (
+  borders: TableCellBorders | undefined,
+  theme: Theme | null | undefined,
+): TableCellBorders | undefined => {
+  if (!borders || !theme?.colorScheme) {
+    return borders;
+  }
+
+  let resolved: TableCellBorders | undefined;
+  for (const side of TABLE_BORDER_SIDES) {
+    const border = borders[side];
+    if (!border?.color?.themeColor || border.color.auto) {
+      continue;
+    }
+
+    resolved ??= { ...borders };
+    resolved[side] = {
+      ...border,
+      color: {
+        rgb: resolveColor(border.color, theme).replace(/^#/u, ""),
+      },
+    };
+  }
+
+  return resolved ?? borders;
+};
diff --git a/packages/core/src/prosemirror/conversion/toProseDoc.ts b/packages/core/src/prosemirror/conversion/toProseDoc.ts
