docxmlater 10.1.3 → 10.1.5

package/src/elements/StructuredDocumentTag.ts

@@ -1,1207 +1,1176 @@
-/**
- * Structured Document Tag (SDT) - Content control wrapper
- *
- * SDTs are used by applications like Google Docs to wrap content
- * with metadata and control settings. They can contain paragraphs,
- * tables, or other block-level elements.
- */
-
-import { XMLBuilder, XMLElement } from "../xml/XMLBuilder";
-import { Paragraph } from "./Paragraph";
-import { Table } from "./Table";
-
-/**
- * Type of content lock for SDT
- */
-export type SDTLockType =
-  | "unlocked"
-  | "sdtLocked"
-  | "contentLocked"
-  | "sdtContentLocked";
-
-/**
- * Content control type
- */
-export type ContentControlType =
-  | "richText"
-  | "plainText"
-  | "comboBox"
-  | "dropDownList"
-  | "datePicker"
-  | "checkbox"
-  | "picture"
-  | "buildingBlock"
-  | "group"
-  | "citation"
-  | "bibliography"
-  | "docPartList"
-  | "equation";
-
-/**
- * List item for combo box or dropdown
- */
-export interface ListItem {
-  /** Display text shown to user */
-  displayText: string;
-  /** Internal value */
-  value: string;
-}
-
-/**
- * Plain text control properties
- */
-export interface PlainTextProperties {
-  /** Allow multiple lines */
-  multiLine?: boolean;
-}
-
-/**
- * Combo box control properties
- */
-export interface ComboBoxProperties {
-  /** List of items */
-  items: ListItem[];
-  /** Last selected value */
-  lastValue?: string;
-}
-
-/**
- * Dropdown list control properties
- */
-export interface DropDownListProperties {
-  /** List of items */
-  items: ListItem[];
-  /** Last selected value */
-  lastValue?: string;
-}
-
-/**
- * Date picker control properties
- */
-export interface DatePickerProperties {
-  /** Date format string (e.g., 'M/d/yyyy') */
-  dateFormat?: string;
-  /** Full date value */
-  fullDate?: Date;
-  /** Locale ID */
-  lid?: string;
-  /** Calendar type */
-  calendar?:
-    | "gregorian"
-    | "hijri"
-    | "hebrew"
-    | "taiwan"
-    | "japan"
-    | "thai"
-    | "korean";
-}
-
-/**
- * Checkbox control properties
- */
-export interface CheckboxProperties {
-  /** Whether the checkbox is checked */
-  checked?: boolean;
-  /** Character code for checked state (default: '2612' - ☒) */
-  checkedState?: string;
-  /** Character code for unchecked state (default: '2610' - ☐) */
-  uncheckedState?: string;
-}
-
-/**
- * Building block control properties
- */
-export interface BuildingBlockProperties {
-  /** Building block gallery name */
-  gallery?: string;
-  /** Building block category */
-  category?: string;
-  /** Whether to use docPartList (true) or docPartObj (false, default) */
-  isList?: boolean;
-}
-
-/**
- * Placeholder properties for SDT
- */
-export interface SDTPlaceholder {
-  /** Name of the document part to use as placeholder */
-  docPart: string;
-}
-
-/**
- * Data binding properties for SDT
- */
-export interface SDTDataBinding {
-  /** XPath expression for the data binding */
-  xpath: string;
-  /** Namespace prefix mappings */
-  prefixMappings?: string;
-  /** Custom XML data store item ID */
-  storeItemId?: string;
-}
-
-/**
- * Properties for a Structured Document Tag
- */
-export interface SDTProperties {
-  /** Unique ID for this SDT */
-  id?: number;
-  /** Tag value (used by applications) */
-  tag?: string;
-  /** Lock type */
-  lock?: SDTLockType;
-  /** Alias (display name) */
-  alias?: string;
-  /** Temporary placeholder (removed when content is edited) */
-  temporary?: boolean;
-  /** Content control type */
-  controlType?: ContentControlType;
-  /** Plain text properties */
-  plainText?: PlainTextProperties;
-  /** Combo box properties */
-  comboBox?: ComboBoxProperties;
-  /** Dropdown list properties */
-  dropDownList?: DropDownListProperties;
-  /** Date picker properties */
-  datePicker?: DatePickerProperties;
-  /** Checkbox properties */
-  checkbox?: CheckboxProperties;
-  /** Building block properties */
-  buildingBlock?: BuildingBlockProperties;
-  /** Placeholder (w:placeholder) */
-  placeholder?: SDTPlaceholder;
-  /** Data binding (w:dataBinding) */
-  dataBinding?: SDTDataBinding;
-  /** Whether SDT is currently showing placeholder content */
-  showingPlcHdr?: boolean;
-}
-
-/**
- * Content that can be wrapped by an SDT
- */
-export type SDTContent = Table | Paragraph | StructuredDocumentTag;
-
-/**
- * Structured Document Tag class
- * Wraps content with metadata and control settings
- *
- * Example XML:
- * ```xml
- * <w:sdt>
- *   <w:sdtPr>
- *     <w:lock w:val="contentLocked"/>
- *     <w:id w:val="-258490443"/>
- *     <w:tag w:val="goog_rdk_0"/>
- *   </w:sdtPr>
- *   <w:sdtContent>
- *     <!-- content here -->
- *   </w:sdtContent>
- * </w:sdt>
- * ```
- */
-export class StructuredDocumentTag {
-  private properties: SDTProperties;
-  private content: SDTContent[];
-
-  /**
-   * Create a new Structured Document Tag
-   * @param properties - SDT properties
-   * @param content - Content elements to wrap
-   */
-  constructor(properties: SDTProperties = {}, content: SDTContent[] = []) {
-    this.properties = properties;
-    this.content = content;
-  }
-
-  /**
-   * Get the SDT ID
-   * @returns SDT ID or undefined
-   */
-  getId(): number | undefined {
-    return this.properties.id;
-  }
-
-  /**
-   * Set the SDT ID
-   * @param id - Unique ID
-   */
-  setId(id: number): this {
-    this.properties.id = id;
-    return this;
-  }
-
-  /**
-   * Get the SDT tag
-   * @returns Tag value or undefined
-   */
-  getTag(): string | undefined {
-    return this.properties.tag;
-  }
-
-  /**
-   * Set the SDT tag
-   * @param tag - Tag value
-   */
-  setTag(tag: string): this {
-    this.properties.tag = tag;
-    return this;
-  }
-
-  /**
-   * Get the lock type
-   * @returns Lock type or undefined
-   */
-  getLock(): SDTLockType | undefined {
-    return this.properties.lock;
-  }
-
-  /**
-   * Set the lock type
-   * @param lock - Lock type
-   */
-  setLock(lock: SDTLockType): this {
-    this.properties.lock = lock;
-    return this;
-  }
-
-  /**
-   * Get the alias (display name)
-   * @returns Alias or undefined
-   */
-  getAlias(): string | undefined {
-    return this.properties.alias;
-  }
-
-  /**
-   * Set the alias (display name)
-   * @param alias - Display name
-   */
-  setAlias(alias: string): this {
-    this.properties.alias = alias;
-    return this;
-  }
-
-  /**
-   * Get the content control type
-   * @returns Control type or undefined
-   */
-  getControlType(): ContentControlType | undefined {
-    return this.properties.controlType;
-  }
-
-  /**
-   * Set the content control type
-   * @param type - Control type
-   */
-  setControlType(type: ContentControlType): this {
-    this.properties.controlType = type;
-    return this;
-  }
-
-  /**
-   * Get plain text properties
-   * @returns Plain text properties or undefined
-   */
-  getPlainTextProperties(): PlainTextProperties | undefined {
-    return this.properties.plainText;
-  }
-
-  /**
-   * Set plain text properties
-   * @param properties - Plain text properties
-   */
-  setPlainTextProperties(properties: PlainTextProperties): this {
-    this.properties.controlType = "plainText";
-    this.properties.plainText = properties;
-    return this;
-  }
-
-  /**
-   * Get combo box properties
-   * @returns Combo box properties or undefined
-   */
-  getComboBoxProperties(): ComboBoxProperties | undefined {
-    return this.properties.comboBox;
-  }
-
-  /**
-   * Set combo box properties
-   * @param properties - Combo box properties
-   */
-  setComboBoxProperties(properties: ComboBoxProperties): this {
-    this.properties.controlType = "comboBox";
-    this.properties.comboBox = properties;
-    return this;
-  }
-
-  /**
-   * Get dropdown list properties
-   * @returns Dropdown list properties or undefined
-   */
-  getDropDownListProperties(): DropDownListProperties | undefined {
-    return this.properties.dropDownList;
-  }
-
-  /**
-   * Set dropdown list properties
-   * @param properties - Dropdown list properties
-   */
-  setDropDownListProperties(properties: DropDownListProperties): this {
-    this.properties.controlType = "dropDownList";
-    this.properties.dropDownList = properties;
-    return this;
-  }
-
-  /**
-   * Get date picker properties
-   * @returns Date picker properties or undefined
-   */
-  getDatePickerProperties(): DatePickerProperties | undefined {
-    return this.properties.datePicker;
-  }
-
-  /**
-   * Set date picker properties
-   * @param properties - Date picker properties
-   */
-  setDatePickerProperties(properties: DatePickerProperties): this {
-    this.properties.controlType = "datePicker";
-    this.properties.datePicker = properties;
-    return this;
-  }
-
-  /**
-   * Get checkbox properties
-   * @returns Checkbox properties or undefined
-   */
-  getCheckboxProperties(): CheckboxProperties | undefined {
-    return this.properties.checkbox;
-  }
-
-  /**
-   * Set checkbox properties
-   * @param properties - Checkbox properties
-   */
-  setCheckboxProperties(properties: CheckboxProperties): this {
-    this.properties.controlType = "checkbox";
-    this.properties.checkbox = properties;
-    return this;
-  }
-
-  /**
-   * Get building block properties
-   * @returns Building block properties or undefined
-   */
-  getBuildingBlockProperties(): BuildingBlockProperties | undefined {
-    return this.properties.buildingBlock;
-  }
-
-  /**
-   * Alias for getBuildingBlockProperties() for backward compatibility
-   * @returns Building block properties or undefined
-   */
-  getBuildingBlock(): BuildingBlockProperties | undefined {
-    return this.getBuildingBlockProperties();
-  }
-
-  /**
-   * Set building block properties
-   * @param properties - Building block properties
-   */
-  setBuildingBlockProperties(properties: BuildingBlockProperties): this {
-    this.properties.controlType = "buildingBlock";
-    this.properties.buildingBlock = properties;
-    return this;
-  }
-
-  /**
-   * Get list items from combo box or dropdown list
-   * @returns List items or undefined if not a list control
-   */
-  getListItems(): ListItem[] | undefined {
-    if (this.properties.comboBox) {
-      return this.properties.comboBox.items;
-    }
-    if (this.properties.dropDownList) {
-      return this.properties.dropDownList.items;
-    }
-    return undefined;
-  }
-
-  /**
-   * Get date format from date picker
-   * @returns Date format string or undefined
-   */
-  getDateFormat(): string | undefined {
-    return this.properties.datePicker?.dateFormat;
-  }
-
-  /**
-   * Get checked state from checkbox
-   * @returns True if checkbox is checked, false otherwise
-   */
-  isChecked(): boolean {
-    return this.properties.checkbox?.checked ?? false;
-  }
-
-  /**
-   * Get temporary state
-   * Temporary SDTs are placeholders removed when content is edited
-   * @returns True if SDT is temporary (placeholder), false otherwise
-   */
-  isTemporary(): boolean {
-    return this.properties.temporary === true;
-  }
-
-  /**
-   * Set whether SDT is temporary
-   * @param temporary - Whether SDT is temporary
-   * @returns This instance for chaining
-   */
-  setTemporary(temporary: boolean): this {
-    this.properties.temporary = temporary;
-    return this;
-  }
-
-  /**
-   * Get all content elements
-   * @returns Array of content elements
-   */
-  getContent(): SDTContent[] {
-    return [...this.content];
-  }
-
-  /**
-   * Add content element
-   * @param element - Element to add
-   */
-  addContent(element: SDTContent): this {
-    this.content.push(element);
-    return this;
-  }
-
-  /**
-   * Clear all content
-   */
-  clearContent(): this {
-    this.content = [];
-    return this;
-  }
-
-  /**
-   * Generate XML for this SDT
-   * @returns XML element
-   */
-  toXML(): XMLElement {
-    const children: XMLElement[] = [];
-
-    // Build sdtPr (properties)
-    const sdtPrChildren: XMLElement[] = [];
-
-    if (this.properties.lock) {
-      sdtPrChildren.push(
-        XMLBuilder.wSelf("lock", { "w:val": this.properties.lock })
-      );
-    }
-
-    if (this.properties.id !== undefined) {
-      sdtPrChildren.push(
-        XMLBuilder.wSelf("id", { "w:val": this.properties.id.toString() })
-      );
-    }
-
-    if (this.properties.tag) {
-      sdtPrChildren.push(
-        XMLBuilder.wSelf("tag", { "w:val": this.properties.tag })
-      );
-    }
-
-    if (this.properties.alias) {
-      sdtPrChildren.push(
-        XMLBuilder.wSelf("alias", { "w:val": this.properties.alias })
-      );
-    }
-
-    // Add placeholder
-    if (this.properties.placeholder) {
-      sdtPrChildren.push(
-        XMLBuilder.w("placeholder", {}, [
-          XMLBuilder.wSelf("docPart", { "w:val": this.properties.placeholder.docPart }),
-        ])
-      );
-    }
-
-    // Add showing placeholder flag
-    if (this.properties.showingPlcHdr !== undefined) {
-      sdtPrChildren.push(
-        XMLBuilder.wSelf("showingPlcHdr", {
-          "w:val": this.properties.showingPlcHdr ? "true" : "false",
-        })
-      );
-    }
-
-    // Add data binding
-    if (this.properties.dataBinding) {
-      const dbAttrs: Record<string, string> = {
-        "w:xpath": this.properties.dataBinding.xpath,
-      };
-      if (this.properties.dataBinding.prefixMappings) {
-        dbAttrs["w:prefixMappings"] = this.properties.dataBinding.prefixMappings;
-      }
-      if (this.properties.dataBinding.storeItemId) {
-        dbAttrs["w:storeItemID"] = this.properties.dataBinding.storeItemId;
-      }
-      sdtPrChildren.push(XMLBuilder.wSelf("dataBinding", dbAttrs));
-    }
-
-    // Add control type-specific XML
-    if (this.properties.controlType) {
-      switch (this.properties.controlType) {
-        case "richText":
-          sdtPrChildren.push(XMLBuilder.wSelf("richText", {}));
-          break;
-
-        case "plainText":
-          if (this.properties.plainText) {
-            const attrs: Record<string, string> = {};
-            if (this.properties.plainText.multiLine !== undefined) {
-              attrs["w:multiLine"] = this.properties.plainText.multiLine
-                ? "1"
-                : "0";
-            }
-            sdtPrChildren.push(XMLBuilder.wSelf("text", attrs));
-          } else {
-            sdtPrChildren.push(XMLBuilder.wSelf("text", {}));
-          }
-          break;
-
-        case "comboBox":
-          if (this.properties.comboBox) {
-            const comboBoxChildren: XMLElement[] = [];
-            for (const item of this.properties.comboBox.items) {
-              comboBoxChildren.push(
-                XMLBuilder.wSelf("listItem", {
-                  "w:displayText": item.displayText,
-                  "w:value": item.value,
-                })
-              );
-            }
-            sdtPrChildren.push(XMLBuilder.w("comboBox", {}, comboBoxChildren));
-          }
-          break;
-
-        case "dropDownList":
-          if (this.properties.dropDownList) {
-            const dropDownChildren: XMLElement[] = [];
-            for (const item of this.properties.dropDownList.items) {
-              dropDownChildren.push(
-                XMLBuilder.wSelf("listItem", {
-                  "w:displayText": item.displayText,
-                  "w:value": item.value,
-                })
-              );
-            }
-            sdtPrChildren.push(
-              XMLBuilder.w("dropDownList", {}, dropDownChildren)
-            );
-          }
-          break;
-
-        case "datePicker":
-          if (this.properties.datePicker) {
-            // Per ECMA-376, w:date has w:fullDate as attribute; dateFormat, lid,
-            // storeMappedDataAs, and calendar are child elements with w:val
-            const dateAttrs: Record<string, string> = {};
-            if (this.properties.datePicker.fullDate) {
-              dateAttrs["w:fullDate"] =
-                this.properties.datePicker.fullDate.toISOString();
-            }
-            const dateChildren: XMLElement[] = [];
-            if (this.properties.datePicker.dateFormat) {
-              dateChildren.push(XMLBuilder.wSelf("dateFormat", {
-                "w:val": this.properties.datePicker.dateFormat,
-              }));
-            }
-            if (this.properties.datePicker.lid) {
-              dateChildren.push(XMLBuilder.wSelf("lid", {
-                "w:val": this.properties.datePicker.lid,
-              }));
-            }
-            if (this.properties.datePicker.calendar) {
-              dateChildren.push(XMLBuilder.wSelf("calendar", {
-                "w:val": this.properties.datePicker.calendar,
-              }));
-            }
-            if (dateChildren.length > 0) {
-              sdtPrChildren.push(XMLBuilder.w("date", dateAttrs, dateChildren));
-            } else {
-              sdtPrChildren.push(XMLBuilder.wSelf("date", dateAttrs));
-            }
-          }
-          break;
-
-        case "checkbox":
-          if (this.properties.checkbox) {
-            const checkboxChildren: XMLElement[] = [];
-
-            // Add checked state - use w14 namespace per OOXML spec
-            if (this.properties.checkbox.checked !== undefined) {
-              checkboxChildren.push(
-                XMLBuilder.w14Self("checked", {
-                  "w14:val": this.properties.checkbox.checked ? "1" : "0",
-                })
-              );
-            }
-
-            // Add checked state symbol - use w14 namespace per OOXML spec
-            if (this.properties.checkbox.checkedState) {
-              checkboxChildren.push(
-                XMLBuilder.w14Self("checkedState", {
-                  "w14:val": this.properties.checkbox.checkedState,
-                  "w14:font": "MS Gothic",
-                })
-              );
-            }
-
-            // Add unchecked state symbol - use w14 namespace per OOXML spec
-            if (this.properties.checkbox.uncheckedState) {
-              checkboxChildren.push(
-                XMLBuilder.w14Self("uncheckedState", {
-                  "w14:val": this.properties.checkbox.uncheckedState,
-                  "w14:font": "MS Gothic",
-                })
-              );
-            }
-
-            sdtPrChildren.push(
-              XMLBuilder.w14("checkbox", {}, checkboxChildren)
-            );
-          }
-          break;
-
-        case "picture":
-          sdtPrChildren.push(XMLBuilder.wSelf("picture", {}));
-          break;
-
-        case "buildingBlock":
-          if (this.properties.buildingBlock) {
-            const bbChildren: XMLElement[] = [];
-            if (this.properties.buildingBlock.gallery) {
-              bbChildren.push(
-                XMLBuilder.wSelf("docPartGallery", {
-                  "w:val": this.properties.buildingBlock.gallery,
-                })
-              );
-            }
-            if (this.properties.buildingBlock.category) {
-              bbChildren.push(
-                XMLBuilder.wSelf("docPartCategory", {
-                  "w:val": this.properties.buildingBlock.category,
-                })
-              );
-            }
-            sdtPrChildren.push(XMLBuilder.w("docPartObj", {}, bbChildren));
-          }
-          break;
-
-        case "group":
-          sdtPrChildren.push(XMLBuilder.wSelf("group", {}));
-          break;
-
-        case "citation":
-          sdtPrChildren.push(XMLBuilder.wSelf("citation", {}));
-          break;
-
-        case "bibliography":
-          sdtPrChildren.push(XMLBuilder.wSelf("bibliography", {}));
-          break;
-
-        case "equation":
-          sdtPrChildren.push(XMLBuilder.wSelf("equation", {}));
-          break;
-
-        case "docPartList":
-          if (this.properties.buildingBlock) {
-            const dplChildren: XMLElement[] = [];
-            if (this.properties.buildingBlock.gallery) {
-              dplChildren.push(
-                XMLBuilder.wSelf("docPartGallery", {
-                  "w:val": this.properties.buildingBlock.gallery,
-                })
-              );
-            }
-            if (this.properties.buildingBlock.category) {
-              dplChildren.push(
-                XMLBuilder.wSelf("docPartCategory", {
-                  "w:val": this.properties.buildingBlock.category,
-                })
-              );
-            }
-            sdtPrChildren.push(XMLBuilder.w("docPartList", {}, dplChildren));
-          }
-          break;
-      }
-    }
-
-    if (sdtPrChildren.length > 0) {
-      children.push(XMLBuilder.w("sdtPr", {}, sdtPrChildren));
-    }
-
-    // Build sdtContent
-    const sdtContentChildren: XMLElement[] = [];
-    for (const element of this.content) {
-      sdtContentChildren.push(element.toXML());
-    }
-
-    children.push(XMLBuilder.w("sdtContent", {}, sdtContentChildren));
-
-    return XMLBuilder.w("sdt", {}, children);
-  }
-
-  /**
-   * Create an SDT wrapping a table (common for Google Docs)
-   * @param table - Table to wrap
-   * @param tag - Optional tag value
-   * @param lock - Optional lock type (default: unlocked for editability)
-   * @returns New SDT instance
-   * @example
-   * ```typescript
-   * // Unlocked table (editable in Word) - RECOMMENDED
-   * const sdt = StructuredDocumentTag.wrapTable(table);
-   *
-   * // Locked table (read-only in Word)
-   * const lockedSdt = StructuredDocumentTag.wrapTable(table, 'my-table', 'contentLocked');
-   * ```
-   */
-  static wrapTable(
-    table: Table,
-    tag = "goog_rdk_0",
-    lock?: SDTLockType
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000, // Generate a reasonable ID
-        tag,
-        lock, // Only set if provided - defaults to unlocked
-      },
-      [table]
-    );
-  }
-
-  /**
-   * Create an SDT wrapping a paragraph
-   * @param paragraph - Paragraph to wrap
-   * @param tag - Optional tag value
-   * @returns New SDT instance
-   */
-  static wrapParagraph(
-    paragraph: Paragraph,
-    tag?: string
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        tag,
-      },
-      [paragraph]
-    );
-  }
-
-  /**
-   * Create an empty SDT
-   * @param properties - SDT properties
-   * @returns New SDT instance
-   */
-  static create(properties: SDTProperties = {}): StructuredDocumentTag {
-    return new StructuredDocumentTag(properties);
-  }
-
-  /**
-   * Create a rich text content control
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   * @returns New SDT instance
-   */
-  static createRichText(
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "richText",
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create a plain text content control
-   * @param content - Initial content
-   * @param multiLine - Allow multiple lines
-   * @param properties - Additional SDT properties
-   * @returns New SDT instance
-   */
-  static createPlainText(
-    content: SDTContent[] = [],
-    multiLine = false,
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "plainText",
-        plainText: { multiLine },
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create a combo box content control
-   * @param items - List items
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   * @returns New SDT instance
-   */
-  static createComboBox(
-    items: ListItem[],
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "comboBox",
-        comboBox: { items },
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create a dropdown list content control
-   * @param items - List items
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   * @returns New SDT instance
-   */
-  static createDropDownList(
-    items: ListItem[],
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "dropDownList",
-        dropDownList: { items },
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create a date picker content control
-   * @param dateFormat - Date format string (e.g., 'M/d/yyyy')
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   * @returns New SDT instance
-   */
-  static createDatePicker(
-    dateFormat = "M/d/yyyy",
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "datePicker",
-        datePicker: { dateFormat },
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create a checkbox content control
-   * @param checked - Initial checked state
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   * @returns New SDT instance
-   */
-  static createCheckbox(
-    checked = false,
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "checkbox",
-        checkbox: {
-          checked,
-          checkedState: "2612", // ☒
-          uncheckedState: "2610", // ☐
-        },
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create a picture content control
-   * @param content - Initial content (typically contains an image)
-   * @param properties - Additional SDT properties
-   * @returns New SDT instance
-   */
-  static createPicture(
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "picture",
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create a building block content control
-   * @param gallery - Building block gallery name
-   * @param category - Building block category
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   * @returns New SDT instance
-   */
-  static createBuildingBlock(
-    gallery: string,
-    category: string,
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "buildingBlock",
-        buildingBlock: { gallery, category },
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create a group content control
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   * @returns New SDT instance
-   */
-  static createGroup(
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "group",
-        lock: "sdtContentLocked", // Groups typically lock content
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Unlocks the SDT content (allows editing)
-   * Removes any lock that prevents content modification
-   * @returns This SDT for chaining
-   * @example
-   * ```typescript
-   * // Unlock a locked SDT to enable editing
-   * sdt.unlock();
-   *
-   * // Chain with other modifications
-   * sdt.unlock().setTag('editable-content');
-   * ```
-   */
-  unlock(): this {
-    delete this.properties.lock;
-    return this;
-  }
-
-  /**
-   * Checks if SDT content is locked in any way
-   * @returns True if content is locked (contentLocked, sdtLocked, or sdtContentLocked)
-   * @example
-   * ```typescript
-   * if (sdt.isLocked()) {
-   *   console.log('SDT is locked - unlocking for editing');
-   *   sdt.unlock();
-   * }
-   * ```
-   */
-  isLocked(): boolean {
-    const lock = this.properties.lock;
-    return (
-      lock === "contentLocked" ||
-      lock === "sdtContentLocked" ||
-      lock === "sdtLocked"
-    );
-  }
-
-  /**
-   * Checks if SDT content can be edited by users
-   * @returns True if content can be modified (not locked by contentLocked or sdtContentLocked)
-   * @example
-   * ```typescript
-   * const editable = sdt.isContentEditable();
-   * console.log(editable ? 'Can edit' : 'Cannot edit');
-   * ```
-   */
-  isContentEditable(): boolean {
-    const lock = this.properties.lock;
-    return lock !== "contentLocked" && lock !== "sdtContentLocked";
-  }
-
-  /**
-   * Get the placeholder configuration
-   */
-  getPlaceholder(): SDTPlaceholder | undefined {
-    return this.properties.placeholder;
-  }
-
-  /**
-   * Set the placeholder (w:placeholder/w:docPart)
-   * @param docPart - Name of the document part to use as placeholder
-   */
-  setPlaceholder(docPart: string): this {
-    this.properties.placeholder = { docPart };
-    return this;
-  }
-
-  /**
-   * Get the data binding configuration
-   */
-  getDataBinding(): SDTDataBinding | undefined {
-    return this.properties.dataBinding;
-  }
-
-  /**
-   * Set the data binding (w:dataBinding)
-   * @param xpath - XPath expression
-   * @param prefixMappings - Namespace prefix mappings
-   * @param storeItemId - Custom XML data store item ID
-   */
-  setDataBinding(xpath: string, prefixMappings?: string, storeItemId?: string): this {
-    this.properties.dataBinding = { xpath, prefixMappings, storeItemId };
-    return this;
-  }
-
-  /**
-   * Get whether the SDT is currently showing placeholder content
-   */
-  isShowingPlaceholder(): boolean {
-    return this.properties.showingPlcHdr === true;
-  }
-
-  /**
-   * Set whether the SDT is showing placeholder content
-   * @param val - Whether placeholder is showing
-   */
-  setShowingPlaceholder(val: boolean): this {
-    this.properties.showingPlcHdr = val;
-    return this;
-  }
-
-  /**
-   * Create a citation content control
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   */
-  static createCitation(
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "citation",
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create a bibliography content control
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   */
-  static createBibliography(
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "bibliography",
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create a document part list content control
-   * Uses w:docPartList instead of w:docPartObj
-   * @param gallery - Building block gallery name
-   * @param category - Building block category
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   */
-  static createDocPartList(
-    gallery: string,
-    category: string,
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "docPartList",
-        buildingBlock: { gallery, category, isList: true },
-        ...properties,
-      },
-      content
-    );
-  }
-
-  /**
-   * Create an equation content control
-   * @param content - Initial content
-   * @param properties - Additional SDT properties
-   */
-  static createEquation(
-    content: SDTContent[] = [],
-    properties: Partial<SDTProperties> = {}
-  ): StructuredDocumentTag {
-    return new StructuredDocumentTag(
-      {
-        id: Date.now() % 1000000000,
-        controlType: "equation",
-        ...properties,
-      },
-      content
-    );
-  }
-}
+/**
+ * Structured Document Tag (SDT) - Content control wrapper
+ *
+ * SDTs are used by applications like Google Docs to wrap content
+ * with metadata and control settings. They can contain paragraphs,
+ * tables, or other block-level elements.
+ */
+
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
+import { Paragraph } from './Paragraph';
+import { Table } from './Table';
+
+/**
+ * Type of content lock for SDT
+ */
+export type SDTLockType = 'unlocked' | 'sdtLocked' | 'contentLocked' | 'sdtContentLocked';
+
+/**
+ * Content control type
+ */
+export type ContentControlType =
+  | 'richText'
+  | 'plainText'
+  | 'comboBox'
+  | 'dropDownList'
+  | 'datePicker'
+  | 'checkbox'
+  | 'picture'
+  | 'buildingBlock'
+  | 'group'
+  | 'citation'
+  | 'bibliography'
+  | 'docPartList'
+  | 'equation';
+
+/**
+ * List item for combo box or dropdown
+ */
+export interface ListItem {
+  /** Display text shown to user */
+  displayText: string;
+  /** Internal value */
+  value: string;
+}
+
+/**
+ * Plain text control properties
+ */
+export interface PlainTextProperties {
+  /** Allow multiple lines */
+  multiLine?: boolean;
+}
+
+/**
+ * Combo box control properties
+ */
+export interface ComboBoxProperties {
+  /** List of items */
+  items: ListItem[];
+  /** Last selected value */
+  lastValue?: string;
+}
+
+/**
+ * Dropdown list control properties
+ */
+export interface DropDownListProperties {
+  /** List of items */
+  items: ListItem[];
+  /** Last selected value */
+  lastValue?: string;
+}
+
+/**
+ * Date picker control properties
+ */
+export interface DatePickerProperties {
+  /** Date format string (e.g., 'M/d/yyyy') */
+  dateFormat?: string;
+  /** Full date value */
+  fullDate?: Date;
+  /** Locale ID */
+  lid?: string;
+  /** Calendar type */
+  calendar?: 'gregorian' | 'hijri' | 'hebrew' | 'taiwan' | 'japan' | 'thai' | 'korean';
+}
+
+/**
+ * Checkbox control properties
+ */
+export interface CheckboxProperties {
+  /** Whether the checkbox is checked */
+  checked?: boolean;
+  /** Character code for checked state (default: '2612' - ☒) */
+  checkedState?: string;
+  /** Character code for unchecked state (default: '2610' - ☐) */
+  uncheckedState?: string;
+}
+
+/**
+ * Building block control properties
+ */
+export interface BuildingBlockProperties {
+  /** Building block gallery name */
+  gallery?: string;
+  /** Building block category */
+  category?: string;
+  /** Whether to use docPartList (true) or docPartObj (false, default) */
+  isList?: boolean;
+}
+
+/**
+ * Placeholder properties for SDT
+ */
+export interface SDTPlaceholder {
+  /** Name of the document part to use as placeholder */
+  docPart: string;
+}
+
+/**
+ * Data binding properties for SDT
+ */
+export interface SDTDataBinding {
+  /** XPath expression for the data binding */
+  xpath: string;
+  /** Namespace prefix mappings */
+  prefixMappings?: string;
+  /** Custom XML data store item ID */
+  storeItemId?: string;
+}
+
+/**
+ * Properties for a Structured Document Tag
+ */
+export interface SDTProperties {
+  /** Unique ID for this SDT */
+  id?: number;
+  /** Tag value (used by applications) */
+  tag?: string;
+  /** Lock type */
+  lock?: SDTLockType;
+  /** Alias (display name) */
+  alias?: string;
+  /** Temporary placeholder (removed when content is edited) */
+  temporary?: boolean;
+  /** Content control type */
+  controlType?: ContentControlType;
+  /** Plain text properties */
+  plainText?: PlainTextProperties;
+  /** Combo box properties */
+  comboBox?: ComboBoxProperties;
+  /** Dropdown list properties */
+  dropDownList?: DropDownListProperties;
+  /** Date picker properties */
+  datePicker?: DatePickerProperties;
+  /** Checkbox properties */
+  checkbox?: CheckboxProperties;
+  /** Building block properties */
+  buildingBlock?: BuildingBlockProperties;
+  /** Placeholder (w:placeholder) */
+  placeholder?: SDTPlaceholder;
+  /** Data binding (w:dataBinding) */
+  dataBinding?: SDTDataBinding;
+  /** Whether SDT is currently showing placeholder content */
+  showingPlcHdr?: boolean;
+}
+
+/**
+ * Content that can be wrapped by an SDT
+ */
+export type SDTContent = Table | Paragraph | StructuredDocumentTag;
+
+/**
+ * Structured Document Tag class
+ * Wraps content with metadata and control settings
+ *
+ * Example XML:
+ * ```xml
+ * <w:sdt>
+ *   <w:sdtPr>
+ *     <w:lock w:val="contentLocked"/>
+ *     <w:id w:val="-258490443"/>
+ *     <w:tag w:val="goog_rdk_0"/>
+ *   </w:sdtPr>
+ *   <w:sdtContent>
+ *     <!-- content here -->
+ *   </w:sdtContent>
+ * </w:sdt>
+ * ```
+ */
+export class StructuredDocumentTag {
+  private properties: SDTProperties;
+  private content: SDTContent[];
+
+  /**
+   * Create a new Structured Document Tag
+   * @param properties - SDT properties
+   * @param content - Content elements to wrap
+   */
+  constructor(properties: SDTProperties = {}, content: SDTContent[] = []) {
+    this.properties = properties;
+    this.content = content;
+  }
+
+  /**
+   * Get the SDT ID
+   * @returns SDT ID or undefined
+   */
+  getId(): number | undefined {
+    return this.properties.id;
+  }
+
+  /**
+   * Set the SDT ID
+   * @param id - Unique ID
+   */
+  setId(id: number): this {
+    this.properties.id = id;
+    return this;
+  }
+
+  /**
+   * Get the SDT tag
+   * @returns Tag value or undefined
+   */
+  getTag(): string | undefined {
+    return this.properties.tag;
+  }
+
+  /**
+   * Set the SDT tag
+   * @param tag - Tag value
+   */
+  setTag(tag: string): this {
+    this.properties.tag = tag;
+    return this;
+  }
+
+  /**
+   * Get the lock type
+   * @returns Lock type or undefined
+   */
+  getLock(): SDTLockType | undefined {
+    return this.properties.lock;
+  }
+
+  /**
+   * Set the lock type
+   * @param lock - Lock type
+   */
+  setLock(lock: SDTLockType): this {
+    this.properties.lock = lock;
+    return this;
+  }
+
+  /**
+   * Get the alias (display name)
+   * @returns Alias or undefined
+   */
+  getAlias(): string | undefined {
+    return this.properties.alias;
+  }
+
+  /**
+   * Set the alias (display name)
+   * @param alias - Display name
+   */
+  setAlias(alias: string): this {
+    this.properties.alias = alias;
+    return this;
+  }
+
+  /**
+   * Get the content control type
+   * @returns Control type or undefined
+   */
+  getControlType(): ContentControlType | undefined {
+    return this.properties.controlType;
+  }
+
+  /**
+   * Set the content control type
+   * @param type - Control type
+   */
+  setControlType(type: ContentControlType): this {
+    this.properties.controlType = type;
+    return this;
+  }
+
+  /**
+   * Get plain text properties
+   * @returns Plain text properties or undefined
+   */
+  getPlainTextProperties(): PlainTextProperties | undefined {
+    return this.properties.plainText;
+  }
+
+  /**
+   * Set plain text properties
+   * @param properties - Plain text properties
+   */
+  setPlainTextProperties(properties: PlainTextProperties): this {
+    this.properties.controlType = 'plainText';
+    this.properties.plainText = properties;
+    return this;
+  }
+
+  /**
+   * Get combo box properties
+   * @returns Combo box properties or undefined
+   */
+  getComboBoxProperties(): ComboBoxProperties | undefined {
+    return this.properties.comboBox;
+  }
+
+  /**
+   * Set combo box properties
+   * @param properties - Combo box properties
+   */
+  setComboBoxProperties(properties: ComboBoxProperties): this {
+    this.properties.controlType = 'comboBox';
+    this.properties.comboBox = properties;
+    return this;
+  }
+
+  /**
+   * Get dropdown list properties
+   * @returns Dropdown list properties or undefined
+   */
+  getDropDownListProperties(): DropDownListProperties | undefined {
+    return this.properties.dropDownList;
+  }
+
+  /**
+   * Set dropdown list properties
+   * @param properties - Dropdown list properties
+   */
+  setDropDownListProperties(properties: DropDownListProperties): this {
+    this.properties.controlType = 'dropDownList';
+    this.properties.dropDownList = properties;
+    return this;
+  }
+
+  /**
+   * Get date picker properties
+   * @returns Date picker properties or undefined
+   */
+  getDatePickerProperties(): DatePickerProperties | undefined {
+    return this.properties.datePicker;
+  }
+
+  /**
+   * Set date picker properties
+   * @param properties - Date picker properties
+   */
+  setDatePickerProperties(properties: DatePickerProperties): this {
+    this.properties.controlType = 'datePicker';
+    this.properties.datePicker = properties;
+    return this;
+  }
+
+  /**
+   * Get checkbox properties
+   * @returns Checkbox properties or undefined
+   */
+  getCheckboxProperties(): CheckboxProperties | undefined {
+    return this.properties.checkbox;
+  }
+
+  /**
+   * Set checkbox properties
+   * @param properties - Checkbox properties
+   */
+  setCheckboxProperties(properties: CheckboxProperties): this {
+    this.properties.controlType = 'checkbox';
+    this.properties.checkbox = properties;
+    return this;
+  }
+
+  /**
+   * Get building block properties
+   * @returns Building block properties or undefined
+   */
+  getBuildingBlockProperties(): BuildingBlockProperties | undefined {
+    return this.properties.buildingBlock;
+  }
+
+  /**
+   * Alias for getBuildingBlockProperties() for backward compatibility
+   * @returns Building block properties or undefined
+   */
+  getBuildingBlock(): BuildingBlockProperties | undefined {
+    return this.getBuildingBlockProperties();
+  }
+
+  /**
+   * Set building block properties
+   * @param properties - Building block properties
+   */
+  setBuildingBlockProperties(properties: BuildingBlockProperties): this {
+    this.properties.controlType = 'buildingBlock';
+    this.properties.buildingBlock = properties;
+    return this;
+  }
+
+  /**
+   * Get list items from combo box or dropdown list
+   * @returns List items or undefined if not a list control
+   */
+  getListItems(): ListItem[] | undefined {
+    if (this.properties.comboBox) {
+      return this.properties.comboBox.items;
+    }
+    if (this.properties.dropDownList) {
+      return this.properties.dropDownList.items;
+    }
+    return undefined;
+  }
+
+  /**
+   * Get date format from date picker
+   * @returns Date format string or undefined
+   */
+  getDateFormat(): string | undefined {
+    return this.properties.datePicker?.dateFormat;
+  }
+
+  /**
+   * Get checked state from checkbox
+   * @returns True if checkbox is checked, false otherwise
+   */
+  isChecked(): boolean {
+    return this.properties.checkbox?.checked ?? false;
+  }
+
+  /**
+   * Get temporary state
+   * Temporary SDTs are placeholders removed when content is edited
+   * @returns True if SDT is temporary (placeholder), false otherwise
+   */
+  isTemporary(): boolean {
+    return this.properties.temporary === true;
+  }
+
+  /**
+   * Set whether SDT is temporary
+   * @param temporary - Whether SDT is temporary
+   * @returns This instance for chaining
+   */
+  setTemporary(temporary: boolean): this {
+    this.properties.temporary = temporary;
+    return this;
+  }
+
+  /**
+   * Get all content elements
+   * @returns Array of content elements
+   */
+  getContent(): SDTContent[] {
+    return [...this.content];
+  }
+
+  /**
+   * Add content element
+   * @param element - Element to add
+   */
+  addContent(element: SDTContent): this {
+    this.content.push(element);
+    return this;
+  }
+
+  /**
+   * Clear all content
+   */
+  clearContent(): this {
+    this.content = [];
+    return this;
+  }
+
+  /**
+   * Generate XML for this SDT
+   * @returns XML element
+   */
+  toXML(): XMLElement {
+    const children: XMLElement[] = [];
+
+    // Build sdtPr (properties)
+    const sdtPrChildren: XMLElement[] = [];
+
+    if (this.properties.lock) {
+      sdtPrChildren.push(XMLBuilder.wSelf('lock', { 'w:val': this.properties.lock }));
+    }
+
+    if (this.properties.id !== undefined) {
+      sdtPrChildren.push(XMLBuilder.wSelf('id', { 'w:val': this.properties.id.toString() }));
+    }
+
+    if (this.properties.tag) {
+      sdtPrChildren.push(XMLBuilder.wSelf('tag', { 'w:val': this.properties.tag }));
+    }
+
+    if (this.properties.alias) {
+      sdtPrChildren.push(XMLBuilder.wSelf('alias', { 'w:val': this.properties.alias }));
+    }
+
+    // Add placeholder
+    if (this.properties.placeholder) {
+      sdtPrChildren.push(
+        XMLBuilder.w('placeholder', {}, [
+          XMLBuilder.wSelf('docPart', { 'w:val': this.properties.placeholder.docPart }),
+        ])
+      );
+    }
+
+    // Add showing placeholder flag
+    if (this.properties.showingPlcHdr !== undefined) {
+      sdtPrChildren.push(
+        XMLBuilder.wSelf('showingPlcHdr', {
+          'w:val': this.properties.showingPlcHdr ? 'true' : 'false',
+        })
+      );
+    }
+
+    // Add data binding
+    if (this.properties.dataBinding) {
+      const dbAttrs: Record<string, string> = {
+        'w:xpath': this.properties.dataBinding.xpath,
+      };
+      if (this.properties.dataBinding.prefixMappings) {
+        dbAttrs['w:prefixMappings'] = this.properties.dataBinding.prefixMappings;
+      }
+      if (this.properties.dataBinding.storeItemId) {
+        dbAttrs['w:storeItemID'] = this.properties.dataBinding.storeItemId;
+      }
+      sdtPrChildren.push(XMLBuilder.wSelf('dataBinding', dbAttrs));
+    }
+
+    // Add control type-specific XML
+    if (this.properties.controlType) {
+      switch (this.properties.controlType) {
+        case 'richText':
+          sdtPrChildren.push(XMLBuilder.wSelf('richText', {}));
+          break;
+
+        case 'plainText':
+          if (this.properties.plainText) {
+            const attrs: Record<string, string> = {};
+            if (this.properties.plainText.multiLine !== undefined) {
+              attrs['w:multiLine'] = this.properties.plainText.multiLine ? '1' : '0';
+            }
+            sdtPrChildren.push(XMLBuilder.wSelf('text', attrs));
+          } else {
+            sdtPrChildren.push(XMLBuilder.wSelf('text', {}));
+          }
+          break;
+
+        case 'comboBox':
+          if (this.properties.comboBox) {
+            const comboBoxChildren: XMLElement[] = [];
+            for (const item of this.properties.comboBox.items) {
+              comboBoxChildren.push(
+                XMLBuilder.wSelf('listItem', {
+                  'w:displayText': item.displayText,
+                  'w:value': item.value,
+                })
+              );
+            }
+            sdtPrChildren.push(XMLBuilder.w('comboBox', {}, comboBoxChildren));
+          }
+          break;
+
+        case 'dropDownList':
+          if (this.properties.dropDownList) {
+            const dropDownChildren: XMLElement[] = [];
+            for (const item of this.properties.dropDownList.items) {
+              dropDownChildren.push(
+                XMLBuilder.wSelf('listItem', {
+                  'w:displayText': item.displayText,
+                  'w:value': item.value,
+                })
+              );
+            }
+            sdtPrChildren.push(XMLBuilder.w('dropDownList', {}, dropDownChildren));
+          }
+          break;
+
+        case 'datePicker':
+          if (this.properties.datePicker) {
+            // Per ECMA-376, w:date has w:fullDate as attribute; dateFormat, lid,
+            // storeMappedDataAs, and calendar are child elements with w:val
+            const dateAttrs: Record<string, string> = {};
+            if (this.properties.datePicker.fullDate) {
+              dateAttrs['w:fullDate'] = this.properties.datePicker.fullDate.toISOString();
+            }
+            const dateChildren: XMLElement[] = [];
+            if (this.properties.datePicker.dateFormat) {
+              dateChildren.push(
+                XMLBuilder.wSelf('dateFormat', {
+                  'w:val': this.properties.datePicker.dateFormat,
+                })
+              );
+            }
+            if (this.properties.datePicker.lid) {
+              dateChildren.push(
+                XMLBuilder.wSelf('lid', {
+                  'w:val': this.properties.datePicker.lid,
+                })
+              );
+            }
+            if (this.properties.datePicker.calendar) {
+              dateChildren.push(
+                XMLBuilder.wSelf('calendar', {
+                  'w:val': this.properties.datePicker.calendar,
+                })
+              );
+            }
+            if (dateChildren.length > 0) {
+              sdtPrChildren.push(XMLBuilder.w('date', dateAttrs, dateChildren));
+            } else {
+              sdtPrChildren.push(XMLBuilder.wSelf('date', dateAttrs));
+            }
+          }
+          break;
+
+        case 'checkbox':
+          if (this.properties.checkbox) {
+            const checkboxChildren: XMLElement[] = [];
+
+            // Add checked state - use w14 namespace per OOXML spec
+            if (this.properties.checkbox.checked !== undefined) {
+              checkboxChildren.push(
+                XMLBuilder.w14Self('checked', {
+                  'w14:val': this.properties.checkbox.checked ? '1' : '0',
+                })
+              );
+            }
+
+            // Add checked state symbol - use w14 namespace per OOXML spec
+            if (this.properties.checkbox.checkedState) {
+              checkboxChildren.push(
+                XMLBuilder.w14Self('checkedState', {
+                  'w14:val': this.properties.checkbox.checkedState,
+                  'w14:font': 'MS Gothic',
+                })
+              );
+            }
+
+            // Add unchecked state symbol - use w14 namespace per OOXML spec
+            if (this.properties.checkbox.uncheckedState) {
+              checkboxChildren.push(
+                XMLBuilder.w14Self('uncheckedState', {
+                  'w14:val': this.properties.checkbox.uncheckedState,
+                  'w14:font': 'MS Gothic',
+                })
+              );
+            }
+
+            sdtPrChildren.push(XMLBuilder.w14('checkbox', {}, checkboxChildren));
+          }
+          break;
+
+        case 'picture':
+          sdtPrChildren.push(XMLBuilder.wSelf('picture', {}));
+          break;
+
+        case 'buildingBlock':
+          if (this.properties.buildingBlock) {
+            const bbChildren: XMLElement[] = [];
+            if (this.properties.buildingBlock.gallery) {
+              bbChildren.push(
+                XMLBuilder.wSelf('docPartGallery', {
+                  'w:val': this.properties.buildingBlock.gallery,
+                })
+              );
+            }
+            if (this.properties.buildingBlock.category) {
+              bbChildren.push(
+                XMLBuilder.wSelf('docPartCategory', {
+                  'w:val': this.properties.buildingBlock.category,
+                })
+              );
+            }
+            sdtPrChildren.push(XMLBuilder.w('docPartObj', {}, bbChildren));
+          }
+          break;
+
+        case 'group':
+          sdtPrChildren.push(XMLBuilder.wSelf('group', {}));
+          break;
+
+        case 'citation':
+          sdtPrChildren.push(XMLBuilder.wSelf('citation', {}));
+          break;
+
+        case 'bibliography':
+          sdtPrChildren.push(XMLBuilder.wSelf('bibliography', {}));
+          break;
+
+        case 'equation':
+          sdtPrChildren.push(XMLBuilder.wSelf('equation', {}));
+          break;
+
+        case 'docPartList':
+          if (this.properties.buildingBlock) {
+            const dplChildren: XMLElement[] = [];
+            if (this.properties.buildingBlock.gallery) {
+              dplChildren.push(
+                XMLBuilder.wSelf('docPartGallery', {
+                  'w:val': this.properties.buildingBlock.gallery,
+                })
+              );
+            }
+            if (this.properties.buildingBlock.category) {
+              dplChildren.push(
+                XMLBuilder.wSelf('docPartCategory', {
+                  'w:val': this.properties.buildingBlock.category,
+                })
+              );
+            }
+            sdtPrChildren.push(XMLBuilder.w('docPartList', {}, dplChildren));
+          }
+          break;
+      }
+    }
+
+    if (sdtPrChildren.length > 0) {
+      children.push(XMLBuilder.w('sdtPr', {}, sdtPrChildren));
+    }
+
+    // Build sdtContent
+    const sdtContentChildren: XMLElement[] = [];
+    for (const element of this.content) {
+      sdtContentChildren.push(element.toXML());
+    }
+
+    children.push(XMLBuilder.w('sdtContent', {}, sdtContentChildren));
+
+    return XMLBuilder.w('sdt', {}, children);
+  }
+
+  /**
+   * Create an SDT wrapping a table (common for Google Docs)
+   * @param table - Table to wrap
+   * @param tag - Optional tag value
+   * @param lock - Optional lock type (default: unlocked for editability)
+   * @returns New SDT instance
+   * @example
+   * ```typescript
+   * // Unlocked table (editable in Word) - RECOMMENDED
+   * const sdt = StructuredDocumentTag.wrapTable(table);
+   *
+   * // Locked table (read-only in Word)
+   * const lockedSdt = StructuredDocumentTag.wrapTable(table, 'my-table', 'contentLocked');
+   * ```
+   */
+  static wrapTable(table: Table, tag = 'goog_rdk_0', lock?: SDTLockType): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000, // Generate a reasonable ID
+        tag,
+        lock, // Only set if provided - defaults to unlocked
+      },
+      [table]
+    );
+  }
+
+  /**
+   * Create an SDT wrapping a paragraph
+   * @param paragraph - Paragraph to wrap
+   * @param tag - Optional tag value
+   * @returns New SDT instance
+   */
+  static wrapParagraph(paragraph: Paragraph, tag?: string): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        tag,
+      },
+      [paragraph]
+    );
+  }
+
+  /**
+   * Create an empty SDT
+   * @param properties - SDT properties
+   * @returns New SDT instance
+   */
+  static create(properties: SDTProperties = {}): StructuredDocumentTag {
+    return new StructuredDocumentTag(properties);
+  }
+
+  /**
+   * Create a rich text content control
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   * @returns New SDT instance
+   */
+  static createRichText(
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'richText',
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create a plain text content control
+   * @param content - Initial content
+   * @param multiLine - Allow multiple lines
+   * @param properties - Additional SDT properties
+   * @returns New SDT instance
+   */
+  static createPlainText(
+    content: SDTContent[] = [],
+    multiLine = false,
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'plainText',
+        plainText: { multiLine },
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create a combo box content control
+   * @param items - List items
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   * @returns New SDT instance
+   */
+  static createComboBox(
+    items: ListItem[],
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'comboBox',
+        comboBox: { items },
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create a dropdown list content control
+   * @param items - List items
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   * @returns New SDT instance
+   */
+  static createDropDownList(
+    items: ListItem[],
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'dropDownList',
+        dropDownList: { items },
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create a date picker content control
+   * @param dateFormat - Date format string (e.g., 'M/d/yyyy')
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   * @returns New SDT instance
+   */
+  static createDatePicker(
+    dateFormat = 'M/d/yyyy',
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'datePicker',
+        datePicker: { dateFormat },
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create a checkbox content control
+   * @param checked - Initial checked state
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   * @returns New SDT instance
+   */
+  static createCheckbox(
+    checked = false,
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'checkbox',
+        checkbox: {
+          checked,
+          checkedState: '2612', // ☒
+          uncheckedState: '2610', // ☐
+        },
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create a picture content control
+   * @param content - Initial content (typically contains an image)
+   * @param properties - Additional SDT properties
+   * @returns New SDT instance
+   */
+  static createPicture(
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'picture',
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create a building block content control
+   * @param gallery - Building block gallery name
+   * @param category - Building block category
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   * @returns New SDT instance
+   */
+  static createBuildingBlock(
+    gallery: string,
+    category: string,
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'buildingBlock',
+        buildingBlock: { gallery, category },
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create a group content control
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   * @returns New SDT instance
+   */
+  static createGroup(
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'group',
+        lock: 'sdtContentLocked', // Groups typically lock content
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Unlocks the SDT content (allows editing)
+   * Removes any lock that prevents content modification
+   * @returns This SDT for chaining
+   * @example
+   * ```typescript
+   * // Unlock a locked SDT to enable editing
+   * sdt.unlock();
+   *
+   * // Chain with other modifications
+   * sdt.unlock().setTag('editable-content');
+   * ```
+   */
+  unlock(): this {
+    delete this.properties.lock;
+    return this;
+  }
+
+  /**
+   * Checks if SDT content is locked in any way
+   * @returns True if content is locked (contentLocked, sdtLocked, or sdtContentLocked)
+   * @example
+   * ```typescript
+   * if (sdt.isLocked()) {
+   *   console.log('SDT is locked - unlocking for editing');
+   *   sdt.unlock();
+   * }
+   * ```
+   */
+  isLocked(): boolean {
+    const lock = this.properties.lock;
+    return lock === 'contentLocked' || lock === 'sdtContentLocked' || lock === 'sdtLocked';
+  }
+
+  /**
+   * Checks if SDT content can be edited by users
+   * @returns True if content can be modified (not locked by contentLocked or sdtContentLocked)
+   * @example
+   * ```typescript
+   * const editable = sdt.isContentEditable();
+   * console.log(editable ? 'Can edit' : 'Cannot edit');
+   * ```
+   */
+  isContentEditable(): boolean {
+    const lock = this.properties.lock;
+    return lock !== 'contentLocked' && lock !== 'sdtContentLocked';
+  }
+
+  /**
+   * Get the placeholder configuration
+   */
+  getPlaceholder(): SDTPlaceholder | undefined {
+    return this.properties.placeholder;
+  }
+
+  /**
+   * Set the placeholder (w:placeholder/w:docPart)
+   * @param docPart - Name of the document part to use as placeholder
+   */
+  setPlaceholder(docPart: string): this {
+    this.properties.placeholder = { docPart };
+    return this;
+  }
+
+  /**
+   * Get the data binding configuration
+   */
+  getDataBinding(): SDTDataBinding | undefined {
+    return this.properties.dataBinding;
+  }
+
+  /**
+   * Set the data binding (w:dataBinding)
+   * @param xpath - XPath expression
+   * @param prefixMappings - Namespace prefix mappings
+   * @param storeItemId - Custom XML data store item ID
+   */
+  setDataBinding(xpath: string, prefixMappings?: string, storeItemId?: string): this {
+    this.properties.dataBinding = { xpath, prefixMappings, storeItemId };
+    return this;
+  }
+
+  /**
+   * Get whether the SDT is currently showing placeholder content
+   */
+  isShowingPlaceholder(): boolean {
+    return this.properties.showingPlcHdr === true;
+  }
+
+  /**
+   * Set whether the SDT is showing placeholder content
+   * @param val - Whether placeholder is showing
+   */
+  setShowingPlaceholder(val: boolean): this {
+    this.properties.showingPlcHdr = val;
+    return this;
+  }
+
+  /**
+   * Create a citation content control
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   */
+  static createCitation(
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'citation',
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create a bibliography content control
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   */
+  static createBibliography(
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'bibliography',
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create a document part list content control
+   * Uses w:docPartList instead of w:docPartObj
+   * @param gallery - Building block gallery name
+   * @param category - Building block category
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   */
+  static createDocPartList(
+    gallery: string,
+    category: string,
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'docPartList',
+        buildingBlock: { gallery, category, isList: true },
+        ...properties,
+      },
+      content
+    );
+  }
+
+  /**
+   * Create an equation content control
+   * @param content - Initial content
+   * @param properties - Additional SDT properties
+   */
+  static createEquation(
+    content: SDTContent[] = [],
+    properties: Partial<SDTProperties> = {}
+  ): StructuredDocumentTag {
+    return new StructuredDocumentTag(
+      {
+        id: Date.now() % 1000000000,
+        controlType: 'equation',
+        ...properties,
+      },
+      content
+    );
+  }
+}