UseJunior Book a Demo

safe-docx · Layout

Table cell padding container creation

When applying padding to selected Word table cells, the padding values belong inside cell properties and cell margin containers. The cell properties container (the <w:tcPr> element) holds table-cell formatting, and the cell margin container (the <w:tcMar> element) holds the padding entries for each side.

setTableCellPadding applies this document mutation by selecting tables, rows, and cells by index, then ensuring the required OOXML containers exist before writing side-specific padding values. Because the mutation targets a selected cell range, cells outside that range must keep their existing margin state unchanged.[1]

Below is a test scenario of the baseline successful case of setTableCellPadding: creating missing table-cell property and margin containers for the selected cell only.

The scenario

Given a table cell without tcPr or tcMar children,
When setTableCellPadding is called,
Then the engine SHALL create container elements and untargeted cells SHALL NOT be modified.

The test fixture

The fixture builds a WordprocessingML table with two cells in one row, then applies padding to the first cell by table, row, and cell index.

Below is the test fixture code.

test.openspec('setTableCellPadding creates tcPr and tcMar containers')('Scenario: setTableCellPadding creates tcPr and tcMar containers', async ({ given, when, then, attachPrettyJson }: AllureBddContext) => {
  const doc = makeDoc(
    '<w:tbl>' +
    '<w:tr>' +
    '<w:tc><w:p><w:r><w:t>A1</w:t></w:r></w:p></w:tc>' +
    '<w:tc><w:p><w:r><w:t>B1</w:t></w:r></w:p></w:tc>' +
    '</w:tr>' +
    '</w:tbl>',
  );

  await given('a table cell without tcPr or tcMar children', () => {
    const tcPr = doc.getElementsByTagNameNS(OOXML.W_NS, 'tcPr');
    expect(tcPr.length).toBe(0);
  });

  await when('setTableCellPadding is called', async () => {
    const result = setTableCellPadding(doc, {
      tableIndexes: [0],
      rowIndexes: [0],
      cellIndexes: [0],
      topDxa: 80,
      bottomDxa: 120,
      leftDxa: 40,
      rightDxa: 60,
    });
    await attachPrettyJson('Result', result);
  });

  await then('the engine SHALL create container elements and untargeted cells SHALL NOT be modified', () => {
    const firstCell = doc.getElementsByTagNameNS(OOXML.W_NS, W.tc).item(0)!;
    const secondCell = doc.getElementsByTagNameNS(OOXML.W_NS, W.tc).item(1)!;

    const tcMar = firstCell.getElementsByTagNameNS(OOXML.W_NS, W.tcMar).item(0);
    expect(tcMar).toBeTruthy();

    const secondCellMar = secondCell.getElementsByTagNameNS(OOXML.W_NS, W.tcMar).item(0);
    expect(secondCellMar).toBeNull();
  });
});

The expected document state

This scenario asserts the document state after the mutation by querying margin containers on the selected and untargeted cells.[2]

Below is the result that setTableCellPadding is expected to return for this scenario.

{
  firstCell: {
    tcMar: expect.any(Element),
  },
  secondCell: {
    tcMar: null,
  },
}

Below is a description of the expected fields: