shortcutxl 0.2.13 → 0.2.15

package/xll/modules/shortcut_xl/_navigate.py

@@ -0,0 +1,115 @@
+"""Navigate Excel to a specific cell — used during diff review.
+
+Highlights the cursor cell with a colored border via direct Range
+formatting. Visible even when Excel doesn't have focus (unlike
+.Select() which only shows when Excel is foreground).
+
+Thread safety: called via _run_on_main, serialized by s_exec_lock.
+"""
+
+from shortcut_xl._log import xl_log
+from shortcut_xl.api.utils.helpers import extract_sheet_and_range
+
+# Excel COM constants
+_XL_EDGE_LEFT = 7
+_XL_EDGE_TOP = 8
+_XL_EDGE_BOTTOM = 9
+_XL_EDGE_RIGHT = 10
+_XL_CONTINUOUS = 1
+_XL_LINE_STYLE_NONE = -4142
+_XL_MEDIUM = -4138
+
+_CURSOR_BLUE = 0xFF0000    # BGR — distinct from yellow change highlights
+_BORDER_EDGES = (_XL_EDGE_LEFT, _XL_EDGE_TOP, _XL_EDGE_BOTTOM, _XL_EDGE_RIGHT)
+
+# Current cursor state — at most one cell highlighted at a time.
+_cursor_ws = None       # COM Worksheet of the current cursor cell
+_cursor_address = None  # e.g. "B5"
+
+
+def parse_cell_ref(cell_ref):
+    """Parse a cell reference into (workbook, sheet, address).
+
+    Supports single cells and ranges:
+      "[Book1]Sheet1!A1"     → ("Book1", "Sheet1", "A1")
+      "Sheet1!A1:E1"         → (None,    "Sheet1", "A1:E1")
+
+    Returns (None, None, None) if the reference is invalid.
+    """
+    rest = cell_ref
+    workbook = None
+
+    if rest.startswith('['):
+        close = rest.find(']')
+        if close <= 1:          # missing or empty workbook name
+            return None, None, None
+        workbook = rest[1:close]
+        rest = rest[close + 1:]
+
+    sheet, address = extract_sheet_and_range(rest)
+    if not sheet or not address:
+        return None, None, None
+
+    return workbook, sheet, address
+
+
+def _resolve_worksheet(app, workbook, sheet):
+    """Get the COM Worksheet object for the given workbook/sheet names."""
+    if workbook:
+        return app.Workbooks(workbook).Worksheets(sheet)
+    return app.Worksheets(sheet)
+
+
+def _set_border(rng, color, line_style, weight):
+    """Apply border styling to all four edges of a range."""
+    for edge in _BORDER_EDGES:
+        b = rng.Borders(edge)
+        b.LineStyle = line_style
+        if line_style != _XL_LINE_STYLE_NONE:
+            b.Color = color
+            b.Weight = weight
+
+
+def _clear_cursor():
+    """Remove the border from the current cursor cell, if any."""
+    global _cursor_ws, _cursor_address
+    if _cursor_ws is None or _cursor_address is None:
+        return
+    try:
+        _set_border(_cursor_ws.Range(_cursor_address), 0, _XL_LINE_STYLE_NONE, 0)
+    except Exception as e:
+        xl_log(f"_clear_cursor({_cursor_address}): {e}")
+    _cursor_ws = None
+    _cursor_address = None
+
+
+def navigate_to_cell(app, cell_ref):
+    """Highlight the cell with a colored border.
+
+    *cell_ref* is "[Book1]Sheet1!A1" or "Sheet1!A1".
+    Clears the previous cursor border before applying the new one.
+    Returns True on success, False on failure.
+    """
+    global _cursor_ws, _cursor_address
+
+    workbook, sheet, address = parse_cell_ref(cell_ref)
+    if not sheet or not address:
+        return False
+
+    _clear_cursor()
+
+    try:
+        ws = _resolve_worksheet(app, workbook, sheet)
+        rng = ws.Range(address)
+        _set_border(rng, _CURSOR_BLUE, _XL_CONTINUOUS, _XL_MEDIUM)
+        _cursor_ws = ws
+        _cursor_address = address
+        return True
+    except Exception as e:
+        xl_log(f"navigate_to_cell({cell_ref}): {e}")
+        return False
+
+
+def clear_navigate_cursor():
+    """Remove the cursor border. Called on approval accept/reject."""
+    _clear_cursor()

