@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
158 lines • 5.68 kB
TypeScript
import type { Breakpoint, ImageFormat, ImageParams, ImageVariant, SrcsetData, SrcsetOptions, } from '../types';
/**
* Generate a width-based srcset string
*
* @example
* ```typescript
* const srcset = generateWidthSrcset('/images/hero.jpg', [320, 640, 1024])
* // Result: "/images/hero.jpg?w=320 320w, /images/hero.jpg?w=640 640w, /images/hero.jpg?w=1024 1024w"
* ```
*/
export declare function generateWidthSrcset(src: string, widths?: number[], params?: ImageParams, format?: ImageFormat): string;
/**
* Generate width-based srcset with automatic width calculation
*
* Uses a tolerance-based approach similar to imgix.js to calculate optimal widths
* between min and max values.
*
* @param src - Image source URL
* @param minWidth - Minimum width (default: 320)
* @param maxWidth - Maximum width (default: 2560)
* @param tolerance - Width tolerance factor (default: 0.08 = 8%)
*/
export declare function generateAutoWidthSrcset(src: string, minWidth?: number, maxWidth?: number, tolerance?: number, params?: ImageParams, format?: ImageFormat): string;
/**
* Calculate optimal widths between min and max using tolerance factor
*
* Similar to imgix.js srcset generation algorithm
*/
export declare function calculateOptimalWidths(minWidth: number, maxWidth: number, tolerance?: number): number[];
/**
* Generate a DPR-based srcset for fixed-width images
*
* @example
* ```typescript
* const srcset = generateDprSrcset('/images/avatar.jpg', 200, [1, 2, 3])
* // Result: "/images/avatar.jpg?w=200 1x, /images/avatar.jpg?w=400 2x, /images/avatar.jpg?w=600 3x"
* ```
*/
export declare function generateDprSrcset(src: string, width: number, dprValues?: number[], params?: ImageParams, format?: ImageFormat): string;
/**
* Generate DPR-based srcset with variable quality
*
* Reduces quality for higher DPR values to maintain reasonable file sizes
* (similar to imgix variable quality feature)
*/
export declare function generateDprSrcsetWithVariableQuality(src: string, width: number, dprValues?: number[], baseQuality?: number, params?: ImageParams, format?: ImageFormat): string;
/**
* Generate a sizes attribute from breakpoint definitions
*
* @example
* ```typescript
* const sizes = generateSizesAttribute({
* '768px': '100vw',
* '1024px': '50vw',
* })
* // Result: "(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 100vw"
* ```
*/
export declare function generateSizesAttribute(breakpoints: Record<string, string>, defaultSize?: string): string;
/**
* Generate sizes from named breakpoints
*/
export declare function generateSizesFromBreakpoints(breakpoints: Breakpoint[], defaultSize?: string): string;
/**
* Build an image URL with transformation parameters
*
* @example
* ```typescript
* const url = buildImageUrl('/images/hero.jpg', { w: 800, h: 600, fit: 'crop', q: 85 })
* // Result: "/images/hero.jpg?w=800&h=600&fit=crop&q=85"
* ```
*/
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 };
/**
* Generate complete srcset data for all formats
*
* @returns Array of srcset data for each format
*/
export declare function generateSrcsetData(options: SrcsetOptions): SrcsetData[];
/**
* Generate a complete <picture> element's source tags
*/
export declare function generateSourceTags(srcsetData: SrcsetData[], sizes?: string): string;
/**
* Get the best variant for a given width from a list of variants
*/
export declare function getBestVariant(variants: ImageVariant[], targetWidth: number): ImageVariant | undefined;
/**
* Get the fallback variant (middle resolution JPEG)
*/
export declare function getFallbackVariant(variants: ImageVariant[], preferFormat?: ImageFormat): ImageVariant | undefined;
/**
* Group variants by format
*/
export declare function groupVariantsByFormat(variants: ImageVariant[]): Map<ImageFormat, ImageVariant[]>;
/**
* Get MIME type for a format
*/
export declare function getMimeType(format: ImageFormat): string;
/**
* Get file extension for a format
*/
export declare function getFormatExtension(format: ImageFormat): string;
/**
* Detect image format from file extension or URL
*/
export declare function detectFormat(src: string): ImageFormat | undefined;
/**
* Default breakpoint widths for responsive images
*/
export declare const DEFAULT_WIDTHS: readonly [320, 480, 640, 768, 1024, 1280, 1536, 1920, 2560];
/**
* Default DPR values for fixed-width images
*/
export declare const DEFAULT_DPR_VALUES: readonly [1, 1.5, 2, 3];
/**
* Default output formats in order of preference
*/
export declare const DEFAULT_FORMATS: ImageFormat[];
/**
* MIME types for each format
*/
export declare const MIME_TYPES: {
avif: 'image/avif';
webp: 'image/webp';
jpeg: 'image/jpeg';
png: 'image/png';
gif: 'image/gif'
};
/**
* File extensions for each format
*/
export declare const FORMAT_EXTENSIONS: {
avif: 'avif';
webp: 'webp';
jpeg: 'jpg';
png: 'png';
gif: 'gif'
};
/**
* Common responsive sizes patterns
*/
export declare const COMMON_SIZES: {
/** Full width on all screens */
fullWidth: '100vw';
/** Half width on desktop, full on mobile */
halfDesktop: '(max-width: 768px) 100vw, 50vw';
/** Third width on desktop, full on mobile */
thirdDesktop: '(max-width: 768px) 100vw, 33.33vw';
/** Quarter width on desktop, half on tablet, full on mobile */
quarterDesktop: '(max-width: 480px) 100vw, (max-width: 768px) 50vw, 25vw';
/** Content width (centered with max-width) */
contentWidth: '(max-width: 768px) 100vw, (max-width: 1200px) 80vw, 960px'
};