karma-viewport

import { range, Viewport, ViewportConfiguration } from "karma-viewport";

// karma.conf.js
module.exports = function(config) {
  config.set({
    frameworks: ["viewport"],
    
    // Optional viewport configuration
    viewport: {
      context: "#context",  // iframe selector (default)
      breakpoints: [
        {
          name: "mobile",
          size: { width: 320, height: 480 }
        },
        {
          name: "tablet", 
          size: { width: 768, height: 1024 }
        },
        {
          name: "desktop",
          size: { width: 1440, height: 900 }
        }
      ]
    }
  });
};

/// <reference types="karma-viewport" />

// Test file - viewport is available globally
describe("responsive layout", () => {
  
  beforeEach(() => {
    viewport.reset(); // Reset to default size
  });
  
  it("should work on mobile", () => {
    viewport.set(320, 480); // Set specific dimensions
    // Test mobile layout...
  });
  
  it("should work on tablet", () => {
    viewport.set("tablet"); // Use named breakpoint
    // Test tablet layout...
  });
  
  it("should test all breakpoints", () => {
    viewport.each(name => {
      // This runs for each configured breakpoint
      console.log(`Testing ${name} viewport`);
      // Test layout for current viewport...
    });
  });
});

/**
 * Set viewport to specific width and optional height
 * @param width - Width in pixels
 * @param height - Optional height in pixels
 */
set(width: number, height?: number): void;

/**
 * Set viewport to named breakpoint
 * @param breakpoint - Name of configured breakpoint
 */
set(breakpoint: string): void;

/**
 * Reset viewport to default size (100% x 100%)
 */
reset(): void;

/**
 * Load and embed document into viewport
 * @param url - URL of document to load  
 * @param cb - Optional callback function called after load completes
 * @returns Promise resolving with no result when load completes
 */
load(url: string, cb?: () => void): Promise<void>;

/**
 * Change viewport scroll offset
 * @param x - Horizontal offset in pixels
 * @param y - Vertical offset in pixels (default: 0)
 */
offset(x: number, y?: number): void;

/**
 * Execute callback for all configured breakpoints
 * @param cb - Callback function receiving breakpoint name
 * @returns Promise if callback returns Promise, void otherwise
 */
each<T>(cb: ViewportCallback<T>): void | Promise<void>;

/**
 * Execute callback for breakpoints starting from specified breakpoint
 * @param first - First breakpoint name
 * @param cb - Callback function receiving breakpoint name
 * @returns Promise if callback returns Promise, void otherwise
 */
from<T>(first: string, cb: ViewportCallback<T>): void | Promise<void>;

/**
 * Execute callback for breakpoints up to specified breakpoint
 * @param last - Last breakpoint name
 * @param cb - Callback function receiving breakpoint name
 * @returns Promise if callback returns Promise, void otherwise
 */
to<T>(last: string, cb: ViewportCallback<T>): void | Promise<void>;

/**
 * Execute callback for breakpoints between two specified breakpoints (inclusive)
 * @param first - First breakpoint name
 * @param last - Last breakpoint name
 * @param cb - Callback function receiving breakpoint name
 * @returns Promise if callback returns Promise, void otherwise
 */
between<T>(first: string, last: string, cb: ViewportCallback<T>): void | Promise<void>;

// Test all breakpoints
viewport.each(name => {
  console.log(`Testing ${name}`);
  // Test logic here
});

// Test from tablet onwards
viewport.from("tablet", name => {
  // Tests tablet, desktop, etc.
});

// Test up to tablet
viewport.to("tablet", name => {
  // Tests mobile, tablet
});

// Test specific range
viewport.between("tablet", "desktop", name => {
  // Tests tablet, desktop
});

// Async support
viewport.each(async name => {
  await someAsyncTest();
});

interface ViewportConfiguration {
  /** Context element selector (default: "#context") */
  context: string;
  /** Array of named breakpoints */
  breakpoints: ViewportBreakpoint[];
}

interface ViewportBreakpoint {
  /** Breakpoint name */
  name: string;
  /** Viewport dimensions */
  size: {
    width: number;
    height: number;
  };
}

/**
 * Resolve relevant breakpoint range between two breakpoints
 * @param breakpoints - Array of viewport breakpoints
 * @param first - First breakpoint name
 * @param last - Last breakpoint name (defaults to first)
 * @returns Array of breakpoints in the specified range
 * @throws ReferenceError if breakpoint name is invalid
 */
function range(
  breakpoints: ViewportBreakpoint[], 
  first: string, 
  last?: string
): ViewportBreakpoint[];

/**
 * Callback function type for viewport iteration methods
 */
type ViewportCallback<T> = (breakpoint: string) => T;

/**
 * Main Viewport class - available as global 'viewport' instance
 */
class Viewport {
  /** Viewport configuration (read-only) */
  readonly config: Readonly<ViewportConfiguration>;
  /** Target iframe element */
  readonly context: HTMLIFrameElement;
  
  /**
   * Create viewport resizer
   * @param config - Viewport configuration
   * @param parent - Initialization context (window)
   * @throws ReferenceError if context selector doesn't match HTMLIFrameElement
   */
  constructor(config: ViewportConfiguration, parent: Window);
  
  /** Set viewport to specific dimensions */
  set(width: number, height?: number): void;
  /** Set viewport to named breakpoint */
  set(breakpoint: string): void;
  /** Reset viewport to default size */
  reset(): void;
  /** Load and embed document into viewport */
  load(url: string, cb?: () => void): Promise<void>;
  /** Change viewport scroll offset */
  offset(x: number, y?: number): void;
  /** Execute callback for all breakpoints */
  each<T>(cb: ViewportCallback<T>): void | Promise<void>;
  /** Execute callback starting from specified breakpoint */
  from<T>(first: string, cb: ViewportCallback<T>): void | Promise<void>;
  /** Execute callback up to specified breakpoint */
  to<T>(last: string, cb: ViewportCallback<T>): void | Promise<void>;
  /** Execute callback between two specified breakpoints */
  between<T>(first: string, last: string, cb: ViewportCallback<T>): void | Promise<void>;
}

/**
 * Global viewport instance declaration
 */
declare const viewport: Viewport;

/**
 * Common errors thrown by karma-viewport
 */

// Invalid breakpoint name in set(), each(), from(), to(), between() methods
ReferenceError: `Invalid breakpoint: ${inspect(name)}`

// Invalid context selector during initialization
ReferenceError: `No match for selector: ${inspect(config.context)}`

// Invalid viewport width (must be positive number)
TypeError: `Invalid breakpoint width: ${width}`

// Invalid viewport height (must be positive number or undefined)
TypeError: `Invalid breakpoint height: ${height}`

// Invalid viewport configuration object
TypeError: `Invalid viewport configuration: ${viewport}`

// Configuration validation errors (uses jsonschema validation)
TypeError: `Invalid viewport configuration: ${result.errors[0].stack}`

// Karma iframe configuration requirement
Error: "Invalid configuration: client.useIframe must be set to true or a different context selector must be given"