@stacksjs/stx 0.2.0 → 0.2.3

package/dist/media/client/upload-handler.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Validate a file before upload
+ */
+export declare function validateFile(file: File, options?: Partial<UploadHandlerOptions>): FileValidationResult;
+/**
+ * Upload a single file with progress tracking
+ *
+ * @example
+ * ```typescript
+ * const result = await uploadFile(file, {
+ *   endpoint: '/api/upload',
+ *   onProgress: (progress) => console.log(progress.percent + '%')
+ * })
+ * ```
+ */
+export declare function uploadFile(file: File, options: UploadHandlerOptions, onProgress?: (progress: UploadProgress) => void): Promise<UploadResult>;
+/**
+ * Upload multiple files
+ */
+export declare function uploadFiles(files: File[], options: UploadHandlerOptions, onProgress?: (file: File, progress: UploadProgress) => void, onComplete?: (file: File, result: UploadResult) => void): Promise<UploadResult[]>;
+/**
+ * Generate a preview data URL for an image file
+ */
+export declare function generateImagePreview(file: File, maxSize?: number): Promise<string>;
+/**
+ * Generate preview for video file (first frame)
+ */
+export declare function generateVideoPreview(file: File): Promise<string>;
+/**
+ * Generate client-side upload handler runtime
+ */
+export declare function generateUploadRuntime(): string;
+/**
+ * STX Media - Client-Side Upload Handler
+ *
+ * Handle file uploads with progress tracking, validation, and preview.
+ *
+ * @module media/client/upload-handler
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface UploadHandlerOptions {
+  endpoint: string
+  method?: 'POST' | 'PUT' | 'PATCH'
+  headers?: Record<string, string>
+  fieldName?: string
+  maxSize?: number
+  accept?: string[]
+  timeout?: number
+  withCredentials?: boolean
+  formData?: Record<string, string>
+  chunkSize?: number
+}
+export declare interface UploadProgress {
+  file: File
+  loaded: number
+  total: number
+  percent: number
+  speed?: number
+  timeRemaining?: number
+  chunk?: number
+  totalChunks?: number
+}
+export declare interface UploadResult {
+  success: boolean
+  url?: string
+  id?: string
+  name?: string
+  size?: number
+  type?: string
+  error?: string
+  data?: Record<string, unknown>
+}
+export declare interface FileValidationResult {
+  valid: boolean
+  error?: string
+  code?: 'INVALID_TYPE' | 'FILE_TOO_LARGE' | 'FILE_TOO_SMALL'
+}

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

@@ -0,0 +1,46 @@
+import {  } from './placeholder';
+import {  } from './srcset';
+import type { ImageRenderContext, ImageRenderResult, ImgProps, EnhancedImgProps, TsImagesConfig, ProcessedImageResult, ResponsiveVariantSet,  } from '../types';
+/**
+ * Render an optimized <Img> component
+ *
+ * Supports both standard ImgProps and EnhancedImgProps with ts-images integration.
+ *
+ * @example
+ * ```typescript
+ * // Standard usage
+ * const result = await renderImgComponent({
+ *   src: '/images/hero.jpg',
+ *   alt: 'Hero image',
+ *   sizes: '(max-width: 768px) 100vw, 50vw',
+ *   placeholder: 'thumbhash',
+ *   lazy: true,
+ * })
+ *
+ * // With ts-images processing
+ * const result = await renderImgComponent({
+ *   src: '/images/hero.jpg',
+ *   alt: 'Hero image',
+ *   process: true,
+ *   preset: 'web',
+ *   responsiveWidths: [320, 640, 1024, 1920],
+ * }, { tsImagesConfig: { enabled: true, outputDir: 'dist/images' } })
+ * ```
+ */
+export declare function renderImgComponent(props: ImgProps | EnhancedImgProps, context?: ImageRenderContext | ExtendedImageRenderContext): Promise<ImageRenderResult>;
+/**
+ * Parse <Img> component from template content
+ */
+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
+}

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

