@shopware/cms-base-layer 4.0.0 → 4.1.0

package/app/helpers/cms/getAppRendererLayout.test.ts

@@ -0,0 +1,93 @@
+import type { CmsBlockAppRenderer } from "@shopware/composables";
+import { describe, expect, it } from "vitest";
+
+import { getAppRendererLayout } from "./getAppRendererLayout";
+
+const block = (
+  customFields: CmsBlockAppRenderer["customFields"],
+  slots: string[] = [],
+) =>
+  ({
+    type: "app-renderer",
+    customFields,
+    slots: slots.map((slot) => ({ id: slot, slot, type: slot.split("-")[0] })),
+  }) as unknown as CmsBlockAppRenderer;
+
+describe("getAppRendererLayout", () => {
+  it("reads the app block name and grid", () => {
+    const layout = getAppRendererLayout(
+      block({
+        appBlockName: "swag-two-columns",
+        slotLayout: { grid: "auto / auto auto" },
+      }),
+    );
+
+    expect(layout.appBlockName).toBe("swag-two-columns");
+    expect(layout.grid).toBe("auto / auto auto");
+  });
+
+  it.each([
+    ["swag-two-columns", "CmsBlockAppRendererSwagTwoColumns"],
+    ["SwagTwoColumns", "CmsBlockAppRendererSwagTwoColumns"],
+    ["swag_two_columns", "CmsBlockAppRendererSwagTwoColumns"],
+  ])(
+    "derives the override component name from %s",
+    (appBlockName, expected) => {
+      expect(getAppRendererLayout(block({ appBlockName })).componentName).toBe(
+        expected,
+      );
+    },
+  );
+
+  it("has no override component and no grid without custom fields", () => {
+    const layout = getAppRendererLayout(block(null));
+
+    expect(layout.appBlockName).toBe("");
+    expect(layout.componentName).toBeUndefined();
+    expect(layout.grid).toBeUndefined();
+  });
+
+  it("restores the declared order from the name-sorted Store API order", () => {
+    const layout = getAppRendererLayout(
+      block({ appBlockName: "swag" }, [
+        "image-1",
+        "image-3",
+        "text-0",
+        "text-10",
+        "text-2",
+      ]),
+    );
+
+    expect(layout.slots.map((slot) => slot.slot)).toEqual([
+      "text-0",
+      "image-1",
+      "text-2",
+      "image-3",
+      "text-10",
+    ]);
+  });
+
+  it("keeps slots without an index after the indexed ones, in their order", () => {
+    const layout = getAppRendererLayout(
+      block({ appBlockName: "swag" }, ["content", "text-1", "left", "text-0"]),
+    );
+
+    expect(layout.slots.map((slot) => slot.slot)).toEqual([
+      "text-0",
+      "text-1",
+      "content",
+      "left",
+    ]);
+  });
+
+  it("does not reorder the block's own slots", () => {
+    const content = block({ appBlockName: "swag" }, ["text-1", "text-0"]);
+
+    getAppRendererLayout(content);
+
+    expect(content.slots.map((slot) => slot.slot)).toEqual([
+      "text-1",
+      "text-0",
+    ]);
+  });
+});

package/app/helpers/cms/getAppRendererLayout.ts

@@ -0,0 +1,36 @@
+import type { CmsBlockAppRenderer } from "@shopware/composables";
+import { pascalCase } from "scule";
+
+type AppRendererSlot = CmsBlockAppRenderer["slots"][number];
+
+export type AppRendererLayout = {
+  appBlockName: string;
+  componentName?: string;
+  grid?: string;
+  slots: AppRendererSlot[];
+};
+
+const SLOT_INDEX = /-(\d+)$/;
+
+function getSlotIndex(slot: AppRendererSlot): number {
+  const match = SLOT_INDEX.exec(slot.slot ?? "");
+
+  return match ? Number(match[1]) : Number.MAX_SAFE_INTEGER;
+}
+
+export function getAppRendererLayout(
+  block: CmsBlockAppRenderer,
+): AppRendererLayout {
+  const appBlockName = block.customFields?.appBlockName ?? "";
+
+  return {
+    appBlockName,
+    componentName: appBlockName
+      ? pascalCase(`CmsBlockAppRenderer-${appBlockName}`)
+      : undefined,
+    grid: block.customFields?.slotLayout?.grid || undefined,
+    slots: [...(block.slots ?? [])].sort(
+      (a, b) => getSlotIndex(a) - getSlotIndex(b),
+    ),
+  };
+}

package/app/helpers/cms/getCategoryNameContent.test.ts

