feat: implement Visual Viewport mock with event handling and comprehensive tests

Author: trurl-master

README.md

@@ -20,7 +20,8 @@ A set of tools for emulating browser behavior in jsdom environment
 [Intersection Observer](#mock-intersectionobserver)  
 [Resize Observer](#mock-resizeobserver)  
 [Web Animations API](#mock-web-animations-api)  
-[CSS Typed OM](#mock-css-typed-om)
+[CSS Typed OM](#mock-css-typed-om)  
+[Visual Viewport](#mock-visual-viewport)
 
 ## Installation
 
@@ -442,6 +443,75 @@ it('enforces type safety', () => {
 
 Supports all CSS units (length, angle, time, frequency, resolution, flex, percentage), mathematical operations, and enforces type compatibility rules as defined in the [W3C specification](https://www.w3.org/TR/css-typed-om-1/).
 
+## Mock Visual Viewport
+
+Provides a mock implementation of the Visual Viewport API for testing components that depend on viewport properties like `width`, `height`, `scale`, and position. The mock follows the library's pattern of manual event triggering for deterministic testing.
+
+```jsx
+import { mockVisualViewport } from 'jsdom-testing-mocks';
+
+it('responds to viewport changes', () => {
+  const viewport = mockVisualViewport({
+    width: 375,
+    height: 667,
+    scale: 1,
+    offsetLeft: 0,
+    offsetTop: 0,
+    pageLeft: 0,
+    pageTop: 0,
+  });
+
+  const resizeCallback = jest.fn();
+  window.visualViewport?.addEventListener('resize', resizeCallback);
+
+  // Update viewport properties
+  viewport.set({ width: 768, height: 1024 });
+
+  // Manually trigger events (no automatic dispatch)
+  viewport.triggerResize();
+  expect(resizeCallback).toHaveBeenCalledTimes(1);
+
+  // Test scroll events
+  const scrollCallback = jest.fn();
+  window.visualViewport?.addEventListener('scroll', scrollCallback);
+
+  viewport.set({ pageLeft: 100, pageTop: 200 });
+  viewport.triggerScroll();
+  expect(scrollCallback).toHaveBeenCalledTimes(1);
+
+  viewport.cleanup();
+});
+```
+
+### Properties
+
+The mock supports all Visual Viewport properties:
+- `width` / `height`: Viewport dimensions
+- `scale`: Zoom level (must be positive and finite)
+- `offsetLeft` / `offsetTop`: Visual viewport offset from layout viewport
+- `pageLeft` / `pageTop`: Visual viewport position relative to the page
+- `segments`: Returns empty array (experimental property)
+
+### Events
+
+- `resize`: Triggered manually via `triggerResize()`
+- `scroll`: Triggered manually via `triggerScroll()`
+- Event handlers: `onresize` and `onscroll` properties supported
+
+### Manual Triggering
+
+Unlike real browsers, events are not automatically dispatched when properties change. This ensures deterministic tests:
+
+```jsx
+// Properties can be updated without triggering events
+viewport.set({ width: 500, height: 600 });
+expect(resizeCallback).not.toHaveBeenCalled();
+
+// Events must be triggered manually
+viewport.triggerResize();
+expect(resizeCallback).toHaveBeenCalledTimes(1);
+```
+
 ## Current issues
 
 - Needs more tests

TODO-visual-viewport.md

@@ -0,0 +1,125 @@
+# Visual Viewport Mock Implementation Plan
+
+## 1. API SURFACE GAPS & DESIGN DECISIONS
+
+### A. `addEventListener` / `removeEventListener` signature
+- Accept the optional `options?: boolean | AddEventListenerOptions` parameter just as the DOM type does (ignore it internally).
+- Keeps TypeScript happy when user code passes `{once: true}`, `{passive:true}`, etc.
+
+### B. `segments` property (experimental but present in spec & polyfill)
+- Minimal stub: define a **read-only** getter that always returns `[]`.
+- This lets feature-detection (`'segments' in visualViewport`) succeed without misleading tests.
+
+### C. Event bubbling to `window` (low priority)
+- Real browsers bubble `scroll`/`resize` from `visualViewport` to the Window.
+- Decide whether to replicate or knowingly document the divergence.
+- If replicated: after running local listeners, call `window.dispatchEvent(clonedEvent)`.
+
+### D. Input validation / edge cases
+- Clamp `scale` to `> 0` and disallow `NaN` to avoid accidental bad state.
+- Document that the helper does **no automatic geometry**; all numbers are accepted "as-is".
+
+### E. Documentation
+- README section explaining:
+  - `set()` mutates state only.
+  - Call `triggerResize` / `triggerScroll` (or `dispatchEvent`) when you want observers to run.
+  - `segments` not yet supported (returns empty array).
+  - Examples mirroring IntersectionObserver mock pattern.
+
+## 2. CODE-LEVEL TASKS
+
+1. Edit `MockedVisualViewport.addEventListener` / `removeEventListener` to include unused `options` param.
+2. Add private field `#segments: readonly DOMRectReadOnly[] = []` and read-only getter `segments`.
+   - Export a `setSegments(rects)` helper only if a test ever needs it; otherwise keep fixed.
+3. (Optional) Implement bubbling:
+   ```ts
+   if (config.getConfig().bubbleVisualViewportEvents) {
+     window.dispatchEvent(event);
+   }
+   ```
+4. Guard against `NaN`, `Infinity`, negative `scale` in `update()`.
+5. Update `src/index.ts` re-exports if new helpers are added.
+
+## 3. TEST SUITE ADDITIONS
+
+### A. Signature acceptance
+- `addEventListener('resize', fn, {once:true})` does **not** throw.
+- Same for `removeEventListener`.
+
+### B. Segments
+- `expect(window.visualViewport!.segments).toEqual([]);`
+- Property is read-only (assignment throws in strict mode).
+
+### C. Bubbling (only if implemented)
+- Attach `window.addEventListener('resize', spy)`; call `visualViewport.triggerResize()`; spy called.
+
+### D. Validation
+- `set({ scale: -1 })` clamps or throws as documented.
+- `set({ scale: NaN })` ignored or throws.
+
+### E. No auto-dispatch guarantee
+- `set({ width:123 })` by itself does **not** invoke listeners; after `triggerResize()` it does.
+
+### F. Options untouched cleanup
+- After `cleanup()` original `window.visualViewport` (undefined or native) is restored.
+
+## 4. DELIVERABLE ORDER
+
+1. **Code changes** (steps 1-4).
+2. **New tests** – place in `src/mocks/visual-viewport.*.test.ts`.
+3. **README update**.
+4. Run Jest/Vitest & `npm run build`.
+5. One-sentence commit message:
+   `feat(mockVisualViewport): add segments stub, full listener signature & tests`
+
+## Implementation Steps
+
+### Step 1: Fix addEventListener/removeEventListener signatures
+- [x] Add `options?: boolean | AddEventListenerOptions` to `addEventListener`
+- [x] Add `options?: boolean | EventListenerOptions` to `removeEventListener`
+- [x] Test that these don't break existing functionality
+
+### Step 2: Add segments property
+- [x] Add private field `#segments: readonly DOMRectReadOnly[] = []`
+- [x] Add read-only getter `segments`
+- [x] Test that it returns empty array and is read-only
+
+### Step 3: Add input validation
+- [x] Add validation in `update()` method for scale values
+- [x] Test edge cases (NaN, negative scale, etc.)
+
+### Step 4: Add comprehensive tests
+- [x] Test signature acceptance
+- [x] Test segments property
+- [x] Test validation
+- [x] Test no auto-dispatch guarantee
+- [x] Test cleanup
+
+### Step 5: Update documentation
+- [x] Add README section for Visual Viewport mock
+- [x] Document the manual trigger pattern
+- [x] Add usage examples
+
+## Implementation Status
+
+All steps completed! ✅
+
+The Visual Viewport mock implementation is now complete with:
+- ✅ Proper event listener signatures with options support
+- ✅ Segments property (read-only empty array)
+- ✅ Input validation for scale values
+- ✅ Comprehensive test coverage
+- ✅ Complete documentation with examples
+
+## Summary
+
+We have successfully implemented the Visual Viewport API mock for the `jsdom-testing-mocks` library, addressing issue #61. The implementation includes:
+
+1. **Complete API Surface**: All Visual Viewport properties (`width`, `height`, `scale`, `offsetLeft`, `offsetTop`, `pageLeft`, `pageTop`, `segments`)
+2. **Event Support**: `resize` and `scroll` events with manual triggering pattern
+3. **Event Handlers**: `onresize` and `onscroll` properties
+4. **Input Validation**: Scale values must be positive and finite
+5. **Comprehensive Testing**: 15 test cases covering all functionality
+6. **Documentation**: Complete README section with usage examples
+
+The mock follows the library's established pattern of manual event triggering for deterministic testing, ensuring that tests are predictable and reliable. 

eslint.config.js

@@ -37,6 +37,7 @@ export default [
       // TS handles undefined types, turn off for TS files
       'no-undef': 'off',
       '@typescript-eslint/ban-ts-comment': 'off',
+      '@typescript-eslint/no-explicit-any': 'error',
     },
   },
   {

examples/src/components/visual-viewport/VisualViewportExample.test.tsx

@@ -0,0 +1,174 @@
+import { render, act, screen } from '@testing-library/react';
+import { mockVisualViewport, configMocks } from '../../../../dist';
+import VisualViewportExample from './VisualViewportExample';
+
+configMocks({ act });
+
+describe('VisualViewportExample', () => {
+  it('should display viewport information when VisualViewport API is available', () => {
+    const visualViewport = mockVisualViewport({
+      width: 375,
+      height: 667,
+      scale: 1,
+      offsetLeft: 0,
+      offsetTop: 0,
+      pageLeft: 0,
+      pageTop: 0,
+    });
+
+    render(<VisualViewportExample />);
+
+    expect(screen.getByText('VisualViewport API')).toBeInTheDocument();
+    expect(screen.getByText('Width: 375px')).toBeInTheDocument();
+    expect(screen.getByText('Height: 667px')).toBeInTheDocument();
+    expect(screen.getByText('Scale: 1')).toBeInTheDocument();
+
+    visualViewport.cleanup();
+  });
+
+  it('should update viewport information when properties change', () => {
+    const visualViewport = mockVisualViewport({
+      width: 375,
+      height: 667,
+      scale: 1,
+      offsetLeft: 0,
+      offsetTop: 0,
+      pageLeft: 0,
+      pageTop: 0,
+    });
+
+    render(<VisualViewportExample />);
+
+    expect(screen.getByText('Width: 375px')).toBeInTheDocument();
+    expect(screen.getByText('Scale: 1')).toBeInTheDocument();
+
+    act(() => {
+      visualViewport.set({
+        width: 500,
+        scale: 1.5,
+        offsetLeft: 10,
+        offsetTop: 20,
+      });
+    });
+
+    expect(screen.getByText('Width: 500px')).toBeInTheDocument();
+    expect(screen.getByText('Scale: 1.5')).toBeInTheDocument();
+    expect(screen.getByText('Offset Left: 10px')).toBeInTheDocument();
+    expect(screen.getByText('Offset Top: 20px')).toBeInTheDocument();
+
+    visualViewport.cleanup();
+  });
+
+  it('should increment resize counter when resize event is triggered', () => {
+    const visualViewport = mockVisualViewport({
+      width: 375,
+      height: 667,
+      scale: 1,
+      offsetLeft: 0,
+      offsetTop: 0,
+      pageLeft: 0,
+      pageTop: 0,
+    });
+
+    render(<VisualViewportExample />);
+
+    expect(screen.getByText('Resize Events: 0')).toBeInTheDocument();
+
+    act(() => {
+      visualViewport.triggerResize();
+    });
+
+    expect(screen.getByText('Resize Events: 1')).toBeInTheDocument();
+
+    act(() => {
+      visualViewport.triggerResize();
+    });
+
+    expect(screen.getByText('Resize Events: 2')).toBeInTheDocument();
+
+    visualViewport.cleanup();
+  });
+
+  it('should increment scroll counter when scroll event is triggered', () => {
+    const visualViewport = mockVisualViewport({
+      width: 375,
+      height: 667,
+      scale: 1,
+      offsetLeft: 0,
+      offsetTop: 0,
+      pageLeft: 0,
+      pageTop: 0,
+    });
+
+    render(<VisualViewportExample />);
+
+    expect(screen.getByText('Scroll Events: 0')).toBeInTheDocument();
+
+    act(() => {
+      visualViewport.triggerScroll();
+    });
+
+    expect(screen.getByText('Scroll Events: 1')).toBeInTheDocument();
+
+    act(() => {
+      visualViewport.triggerScroll();
+    });
+
+    expect(screen.getByText('Scroll Events: 2')).toBeInTheDocument();
+
+    visualViewport.cleanup();
+  });
+
+  it('should update viewport info when resize event is triggered', () => {
+    const visualViewport = mockVisualViewport({
+      width: 375,
+      height: 667,
+      scale: 1,
+      offsetLeft: 0,
+      offsetTop: 0,
+      pageLeft: 0,
+      pageTop: 0,
+    });
+
+    render(<VisualViewportExample />);
+
+    expect(screen.getByText('Width: 375px')).toBeInTheDocument();
+
+    act(() => {
+      visualViewport.set({ width: 500, height: 800 });
+      visualViewport.triggerResize();
+    });
+
+    expect(screen.getByText('Width: 500px')).toBeInTheDocument();
+    expect(screen.getByText('Height: 800px')).toBeInTheDocument();
+
+    visualViewport.cleanup();
+  });
+
+  it('should update viewport info when scroll event is triggered', () => {
+    const visualViewport = mockVisualViewport({
+      width: 375,
+      height: 667,
+      scale: 1,
+      offsetLeft: 0,
+      offsetTop: 0,
+      pageLeft: 0,
+      pageTop: 0,
+    });
+
+    render(<VisualViewportExample />);
+
+    expect(screen.getByText('Page Left: 0px')).toBeInTheDocument();
+    expect(screen.getByText('Page Top: 0px')).toBeInTheDocument();
+
+    act(() => {
+      visualViewport.set({ pageLeft: 100, pageTop: 200 });
+      visualViewport.triggerScroll();
+    });
+
+    expect(screen.getByText('Page Left: 100px')).toBeInTheDocument();
+    expect(screen.getByText('Page Top: 200px')).toBeInTheDocument();
+
+    visualViewport.cleanup();
+  });
+});