Fix: separate vertical alignment enums for ITableCellOptions and ISectionPropertiesOptions (#3079)

* fix: separate vertical alignment enums for table and section properties

- Introduced `VerticalAlignTable` for table-cell vertical alignment with valid values: `top`, `center`, and `bottom`.
- Added `VerticalAlignSection` for section properties, extending `VerticalAlignTable` with an additional value `both`.
- Marked the original `VerticalAlign` as deprecated for backward compatibility, directing users to the new enums.
- Updated type definitions for better clarity on valid vertical alignments.

* refactor: update vertical alignment imports and types for section and table properties

- Renamed `VerticalAlign` to `VerticalAlignSection` in section properties and `VerticalAlignTable` in table-cell properties for clarity.
- Updated type definitions to reflect the new enum names, ensuring better organization and understanding of vertical alignment options.
- Adjusted related test cases to utilize the new imports and types.

* refactor: update demos to use new enums for table and section properties for vertical alignment

src/file/document/body/section-properties/section-properties.spec.ts

@@ -6,7 +6,7 @@ import { FooterWrapper } from "@file/footer-wrapper";
 import { HeaderWrapper } from "@file/header-wrapper";
 import { Media } from "@file/media";
 import { NumberFormat } from "@file/shared/number-format";
-import { VerticalAlign } from "@file/vertical-align";
+import { VerticalAlignSection } from "@file/vertical-align";
 import { convertInchesToTwip } from "@util/convenience-functions";
 
 import { PageOrientation } from "./properties";
@@ -75,7 +75,7 @@ describe("SectionProperties", () => {
                     even: new FooterWrapper(media, 200),
                 },
                 titlePage: true,
-                verticalAlign: VerticalAlign.TOP,
+                verticalAlign: VerticalAlignSection.TOP,
             });
 
             const tree = new Formatter().format(properties);

src/file/document/body/section-properties/section-properties.ts

@@ -2,7 +2,7 @@
 
 import { FooterWrapper } from "@file/footer-wrapper";
 import { HeaderWrapper } from "@file/header-wrapper";
-import { VerticalAlign, VerticalAlignElement } from "@file/vertical-align";
+import { SectionVerticalAlign, VerticalAlignElement } from "@file/vertical-align";
 import { OnOffElement, XmlComponent } from "@file/xml-components";
 
 import { Columns, IColumnsAttributes } from "./properties/columns";
@@ -35,7 +35,7 @@ export type ISectionPropertiesOptions = {
     readonly footerWrapperGroup?: IHeaderFooterGroup<FooterWrapper>;
     readonly lineNumbers?: ILineNumberAttributes;
     readonly titlePage?: boolean;
-    readonly verticalAlign?: (typeof VerticalAlign)[keyof typeof VerticalAlign];
+    readonly verticalAlign?: SectionVerticalAlign;
     readonly column?: IColumnsAttributes;
     readonly type?: (typeof SectionType)[keyof typeof SectionType];
 };

src/file/table/table-cell/table-cell-properties.spec.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import { Formatter } from "@export/formatter";
 import { BorderStyle } from "@file/border";
-import { VerticalAlign } from "@file/vertical-align";
+import { VerticalAlignTable } from "@file/vertical-align";
 
 import { WidthType } from "../table-width";
 import { VerticalMergeType } from "./table-cell-components";
@@ -32,7 +32,7 @@ describe("TableCellProperties", () => {
         });
 
         it("sets vertical align", () => {
-            const properties = new TableCellProperties({ verticalAlign: VerticalAlign.BOTTOM });
+            const properties = new TableCellProperties({ verticalAlign: VerticalAlignTable.BOTTOM });
             const tree = new Formatter().format(properties);
             expect(tree).to.deep.equal({ "w:tcPr": [{ "w:vAlign": { _attr: { "w:val": "bottom" } } }] });
         });

src/file/table/table-cell/table-cell-properties.ts

@@ -1,4 +1,4 @@
-import { VerticalAlign, VerticalAlignElement } from "@file/vertical-align";
+import { TableVerticalAlign, VerticalAlignElement } from "@file/vertical-align";
 import { IgnoreIfEmptyXmlComponent } from "@file/xml-components";
 
 import { IShadingAttributesProperties, Shading } from "../../shading";
@@ -17,7 +17,7 @@ import {
 export type ITableCellPropertiesOptions = {
     readonly shading?: IShadingAttributesProperties;
     readonly margins?: ITableCellMarginOptions;
-    readonly verticalAlign?: (typeof VerticalAlign)[keyof typeof VerticalAlign];
+    readonly verticalAlign?: TableVerticalAlign;
     readonly textDirection?: (typeof TextDirection)[keyof typeof TextDirection];
     readonly verticalMerge?: (typeof VerticalMergeType)[keyof typeof VerticalMergeType];
     readonly width?: ITableWidthProperties;

src/file/table/table-cell/table-cell.spec.ts

@@ -3,7 +3,7 @@ import { describe, expect, it } from "vitest";
 import { Formatter } from "@export/formatter";
 import { BorderStyle } from "@file/border";
 import { ShadingType } from "@file/shading";
-import { VerticalAlign } from "@file/vertical-align";
+import { VerticalAlignTable } from "@file/vertical-align";
 
 import { WidthType } from "../table-width";
 import { TableCell } from "./table-cell";
@@ -286,7 +286,7 @@ describe("TableCell", () => {
         it("should create with vertical align", () => {
             const cell = new TableCell({
                 children: [],
-                verticalAlign: VerticalAlign.CENTER,
+                verticalAlign: VerticalAlignTable.CENTER,
             });
 
             const tree = new Formatter().format(cell);

src/file/vertical-align/vertical-align.ts

@@ -6,17 +6,43 @@ import { XmlAttributeComponent, XmlComponent } from "@file/xml-components";
 
 // <xsd:simpleType name="ST_VerticalJc">
 // <xsd:restriction base="xsd:string">
+//   <xsd:enumeration value="both"/>
 //   <xsd:enumeration value="top"/>
 //   <xsd:enumeration value="center"/>
 //   <xsd:enumeration value="bottom"/>
 // </xsd:restriction>
 // </xsd:simpleType>
-export const VerticalAlign = {
-    BOTTOM: "bottom",
-    CENTER: "center",
+
+/**
+ * Enumeration for table-cell vertical alignment. Only `top`, `center`, `bottom`
+ * are valid according to ECMA-376 (§17.18.87 ST_VerticalJc within <w:tcPr>).
+ */
+export const VerticalAlignTable = {
     TOP: "top",
+    CENTER: "center",
+    BOTTOM: "bottom",
 } as const;
 
+/**
+ * Enumeration for section (<w:sectPr>) vertical alignment. Adds `both` on top of
+ * the table-cell set (§17.18.87 ST_VerticalJc within <w:sectPr>).
+ */
+export const VerticalAlignSection = {
+    ...VerticalAlignTable,
+    BOTH: "both",
+} as const;
+
+/**
+ * @deprecated Use {@link VerticalAlignTable} for table cells or
+ * {@link VerticalAlignSection} for section properties. This alias remains for
+ * backward-compatibility and will be removed in the next major release.
+ */
+export const VerticalAlign = VerticalAlignSection;
+
+export type TableVerticalAlign = (typeof VerticalAlignTable)[keyof typeof VerticalAlignTable];
+
+export type SectionVerticalAlign = (typeof VerticalAlignSection)[keyof typeof VerticalAlignSection];
+
 export class VerticalAlignAttributes extends XmlAttributeComponent<{
     readonly verticalAlign?: (typeof VerticalAlign)[keyof typeof VerticalAlign];
 }> {