@@ -0,0 +1,9 @@
+import type { CustomDirective } from '../../types';
+/**
+ * Create the @img directive
+ */
+export declare function createImgDirective(): CustomDirective;
+/**
+ * The @img directive instance
+ */
+export declare const imgDirective: unknown;

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

@@ -0,0 +1,212 @@
+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
+}
+};

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

@@ -0,0 +1,118 @@
+export type { ExtendedImageRenderContext } from './component';
+export {
+  // Main render function
+  renderImgComponent,
+  // Template parser
+  parseImgComponent,
+  processImgComponents,
+} from './component';
+export {
+  // Directive factory
+  createImgDirective,
+  // Directive instance
+  imgDirective,
+} from './directive';
+export {
+  // Constants
+  DEFAULT_WIDTHS,
+  DEFAULT_DPR_VALUES,
+  DEFAULT_FORMATS,
+  MIME_TYPES,
+  FORMAT_EXTENSIONS,
+  COMMON_SIZES,
+
+  // Width-based srcset
+  generateWidthSrcset,
+  generateAutoWidthSrcset,
+  calculateOptimalWidths,
+
+  // DPR-based srcset
+  generateDprSrcset,
+  generateDprSrcsetWithVariableQuality,
+
+  // Sizes attribute
+  generateSizesAttribute,
+  generateSizesFromBreakpoints,
+
+  // URL building
+  buildImageUrl,
+  parseImageUrl,
+
+  // Full srcset generation
+  generateSrcsetData,
+  generateSourceTags,
+
+  // Utilities
+  getBestVariant,
+  getFallbackVariant,
+  groupVariantsByFormat,
+  getMimeType,
+  getFormatExtension,
+  detectFormat,
+} from './srcset';
+export {
+  // Constants
+  DEFAULT_PLACEHOLDER_OPTIONS,
+  BLUR_UP_CSS,
+
+  // Generation
+  generatePlaceholder,
+  generateThumbhashPlaceholder,
+  generateLQIP,
+  extractDominantColor,
+  generateColorPlaceholder,
+
+  // Thumbhash
+  decodeThumbhash,
+
+  // CSS
+  generatePlaceholderCSS,
+  generatePlaceholderStyle,
+
+  // Cache
+  getCachedPlaceholder,
+  clearPlaceholderCache,
+  getPlaceholderCacheStats,
+} from './placeholder';
+export {
+  // URL building
+  buildImageUrl as buildUrl,
+  parseImageUrl as parseUrl,
+  mergeParams,
+
+  // Convenience functions
+  resize,
+  crop,
+  thumbnail,
+  contain,
+  cover,
+  blur,
+  sharpen,
+  grayscale,
+  sepia,
+  invert,
+  brightness,
+  contrast,
+  saturation,
+  rotate,
+  flipHorizontal,
+  flipVertical,
+  format,
+  quality,
+  auto,
+
+  // Watermark
+  watermark,
+
+  // Presets
+  PRESETS,
+  applyPreset,
+
+  // Responsive helpers
+  srcsetUrls,
+  dprUrls,
+
+  // Validation
+  validateParams,
+  sanitizeParams,
+} from './editing';

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

