@stacksjs/stx 0.2.0 → 0.2.3

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

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

package/dist/media/index.d.ts

@@ -0,0 +1,295 @@
+import type { MediaConfig } from './types';
+export type {
+  // Placeholder types
+  PlaceholderStrategy,
+  PlaceholderOptions,
+  PlaceholderResult,
+
+  // Image types (prefixed to avoid conflicts with image-optimization)
+  ImageFormat as MediaImageFormat,
+  ImageFit,
+  ImageCrop,
+  ImageParams,
+  ImageVariant,
+  ProcessedImage,
+  ImgProps,
+  ImgDirectiveOptions,
+  ImageRenderContext as MediaImageRenderContext,
+  ImageRenderResult,
+
+  // Enhanced image types (ts-images integration)
+  EnhancedImgProps,
+  ProcessedImageResult,
+  ResponsiveVariantSet,
+  TsImagesConfig,
+  ImageOptimizationPreset,
+  ImageTransformation,
+  ImageTransformationConfig,
+  FormatQualitySettings,
+  WatermarkConfig,
+  WatermarkPosition,
+  ArtDirectionConfig,
+
+  // Video types
+  VideoSource,
+  VideoEmbedType,
+  PlyrControl,
+  PlyrOptions,
+  VideoProps,
+  VideoDirectiveOptions,
+  VideoRenderResult,
+
+  // Enhanced video types (ts-videos integration)
+  EnhancedVideoProps,
+  ProcessedVideoResult,
+  TsVideosConfig,
+  VideoQualityPreset,
+  VideoPlatformPreset,
+  VideoCodec,
+  AudioCodec,
+  TranscodeConfig,
+  TranscodeResult,
+  ThumbnailResult,
+  PosterGenerationConfig,
+  SpriteSheetConfig,
+  StreamingConfig,
+  StreamingQualityLevel,
+  HLSResult,
+  DASHResult,
+  WaveformConfig,
+
+  // Upload types
+  UploadConfig,
+  UploadProgress,
+  UploadResult,
+  FileValidationResult,
+  MediaUploadProps,
+  UploadDirectiveOptions,
+
+  // Protected media types
+  SignedUrl,
+  SignatureConfig,
+  BatchSignatureRequest,
+  BatchSignatureResult,
+  ProtectedAuthContext,
+  ProtectedMediaProps,
+  ProtectedDirectiveOptions,
+
+  // Media manager types
+  MediaManagerConfig,
+  MediaItem,
+
+  // Configuration types
+  MediaConfig,
+  MediaImageConfig,
+  MediaVideoConfig,
+  MediaUploadConfig,
+  MediaProtectedConfig,
+  MediaCacheConfig,
+
+  // Client types
+  LazyLoadOptions,
+  BlurUpOptions,
+
+  // Utility types
+  Breakpoint,
+  SrcsetOptions,
+  SrcsetData,
+} from './types';
+export type { ExtendedVideoRenderContext } from './video';
+export type { CacheConfig, CacheEntry } from './shared';
+/**
+ * Default media configuration
+ */
+export declare const defaultMediaConfig: MediaConfig;
+export {
+  // Component
+  renderImgComponent,
+  parseImgComponent,
+  processImgComponents,
+
+  // Directive
+  createImgDirective,
+  imgDirective,
+
+  // Srcset generation (prefixed to avoid conflicts with image-optimization)
+  DEFAULT_WIDTHS as MEDIA_DEFAULT_WIDTHS,
+  DEFAULT_DPR_VALUES,
+  DEFAULT_FORMATS as MEDIA_DEFAULT_FORMATS,
+  MIME_TYPES,
+  COMMON_SIZES,
+  generateWidthSrcset,
+  generateAutoWidthSrcset,
+  calculateOptimalWidths,
+  generateDprSrcset,
+  generateDprSrcsetWithVariableQuality,
+  generateSizesAttribute,
+  generateSizesFromBreakpoints,
+  buildImageUrl,
+  parseImageUrl,
+  generateSrcsetData,
+  generateSourceTags,
+  getBestVariant,
+  getFallbackVariant,
+  groupVariantsByFormat,
+  getMimeType,
+  getFormatExtension,
+  detectFormat,
+
+  // Placeholder generation
+  DEFAULT_PLACEHOLDER_OPTIONS,
+  BLUR_UP_CSS,
+  generatePlaceholder,
+  generateThumbhashPlaceholder,
+  generateLQIP,
+  extractDominantColor,
+  generateColorPlaceholder,
+  decodeThumbhash,
+  generatePlaceholderCSS,
+  generatePlaceholderStyle,
+  getCachedPlaceholder,
+  clearPlaceholderCache,
+  getPlaceholderCacheStats,
+
+  // Editing API
+  buildUrl,
+  parseUrl,
+  mergeParams,
+  resize,
+  crop,
+  thumbnail,
+  contain,
+  cover,
+  blur,
+  sharpen,
+  grayscale,
+  sepia,
+  invert,
+  brightness,
+  contrast,
+  saturation,
+  rotate,
+  flipHorizontal,
+  flipVertical,
+  format,
+  quality,
+  auto,
+  watermark,
+  PRESETS,
+  applyPreset,
+  srcsetUrls,
+  dprUrls,
+  validateParams,
+  sanitizeParams,
+} from './image';
+export {
+  processImage,
+  optimizeImage,
+  applyTransformations,
+  generateResponsiveVariants,
+  generateSrcset,
+  getCachedImageResult,
+  setCachedImageResult,
+  clearImageCache,
+  ImageProcessorCache,
+} from './image/processor';
+export {
+  renderVideoComponent,
+  parseVideoDirectiveOptions,
+  // Directive
+  createVideoDirective,
+  videoDirective,
+} from './video';
+export {
+  processVideo,
+  analyzeVideo,
+  generatePoster,
+  generateThumbnails,
+  generateSpriteSheet,
+  generateHLSManifest,
+  generateDASHManifest,
+  getCachedVideoResult,
+  setCachedVideoResult,
+  clearVideoCache,
+  VideoProcessorCache,
+} from './video/processor';
+export { renderMediaUpload } from './upload';
+export {
+  // URL signing
+  signUrl,
+  batchSignUrls,
+  smartBatchSign,
+
+  // Validation
+  isSignatureValid,
+  getTimeUntilExpiry,
+  shouldRefreshSignature,
+
+  // Auth helpers
+  checkAuthAccess,
+  buildAuthParams,
+
+  // Cache
+  getCachedSignature,
+  clearSignatureCache,
+  pruneSignatureCache,
+
+  // Component
+  renderProtectedImg,
+  renderProtectedVideo,
+  processProtectedMedia,
+  parseProtectedArgs,
+
+  // Runtime
+  generateSignatureRuntime,
+} from './protected';
+export { generateMediaManagerEmbed, generateSimpleMediaPicker } from './manager/embed';
+export {
+  // Lazy loading
+  isNativeLazySupported,
+  isIntersectionObserverSupported,
+  initLazyLoading,
+  loadElement,
+  lazyLoad,
+  lazyLoadAll,
+  createLazyObserver,
+  observeElement,
+  disconnectObserver,
+  generateLazyLoadRuntime,
+
+  // Blur-up
+  initBlurUp,
+  initAllBlurUp,
+  renderThumbhashToCanvas,
+  thumbHashToRGBA,
+  thumbHashToDataURL,
+  parseThumbhashString,
+  crossfadeTransition,
+  generateBlurUpRuntime,
+  generateBlurUpCSS,
+
+  // Upload handler
+  validateFile,
+  uploadFile,
+  uploadFiles,
+  generateImagePreview,
+  generateVideoPreview,
+  generateUploadRuntime,
+
+  // Combined runtime
+  generateMediaRuntime,
+  generateMinifiedMediaRuntime,
+} from './client';
+export {
+  hashFile,
+  hashBuffer,
+  hashString,
+  generateCacheKey,
+  getFileMtime,
+  fileExists,
+  getCached,
+  setCached,
+  clearCache,
+  getCacheStats,
+  pruneCache,
+} from './shared';

