@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/media/image/index.js

@@ -0,0 +1,80 @@
+export {
+  renderImgComponent,
+  parseImgComponent,
+  processImgComponents
+} from "./component.js";
+export {
+  createImgDirective,
+  imgDirective
+} from "./directive.js";
+export {
+  DEFAULT_WIDTHS,
+  DEFAULT_DPR_VALUES,
+  DEFAULT_FORMATS,
+  MIME_TYPES,
+  FORMAT_EXTENSIONS,
+  COMMON_SIZES,
+  generateWidthSrcset,
+  generateAutoWidthSrcset,
+  calculateOptimalWidths,
+  generateDprSrcset,
+  generateDprSrcsetWithVariableQuality,
+  generateSizesAttribute,
+  generateSizesFromBreakpoints,
+  buildImageUrl,
+  parseImageUrl,
+  generateSrcsetData,
+  generateSourceTags,
+  getBestVariant,
+  getFallbackVariant,
+  groupVariantsByFormat,
+  getMimeType,
+  getFormatExtension,
+  detectFormat
+} from "./srcset.js";
+export {
+  DEFAULT_PLACEHOLDER_OPTIONS,
+  BLUR_UP_CSS,
+  generatePlaceholder,
+  generateThumbhashPlaceholder,
+  generateLQIP,
+  extractDominantColor,
+  generateColorPlaceholder,
+  decodeThumbhash,
+  generatePlaceholderCSS,
+  generatePlaceholderStyle,
+  getCachedPlaceholder,
+  clearPlaceholderCache,
+  getPlaceholderCacheStats
+} from "./placeholder.js";
+export {
+  buildImageUrl as buildUrl,
+  parseImageUrl as 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 "./editing.js";

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

@@ -0,0 +1,89 @@
+/**
+ * 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
+ *
+ * @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[];
+};

package/dist/media/image/placeholder.js

@@ -0,0 +1,188 @@
+export const DEFAULT_PLACEHOLDER_OPTIONS = {
+  strategy: "thumbhash",
+  width: 20,
+  quality: 50,
+  blurLevel: 40,
+  transitionDuration: 300,
+  easing: "ease-out"
+}, BLUR_UP_CSS = `
+.stx-img-placeholder {
+  position: relative;
+  overflow: hidden;
+  background-size: cover;
+  background-position: center;
+  background-repeat: no-repeat;
+}
+
+.stx-img-placeholder img {
+  opacity: 0;
+  transition: opacity var(--stx-img-transition-duration, 300ms) var(--stx-img-transition-easing, ease-out);
+}
+
+.stx-img-placeholder.stx-img-loaded img {
+  opacity: 1;
+}
+
+.stx-img-blur {
+  filter: blur(20px);
+  transform: scale(1.1);
+  transition: filter var(--stx-img-transition-duration, 300ms) var(--stx-img-transition-easing, ease-out),
+              transform var(--stx-img-transition-duration, 300ms) var(--stx-img-transition-easing, ease-out);
+}
+
+.stx-img-loaded .stx-img-blur {
+  filter: blur(0);
+  transform: scale(1);
+}
+`.trim();
+async function getTsImages() {
+  try {
+    return await import("ts-images");
+  } catch {
+    return null;
+  }
+}
+export async function generatePlaceholder(src, options = {}) {
+  const opts = { ...DEFAULT_PLACEHOLDER_OPTIONS, ...options }, tsImages = await getTsImages();
+  if (tsImages)
+    try {
+      return await generateWithTsImages(src, opts, tsImages);
+    } catch (error) {
+      console.warn(`[stx-media] ts-images placeholder generation failed, using fallback: ${error}`);
+    }
+  return generateFallbackPlaceholder(src, opts);
+}
+async function generateWithTsImages(src, options, tsImages) {
+  const { generatePlaceholder: tsGeneratePlaceholder, generateThumbHash } = tsImages, tsStrategy = {
+    blur: "blur",
+    thumbhash: "thumbhash",
+    blurhash: "thumbhash",
+    pixelate: "pixelate",
+    "dominant-color": "dominant-color",
+    none: "blur"
+  }[options.strategy] || "blur";
+  if (options.strategy === "thumbhash")
+    return {
+      dataURL: (await generateThumbHash(src)).dataUrl,
+      width: 32,
+      height: 32,
+      aspectRatio: 1,
+      originalWidth: 0,
+      originalHeight: 0,
+      strategy: "thumbhash"
+    };
+  const result = await tsGeneratePlaceholder(src, {
+    width: options.width,
+    height: options.height,
+    quality: options.quality,
+    blurLevel: options.blurLevel,
+    strategy: tsStrategy,
+    base64Encode: !0
+  });
+  return {
+    dataURL: result.dataURL,
+    width: result.width,
+    height: result.height,
+    aspectRatio: result.aspectRatio,
+    originalWidth: result.originalWidth,
+    originalHeight: result.originalHeight,
+    strategy: options.strategy,
+    dominantColor: result.dominantColor,
+    css: result.css
+  };
+}
+function generateFallbackPlaceholder(_src, options) {
+  const width = options.width || 20, height = options.height || width, color = "#e5e7eb", svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"><rect fill="${color}" width="${width}" height="${height}"/></svg>`;
+  return {
+    dataURL: `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`,
+    width,
+    height,
+    aspectRatio: width / height,
+    originalWidth: 0,
+    originalHeight: 0,
+    strategy: options.strategy,
+    dominantColor: color
+  };
+}
+export async function generateThumbhashPlaceholder(src) {
+  const tsImages = await getTsImages();
+  if (tsImages)
+    try {
+      return (await tsImages.generateThumbHash(src)).dataUrl;
+    } catch {}
+  return (await generateFallbackPlaceholder(src, {
+    strategy: "thumbhash",
+    width: 32,
+    height: 32
+  })).dataURL;
+}
+export function decodeThumbhash(hash) {
+  const header = hash[0] | hash[1] << 8 | hash[2] << 16, l_dc = (header & 63) / 63, p_dc = (header >> 6 & 63) / 31.5 - 1, q_dc = (header >> 12 & 63) / 31.5 - 1, l_scale = (header >> 18 & 31) / 31, hasAlpha = header >> 23 !== 0, header2 = hash[3] | hash[4] << 8, p_scale = (header2 >> 3 & 63) / 63, q_scale = (header2 >> 9 & 63) / 63, isLandscape = header2 >> 15 !== 0, lx = Math.max(3, isLandscape ? hasAlpha ? 5 : 7 : hasAlpha ? 5 : 7), ly = Math.max(3, isLandscape ? hasAlpha ? 5 : 7 : hasAlpha ? 5 : 7), width = 32, height = 32, r = Math.max(0, Math.min(255, Math.round((l_dc + p_dc) * 255))), g = Math.max(0, Math.min(255, Math.round(l_dc * 255))), b = Math.max(0, Math.min(255, Math.round((l_dc - p_dc) * 255))), svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+    <rect fill="rgb(${r},${g},${b})" width="${width}" height="${height}"/>
+  </svg>`;
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+export async function generateLQIP(src, width = 20, quality = 50) {
+  return generatePlaceholder(src, {
+    strategy: "blur",
+    width,
+    quality,
+    blurLevel: 40
+  });
+}
+export async function extractDominantColor(src) {
+  const tsImages = await getTsImages();
+  if (tsImages)
+    try {
+      return (await tsImages.generatePlaceholder(src, {
+        strategy: "dominant-color"
+      })).dominantColor || "#e5e7eb";
+    } catch {}
+  return "#e5e7eb";
+}
+export function generateColorPlaceholder(color, width = 1, height = 1) {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect fill="${color}" width="${width}" height="${height}"/></svg>`;
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+export function generatePlaceholderCSS(id, placeholder, options = {}) {
+  const duration = options.transitionDuration || 300, easing = options.easing || "ease-out";
+  return `
+#${id} {
+  --stx-img-transition-duration: ${duration}ms;
+  --stx-img-transition-easing: ${easing};
+  background-image: url('${placeholder.dataURL}');
+  background-size: cover;
+  background-position: center;
+}
+
+#${id} img {
+  opacity: 0;
+  transition: opacity var(--stx-img-transition-duration) var(--stx-img-transition-easing);
+}
+
+#${id}.stx-img-loaded img {
+  opacity: 1;
+}
+`.trim();
+}
+export function generatePlaceholderStyle(placeholder) {
+  return `background-image: url('${placeholder.dataURL}'); background-size: cover; background-position: center;`;
+}
+const placeholderCache = new Map;
+export async function getCachedPlaceholder(src, options = {}) {
+  const cacheKey = `${src}:${JSON.stringify(options)}`;
+  if (placeholderCache.has(cacheKey))
+    return placeholderCache.get(cacheKey);
+  const placeholder = await generatePlaceholder(src, options);
+  placeholderCache.set(cacheKey, placeholder);
+  return placeholder;
+}
+export function clearPlaceholderCache() {
+  placeholderCache.clear();
+}
+export function getPlaceholderCacheStats() {
+  return {
+    size: placeholderCache.size,
+    keys: Array.from(placeholderCache.keys())
+  };
+}

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

@@ -0,0 +1,53 @@
+/**
+ * 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
+ */
+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>;

package/dist/media/image/processor/cache.js

@@ -0,0 +1,51 @@
+import {
+  getCached,
+  setCached,
+  clearCache
+} from "../../shared/cache.js";
+const defaultImageCacheConfig = {
+  enabled: !0,
+  directory: ".stx/media-cache",
+  maxAge: 30,
+  maxSize: 500,
+  cacheVariants: !0,
+  cachePlaceholders: !0
+};
+
+export class ImageProcessorCache {
+  config;
+  constructor(config = {}) {
+    this.config = { ...defaultImageCacheConfig, ...config };
+  }
+  async get(src, options) {
+    return getCached(src, options, "image", this.config);
+  }
+  async set(src, options, result) {
+    return setCached(src, options, result, "image", this.config);
+  }
+  async clear() {
+    return clearCache("image", this.config);
+  }
+  updateConfig(config) {
+    this.config = { ...this.config, ...config };
+  }
+}
+let globalImageCache = null;
+function getImageCache(config) {
+  if (!globalImageCache)
+    globalImageCache = new ImageProcessorCache(config);
+  else if (config)
+    globalImageCache.updateConfig(config);
+  return globalImageCache;
+}
+export async function getCachedImageResult(src, options, config) {
+  const cacheConfig = config ? { directory: `${config.outputDir}/../.cache` } : {};
+  return getImageCache(cacheConfig).get(src, options);
+}
+export async function setCachedImageResult(src, options, result, config) {
+  const cacheConfig = config ? { directory: `${config.outputDir}/../.cache` } : {};
+  return getImageCache(cacheConfig).set(src, options, result);
+}
+export async function clearImageCache() {
+  return getImageCache().clear();
+}

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

@@ -0,0 +1,11 @@
+/**
+ * STX Media - Image Processor
+ *
+ * Integration with ts-images for build-time image optimization.
+ *
+ * @module media/image/processor
+ */
+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/index.js

@@ -0,0 +1,3 @@
+export { processImage, optimizeImage, applyTransformations } from "./optimizer.js";
+export { generateResponsiveVariants, generateSrcset } from "./responsive.js";
+export { getCachedImageResult, setCachedImageResult, clearImageCache, ImageProcessorCache } from "./cache.js";

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

@@ -0,0 +1,24 @@
+/**
+ * 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
+ */
+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>;