refactor(textEdit): refactor the text edit and define a library for the wrap engines (#617)

Author: ceccopierangiolieugenio

.github/copilot-instructions.md

@@ -125,7 +125,7 @@ def ttkStringData(self, row:int, col:int) -> TTkString:
     data = self.data(row,col)
     return TTkAbstractTableModel._dataToTTkString(data)
 
-def setGeometry(self, x: int, y: int, width: int, height: int):
+def setGeometry(self, x: int, y: int, width: int, height: int) -> None:
     ''' Resize and move the widget
 
     :param x: the horizontal position
@@ -203,6 +203,7 @@ i.e., whenever the user checks or unchecks it.
 
 **Key conventions**:
 - Use single quotes `'''` for docstrings
+- When adding Python code, type hints are required; use standard `typing` module types (or builtin generic types where equivalent) whenever possible
 - Include ASCII art for visual widgets showing borders/layout
 - Link to demo files with full GitHub URLs
 - Use `:py:class:` for cross-references to other classes

.github/instructions/tests.instructions.md

@@ -0,0 +1,31 @@
+---
+applyTo: "tests/pytest/**/*.py,apps/*/tests/**/*.py"
+description: Rules for creating or updating tests in core and app test folders with behavior-first assertions and full coverage expectations.
+---
+# Test Authoring Rules (Path Scoped)
+
+These rules apply when creating or editing tests under `tests/pytest/` and `apps/*/tests/`.
+
+## Coverage Requirements
+
+- New or modified tests must drive the touched production code to full line and branch coverage.
+- Add tests for normal, edge, and error paths.
+- Do not leave uncovered branches for newly introduced logic.
+
+## Behavior-First Assertions
+
+- Test the expected behavior of widgets and functionality from a user/API perspective.
+- Prefer public APIs, signals, and documented contracts over internal implementation details.
+- Validate observable outcomes (state changes, emitted signals, rendered output, return values, raised errors).
+
+## Anti-Pattern to Avoid
+
+- Do not tune tests to match known bugs, undefined behavior, or accidental current implementation quirks.
+- If current behavior is buggy but intentional fixes are in scope, write the test for the correct expected behavior and align code to pass it.
+- If behavior is ambiguous, derive expectations from docs, demos, existing stable APIs, and widget design intent.
+
+## Test Quality
+
+- Keep tests deterministic and isolated; avoid timing-sensitive or flaky assertions.
+- Use concise fixtures and clear test names describing the behavior under test.
+- When fixing a bug, include a regression test that fails before the fix and passes after it.

libs/pyTermTk/TermTk/TTkCore/constant.py

@@ -24,7 +24,7 @@
 
 __all__ = ['TTkConstant', 'TTkK']
 
-from enum import IntEnum, Flag
+from enum import Enum, IntEnum, Flag, auto
 
 class TTkConstant:
     '''Class container of all the constants used in :mod:`~TermTk`'''
@@ -334,13 +334,12 @@ class MouseKey(int):
     MiddleButton  = MouseKey.MiddleButton
     Wheel         = MouseKey.Wheel
 
-    class WrapMode(int):
+    class WrapMode(IntEnum):
         '''Those constants describes how text is wrapped in a document.
 
         .. autosummary::
           WordWrap
           WrapAnywhere
-          WrapAtWordBoundaryOrAnywhere
         '''
         # NoWrap        = 0x00
         # '''Text is not wrapped at all.'''
@@ -350,22 +349,40 @@ class WrapMode(int):
         # '''Same as :py:class:`~TermTk.TTkCore.constant.TTkConstant.WrapMode.NoWrap`'''
         WrapAnywhere  = 0x03
         '''Text can be wrapped at any point on a line, even if it occurs in the middle of a word.'''
-        WrapAtWordBoundaryOrAnywhere = 0x04
-        '''If possible, wrapping occurs at a word boundary; otherwise it will occur at the appropriate point on the line, even in the middle of a word.'''
+        # WrapAtWordBoundaryOrAnywhere = 0x04
+        # '''If possible, wrapping occurs at a word boundary; otherwise it will occur at the appropriate point on the line, even in the middle of a word.'''
 
     # NoWrap       = WrapMode.NoWrap
     WordWrap     = WrapMode.WordWrap
     # ManualWrap   = WrapMode.ManualWrap
     WrapAnywhere = WrapMode.WrapAnywhere
-    WrapAtWordBoundaryOrAnywhere = WrapMode.WrapAtWordBoundaryOrAnywhere
+    # WrapAtWordBoundaryOrAnywhere = WrapMode.WrapAtWordBoundaryOrAnywhere
+
+    class WrapEngine(Enum):
+        '''Those constants describes which wrapping engine should be used
+
+        .. autosummary::
+          NoWrap
+          FullWrap
+          FastWrap
+          VimWrap
+        '''
+        NoWrap = auto()
+        '''No Wrapping'''
+        FullWrap = auto()
+        '''Full document Wrap at any change, Ideal for small documents (~300 Lines) [Precise] (Slow)'''
+        # FastWrap = auto()
+        # '''Chunk based document Wrap, Default wrap [Fast] (Scrolling position is estimated)'''
+        VimWrap = auto()
+        '''Wrap applied only in the displayed area, [Fastest] (the scrolling is snap to the beginning of the lines)'''
 
     class LineWrapMode(IntEnum):
         '''Those constants describes which wrapping status is required in the document
 
         .. autosummary::
-          NoWrapk
-          WidgetWidthk
-          FixedWidthk
+          NoWrap
+          WidgetWidth
+          FixedWidth
         '''
         NoWrap       =  0x00
         '''No Wrapping is applied'''

libs/pyTermTk/TermTk/TTkGui/TTkTextWrap/__init__.py

@@ -0,0 +1 @@
+from .text_wrap import *

libs/pyTermTk/TermTk/TTkGui/TTkTextWrap/text_wrap.py

@@ -0,0 +1,223 @@
+# MIT License
+#
+# Copyright (c) 2026 Eugenio Parodi <ceccopierangiolieugenio AT googlemail DOT com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+__all__ = ['TTkTextWrap']
+
+
+from typing import Optional, Tuple
+
+from TermTk.TTkCore.constant import TTkK
+from TermTk.TTkCore.signal import pyTTkSignal, pyTTkSlot
+from TermTk.TTkGui.textdocument import TTkTextDocument
+
+from .text_wrap_data import _RetScreenRows, _WrapState, _ReWrapData
+from .text_wrap_engine import _WrapEngine_Interface
+from .text_wrap_engine_no_wrap import _WrapEngine_NoWrap
+from .text_wrap_engine_vim_wrap import _WrapEngine_VimWrap
+from .text_wrap_engine_fast_wrap import _WrapEngine_FastWrap
+from .text_wrap_engine_full_wrap import _WrapEngine_FullWrap
+
+_wrapEngines = {
+    # TTkK.WrapEngine.FastWrap : _WrapEngine_FastWrap,
+    TTkK.WrapEngine.FullWrap : _WrapEngine_FullWrap,
+    TTkK.WrapEngine.VimWrap : _WrapEngine_VimWrap,
+    TTkK.WrapEngine.NoWrap : _WrapEngine_NoWrap,
+}
+
+class TTkTextWrap():
+    '''TTkTextWrap:
+
+    Incremental text wrapping helper for :py:class:`TTkTextDocument`.
+    It maps document positions to wrapped screen rows and vice versa.
+    '''
+    __slots__ = (
+        '_wrapState',
+        '_wrapEngine',
+
+        # Signals
+        'wrapChanged'
+        )
+
+    _wrapState: _WrapState
+    _wrapEngine: _WrapEngine_Interface
+    wrapChanged: pyTTkSignal
+    '''
+    This signal is emitted whenever wrapped line mapping changes.
+
+    It is triggered after incremental updates from document edits and after
+    explicit full rewrap requests.
+    '''
+
+    def __init__(self, document:TTkTextDocument) -> None:
+        '''Create a wrap manager bound to a text document.
+
+        :param document: the source text document to wrap.
+        :type document: :py:class:`TTkTextDocument`
+        '''
+        # signals
+        self.wrapChanged = pyTTkSignal()
+
+        self._wrapState = _WrapState(
+            size=80,
+            tabSpaces=4,
+            textDocument=document,
+            wordWrapMode=TTkK.WrapAnywhere,
+        )
+        self._wrapEngine = _WrapEngine_NoWrap(state=self._wrapState)
+        document.contentsChange.connect(self._documentContentsChange)
+
+    @pyTTkSlot(int,int,int)
+    def _documentContentsChange(self, line:int, removed:int, added:int) -> None:
+        self._wrapEngine.rewrap(data=_ReWrapData(line,added,removed))
+        self.wrapChanged.emit()
+
+    def engine(self) -> TTkK.WrapEngine:
+        for _e, _t in _wrapEngines.items():
+            if isinstance(self._wrapEngine, _t):
+                return _e
+        return TTkK.WrapEngine.NoWrap
+
+    def setEngine(self, engine:TTkK.WrapEngine, width:Optional[int]=None) -> None:
+        '''Switch the wrapping backend implementation.
+
+        :param engine: engine selector from :py:class:`TTkK.WrapEngine`.
+        :type engine: :py:class:`TTkK.WrapEngine`
+        :param width: optional wrap width applied before switching engines.
+        :type width: Optional[int]
+        '''
+        engine_class = _wrapEngines.get(engine, _WrapEngine_NoWrap)
+        if isinstance(self._wrapEngine, engine_class):
+            return
+        if width is not None:
+            self._wrapState.size = width
+        self._wrapEngine = engine_class(state=self._wrapState)
+        self.rewrap()
+
+    def size(self) -> int:
+        '''Return the estimated wrapped row count.
+
+        :return: wrapped size in screen rows.
+        :rtype: int
+        '''
+        return self._wrapEngine.size()
+
+    def documentLineCount(self) -> int:
+        '''Return the number of logical data lines in the document.
+
+        :return: document line count.
+        :rtype: int
+        '''
+        return self._wrapState.textDocument.lineCount()
+
+    def wrapWidth(self) -> int:
+        '''Return the current wrap width in terminal cells.
+
+        :return: wrap width.
+        :rtype: int
+        '''
+        return self._wrapState.size
+
+    def setWrapWidth(self, width:int) -> None:
+        '''Set wrap width and trigger a full rewrap.
+
+        :param width: target width in terminal cells.
+        :type width: int
+        '''
+        self._wrapState.size = width
+        self.rewrap()
+
+    def wordWrapMode(self) -> TTkK.WrapMode:
+        '''Return the active word-wrap mode.
+
+        :return: current wrap mode.
+        :rtype: :py:class:`TTkK.WrapMode`
+        '''
+        return self._wrapState.wordWrapMode
+
+    def setWordWrapMode(self, mode:TTkK.WrapMode) -> None:
+        '''Set the word-wrap mode and invalidate cached wrapping.
+
+        :param mode: new wrap mode.
+        :type mode: :py:class:`TTkK.WrapMode`
+        '''
+        self._wrapState.wordWrapMode = mode
+        self.rewrap()
+
+    def screenRows(self, y:int, h:int) -> _RetScreenRows:
+        '''Return wrapped slices visible in the requested viewport.
+
+        :param y: first screen row.
+        :type y: int
+        :param h: number of rows to extract.
+        :type h: int
+
+        :return: wrapped row slices.
+        :rtype: List[:py:class:`_WrapLine`]
+        '''
+        if h <= 0:
+            return _RetScreenRows(y=y, rows=[])
+        return self._wrapEngine.screenRows(y=y,h=h)
+
+    def rewrap(self) -> None:
+        '''Force a complete wrap refresh and emit ``wrapChanged``.
+
+        This invalidates any incremental wrapping cache maintained by the
+        active engine.
+        '''
+        self._wrapEngine.rewrap()
+        self.wrapChanged.emit()
+
+    def dataToScreenPosition(self, line:int, pos:int) -> Tuple[int, int]:
+        '''Map a document position to wrapped screen coordinates.
+
+        :param line: logical line index.
+        :type line: int
+        :param pos: character position in the logical line.
+        :type pos: int
+        :return: ``(x, y)`` wrapped screen coordinates.
+        :rtype: Tuple[int, int]
+        '''
+        return self._wrapEngine.dataToScreenPosition(line=line, pos=pos)
+
+    def screenToDataPosition(self, x:int, y:int) -> Tuple[int, int]:
+        '''Map wrapped screen coordinates to a document position.
+
+        :param x: horizontal screen coordinate.
+        :type x: int
+        :param y: vertical screen coordinate.
+        :type y: int
+        :return: ``(line, pos)`` document position.
+        :rtype: Tuple[int, int]
+        '''
+        return self._wrapEngine.screenToDataPosition(x=x, y=y)
+
+    def normalizeScreenPosition(self, x:int, y:int) -> Tuple[int, int]:
+        '''Snap a screen position to the nearest editable character cell.
+
+        :param x: horizontal widget-relative coordinate.
+        :type x: int
+        :param y: vertical widget-relative coordinate.
+        :type y: int
+        :return: normalized ``(x, y)`` screen position.
+        :rtype: Tuple[int, int]
+        '''
+        return self._wrapEngine.normalizeScreenPosition(x=x, y=y)