@@ -0,0 +1,57 @@
+import type { CmsElementCategoryName } from "@shopware/composables";
+import { describe, expect, it } from "vitest";
+
+import { getCategoryNameContent } from "./getCategoryNameContent";
+
+const element = (source: "static" | "mapped", content: string | null) =>
+  ({
+    type: "category-name",
+    config: {
+      content: {
+        source,
+        value: source === "mapped" ? "category.name" : "<p>static</p>",
+      },
+    },
+    data: { content, apiAlias: "cms_text" },
+  }) as unknown as CmsElementCategoryName;
+
+describe("getCategoryNameContent", () => {
+  it("wraps mapped content in the page headline", () => {
+    expect(getCategoryNameContent(element("mapped", "Clothing"))).toBe(
+      '<h1 class="cms-element-category-name-headline">Clothing</h1>',
+    );
+  });
+
+  it("keeps entities the backend sanitizer produced", () => {
+    expect(getCategoryNameContent(element("mapped", "Shoes &amp; Bags"))).toBe(
+      '<h1 class="cms-element-category-name-headline">Shoes &amp; Bags</h1>',
+    );
+  });
+
+  it("returns static content as authored", () => {
+    expect(
+      getCategoryNameContent(element("static", "<h2>Our <b>range</b></h2>")),
+    ).toBe("<h2>Our <b>range</b></h2>");
+  });
+
+  it("renders no empty headline when the mapped value did not resolve", () => {
+    expect(getCategoryNameContent(element("mapped", null))).toBe("");
+    expect(getCategoryNameContent(element("mapped", ""))).toBe("");
+  });
+
+  it("renders no headline around a mapping path the backend returned", () => {
+    const leakedPath = {
+      type: "category-name",
+      config: {
+        content: { source: "mapped", value: "category.customFields" },
+      },
+      data: { content: "category.customFields", apiAlias: "cms_text" },
+    } as unknown as CmsElementCategoryName;
+
+    expect(getCategoryNameContent(leakedPath)).toBe("");
+  });
+
+  it("returns nothing for static content that did not resolve", () => {
+    expect(getCategoryNameContent(element("static", null))).toBe("");
+  });
+});

package/app/helpers/cms/getCategoryNameContent.ts

@@ -0,0 +1,15 @@
+import type { CmsElementCategoryName } from "@shopware/composables";
+
+import { getTextElementContent } from "./getTextElementContent";
+
+export function getCategoryNameContent(
+  element: CmsElementCategoryName,
+): string {
+  const content = getTextElementContent(element);
+
+  if (!content || element.config?.content?.source !== "mapped") {
+    return content;
+  }
+
+  return `<h1 class="cms-element-category-name-headline">${content}</h1>`;
+}

package/app/helpers/cms/getTextElementContent.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { getTextElementContent } from "./getTextElementContent";
+
+const element = (
+  source: "static" | "mapped",
+  value: string,
+  data: { content: string | null } | null,
+) => ({ config: { content: { source, value } }, data });
+
+describe("getTextElementContent", () => {
+  it("renders the content the backend resolved", () => {
+    expect(
+      getTextElementContent(
+        element("static", "<p>{{ category.name }}</p>", {
+          content: "<p>Clothing</p>",
+        }),
+      ),
+    ).toBe("<p>Clothing</p>");
+    expect(
+      getTextElementContent(
+        element("mapped", "category.name", { content: "Clothing" }),
+      ),
+    ).toBe("Clothing");
+  });
+
+  it("does not fall back to the unsanitized config when the backend sanitized the content away", () => {
+    expect(
+      getTextElementContent(
+        element("static", "<script>alert(1)</script>", { content: "" }),
+      ),
+    ).toBe("");
+  });
+
+  it("does not render a placeholder that resolved to nothing", () => {
+    expect(
+      getTextElementContent(
+        element("static", "{{ category.description }}", { content: "" }),
+      ),
+    ).toBe("");
+    expect(
+      getTextElementContent(
+        element("static", "{{ category.description }}", { content: null }),
+      ),
+    ).toBe("");
+  });
+
+  it("does not render a mapping path", () => {
+    expect(
+      getTextElementContent(
+        element("mapped", "category.name", { content: null }),
+      ),
+    ).toBe("");
+    expect(
+      getTextElementContent(
+        element("mapped", "category.customFields", {
+          content: "category.customFields",
+        }),
+      ),
+    ).toBe("");
+  });
+
+  it("renders static config for an element without data", () => {
+    expect(getTextElementContent(element("static", "<p>Hi</p>", null))).toBe(
+      "<p>Hi</p>",
+    );
+    expect(
+      getTextElementContent(element("mapped", "category.name", null)),
+    ).toBe("");
+  });
+
+  it("renders nothing for a missing element or config", () => {
+    expect(getTextElementContent(undefined)).toBe("");
+    expect(getTextElementContent({ config: null, data: null })).toBe("");
+    expect(getTextElementContent({ data: { content: "<p>x</p>" } })).toBe(
+      "<p>x</p>",
+    );
+  });
+});

