Add PanAndZoom and headless testing docs content

Author: wieslawsoltes

site/articles/advanced/custom-bounds-resize-and-rotation.md

@@ -0,0 +1,42 @@
+---
+title: "Custom Bounds, Resize, and Rotation"
+---
+
+# Custom Bounds, Resize, and Rotation
+
+If the built-in behavior is close but not exact, `ZoomBorder` exposes virtual hooks for custom policy.
+
+## Extensibility Points
+
+- `GetContentBounds()`: return the effective content bounds used for custom constraints
+- `ValidateTransform(Matrix newMatrix)`: veto proposed transforms
+- `OnResized(Size oldSize, Size newSize)`: apply custom resize policy
+
+Example:
+
+```csharp
+public class CustomZoomBorder : ZoomBorder
+{
+    protected override Rect GetContentBounds() => base.GetContentBounds();
+
+    protected override bool ValidateTransform(Matrix newMatrix)
+    {
+        return base.ValidateTransform(newMatrix);
+    }
+
+    protected override void OnResized(Size oldSize, Size newSize)
+    {
+        base.OnResized(oldSize, newSize);
+    }
+}
+```
+
+## When To Override
+
+- content bounds depend on domain data rather than only the child's measured bounds
+- certain zoom or pan regions must be blocked
+- resize behavior needs to preserve a custom anchor or workflow-specific invariant
+
+## Rotation Considerations
+
+Rotation state is configurable, but advanced rotation-heavy surfaces should validate how rotation interacts with bounds, serialization, and any custom overlay math before relying on it as a full scene-graph feature.

site/articles/advanced/diagnostics-and-testing.md

@@ -0,0 +1,41 @@
+---
+title: "Diagnostics and Testing"
+---
+
+# Diagnostics and Testing
+
+This repository is already test-heavy, which makes the codebase a good reference for both usage and expected behavior.
+
+## PanAndZoom Test Coverage Areas
+
+The main test project covers:
+
+- pointer, wheel, keyboard, and gesture interaction
+- bounds modes and dynamic zoom limits
+- view history, saved views, and state serialization
+- rotation, scale indicator, viewport culling, and `ILogicalScrollable`
+- Appium-style APIs and recording workflows
+
+## HeadlessTestingFramework Test Coverage Areas
+
+The second test project focuses on:
+
+- touch simulation and gesture recognizer helpers
+- tree validation, tree comparison, and XPath helpers
+- recording infrastructure and multi-touch helper construction
+
+## Useful Debug Artifacts
+
+- generated Lunet API docs under `site/.lunet/build/www/api`
+- recording output from `HeadlessScreenRecorder` or `RecordingSession`
+- tree and template comparison summaries from `TreeComparer` and `TemplateComparer`
+
+## Documentation Validation
+
+Validate docs locally with:
+
+```bash
+./check-docs.sh
+```
+
+That rebuilds the Lunet site and API reference from the same sources used by CI.

site/articles/advanced/menu.yml

@@ -0,0 +1,5 @@
+advanced:
+  - {path: readme.md, title: "Advanced"}
+  - {path: custom-bounds-resize-and-rotation.md, title: "Custom Bounds, Resize, and Rotation"}
+  - {path: scrollviewer-and-logical-scroll.md, title: "ScrollViewer and Logical Scroll"}
+  - {path: diagnostics-and-testing.md, title: "Diagnostics and Testing"}

site/articles/advanced/readme.md

@@ -0,0 +1,9 @@
+---
+title: "Advanced"
+---
+
+# Advanced
+
+- [Custom Bounds, Resize, and Rotation](custom-bounds-resize-and-rotation.md)
+- [ScrollViewer and Logical Scroll](scrollviewer-and-logical-scroll.md)
+- [Diagnostics and Testing](diagnostics-and-testing.md)

site/articles/advanced/scrollviewer-and-logical-scroll.md

@@ -0,0 +1,28 @@
+---
+title: "ScrollViewer and Logical Scroll"
+---
+
+# ScrollViewer and Logical Scroll
+
+`ZoomBorder` implements `ILogicalScrollable` so it can participate in Avalonia scrolling infrastructure instead of fighting it.
+
+## Why This Matters
+
+Embedding zoomable content inside a `ScrollViewer` is common, but naive implementations can create feedback loops between viewport transforms and host scroll offsets.
+
+`ZoomBorder` addresses that through:
+
+- the `ILogicalScrollable` implementation in `ZoomBorder.ILogicalScrollable.cs`
+- `CalculateScrollable(...)` for computing extent, viewport, and offset from source bounds and the active matrix
+
+## Practical Guidance
+
+- Put a `ScrollViewer` around the control only when you want scrollbars or host-level scrolling semantics.
+- Review wheel configuration carefully; wheel input may need to pan instead of zoom in some host layouts.
+- Use the existing unit tests around logical scrolling as the baseline behavior contract when modifying this area.
+
+## Related APIs
+
+- `Avalonia.Controls.PanAndZoom.ZoomBorder.CalculateScrollable(Avalonia.Rect,Avalonia.Size,Avalonia.Media.Transformation.Matrix,Avalonia.Size@,Avalonia.Size@,Avalonia.Vector@)`
+- `BringIntoView(...)` behavior through the scrollable contract
+- [Bounds, Wheel, and Resize](../guides/bounds-wheel-and-resize.md)

site/articles/build-and-package.md

