python-hwpx 5.2.0__tar.gz → 5.4.0__tar.gz

{python_hwpx-5.2.0/src/python_hwpx.egg-info → python_hwpx-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 5.2.0
+Version: 5.4.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0

{python_hwpx-5.2.0 → python_hwpx-5.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "5.2.0"
+version = "5.4.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"

{python_hwpx-5.2.0 → python_hwpx-5.4.0}/src/hwpx/_document/layout.py

@@ -425,17 +425,28 @@ def add_hyperlink(
     paragraph: HwpxOxmlParagraph | None = None,
     section: HwpxOxmlSection | None = None,
     section_index: int | None = None,
+    char_pr_id_ref: str | int | None = None,
 ) -> HwpxOxmlInlineObject:
     """Insert a hyperlink (fieldBegin + text + fieldEnd).
 
+    The display text follows the Hancom convention (blue ``#0000FF`` text
+    with a blue bottom underline — dominant styling across real-corpus
+    hyperlinks) unless ``char_pr_id_ref`` overrides it.
+
     Returns the ``<hp:ctrl>`` wrapper containing the ``<hp:fieldBegin>``.
     """
+    if char_pr_id_ref is None:
+        char_pr_id_ref = doc.ensure_run_style(
+            underline=True,
+            color="#0000FF",
+            underline_color="#0000FF",
+        )
     if paragraph is None:
         paragraph = doc.add_paragraph(
             "", section=section, section_index=section_index,
             include_run=False,
         )
-    return paragraph.add_hyperlink(url, display_text)
+    return paragraph.add_hyperlink(url, display_text, char_pr_id_ref=char_pr_id_ref)
 
 
 def _resolve_section(

{python_hwpx-5.2.0 → python_hwpx-5.4.0}/src/hwpx/_document/shapes.py

@@ -282,3 +282,78 @@ def add_equation(
     raise RuntimeError(
         "created equation was not recognized by the standard section scan"
     )
+
+
+def add_chart(
+    doc: "HwpxDocument",
+    chart_xml: bytes | str,
+    *,
+    paragraph: HwpxOxmlParagraph | None = None,
+    section: HwpxOxmlSection | None = None,
+    section_index: int | None = None,
+    size: tuple[int, int] | None = None,
+    treat_as_char: bool = False,
+    char_pr_id_ref: str | int | None = None,
+) -> HwpxOxmlInlineObject:
+    """Add a chartML part and its ``<hp:chart>`` anchor, then prove recognition.
+
+    The part is stored under ``Chart/chartN.xml`` and addressed directly by
+    the anchor's ``chartIDRef`` — real Hancom registers chart parts in no
+    manifest and draws the chart from the ECMA-376 chartML alone
+    (specs/055-chart-authoring/evidence/p0/chart-contract.md). The chartML is
+    validated to parse and to carry the ``c:chartSpace`` root before any part
+    is written; after insertion the anchor is re-read through the standard
+    section scan — creation fails loudly if it did not land (no
+    special-casing by design).
+    """
+    from lxml import etree as _etree  # type: ignore[reportAttributeAccessIssue]  # lxml has no complete bundled typing
+
+    from ..oxml.namespaces import HP
+
+    _CHART_SPACE = "{http://schemas.openxmlformats.org/drawingml/2006/chart}chartSpace"
+
+    data = chart_xml.encode("utf-8") if isinstance(chart_xml, str) else bytes(chart_xml)
+    if not data.strip():
+        raise ValueError("chart_xml must be non-empty chartML")
+    try:
+        root = _etree.fromstring(data)
+    except _etree.XMLSyntaxError as exc:
+        raise ValueError(f"chart_xml is not well-formed XML: {exc}") from exc
+    if root.tag != _CHART_SPACE:
+        raise ValueError(
+            "chart_xml root must be the ECMA-376 c:chartSpace element, "
+            f"got {root.tag!r}"
+        )
+
+    existing = {name for name in doc._package.part_names() if name.startswith("Chart/")}
+    n = 1
+    while f"Chart/chart{n}.xml" in existing:
+        n += 1
+    part_path = f"Chart/chart{n}.xml"
+
+    if paragraph is None:
+        paragraph = doc.add_paragraph(
+            "", section=section, section_index=section_index,
+            include_run=False,
+        )
+    doc._package.write(part_path, data)
+    inline_object = paragraph.add_chart(
+        part_path,
+        size=size,
+        treat_as_char=treat_as_char,
+        char_pr_id_ref=char_pr_id_ref,
+    )
+
+    created_id = inline_object.element.get("id", "")
+    for owning_section in doc.sections:
+        for candidate in owning_section.element.iter(f"{HP}chart"):
+            if candidate.get("id") != created_id:
+                continue
+            if candidate.get("chartIDRef") != part_path:
+                raise RuntimeError(
+                    "created chart anchor does not reference its part"
+                )
+            return inline_object
+    raise RuntimeError(
+        "created chart was not recognized by the standard section scan"
+    )

{python_hwpx-5.2.0 → python_hwpx-5.4.0}/src/hwpx/document.py

@@ -264,14 +264,21 @@ class HwpxDocument:
         border_width: str = "0.12 mm",
         fill_color: str | None = None,
         active_borders: Sequence[str] | None = None,
+        border_type: str = "SOLID",
     ) -> str:
-        """Return a borderFill id matching the requested border/fill attributes."""
+        """Return a borderFill id matching the requested border/fill attributes.
+
+        ``border_type`` selects the OWPML line style (``SOLID``, ``DASH``,
+        ``DOT``, ``DOUBLE_SLIM``, ``WAVE``, …); values outside the OWPML
+        vocabulary are rejected.
+        """
 
         return self._root.ensure_border_fill(
             border_color=border_color,
             border_width=border_width,
             fill_color=fill_color,
             active_borders=active_borders,
+            border_type=border_type,
         )
 
     @property
@@ -594,9 +601,22 @@ class HwpxDocument:
         size: int | float | None = None,
         highlight: str | None = None,
         strike: bool | None = None,
+        underline_shape: str | None = None,
+        underline_color: str | None = None,
+        strike_shape: str | None = None,
+        ratio: int | None = None,
+        letter_spacing: int | None = None,
+        shadow: str | None = None,
+        script: str | None = None,
         base_char_pr_id: str | int | None = None,
     ) -> str:
-        """Return a ``charPr`` identifier matching the requested flags."""
+        """Return a ``charPr`` identifier matching the requested flags.
+
+        5.4.0 additions (render-verified vocabulary; invalid values are
+        rejected): ``underline_shape``/``underline_color``, ``strike_shape``,
+        ``ratio`` (장평 %), ``letter_spacing`` (자간 %), ``shadow`` (drop
+        shadow colour), ``script`` (``"sup"``/``"sub"``).
+        """
 
         return self._root.ensure_run_style(
             bold=bold,
@@ -607,6 +627,13 @@ class HwpxDocument:
             size=size,
             highlight=highlight,
             strike=strike,
+            underline_shape=underline_shape,
+            underline_color=underline_color,
+            strike_shape=strike_shape,
+            ratio=ratio,
+            letter_spacing=letter_spacing,
+            shadow=shadow,
+            script=script,
             base_char_pr_id=base_char_pr_id,
         )
 
@@ -1373,9 +1400,13 @@ class HwpxDocument:
         paragraph: HwpxOxmlParagraph | None = None,
         section: HwpxOxmlSection | None = None,
         section_index: int | None = None,
+        char_pr_id_ref: str | int | None = None,
     ) -> HwpxOxmlInlineObject:
         """Insert a hyperlink (fieldBegin + text + fieldEnd).
 
+        The display text follows the Hancom convention (blue underlined)
+        unless ``char_pr_id_ref`` overrides it.
+
         Returns the ``<hp:ctrl>`` wrapper containing the ``<hp:fieldBegin>``.
         """
 
@@ -1386,6 +1417,7 @@ class HwpxDocument:
             paragraph=paragraph,
             section=section,
             section_index=section_index,
+            char_pr_id_ref=char_pr_id_ref,
         )
 
     def add_form_field(
@@ -1431,6 +1463,48 @@ class HwpxDocument:
         )
 
 