package/dist/media/manager/embed.d.ts

@@ -0,0 +1,25 @@
+import type { MediaManagerConfig } from '../types';
+/**
+ * Generate HTML and script for embedding a media manager
+ *
+ * @example
+ * ```typescript
+ * const { html, script } = generateMediaManagerEmbed({
+ *   src: 'https://media-manager.example.com/embed.js',
+ *   apiKey: 'your-api-key',
+ *   bucket: 'uploads',
+ * })
+ * ```
+ */
+export declare function generateMediaManagerEmbed(config: MediaManagerConfig): { html: string; script: string };
+/**
+ * Generate a simple media picker modal
+ *
+ * For use when a full media manager is not available,
+ * provides a basic file browser interface.
+ */
+export declare function generateSimpleMediaPicker(options: {
+  accept?: string
+  multiple?: boolean
+  onSelect?: string
+}): { html: string; script: string; css: string };

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

@@ -0,0 +1,34 @@
+import {  } from './signature';
+import type { ProtectedMediaProps,  } from '../types';
+/**
+ * Render a protected image component
+ *
+ * @example
+ * ```typescript
+ * const html = await renderProtectedImg({
+ *   src: '/api/media/secure-image.jpg',
+ *   alt: 'Secure content',
+ *   signatureEndpoint: '/api/sign',
+ *   auth: { role: 'premium' },
+ * })
+ * ```
+ */
+export declare function renderProtectedImg(props: ProtectedMediaProps): Promise<{ html: string; script?: string }>;
+/**
+ * Render a protected video component
+ */
+export declare function renderProtectedVideo(props: ProtectedMediaProps & {
+    poster?: string
+    controls?: boolean
+    autoplay?: boolean
+    muted?: boolean
+    loop?: boolean
+  }): Promise<{ html: string; script?: string }>;
+/**
+ * Collect all protected media elements from content and batch sign
+ */
+export declare function processProtectedMedia(content: string, signatureEndpoint: string): Promise<{ html: string; script: string }>;
+/**
+ * Parse @protected directive arguments
+ */
+export declare function parseProtectedArgs(content: string, params: Record<string, unknown>, context: Record<string, unknown>): ProtectedMediaProps;

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