package/app/helpers/cms/getTextElementContent.ts

@@ -0,0 +1,37 @@
+type TextElementLike = {
+  config?: {
+    content?: { source?: string; value?: unknown } | null;
+  } | null;
+  data?: { content?: string | null } | null;
+};
+
+/**
+ * The HTML a text-like element (`text`, `product-name`, `category-name`)
+ * renders.
+ *
+ * Once the Store API resolved the slot, `data.content` is the only source: the
+ * backend sanitized it, `config.content.value` is the raw input. The config is
+ * read only for an element without `data`, which the API never sends but a
+ * hand-built element may.
+ */
+export function getTextElementContent(
+  element: TextElementLike | null | undefined,
+): string {
+  const config = element?.config?.content;
+
+  if (!element?.data) {
+    return config?.source !== "mapped" && typeof config?.value === "string"
+      ? config.value
+      : "";
+  }
+
+  const content = element.data.content ?? "";
+
+  // The backend answers a mapping to a value that is not a string (an entity,
+  // an array) with the mapping path itself, e.g. `category.customFields`.
+  if (config?.source === "mapped" && content === config.value) {
+    return "";
+  }
+
+  return content;
+}

package/app/helpers/cms/getVideoElementOptions.test.ts

@@ -0,0 +1,384 @@
+import type { CmsElementVideo } from "@shopware/composables";
+import { describe, expect, it } from "vitest";
+
+import {
+  getVideoAttributes,
+  getVideoElementOptions,
+  getVideoToggleAttributes,
+} from "./getVideoElementOptions";
+import type { VideoElementOptions } from "./getVideoElementOptions";
+
+type Config = Partial<Record<keyof CmsElementVideo["config"], unknown>>;
+
+const media = {
+  url: "https://shop.test/media/intro.mp4",
+  mimeType: "video/mp4",
+  alt: "Alt",
+  title: "Title",
+  translated: { alt: "Translated alt", title: "Translated title" },
+  extensions: {
+    videoCoverMedia: { url: "https://shop.test/media/intro-cover.jpg" },
+  },
+};
+
+const element = (
+  config: Config = {},
+  data: Partial<CmsElementVideo["data"]> = {},
+) =>
+  ({
+    type: "video",
+    config: Object.fromEntries(
+      Object.entries(config).map(([key, value]) => [
+        key,
+        { source: "static", value },
+      ]),
+    ),
+    data: {
+      apiAlias: "cms_video",
+      media,
+      ariaLabel: "ariaLabel" in config ? String(config.ariaLabel ?? "") : null,
+      ...data,
+    },
+  }) as unknown as CmsElementVideo;
+
+const withMedia = (overrides: Record<string, unknown>) => ({
+  media: { ...media, ...overrides } as CmsElementVideo["data"]["media"],
+});
+
+describe("getVideoElementOptions", () => {
+  describe("media", () => {
+    it("plays the resolved media", () => {
+      const options = getVideoElementOptions(element());
+
+      expect(options.src).toBe("https://shop.test/media/intro.mp4");
+      expect(options.mimeType).toBe("video/mp4");
+      expect(options.preload).toBe("auto");
+    });
+
+    it("has no source when no media resolved", () => {
+      expect(
+        getVideoElementOptions(element({}, { media: null })).src,
+      ).toBeUndefined();
+    });
+  });
+
+  describe("displayMode", () => {
+    it.each(["standard", "stretch", "cover"])("accepts %s", (displayMode) => {
+      expect(getVideoElementOptions(element({ displayMode })).displayMode).toBe(
+        displayMode,
+      );
+    });
+
+    it("falls back to standard for a missing or unknown value", () => {
+      expect(getVideoElementOptions(element()).displayMode).toBe("standard");
+      expect(
+        getVideoElementOptions(element({ displayMode: "contain" })).displayMode,
+      ).toBe("standard");
+    });
+
+    it("applies the minimum height to cover only", () => {
+      expect(
+        getVideoElementOptions(
+          element({ displayMode: "cover", minHeight: "400px" }),
+        ).minHeight,
+      ).toBe("400px");
+      expect(
+        getVideoElementOptions(
+          element({ displayMode: "standard", minHeight: "400px" }),
+        ).minHeight,
+      ).toBeUndefined();
+    });
+  });
+
+  describe("alignment", () => {
+    it("reads both alignments", () => {
+      const options = getVideoElementOptions(
+        element({ verticalAlign: "flex-end", horizontalAlign: "center" }),
+      );
+
+      expect(options.verticalAlign).toBe("flex-end");
+      expect(options.horizontalAlign).toBe("center");
+    });
+
+    it("ignores both alignments for cover, which fills the element", () => {
+      const options = getVideoElementOptions(
+        element({
+          displayMode: "cover",
+          verticalAlign: "flex-end",
+          horizontalAlign: "center",
+        }),
+      );
+
+      expect(options.verticalAlign).toBeUndefined();
+      expect(options.horizontalAlign).toBeUndefined();
+    });
+
+    it("drops an empty or unknown alignment", () => {
+      const options = getVideoElementOptions(
+        element({ verticalAlign: "", horizontalAlign: "left" }),
+      );
+
+      expect(options.verticalAlign).toBeUndefined();
+      expect(options.horizontalAlign).toBeUndefined();
+    });
+  });
+
+  describe("playback", () => {
+    const switchesOf = ({
+      muted,
+      loop,
+      playsInline,
+      controls,
+    }: VideoElementOptions) => ({ muted, loop, playsInline, controls });
+
+    it.each([
+      ["muted", "muted"],
+      ["loop", "loop"],
+      ["playsInline", "playsInline"],
+      ["showControls", "controls"],
+    ] as const)("maps %s to %s and nothing else", (configKey, optionKey) => {
+      expect(
+        switchesOf(getVideoElementOptions(element({ [configKey]: true }))),
+      ).toEqual({
+        muted: false,
+        loop: false,
+        playsInline: false,
+        controls: false,
+        [optionKey]: true,
+      });
+    });
+
+    it("leaves every switch off when it is not configured", () => {
+      expect(getVideoElementOptions(element())).toMatchObject({
+        autoplay: false,
+        muted: false,
+        loop: false,
+        playsInline: false,
+        controls: false,
+      });
+    });
+
+    it("mutes an autoplaying video", () => {
+      expect(
+        getVideoElementOptions(element({ autoPlay: true, muted: false })),
+      ).toMatchObject({ autoplay: true, muted: true });
+    });
+  });
+
+  describe("load only after confirmation", () => {
+    it("shows the cover, loads nothing up front and does not autoplay", () => {
+      expect(
+        getVideoElementOptions(element({ showCover: true, autoPlay: true })),
+      ).toMatchObject({
+        poster: "https://shop.test/media/intro-cover.jpg",
+        preload: "none",
+        autoplay: false,
+        muted: false,
+      });
+    });
+
+    it("waits for the visitor even when the video has no cover", () => {
+      const options = getVideoElementOptions(
+        element({ showCover: true }, withMedia({ extensions: {} })),
+      );
+
+      expect(options.poster).toBeUndefined();
+      expect(options.preload).toBe("none");
+    });
+
+    it("does not use the cover without the option", () => {
+      expect(getVideoElementOptions(element()).poster).toBeUndefined();
+    });
+
+    it("reserves a 16:9 box for a stretched video without a cover", () => {
+      expect(
+        getVideoElementOptions(
+          element(
+            { showCover: true, displayMode: "stretch" },
+            withMedia({ extensions: {} }),
+          ),
+        ).placeholderAspectRatio,
+      ).toBe("auto 16 / 9");
+    });
+
+    it.each([
+      ["the cover sizes it", { showCover: true, displayMode: "stretch" }, {}],
+      [
+        "it is a standard video",
+        { showCover: true, displayMode: "standard" },
+        withMedia({ extensions: {} }),
+      ],
+      [
+        "it covers the element",
+        { showCover: true, displayMode: "cover" },
+        withMedia({ extensions: {} }),
+      ],
+      [
+        "its metadata preloads",
+        { displayMode: "stretch" },
+        withMedia({ extensions: {} }),
+      ],
+    ])("reserves no box when %s", (_, config, data) => {
+      expect(
+        getVideoElementOptions(element(config, data)).placeholderAspectRatio,
+      ).toBeUndefined();
+    });
+  });
+
+  describe("accessible name", () => {
+    it("uses the screen reader title", () => {
+      const options = getVideoElementOptions(
+        element({ ariaLabel: " Product demo " }),
+      );
+
+      expect(options.ariaLabel).toBe("Product demo");
+      expect(options.title).toBe("Product demo");
+    });
+
+    it("falls back to the media alt text and title", () => {
+      const options = getVideoElementOptions(element({ ariaLabel: null }));
+
+      expect(options.ariaLabel).toBe("Translated alt");
+      expect(options.title).toBe("Translated title");
+    });
+
+    it("trims the media alt text and title", () => {
+      const options = getVideoElementOptions(
+        element(
+          {},
+          withMedia({ translated: { alt: "  Alt  ", title: " Title " } }),
+        ),
+      );
+
+      expect(options.ariaLabel).toBe("Alt");
+      expect(options.title).toBe("Title");
+    });
+
+    it("has no name when nothing provides one", () => {
+      const options = getVideoElementOptions(
+        element(
+          { ariaLabel: "  " },
+          withMedia({
+            alt: "",
+            title: "",
+            translated: { alt: " ", title: "" },
+          }),
+        ),
+      );
+
+      expect(options.ariaLabel).toBeUndefined();
+      expect(options.title).toBeUndefined();
+    });
+
+    it("ignores a mapped screen reader title, which arrives as the mapping path", () => {
+      const mapped = element({}, { ariaLabel: "media.title" });
+      mapped.config.ariaLabel = { source: "mapped", value: "media.title" };
+
+      expect(getVideoElementOptions(mapped).ariaLabel).toBe("Translated alt");
+    });
+  });
+});
+
+describe("getVideoAttributes", () => {
+  it("renders no playsinline attribute when inline playback is off", () => {
+    expect(
+      getVideoAttributes(getVideoElementOptions(element())).playsinline,
+    ).toBeUndefined();
+    expect(
+      getVideoAttributes(getVideoElementOptions(element({ playsInline: true })))
+        .playsinline,
+    ).toBe(true);
+  });
+
+  it("passes the options on to the video", () => {
+    expect(
+      getVideoAttributes(
+        getVideoElementOptions(
+          element({ autoPlay: true, loop: true, ariaLabel: "Product demo" }),
+        ),
+      ),
+    ).toEqual({
+      preload: "auto",
+      poster: undefined,
+      autoplay: true,
+      muted: true,
+      loop: true,
+      playsinline: undefined,
+      controls: false,
+      "aria-label": "Product demo",
+      title: "Product demo",
+    });
+  });
+});
+
+describe("getVideoToggleAttributes", () => {
+  const labels = {
+    playLabel: "Play video",
+    pauseLabel: "Pause video",
+    loadError: "The video could not be loaded.",
+  };
+  const state = { isPlaying: false, hasFailed: false, videoId: "video-1" };
+  const unnamed = getVideoElementOptions(
+    element(
+      {},
+      withMedia({ alt: "", title: "", translated: { alt: "", title: "" } }),
+    ),
+  );
+
+  it("adds nothing when the video shows its controls", () => {
+    expect(
+      getVideoToggleAttributes(
+        getVideoElementOptions(element({ showControls: true })),
+        state,
+        labels,
+      ),
+    ).toEqual({});
+  });
+
+  it("names the button after what it does", () => {
+    expect(getVideoToggleAttributes(unnamed, state, labels)).toEqual({
+      role: "button",
+      tabindex: 0,
+      "aria-label": "Play video",
+      "aria-describedby": undefined,
+      "aria-disabled": undefined,
+      title: "Play video",
+    });
+    expect(
+      getVideoToggleAttributes(unnamed, { ...state, isPlaying: true }, labels)[
+        "aria-label"
+      ],
+    ).toBe("Pause video");
+  });
+
+  it("keeps the action in the name of a named video and describes it by the video", () => {
+    const named = getVideoElementOptions(
+      element({ ariaLabel: "Product demo" }),
+    );
+
+    expect(
+      getVideoToggleAttributes(named, { ...state, isPlaying: true }, labels),
+    ).toMatchObject({
+      "aria-label": "Pause video",
+      "aria-describedby": "video-1",
+      title: "Product demo",
+    });
+  });
+
+  it("reports a video that failed to load and stays focusable", () => {
+    expect(
+      getVideoToggleAttributes(
+        getVideoElementOptions(element({ ariaLabel: "Product demo" })),
+        { ...state, hasFailed: true },
+        labels,
+      ),
+    ).toEqual({
+      role: "button",
+      tabindex: 0,
+      "aria-label": "The video could not be loaded.",
+      "aria-describedby": "video-1",
+      "aria-disabled": true,
+      title: "The video could not be loaded.",
+    });
+  });
+});