python-hwpx 5.0.2__py3-none-any.whl → 5.1.1__py3-none-any.whl

hwpx/_document/fields.py

@@ -211,10 +211,16 @@ def _form_field_payload(
         name = _field_parameter_value(parameters, "fieldName", "fieldname", "field_name", "name", "title")
     prompt = _first_attr(field_begin, _FORM_FIELD_PROMPT_ATTRS)
     if not prompt:
-        prompt = _field_parameter_value(parameters, *_FORM_FIELD_PARAM_NAMES)
+        # "Direction" is the real-Hancom 안내문 parameter (P0 gold contract).
+        prompt = _field_parameter_value(parameters, "Direction", *_FORM_FIELD_PARAM_NAMES)
     instruction = _field_parameter_value(parameters, "instruction", "guide", "help", "description", "desc")
     if not instruction:
         instruction = prompt
+    memo = _field_parameter_value(parameters, "HelpState", "memo")
+    dirty = (field_begin.get("dirty") or "").strip()
+    # Contract: while dirty != "1" the content between begin/end is the prompt
+    # placeholder (screen-only, not printed), not a user value.
+    is_placeholder = dirty != "1" and bool(prompt) and current_value == prompt
     return {
         "index": index,
         "field_id": _field_identifier(field_begin),
@@ -223,9 +229,13 @@ def _form_field_payload(
         "name": name,
         "prompt": prompt,
         "instruction": instruction,
+        "memo": memo,
+        "dirty": dirty,
+        "is_placeholder": is_placeholder,
         "current_value": current_value,
         "field_type": field_begin.get("type", ""),
         "control_type": ctrl.get("type", ""),
+        "_field_begin": field_begin,
         "section_index": section_index,
         "paragraph_index": paragraph_index,
         "paragraph_index_in_section": paragraph_index_in_section,
@@ -320,6 +330,62 @@ def list_form_fields(doc: "HwpxDocument") -> list[dict[str, Any]]:
     ]
 
 
+_PROMPT_TEXT_COLOR = "#FF0000"
+
+
+def add_form_field(
+    doc: "HwpxDocument",
+    name: str,
+    *,
+    prompt: str = "",
+    memo: str = "",
+    editable: bool = True,
+    paragraph: Any | None = None,
+    section: Any | None = None,
+    section_index: int | None = None,
+) -> dict[str, Any]:
+    """Create a click-here (누름틀) form field and return its field payload.
+
+    The emitted XML follows the real-Hancom CLICKHERE contract
+    (reverse-engineered from Hancom Office 12.0.0.3288 gold documents). The
+    prompt (안내문) is materialized as a screen-only red-italic run, exactly as
+    Hancom authors it. The created field is immediately re-read through the
+    standard ``list_form_fields`` matcher — creation fails loudly if the
+    standard consumer would not recognize it (no special-casing by design).
+    """
+
+    if not str(name).strip():
+        raise ValueError("form field name must be a non-empty string")
+    if paragraph is None:
+        paragraph = doc.add_paragraph(
+            "", section=section, section_index=section_index, include_run=False,
+        )
+
+    prompt_char_pr: str | None = None
+    if _sanitize_field_text(prompt):
+        prompt_char_pr = doc.ensure_run_style(italic=True, color=_PROMPT_TEXT_COLOR)
+
+    control = paragraph.add_form_field(
+        name,
+        prompt=prompt,
+        memo=memo,
+        editable=editable,
+        prompt_char_pr_id_ref=prompt_char_pr,
+    )
+    _clear_form_field_layout_cache(paragraph.element)
+
+    field_begin = control.element.find(f"{_HP}fieldBegin")
+    created_id = field_begin.get("id", "") if field_begin is not None else ""
+    for match in _iter_form_field_matches(doc):
+        if match.get("id") == created_id:
+            return {
+                key: value for key, value in match.items() if not key.startswith("_")
+            }
+    raise RuntimeError(
+        "created form field was not recognized by the standard form-field matcher"
+    )
+
+
 def _select_form_field(
     doc: "HwpxDocument",
     matches: Sequence[dict[str, Any]],
@@ -447,9 +513,23 @@ def fill_form_field(
             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)
     else:
         _insert_form_field_text_run(doc, match, sanitized)
 
+    # Contract (P0 gold): a field that went through fill machinery carries
+    # dirty="1"; while dirty != "1" readers treat the content as the prompt.
+    field_begin = match.get("_field_begin")
+    if field_begin is not None:
+        field_begin.set("dirty", "1")
+
     if fit_result is not None:
         _apply_form_field_fit_style(doc, match, fit_result)
 

hwpx/document.py

@@ -1388,6 +1388,48 @@ class HwpxDocument:
             section_index=section_index,
         )
 
+    def add_form_field(
+        self,
+        name: str,
+        *,
+        prompt: str = "",
+        memo: str = "",
+        editable: bool = True,
+        paragraph: HwpxOxmlParagraph | None = None,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+    ) -> dict[str, Any]:
+        """Create a click-here (누름틀) form field. **Experimental contract.**
+
+        Emits the real-Hancom CLICKHERE shape (안내문 placeholder run included)
+        so the created field is indistinguishable from a Hancom-authored one:
+        ``list_form_fields``/``fill_form_field`` recognize it with no
+        special-casing, and real Hancom Office enumerates and fills it.
+
+        Args:
+            name: Field name (non-empty).
+            prompt: 안내문 shown while the field is empty. Screen-only —
+                Hancom does not print it.
+            memo: Help text (``HelpState``).
+            paragraph: Target paragraph (e.g. inside a table cell). When
+                omitted a new paragraph is appended to *section*.
+
+        Returns:
+            The created field's payload, same shape as a ``list_form_fields``
+            entry.
+        """
+
+        return _fields.add_form_field(
+            self,
+            name,
+            prompt=prompt,
+            memo=memo,
+            editable=editable,
+            paragraph=paragraph,
+            section=section,
+            section_index=section_index,
+        )
+
 
     def set_page_size(
         self,

hwpx/oxml/paragraph.py

@@ -27,7 +27,7 @@ from ._document_primitives import (
     _sanitize_text,
 )
 from .memo import HwpxOxmlNote
-from .namespaces import tag_local_name
+from .namespaces import XML_NS, tag_local_name
 from .objects import (
     HwpxOxmlInlineObject,
     HwpxOxmlShape,
@@ -834,6 +834,105 @@ class HwpxOxmlParagraph:
         self.section.mark_dirty()
         return HwpxOxmlInlineObject(ctrl1, self)
 
+    def add_form_field(
+        self,
+        name: str,
+        *,
+        prompt: str = "",
+        memo: str = "",
+        editable: bool = True,
+        prompt_char_pr_id_ref: str | int | None = None,
+        char_pr_id_ref: str | int | None = None,
+    ) -> HwpxOxmlInlineObject:
+        """Insert a click-here (누름틀) form field at the end of this paragraph.
+
+        Emits the real-Hancom CLICKHERE shape (reverse-engineered from Hancom
+        Office 12.0.0.3288 gold documents):
+        a ``fieldBegin`` ctrl run carrying the ``Prop``/``Command``/``Direction``/
+        ``HelpState`` parameters, an optional prompt run showing *prompt* (the
+        안내문, screen-only — Hancom does not print it), and a ``fieldEnd`` ctrl
+        run. ``Command`` lengths count UTF-16 characters, so values may contain
+        spaces. ``id``/``fieldid`` values are semantically free — Hancom reissues
+        its own on save.
+
+        Args:
+            name: Field name used by ``list_form_fields``/``fill_form_field``.
+            prompt: 안내문 text shown while the field is empty (``Direction``).
+            memo: Help text (``HelpState``).
+            prompt_char_pr_id_ref: charPr for the prompt run (callers normally
+                pass a red-italic style; Hancom uses one).
+
+        Returns:
+            The ``<hp:ctrl>`` element wrapping the ``<hp:fieldBegin>``.
+        """
+        field_id = _object_id()
+        field_instance_id = _object_id()
+        direction = _sanitize_text(prompt)
+        help_state = _sanitize_text(memo)
+
+        # Run 1: fieldBegin with the CLICKHERE parameter block
+        run1 = self._create_run_for_object(char_pr_id_ref=char_pr_id_ref)
+        ctrl1 = _append_child(run1, f"{_HP}ctrl", {})
+        field_begin = _append_child(ctrl1, f"{_HP}fieldBegin", {
+            "id": field_id,
+            "type": "CLICK_HERE",
+            "name": _sanitize_text(name),
+            "editable": "1" if editable else "0",
+            "dirty": "0",
+            "zorder": "-1",
+            "fieldid": field_instance_id,
+            "metaTag": "",
+        })
+        payload = (
+            f"Direction:wstring:{len(direction)}:{direction} "
+            f"HelpState:wstring:{len(help_state)}:{help_state} "
+        )
+        param_count = 2 + (1 if direction else 0) + (1 if help_state else 0)
+        parameters = _append_child(
+            field_begin, f"{_HP}parameters", {"cnt": str(param_count), "name": ""}
+        )
+        prop = _append_child(parameters, f"{_HP}integerParam", {"name": "Prop"})
+        prop.text = "9"
+        command = _append_child(parameters, f"{_HP}stringParam", {
+            "name": "Command",
+            f"{{{XML_NS}}}space": "preserve",
+        })
+        command.text = f"Clickhere:set:{len(payload)}:{payload} "
+        if direction:
+            direction_param = _append_child(
+                parameters, f"{_HP}stringParam", {"name": "Direction"}
+            )
+            direction_param.text = direction
+        if help_state:
+            help_param = _append_child(
+                parameters, f"{_HP}stringParam", {"name": "HelpState"}
+            )
+            help_param.text = help_state
+
+        # Run 2: the prompt placeholder (only while a prompt exists)
+        if direction:
+            run2 = self._create_run_for_object(
+                char_pr_id_ref=(
+                    prompt_char_pr_id_ref
+                    if prompt_char_pr_id_ref is not None
+                    else char_pr_id_ref
+                ),
+            )
+            prompt_text = _append_child(run2, f"{_HP}t", {})
+            prompt_text.text = direction
+
+        # Run 3: fieldEnd + trailing empty text node (gold shape)
+        run3 = self._create_run_for_object(char_pr_id_ref=char_pr_id_ref)
+        ctrl3 = _append_child(run3, f"{_HP}ctrl", {})
+        _append_child(ctrl3, f"{_HP}fieldEnd", {
+            "beginIDRef": field_id,
+            "fieldid": field_instance_id,
+        })
+        _append_child(run3, f"{_HP}t", {})
+
+        self.section.mark_dirty()
+        return HwpxOxmlInlineObject(ctrl1, self)
+
     @property
     def bookmarks(self) -> list[str]:
         """Return the names of all bookmarks in this paragraph."""

{python_hwpx-5.0.2.dist-info → python_hwpx-5.1.1.dist-info}/METADATA

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

{python_hwpx-5.0.2.dist-info → python_hwpx-5.1.1.dist-info}/RECORD

@@ -1,6 +1,6 @@
 hwpx/__init__.py,sha256=C63jP28R_TnVNTQifvWgOXwKg273JUpLwAa-8Z0B4dQ,15706
 hwpx/body_patch.py,sha256=XfwrTMThS9vPLA62PDnEleCGuvYv61URxelbD_LHe8w,25730
-hwpx/document.py,sha256=sDbRQjIoUGw3VzKPAIuQi9oemcb4PqKHczBDrYZ9wTU,60776
+hwpx/document.py,sha256=fjFEO12_bBnDLHmAwD-CfHNYWbnvK0jHdWWthhtpEl4,62237
 hwpx/errors.py,sha256=l3QK2Izwkpm25ar7QnNQvyg0yosoLfQt7kW5wn5MCG0,3033
 hwpx/experimental.py,sha256=H8fBrmGf0BzoDS6dqwBpUChUestUgOpO7XjMEBXsssg,1499
 hwpx/mutation_report.py,sha256=6hurhDdgGiONeLIeWZJT8lwLtWJZ1VHp1l6G0zy0mQo,19409
@@ -11,7 +11,7 @@ hwpx/table_patch.py,sha256=nl7UT-Qf5-KV25Wdxm4ve9ZxX6FfijibymPXZcJJIjQ,83729
 hwpx/templates.py,sha256=28bYqeJVeDb1Cq8G9NZG9Mhnu4K2GamAKC4QhxvUZyA,1187
 hwpx/_document/__init__.py,sha256=REiNqMbuk_TS4NVC27FIo1rUt3Z8nhJrTBGOgNtxBRg,90
 hwpx/_document/_units.py,sha256=qyC8YtnvV2VlSGltJntDaIMF_sHy_XJZCwwe-g080TQ,386
-hwpx/_document/fields.py,sha256=-R3tXMaTvX1DtSNouARSvcBepW1JYUk2caOYTz4sVh0,19683
+hwpx/_document/fields.py,sha256=6VB7FV69cWcHLONj_Bn_DUGH5k9IMn94SRhRCia6wvI,22935
 hwpx/_document/layout.py,sha256=TicBhdxXW2lQkLyG5bg6PHW-OP-X4oWdP6XAgAXw8mg,23089
 hwpx/_document/media.py,sha256=kamsFJZ4K9aoKhjyztMHC64MVFR_ZQ50rDVgouZqxFA,11592
 hwpx/_document/memos.py,sha256=_tscEhNfPe9-iAkcEtJGjwHTN42_lx4stFoPrgJxk3o,7481
@@ -55,7 +55,7 @@ hwpx/oxml/memo.py,sha256=QlmuELEzywnmywgjm94S3vzJB8wPpoFOmI8KVuzoNPw,9484
 hwpx/oxml/namespaces.py,sha256=c7JfdOdJbzrhyHvjbxoeeeloRE3xPuoB7v3YI8SmKDk,6524
 hwpx/oxml/numbering.py,sha256=9a0ARGW1DkKsTF7mEEXM4FA5loQmzIBuqE4APA8UFIQ,669
 hwpx/oxml/objects.py,sha256=8ErDXWvkjLm3FTsx0Z_IovUXbiv2uc-j0B5Y2-OtihA,20864
-hwpx/oxml/paragraph.py,sha256=0Gb8FBgzirE32_ALJQIz6TYpBeQiLX3Jh14JOKyS-SA,36779
+hwpx/oxml/paragraph.py,sha256=tjsPttiYAu0d92C3O78pt-7h9gJa1cPRs9qP7iY-6wQ,40865
 hwpx/oxml/parser.py,sha256=pIfyNdW3WdFkCcE8JFY7hn1fobRbMngzfhVZICvWeVs,2937
 hwpx/oxml/run.py,sha256=F939J1W6zQjr-JQ1Z8-nKh2s7NQ_0Okov4QJAEyw_5M,15503
 hwpx/oxml/schema.py,sha256=ElR3_IIhhPPZEqJtNKMNCHA-VFVLdhL454W_4spuvlc,1284
@@ -103,10 +103,10 @@ hwpx/tools/toc_fidelity.py,sha256=rvoKH8QJ65WNVrxS0d-i2AtODvBy-4O8NRudfQ244v4,19
 hwpx/tools/validator.py,sha256=U856izL9NcJZOiKDYoCpwOSaFNQ2Un8Jn4pzL20A96Q,7100
 hwpx/tools/_schemas/header.xsd,sha256=mJXuFMuHGT1JnFFaluUpYUglwjMCNlfbFCRVM26eHXE,664
 hwpx/tools/_schemas/section.xsd,sha256=MgvavVHG05RDfUnVPxVU10H4FQOja5ON04_m9Uk_m7E,522
-python_hwpx-5.0.2.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-5.0.2.dist-info/licenses/NOTICE,sha256=KJgtwIIzrXoA0j3PUhwp78ZtnucocEoB7jiuwoL4i7o,3060
-python_hwpx-5.0.2.dist-info/METADATA,sha256=nLrp-MhviX2B4sd8FIUBc8rLKQxTX_itwHnLeyDExSg,13162
-python_hwpx-5.0.2.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_hwpx-5.0.2.dist-info/entry_points.txt,sha256=JUKRxbly9UaeHV7YzOea23y8IiqSTcrhUlooP3fS_Zc,405
-python_hwpx-5.0.2.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-5.0.2.dist-info/RECORD,,
+python_hwpx-5.1.1.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
+python_hwpx-5.1.1.dist-info/licenses/NOTICE,sha256=KJgtwIIzrXoA0j3PUhwp78ZtnucocEoB7jiuwoL4i7o,3060
+python_hwpx-5.1.1.dist-info/METADATA,sha256=K_jKvQjMhwByWju_P3C9_TIyGyqJQVTvGfns4Y2viPI,13162
+python_hwpx-5.1.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_hwpx-5.1.1.dist-info/entry_points.txt,sha256=JUKRxbly9UaeHV7YzOea23y8IiqSTcrhUlooP3fS_Zc,405
+python_hwpx-5.1.1.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-5.1.1.dist-info/RECORD,,