ngx-pinch-zoom/CONTRIBUTING.md

Contributing to ngx-pinch-zoom

For New Maintainers

This document provides comprehensive information for maintaining and developing this Angular library.

Project Overview

ngx-pinch-zoom is an Angular library providing touch-enabled image zoom and pan functionality. The library is built with Angular 20+ and uses the modern signals API for reactivity.

Key Features

• Touch and mouse support for pinch-to-zoom
• Wheel zoom support
• Double-tap to zoom
• Pan and drag functionality
• Configurable zoom limits and behaviors
• Standalone component (no NgModule required)
• Built with Angular signals for optimal performance

Architecture

Project Structure

ngx-pinch-zoom/
├── projects/ngx-pinch-zoom/          # Library source code
│   └── src/lib/
│       ├── pinch-zoom.component.ts    # Main component with signals API
│       ├── ivypinch.ts                # Core zoom logic
│       ├── touches.ts                 # Touch/mouse event handling
│       ├── interfaces.ts              # TypeScript interfaces
│       └── properties.ts              # Default configuration
├── src/                               # Demo application
├── angular.json                       # Angular CLI configuration
├── package.json                       # Dependencies and scripts
└── tsconfig.json                      # TypeScript configuration

Core Components

1. PinchZoomComponent (pinch-zoom.component.ts)

   • Main Angular component
   • Uses signals for all inputs and outputs
   • Implements modern Angular patterns (inject, computed, effect)
   • Standalone component

2. IvyPinch (ivypinch.ts)

   • Core zoom/pan logic
   • Handles transformations and calculations
   • No Angular dependencies (plain TypeScript class)

3. Touches (touches.ts)

   • Event handling for touch and mouse interactions
   • Gesture detection (pinch, pan, tap, double-tap)
   • Cross-browser compatibility

Development Setup

Prerequisites

• Node.js 18.19.1+, 20.11.1+, or 22.0.0+
• npm 9.0.0+ or 10.0.0+

Installation

# Install dependencies
npm install

# Build the library
npm run build-lib

# Start demo app
npm start

Available Scripts

npm run build-lib    # Build the library
npm run build        # Build the demo app
npm start            # Serve the demo app
npm run format       # Format code with Prettier
npm run format:check # Check code formatting

Building the Library

The library is built using Angular's ng-packagr:

npm run build-lib

Output is generated in dist/ngx-pinch-zoom/ with:

• ESM bundles
• TypeScript declaration files
• package.json for npm publishing
• README.md

Angular Signals Migration

This library has been migrated to use Angular signals (Angular 20+). Here's what changed:

Before (Traditional Approach)

@Input() disabled: boolean;
@Output() zoomChanged = new EventEmitter<number>();

get scale(): number {
  return this.pinchZoom.scale;
}

After (Signals Approach)

disabled = input<boolean>(false);
zoomChanged = output<number>();

scale = computed<number>(() => {
    return this.currentScale();
});

Key Benefits

1. Better Performance: Signals provide fine-grained reactivity
2. Simpler State Management: No need for manual change detection
3. Type Safety: Improved TypeScript inference
4. Modern Angular: Aligns with Angular's future direction

Making Changes

Code Style

• Use Prettier for formatting (config in .prettierrc)
• Follow TypeScript strict mode rules
• Use meaningful variable names
• Add JSDoc comments for public APIs

TypeScript Configuration

The project uses strict TypeScript settings:

{
    "strict": true,
    "strictNullChecks": true,
    "strictInjectionParameters": true,
    "strictInputAccessModifiers": true,
    "strictTemplates": true
}

Adding New Features

1. Update the component (pinch-zoom.component.ts):

   • Add input signals for configuration
   • Add computed signals for derived state
   • Update the component template if needed

2. Update core logic (ivypinch.ts):

   • Add properties to the Properties interface
   • Implement the functionality
   • Test calculations thoroughly

3. Document the feature:

   • Update README.md with the new property
   • Add usage examples
   • Document default values

Testing Changes

Currently, the test infrastructure has been simplified. To test changes:

1. Build the library: npm run build-lib
2. Run the demo app: npm start
3. Manually test in the browser
4. Test on both desktop (mouse) and touch devices

Future improvement: Add Jest or Vitest for unit testing.

Common Tasks

Updating Dependencies

# Update Angular to latest version
npx ng update @angular/core @angular/cli

# Update other dependencies
npm update

Publishing to npm

1. Update version in package.json
2. Update version in projects/ngx-pinch-zoom/package.json
3. Build the library: npm run build-lib
4. Publish: cd dist/ngx-pinch-zoom && npm publish

Debugging

1. Component Issues:

   • Check signal reactivity with Angular DevTools
   • Use effect(() => console.log(signalValue()))

2. Touch/Mouse Issues:

   • Add console.logs in touches.ts event handlers
   • Check browser dev tools for event listeners

3. Transform Issues:

   • Inspect ivypinch.ts transformElement method
   • Check CSS transform values in browser inspector

Browser Compatibility

The library supports all modern browsers:

• Chrome/Edge (latest 2 versions)
• Firefox (latest 2 versions)
• Safari (latest 2 versions)
• Mobile browsers (iOS Safari, Chrome Mobile)

Performance Considerations

1. Signals: Use computed signals for derived state
2. Event Listeners: Properly clean up in ngOnDestroy
3. Transform: Use CSS transforms (hardware accelerated)
4. Change Detection: OnPush strategy compatible (signals don't require manual CD)

Troubleshooting

Build Failures

TypeScript errors: Ensure strict mode compliance

# Check TypeScript version
npx tsc --version  # Should be ~5.8.0

Dependency conflicts: Clear cache and reinstall

rm -rf node_modules package-lock.json
npm install

Runtime Issues

Signals not updating: Check if effects are running Touch events not working: Verify viewport meta tag in host app Zoom calculations off: Check element positioning and getBoundingClientRect

Getting Help

• Create an issue on GitHub
• Check existing issues for similar problems
• Review the README.md for usage examples

Code of Conduct

• Be respectful and constructive
• Test your changes before submitting
• Document new features
• Keep the codebase clean and maintainable