@@ -0,0 +1,34 @@
+export {
+  // URL signing
+  signUrl,
+  batchSignUrls,
+  smartBatchSign,
+
+  // Validation
+  isSignatureValid,
+  getTimeUntilExpiry,
+  shouldRefreshSignature,
+
+  // Auth helpers
+  checkAuthAccess,
+  buildAuthParams,
+
+  // Cache
+  getCachedSignature,
+  clearSignatureCache,
+  pruneSignatureCache,
+
+  // Runtime
+  generateSignatureRuntime,
+} from './signature';
+export {
+  // Components
+  renderProtectedImg,
+  renderProtectedVideo,
+
+  // Processing
+  processProtectedMedia,
+
+  // Directive helpers
+  parseProtectedArgs,
+} from './component';

package/dist/media/protected/signature.d.ts

@@ -0,0 +1,72 @@
+import type { BatchSignatureResult, ProtectedAuthContext, SignatureConfig, SignedUrl,  } from '../types';
+/**
+ * Sign a single URL for protected access
+ *
+ * @example
+ * ```typescript
+ * const signed = await signUrl('/media/secure-video.mp4', {
+ *   endpoint: '/api/sign',
+ *   expirationSeconds: 3600,
+ * })
+ * console.log(signed.url) // URL with signature query param
+ * ```
+ */
+export declare function signUrl(src: string, config: SignatureConfig): Promise<SignedUrl>;
+/**
+ * Sign multiple URLs in a single batch request
+ *
+ * This minimizes API calls when a page has multiple protected media items.
+ *
+ * @example
+ * ```typescript
+ * const result = await batchSignUrls(
+ *   ['/media/video1.mp4', '/media/video2.mp4'],
+ *   { endpoint: '/api/batch-sign' }
+ * )
+ * console.log(result.signatures.get('/media/video1.mp4'))
+ * ```
+ */
+export declare function batchSignUrls(sources: string[], config: SignatureConfig): Promise<BatchSignatureResult>;
+/**
+ * Smart batch signing that groups requests for efficiency
+ */
+export declare function smartBatchSign(sources: string[], config: SignatureConfig, batchSize?: number): Promise<BatchSignatureResult>;
+/**
+ * Check if a signed URL is still valid (not expired)
+ */
+export declare function isSignatureValid(signedUrl: SignedUrl): boolean;
+/**
+ * Get time until signature expires (in ms)
+ */
+export declare function getTimeUntilExpiry(signedUrl: SignedUrl): number;
+/**
+ * Check if signature should be refreshed (within refresh window)
+ *
+ * @param signedUrl - The signed URL to check
+ * @param refreshWindowMs - Time before expiry to trigger refresh (default: 5 minutes)
+ */
+export declare function shouldRefreshSignature(signedUrl: SignedUrl, refreshWindowMs?: number): boolean;
+/**
+ * Check if user has access based on auth context
+ */
+export declare function checkAuthAccess(auth: ProtectedAuthContext): Promise<boolean>;
+/**
+ * Build auth params for signature request
+ */
+export declare function buildAuthParams(auth: ProtectedAuthContext): Record<string, unknown>;
+/**
+ * Get signed URL from cache or fetch new
+ */
+export declare function getCachedSignature(src: string, config: SignatureConfig): Promise<SignedUrl>;
+/**
+ * Clear signature cache
+ */
+export declare function clearSignatureCache(): void;
+/**
+ * Remove expired signatures from cache
+ */
+export declare function pruneSignatureCache(): number;
+/**
+ * Generate client-side signature handler runtime
+ */
+export declare function generateSignatureRuntime(): string;

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

