@stacksjs/stx 0.2.155 → 0.2.156

package/dist/media/image/component.d.ts

@@ -1,4 +1,23 @@
+/**
+ * STX Media - Image Component
+ *
+ * Render optimized responsive images with srcset, lazy loading,
+ * and blur-up placeholder effects.
+ *
+ * @module media/image/component
+ */
 import type { ImageRenderContext, ImageRenderResult, ImgProps, EnhancedImgProps, TsImagesConfig, ProcessedImageResult, ResponsiveVariantSet } from '../types';
+/**
+ * Extended image render context with ts-images config
+ */
+export interface ExtendedImageRenderContext extends ImageRenderContext {
+    /** ts-images configuration */
+    tsImagesConfig?: TsImagesConfig;
+    /** Processed image result (pre-computed) */
+    processedResult?: ProcessedImageResult;
+    /** Responsive variants (pre-computed) */
+    responsiveVariants?: ResponsiveVariantSet;
+}
 /**
  * Render an optimized <Img> component
  *
@@ -33,12 +52,9 @@ export declare function parseImgComponent(content: string): ImgProps | null;
 /**
  * Process all <Img> components in template content
  */
-export declare function processImgComponents(content: string, context?: ImageRenderContext): Promise<{ html: string; preloadLinks: string[]; styles: string[]; scripts: string[] }>;
-/**
- * Extended image render context with ts-images config
- */
-export declare interface ExtendedImageRenderContext extends ImageRenderContext {
-  tsImagesConfig?: TsImagesConfig
-  processedResult?: ProcessedImageResult
-  responsiveVariants?: ResponsiveVariantSet
-}
+export declare function processImgComponents(content: string, context?: ImageRenderContext): Promise<{
+    html: string;
+    preloadLinks: string[];
+    styles: string[];
+    scripts: string[];
+}>;

package/dist/media/image/directive.d.ts

@@ -1,3 +1,17 @@
+/**
+ * STX Media - Image Directive
+ *
+ * @img directive for declarative responsive image rendering.
+ *
+ * @module media/image/directive
+ *
+ * @example
+ * ```html
+ * @img('/images/hero.jpg', 'Hero image', { sizes: '100vw', placeholder: 'thumbhash' })
+ * @img('/images/photo.jpg', 'Photo')
+ * @img(dynamicSrc, dynamicAlt, { lazy: true })
+ * ```
+ */
 import type { CustomDirective } from '../../types';
 /**
  * Create the @img directive
@@ -6,4 +20,4 @@ export declare function createImgDirective(): CustomDirective;
 /**
  * The @img directive instance
  */
-export declare const imgDirective: unknown;
+export declare const imgDirective: CustomDirective;

package/dist/media/image/placeholder.d.ts

@@ -1,4 +1,20 @@
+/**
+ * STX Media - Placeholder Generation
+ *
+ * Generate low-quality image placeholders (LQIP) for blur-up lazy loading effects.
+ * Supports multiple strategies: blur, thumbhash, blurhash, pixelate, dominant-color.
+ *
+ * @module media/image/placeholder
+ */
 import type { PlaceholderOptions, PlaceholderResult } from '../types';
+/**
+ * Default placeholder options
+ */
+export declare const DEFAULT_PLACEHOLDER_OPTIONS: PlaceholderOptions;
+/**
+ * CSS for blur-up transition
+ */
+export declare const BLUR_UP_CSS: string;
 /**
  * Generate a placeholder for an image using the specified strategy
  *
@@ -67,12 +83,7 @@ export declare function clearPlaceholderCache(): void;
 /**
  * Get cache statistics
  */
-export declare function getPlaceholderCacheStats(): { size: number; keys: string[] };
-/**
- * Default placeholder options
- */
-export declare const DEFAULT_PLACEHOLDER_OPTIONS: PlaceholderOptions;
-/**
- * CSS for blur-up transition
- */
-export declare const BLUR_UP_CSS: unknown;
+export declare function getPlaceholderCacheStats(): {
+    size: number;
+    keys: string[];
+};

