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

package/dist/media/image/component.js

@@ -0,0 +1,574 @@
+import {
+  DEFAULT_FORMATS,
+  DEFAULT_WIDTHS,
+  generateSizesAttribute,
+  generateWidthSrcset,
+  generateDprSrcset,
+  getMimeType,
+  buildImageUrl
+} from "./srcset.js";
+import {
+  getCachedPlaceholder,
+  generatePlaceholderCSS,
+  BLUR_UP_CSS
+} from "./placeholder.js";
+async function getProcessor() {
+  try {
+    return await import("./processor/index.js");
+  } catch (error) {
+    if (!processorWarningLogged) {
+      console.warn("[stx-media] Image processor not available, some features disabled:", error);
+      processorWarningLogged = !0;
+    }
+    return null;
+  }
+}
+let processorWarningLogged = !1;
+const DEFAULT_QUALITY = 80, DEFAULT_DECODING = "async", DEFAULT_LOADING = "lazy";
+let cssInjected = !1;
+export async function renderImgComponent(props, context = {}) {
+  const extendedContext = context, enhancedProps = props;
+  if (enhancedProps.process && !enhancedProps.skipOptimization) {
+    if (extendedContext.tsImagesConfig?.enabled && !extendedContext.isDev)
+      return renderWithTsImages(enhancedProps, extendedContext);
+  }
+  if (extendedContext.processedResult?.processed)
+    return renderFromProcessedResult(props, extendedContext.processedResult, context);
+  if (extendedContext.responsiveVariants)
+    return renderFromResponsiveVariants(props, extendedContext.responsiveVariants, context);
+  const {
+    src,
+    alt,
+    width,
+    height,
+    sizes,
+    widths = DEFAULT_WIDTHS,
+    dpr,
+    formats = DEFAULT_FORMATS,
+    quality = DEFAULT_QUALITY,
+    params = {},
+    placeholder: placeholderStrategy = "none",
+    placeholderOptions = {},
+    lazy = !0,
+    priority = !1,
+    loading = priority ? "eager" : DEFAULT_LOADING,
+    decoding = DEFAULT_DECODING,
+    fetchpriority,
+    objectFit,
+    objectPosition,
+    crossorigin,
+    referrerpolicy
+  } = props, className = props.class, style = props.style, id = props.id, dataAttrs = props.data || {}, { isDev = !1, baseUrl = "" } = context;
+  if (isDev && !context.optimize)
+    return renderSimpleImg(props);
+  let placeholder, placeholderCss;
+  const componentId = id || `stx-img-${Math.random().toString(36).slice(2, 8)}`;
+  if (placeholderStrategy !== "none" && !priority)
+    try {
+      placeholder = await getCachedPlaceholder(src, {
+        strategy: placeholderStrategy,
+        ...placeholderOptions
+      });
+      placeholderCss = generatePlaceholderCSS(componentId, placeholder, placeholderOptions);
+    } catch {}
+  const usesDprSrcset = dpr !== void 0 && width !== void 0;
+  let html;
+  if (usesDprSrcset)
+    html = renderDprBasedImg(props, componentId, placeholder, context);
+  else
+    html = await renderPictureElement(props, componentId, placeholder, context);
+  let preloadLink;
+  if (priority) {
+    const fallbackFormat = formats.includes("webp") ? "webp" : formats[0], preloadSrcset = generateWidthSrcset(src, widths, { ...params, q: quality }, fallbackFormat), sizesAttr = typeof sizes === "object" ? generateSizesAttribute(sizes) : sizes || "100vw";
+    preloadLink = `<link rel="preload" as="image" imagesrcset="${preloadSrcset}" imagesizes="${sizesAttr}" />`;
+  }
+  const cssStyles = [];
+  if (!cssInjected && placeholderStrategy !== "none") {
+    cssStyles.push(BLUR_UP_CSS);
+    cssInjected = !0;
+  }
+  if (placeholderCss)
+    cssStyles.push(placeholderCss);
+  const script = lazy ? generateLazyLoadScript(componentId) : void 0;
+  return {
+    html,
+    preloadLink,
+    css: cssStyles.length > 0 ? cssStyles.join(`
+`) : void 0,
+    script
+  };
+}
+async function renderPictureElement(props, componentId, placeholder, context) {
+  const {
+    src,
+    alt,
+    width,
+    height,
+    sizes,
+    widths = DEFAULT_WIDTHS,
+    formats = DEFAULT_FORMATS,
+    quality = DEFAULT_QUALITY,
+    params = {},
+    lazy = !0,
+    priority = !1,
+    loading = priority ? "eager" : DEFAULT_LOADING,
+    decoding = DEFAULT_DECODING,
+    fetchpriority,
+    objectFit,
+    objectPosition,
+    crossorigin,
+    referrerpolicy
+  } = props, className = props.class, style = props.style, dataAttrs = props.data || {}, sizesAttr = typeof sizes === "object" ? generateSizesAttribute(sizes) : sizes || "100vw", sources = [];
+  for (const format of formats) {
+    const srcset = generateWidthSrcset(src, widths, { ...params, q: quality }, format), mimeType = getMimeType(format);
+    if (lazy && !priority)
+      sources.push(`  <source type="${mimeType}" data-srcset="${srcset}" data-sizes="${sizesAttr}" />`);
+    else
+      sources.push(`  <source type="${mimeType}" srcset="${srcset}" sizes="${sizesAttr}" />`);
+  }
+  const imgAttrs = buildImgAttributes({
+    src: buildImageUrl(src, { ...params, q: quality }),
+    alt,
+    width,
+    height,
+    loading: priority ? void 0 : loading,
+    decoding,
+    fetchpriority: priority ? "high" : fetchpriority,
+    objectFit,
+    objectPosition,
+    crossorigin,
+    referrerpolicy,
+    className: buildClassName(className, placeholder),
+    style: buildStyle(style, objectFit, objectPosition, placeholder),
+    lazy: lazy && !priority,
+    data: dataAttrs
+  });
+  let html;
+  if (placeholder) {
+    const wrapperStyle = `background-image: url('${placeholder.dataURL}'); background-size: cover; background-position: center;`;
+    html = `<div id="${componentId}" class="stx-img-placeholder" style="${wrapperStyle}">
+  <picture>
+${sources.join(`
+`)}
+    <img ${imgAttrs} />
+  </picture>
+</div>`;
+  } else
+    html = `<picture${componentId ? ` id="${componentId}"` : ""}>
+${sources.join(`
+`)}
+  <img ${imgAttrs} />
+</picture>`;
+  return html;
+}
+function renderDprBasedImg(props, componentId, placeholder, context) {
+  const {
+    src,
+    alt,
+    width,
+    height,
+    dpr = [1, 2, 3],
+    quality = DEFAULT_QUALITY,
+    params = {},
+    lazy = !0,
+    priority = !1,
+    loading = priority ? "eager" : DEFAULT_LOADING,
+    decoding = DEFAULT_DECODING,
+    fetchpriority,
+    objectFit,
+    objectPosition,
+    crossorigin,
+    referrerpolicy
+  } = props, className = props.class, style = props.style, dataAttrs = props.data || {}, numericWidth = typeof width === "number" ? width : Number.parseInt(String(width), 10), srcset = generateDprSrcset(src, numericWidth, dpr, { ...params, q: quality }), imgAttrs = buildImgAttributes({
+    src: buildImageUrl(src, { ...params, w: numericWidth, q: quality }),
+    alt,
+    width,
+    height,
+    loading: priority ? void 0 : loading,
+    decoding,
+    fetchpriority: priority ? "high" : fetchpriority,
+    objectFit,
+    objectPosition,
+    crossorigin,
+    referrerpolicy,
+    className: buildClassName(className, placeholder),
+    style: buildStyle(style, objectFit, objectPosition, placeholder),
+    lazy: lazy && !priority,
+    data: dataAttrs
+  }), srcsetAttr = lazy && !priority ? `data-srcset="${srcset}"` : `srcset="${srcset}"`;
+  if (placeholder) {
+    const wrapperStyle = `background-image: url('${placeholder.dataURL}'); background-size: cover; background-position: center;`;
+    return `<div id="${componentId}" class="stx-img-placeholder" style="${wrapperStyle}">
+  <img ${imgAttrs} ${srcsetAttr} />
+</div>`;
+  }
+  return `<img ${componentId ? `id="${componentId}" ` : ""}${imgAttrs} ${srcsetAttr} />`;
+}
+function renderSimpleImg(props) {
+  const {
+    src,
+    alt,
+    width,
+    height,
+    loading = DEFAULT_LOADING,
+    decoding = DEFAULT_DECODING,
+    fetchpriority,
+    objectFit,
+    objectPosition,
+    crossorigin,
+    referrerpolicy,
+    priority = !1
+  } = props, className = props.class, style = props.style, id = props.id, dataAttrs = props.data || {};
+  return {
+    html: `<img ${buildImgAttributes({
+      src,
+      alt,
+      width,
+      height,
+      loading: priority ? "eager" : loading,
+      decoding,
+      fetchpriority: priority ? "high" : fetchpriority,
+      objectFit,
+      objectPosition,
+      crossorigin,
+      referrerpolicy,
+      className,
+      style: buildStyle(style, objectFit, objectPosition),
+      id,
+      data: dataAttrs
+    })} />`
+  };
+}
+function buildImgAttributes(opts) {
+  const attrs = [];
+  if (opts.lazy) {
+    attrs.push(`data-src="${escapeAttr(opts.src)}"`);
+    attrs.push('src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"');
+  } else
+    attrs.push(`src="${escapeAttr(opts.src)}"`);
+  attrs.push(`alt="${escapeAttr(opts.alt)}"`);
+  if (opts.width)
+    attrs.push(`width="${opts.width}"`);
+  if (opts.height)
+    attrs.push(`height="${opts.height}"`);
+  if (opts.loading)
+    attrs.push(`loading="${opts.loading}"`);
+  if (opts.decoding)
+    attrs.push(`decoding="${opts.decoding}"`);
+  if (opts.fetchpriority)
+    attrs.push(`fetchpriority="${opts.fetchpriority}"`);
+  if (opts.crossorigin)
+    attrs.push(`crossorigin="${opts.crossorigin}"`);
+  if (opts.referrerpolicy)
+    attrs.push(`referrerpolicy="${opts.referrerpolicy}"`);
+  if (opts.className)
+    attrs.push(`class="${escapeAttr(opts.className)}"`);
+  if (opts.style)
+    attrs.push(`style="${escapeAttr(opts.style)}"`);
+  if (opts.id)
+    attrs.push(`id="${escapeAttr(opts.id)}"`);
+  if (opts.data)
+    for (const [key, value] of Object.entries(opts.data))
+      attrs.push(`data-${key}="${escapeAttr(value)}"`);
+  if (opts.lazy)
+    attrs.push("data-stx-lazy");
+  return attrs.join(" ");
+}
+function buildClassName(className, placeholder) {
+  const classes = [];
+  if (className)
+    classes.push(className);
+  if (placeholder)
+    classes.push("stx-img-blur");
+  return classes.join(" ") || "";
+}
+function buildStyle(style, objectFit, objectPosition, placeholder) {
+  const styles = [];
+  if (objectFit)
+    styles.push(`object-fit: ${objectFit}`);
+  if (objectPosition)
+    styles.push(`object-position: ${objectPosition}`);
+  if (placeholder)
+    styles.push("opacity: 0; transition: opacity 300ms ease-out");
+  if (style)
+    styles.push(style);
+  return styles.join("; ");
+}
+function escapeAttr(str) {
+  return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/'/g, "&#039;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function generateLazyLoadScript(componentId) {
+  return `
+(function() {
+  const container = document.getElementById('${componentId}');
+  if (!container) return;
+
+  const img = container.querySelector('img[data-stx-lazy]') || container;
+  if (!img.dataset.src && !img.dataset.srcset) return;
+
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        // Load image
+        if (img.dataset.src) img.src = img.dataset.src;
+        if (img.dataset.srcset) img.srcset = img.dataset.srcset;
+
+        // Load sources
+        const sources = container.querySelectorAll('source[data-srcset]');
+        sources.forEach(source => {
+          if (source.dataset.srcset) source.srcset = source.dataset.srcset;
+          if (source.dataset.sizes) source.sizes = source.dataset.sizes;
+        });
+
+        // Handle load completion
+        img.onload = () => {
+          img.style.opacity = '1';
+          if (container.classList.contains('stx-img-placeholder')) {
+            container.classList.add('stx-img-loaded');
+          }
+        };
+
+        observer.disconnect();
+      }
+    });
+  }, { rootMargin: '50px' });
+
+  observer.observe(container);
+})();
+`.trim();
+}
+export function parseImgComponent(content) {
+  const match = content.match(/<Img\s+([^>]*?)\/?>/);
+  if (!match)
+    return null;
+  const attrsStr = match[1], props = {}, attrRegex = /(:?)(\w+)(?:=(?:"([^"]*)"|'([^']*)'|\{([^}]+)\}))?/g;
+  let attrMatch;
+  while ((attrMatch = attrRegex.exec(attrsStr)) !== null) {
+    const [, binding, name, doubleQuoted, singleQuoted, braced] = attrMatch, value = doubleQuoted ?? singleQuoted ?? braced ?? !0;
+    if (binding === ":" && typeof value === "string")
+      try {
+        props[name] = JSON.parse(value);
+      } catch {
+        props[name] = value;
+      }
+    else
+      switch (name) {
+        case "src":
+          props.src = String(value);
+          break;
+        case "alt":
+          props.alt = String(value);
+          break;
+        case "width":
+          props.width = Number(value) || value;
+          break;
+        case "height":
+          props.height = Number(value) || value;
+          break;
+        case "sizes":
+          props.sizes = String(value);
+          break;
+        case "quality":
+          props.quality = Number(value);
+          break;
+        case "placeholder":
+          props.placeholder = value;
+          break;
+        case "lazy":
+          props.lazy = value === !0 || value === "true";
+          break;
+        case "priority":
+          props.priority = value === !0 || value === "true";
+          break;
+        case "class":
+          props.class = String(value);
+          break;
+        case "style":
+          props.style = String(value);
+          break;
+        case "id":
+          props.id = String(value);
+          break;
+        case "loading":
+          props.loading = value;
+          break;
+        case "decoding":
+          props.decoding = value;
+          break;
+        case "fetchpriority":
+          props.fetchpriority = value;
+          break;
+        case "objectFit":
+          props.objectFit = value;
+          break;
+        case "objectPosition":
+          props.objectPosition = String(value);
+          break;
+        case "crossorigin":
+          props.crossorigin = value;
+          break;
+      }
+  }
+  if (!props.src || !props.alt)
+    return null;
+  return props;
+}
+export async function processImgComponents(content, context = {}) {
+  const imgPattern = /<Img\s+[^>]*?\/?>/g, preloadLinks = [], styles = [], scripts = [];
+  let result = content;
+  const matches = [];
+  let match;
+  while ((match = imgPattern.exec(content)) !== null)
+    matches.push({ match: match[0], index: match.index });
+  for (let i = matches.length - 1;i >= 0; i--) {
+    const { match: imgTag } = matches[i], props = parseImgComponent(imgTag);
+    if (props) {
+      const renderResult = await renderImgComponent(props, context);
+      result = result.replace(imgTag, renderResult.html);
+      if (renderResult.preloadLink)
+        preloadLinks.push(renderResult.preloadLink);
+      if (renderResult.css)
+        styles.push(renderResult.css);
+      if (renderResult.script)
+        scripts.push(renderResult.script);
+    }
+  }
+  return { html: result, preloadLinks, styles, scripts };
+}
+async function renderWithTsImages(props, context) {
+  const processor = await getProcessor();
+  if (!processor)
+    return renderImgComponent({ ...props, process: !1 }, context);
+  const tsConfig = context.tsImagesConfig;
+  if (props.responsiveWidths && props.responsiveWidths.length > 0 || props.widths && props.widths.length > 0 || !props.width && !props.dpr) {
+    const variants = await processor.generateResponsiveVariants(props.src, props, tsConfig);
+    if (variants)
+      return renderFromResponsiveVariants(props, variants, context);
+  } else {
+    const processed = await processor.processImage(props.src, props, tsConfig);
+    if (processed.processed)
+      return renderFromProcessedResult(props, processed, context);
+  }
+  return renderImgComponent({ ...props, process: !1 }, context);
+}
+async function renderFromProcessedResult(props, processed, context) {
+  const {
+    alt,
+    width,
+    height,
+    lazy = !0,
+    priority = !1,
+    objectFit,
+    objectPosition,
+    crossorigin,
+    referrerpolicy
+  } = props, className = props.class, style = props.style, id = props.id || `stx-img-${Math.random().toString(36).slice(2, 8)}`, dataAttrs = props.data || {}, variants = processed.variants || [], fallbackVariant = variants.find((v) => v.format === "jpeg") || variants.find((v) => v.format === "webp") || variants[0], fallbackSrc = fallbackVariant?.url || props.src, srcset = variants.filter((v) => v.format === (fallbackVariant?.format || "jpeg")).map((v) => `${v.url} ${v.width}w`).join(", "), formatGroups = new Map;
+  for (const variant of variants) {
+    if (!formatGroups.has(variant.format))
+      formatGroups.set(variant.format, []);
+    formatGroups.get(variant.format).push(variant);
+  }
+  const sources = [], formatOrder = ["avif", "webp", "jpeg", "png"];
+  for (const format of formatOrder) {
+    const formatVariants = formatGroups.get(format);
+    if (formatVariants && formatVariants.length > 0) {
+      const formatSrcset = formatVariants.map((v) => `${v.url} ${v.width}w`).join(", "), mimeType = getMimeType(format);
+      if (lazy && !priority)
+        sources.push(`  <source type="${mimeType}" data-srcset="${formatSrcset}" />`);
+      else
+        sources.push(`  <source type="${mimeType}" srcset="${formatSrcset}" />`);
+    }
+  }
+  const imgAttrs = [];
+  if (lazy && !priority) {
+    imgAttrs.push(`data-src="${escapeAttr(fallbackSrc)}"`);
+    imgAttrs.push('src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"');
+    if (srcset)
+      imgAttrs.push(`data-srcset="${srcset}"`);
+  } else {
+    imgAttrs.push(`src="${escapeAttr(fallbackSrc)}"`);
+    if (srcset)
+      imgAttrs.push(`srcset="${srcset}"`);
+  }
+  imgAttrs.push(`alt="${escapeAttr(alt)}"`);
+  const imgWidth = width || processed.originalWidth, imgHeight = height || processed.originalHeight;
+  if (imgWidth)
+    imgAttrs.push(`width="${imgWidth}"`);
+  if (imgHeight)
+    imgAttrs.push(`height="${imgHeight}"`);
+  if (!priority)
+    imgAttrs.push(`loading="${lazy ? "lazy" : "eager"}"`);
+  imgAttrs.push('decoding="async"');
+  if (priority)
+    imgAttrs.push('fetchpriority="high"');
+  if (crossorigin)
+    imgAttrs.push(`crossorigin="${crossorigin}"`);
+  if (referrerpolicy)
+    imgAttrs.push(`referrerpolicy="${referrerpolicy}"`);
+  const styleProps = [];
+  if (objectFit)
+    styleProps.push(`object-fit: ${objectFit}`);
+  if (objectPosition)
+    styleProps.push(`object-position: ${objectPosition}`);
+  if (processed.placeholder && lazy)
+    styleProps.push("opacity: 0; transition: opacity 300ms ease-out");
+  if (style)
+    styleProps.push(style);
+  if (styleProps.length > 0)
+    imgAttrs.push(`style="${styleProps.join("; ")}"`);
+  const classNames = [];
+  if (className)
+    classNames.push(className);
+  if (processed.placeholder)
+    classNames.push("stx-img-blur");
+  if (classNames.length > 0)
+    imgAttrs.push(`class="${classNames.join(" ")}"`);
+  if (lazy && !priority)
+    imgAttrs.push("data-stx-lazy");
+  for (const [key, value] of Object.entries(dataAttrs))
+    imgAttrs.push(`data-${key}="${escapeAttr(value)}"`);
+  let html;
+  if (processed.placeholder || processed.dominantColor && props.useDominantColor) {
+    const bgStyle = processed.placeholder ? `background-image: url('${processed.placeholder}'); background-size: cover; background-position: center;` : `background-color: ${processed.dominantColor};`;
+    html = `<div id="${id}" class="stx-img-placeholder" style="${bgStyle}">
+  <picture>
+${sources.join(`
+`)}
+    <img ${imgAttrs.join(" ")} />
+  </picture>
+</div>`;
+  } else
+    html = `<picture${id ? ` id="${id}"` : ""}>
+${sources.join(`
+`)}
+  <img ${imgAttrs.join(" ")} />
+</picture>`;
+  const cssStyles = [];
+  if (processed.placeholder)
+    cssStyles.push(BLUR_UP_CSS);
+  const script = lazy ? generateLazyLoadScript(id) : void 0;
+  let preloadLink;
+  if (priority && srcset)
+    preloadLink = `<link rel="preload" as="image" imagesrcset="${srcset}" />`;
+  return {
+    html,
+    preloadLink,
+    css: cssStyles.length > 0 ? cssStyles.join(`
+`) : void 0,
+    script
+  };
+}
+async function renderFromResponsiveVariants(props, variants, context) {
+  const processed = {
+    src: variants.src,
+    processed: !0,
+    variants: [],
+    placeholder: variants.placeholder?.dataURL,
+    originalWidth: variants.placeholder?.width,
+    originalHeight: variants.placeholder?.height
+  };
+  for (const [format, formatVariants] of Object.entries(variants.byFormat))
+    if (formatVariants)
+      processed.variants.push(...formatVariants);
+  return renderFromProcessedResult(props, processed, context);
+}

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

@@ -0,0 +1,23 @@
+/**
+ * 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
+ */
+export declare function createImgDirective(): CustomDirective;
+/**
+ * The @img directive instance
+ */
+export declare const imgDirective: CustomDirective;