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

package/dist/media/image/directive.js

@@ -0,0 +1,160 @@
+import { defineDirective } from "../../directive-api.js";
+import { renderImgComponent } from "./component.js";
+import { DEFAULT_WIDTHS, DEFAULT_FORMATS } from "./srcset.js";
+export function createImgDirective() {
+  return defineDirective({
+    name: "img",
+    hasEndTag: !1,
+    description: "Render an optimized responsive image with srcset and lazy loading",
+    transform: async (content, params, context, filePath) => {
+      const { src, alt, options } = parseImgArgs(content, params, context);
+      if (!src) {
+        console.warn("@img directive: missing src argument");
+        return "<!-- @img: missing src -->";
+      }
+      const props = {
+        src,
+        alt: alt || "",
+        widths: options.widths || DEFAULT_WIDTHS,
+        formats: options.formats || DEFAULT_FORMATS,
+        quality: options.quality,
+        sizes: options.sizes,
+        dpr: options.dpr,
+        params: options.params,
+        placeholder: options.placeholder,
+        placeholderOptions: options.placeholderOptions,
+        lazy: options.lazy !== !1,
+        priority: options.priority || !1,
+        loading: options.loading,
+        decoding: options.decoding,
+        fetchpriority: options.fetchpriority,
+        objectFit: options.objectFit,
+        objectPosition: options.objectPosition,
+        class: options.class,
+        style: options.style,
+        id: options.id,
+        width: options.width,
+        height: options.height
+      }, isDev = context.__isDev || !1, result = await renderImgComponent(props, { isDev });
+      let output = result.html;
+      if (result.preloadLink)
+        output = result.preloadLink + `
+` + output;
+      if (result.css)
+        output += `
+<style>${result.css}</style>`;
+      if (result.script)
+        output += `
+<script>${result.script}</script>`;
+      return output;
+    },
+    defaults: {
+      src: "",
+      alt: "",
+      options: {
+        lazy: !0,
+        placeholder: "none"
+      }
+    }
+  });
+}
+function parseImgArgs(content, params, context) {
+  if (params.src)
+    return {
+      src: String(params.src),
+      alt: String(params.alt || ""),
+      options: params.options || {}
+    };
+  let args = content.trim();
+  if (args.startsWith("@img(") || args.startsWith("("))
+    args = args.replace(/^@img\(/, "").replace(/^\(/, "").replace(/\)$/, "");
+  const parsed = parseArguments(args);
+  let src = resolveValue(parsed[0], context) || "", alt = resolveValue(parsed[1], context) || "", options = {};
+  if (parsed[2]) {
+    const resolvedOptions = resolveValue(parsed[2], context);
+    if (typeof resolvedOptions === "object" && resolvedOptions !== null)
+      options = resolvedOptions;
+    else if (typeof parsed[2] === "string")
+      try {
+        options = JSON.parse(parsed[2]);
+      } catch {}
+  }
+  return { src, alt, options };
+}
+function parseArguments(argsStr) {
+  const args = [];
+  let current = "", inString = !1, stringChar = "", braceDepth = 0, bracketDepth = 0;
+  for (let i = 0;i < argsStr.length; i++) {
+    const char = argsStr[i], prevChar = i > 0 ? argsStr[i - 1] : "";
+    if ((char === '"' || char === "'" || char === "`") && prevChar !== "\\") {
+      if (!inString) {
+        inString = !0;
+        stringChar = char;
+      } else if (char === stringChar) {
+        inString = !1;
+        stringChar = "";
+      } else
+        current += char;
+      continue;
+    }
+    if (!inString) {
+      if (char === "{")
+        braceDepth++;
+      if (char === "}")
+        braceDepth--;
+      if (char === "[")
+        bracketDepth++;
+      if (char === "]")
+        bracketDepth--;
+      if (char === "," && braceDepth === 0 && bracketDepth === 0) {
+        args.push(current.trim());
+        current = "";
+        continue;
+      }
+    }
+    current += char;
+  }
+  if (current.trim())
+    args.push(current.trim());
+  return args;
+}
+function resolveValue(value, context) {
+  if (typeof value !== "string")
+    return value;
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'"))
+    return trimmed.slice(1, -1);
+  if (!trimmed.startsWith("/") && !trimmed.startsWith(".") && !trimmed.startsWith("http") && !trimmed.startsWith("{")) {
+    const contextValue = context[trimmed];
+    if (contextValue !== void 0)
+      return contextValue;
+  }
+  if (trimmed.startsWith("{") || trimmed.startsWith("["))
+    try {
+      return JSON.parse(trimmed);
+    } catch {}
+  return trimmed;
+}
+function renderSimpleImage(src, alt, options) {
+  const attrs = [`src="${escapeAttr(src)}"`];
+  if (alt)
+    attrs.push(`alt="${escapeAttr(alt)}"`);
+  if (options.width)
+    attrs.push(`width="${options.width}"`);
+  if (options.height)
+    attrs.push(`height="${options.height}"`);
+  if (options.class)
+    attrs.push(`class="${escapeAttr(options.class)}"`);
+  if (options.style)
+    attrs.push(`style="${escapeAttr(options.style)}"`);
+  if (options.id)
+    attrs.push(`id="${escapeAttr(options.id)}"`);
+  if (options.lazy !== !1)
+    attrs.push('loading="lazy"');
+  attrs.push('decoding="async"');
+  return `<img ${attrs.join(" ")} />`;
+}
+function escapeAttr(str) {
+  return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/'/g, "&#039;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export const imgDirective = createImgDirective();

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/editing.js

@@ -0,0 +1,193 @@
+export function buildImageUrl(src, params = {}) {
+  const queryParams = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null)
+      continue;
+    if (Array.isArray(value))
+      queryParams.push(`${key}=${encodeURIComponent(value.join(","))}`);
+    else if (typeof value === "boolean") {
+      if (value)
+        queryParams.push(`${key}=true`);
+    } else
+      queryParams.push(`${key}=${encodeURIComponent(String(value))}`);
+  }
+  if (queryParams.length === 0)
+    return src;
+  const separator = src.includes("?") ? "&" : "?";
+  return `${src}${separator}${queryParams.join("&")}`;
+}
+export function parseImageUrl(url) {
+  const questionIndex = url.indexOf("?");
+  if (questionIndex === -1)
+    return { src: url, params: {} };
+  const src = url.slice(0, questionIndex), queryString = url.slice(questionIndex + 1), params = {};
+  for (const pair of queryString.split("&")) {
+    const [key, rawValue] = pair.split("="), value = rawValue ? decodeURIComponent(rawValue) : "";
+    if (value === "true")
+      params[key] = !0;
+    else if (value === "false")
+      params[key] = !1;
+    else if (/^-?\d+$/.test(value))
+      params[key] = Number.parseInt(value, 10);
+    else if (/^-?\d+\.\d+$/.test(value))
+      params[key] = Number.parseFloat(value);
+    else if (value.includes(","))
+      params[key] = value.split(",");
+    else
+      params[key] = value;
+  }
+  return { src, params };
+}
+export function mergeParams(...paramSets) {
+  const result = {};
+  for (const params of paramSets)
+    if (params)
+      Object.assign(result, params);
+  return result;
+}
+export function resize(src, width, height, fit) {
+  const params = { w: width };
+  if (height)
+    params.h = height;
+  if (fit)
+    params.fit = fit;
+  return buildImageUrl(src, params);
+}
+export function crop(src, width, height, position = "center") {
+  return buildImageUrl(src, {
+    w: width,
+    h: height,
+    fit: "crop",
+    crop: position
+  });
+}
+export function thumbnail(src, size, cropPosition = "center") {
+  return buildImageUrl(src, {
+    w: size,
+    h: size,
+    fit: "crop",
+    crop: cropPosition
+  });
+}
+export function contain(src, maxWidth, maxHeight) {
+  return buildImageUrl(src, {
+    w: maxWidth,
+    h: maxHeight,
+    fit: "max"
+  });
+}
+export function cover(src, width, height) {
+  return buildImageUrl(src, {
+    w: width,
+    h: height,
+    fit: "crop"
+  });
+}
+export function blur(src, radius) {
+  return buildImageUrl(src, { blur: Math.min(2000, Math.max(0, radius)) });
+}
+export function sharpen(src, amount) {
+  return buildImageUrl(src, { sharp: Math.min(100, Math.max(0, amount)) });
+}
+export function grayscale(src) {
+  return buildImageUrl(src, { sat: -100 });
+}
+export function sepia(src, amount = 100) {
+  return buildImageUrl(src, { sepia: Math.min(100, Math.max(0, amount)) });
+}
+export function invert(src) {
+  return buildImageUrl(src, { invert: !0 });
+}
+export function brightness(src, amount) {
+  return buildImageUrl(src, { bri: Math.min(100, Math.max(-100, amount)) });
+}
+export function contrast(src, amount) {
+  return buildImageUrl(src, { con: Math.min(100, Math.max(-100, amount)) });
+}
+export function saturation(src, amount) {
+  return buildImageUrl(src, { sat: Math.min(100, Math.max(-100, amount)) });
+}
+export function rotate(src, degrees) {
+  return buildImageUrl(src, { rot: (degrees % 360 + 360) % 360 });
+}
+export function flipHorizontal(src) {
+  return buildImageUrl(src, { flip: "h" });
+}
+export function flipVertical(src) {
+  return buildImageUrl(src, { flip: "v" });
+}
+export function format(src, fmt, quality) {
+  const params = { fm: fmt };
+  if (quality !== void 0)
+    params.q = quality;
+  return buildImageUrl(src, params);
+}
+export function quality(src, q) {
+  return buildImageUrl(src, { q: Math.min(100, Math.max(1, q)) });
+}
+export function auto(src, enhancements = ["format", "compress"]) {
+  return buildImageUrl(src, { auto: enhancements });
+}
+export function watermark(src, markUrl, options = {}) {
+  return buildImageUrl(src, {
+    mark: markUrl,
+    markx: options.x,
+    marky: options.y,
+    markalpha: options.alpha,
+    markscale: options.scale,
+    markalign: options.align
+  });
+}
+export const PRESETS = {
+  web: { fm: "webp", q: 80, auto: ["format", "compress"] },
+  highQuality: { q: 95 },
+  thumb: { w: 150, h: 150, fit: "crop", crop: "center" },
+  avatar: { w: 200, h: 200, fit: "crop", crop: "faces" },
+  social: { w: 1200, h: 630, fit: "crop" },
+  preview: { w: 400, q: 70 },
+  placeholder: { w: 20, blur: 200, q: 20 }
+};
+export function applyPreset(src, preset, additionalParams) {
+  return buildImageUrl(src, mergeParams(PRESETS[preset], additionalParams));
+}
+export function srcsetUrls(src, widths, params) {
+  return widths.map((w) => buildImageUrl(src, { ...params, w }));
+}
+export function dprUrls(src, width, dprValues = [1, 2, 3], params) {
+  return dprValues.map((dpr) => buildImageUrl(src, { ...params, w: Math.round(width * dpr), dpr }));
+}
+export function validateParams(params) {
+  const errors = [];
+  if (params.w !== void 0 && (params.w < 1 || params.w > 16383))
+    errors.push("Width must be between 1 and 16383");
+  if (params.h !== void 0 && (params.h < 1 || params.h > 16383))
+    errors.push("Height must be between 1 and 16383");
+  if (params.q !== void 0 && (params.q < 1 || params.q > 100))
+    errors.push("Quality must be between 1 and 100");
+  if (params.blur !== void 0 && (params.blur < 0 || params.blur > 2000))
+    errors.push("Blur must be between 0 and 2000");
+  if (params.rot !== void 0 && (params.rot < 0 || params.rot > 359))
+    errors.push("Rotation must be between 0 and 359");
+  if (params.dpr !== void 0 && (params.dpr < 1 || params.dpr > 5))
+    errors.push("DPR must be between 1 and 5");
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+export function sanitizeParams(params) {
+  const sanitized = { ...params };
+  if (sanitized.w !== void 0)
+    sanitized.w = Math.min(16383, Math.max(1, sanitized.w));
+  if (sanitized.h !== void 0)
+    sanitized.h = Math.min(16383, Math.max(1, sanitized.h));
+  if (sanitized.q !== void 0)
+    sanitized.q = Math.min(100, Math.max(1, sanitized.q));
+  if (sanitized.blur !== void 0)
+    sanitized.blur = Math.min(2000, Math.max(0, sanitized.blur));
+  if (sanitized.rot !== void 0)
+    sanitized.rot = (sanitized.rot % 360 + 360) % 360;
+  if (sanitized.dpr !== void 0)
+    sanitized.dpr = Math.min(5, Math.max(1, sanitized.dpr));
+  return sanitized;
+}

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

@@ -0,0 +1,142 @@
+// Export types separately
+export type { ExtendedImageRenderContext } from './component';
+/**
+ * STX Media - Image Module
+ *
+ * Complete image optimization with responsive srcset, lazy loading,
+ * blur-up placeholders, and imgix-style URL transformations.
+ *
+ * @module media/image
+ */
+// =============================================================================
+// Component Exports
+// =============================================================================
+export {
+  // Main render function
+  renderImgComponent,
+  // Template parser
+  parseImgComponent,
+  processImgComponents,
+} from './component';
+// =============================================================================
+// Directive Exports
+// =============================================================================
+export {
+  // Directive factory
+  createImgDirective,
+  // Directive instance
+  imgDirective,
+} from './directive';
+// =============================================================================
+// Srcset Exports
+// =============================================================================
+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';
+// =============================================================================
+// Placeholder Exports
+// =============================================================================
+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';
+// =============================================================================
+// Editing API Exports
+// =============================================================================
+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';