@@ -0,0 +1,78 @@
+import type { PlaceholderOptions, PlaceholderResult } from '../types';
+/**
+ * Generate a placeholder for an image using the specified strategy
+ *
+ * @param src - Image source path
+ * @param options - Placeholder options
+ * @returns Placeholder result with data URL
+ *
+ * @example
+ * ```typescript
+ * const placeholder = await generatePlaceholder('/images/hero.jpg', {
+ *   strategy: 'thumbhash',
+ * })
+ * console.log(placeholder.dataURL) // data:image/png;base64,...
+ * ```
+ */
+export declare function generatePlaceholder(src: string, options?: Partial<PlaceholderOptions>): Promise<PlaceholderResult>;
+/**
+ * Generate a thumbhash placeholder specifically
+ *
+ * @param src - Image source path
+ * @returns Thumbhash data URL
+ */
+export declare function generateThumbhashPlaceholder(src: string): Promise<string>;
+/**
+ * Decode a thumbhash string to a data URL (client-side)
+ *
+ * This is a minimal thumbhash decoder for client-side use
+ * Based on https://github.com/evanw/thumbhash
+ */
+export declare function decodeThumbhash(hash: Uint8Array): string;
+/**
+ * Generate a low-quality image placeholder with blur
+ *
+ * @param src - Image source path
+ * @param width - Placeholder width (default: 20)
+ * @param quality - JPEG quality (default: 50)
+ */
+export declare function generateLQIP(src: string, width?: number, quality?: number): Promise<PlaceholderResult>;
+/**
+ * Extract dominant color from an image
+ *
+ * @param src - Image source path
+ * @returns Hex color string
+ */
+export declare function extractDominantColor(src: string): Promise<string>;
+/**
+ * Generate a solid color placeholder
+ */
+export declare function generateColorPlaceholder(color: string, width?: number, height?: number): string;
+/**
+ * Generate CSS for placeholder with specific options
+ */
+export declare function generatePlaceholderCSS(id: string, placeholder: PlaceholderResult, options?: Partial<PlaceholderOptions>): string;
+/**
+ * Generate inline style for placeholder background
+ */
+export declare function generatePlaceholderStyle(placeholder: PlaceholderResult): string;
+/**
+ * Get placeholder from cache or generate new
+ */
+export declare function getCachedPlaceholder(src: string, options?: Partial<PlaceholderOptions>): Promise<PlaceholderResult>;
+/**
+ * Clear the placeholder cache
+ */
+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;

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

@@ -0,0 +1,32 @@
+import {  } from '../../shared/cache';
+import type { EnhancedImgProps, ProcessedImageResult, TsImagesConfig,  } from '../../types';
+/**
+ * Get cached image processing result
+ */
+export declare function getCachedImageResult(src: string, options: Partial<EnhancedImgProps>, config?: TsImagesConfig): Promise<ProcessedImageResult | null>;
+/**
+ * Set cached image processing result
+ */
+export declare function setCachedImageResult(src: string, options: Partial<EnhancedImgProps>, result: ProcessedImageResult, config?: TsImagesConfig): Promise<void>;
+/**
+ * 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 {
+  private config: ImageCacheConfig;
+  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

@@ -0,0 +1,12 @@
+export type {
+  EnhancedImgProps,
+  ProcessedImageResult,
+  ResponsiveVariantSet,
+  TsImagesConfig,
+  ImageOptimizationPreset,
+  ImageTransformationConfig,
+  FormatQualitySettings,
+} from '../../types';
+export { processImage, optimizeImage, applyTransformations } from './optimizer';
+export { generateResponsiveVariants, generateSrcset } from './responsive';
+export { getCachedImageResult, setCachedImageResult, clearImageCache, ImageProcessorCache } from './cache';

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

@@ -0,0 +1,13 @@
+import type { EnhancedImgProps, ProcessedImageResult, TsImagesConfig, ImageFormat, ImageTransformationConfig,  } from '../../types';
+/**
+ * Process a single image with ts-images
+ */
+export declare function processImage(src: string, options: Partial<EnhancedImgProps>, config: TsImagesConfig): Promise<ProcessedImageResult>;
+/**
+ * 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 }>;
+/**
+ * Apply transformations to an image
+ */
+export declare function applyTransformations(src: string, transformations: ImageTransformationConfig[], tsImages?: typeof import('ts-images') | null): Promise<Buffer | null>;

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

@@ -0,0 +1,17 @@
+import type { EnhancedImgProps, ResponsiveVariantSet, TsImagesConfig, ProcessedImageResult,  } from '../../types';
+/**
+ * Generate responsive image variants using ts-images
+ */
+export declare function generateResponsiveVariants(src: string, options: Partial<EnhancedImgProps>, config: TsImagesConfig): Promise<ResponsiveVariantSet | null>;
+/**
+ * Generate srcset string from variants
+ */
+export declare function generateSrcset(variants: ProcessedImageResult['variants'], type?: 'width' | 'dpr'): string;
+/**
+ * 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
+ */
+export declare const DEFAULT_RESPONSIVE_WIDTHS: readonly [320, 480, 640, 768, 1024, 1280, 1536, 1920];