@shopware/cms-base-layer 1.5.1 → 2.1.0

package/app/helpers/html-to-vue/ast.ts

@@ -0,0 +1,106 @@
+/**
+ * Based on the https://github.com/HCESrl/html-to-vue
+ */
+// @ts-expect-error - html-to-ast has type definition issues with package.json exports
+import { parse } from "html-to-ast";
+import type { NodeObject } from "./getOptionsFromNode";
+
+type ASTNode = NodeObject | NodeObject[];
+
+type VisitCallback = (
+  node: unknown,
+  parent: NodeObject | null,
+  key: string | null,
+  index: number | undefined,
+) => void;
+
+type ExtraComponentConfig = {
+  conditions: (node: NodeObject) => boolean;
+  renderer?: unknown;
+};
+
+export type RectifyConfig = {
+  extraComponentsMap?: Record<string, ExtraComponentConfig>;
+};
+
+/**
+ * Visit each node in the AST - with callback (adapted from https://lihautan.com/manipulating-ast-with-javascript/)
+ * @param ast html-parse-stringify AST
+ * @param callback
+ */
+function _visitAST(ast: ASTNode, callback: VisitCallback): void {
+  function _visit(
+    node: unknown,
+    parent: NodeObject | null,
+    key: string | null,
+    index: number | undefined,
+  ): void {
+    callback(node, parent, key, index);
+    if (Array.isArray(node)) {
+      // node is an array
+      node.forEach((value, idx) => {
+        _visit(value, node as unknown as NodeObject, null, idx);
+      });
+    } else if (isNode(node)) {
+      const keys = Object.keys(node);
+      for (let i = 0; i < keys.length; i++) {
+        const childKey = keys[i];
+        if (childKey === undefined) continue;
+        const child = (node as Record<string, unknown>)[childKey];
+        if (Array.isArray(child)) {
+          for (let j = 0; j < child.length; j++) {
+            _visit(child[j], node, key, j);
+          }
+        } else if (isNode(child)) {
+          _visit(child, node, key, undefined);
+        }
+      }
+    }
+  }
+  _visit(ast, null, null, undefined);
+}
+
+/**
+ *
+ * @param node html-parse-stringify AST node
+ * @returns {boolean}
+ */
+export function isNode(node: unknown): node is NodeObject {
+  return (
+    typeof node === "object" &&
+    node !== null &&
+    typeof (node as NodeObject).type !== "undefined"
+  );
+}
+
+export function generateAST(html: string): ASTNode {
+  return parse(html) as ASTNode;
+}
+
+/**
+ * Converts ast html nodes in vue components
+ * @param ast
+ * @param config
+ * @returns {*}
+ */
+export function rectifyAST(ast: ASTNode, config: RectifyConfig): ASTNode {
+  const _ast = JSON.parse(JSON.stringify(ast)) as ASTNode;
+  const keys = config.extraComponentsMap
+    ? Object.keys(config.extraComponentsMap)
+    : [];
+  _visitAST(_ast, (node) => {
+    if (!isNode(node)) {
+      return;
+    }
+    // checking whether the AST has some components that has to become Vue Components
+    for (let i = 0; i < keys.length; i++) {
+      const currentKey = keys[i];
+      if (currentKey === undefined) continue;
+      const componentConfig = config.extraComponentsMap?.[currentKey];
+      if (componentConfig?.conditions(node)) {
+        node.name = currentKey;
+      }
+    }
+  });
+  return _ast;
+}

package/{helpers → app/helpers}/html-to-vue/getOptionsFromNode.ts

@@ -7,7 +7,7 @@ export type NodeObject = {
   content: string;
 };
 