package/xll/modules/shortcut_xl/_threading.py

@@ -6,12 +6,12 @@ This matches the pattern used by PyXLL, Excel-DNA, and xlwings:
 background threads enqueue work, a timer on the main thread drains it.
 """
 
-import threading
-import queue
 import ctypes
+import queue
+import threading
 from ctypes import wintypes
-from shortcut_xl._log import xl_log
 
+from shortcut_xl._log import xl_log
 
 # COM error code: Excel is busy (VBA_E_IGNORE = 0x800AC472)
 _VBA_E_IGNORE = -2146777998
@@ -44,6 +44,7 @@ def _is_excel_busy(e):
 
 # Persist main thread ID in builtins so it survives hot-reload.
 import builtins
+
 _main_thread_id = getattr(builtins, '_shortcutxl_main_thread_id', None)
 if _main_thread_id is None:
     _main_thread_id = threading.current_thread().ident

package/xll/modules/shortcut_xl/_tracking.py

@@ -7,9 +7,9 @@ sheets) not O(workbook), and the agent gets raw COM objects for everything
 below the Worksheet level — zero overhead on Range reads/writes.
 """
 
-from shortcut_xl.api.utils.helpers import col_letter
-from shortcut_xl.api.utils.com_utils import normalize_2d
 from shortcut_xl._log import xl_log
+from shortcut_xl.api.utils.com_utils import normalize_2d
+from shortcut_xl.api.utils.helpers import col_letter
 
 
 class _SheetSnapshot:
@@ -69,6 +69,9 @@ def _diff_snapshots(sheet_name, before, after):
                     formula = _get_formula(after, ri, ci)
                     if formula:
                         entry['formula'] = formula
+                    old_formula = _get_formula(before, ri, ci)
+                    if old_formula:
+                        entry['oldFormula'] = old_formula
                     changes.append(entry)
         return changes
 
@@ -105,6 +108,9 @@ def _diff_snapshots(sheet_name, before, after):
                 formula = _get_formula_abs(after, row, col)
                 if formula:
                     entry['formula'] = formula
+                old_formula = _get_formula_abs(before, row, col)
+                if old_formula:
+                    entry['oldFormula'] = old_formula
                 changes.append(entry)
     return changes
 
@@ -136,8 +142,14 @@ class DirtyTracker:
             try:
                 after = _SheetSnapshot(ws)
                 changes = _diff_snapshots(name, before, after)
-                # Enrich with numberFormat (can't bulk-read mixed ranges)
+                # Enrich with workbook name + numberFormat
+                try:
+                    wb_name = ws.Parent.Name
+                except Exception:
+                    wb_name = None
                 for entry in changes:
+                    if wb_name:
+                        entry['workbook'] = wb_name
                     try:
                         fmt = ws.Range(entry['address']).NumberFormat
                         if fmt and fmt != 'General':

package/xll/modules/shortcut_xl/api/__init__.py

@@ -1,4 +1,4 @@
 """API layer — Workbook/Worksheet wrappers and supporting modules."""
 
-from shortcut_xl.api.workbook import Workbook
-from shortcut_xl.api.worksheet import Worksheet
+from shortcut_xl.api.workbook import Workbook as Workbook
+from shortcut_xl.api.worksheet import Worksheet as Worksheet

package/xll/modules/shortcut_xl/api/format.py

