feat: bump version to 0.7.3, add support for image and chart copying in openpyxl engine

Update the version to 0.7.3 and enhance the OpenpyxlEngine to support copying images and charts between worksheets. Introduce new methods for image and chart handling, ensuring that visual elements are preserved during sheet imports. Add comprehensive tests to validate the functionality of image and chart preservation, including end-to-end tests for various scenarios.

Author: dakixr

AGENTS.md

@@ -0,0 +1,149 @@
+# AGENTS.md (repo instructions for coding agents)
+
+This repository is `xpyxl`, a typed Python 3.12 library for building and rendering Excel (and HTML) reports.
+
+If you are an agent making changes:
+- Keep diffs small and focused.
+- Prefer the existing patterns in `src/xpyxl/` and tests in `tests/`.
+- Do not add new tooling/deps unless requested.
+
+## Repo layout
+- `src/xpyxl/`: library code (public API re-exported from `src/xpyxl/__init__.py`).
+- `src/xpyxl/engines/`: rendering backends.
+- `tests/`: pytest suite.
+- `tests/end_to_end/`: demo modules and an end-to-end test that saves files into `.testing/`.
+- `scripts/`: ad-hoc scripts (e.g. benchmarking).
+
+## Environment
+- Python: `3.12` (see `.python-version` and CI workflow).
+- Dependency manager/build tool: `uv` (see `uv.lock` and `.github/workflows/publish.yml`).
+
+## Commands (build / lint / test)
+
+### Install / sync
+- Create/sync a dev environment: `uv sync --dev`
+- Run a one-off command in the env: `uv run <cmd>`
+
+Notes:
+- `uv.lock` exists; prefer workflows that respect the lock file for reproducibility.
+- If you add/remove dependencies, update `pyproject.toml` and refresh `uv.lock`.
+
+### Tests (pytest)
+- Run all tests: `uv run pytest`
+- Run tests with output: `uv run pytest -q` or `uv run pytest -vv`
+- Stop on first failure: `uv run pytest -x --maxfail=1`
+
+Run a single file:
+- `uv run pytest tests/test_html_engine.py`
+
+Run a single test (node id):
+- `uv run pytest tests/test_html_engine.py::test_tailwind_cdn_included`
+
+Run tests matching a substring/expr:
+- `uv run pytest -k "html and not missing"`
+
+Run only end-to-end test:
+- `uv run pytest tests/end_to_end/test_demo.py`
+
+### Type checking (lint-ish)
+There is no dedicated linter configured in this repo, but type checking is part of the dev toolchain.
+- Run Pyright: `uv run pyright`
+
+### Build
+CI builds with `uv build`.
+- Build sdist + wheel: `uv build --sdist --wheel`
+
+### Misc
+- Benchmark script: `uv run python scripts/benchmark.py`
+
+### Quick sanity (optional)
+These are useful when iterating on core rendering/layout changes:
+- Import check: `uv run python -c "import xpyxl"`
+- Bytecode compile: `uv run python -m compileall src/xpyxl`
+- Minimal save smoke test: `uv run python -c "import xpyxl as x; wb=x.workbook()[x.sheet('S')[x.row()['ok']]]; wb.save(engine='html')"`
+
+### CI parity
+Before opening a PR, prefer running:
+- `uv run pyright`
+- `uv run pytest`
+
+## Cursor/Copilot rules
+- No Cursor rules found in `.cursor/rules/` or `.cursorrules` at time of writing.
+- No Copilot instructions found in `.github/copilot-instructions.md` at time of writing.
+
+If these files appear later, follow them and update this document accordingly.
+
+## Code style (Python)
+
+### General
+- Target Python `>=3.12`.
+- Prefer small, composable functions over deeply nested logic.
+- Favor determinism: avoid randomness/time dependence in core logic unless explicitly required.
+
+### Imports
+Follow the existing import ordering:
+1. `from __future__ import annotations` (used widely; include in new modules).
+2. Standard library imports.
+3. Third-party imports.
+4. Local imports (`from .foo import Bar`).
+
+Prefer:
+- `collections.abc` for `Sequence`, `Mapping`, etc.
+- `pathlib.Path` for filesystem paths.
+
+### Formatting
+- No formatter is enforced by configuration files in this repo.
+- Keep formatting consistent with the current codebase (Black-compatible style is already used: trailing commas, hanging indents, one-arg-per-line when wrapping).
+- Keep line length reasonable (the current code is typically ~88-ish, but follow surrounding code).
+
+### Types
+- The codebase is fully typed; keep/add type hints for new/changed public functions.
+- Prefer modern syntax:
+  - `X | None` instead of `Optional[X]`.
+  - `list[str]`, `tuple[int, ...]`, etc.
+  - `TypeAlias` for aliases (see `src/xpyxl/nodes.py`).
+- Use `assert_never(...)` for exhaustiveness in tagged unions when appropriate.
+- Avoid `Any` unless it is truly necessary at API boundaries.
+
+### Naming
+- Modules: `snake_case.py`.
+- Classes: `CamelCase`.
+- Functions/vars: `snake_case`.
+- Constants: `UPPER_SNAKE_CASE`.
+- Private helpers: prefix `_`.
+
+### Data model & immutability
+- Core AST-like nodes are immutable dataclasses (`@dataclass(frozen=True)`).
+- Prefer returning new values over mutating existing nodes.
+
+### Errors and validation
+- Use `TypeError` for incorrect types/shape (e.g. passing a `RowNode` where a scalar cell is expected).
+- Use `ValueError` for invalid values/ranges (e.g. negative sizes).
+- Error messages should be actionable and stable (tests may match them).
+- Prefer:
+  - `msg = "..."; raise ValueError(msg)` when the message is reused or multi-line.
+  - `raise ValueError("...")` for simple one-liners.
+
+### Public API surface
+- Public API is re-exported in `src/xpyxl/__init__.py`.
+- If you add a new user-facing function/type, consider whether it must be exported and added to `__all__`.
+- Keep backwards compatibility in mind: avoid renames/breaking changes unless requested.
+
+### Performance
+- Rendering can be performance-sensitive. Avoid introducing quadratic behavior in layout/render loops.
+- Prefer tuples for immutable collections exposed on nodes (consistent with current dataclasses).
+
+## Tests
+- Tests use `pytest`.
+- Prefer unit tests in `tests/` and keep them deterministic.
+- For exception behavior, use `pytest.raises(..., match=...)` with a stable substring/regex.
+- The end-to-end test writes to `.testing/` (ignored by git); do not commit generated output files.
+
+### Test file I/O
+- Prefer `tempfile.TemporaryDirectory()` for tests that write outputs.
+- If you need stable artifacts for manual inspection, write under `.testing/`.
+- Keep file names deterministic to avoid flaky diffs.
+
+## Git hygiene
+- Do not commit local artifacts: `__pycache__/`, `.pytest_cache/`, `.testing/`, `*.egg-info/`.
+- Keep `uv.lock` in sync with `pyproject.toml` when dependencies change.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xpyxl"
-version = "0.7.2"
+version = "0.7.3"
 description = "Create styled excel reports with declarative python."
 readme = "README.md"
 authors = [{ name = "dakixr", email = "[email protected]" }]