+    def add_chart(
+        self,
+        chart_xml: bytes | str,
+        *,
+        paragraph: HwpxOxmlParagraph | None = None,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+        size: tuple[int, int] | None = None,
+        treat_as_char: bool = False,
+        char_pr_id_ref: str | int | None = None,
+    ) -> HwpxOxmlInlineObject:
+        """Insert a native chart from ECMA-376 chartML. **Experimental contract.**
+
+        Stores *chart_xml* as a ``Chart/chartN.xml`` package part and emits the
+        real-Hancom ``<hp:chart>`` anchor referencing it via ``chartIDRef``
+        (contract: ``specs/055-chart-authoring/evidence/p0/chart-contract.md``).
+        Hancom draws the chart from the chartML alone — no OLE fallback or
+        pre-rendered image is written. The chartML must parse and carry the
+        ``c:chartSpace`` root (typed rejection otherwise), and the created
+        anchor is re-read through the standard section scan — creation fails
+        loudly if the standard consumer would not see it.
+
+        Args:
+            chart_xml: ECMA-376 chartML document (``c:chartSpace``).
+            paragraph: Target paragraph (e.g. inside a table cell). When
+                omitted a new paragraph is appended to *section*.
+            size: Optional ``(width, height)`` HWPUNIT pair for the anchor.
+            treat_as_char: ``True`` places the chart inline in the text flow;
+                default mirrors the render-verified gold float placement.
+        """
+
+        return _shapes.add_chart(
+            self,
+            chart_xml,
+            paragraph=paragraph,
+            section=section,
+            section_index=section_index,
+            size=size,
+            treat_as_char=treat_as_char,
+            char_pr_id_ref=char_pr_id_ref,
+        )
+
     def add_equation(
         self,
         script: str,

{python_hwpx-5.2.0 → python_hwpx-5.4.0}/src/hwpx/oxml/_document_primitives.py

@@ -422,9 +422,10 @@ def _border_fill_child_attrs(
     active: bool,
     color: str,
     width: str,
+    border_type: str = "SOLID",
 ) -> dict[str, str]:
     return {
-        "type": "SOLID" if active else "NONE",
+        "type": border_type if active else "NONE",
         "width": width,
         "color": color,
     }
@@ -465,6 +466,7 @@ def _border_fill_matches(
     border_width: str,
     fill_color: str | None,
     active_borders: set[str],
+    border_type: str = "SOLID",
 ) -> bool:
     if _element_local_name(element) != "borderFill":
         return False
@@ -484,7 +486,7 @@ def _border_fill_matches(
         child = element.find(f"{_HH}{child_name}")
         if child is None:
             return False
-        expected_type = "SOLID" if side in active_borders else "NONE"
+        expected_type = border_type if side in active_borders else "NONE"
         if (child.get("type") or "").upper() != expected_type:
             return False
         if _normalize_length(child.get("width")) != _normalize_length(border_width):
@@ -509,6 +511,7 @@ def _create_border_fill_element(
     border_width: str,
     fill_color: str | None,
     active_borders: set[str],
+    border_type: str = "SOLID",
 ) -> ET.Element:
     element = ET.Element(f"{_HH}borderFill", {"id": border_id, **_BASIC_BORDER_FILL_ATTRIBUTES})
     ET.SubElement(element, f"{_HH}slash", {"type": "NONE", "Crooked": "0", "isCounter": "0"})
@@ -521,6 +524,7 @@ def _create_border_fill_element(
                 active=side in active_borders,
                 color=border_color,
                 width=border_width,
+                border_type=border_type,
             ),
         )
     ET.SubElement(
@@ -579,6 +583,17 @@ def _default_cell_margin_attributes() -> dict[str, str]:
     return {"left": "0", "right": "0", "top": "0", "bottom": "0"}
 
 
+def _default_cell_inner_margin_attributes() -> dict[str, str]:
+    """Hancom's new-table cell padding: 1.8 mm left/right, 0.5 mm top/bottom.
+
+    Measured from real Hancom-authored gold documents
+    (specs/056-authoring-fidelity-audit — the audit found our former 0
+    padding makes text hug the borders, visibly unlike a Hancom table).
+    """
+
+    return {"left": "510", "right": "510", "top": "141", "bottom": "141"}
+
+
 def _get_int_attr(element: ET.Element, name: str, default: int = 0) -> int:
     """Return *name* attribute of *element* as an integer."""
 

{python_hwpx-5.2.0 → python_hwpx-5.4.0}/src/hwpx/oxml/document_parts.py

@@ -59,6 +59,13 @@ class _RunStyleSpec:
     height: str | None
     strike: bool | None
     font_ref: dict[str, str] | None
+    underline_shape: str | None = None
+    underline_color: str | None = None
+    strike_shape: str | None = None
+    ratio: int | None = None
+    letter_spacing: int | None = None
+    shadow_color: str | None = None
+    script: str | None = None
 
 
 def _run_style_element_flags(element: ET.Element) -> tuple[bool, bool, bool]:
@@ -78,6 +85,81 @@ def _run_style_element_strike(element: ET.Element) -> bool:
     return strike_element.get("shape", "").upper() != "NONE"
 
 
+def _validated_line_shape(
+    value: str | None, vocabulary: frozenset[str], label: str
+) -> str | None:
+    if value is None:
+        return None
+    normalized = str(value).upper()
+    if normalized not in vocabulary:
+        raise ValueError(f"unsupported {label} {value!r}")
+    return normalized
+
+
+def _run_style_underline_matches(element: ET.Element, spec: _RunStyleSpec) -> bool:
+    if spec.underline_shape is None and spec.underline_color is None:
+        return True
+    underline = element.find(f"{_HH}underline")
+    if underline is None:
+        return False
+    if spec.underline_shape is not None and (
+        underline.get("shape", "").upper() != spec.underline_shape
+    ):
+        return False
+    if spec.underline_color is not None and (
+        (underline.get("color") or "").upper() != spec.underline_color.upper()
+    ):
+        return False
+    return True
+
+
+def _run_style_lang_value_matches(
+    element: ET.Element, tag: str, value: int | None
+) -> bool:
+    if value is None:
+        return True
+    node = element.find(f"{_HH}{tag}")
+    return node is not None and node.get("hangul") == str(value)
+
+
+def _run_style_extensions_match(element: ET.Element, spec: _RunStyleSpec) -> bool:
+    if not _run_style_underline_matches(element, spec):
+        return False
+    if spec.strike_shape is not None:
+        strike_el = element.find(f"{_HH}strikeout")
+        if strike_el is None or strike_el.get("shape", "").upper() != spec.strike_shape:
+            return False
+    if not _run_style_lang_value_matches(element, "ratio", spec.ratio):
+        return False
+    if not _run_style_lang_value_matches(element, "spacing", spec.letter_spacing):
+        return False
+    if not _run_style_shadow_matches(element, spec.shadow_color):
+        return False
+    if not _run_style_script_matches(element, spec.script):
+        return False
+    return True
+
+
+def _run_style_shadow_matches(element: ET.Element, shadow_color: str | None) -> bool:
+    if shadow_color is None:
+        return True
+    shadow_el = element.find(f"{_HH}shadow")
+    if shadow_el is None or shadow_el.get("type", "").upper() == "NONE":
+        return False
+    return (shadow_el.get("color") or "").upper() == shadow_color.upper()
+
+
+def _run_style_script_matches(element: ET.Element, script: str | None) -> bool:
+    if script is None:
+        return True
+    if not _run_style_lang_value_matches(element, "relSz", 67):
+        return False
+    off_el = element.find(f"{_HH}offset")
+    # 실한컴 렌더 실측: offset 음수=위로(위첨자), 양수=아래로(아래첨자).
+    wanted_offset = "-30" if script == "sup" else "30"
+    return off_el is not None and off_el.get("hangul") == wanted_offset
+
+
 def _run_style_predicate(element: ET.Element, spec: _RunStyleSpec) -> bool:
     if _run_style_element_flags(element) != spec.flags:
         return False
@@ -92,6 +174,8 @@ def _run_style_predicate(element: ET.Element, spec: _RunStyleSpec) -> bool:
         return False
     if spec.strike is not None and _run_style_element_strike(element) != bool(spec.strike):
         return False
+    if not _run_style_extensions_match(element, spec):
+        return False
     if spec.font_ref is not None:
         font_ref = element.find(f"{_HH}fontRef")
         if font_ref is None:
@@ -127,9 +211,10 @@ def _run_style_apply_underline(
 ) -> None:
     underline_attrs = dict(base_underline_attrs)
     if want_underline:
-        underline_attrs.setdefault("type", "SOLID")
-        if underline_attrs.get("type", "").upper() == "NONE":
-            underline_attrs["type"] = "SOLID"
+        # 실한컴 gold 관례: hh:underline type은 위치 어휘(BOTTOM/CENTER/TOP).
+        underline_attrs.setdefault("type", "BOTTOM")
+        if underline_attrs.get("type", "").upper() in ("NONE", "SOLID"):
+            underline_attrs["type"] = "BOTTOM"
         underline_attrs.setdefault(
             "shape", base_underline_attrs.get("shape", "SOLID")
         )
@@ -159,6 +244,56 @@ def _run_style_apply_strikeout(
         _append_child(element, f"{_HH}strikeout", strike_attrs)
 
 
+def _run_style_set_lang_values(element: ET.Element, tag: str, value: int) -> None:
+    node = element.find(f"{_HH}{tag}")
+    if node is None:
+        node = _append_child(element, f"{_HH}{tag}")
+    for lang in ("hangul", "latin", "hanja", "japanese", "other", "symbol", "user"):
+        node.set(lang, str(value))
+
+
+def _run_style_apply_underline_extension(
+    element: ET.Element, spec: _RunStyleSpec
+) -> None:
+    if spec.underline_shape is None and spec.underline_color is None:
+        return
+    underline = element.find(f"{_HH}underline")
+    if underline is None:
+        return
+    if underline.get("type", "").upper() == "NONE":
+        underline.set("type", "BOTTOM")
+    if spec.underline_shape is not None:
+        underline.set("shape", spec.underline_shape)
+    if spec.underline_color is not None:
+        underline.set("color", spec.underline_color)
+
+
+def _run_style_apply_extensions(element: ET.Element, spec: _RunStyleSpec) -> None:
+    _run_style_apply_underline_extension(element, spec)
+    if spec.strike_shape is not None:
+        strike_el = element.find(f"{_HH}strikeout")
+        if strike_el is None:
+            strike_el = _append_child(element, f"{_HH}strikeout")
+        strike_el.set("shape", spec.strike_shape)
+        if not strike_el.get("color"):
+            strike_el.set("color", "#000000")
+    if spec.ratio is not None:
+        _run_style_set_lang_values(element, "ratio", spec.ratio)
+    if spec.letter_spacing is not None:
+        _run_style_set_lang_values(element, "spacing", spec.letter_spacing)
+    if spec.shadow_color is not None:
+        shadow_el = element.find(f"{_HH}shadow")
+        if shadow_el is None:
+            shadow_el = _append_child(element, f"{_HH}shadow")
+        shadow_el.set("type", "DROP")
+        shadow_el.set("color", spec.shadow_color)
+        shadow_el.set("offsetX", "12")
+        shadow_el.set("offsetY", "12")
+    if spec.script is not None:
+        _run_style_set_lang_values(element, "relSz", 67)
+        _run_style_set_lang_values(element, "offset", -30 if spec.script == "sup" else 30)
+
+
 def _run_style_modifier(element: ET.Element, spec: _RunStyleSpec) -> None:
     underline_nodes = list(element.findall(f"{_HH}underline"))
     base_underline_attrs = (
@@ -186,6 +321,8 @@ def _run_style_modifier(element: ET.Element, spec: _RunStyleSpec) -> None:
     _run_style_apply_underline(element, base_underline_attrs, spec.flags[2])
     _run_style_apply_strikeout(element, base_strike_attrs, spec.strike)
 
+    _run_style_apply_extensions(element, spec)
+
 
 class HwpxOxmlDocument:
     """Aggregates the XML parts that make up an HWPX document."""
@@ -357,6 +494,12 @@ class HwpxOxmlDocument:
             return None
         return cache.get(normalized)
 
+    _UNDERLINE_SHAPES = frozenset({
+        "SOLID", "DASH", "DOT", "DASH_DOT", "DASH_DOT_DOT", "LONG_DASH",
+        "CIRCLE", "DOUBLE_SLIM", "SLIM_THICK", "THICK_SLIM",
+        "SLIM_THICK_SLIM", "WAVE", "DOUBLEWAVE",
+    })
+
     def ensure_run_style(
         self,
         *,
@@ -368,13 +511,45 @@ class HwpxOxmlDocument:
         size: int | float | None = None,
         highlight: str | None = None,
         strike: bool | None = None,
+        underline_shape: str | None = None,
+        underline_color: str | None = None,
+        strike_shape: str | None = None,
+        ratio: int | None = None,
+        letter_spacing: int | None = None,
+        shadow: str | None = None,
+        script: str | None = None,
         base_char_pr_id: str | int | None = None,
     ) -> str:
-        """Return a char property identifier matching the requested flags."""
+        """Return a char property identifier matching the requested flags.
+
+        The 5.4.0 additions mirror what the fidelity audit render-verified on
+        real Hancom: ``underline_shape``/``underline_color`` (implies an
+        underline), ``strike_shape`` (implies a strikeout), ``ratio`` (장평 %),
+        ``letter_spacing`` (자간 %), ``shadow`` (drop-shadow colour), and
+        ``script`` (``"sup"``/``"sub"``). Values outside the OWPML vocabulary
+        are rejected — no silent approximation.
+        """
 
         if not self._headers:
             raise ValueError("document does not contain any headers")
 
+        normalized_underline_shape = _validated_line_shape(
+            underline_shape, self._UNDERLINE_SHAPES, "underline_shape"
+        )
+        if normalized_underline_shape is not None or underline_color is not None:
+            underline = True
+        normalized_strike_shape = _validated_line_shape(
+            strike_shape, self._UNDERLINE_SHAPES, "strike_shape"
+        )
+        if normalized_strike_shape is not None:
+            strike = True
+        if ratio is not None and not 10 <= int(ratio) <= 400:
+            raise ValueError("ratio must be a percentage between 10 and 400")
+        if letter_spacing is not None and not -50 <= int(letter_spacing) <= 100:
+            raise ValueError("letter_spacing must be between -50 and 100")
+        if script is not None and script not in ("sup", "sub"):
+            raise ValueError('script must be "sup" or "sub"')
+
         header = self._headers[0]
         spec = _RunStyleSpec(
             flags=(bool(bold), bool(italic), bool(underline)),
@@ -383,6 +558,13 @@ class HwpxOxmlDocument:
             height=_char_height_from_points(size),
             strike=strike,
             font_ref=header.font_ref_for_face(font) if font is not None else None,
+            underline_shape=normalized_underline_shape,
+            underline_color=_normalize_color(underline_color),
+            strike_shape=normalized_strike_shape,
+            ratio=int(ratio) if ratio is not None else None,
+            letter_spacing=int(letter_spacing) if letter_spacing is not None else None,
+            shadow_color=_normalize_color(shadow),
+            script=script,
         )
         element = header.ensure_char_property(
             predicate=lambda el: _run_style_predicate(el, spec),
@@ -425,6 +607,7 @@ class HwpxOxmlDocument:
         border_width: str = "0.12 mm",
         fill_color: str | None = None,
         active_borders: Iterable[str] | None = None,
+        border_type: str = "SOLID",
     ) -> str:
         if not self._headers:
             return "0"
@@ -433,6 +616,7 @@ class HwpxOxmlDocument:
             border_width=border_width,
             fill_color=fill_color,
             active_borders=active_borders,
+            border_type=border_type,
         )
 
     def ensure_shading_border_fill(

{python_hwpx-5.2.0 → python_hwpx-5.4.0}/src/hwpx/oxml/header_part.py

@@ -898,6 +898,13 @@ class HwpxOxmlHeader:
         self.mark_dirty()
         return new_id
 
+    _BORDER_LINE_TYPES = frozenset({
+        "SOLID", "DASH", "DOT", "DASH_DOT", "DASH_DOT_DOT", "LONG_DASH",
+        "CIRCLE", "DOUBLE_SLIM", "SLIM_THICK", "THICK_SLIM", "SLIM_THICK_SLIM",
+        "WAVE", "DOUBLEWAVE", "THICK_3D", "THICK_3D_REVERSE_LIGHTING",
+        "SLIM_3D", "SLIM_3D_REVERSE_LIGHTING",
+    })
+
     def ensure_border_fill(
         self,
         *,
@@ -905,11 +912,18 @@ class HwpxOxmlHeader:
         border_width: str = "0.12 mm",
         fill_color: str | None = None,
         active_borders: Iterable[str] | None = None,
+        border_type: str = "SOLID",
     ) -> str:
         element = self._border_fills_element(create=True)
         if element is None:  # pragma: no cover - defensive branch
             raise RuntimeError("failed to create <borderFills> element")
 
+        normalized_border_type = str(border_type or "SOLID").upper()
+        if normalized_border_type not in self._BORDER_LINE_TYPES:
+            raise ValueError(
+                f"unsupported border_type {border_type!r}; expected one of "
+                + ", ".join(sorted(self._BORDER_LINE_TYPES))
+            )
         normalized_border_color = _normalize_color(border_color) or "#BFBFBF"
         normalized_border_width = str(border_width or "0.12 mm")
         normalized_active_borders = _normalize_border_side_names(active_borders)
@@ -922,6 +936,7 @@ class HwpxOxmlHeader:
                 border_width=normalized_border_width,
                 fill_color=normalized_fill_color,
                 active_borders=normalized_active_borders,
+                border_type=normalized_border_type,
             ):
                 border_id = border_fill.get("id")
                 if border_id:
@@ -934,6 +949,7 @@ class HwpxOxmlHeader:
             border_width=normalized_border_width,
             fill_color=normalized_fill_color,
             active_borders=normalized_active_borders,
+            border_type=normalized_border_type,
         )
         if isinstance(element, LET._Element):
             new_border_fill = LET.fromstring(ET.tostring(new_border_fill, encoding="utf-8"))