@@ -0,0 +1,54 @@
+/**
+ * Get item from cache
+ */
+export declare function getCached<T>(src: string, options: Record<string, unknown>, type: 'image' | 'video', config?: CacheConfig): Promise<T | null>;
+/**
+ * Set item in cache
+ */
+export declare function setCached<T>(src: string, options: Record<string, unknown>, data: T, type: 'image' | 'video', config?: CacheConfig): Promise<void>;
+/**
+ * Clear cache for a specific source
+ */
+export declare function clearCacheForSource(src: string, type: 'image' | 'video', config?: CacheConfig): Promise<void>;
+/**
+ * Clear entire cache
+ */
+export declare function clearCache(type: 'image' | 'video' | 'all', config?: CacheConfig): Promise<void>;
+/**
+ * Get cache statistics
+ */
+export declare function getCacheStats(config?: CacheConfig): Promise<{
+  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

@@ -0,0 +1,24 @@
+/**
+ * Generate SHA-256 hash of file content
+ */
+export declare function hashFile(filePath: string): Promise<string>;
+/**
+ * Generate hash from buffer
+ */
+export declare function hashBuffer(buffer: Buffer | Uint8Array): string;
+/**
+ * Generate hash from string
+ */
+export declare function hashString(str: string): string;
+/**
+ * Generate cache key from source path and options
+ */
+export declare function generateCacheKey(src: string, options: Record<string, unknown>): string;
+/**
+ * Get file modification time for cache validation
+ */
+export declare function getFileMtime(filePath: string): Promise<number>;
+/**
+ * Check if file exists
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;

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

@@ -0,0 +1,2 @@
+export * from './hash';
+export * from './cache';