@@ -9,6 +9,7 @@ dependencies = ["openpyxl>=3.1.5", "xlsxwriter>=3.1.0"]
 
 [dependency-groups]
 dev = [
+    "pillow>=12.1.0",
     "pyright>=1.1.406",
     "pytest>=9.0.2",
 ]

src/xpyxl/engines/openpyxl_engine.py

@@ -390,6 +390,138 @@ def _copy_dimension_attrs(source_dim: object, dest_dim: object) -> None:
         for row, dimension in source_ws.row_dimensions.items():
             _copy_dimension_attrs(dimension, target_ws.row_dimensions[row])
 
+        # Images (photos/pictures)
+        self._copy_images(source_ws, target_ws)
+
+        # Charts
+        self._copy_charts(source_ws, target_ws)
+
+    def _copy_images(self, source_ws: Worksheet, target_ws: Worksheet) -> None:
+        """Copy all images from source worksheet to target worksheet."""
+        try:
+            from openpyxl.drawing.image import Image
+        except ImportError:
+            # Image support not available
+            return
+
+        for img in getattr(source_ws, "_images", []):
+            try:
+                # Get the image data from the ref (BytesIO containing the image data)
+                ref = getattr(img, "ref", None)
+                if ref is None:
+                    continue
+
+                # Seek to start if possible
+                if hasattr(ref, "seek"):
+                    try:
+                        ref.seek(0)
+                    except Exception:
+                        pass
+
+                # Create a new Image instance from the image data
+                new_img = Image(ref)
+
+                # Copy anchor (position in the sheet)
+                anchor = getattr(img, "anchor", None)
+                if anchor is not None:
+                    new_img.anchor = anchor
+
+                # Copy dimensions if set
+                if getattr(img, "width", None) is not None:
+                    new_img.width = img.width
+                if getattr(img, "height", None) is not None:
+                    new_img.height = img.height
+
+                target_ws.add_image(new_img)
+            except Exception:
+                # Image copying is best-effort; skip failures
+                pass
+
+    def _copy_charts(self, source_ws: Worksheet, target_ws: Worksheet) -> None:
+        """Copy all charts from source worksheet to target worksheet.
+
+        When copying charts, we need to update the data references to point
+        to the target sheet instead of the source sheet, since sheet names
+        may differ between source and destination.
+        """
+        source_name = source_ws.title
+        target_name = target_ws.title
+
+        for chart in getattr(source_ws, "_charts", []):
+            try:
+                # Deep copy the chart to avoid sharing references
+                new_chart = copy.deepcopy(chart)
+
+                # Update sheet references in chart data
+                self._update_chart_references(new_chart, source_name, target_name)
+
+                target_ws.add_chart(new_chart)
+            except Exception:
+                # Chart copying is best-effort; skip failures
+                pass
+
+    def _update_chart_references(
+        self, chart: object, old_sheet: str, new_sheet: str
+    ) -> None:
+        """Update all sheet references in a chart from old_sheet to new_sheet."""
+        import re
+
+        def update_ref(formula: str | None) -> str | None:
+            if not formula:
+                return formula
+
+            # Escape special regex chars in old_sheet
+            old_escaped = re.escape(old_sheet)
+
+            # Pattern for quoted sheet name: 'Sheet Name'!
+            quoted_pattern = f"'{old_escaped}'!"
+            # Pattern for unquoted sheet name: SheetName!
+            unquoted_pattern = f"{old_escaped}!"
+
+            # New sheet name (quote if has spaces or special chars)
+            if " " in new_sheet or any(c in new_sheet for c in "'![]:"):
+                new_ref = f"'{new_sheet}'!"
+            else:
+                new_ref = f"{new_sheet}!"
+
+            # Replace quoted version first
+            result = re.sub(quoted_pattern, new_ref, formula)
+            # Then try unquoted version if no change
+            if result == formula:
+                result = re.sub(unquoted_pattern, new_ref, formula)
+
+            return result
+
+        # Update series data references
+        for series in getattr(chart, "series", []):
+            # Value reference (numRef)
+            if hasattr(series, "val") and series.val:
+                num_ref = getattr(series.val, "numRef", None)
+                if num_ref and hasattr(num_ref, "f"):
+                    num_ref.f = update_ref(num_ref.f)
+
+            # Category reference (can be numRef or strRef)
+            if hasattr(series, "cat") and series.cat:
+                cat_num_ref = getattr(series.cat, "numRef", None)
+                if cat_num_ref and hasattr(cat_num_ref, "f"):
+                    cat_num_ref.f = update_ref(cat_num_ref.f)
+
+                cat_str_ref = getattr(series.cat, "strRef", None)
+                if cat_str_ref and hasattr(cat_str_ref, "f"):
+                    cat_str_ref.f = update_ref(cat_str_ref.f)
+
+            # X values (for scatter/bubble charts)
+            if hasattr(series, "xVal") and series.xVal:
+                x_num_ref = getattr(series.xVal, "numRef", None)
+                if x_num_ref and hasattr(x_num_ref, "f"):
+                    x_num_ref.f = update_ref(x_num_ref.f)
+
+            # Y values (for scatter/bubble charts)
+            if hasattr(series, "yVal") and series.yVal:
+                y_num_ref = getattr(series.yVal, "numRef", None)
+                if y_num_ref and hasattr(y_num_ref, "f"):
+                    y_num_ref.f = update_ref(y_num_ref.f)
+
     def _load_source_workbook(self, source: SaveTarget | bytes | BinaryIO) -> Workbook:
         if isinstance(source, (str, Path)):
             return load_workbook(