@@ -5,14 +5,19 @@ with Good / Issues breakdown and row sampling.
 """
 
 import re
-from shortcut_xl.api.utils.numerical import NUMERIC_TYPES
+
 from shortcut_xl.api.categorize import (
+    GOOD,
+    HARDCODED_NUMBER,
+    HARDCODED_NUMBER_IN_FORMULA,
+    INVALID_FORMULA,
+    LARGE_PERCENTAGE,
     categorize_cells,
-    GOOD, LARGE_PERCENTAGE, HARDCODED_NUMBER,
-    HARDCODED_NUMBER_IN_FORMULA, INVALID_FORMULA,
-    is_com_error, com_error_to_str,
+    com_error_to_str,
+    is_com_error,
 )
 from shortcut_xl.api.utils.helpers import col_letter
+from shortcut_xl.api.utils.numerical import NUMERIC_TYPES
 
 # Display constants
 MAX_ROWS_TO_SHOW = 10
@@ -165,7 +170,7 @@ def _format_row(sheet, row, entries, indent=2, show_issues=True, show_count=True
     lines.append(f'{ind}{sheet}!Row {row + 1} ({col_range}){count_suffix}')
 
     samples = _sample_first_last(entries, MAX_SAMPLES_PER_ROW)
-    for cell, issues, _col in samples:
+    for cell, _issues, _col in samples:
         fmt = cell.get('numberFormat')
         old_str = format_value(cell.get('oldValue'), fmt)
         new_str = _display_value(cell)

package/xll/modules/shortcut_xl/api/range_formatter.py

@@ -9,11 +9,11 @@ Replicates the TypeScript processCellRange / RangeFormatter logic:
 
 from __future__ import annotations
 
-from shortcut_xl.api.utils.helpers import index_to_address
 from shortcut_xl.api.style import read_style
-from shortcut_xl.api.utils.numerical import is_numerical, NUMERIC_TYPES
+from shortcut_xl.api.utils.helpers import index_to_address
+from shortcut_xl.api.utils.numerical import NUMERIC_TYPES, is_numerical
 from shortcut_xl.api.utils.ranges import consolidate_ranges
-from shortcut_xl.api.utils.style_utils import get_style_key, get_style_description
+from shortcut_xl.api.utils.style_utils import get_style_description, get_style_key
 
 # ---------------------------------------------------------------------------
 # Constants (match TypeScript range-processing/types.ts)
@@ -349,8 +349,8 @@ def format_cell_range(
     5. Context from cells to the left
     6. Context from cells above
     """
+    from shortcut_xl.api.utils.com_utils import make_range, normalize_2d
     from shortcut_xl.api.utils.helpers import parse_range
-    from shortcut_xl.api.utils.com_utils import normalize_2d, make_range
 
     sr, sc, er, ec = parse_range(range_addr)
     rows = er - sr + 1

package/xll/modules/shortcut_xl/api/workbook.py

@@ -5,17 +5,14 @@ Output formats match the SpreadJS equivalents.
 
 from __future__ import annotations
 
-from typing import Any
-
+from shortcut_xl.api.categorize import com_error_to_str, is_com_error
+from shortcut_xl.api.named_ranges import get_named_range_info
 from shortcut_xl.api.utils.helpers import (
-    col_letter,
+    extract_sheet_and_range,
     index_to_address,
     is_error_value,
     parse_range,
-    extract_sheet_and_range,
 )
-from shortcut_xl.api.categorize import is_com_error, com_error_to_str
-from shortcut_xl.api.named_ranges import get_named_range_info
 from shortcut_xl.api.worksheet import Worksheet
 
 # Error check constants (match SpreadJS error-checker.ts)
@@ -263,8 +260,6 @@ class Workbook:
                 rng.Value = com_error_to_str(data)
             return
         # Multi-cell range
-        rows = rng.Rows.Count
-        cols = rng.Columns.Count
         for r_idx, row in enumerate(data):
             if not isinstance(row, tuple):
                 row = (row,)

package/xll/modules/shortcut_xl/api/worksheet.py

@@ -11,17 +11,17 @@ import json
 import re
 from typing import Any
 
-from shortcut_xl.api.categorize import is_com_error, com_error_to_str
-from shortcut_xl.api.utils.numerical import NUMERIC_TYPES
+from shortcut_xl._log import xl_log
+from shortcut_xl.api.categorize import com_error_to_str, is_com_error
+from shortcut_xl.api.picture import add_picture
+from shortcut_xl.api.range_formatter import format_cell_range
+from shortcut_xl.api.style import read_style
+from shortcut_xl.api.utils.com_utils import make_range, normalize_2d
 from shortcut_xl.api.utils.helpers import (
     index_to_address,
     parse_range,
 )
-from shortcut_xl.api.utils.com_utils import normalize_2d, make_range
-from shortcut_xl._log import xl_log
-from shortcut_xl.api.range_formatter import format_cell_range
-from shortcut_xl.api.style import read_style
-from shortcut_xl.api.picture import add_picture
+from shortcut_xl.api.utils.numerical import NUMERIC_TYPES
 
 # Excel xlAutoFillType enum values
 _XL_FILL_DEFAULT = 0

package/xll/modules/shortcut_xl/api-reference.py

@@ -3,6 +3,9 @@ shortcut_xl API Reference
 All symbols are auto-imported in excel_exec — no import statements needed.
 """
 
+from typing import Any
+
+
 class Workbook:
     """
     Workbook wrapper.