js-cloudimage-before-after 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Scaleflex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,305 @@
+<p align="center">
+  <img src="https://scaleflex.cloudimg.io/v7/plugins/js-cloudimage-360-view/logo_scaleflex_on_white_bg.jpg?vh=91b12d&w=700" alt="Scaleflex" width="350">
+</p>
+
+<h1 align="center">js-cloudimage-before-after</h1>
+
+<p align="center">
+  Interactive before/after image comparison slider with zoom, labels, and accessibility. Zero dependencies.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/js-cloudimage-before-after"><img src="https://img.shields.io/npm/v/js-cloudimage-before-after.svg?style=flat-square" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/js-cloudimage-before-after"><img src="https://img.shields.io/npm/dm/js-cloudimage-before-after.svg?style=flat-square" alt="npm downloads"></a>
+  <a href="https://github.com/scaleflex/js-cloudimage-before-after/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/js-cloudimage-before-after.svg?style=flat-square" alt="license"></a>
+  <a href="https://bundlephobia.com/package/js-cloudimage-before-after"><img src="https://img.shields.io/bundlephobia/minzip/js-cloudimage-before-after?style=flat-square" alt="bundle size"></a>
+</p>
+
+<p align="center">
+  <a href="https://scaleflex.github.io/js-cloudimage-before-after/">Live Demo</a> |
+  <a href="https://codesandbox.io/p/devbox/github/scaleflex/js-cloudimage-before-after/tree/main/examples/vanilla">Vanilla Sandbox</a> |
+  <a href="https://codesandbox.io/p/devbox/github/scaleflex/js-cloudimage-before-after/tree/main/examples/react">React Sandbox</a>
+</p>
+
+---
+
+## Why js-cloudimage-before-after?
+
+Existing before/after sliders are often rigid, inaccessible, or missing features like zoom and vertical orientation. This library was built to fill the gap:
+
+- **Lightweight** — under 15 KB gzipped with zero runtime dependencies
+- **Accessible by default** — WCAG 2.1 AA compliant out of the box
+- **Framework-agnostic** — works with vanilla JS, React, or any framework
+- **Built-in zoom & pan** — no need for a separate zoom library
+- **Multiple interaction modes** — drag, hover, or click
+- **Optional Cloudimage CDN** — serve optimally-sized images automatically
+
+---
+
+## Features
+
+- **Three interaction modes** — Drag, hover, or click to reveal before/after
+- **Horizontal & vertical** — Slider works in both orientations
+- **Zoom & Pan** — CSS transform-based with mouse wheel, pinch-to-zoom, double-click, drag-to-pan
+- **Handle styles** — Arrows, circle, or minimal line
+- **Labels** — Customizable before/after labels with configurable position
+- **Entrance animation** — Smooth slider animation on first view with configurable duration, delay, and easing
+- **Fullscreen mode** — Built-in fullscreen toggle
+- **WCAG 2.1 AA** — Full keyboard navigation, ARIA attributes, focus management, reduced motion
+- **CSS variable theming** — Light and dark themes, fully customizable
+- **Two init methods** — JavaScript API and HTML data-attributes
+- **React wrapper** — Separate entry point with component, hook, and ref API
+- **TypeScript** — Full type definitions
+- **Cloudimage CDN** — Optional responsive image loading
+- **Lazy loading** — IntersectionObserver-based image lazy loading
+
+## Installation
+
+```bash
+npm install js-cloudimage-before-after
+```
+
+### CDN
+
+```html
+<script src="https://scaleflex.cloudimg.io/v7/plugins/js-cloudimage-before-after/1.0.0/js-cloudimage-before-after.min.js?vh=ad6399&func=proxy"></script>
+```
+
+## Quick Start
+
+### JavaScript API
+
+```js
+import CIBeforeAfter from 'js-cloudimage-before-after';
+
+const viewer = new CIBeforeAfter('#slider', {
+  beforeSrc: 'https://example.com/kitchen-before.jpg',
+  afterSrc: 'https://example.com/kitchen-after.jpg',
+  beforeAlt: 'Kitchen before renovation',
+  afterAlt: 'Kitchen after renovation',
+  zoom: true,
+  labels: { before: 'Before', after: 'After' },
+  theme: 'light',
+  handleStyle: 'arrows',
+  animate: { duration: 800 },
+  onSlide(position) {
+    console.log('Position:', position);
+  },
+});
+```
+
+### HTML Data-Attributes
+
+```html
+<div
+  data-ci-before-after-before-src="https://example.com/before.jpg"
+  data-ci-before-after-after-src="https://example.com/after.jpg"
+  data-ci-before-after-before-alt="Before renovation"
+  data-ci-before-after-after-alt="After renovation"
+  data-ci-before-after-zoom="true"
+  data-ci-before-after-theme="light"
+  data-ci-before-after-handle-style="arrows"
+  data-ci-before-after-label-before="Before"
+  data-ci-before-after-label-after="After"
+></div>
+
+<script>CIBeforeAfter.autoInit();</script>
+```
+
+## API Reference
+
+### Constructor
+
+```ts
+new CIBeforeAfter(element: HTMLElement | string, config: CIBeforeAfterConfig)
+```
+
+### Config
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `beforeSrc` | `string` | — | Before image URL (required) |
+| `afterSrc` | `string` | — | After image URL (required) |
+| `beforeAlt` | `string` | `'Before'` | Before image alt text |
+| `afterAlt` | `string` | `'After'` | After image alt text |
+| `mode` | `'drag' \| 'hover' \| 'click'` | `'drag'` | Interaction mode |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Slider direction |
+| `initialPosition` | `number` | `50` | Starting position (0–100) |
+| `handleStyle` | `'arrows' \| 'circle' \| 'line'` | `'arrows'` | Handle visual style |
+| `labels` | `boolean \| { before?: string; after?: string }` | `true` | Show labels or custom text |
+| `labelPosition` | `'top' \| 'bottom'` | `'top'` | Label placement |
+| `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
+| `zoom` | `boolean` | `false` | Enable zoom & pan |
+| `zoomMax` | `number` | `4` | Maximum zoom level |
+| `zoomMin` | `number` | `1` | Minimum zoom level |
+| `zoomControls` | `boolean` | `true` | Show zoom control buttons |
+| `zoomControlsPosition` | `string` | `'bottom-right'` | Zoom controls position (`top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`) |
+| `scrollHint` | `boolean` | `true` | Show scroll hint when zoomed |
+| `animate` | `boolean \| AnimateConfig` | `false` | Entrance animation |
+| `animateOnce` | `boolean` | `true` | Animate only on first view |
+| `fullscreenButton` | `boolean` | `true` | Show fullscreen button |
+| `lazyLoad` | `boolean` | `true` | Lazy load images |
+| `keyboardStep` | `number` | `1` | Arrow key step (%) |
+| `keyboardLargeStep` | `number` | `10` | Shift+Arrow step (%) |
+| `onSlide` | `(position: number) => void` | — | Position change callback |
+| `onZoom` | `(level: number) => void` | — | Zoom change callback |
+| `onFullscreenChange` | `(isFullscreen: boolean) => void` | — | Fullscreen callback |
+| `onReady` | `() => void` | — | Ready callback |
+| `cloudimage` | `CloudimageConfig` | — | Cloudimage CDN config |
+
+### AnimateConfig
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `duration` | `number` | `800` | Duration in ms |
+| `delay` | `number` | `0` | Delay before start in ms |
+| `easing` | `string` | `'ease-out'` | CSS easing function |
+
+### Instance Methods
+
+```ts
+instance.setPosition(percent: number): void     // Set slider position (0–100)
+instance.getPosition(): number                   // Get current position
+instance.setZoom(level: number): void            // Set zoom level
+instance.getZoom(): number                       // Get current zoom level
+instance.resetZoom(): void                       // Reset zoom to 1×
+instance.enterFullscreen(): void                 // Enter fullscreen
+instance.exitFullscreen(): void                  // Exit fullscreen
+instance.isFullscreen(): boolean                 // Check fullscreen state
+instance.update(config: Partial<Config>): void   // Update config
+instance.destroy(): void                         // Destroy instance
+instance.getElements(): Elements                 // Get DOM elements
+```
+
+### Static Methods
+
+```ts
+CIBeforeAfter.autoInit(root?: HTMLElement): CIBeforeAfterInstance[]
+```
+
+## React Usage
+
+```tsx
+import { CIBeforeAfterViewer, useCIBeforeAfter } from 'js-cloudimage-before-after/react';
+
+// Component
+function ImageComparison() {
+  return (
+    <CIBeforeAfterViewer
+      beforeSrc="/kitchen-before.jpg"
+      afterSrc="/kitchen-after.jpg"
+      beforeAlt="Kitchen before renovation"
+      afterAlt="Kitchen after renovation"
+      zoom
+      labels={{ before: 'Before', after: 'After' }}
+      handleStyle="arrows"
+      animate={{ duration: 800 }}
+      onSlide={(pos) => console.log('Position:', pos)}
+    />
+  );
+}
+
+// Hook
+function ImageComparison() {
+  const { containerRef, instance } = useCIBeforeAfter({
+    beforeSrc: '/kitchen-before.jpg',
+    afterSrc: '/kitchen-after.jpg',
+    zoom: true,
+  });
+
+  return (
+    <>
+      <div ref={containerRef} />
+      <button onClick={() => instance.current?.setZoom(2)}>Zoom 2×</button>
+    </>
+  );
+}
+
+// Ref API
+function ImageComparison() {
+  const ref = useRef<CIBeforeAfterViewerRef>(null);
+  return (
+    <>
+      <CIBeforeAfterViewer
+        ref={ref}
+        beforeSrc="/kitchen-before.jpg"
+        afterSrc="/kitchen-after.jpg"
+        zoom
+      />
+      <button onClick={() => ref.current?.setPosition(75)}>Show 75%</button>
+    </>
+  );
+}
+```
+
+## Theming
+
+All visuals are customizable via CSS variables:
+
+```css
+.my-viewer {
+  --ci-before-after-border-radius: 12px;
+  --ci-before-after-handle-color: #0058a3;
+  --ci-before-after-handle-size: 44px;
+  --ci-before-after-handle-border: 2px solid white;
+  --ci-before-after-label-bg: rgba(0, 0, 0, 0.6);
+  --ci-before-after-label-color: #fff;
+  --ci-before-after-label-radius: 4px;
+}
+```
+
+Set `theme: 'dark'` for the built-in dark theme.
+
+## Accessibility
+
+- Slider handle is a focusable element with `role="slider"` and `aria-valuenow`
+- `Arrow keys` move the slider position
+- `Shift + Arrow` moves in larger steps
+- `Home` / `End` jump to 0% / 100%
+- `+` / `-` / `0` control zoom
+- `Escape` exits fullscreen
+- `prefers-reduced-motion` disables animations
+- Before/after images have configurable alt text
+
+## Cloudimage Integration
+
+```js
+new CIBeforeAfter('#el', {
+  beforeSrc: 'https://example.com/before.jpg',
+  afterSrc: 'https://example.com/after.jpg',
+  cloudimage: {
+    token: 'demo',
+    limitFactor: 100,
+    params: 'q=80',
+  },
+});
+```
+
+## Browser Support
+
+| Browser | Version |
+|---------|---------|
+| Chrome  | 80+     |
+| Firefox | 80+     |
+| Safari  | 14+     |
+| Edge    | 80+     |
+
+## License
+
+[MIT](./LICENSE)
+
+---
+
+## Support
+
+If this library helped your project, consider buying me a coffee!
+
+<a href="https://buymeacoffee.com/dzmitry.stramavus">
+  <img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee">
+</a>
+
+---
+
+<p align="center">
+  Made with care by the <a href="https://www.scaleflex.com">Scaleflex</a> team
+</p>

package/dist/a11y/aria.d.ts

@@ -0,0 +1,4 @@
+import type { Orientation } from '../core/types';
+export declare function updateAriaValue(handle: HTMLElement, position: number): void;
+export declare function updateAriaOrientation(handle: HTMLElement, orientation: Orientation): void;
+export declare function setContainerAria(container: HTMLElement): void;

package/dist/a11y/keyboard.d.ts

@@ -0,0 +1,22 @@
+import type { Orientation } from '../core/types';
+export interface KeyboardCallbacks {
+    onPositionChange: (position: number) => void;
+    getPosition: () => number;
+    onZoomIn?: () => void;
+    onZoomOut?: () => void;
+    onZoomReset?: () => void;
+}
+export declare class KeyboardHandler {
+    private handle;
+    private orientation;
+    private step;
+    private largeStep;
+    private zoomEnabled;
+    private callbacks;
+    private events;
+    constructor(handle: HTMLElement, orientation: Orientation, step: number, largeStep: number, zoomEnabled: boolean, callbacks: KeyboardCallbacks);
+    private bind;
+    private handleKeyDown;
+    updateConfig(orientation: Orientation, step: number, largeStep: number, zoomEnabled: boolean): void;
+    destroy(): void;
+}

package/dist/animation/entrance.d.ts

@@ -0,0 +1,18 @@
+export declare class EntranceAnimation {
+    private container;
+    private duration;
+    private delay;
+    private easing;
+    private animateOnce;
+    private onAnimate;
+    private observer;
+    private hasPlayed;
+    private isAnimating;
+    private delayTimer;
+    private durationTimer;
+    constructor(container: HTMLElement, duration: number, delay: number, easing: string, animateOnce: boolean, onAnimate: (skipTransition: boolean) => void);
+    private observe;
+    private play;
+    getHasPlayed(): boolean;
+    destroy(): void;
+}

package/dist/core/ci-before-after.d.ts

@@ -0,0 +1,64 @@
+import type { CIBeforeAfterConfig, CIBeforeAfterInstance } from './types';
+export declare class CIBeforeAfterCore implements CIBeforeAfterInstance {
+    private config;
+    private userConfig;
+    private state;
+    private elements;
+    private events;
+    private imageEvents;
+    private sliderGestures;
+    private zoomPan;
+    private zoomGestures;
+    private scrollHint;
+    private fullscreenManager;
+    private entranceAnimation;
+    private keyboardHandler;
+    private resizeObserver;
+    private zoomControlsEl;
+    private zoomControlsEvents;
+    private lazyLoadObserver;
+    private resizeDebounceTimer;
+    private animTransitionTimer;
+    private suppressCallbacks;
+    constructor(target: HTMLElement | string, userConfig: CIBeforeAfterConfig);
+    getElements(): {
+        container: HTMLElement;
+        viewport: HTMLElement;
+        beforeImage: HTMLImageElement;
+        afterImage: HTMLImageElement;
+        handle: HTMLElement;
+    };
+    setPosition(percent: number): void;
+    getPosition(): number;
+    setZoom(level: number): void;
+    getZoom(): number;
+    resetZoom(): void;
+    enterFullscreen(): void;
+    exitFullscreen(): void;
+    isFullscreen(): boolean;
+    update(newConfig: Partial<CIBeforeAfterConfig>): void;
+    destroy(): void;
+    private buildDOM;
+    private initModules;
+    private initZoom;
+    private applyZoomPositionClasses;
+    private initEntranceAnimation;
+    private loadImages;
+    /**
+     * Register load/error handlers for images. Cleans up previous handlers first.
+     * When only one image changed, the unchanged image is treated as already loaded.
+     */
+    private registerImageLoadHandlers;
+    private onImagesReady;
+    private getClipZoomInfo;
+    private syncClip;
+    private updatePosition;
+    private onDragStart;
+    private onDragEnd;
+    private resolveImageSrc;
+    private rebuildHandle;
+    private rebuildLabels;
+    private rebuildZoom;
+    private rebuildFullscreen;
+    private initResizeObserver;
+}

package/dist/core/config.d.ts

@@ -0,0 +1,3 @@
+import type { CIBeforeAfterConfig, ResolvedConfig } from './types';
+export declare function resolveConfig(config: CIBeforeAfterConfig): ResolvedConfig;
+export declare function parseDataAttributes(el: HTMLElement): CIBeforeAfterConfig;

package/dist/core/types.d.ts

@@ -0,0 +1,127 @@
+export type InteractionMode = 'drag' | 'hover' | 'click';
+export type Orientation = 'horizontal' | 'vertical';
+export type HandleStyle = 'arrows' | 'circle' | 'line';
+export type Theme = 'light' | 'dark';
+export type LabelPosition = 'top' | 'bottom';
+export type ZoomControlsPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+export interface AnimateConfig {
+    duration?: number;
+    delay?: number;
+    easing?: string;
+}
+export interface CloudimageConfig {
+    token: string;
+    apiVersion?: string;
+    domain?: string;
+    limitFactor?: number;
+    params?: string;
+    devicePixelRatioList?: number[];
+}
+export interface CIBeforeAfterConfig {
+    beforeSrc: string;
+    afterSrc: string;
+    beforeAlt?: string;
+    afterAlt?: string;
+    mode?: InteractionMode;
+    orientation?: Orientation;
+    initialPosition?: number;
+    zoom?: boolean;
+    zoomMax?: number;
+    zoomMin?: number;
+    theme?: Theme;
+    handleStyle?: HandleStyle;
+    labels?: boolean | {
+        before?: string;
+        after?: string;
+    };
+    labelPosition?: LabelPosition;
+    animate?: boolean | AnimateConfig;
+    animateOnce?: boolean;
+    fullscreenButton?: boolean;
+    lazyLoad?: boolean;
+    zoomControls?: boolean;
+    zoomControlsPosition?: ZoomControlsPosition;
+    scrollHint?: boolean;
+    keyboardStep?: number;
+    keyboardLargeStep?: number;
+    onSlide?: (position: number) => void;
+    onZoom?: (level: number) => void;
+    onFullscreenChange?: (isFullscreen: boolean) => void;
+    onReady?: () => void;
+    cloudimage?: CloudimageConfig;
+}
+export interface ResolvedConfig {
+    beforeSrc: string;
+    afterSrc: string;
+    beforeAlt: string;
+    afterAlt: string;
+    mode: InteractionMode;
+    orientation: Orientation;
+    initialPosition: number;
+    zoom: boolean;
+    zoomMax: number;
+    zoomMin: number;
+    theme: Theme;
+    handleStyle: HandleStyle;
+    labelsEnabled: boolean;
+    labelBefore: string;
+    labelAfter: string;
+    labelPosition: LabelPosition;
+    animateEnabled: boolean;
+    animateDuration: number;
+    animateDelay: number;
+    animateEasing: string;
+    animateOnce: boolean;
+    fullscreenButton: boolean;
+    lazyLoad: boolean;
+    zoomControls: boolean;
+    zoomControlsPosition: ZoomControlsPosition;
+    scrollHint: boolean;
+    keyboardStep: number;
+    keyboardLargeStep: number;
+    onSlide?: (position: number) => void;
+    onZoom?: (level: number) => void;
+    onFullscreenChange?: (isFullscreen: boolean) => void;
+    onReady?: () => void;
+    cloudimage?: CloudimageConfig;
+}
+export interface SliderState {
+    position: number;
+    isDragging: boolean;
+    zoomLevel: number;
+    panX: number;
+    panY: number;
+    isReady: boolean;
+    isFullscreen: boolean;
+}
+export interface CIBeforeAfterElements {
+    container: HTMLElement;
+    viewport: HTMLElement;
+    wrapper: HTMLElement;
+    beforeImage: HTMLImageElement;
+    afterImage: HTMLImageElement;
+    clip: HTMLElement;
+    handle: HTMLElement;
+    handleGrip: HTMLElement;
+    labelBefore: HTMLElement | null;
+    labelAfter: HTMLElement | null;
+}
+export interface CIBeforeAfterInstance {
+    getElements(): {
+        container: HTMLElement;
+        viewport: HTMLElement;
+        beforeImage: HTMLImageElement;
+        afterImage: HTMLImageElement;
+        handle: HTMLElement;
+    };
+    setPosition(percent: number): void;
+    getPosition(): number;
+    setZoom(level: number): void;
+    getZoom(): number;
+    resetZoom(): void;
+    enterFullscreen(): void;
+    exitFullscreen(): void;
+    isFullscreen(): boolean;
+    update(config: Partial<CIBeforeAfterConfig>): void;
+    destroy(): void;
+}

package/dist/fullscreen/fullscreen.d.ts

@@ -0,0 +1,16 @@
+export declare class FullscreenManager {
+    private container;
+    private onFullscreenChange?;
+    private button;
+    private events;
+    private isActive;
+    constructor(container: HTMLElement, onFullscreenChange?: ((isFullscreen: boolean) => void) | undefined);
+    private createButton;
+    private bindEvents;
+    private handleChange;
+    enter(): Promise<void>;
+    exit(): Promise<void>;
+    toggle(): Promise<void>;
+    getIsFullscreen(): boolean;
+    destroy(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { CIBeforeAfterCore } from './core/ci-before-after';
+import type { CIBeforeAfterConfig, CIBeforeAfterInstance } from './core/types';
+export type { CIBeforeAfterConfig, CIBeforeAfterInstance, InteractionMode, Orientation, HandleStyle, Theme, LabelPosition, ZoomControlsPosition, AnimateConfig, CloudimageConfig, SliderState, } from './core/types';
+export { CIBeforeAfterCore };
+declare class CIBeforeAfter extends CIBeforeAfterCore {
+    static autoInit(root?: HTMLElement): CIBeforeAfterInstance[];
+    constructor(target: HTMLElement | string, config: CIBeforeAfterConfig);
+}
+export default CIBeforeAfter;
+export { CIBeforeAfter };