@stacksjs/stx/dist/media/image/editing.d.ts

A performant UI Framework. Powered by Bun.

import type { ImageCrop, ImageFit, ImageFormat, ImageParams } from '../types';
/**
 * Build an image URL with transformation parameters
 *
 * @example
 * ```typescript
 * const url = buildImageUrl('/images/hero.jpg', {
 *   w: 800,
 *   h: 600,
 *   fit: 'crop',
 *   crop: 'center',
 *   q: 85,
 *   fm: 'webp'
 * })
 * // Result: "/images/hero.jpg?w=800&h=600&fit=crop&crop=center&q=85&fm=webp"
 * ```
 */
export declare function buildImageUrl(src: string, params?: ImageParams): string;
/**
 * Parse image parameters from a URL
 */
export declare function parseImageUrl(url: string): { src: string; params: ImageParams };
/**
 * Merge image parameters, with later values overriding earlier ones
 */
export declare function mergeParams(...paramSets: (ImageParams | undefined)[]): ImageParams;
/**
 * Resize an image to specific dimensions
 *
 * @example
 * ```typescript
 * const url = resize('/images/photo.jpg', 800, 600)
 * // Result: "/images/photo.jpg?w=800&h=600"
 * ```
 */
export declare function resize(src: string, width: number, height?: number, fit?: ImageFit): string;
/**
 * Crop an image to specific dimensions
 *
 * @example
 * ```typescript
 * const url = crop('/images/photo.jpg', 800, 600, 'center')
 * // Result: "/images/photo.jpg?w=800&h=600&fit=crop&crop=center"
 * ```
 */
export declare function crop(src: string, width: number, height: number, position?: ImageCrop): string;
/**
 * Create a square thumbnail
 *
 * @example
 * ```typescript
 * const url = thumbnail('/images/photo.jpg', 200)
 * // Result: "/images/photo.jpg?w=200&h=200&fit=crop&crop=center"
 * ```
 */
export declare function thumbnail(src: string, size: number, cropPosition?: ImageCrop): string;
/**
 * Scale image to fit within dimensions while maintaining aspect ratio
 */
export declare function contain(src: string, maxWidth: number, maxHeight?: number): string;
/**
 * Scale and crop image to cover dimensions
 */
export declare function cover(src: string, width: number, height: number): string;
/**
 * Apply blur effect
 *
 * @param radius - Blur radius (0-2000)
 */
export declare function blur(src: string, radius: number): string;
/**
 * Apply sharpening
 *
 * @param amount - Sharpen amount (0-100)
 */
export declare function sharpen(src: string, amount: number): string;
/**
 * Convert to grayscale
 */
export declare function grayscale(src: string): string;
/**
 * Apply sepia tone
 *
 * @param amount - Sepia intensity (0-100)
 */
export declare function sepia(src: string, amount?: number): string;
/**
 * Invert colors
 */
export declare function invert(src: string): string;
/**
 * Adjust brightness
 *
 * @param amount - Brightness adjustment (-100 to 100)
 */
export declare function brightness(src: string, amount: number): string;
/**
 * Adjust contrast
 *
 * @param amount - Contrast adjustment (-100 to 100)
 */
export declare function contrast(src: string, amount: number): string;
/**
 * Adjust saturation
 *
 * @param amount - Saturation adjustment (-100 to 100)
 */
export declare function saturation(src: string, amount: number): string;
/**
 * Rotate image
 *
 * @param degrees - Rotation in degrees (0-359)
 */
export declare function rotate(src: string, degrees: number): string;
/**
 * Flip image horizontally
 */
export declare function flipHorizontal(src: string): string;
/**
 * Flip image vertically
 */
export declare function flipVertical(src: string): string;
/**
 * Convert to specific format
 */
export declare function format(src: string, fmt: ImageFormat, quality?: number): string;
/**
 * Set quality
 */
export declare function quality(src: string, q: number): string;
/**
 * Apply auto enhancements
 *
 * @param enhancements - Array of enhancements: 'format', 'compress', 'enhance'
 */
export declare function auto(src: string, enhancements?: string[]): string;
/**
 * Add a watermark image
 */
export declare function watermark(src: string, markUrl: string, options?: {
    x?: number
    y?: number
    alpha?: number
    scale?: number
    align?: string
  }): string;
/**
 * Apply a preset to an image URL
 */
export declare function applyPreset(src: string, preset: keyof typeof PRESETS, additionalParams?: ImageParams): string;
/**
 * Generate srcset-compatible URLs for multiple widths
 */
export declare function srcsetUrls(src: string, widths: number[], params?: ImageParams): string[];
/**
 * Generate DPR-aware URLs for a fixed width
 */
export declare function dprUrls(src: string, width: number, dprValues?: number[], params?: ImageParams): string[];
/**
 * Validate image parameters
 */
export declare function validateParams(params: ImageParams): { valid: boolean; errors: string[] };
/**
 * Sanitize image parameters (clamp to valid ranges)
 */
export declare function sanitizeParams(params: ImageParams): ImageParams;
/**
 * Common image transformation presets
 */
export declare const PRESETS: {
  /** Optimized for web display */
  web: {
  fm: unknown;
  q: 80;
  auto: readonly ['format', 'compress']
};
  /** High quality for print/download */
  highQuality: {
  q: 95
};
  /** Optimized for thumbnails */
  thumb: {
  w: 150;
  h: 150;
  fit: unknown;
  crop: unknown
};
  /** Avatar image */
  avatar: {
  w: 200;
  h: 200;
  fit: unknown;
  crop: unknown
};
  /** Social media share image */
  social: {
  w: 1200;
  h: 630;
  fit: unknown
};
  /** Small preview */
  preview: {
  w: 400;
  q: 70
};
  /** Blur placeholder */
  placeholder: {
  w: 20;
  blur: 200;
  q: 20
}
};