package/dist/media/image/processor/cache.d.ts

@@ -1,5 +1,44 @@
-import { type CacheConfig } from '../../shared/cache';
+/**
+ * STX Media - Image Processing Cache
+ *
+ * Specialized cache for image processing results.
+ *
+ * @module media/image/processor/cache
+ */
 import type { EnhancedImgProps, ProcessedImageResult, TsImagesConfig } from '../../types';
+import { type CacheConfig } from '../../shared/cache';
+/**
+ * Image processor cache configuration
+ */
+export interface ImageCacheConfig extends CacheConfig {
+    /** Cache variants separately */
+    cacheVariants?: boolean;
+    /** Cache placeholders separately */
+    cachePlaceholders?: boolean;
+}
+/**
+ * Image processor cache class
+ */
+export declare class ImageProcessorCache {
+    private config;
+    constructor(config?: Partial<ImageCacheConfig>);
+    /**
+     * Get cached processing result
+     */
+    get(src: string, options: Partial<EnhancedImgProps>): Promise<ProcessedImageResult | null>;
+    /**
+     * Set cached processing result
+     */
+    set(src: string, options: Partial<EnhancedImgProps>, result: ProcessedImageResult): Promise<void>;
+    /**
+     * Clear the entire image cache
+     */
+    clear(): Promise<void>;
+    /**
+     * Update cache configuration
+     */
+    updateConfig(config: Partial<ImageCacheConfig>): void;
+}
 /**
  * Get cached image processing result
  */
