python-hwpx 6.6.0__py3-none-any.whl → 6.8.0__py3-none-any.whl

hwpx/__init__.py

@@ -14,7 +14,7 @@
 import importlib
 import warnings
 from dataclasses import dataclass
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 
 def _resolve_version() -> str:
@@ -28,9 +28,9 @@ def _resolve_version() -> str:
 
 # --- experimental / deprecated 최상위 표면 (지연 접근, 접근 시 경고) ---------------
 #
-# stable 이름은 아래에서 eager import 되어 모듈 전역에 존재하므로 ``__getattr__``이
-# 호출되지 않습니다(=경고 없음). 여기 등록된 이름만 지연 해석되어 경고를 냅니다.
-# 4.0.0에서 제거되는 이름은 0개 — 모두 계속 import 가능합니다.
+# stable 이름은 경고 없이 해석됩니다. 대부분 아래에서 eager import 되고, ``hwpx.tools``의
+# 이름은 ``_TOOLS_STABLE_EXPORTS``가 지연 해석합니다. 여기 등록된 이름만 지연 해석되어
+# 경고를 냅니다. 4.0.0에서 제거되는 이름은 0개 — 모두 계속 import 가능합니다.
 
 _EXPERIMENTAL_EXPORTS = {
     # 문서 ingestion 프레임워크(임의 포맷 -> HWPX). 계약 유동.
@@ -45,6 +45,10 @@ _EXPERIMENTAL_EXPORTS = {
     "LayoutPreview": "hwpx.tools.layout_preview",
     "PreviewPage": "hwpx.tools.layout_preview",
     "render_layout_preview": "hwpx.tools.layout_preview",
+    # 쪽 수 추정(한/글 없이, 줄마다 쪽·단·세로 위치). 계약 유동.
+    "EstimatedLine": "hwpx.layout.pages",
+    "PageEstimate": "hwpx.layout.pages",
+    "estimate_pages": "hwpx.layout.pages",
     # 문서 프리뷰 뷰어(3.8.0 신규). 계약 유동.
     "DocumentViewer": "hwpx.tools.document_viewer",
     "render_document_viewer": "hwpx.tools.document_viewer",
@@ -289,8 +293,8 @@ class RetiredSurface(ImportError):
 def __getattr__(name: str) -> object:
     """Resolve dynamic module attributes.
 
-    ``__version__``은 경고 없이 지연 해석하고, experimental/deprecated 이름은
-    해석 시 ``DeprecationWarning``을 냅니다.
+    ``__version__``과 ``hwpx.tools``의 stable 이름은 경고 없이 지연 해석하고,
+    experimental/deprecated 이름은 해석 시 ``DeprecationWarning``을 냅니다.
     """
 
     if name == "__version__":
@@ -314,6 +318,17 @@ def __getattr__(name: str) -> object:
         warnings.warn(_deprecated_message(name), DeprecationWarning, stacklevel=2)
         return getattr(importlib.import_module(module_name), name)
 
+    if name in _TOOLS_STABLE_EXPORTS or name == "tools":
+        # Not ``from . import tools``: that asks this module for ``tools`` first and
+        # re-enters this function.
+        import hwpx.tools as tools
+
+        if name == "tools":
+            return tools
+        value = getattr(tools, name)
+        globals()[name] = value
+        return value
+
     moved = _MOVED_TO_COMPANION.get(name)
     if moved is not None:
         statement = moved.import_statement(name)
@@ -342,41 +357,87 @@ def __dir__() -> list[str]:
     return sorted(
         set(globals())
         | set(__all__)
+        | {"tools"}
         | set(_EXPERIMENTAL_EXPORTS)
         | set(_DEPRECATED_EXPORTS)
     )
 
 
-# --- stable 최상위 표면 (eager import) ------------------------------------------
-from .tools.text_extractor import (
-    DEFAULT_NAMESPACES,
-    ParagraphInfo,
-    SectionInfo,
-    TextExtractor,
-)
-from .tools.object_finder import FoundElement, ObjectFinder
-from .tools.doc_diff import (
-    DOC_DIFF_REPORT_VERSION,
-    REFERENCE_CONSISTENCY_REPORT_VERSION,
-    diff_paragraphs,
-    doc_diff,
-    inspect_reference_consistency,
-)
-from .tools.mail_merge import (
-    MAIL_MERGE_REPORT_VERSION,
-    inspect_mail_merge_placeholders,
-    load_mail_merge_rows,
-    merge_template_rows,
-)
-from .tools.package_validator import (
-    EditorOpenSafetyReport,
-    PackageValidationReport,
-    validate_editor_open_safety,
-    validate_package,
+# --- 지연 stable 최상위 표면 (첫 접근 때 해석, 경고 없음) ---------------------------
+#
+# ``hwpx.tools``에 사는 stable 이름은 첫 접근 때 ``__getattr__``이 그 모듈을 읽어
+# 같은 객체를 돌려주고 모듈 전역에 둡니다(경고 없음). ``import hwpx``가 도구 모듈
+# 전부(내보내기·비교·검증 등)를 읽지 않게 하려는 것입니다. ``__all__``·``dir()``·
+# ``from hwpx import *``에는 그대로 있습니다.
+
+#: ``hwpx.tools``의 하위 모듈이 정의하고 ``hwpx.tools``가 다시 내보내는 stable 이름(텍스트 추출·개체
+#: 찾기·문서 비교·메일 머지·패키지 검증). 정적 import로 해석하므로 동적 import 지점은
+#: 늘지 않는다.
+_TOOLS_STABLE_EXPORTS = frozenset(
+    {
+        "DEFAULT_NAMESPACES",
+        "ParagraphInfo",
+        "SectionInfo",
+        "TextExtractor",
+        "FoundElement",
+        "ObjectFinder",
+        "DOC_DIFF_REPORT_VERSION",
+        "REFERENCE_CONSISTENCY_REPORT_VERSION",
+        "diff_paragraphs",
+        "doc_diff",
+        "inspect_reference_consistency",
+        "MAIL_MERGE_REPORT_VERSION",
+        "inspect_mail_merge_placeholders",
+        "load_mail_merge_rows",
+        "merge_template_rows",
+        "EditorOpenSafetyReport",
+        "PackageValidationReport",
+        "validate_editor_open_safety",
+        "validate_package",
+    }
 )
+
+
+if TYPE_CHECKING:  # type checkers see the real objects; at runtime they load lazily
+    from .tools.doc_diff import (
+        DOC_DIFF_REPORT_VERSION,
+        REFERENCE_CONSISTENCY_REPORT_VERSION,
+        diff_paragraphs,
+        doc_diff,
+        inspect_reference_consistency,
+    )
+    from .tools.mail_merge import (
+        MAIL_MERGE_REPORT_VERSION,
+        inspect_mail_merge_placeholders,
+        load_mail_merge_rows,
+        merge_template_rows,
+    )
+    from .tools.object_finder import FoundElement, ObjectFinder
+    from .tools.package_validator import (
+        EditorOpenSafetyReport,
+        PackageValidationReport,
+        validate_editor_open_safety,
+        validate_package,
+    )
+    from .tools.text_extractor import (
+        DEFAULT_NAMESPACES,
+        ParagraphInfo,
+        SectionInfo,
+        TextExtractor,
+    )
+
+
+# ``import hwpx.builder`` goes through the import system, not ``__getattr__``,
+# so the moved module names get their destination from a finder instead.
+from . import _moved_modules
+
+_moved_modules.install(_MOVED_TO_COMPANION)
+
+
+# --- stable 최상위 표면 (eager import) ------------------------------------------
+# ``hwpx.tools``의 stable 이름은 위 ``_TOOLS_STABLE_EXPORTS``가 지연 해석한다.
 from .ingest import HwpxMarkdownConverter
-from .errors import HwpxError
-from .hwp5.errors import Hwp5ConversionWarning, Hwp5Error
+from .errors import Hwp5ConversionWarning, Hwp5Error, HwpxError
 from .mutation_report import (
     MutationReport,
     PreservationDowngradeError,

hwpx/_document/_legacy.py

@@ -615,7 +615,7 @@ class _LegacyFacade:
         field_id: str | None = None,
         author: str | None = None,
         created: datetime | str | None = None,
-        number: int = 1,
+        number: int | None = None,
         anchor_char_pr_id_ref: str | int | None = None,
     ) -> tuple[HwpxOxmlMemo, HwpxOxmlParagraph, str]:
         """Create a memo and ensure it is visible by anchoring a MEMO field."""
@@ -801,7 +801,7 @@ class _LegacyFacade:
         field_id: str | None = None,
         author: str | None = None,
         created: datetime | str | None = None,
-        number: int = 1,
+        number: int | None = None,
         char_pr_id_ref: str | int | None = None,
     ) -> str:
         """Attach a MEMO field control to *paragraph* so Hangul shows *memo*."""

hwpx/_document/fields.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, Any, Iterator, Mapping, Sequence, cast
 
 from ..errors import HwpxStateError, HwpxValueError
 from ..objects.checkbox import CheckBox
-from ..objects.form_field import CellField, FieldLocation, FieldParameter, FormField
+from ..objects.form_field import CellField, FieldLocation, FieldParameter, FormField, TextBoxField
 from ..objects.results import FieldFillResult
 from ..oxml import HwpxOxmlParagraph
 from ..oxml.namespaces import HP
@@ -88,6 +88,41 @@ def _sanitize_field_text(value: str) -> str:
     return _TEXT_ILLEGAL.sub("", value)
 
 
+# Characters an hp:t holds as child elements; they belong to the text they sit in.
+_TEXT_CHARACTER_NAMES = {"tab": "\t", "lineBreak": "\n", "hyphen": "", "nbSpace": "\u00a0", "fwSpace": "\u3000"}
+
+
+def _text_node_value(node: Any) -> str:
+    """The text of an ``hp:t``, with ``hp:lineBreak`` as a newline and ``hp:tab`` as a tab."""
+
+    parts = [node.text or ""]
+    for child in node:
+        parts.append(_TEXT_CHARACTER_NAMES.get(_local_name(child), ""))
+        parts.append(child.tail or "")
+    return "".join(parts)
+
+
+def _write_text_node(node: Any, value: str) -> None:
+    """Put *value* in the ``hp:t`` *node* in place of its text.
+
+    A line break (CRLF, LF or CR) becomes ``hp:lineBreak``, the element Hancom
+    turns such a character into when it opens the file. The characters of the
+    old text (tabs, line breaks) go; other marks stay, emptied.
+    """
+
+    for child in list(node):
+        if _local_name(child) in _TEXT_CHARACTER_NAMES:
+            node.remove(child)
+        else:
+            child.tail = ""
+    lines = value.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    node.text = lines[0]
+    for line in lines[1:]:
+        line_break = node.makeelement(f"{_HP}lineBreak", {})
+        node.append(line_break)
+        line_break.tail = line
+
+
 def _field_type_tokens(*values: str | None) -> set[str]:
     tokens: set[str] = set()
     for value in values:
@@ -125,6 +160,11 @@ def _field_identifier(field_begin: Any) -> str:
 
 
 def _field_end_matches(field_begin: Any, field_end: Any) -> bool:
+    # An end that names its begin (beginIDRef) is that begin's end only: a fieldid
+    # is shared by every field of a type (Hancom's control id), so it pairs only
+    # ends that name no begin.
+    if field_begin.get("id") and field_end.get("beginIDRef"):
+        return field_begin.get("id") == field_end.get("beginIDRef")
     begin_keys = {
         value
         for value in (
@@ -160,6 +200,18 @@ def _field_parameters(field_begin: Any) -> list[dict[str, str]]:
     return parameters
 
 
+def _field_name(field_begin: Any, parameters: Sequence[dict[str, str]]) -> str:
+    """The field's name. A ``name`` attribute is the name even when empty: Hancom
+    treats such a field as unnamed (it lists and fills fields by name only)."""
+
+    if field_begin.get("name") is not None:
+        return field_begin.get("name", "").strip()
+    name = _first_attr(field_begin, _FORM_FIELD_NAME_ATTRS)
+    if not name:
+        name = _field_parameter_value(parameters, "fieldName", "fieldname", "field_name", "name", "title")
+    return name
+
+
 def _first_attr(element: Any, names: Sequence[str]) -> str:
     for name in names:
         value = (element.get(name) or "").strip()
@@ -178,6 +230,21 @@ def _field_parameter_value(parameters: Sequence[dict[str, str]], *names: str) ->
     return ""
 
 
+_COMMAND_DIRECTION = re.compile(r"(?:^|[\s:])Direction:wstring:(\d+):")
+
+
+def _command_direction(parameters: Sequence[dict[str, str]]) -> str:
+    """The prompt a field keeps only in its ``Command`` string
+    (``Clickhere:set:N:Direction:wstring:<length>:<prompt> HelpState:...``)."""
+
+    command = _field_parameter_value(parameters, "Command")
+    found = _COMMAND_DIRECTION.search(command)
+    if found is None:
+        return ""
+    start = found.end()
+    return command[start : start + int(found.group(1))]
+
+
 def _clear_form_field_layout_cache(paragraph: Any) -> int:
     removed = 0
     for child in list(paragraph):
@@ -208,6 +275,40 @@ def _find_field_end_position(
     return None
 
 
+def _find_field_end_in_following_paragraphs(
+    paragraph_element: Any, field_begin: Any
+) -> tuple[Any, list[Any], int, int, list[Any]] | None:
+    """The end of a field whose content runs past its paragraph: the later
+    paragraph beside it that holds the fieldEnd naming this field's id, that
+    paragraph's runs, the end's run and child index, and the paragraphs in
+    between. Only an end that names the begin's id counts here."""
+
+    ids = {value for value in (field_begin.get("id"), field_begin.get("fieldid")) if value}
+    if not ids:
+        return None
+    middle: list[Any] = []
+    sibling = paragraph_element.getnext()
+    while sibling is not None:
+        if _local_name(sibling) == "p":
+            runs = [child for child in sibling if _local_name(child) == "run"]
+            for run_index, run in enumerate(runs):
+                for child_index, child in enumerate(run):
+                    if _local_name(child) != "ctrl":
+                        continue
+                    for field_end in child.findall(f"{_HP}fieldEnd"):
+                        if _field_end_matches(field_begin, field_end) and (
+                            ids & {field_end.get("beginIDRef"), field_end.get("fieldid")}
+                        ):
+                            return sibling, runs, run_index, child_index, middle
+            middle.append(sibling)
+        sibling = sibling.getnext()
+    return None
+
+
+def _run_texts(runs: Sequence[Any]) -> str:
+    return "".join(_text_node_value(node) for run in runs for node in run if _local_name(node) == "t")
+
+
 def _field_text_nodes(
     doc: "HwpxDocument",
     runs: Sequence[Any],
@@ -244,13 +345,14 @@ def _form_field_payload(
     has_end: bool,
 ) -> dict[str, Any]:
     parameters = _field_parameters(field_begin)
-    name = _first_attr(field_begin, _FORM_FIELD_NAME_ATTRS)
-    if not name:
-        name = _field_parameter_value(parameters, "fieldName", "fieldname", "field_name", "name", "title")
+    name = _field_name(field_begin, parameters)
     prompt = _first_attr(field_begin, _FORM_FIELD_PROMPT_ATTRS)
     if not prompt:
         # "Direction" is the real-Hancom 안내문 parameter (P0 gold contract).
         prompt = _field_parameter_value(parameters, "Direction", *_FORM_FIELD_PARAM_NAMES)
+    if not prompt:
+        # Some fields keep it only inside their Command string.
+        prompt = _command_direction(parameters)
     instruction = _field_parameter_value(parameters, "instruction", "guide", "help", "description", "desc")
     if not instruction:
         instruction = prompt
@@ -325,17 +427,38 @@ def _iter_form_field_matches(doc: "HwpxDocument") -> list[dict[str, Any]]:
                         )
                         end_run_index: int | None = None
                         end_child_index: int | None = None
+                        span = None
                         if end_position is not None:
                             end_run_index, end_child_index, _field_end = end_position
+                        else:
+                            span = _find_field_end_in_following_paragraphs(paragraph_element, field_begin)
                         text_nodes = _field_text_nodes(
                             doc,
                             runs,
                             begin_run_index=run_index,
                             begin_child_index=child_index,
-                            end_run_index=end_run_index,
+                            end_run_index=end_run_index if span is None else len(runs) - 1,
                             end_child_index=end_child_index,
                         )
-                        current_value = "".join("".join(node.itertext()) for node in text_nodes)
+                        current_value = "".join(_text_node_value(node) for node in text_nodes)
+                        if span is not None:
+                            # the content goes on over paragraphs: their texts, one per line
+                            end_paragraph, end_runs, span_run, span_child, middle = span
+                            tail = _field_text_nodes(
+                                doc,
+                                end_runs,
+                                begin_run_index=0,
+                                begin_child_index=-1,
+                                end_run_index=span_run,
+                                end_child_index=span_child,
+                            )
+                            current_value = "\n".join(
+                                [
+                                    current_value,
+                                    *(_run_texts([c for c in p if _local_name(c) == "run"]) for p in middle),
+                                    "".join(_text_node_value(node) for node in tail),
+                                ]
+                            )
                         payload = _form_field_payload(
                             doc,
                             index=len(matches),
@@ -347,7 +470,7 @@ def _iter_form_field_matches(doc: "HwpxDocument") -> list[dict[str, Any]]:
                             ctrl=child,
                             field_begin=field_begin,
                             current_value=current_value,
-                            has_end=end_position is not None,
+                            has_end=end_position is not None or span is not None,
                         )
                         payload["_paragraph"] = paragraph
                         payload["_runs"] = runs
@@ -356,6 +479,7 @@ def _iter_form_field_matches(doc: "HwpxDocument") -> list[dict[str, Any]]:
                         payload["_end_run_index"] = end_run_index
                         payload["_end_child_index"] = end_child_index
                         payload["_text_nodes"] = text_nodes
+                        payload["_span"] = span
                         matches.append(payload)
             paragraph_index += 1
     return matches
@@ -401,7 +525,13 @@ def _form_field_from_match(doc: "HwpxDocument", match: Mapping[str, Any]) -> For
 
 
 def list_form_fields(doc: "HwpxDocument") -> tuple[FormField, ...]:
-    """Return native form/click-here fields in document order."""
+    """Return native form/click-here fields in document order.
+
+    Every field in the document is listed. An unnamed field (an empty ``name``) is
+    listed with an empty name and told apart by its id: :func:`fill_form_field`
+    does not find it by name, as Hancom does not, but ``field_index`` and
+    ``field_id`` reach it.
+    """
 
     return tuple(_form_field_from_match(doc, match) for match in _iter_form_field_matches(doc))
 
@@ -442,6 +572,80 @@ def fill_cell_fields(doc: "HwpxDocument", value: str, *, name: str, index: int |
     return tuple(fields)
 
 
+def list_text_box_fields(doc: "HwpxDocument") -> tuple[TextBoxField, ...]:
+    """Named text boxes in document order: Hancom lists a text box whose ``hp:drawText``
+    has a name among its fields (and leaves an unnamed one out)."""
+
+    return tuple(
+        TextBoxField(draw_text, section)
+        for section in doc.sections
+        for draw_text in section.element.iter(f"{_HP}drawText")
+        if (draw_text.get("name") or "").strip()
+    )
+
+
+def fill_text_box_fields(
+    doc: "HwpxDocument", value: str, *, name: str, index: int | None = None
+) -> tuple[TextBoxField, ...]:
+    """Set the text of every text box called *name*, or of the *index*-th of them only."""
+
+    wanted = (name or "").strip()
+    fields = [field for field in list_text_box_fields(doc) if wanted and field.name == wanted]
+    if index is not None:
+        fields = fields[index : index + 1] if index >= 0 else []
+    if not fields:
+        where = f"{wanted!r}" if index is None else f"{wanted!r} at index {index}"
+        raise HwpxValueError(
+            f"no text box named {where}",
+            code="field-text-box-not-found",
+            context={"name": wanted, "index": index},
+            suggestion="List doc.fields.text_boxes to see the text box names.",
+        )
+    for field in fields:
+        field.text = value
+    return tuple(fields)
+
+
+def text_box_text(draw_text: Any) -> str:
+    """The text of a text box, a line per paragraph."""
+
+    return "\n".join(
+        "".join(_text_node_value(node) for node in paragraph.iter(f"{_HP}t"))
+        for paragraph in draw_text.findall(f"{_HP}subList/{_HP}p")
+    )
+
+
+def set_text_box_text(draw_text: Any, section: Any, value: str) -> None:
+    """Put *value* in a text box as Hancom fills a text box field: the box keeps its
+    first paragraph and that paragraph's first run, which hold the value alone."""
+
+    sub_list = draw_text.find(f"{_HP}subList")
+    if sub_list is None:
+        sub_list = draw_text.makeelement(f"{_HP}subList", {})
+        draw_text.insert(0, sub_list)
+    paragraphs = sub_list.findall(f"{_HP}p")
+    first = paragraphs[0] if paragraphs else sub_list.makeelement(
+        f"{_HP}p", {"id": "0", "paraPrIDRef": "0", "styleIDRef": "0", "pageBreak": "0", "columnBreak": "0", "merged": "0"}
+    )
+    if not paragraphs:
+        sub_list.append(first)
+    for extra in paragraphs[1:]:
+        sub_list.remove(extra)
+    runs = first.findall(f"{_HP}run")
+    run = runs[0] if runs else first.makeelement(f"{_HP}run", {"charPrIDRef": "0"})
+    if not runs:
+        first.insert(0, run)
+    for extra in runs[1:]:
+        first.remove(extra)
+    for child in list(run):
+        run.remove(child)
+    text = run.makeelement(f"{_HP}t", {})
+    run.append(text)
+    _write_text_node(text, value)
+    _clear_form_field_layout_cache(first)
+    section.mark_dirty()
+
+
 _PROMPT_TEXT_COLOR = "#FF0000"
 
 
@@ -686,6 +890,7 @@ def _select_form_field(
             match
             for match in matches
             if wanted_name
+            and match.get("name")
             and wanted_name
             in {
                 str(match.get("name", "")).strip().casefold(),
@@ -735,10 +940,62 @@ def _insert_form_field_text_run(
     runs: list[Any] = match["_runs"]
     begin_run = runs[int(match["_begin_run_index"])]
     text_node = begin_run.makeelement(f"{_HP}t", {})
-    text_node.text = _sanitize_field_text(value)
+    _write_text_node(text_node, _sanitize_field_text(value))
     begin_run.insert(int(match["_begin_child_index"]) + 1, text_node)
 
 
+def _drop_nested_fields(match: Mapping[str, Any]) -> None:
+    """Hancom's way with a field that holds other fields: the value replaces
+    them with the rest of the content, so the begin and end of every field
+    lying wholly between this field's begin and end go."""
+
+    runs: list[Any] = match["_runs"]
+    end_run_index = match.get("_end_run_index")
+    if end_run_index is None:
+        return
+    begin_run_index = int(match["_begin_run_index"])
+    inside: list[tuple[Any, Any]] = []
+    for run_index in range(begin_run_index, int(end_run_index) + 1):
+        children = list(runs[run_index])
+        start = int(match["_begin_child_index"]) + 1 if run_index == begin_run_index else 0
+        stop = int(match["_end_child_index"]) if run_index == end_run_index else len(children)
+        inside.extend((runs[run_index], child) for child in children[start:stop] if _local_name(child) == "ctrl")
+    begun = {mark.get("id") for _, ctrl in inside for mark in ctrl.findall(f"{_HP}fieldBegin")}
+    ended = {mark.get("beginIDRef") for _, ctrl in inside for mark in ctrl.findall(f"{_HP}fieldEnd")}
+    nested = (begun & ended) - {None, ""}
+    for run, ctrl in inside:
+        marks = [(mark.get("id") if _local_name(mark) == "fieldBegin" else mark.get("beginIDRef"))
+                 for mark in ctrl if _local_name(mark) in ("fieldBegin", "fieldEnd")]
+        if marks and all(mark in nested for mark in marks):
+            run.remove(ctrl)
+
+
+def _collapse_field_span(match: Mapping[str, Any]) -> None:
+    """Hancom's way with a field whose content runs over paragraphs: the
+    content between the begin and the end goes, paragraphs and all, and the
+    end with the rest of its paragraph joins the begin's paragraph."""
+
+    end_paragraph, end_runs, end_run_index, end_child_index, middle = match["_span"]
+    paragraph_element = match["_paragraph"].element
+    runs: list[Any] = match["_runs"]
+    begin_run_index = int(match["_begin_run_index"])
+    begin_run = runs[begin_run_index]
+    for child in list(begin_run)[int(match["_begin_child_index"]) + 1 :]:
+        begin_run.remove(child)
+    for run in runs[begin_run_index + 1 :]:
+        paragraph_element.remove(run)
+    for element in middle:
+        element.getparent().remove(element)
+    end_run = end_runs[end_run_index]
+    moved = end_run.makeelement(end_run.tag, dict(end_run.attrib))
+    for child in list(end_run)[end_child_index:]:
+        moved.append(child)
+    position = paragraph_element.index(begin_run) + 1
+    for offset, run in enumerate([moved, *end_runs[end_run_index + 1 :]]):
+        paragraph_element.insert(position + offset, run)
+    end_paragraph.getparent().remove(end_paragraph)
+
+
 def fill_form_field(
     doc: "HwpxDocument",
     value: str,
@@ -766,6 +1023,13 @@ def fill_form_field(
         field_id=field_id,
         name=name,
     )
+    if not match.get("has_end"):
+        raise HwpxValueError(
+            f"the field {match.get('name') or match.get('index')!r} has no end, so it has no content to replace",
+            code="field-end-missing",
+            context={"name": match.get("name"), "index": match.get("index")},
+            suggestion="Hancom leaves such a field unchanged too; give it an end or remove it.",
+        )
     paragraph = match["_paragraph"]
     runs = match["_runs"]
     before_value = str(match.get("current_value", ""))
@@ -802,23 +1066,23 @@ def fill_form_field(
 
     text_nodes: list[Any] = match.get("_text_nodes", [])
     sanitized = _sanitize_field_text(write_value)
-    if text_nodes:
+    if match.get("_span") is None:
+        _drop_nested_fields(match)
+    if match.get("_span") is not None:
+        _collapse_field_span(match)
+        _insert_form_field_text_run(doc, match, sanitized)
+    elif text_nodes:
         primary = text_nodes[0]
-        primary.text = sanitized
-        for child in list(primary):
-            child.tail = ""
+        _write_text_node(primary, sanitized)
         for node in text_nodes[1:]:
-            node.text = ""
-            for child in list(node):
-                child.tail = ""
-        if match.get("is_placeholder"):
-            # Contract (P0 gold): Hancom swaps the screen-only prompt style for
-            # the surrounding style when a value replaces the placeholder.
-            begin_run = runs[int(match["_begin_run_index"])]
-            begin_ref = begin_run.get("charPrIDRef")
-            primary_run = primary.getparent()
-            if begin_ref is not None and primary_run is not None:
-                primary_run.set("charPrIDRef", begin_ref)
+            _write_text_node(node, "")
+        # Hancom writes the value in the shape of the run holding the field's
+        # begin, whatever shape the old value or the screen-only prompt had.
+        begin_run = runs[int(match["_begin_run_index"])]
+        begin_ref = begin_run.get("charPrIDRef")
+        primary_run = primary.getparent()
+        if begin_ref is not None and primary_run is not None:
+            primary_run.set("charPrIDRef", begin_ref)
     else:
         _insert_form_field_text_run(doc, match, sanitized)