@@ -0,0 +1,45 @@
+---
+title: "Build and Package"
+---
+
+# Build and Package
+
+Build, test, and pack from repository root:
+
+```bash
+dotnet restore
+dotnet build -c Release --no-restore
+dotnet test -c Release --no-build
+dotnet pack -c Release --no-build -o artifacts/packages
+```
+
+Packages are written to `artifacts/packages` as `.nupkg` and `.snupkg` files.
+
+## Build The Sample App
+
+```bash
+dotnet build samples/AvaloniaDemo.Desktop/AvaloniaDemo.Desktop.csproj -c Release
+```
+
+## Build Documentation
+
+```bash
+./build-docs.sh
+./check-docs.sh
+./serve-docs.sh
+```
+
+PowerShell:
+
+```powershell
+./build-docs.ps1
+./serve-docs.ps1
+```
+
+Documentation output is written to `site/.lunet/build/www`.
+
+## CI
+
+- `build.yml` builds, tests, and packs the repository
+- `docs.yml` builds the Lunet site and publishes it to GitHub Pages
+- `release.yml` builds release packages and publishes NuGet artifacts

site/articles/concepts/interaction-model.md

@@ -0,0 +1,36 @@
+---
+title: "Interaction Model"
+---
+
+# Interaction Model
+
+`ZoomBorder` combines several input paths, each with its own enable flags and behavior settings.
+
+## Pointer And Wheel
+
+- dragging pans the content using the configured `PanButton`
+- wheel input is controlled by `WheelBehavior`, `WheelWithCtrl`, `WheelWithShift`, `WheelZoomSensitivity`, and `WheelPanSensitivity`
+- `EnablePan` and `EnableZoom` are the first-level switches
+
+## Gestures
+
+When `EnableGestures` is `true`, the control attaches pinch and scroll recognizers. Additional flags refine what a gesture is allowed to do:
+
+- `EnableGestureZoom`
+- `EnableGestureTranslation`
+- `EnableGestureRotation`
+- `EnableSimultaneousPanZoom`
+
+The gesture path is useful on touch devices and in headless tests that use gesture recognizers rather than just pointer emulation.
+
+## Keyboard
+
+With `EnableKeyboardNavigation`, the control listens for built-in navigation and zoom shortcuts. That makes the control usable without custom command wiring, but the command properties are still available for toolbar and MVVM scenarios.
+
+## Commands
+
+`ZoomBorder` exposes `ICommand` properties such as `ZoomInCommand`, `ResetCommand`, `FitCommand`, and history navigation commands. These commands reflect control state and are the preferred way to surface interaction in view models.
+
+## Animation
+
+Most high-level methods accept an `animate` or `skipTransitions` argument. `EnableAnimations` and `AnimationDuration` determine whether transitions should be applied by default for command-driven view changes.

site/articles/concepts/menu.yml

@@ -0,0 +1,5 @@
+concepts:
+  - {path: readme.md, title: "Concepts"}
+  - {path: transform-and-coordinate-spaces.md, title: "Transform and Coordinate Spaces"}
+  - {path: interaction-model.md, title: "Interaction Model"}
+  - {path: view-state-and-persistence.md, title: "View State and Persistence"}

site/articles/concepts/readme.md

@@ -0,0 +1,9 @@
+---
+title: "Concepts"
+---
+
+# Concepts
+
+- [Transform and Coordinate Spaces](transform-and-coordinate-spaces.md)
+- [Interaction Model](interaction-model.md)
+- [View State and Persistence](view-state-and-persistence.md)

site/articles/concepts/transform-and-coordinate-spaces.md

@@ -0,0 +1,50 @@
+---
+title: "Transform and Coordinate Spaces"
+---
+
+# Transform and Coordinate Spaces
+
+`ZoomBorder` maintains a transform matrix that maps content coordinates into viewport coordinates. Most higher-level APIs are thin wrappers over that model.
+
+## The Three Views Of Space
+
+- content space: the original coordinate system of the child control
+- viewport space: the visible region inside the `ZoomBorder`
+- screen-like vectors and sizes: transformed measurements derived from the active matrix
+
+## Core Conversion APIs
+
+Use these methods instead of manually duplicating matrix math:
+
+- `Avalonia.Controls.PanAndZoom.ZoomBorder.ViewportToContent(Avalonia.Point)`
+- `Avalonia.Controls.PanAndZoom.ZoomBorder.ContentToViewport(Avalonia.Point)`
+- `Avalonia.Controls.PanAndZoom.ZoomBorder.ViewportToContent(Avalonia.Rect)`
+- `Avalonia.Controls.PanAndZoom.ZoomBorder.ContentToViewport(Avalonia.Rect)`
+- `Avalonia.Controls.PanAndZoom.ZoomBorder.GetContentToScreenMatrix`
+- `Avalonia.Controls.PanAndZoom.ZoomBorder.GetScreenToContentMatrix`
+
+These become important when:
+
+- zooming to a region selected in viewport space
+- showing overlays aligned with content coordinates
+- translating pointer positions into domain coordinates on a diagram or image
+
+## Matrix Helpers
+
+`Avalonia.Controls.PanAndZoom.MatrixHelper` contains reusable helpers such as:
+
+- `Translate(...)`
+- `ScaleAt(...)`
+- `Rotation(...)`
+- `TransformPoint(...)`
+
+It is useful when you build custom overlays or test matrix calculations separately from the control.
+
+## Visible Area Queries
+
+Two methods are especially important for viewport-aware logic:
+
+- `Avalonia.Controls.PanAndZoom.ZoomBorder.GetVisibleContentBounds`
+- `Avalonia.Controls.PanAndZoom.ZoomBorder.GetViewportBounds`
+
+They allow item culling, overlay rendering, and "jump to region" UX without duplicating coordinate conversion code.