@@ -12,20 +51,3 @@ export declare function setCachedImageResult(src: string, options: Partial<Enhan
  * Clear image processing cache
  */
 export declare function clearImageCache(): Promise<void>;
-/**
- * Image processor cache configuration
- */
-export declare interface ImageCacheConfig extends CacheConfig {
-  cacheVariants?: boolean
-  cachePlaceholders?: boolean
-}
-/**
- * Image processor cache class
- */
-export declare class ImageProcessorCache {
-  constructor(config?: Partial<ImageCacheConfig>);
-  get(src: string, options: Partial<EnhancedImgProps>): Promise<ProcessedImageResult | null>;
-  set(src: string, options: Partial<EnhancedImgProps>, result: ProcessedImageResult): Promise<void>;
-  clear(): Promise<void>;
-  updateConfig(config: Partial<ImageCacheConfig>): void;
-}

package/dist/media/image/processor/index.d.ts

@@ -1,13 +1,3 @@
-// Re-export types for convenience
-export type {
-  EnhancedImgProps,
-  ProcessedImageResult,
-  ResponsiveVariantSet,
-  TsImagesConfig,
-  ImageOptimizationPreset,
-  ImageTransformationConfig,
-  FormatQualitySettings,
-} from '../../types';
 /**
  * STX Media - Image Processor
  *
@@ -18,3 +8,4 @@ export type {
 export { processImage, optimizeImage, applyTransformations } from './optimizer';
 export { generateResponsiveVariants, generateSrcset } from './responsive';
 export { getCachedImageResult, setCachedImageResult, clearImageCache, ImageProcessorCache } from './cache';
+export type { EnhancedImgProps, ProcessedImageResult, ResponsiveVariantSet, TsImagesConfig, ImageOptimizationPreset, ImageTransformationConfig, FormatQualitySettings, } from '../../types';

package/dist/media/image/processor/optimizer.d.ts

@@ -1,3 +1,10 @@
+/**
+ * STX Media - Image Optimizer
+ *
+ * Wraps ts-images for image optimization and transformation.
+ *
+ * @module media/image/processor/optimizer
+ */
 import type { EnhancedImgProps, ProcessedImageResult, TsImagesConfig, ImageFormat, ImageTransformationConfig } from '../../types';
 /**
  * Process a single image with ts-images
@@ -6,7 +13,11 @@ export declare function processImage(src: string, options: Partial<EnhancedImgPr
 /**
  * Optimize a single image without responsive variants
  */
-export declare function optimizeImage(src: string, format: ImageFormat, quality: number, outputPath: string): Promise<{ success: boolean; size?: number; error?: string }>;
+export declare function optimizeImage(src: string, format: ImageFormat, quality: number, outputPath: string): Promise<{
+    success: boolean;
+    size?: number;
+    error?: string;
+}>;
 /**
  * Apply transformations to an image
  */

package/dist/media/image/processor/responsive.d.ts

@@ -1,4 +1,15 @@
+/**
+ * STX Media - Responsive Image Generation
+ *
+ * Generates responsive image variants at multiple widths and formats.
+ *
+ * @module media/image/processor/responsive
+ */
 import type { EnhancedImgProps, ResponsiveVariantSet, TsImagesConfig, ProcessedImageResult } from '../../types';
+/**
+ * Default responsive breakpoints
+ */
+export declare const DEFAULT_RESPONSIVE_WIDTHS: number[];
 /**
  * Generate responsive image variants using ts-images
  */
@@ -10,9 +21,8 @@ export declare function generateSrcset(variants: ProcessedImageResult['variants'
 /**
  * Generate art direction sources for <picture> element
  */
-export declare function generateArtDirectionSources(src: string, artDirection: NonNullable<EnhancedImgProps['artDirection']>, config: TsImagesConfig): Promise<Array<{ media: string; srcset: string; type: string }>>;
-/**
- * Default responsive breakpoints
- * @defaultValue `[320, 480, 640, 768, 1024, 1280, 1536, 1920]`
- */
-export declare const DEFAULT_RESPONSIVE_WIDTHS: number[];
+export declare function generateArtDirectionSources(src: string, artDirection: NonNullable<EnhancedImgProps['artDirection']>, config: TsImagesConfig): Promise<Array<{
+    media: string;
+    srcset: string;
+    type: string;
+}>>;

package/dist/media/image/srcset.d.ts

@@ -1,4 +1,32 @@
+/**
+ * STX Media - Srcset Generation
+ *
+ * Generate responsive srcset attributes for images following imgix.js patterns.
+ * Supports both width-based srcsets and DPR-based srcsets for fixed-width images.
+ *
+ * @module media/image/srcset
+ */
 import type { Breakpoint, ImageFormat, ImageParams, ImageVariant, SrcsetData, SrcsetOptions } from '../types';
+/**
+ * Default breakpoint widths for responsive images
+ */
+export declare const DEFAULT_WIDTHS: number[];
+/**
+ * Default DPR values for fixed-width images
+ */
+export declare const DEFAULT_DPR_VALUES: number[];
+/**
+ * Default output formats in order of preference
+ */
+export declare const DEFAULT_FORMATS: ImageFormat[];
+/**
+ * MIME types for each format
+ */
+export declare const MIME_TYPES: Record<ImageFormat, string>;
+/**
+ * File extensions for each format
+ */
+export declare const FORMAT_EXTENSIONS: Record<ImageFormat, string>;
 /**
  * Generate a width-based srcset string
  *
@@ -61,6 +89,21 @@ export declare function generateSizesAttribute(breakpoints: Record<string, strin
  * Generate sizes from named breakpoints
  */
 export declare function generateSizesFromBreakpoints(breakpoints: Breakpoint[], defaultSize?: string): string;
+/**
+ * Common responsive sizes patterns
+ */
+export declare const COMMON_SIZES: {
+    /** Full width on all screens */
+    readonly fullWidth: '100vw';
+    /** Half width on desktop, full on mobile */
+    readonly halfDesktop: '(max-width: 768px) 100vw, 50vw';
+    /** Third width on desktop, full on mobile */
+    readonly thirdDesktop: '(max-width: 768px) 100vw, 33.33vw';
+    /** Quarter width on desktop, half on tablet, full on mobile */
+    readonly quarterDesktop: '(max-width: 480px) 100vw, (max-width: 768px) 50vw, 25vw';
+    /** Content width (centered with max-width) */
+    readonly contentWidth: '(max-width: 768px) 100vw, (max-width: 1200px) 80vw, 960px';
+};
 /**
  * Build an image URL with transformation parameters
  *
@@ -74,7 +117,10 @@ 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 };
+export declare function parseImageUrl(url: string): {
+    src: string;
+    params: ImageParams;
+};
 /**
  * Generate complete srcset data for all formats
  *
@@ -109,52 +155,3 @@ 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
- * @defaultValue `[320, 480, 640, 768, 1024, 1280, 1536, 1920, 2560]`
- */
-export declare const DEFAULT_WIDTHS: number[];
-/**
- * Default DPR values for fixed-width images
- * @defaultValue `[1, 1.5, 2, 3]`
- */
-export declare const DEFAULT_DPR_VALUES: number[];
-/**
- * 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'
-};

package/dist/media/shared/cache.d.ts

@@ -1,3 +1,48 @@
+/**
+ * STX Media - Shared Cache Implementation
+ *
+ * Provides disk and memory caching for processed media assets.
+ *
+ * @module media/shared/cache
+ */
+/**
+ * Cache entry metadata
+ */
+export interface CacheEntry<T = unknown> {
+    /** Cache key */
+    key: string;
+    /** Source file path */
+    src: string;
+    /** Source file hash */
+    srcHash: string;
+    /** Source file mtime */
+    srcMtime: number;
+    /** Options hash */
+    optionsHash: string;
+    /** Cached data */
+    data: T;
+    /** When this entry was created */
+    createdAt: number;
+    /** When this entry was last accessed */
+    lastAccessedAt: number;
+}
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+    /** Enable caching */
+    enabled: boolean;
+    /** Cache directory */
+    directory: string;
+    /** Max cache age in days */
+    maxAge: number;
+    /** Max cache size in MB */
+    maxSize: number;
+}
+/**
+ * Default cache configuration
+ */
+export declare const defaultCacheConfig: CacheConfig;
 /**
  * Get item from cache
  */
@@ -9,7 +54,6 @@ export declare function setCached<T>(src: string, options: Record<string, unknow
 /**
  * Clear cache for a specific source
  */
-// eslint-disable-next-line pickier/no-unused-vars
 export declare function clearCacheForSource(src: string, type: 'image' | 'video', config?: CacheConfig): Promise<void>;
 /**
  * Clear entire cache
@@ -18,39 +62,15 @@ export declare function clearCache(type: 'image' | 'video' | 'all', config?: Cac
 /**
  * Get cache statistics
  */
-// eslint-disable-next-line pickier/no-unused-vars
 export declare function getCacheStats(config?: CacheConfig): Promise<{
-  memoryEntries: number
-  diskEntries: { image: number; video: number }
-  totalSizeMB: number
+    memoryEntries: number;
+    diskEntries: {
+        image: number;
+        video: number;
+    };
+    totalSizeMB: number;
 }>;
 /**
  * Prune old cache entries
  */
 export declare function pruneCache(config?: CacheConfig): Promise<number>;
-/**
- * Default cache configuration
- */
-export declare const defaultCacheConfig: CacheConfig;
-/**
- * Cache entry metadata
- */
-export declare interface CacheEntry<T = unknown> {
-  key: string
-  src: string
-  srcHash: string
-  srcMtime: number
-  optionsHash: string
-  data: T
-  createdAt: number
-  lastAccessedAt: number
-}
-/**
- * Cache configuration
- */
-export declare interface CacheConfig {
-  enabled: boolean
-  directory: string
-  maxAge: number
-  maxSize: number
-}

package/dist/media/shared/hash.d.ts

@@ -1,3 +1,10 @@
+/**
+ * STX Media - Content Hashing Utilities
+ *
+ * Provides content hashing for cache invalidation.
+ *
+ * @module media/shared/hash
+ */
 /**
  * Generate SHA-256 hash of file content
  */