-type Options = {
+export type Options = {
   align?: string;
   attrs: Record<string, string>;
   class?: string;

package/{helpers → app/helpers}/html-to-vue/renderToHtml.ts

@@ -3,17 +3,10 @@
  */
 
 import type { ComponentInternalInstance, h } from "vue";
-import { generateAST, rectifyAST } from "./ast";
-import { renderer } from "./renderer";
+import { type RectifyConfig, generateAST, rectifyAST } from "./ast";
+import { type RendererConfig, renderer } from "./renderer";
 
-type DefaultConfig = {
-  container: {
-    type: string;
-  };
-  extraComponentsMap: Record<string, unknown>;
-  renderAnyway: boolean;
-  textTransformer: (text: string) => string;
-};
+type DefaultConfig = RendererConfig;
 
 const defaultConfig: DefaultConfig = {
   container: {
@@ -33,7 +26,10 @@ export function renderHtml(
 ) {
   const mergedConfig = Object.assign(defaultConfig, config);
   const _ast = generateAST(html);
-  const _rectifiedAst = rectifyAST(_ast, config);
+  const rectifyConfig: RectifyConfig = {
+    extraComponentsMap: config.extraComponentsMap,
+  };
+  const _rectifiedAst = rectifyAST(_ast, rectifyConfig);
 
   return renderer(
     _rectifiedAst,

package/app/helpers/html-to-vue/renderer.ts

@@ -0,0 +1,116 @@
+/**
+ * Based on the https://github.com/HCESrl/html-to-vue
+ */
+
+import type { ComponentInternalInstance, VNode } from "vue";
+import { isNode } from "./ast";
+import type { NodeObject } from "./getOptionsFromNode";
+import { getOptionsFromNode } from "./getOptionsFromNode";
+
+type ASTNode = NodeObject | NodeObject[];
+
+type RawChildren = string | number | boolean | VNode;
+
+type ExtraComponentRenderer = (
+  node: NodeObject,
+  children: RawChildren[],
+  createElement: typeof import("vue").h,
+  context: ComponentInternalInstance | null,
+) => VNode;
+
+export type ExtraComponentConfig = {
+  conditions: (node: NodeObject) => boolean;
+  renderer: ExtraComponentRenderer;
+};
+
+export type RendererConfig = {
+  container: {
+    type: string;
+  };
+  extraComponentsMap: Record<string, ExtraComponentConfig>;
+  renderAnyway: boolean;
+  textTransformer: (text: string) => string;
+};
+
+function flattenChildren(
+  children: RawChildren | RawChildren[] | undefined,
+): RawChildren[] {
+  if (children === undefined) {
+    return [];
+  }
+  if (Array.isArray(children)) {
+    const result: RawChildren[] = [];
+    for (const child of children) {
+      if (child !== null && child !== undefined) {
+        if (Array.isArray(child)) {
+          result.push(...flattenChildren(child));
+        } else {
+          result.push(child);
+        }
+      }
+    }
+    return result;
+  }
+  return [children];
+}
+
+/**
+ * rendering the ast into vue render functions
+ * @param ast AST generated by html-parse-stringify
+ * @param config our configuration
+ * @param createElement vue's createElement
+ * @param context vue functional component context
+ * @param resolveUrl function to resolve URLs
+ */
+export function renderer(
+  ast: ASTNode,
+  config: RendererConfig,
+  createElement: typeof import("vue").h,
+  context: ComponentInternalInstance | null,
+  resolveUrl: (url: string) => string,
+): VNode {
+  function _render(
+    h: typeof createElement,
+    node: unknown,
+  ): RawChildren | RawChildren[] | undefined {
+    if (Array.isArray(node)) {
+      const nodes: RawChildren[] = [];
+      // node is an array
+      for (const subnode of node) {
+        const rendered = _render(h, subnode);
+        const flattened = flattenChildren(rendered);
+        nodes.push(...flattened);
+      }
+      return nodes;
+    }
+
+    if (isNode(node)) {
+      // node is either a node with children or a node or a text node
+      if (node.type === "text") {
+        return config.textTransformer(node.content); // return text
+      }
+      if (node.type === "tag") {
+        const transformedNode = getOptionsFromNode(node, resolveUrl);
+        const children: RawChildren[] = [];
+        for (const child of node.children) {
+          const rendered = _render(h, child);
+          const flattened = flattenChildren(rendered);
+          children.push(...flattened);
+        }
+        // if it's an extra component use custom renderer
+        const componentConfig = config.extraComponentsMap[node.name];
+        if (componentConfig !== undefined) {
+          return componentConfig.renderer(node, children, h, context);
+        }
+        // else, create normal html element
+        return h(node.name, transformedNode, [...children]);
+      }
+    }
+    return undefined;
+  }
+
+  const rendered = _render(createElement, ast);
+  const children = flattenChildren(rendered);
+
+  return createElement(config.container.type, context?.data || {}, children);
+}

package/app/plugins/unocss-runtime.client.ts

@@ -0,0 +1,23 @@
+import initUnocssRuntime from "@unocss/runtime";
+import { presetWind3 } from "unocss";
+import { defineNuxtPlugin, useAppConfig } from "#imports";
+import unoConfig from "../../uno.config";
+
+// Resolves UnoCSS utility classes at runtime via DOM MutationObserver.
+// Needed when CMS content contains dynamic classes not known at build time,
+// since extracting all CMS-used classes from the backend during build is impractical.
+// Trade-off: may cause layout shift as styles are applied after hydration.
+// Can be disabled via app.config.ts: { unocssRuntime: false }
+// When disabled, CMS classes unknown at build time won't be resolved —
+// add them to the UnoCSS safelist in uno.config.ts to ensure they are generated.
+export default defineNuxtPlugin(() => {
+  const appConfig = useAppConfig();
+  if (!appConfig.unocssRuntime) return;
+
+  initUnocssRuntime({
+    defaults: {
+      theme: unoConfig.theme,
+      presets: [presetWind3()],
+    },
+  });
+});

package/app/providers/shopware.test.ts

@@ -0,0 +1,213 @@
+import type { ImageCTX } from "@nuxt/image";
+import { describe, expect, it } from "vitest";
+import shopwareProvider from "./shopware";
+
+describe("Shopware Image Provider", () => {
+  const provider = shopwareProvider();
+  const mockContext: ImageCTX = {
+    options: {},
+  } as ImageCTX;
+
+  describe("basic functionality", () => {
+    it("should return original URL when no modifiers are provided", () => {
+      const result = provider.getImage(
+        "https://example.com/image.jpg",
+        { modifiers: {} },
+        mockContext,
+      );
+      expect(result.url).toBe("https://example.com/image.jpg");
+    });
+
+    it("should add width modifier to URL", () => {
+      const result = provider.getImage(
+        "https://example.com/image.jpg",
+        { modifiers: { width: 800 } },
+        mockContext,
+      );
+      expect(result.url).toBe("https://example.com/image.jpg?width=800");
+    });
+
+    it("should add height modifier to URL", () => {
+      const result = provider.getImage(
+        "https://example.com/image.jpg",
+        { modifiers: { height: 600 } },
+        mockContext,
+      );
+      expect(result.url).toBe("https://example.com/image.jpg?height=600");
+    });
+
+    it("should add multiple modifiers to URL", () => {
+      const result = provider.getImage(
+        "https://example.com/image.jpg",
+        {
+          modifiers: {
+            width: 800,
+            height: 600,
+            quality: 90,
+            format: "webp",
+            fit: "cover",
+          },
+        },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://example.com/image.jpg?width=800&height=600&quality=90&format=webp&fit=cover",
+      );
+    });
+  });
+
+  describe("existing query parameters", () => {
+    it("should append modifiers to existing query parameters", () => {
+      const result = provider.getImage(
+        "https://example.com/image.jpg?ts=123456",
+        { modifiers: { width: 800 } },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://example.com/image.jpg?ts=123456&width=800",
+      );
+    });
+
+    it("should handle multiple existing query parameters", () => {
+      const result = provider.getImage(
+        "https://example.com/image.jpg?ts=123456&v=2",
+        { modifiers: { width: 800, format: "webp" } },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://example.com/image.jpg?ts=123456&v=2&width=800&format=webp",
+      );
+    });
+  });
+
+  describe("special characters in URL", () => {
+    it("should encode commas in pathname", () => {
+      const result = provider.getImage(
+        "https://example.com/path/image, test.jpg",
+        { modifiers: { width: 800 } },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://example.com/path/image%2C%20test.jpg?width=800",
+      );
+    });
+
+    it("should encode spaces in pathname", () => {
+      const result = provider.getImage(
+        "https://example.com/path/image test.jpg",
+        { modifiers: { width: 800 } },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://example.com/path/image%20test.jpg?width=800",
+      );
+    });
+
+    it("should encode special characters in filename", () => {
+      const result = provider.getImage(
+        "https://cdn.shopware.store/media/ChatGPT Image 2 gru 2025, 14_08_58.png",
+        { modifiers: { height: 300, format: "webp" } },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://cdn.shopware.store/media/ChatGPT%20Image%202%20gru%202025%2C%2014_08_58.png?height=300&format=webp",
+      );
+    });
+
+    it("should handle already encoded URLs correctly", () => {
+      const result = provider.getImage(
+        "https://example.com/path/image%20test.jpg",
+        { modifiers: { width: 800 } },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://example.com/path/image%20test.jpg?width=800",
+      );
+    });
+
+    it("should encode parentheses in pathname", () => {
+      const result = provider.getImage(
+        "https://example.com/path/image (1).jpg",
+        { modifiers: { width: 800 } },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://example.com/path/image%20(1).jpg?width=800",
+      );
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle relative URLs gracefully", () => {
+      const result = provider.getImage(
+        "/media/image.jpg",
+        { modifiers: { width: 800 } },
+        mockContext,
+      );
+      // Relative URLs cannot be parsed as URL objects, so they are returned as-is with modifiers
+      expect(result.url).toBe("/media/image.jpg?width=800");
+    });
+
+    it("should preserve existing query parameters with special characters", () => {
+      const result = provider.getImage(
+        "https://example.com/image.jpg?ts=123456&key=value",
+        { modifiers: { width: 800 } },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://example.com/image.jpg?ts=123456&key=value&width=800",
+      );
+    });
+
+    it("should handle URLs with fragments", () => {
+      const result = provider.getImage(
+        "https://example.com/image.jpg#section",
+        { modifiers: { width: 800 } },
+        mockContext,
+      );
+      // Note: URL constructor places hash after query params
+      expect(result.url).toBe(
+        "https://example.com/image.jpg#section?width=800",
+      );
+    });
+
+    it("should not double-encode already encoded characters", () => {
+      const result = provider.getImage(
+        "https://example.com/path/image%2Ctest.jpg",
+        { modifiers: { width: 800 } },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://example.com/path/image%2Ctest.jpg?width=800",
+      );
+    });
+  });
+
+  describe("Shopware CDN URLs", () => {
+    it("should handle Shopware CDN URLs with existing query parameters", () => {
+      const result = provider.getImage(
+        "https://cdn.shopware.store/a/B/m/pPkDE/media/51/69/bf/1764680961/image.png?width=280&ts=1764680961",
+        {
+          modifiers: { height: 300, format: "webp", quality: 90, fit: "cover" },
+        },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://cdn.shopware.store/a/B/m/pPkDE/media/51/69/bf/1764680961/image.png?width=280&ts=1764680961&height=300&quality=90&format=webp&fit=cover",
+      );
+    });
+
+    it("should properly encode commas in Shopware CDN URLs", () => {
+      const result = provider.getImage(
+        "https://cdn.shopware.store/a/B/m/pPkDE/media/51/69/bf/1764680961/ChatGPT Image 2 gru 2025, 14_08_58.png?width=280&ts=1764680961",
+        {
+          modifiers: { height: 300, format: "webp", quality: 90, fit: "cover" },
+        },
+        mockContext,
+      );
+      expect(result.url).toBe(
+        "https://cdn.shopware.store/a/B/m/pPkDE/media/51/69/bf/1764680961/ChatGPT%20Image%202%20gru%202025%2C%2014_08_58.png?width=280&ts=1764680961&height=300&quality=90&format=webp&fit=cover",
+      );
+    });
+  });
+});

package/app/providers/shopware.ts

@@ -0,0 +1,107 @@
+import { defineProvider } from "@nuxt/image/runtime";
+import { encodeUrlPath } from "@shopware/helpers";
+
+/**
+ * Shopware Image Provider for Nuxt Image
+ *
+ * Generates optimized image URLs compatible with Shopware's remote thumbnail generation feature.
+ * This provider appends transformation parameters as query strings to image URLs, which are then
+ * processed by your configured image transformation backend.
+ *
+ * @remarks
+ * Shopware has built-in thumbnail generation (using GD2 or ImageMagick) that creates predefined
+ * sizes (400x400, 800x800, 1920x1920) during upload. However, for **on-the-fly transformations**
+ * via query parameters (like `?width=800`), you need to configure remote thumbnail generation:
+ * - Shopware Cloud: Uses Fastly CDN (configured automatically)
+ * - Self-hosted: Requires external middleware (Thumbor, Sharp, imgproxy) or plugins like FroshPlatformThumbnailProcessor
+ *
+ * Without remote thumbnail generation, query parameters will have no effect and original/predefined thumbnails are served
+ *
+ * @param src - The source image URL (e.g., "/media/image/product.jpg")
+ * @param options - Configuration options
+ * @param options.modifiers - Image transformation modifiers
+ * @param options.modifiers.width - Target width in pixels
+ * @param options.modifiers.height - Target height in pixels
+ * @param options.modifiers.quality - Image quality (0-100)
+ * @param options.modifiers.format - Output format (jpg, png, webp, avif)
+ * @param options.modifiers.fit - Resize mode (cover, contain, crop, bounds, crop_center)
+ *
+ * @returns Object containing the transformed image URL with query parameters
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = getImage('/media/image/product.jpg', {
+ *   modifiers: {
+ *     width: 800,
+ *     height: 600,
+ *     quality: 85,
+ *     format: 'webp',
+ *     fit: 'cover'
+ *   }
+ * });
+ * // Returns: { url: '/media/image/product.jpg?width=800&height=600&quality=85&format=webp&fit=cover' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With existing query parameters
+ * const result = getImage('/media/image/product.jpg?v=123', {
+ *   modifiers: { width: 400 }
+ * });
+ * // Returns: { url: '/media/image/product.jpg?v=123&width=400' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // No modifiers - returns original URL
+ * const result = getImage('/media/image/product.jpg');
+ * // Returns: { url: '/media/image/product.jpg' }
+ * ```
+ *
+ * @see {@link https://developer.shopware.com/docs/guides/plugins/plugins/content/media/remote-thumbnail-generation.html | Shopware Remote Thumbnail Generation}
+ * @see {@link https://image.nuxt.com/providers/custom | Nuxt Image Custom Providers}
+ */
+
+export default defineProvider(() => ({
+  getImage(src, { modifiers }, _ctx) {
+    // Encode special characters in the URL pathname (commas, spaces, etc.)
+    const encodedSrc = encodeUrlPath(src);
+
+    const params = new URLSearchParams();
+
+    // Map Nuxt Image modifiers to Shopware query parameters
+    if (modifiers.width) {
+      params.set("width", String(modifiers.width));
+    }
+
+    if (modifiers.height) {
+      params.set("height", String(modifiers.height));
+    }
+
+    if (modifiers.quality) {
+      params.set("quality", String(modifiers.quality));
+    }
+
+    if (modifiers.format) {
+      params.set("format", String(modifiers.format));
+    }
+
+    if (modifiers.fit) {
+      params.set("fit", String(modifiers.fit));
+    }
+
+    const query = params.toString();
+
+    if (!query) {
+      return { url: encodedSrc };
+    }
+
+    // Check if URL already has query parameters
+    const separator = encodedSrc.includes("?") ? "&" : "?";
+
+    return {
+      url: `${encodedSrc}${separator}${query}`,
+    };
+  },
+}));

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { NuxtModule } from '@nuxt/schema';
+import * as _nuxt_schema from '@nuxt/schema';
 
-declare const nuxtModule: NuxtModule;
+declare const _default: _nuxt_schema.NuxtModule<_nuxt_schema.ModuleOptions, _nuxt_schema.ModuleOptions, false>;
 
-export { nuxtModule as default };
+export { _default as default };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { NuxtModule } from '@nuxt/schema';
+import * as _nuxt_schema from '@nuxt/schema';
 
-declare const nuxtModule: NuxtModule;
+declare const _default: _nuxt_schema.NuxtModule<_nuxt_schema.ModuleOptions, _nuxt_schema.ModuleOptions, false>;
 
-export { nuxtModule as default };
+export { _default as default };

package/dist/index.mjs

@@ -10,7 +10,7 @@ import __cjs_mod__ from 'module';
 const __filename = __cjs_url__.fileURLToPath(import.meta.url);
 const __dirname = __cjs_path__.dirname(__filename);
 const require = __cjs_mod__.createRequire(import.meta.url);
-const nuxtModule = defineNuxtModule({
+const index = defineNuxtModule({
   meta: {
     name: "@shopware/cms-base",
     configKey: "shopware-cms"
@@ -28,4 +28,4 @@ const nuxtModule = defineNuxtModule({
   }
 });
 
-export { nuxtModule as default };
+export { index as default };

package/index.d.ts

@@ -0,0 +1,36 @@
+/// <reference types="@nuxt/schema" />
+
+export * from "@shopware/composables";
+export * from "./.nuxt/imports";
+
+declare module "nuxt/schema" {
+  interface AppConfig {
+    /** Placeholder shown while CMS images are loading */
+    imagePlaceholder?: {
+      /** CSS color value for the placeholder background */
+      color?: string;
+    };
+    /** CDN optimization options applied to CMS background images and synthetic srcsets */
+    backgroundImage?: {
+      /** Output format passed to the CDN (e.g. "webp", "avif") */
+      format?: string;
+      /** Image quality 1-100 passed to the CDN */
+      quality?: number;
+    };
+    /**
+     * Maps CMS block slot count to a responsive `sizes` attribute value.
+     * Used by CmsGenericBlock to provide sizing hints to child image elements.
+     * @example
+     * ```ts
+     * imageSizes: {
+     *   1: "(max-width: 768px) 100vw, 100vw",
+     *   2: "(max-width: 768px) 100vw, 50vw",
+     *   default: "(max-width: 768px) 50vw, 25vw",
+     * }
+     * ```
+     */
+    imageSizes?: Record<string | number, string>;
+    /** Enable UnoCSS runtime for dynamic class generation */
+    unocssRuntime?: boolean;
+  }
+}