@scayle/storefront-product-detail 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# @scayle/storefront-product-detail
+
+## 1.1.0
+
+### Minor Changes
+
+- **\[SEO\]** Update product JSON-LD data to use the `ProductGroup` schema.
+
+## 1.0.2
+
+### Patch Changes
+
+- Ensure the module meta has the correct package version
+
+## 1.0.1
+
+### Patch Changes
+
+- We've updated to `nuxt@3.14`
+
+## 1.0.0
+
+### Major Changes
+
+- This release introduces the `@scayle/storefront-product-detail` package, decoupling composables and utilities of the Product Detail Page (PDP) functionality from the SCAYLE Storefront Boilerplate for enhanced modularity and integration.
+  This separation empowers developers with greater control over PDP updates and simplifies its integration into existing Storefront-based projects.
+
+  - [Discover more about the Product Detail Page for SCAYLE Storefront in our SCAYLE Resource Center.](https://scayle.dev/en/storefront-guide/developer-guide/features/pages/product-detail-page)
+
+- This release requires `@scayle/storefront-nuxt@8.x` or higher. Support for `@scayle/storefront-nuxt@7.x` has been discontinued. Please update your dependencies accordingly. The `peerDependency` range has been updated to `^8.0.0`.
+
+### Minor Changes
+
+- Compared to the original implementation within the SCAYLE Storefront Boilerplate, the `@scayle/storefront-product-detail` package has received some improvements and refactoring:
+
+  - Introduced the `getCombineWithProductIds` function within the product utility, enabling efficient retrieval of product combinations within product listings.
+  - Added the `getFilteredAttributeGroups` function to the attribute utility, simplifying the retrieval and formatting of filtered product attributes for display in listings.
+  - Introduced the `useProductSeoData` composable, automating the generation of SEO-critical metadata for product pages. This includes dynamically generated canonical links, robots meta tags, product titles, and structured data (`JSON-LD`) for product details and breadcrumbs, enhancing search engine visibility.
+
+## 0.4.0
+
+### Minor Changes
+
+- Fix computed `sortLinks` return type mismatch in `UseProductListSortReturn` interface.
+
+## 0.3.0
+
+### Minor Changes
+
+- Fix `sortLinks` type by extending the `SelectedSort` type with `to` property which represents the `RouteLocationRaw` type from `vue-router`.
+
+## 0.2.0
+
+### Minor Changes
+
+- Add and expose explicit return types/interfaces externally for all product detail composables.
+
+## 0.1.2
+
+### Patch Changes
+
+- Update import of test factories to use new entry point
+
+## 0.1.1
+
+### Patch Changes
+
+- Resolved issue where sorting did not correctly route to the first page.
+
+## 0.1.0
+
+### Minor Changes
+
+- Introduce `@scayle/storefront-product-listing` package

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 SCAYLE GmbH
+Copyright (c) 2025 SCAYLE GmbH
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/module.json

@@ -1,13 +1,13 @@
 {
   "name": "@scayle/storefront-product-detail",
   "configKey": "product-detail",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "compatibility": {
     "bridge": false,
     "nuxt": ">=3.13"
   },
   "builder": {
     "@nuxt/module-builder": "0.8.4",
-    "unbuild": "3.0.1"
+    "unbuild": "3.3.1"
   }
 }

package/dist/module.mjs

@@ -1,10 +1,12 @@
 import { defineNuxtModule, createResolver, addImportsDir } from '@nuxt/kit';
 
+const PACKAGE_NAME = "@scayle/storefront-product-detail";
+const PACKAGE_VERSION = "1.1.0";
 const module = defineNuxtModule({
   meta: {
-    name: "@scayle/storefront-product-detail",
+    name: PACKAGE_NAME,
     configKey: "product-detail",
-    version: "1.0.0",
+    version: PACKAGE_VERSION,
     compatibility: {
       bridge: false,
       nuxt: ">=3.13"

package/dist/runtime/composables/useProductSeoData.d.ts

@@ -1,19 +1,24 @@
-import { type ComputedRef, type MaybeRefOrGetter } from 'vue';
-import type { BreadcrumbItem, Variant } from '@scayle/storefront-nuxt';
-import type { WithContext, Product, BreadcrumbList } from 'schema-dts';
+import type { ComputedRef, MaybeRefOrGetter } from 'vue';
+import type { BreadcrumbItem } from '@scayle/storefront-nuxt';
+import type { WithContext, BreadcrumbList, ProductGroup, Product } from 'schema-dts';
 type CanonicalLink = Record<'rel' | 'key' | 'href', string>;
 type UrlParams = Record<'baseUrl' | 'fullPath', string>;
 interface ProductInfo {
+    /** The id of the product. */
+    productId: number;
     /** The name of the product. */
     name: string;
     /** The brand of the product. */
     brand: string;
     /** A description of the product. */
     productDescription: string;
+    /** The color of the product. */
+    color: string;
     /** Array of product variants. */
-    variants: Variant[];
+    variants: WithContext<Product>[];
     /** Array of image URLs for the product. */
     images: string[];
+    variesBy?: ProductGroup['variesBy'];
 }
 export interface UseProductSeoDataReturn {
     /** The title of the product. */
@@ -22,8 +27,8 @@ export interface UseProductSeoDataReturn {
     robots: string;
     /** Computed ref for canonical link tag metadata. */
     canonicalLink: ComputedRef<CanonicalLink[]>;
-    /** Computed ref containing JSON-LD structured data for the product. */
-    productJsonLd: ComputedRef<WithContext<Product>>;
+    /** Computed ref containing JSON-LD structured data for the product group. */
+    productJsonLd: ComputedRef<WithContext<ProductGroup>>;
     /** Computed ref containing JSON-LD structured data for product breadcrumbs. */
     productBreadcrumbJsonLd: ComputedRef<WithContext<BreadcrumbList>>;
 }

package/dist/runtime/composables/useProductSeoData.js

@@ -3,7 +3,7 @@ import {
   generateCategoryBreadcrumbSchema,
   sanitizeCanonicalURL
 } from "@scayle/storefront-nuxt";
-import { generateProductSchema } from "../utils/seo.js";
+import { generateProductGroupSchema } from "../utils/seo.js";
 export function useProductSeoData(breadcrumbs, urlParams, productInfo) {
   const canonicalUrl = computed(() => {
     const url = `${toValue(urlParams).baseUrl}${toValue(urlParams).fullPath}`;
@@ -14,13 +14,16 @@ export function useProductSeoData(breadcrumbs, urlParams, productInfo) {
   });
   const robots = "index, follow";
   const productJsonLd = computed(() => {
-    return generateProductSchema({
-      productName: toValue(productInfo).name,
-      brandName: toValue(productInfo).brand,
-      url: canonicalUrl.value,
-      variants: toValue(productInfo).variants,
-      images: toValue(productInfo).images,
-      description: toValue(productInfo).productDescription
+    const info = toValue(productInfo);
+    return generateProductGroupSchema({
+      productId: info.productId.toString(),
+      name: info.name,
+      description: info.productDescription,
+      images: info.images,
+      brandName: info.brand,
+      color: info.color,
+      variants: info.variants,
+      variesBy: info.variesBy
     });
   });
   const productBreadcrumbJsonLd = computed(() => {

package/dist/runtime/utils/product.d.ts

@@ -1,4 +1,4 @@
-import { type AdvancedAttribute } from '@scayle/storefront-nuxt';
+import type { AdvancedAttribute } from '@scayle/storefront-nuxt';
 /**
  * Extracts and returns an array of product IDs from an advanced attribute.
  *

package/dist/runtime/utils/product.js

@@ -1,6 +1,4 @@
-import {
-  getFlattenedAdvancedAttribute
-} from "@scayle/storefront-nuxt";
+import { getFlattenedAdvancedAttribute } from "@scayle/storefront-nuxt";
 export const getCombineWithProductIds = (attribute) => {
   if (!attribute) {
     return [];

package/dist/runtime/utils/seo.d.ts

@@ -1,5 +1,5 @@
 import type { Variant } from '@scayle/storefront-nuxt';
-import type { Product, WithContext } from 'schema-dts';
+import type { Product, WithContext, ProductGroup } from 'schema-dts';
 /**
  * Generates an object following the schema.org `Product` type with context.
  *
@@ -8,11 +8,19 @@ import type { Product, WithContext } from 'schema-dts';
  *
  * @returns An object following the schema.org `Product` type with context.
  */
-export declare const generateProductSchema: ({ productName, brandName, variants, url, images, description, }: {
+export declare const generateProductSchema: ({ productName, variant, url, size, }: {
     productName: string;
-    brandName: string;
-    variants: Variant[];
+    variant: Variant;
     url: string;
-    description: string;
-    images?: string[];
+    size?: string;
 }) => WithContext<Product>;
+export declare const generateProductGroupSchema: ({ productId, name, description, images, brandName, color, variants, variesBy, }: {
+    productId: string;
+    name: string;
+    description: string;
+    images: string[];
+    brandName: string;
+    color: string;
+    variants: Product[];
+    variesBy?: ProductGroup["variesBy"];
+}) => WithContext<ProductGroup>;

package/dist/runtime/utils/seo.js

@@ -1,38 +1,58 @@
 import { isInStock } from "@scayle/storefront-nuxt";
-const generateSchemaProductOffers = ({
-  variants
+const generateSchemaProductOffer = ({
+  variant,
+  baseUrl
 }) => {
-  return variants.map((variant) => ({
+  const url = new URL(baseUrl);
+  url.searchParams.append("variantId", variant.id.toString());
+  return {
     "@type": "Offer",
+    url: url.href,
     mpn: variant.referenceKey,
     sku: variant.id.toString(),
     price: variant.price.withTax / 100,
     priceCurrency: variant.price.currencyCode,
     availability: isInStock(variant) ? "https://schema.org/InStock" : "https://schema.org/OutOfStock",
     itemCondition: "https://schema.org/NewCondition"
-  }));
+  };
 };
 export const generateProductSchema = ({
   productName,
-  brandName,
-  variants,
+  variant,
   url,
-  images = [],
-  description
+  size
 }) => {
-  const offers = generateSchemaProductOffers({ variants });
-  const brand = {
-    "@type": "Brand",
-    name: brandName
-  };
   return {
     "@context": "https://schema.org",
     "@type": "Product",
-    url,
-    name: productName,
-    image: images,
+    name: `${productName} (size)`,
+    size,
+    offers: generateSchemaProductOffer({ variant, baseUrl: url })
+  };
+};
+export const generateProductGroupSchema = ({
+  productId,
+  name,
+  description,
+  images,
+  brandName,
+  color,
+  variants,
+  variesBy
+}) => {
+  return {
+    "@context": "https://schema.org",
+    "@type": "ProductGroup",
+    productID: productId,
+    name: `${name}, ${color}`,
     description,
-    brand,
-    offers
+    image: images,
+    brand: {
+      "@type": "Brand",
+      name: brandName
+    },
+    color,
+    ...variants.length ? { hasVariant: variants } : {},
+    ...variesBy ? { variesBy } : {}
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scayle/storefront-product-detail",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Collection of essential composables and utilities to work with product detail",
   "author": "SCAYLE Commerce Engine",
   "license": "MIT",
@@ -19,6 +19,7 @@
   "main": "./dist/module.cjs",
   "types": "./dist/types.d.ts",
   "files": [
+    "CHANGELOG.md",
     "dist"
   ],
   "imports": {
@@ -35,7 +36,7 @@
     "format:fix": "dprint fmt",
     "test": "vitest --run --passWithNoTests",
     "test:watch": "vitest --passWithNoTests",
-    "test:ci": "vitest --run --passWithNoTests --coverage --reporter=default --reporter=junit --outputFile=./junit.xml",
+    "test:ci": "vitest --run --passWithNoTests --coverage --reporter=default --reporter=junit --outputFile=./coverage/junit.xml",
     "typecheck": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
     "package:lint": "publint"
   },
@@ -43,28 +44,28 @@
     "@nuxt/kit": "^3.13.0",
     "@scayle/storefront-nuxt": "^8.0.0",
     "@vue/test-utils": "2.4.6",
-    "@vueuse/core": "12.0.0",
+    "@vueuse/core": "12.7.0",
     "vue-router": "4.5.0"
   },
   "devDependencies": {
     "@nuxt/kit": "3.14.1592",
     "@nuxt/module-builder": "0.8.4",
     "@nuxt/schema": "3.14.1592",
-    "@nuxt/test-utils": "3.15.1",
-    "@scayle/eslint-config-storefront": "4.4.0",
-    "@scayle/storefront-nuxt": "8.1.4",
-    "@types/node": "22.10.2",
+    "@nuxt/test-utils": "3.15.4",
+    "@scayle/eslint-config-storefront": "4.4.1",
+    "@scayle/storefront-nuxt": "8.10.3",
+    "@types/node": "22.13.4",
     "@vue/test-utils": "2.4.6",
-    "@vueuse/core": "12.0.0",
-    "dprint": "0.47.6",
-    "eslint": "9.17.0",
-    "happy-dom": "15.11.7",
+    "@vueuse/core": "12.7.0",
+    "dprint": "0.49.0",
+    "eslint": "9.20.1",
+    "happy-dom": "17.1.1",
     "eslint-formatter-gitlab": "5.1.0",
     "nuxt": "3.14.1592",
     "publint": "0.2.12",
-    "typescript": "5.6.3",
-    "vitest": "2.1.8",
+    "typescript": "5.7.3",
+    "vitest": "2.1.9",
     "vue-router": "4.5.0",
-    "vue-tsc": "2.1.10"
+    "vue-tsc": "2.2.2"
   }
 }

package/dist/runtime/composables/useProductSeoData.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/runtime/composables/useProductSeoData.test.js

@@ -1,179 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { useProductSeoData } from "~/src/runtime";
-import { variantFactory } from "@scayle/storefront-nuxt/dist/test/factories";
-import { ref } from "vue";
-describe("useProductSeoData", () => {
-  it("should return product seo data from product", () => {
-    const {
-      title,
-      productBreadcrumbJsonLd,
-      productJsonLd,
-      robots,
-      canonicalLink
-    } = useProductSeoData(
-      [{ value: "value", to: "/" }],
-      { baseUrl: "baseUrl", fullPath: "fullPath" },
-      {
-        name: "name",
-        variants: [variantFactory.build({ id: 1 })],
-        brand: "brand",
-        productDescription: "description",
-        images: []
-      }
-    );
-    expect(title.value).toBe("name");
-    expect(productBreadcrumbJsonLd.value).toStrictEqual({
-      "@context": "https://schema.org",
-      "@type": "BreadcrumbList",
-      "itemListElement": [
-        {
-          "@type": "ListItem",
-          "item": "/",
-          "name": "value",
-          "position": 1
-        }
-      ]
-    });
-    expect(productJsonLd.value).toStrictEqual({
-      "@context": "https://schema.org",
-      "@type": "Product",
-      "brand": {
-        "@type": "Brand",
-        "name": "brand"
-      },
-      "description": "description",
-      "image": [],
-      "name": "name",
-      "offers": [
-        {
-          "@type": "Offer",
-          "availability": "https://schema.org/InStock",
-          "itemCondition": "https://schema.org/NewCondition",
-          "mpn": void 0,
-          "price": 1,
-          "priceCurrency": "USD",
-          "sku": "1"
-        }
-      ],
-      "url": "baseUrlfullPath"
-    });
-    expect(robots).toBe("index, follow");
-    expect(canonicalLink.value).toStrictEqual([
-      {
-        "href": "baseUrlfullPath",
-        "key": "canonical",
-        "rel": "canonical"
-      }
-    ]);
-  });
-  it("should handle reactivity correctly with changing parameters", () => {
-    const breadcrubs = [{ value: "value", to: "/" }];
-    const urlParams = { baseUrl: "baseUrl", fullPath: "fullPath" };
-    const productInfo = ref({
-      name: "name",
-      variants: [variantFactory.build({ id: 1 })],
-      brand: "brand",
-      productDescription: "description",
-      images: []
-    });
-    const {
-      title,
-      productBreadcrumbJsonLd,
-      productJsonLd,
-      canonicalLink
-    } = useProductSeoData(
-      breadcrubs,
-      urlParams,
-      productInfo
-    );
-    expect(title.value).toBe("name");
-    expect(productBreadcrumbJsonLd.value).toStrictEqual({
-      "@context": "https://schema.org",
-      "@type": "BreadcrumbList",
-      "itemListElement": [
-        {
-          "@type": "ListItem",
-          "item": "/",
-          "name": "value",
-          "position": 1
-        }
-      ]
-    });
-    expect(productJsonLd.value).toStrictEqual({
-      "@context": "https://schema.org",
-      "@type": "Product",
-      "brand": {
-        "@type": "Brand",
-        "name": "brand"
-      },
-      "description": "description",
-      "image": [],
-      "name": "name",
-      "offers": [
-        {
-          "@type": "Offer",
-          "availability": "https://schema.org/InStock",
-          "itemCondition": "https://schema.org/NewCondition",
-          "mpn": void 0,
-          "price": 1,
-          "priceCurrency": "USD",
-          "sku": "1"
-        }
-      ],
-      "url": "baseUrlfullPath"
-    });
-    expect(canonicalLink.value).toStrictEqual([
-      {
-        "href": "baseUrlfullPath",
-        "key": "canonical",
-        "rel": "canonical"
-      }
-    ]);
-    breadcrubs[0].to = "/other";
-    urlParams.baseUrl = "otherUrl";
-    productInfo.value.name = "otherName";
-    expect(title.value).toBe("otherName");
-    expect(productBreadcrumbJsonLd.value).toStrictEqual({
-      "@context": "https://schema.org",
-      "@type": "BreadcrumbList",
-      "itemListElement": [
-        {
-          "@type": "ListItem",
-          "item": "/other",
-          "name": "value",
-          "position": 1
-        }
-      ]
-    });
-    expect(productJsonLd.value).toStrictEqual({
-      "@context": "https://schema.org",
-      "@type": "Product",
-      "brand": {
-        "@type": "Brand",
-        "name": "brand"
-      },
-      "description": "description",
-      "image": [],
-      "name": "otherName",
-      "offers": [
-        {
-          "@type": "Offer",
-          "availability": "https://schema.org/InStock",
-          "itemCondition": "https://schema.org/NewCondition",
-          "mpn": void 0,
-          "price": 1,
-          "priceCurrency": "USD",
-          "sku": "1"
-        }
-      ],
-      "url": "otherUrlfullPath"
-    });
-    expect(canonicalLink.value).toStrictEqual([
-      {
-        "href": "otherUrlfullPath",
-        "key": "canonical",
-        "rel": "canonical"
-      }
-    ]);
-  });
-});

package/dist/runtime/utils/attribute.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/runtime/utils/attribute.test.js

@@ -1,39 +0,0 @@
-import { it, describe, expect } from "vitest";
-import { attributeGroupFactory } from "@scayle/storefront-nuxt/dist/test/factories";
-import { getFilteredAttributeGroups } from "./attribute.js";
-describe("attribute", () => {
-  describe("getFilteredAttributeGroups", () => {
-    it("should return correct filtered and formatted attributes", () => {
-      const attributes = {
-        design: attributeGroupFactory.build({
-          type: "design",
-          label: "Jackenart",
-          values: { id: 2534, label: "Bomberjacke", value: "bomberjacke" }
-        }),
-        extras: attributeGroupFactory.build({
-          label: "Extras",
-          type: "extras",
-          multiSelect: true,
-          values: [
-            { id: 2427, label: "Weicher Griff", value: "weicher_griff" },
-            { id: 2435, label: "Ton-in-Ton-N\xE4hte", value: "tonintonnhte" },
-            { id: 2438, label: "Label-Stickerei", value: "labelstickerei" }
-          ]
-        })
-      };
-      const formattedAttributes = getFilteredAttributeGroups(
-        attributes,
-        ["design", "extras"]
-      );
-      expect(formattedAttributes).toHaveLength(2);
-      expect(formattedAttributes.get("design")).toStrictEqual([
-        "Jackenart: Bomberjacke"
-      ]);
-      expect(formattedAttributes.get("extras")).toStrictEqual([
-        "Weicher Griff",
-        "Ton-in-Ton-N\xE4hte",
-        "Label-Stickerei"
-      ]);
-    });
-  });
-});

package/dist/runtime/utils/product.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/runtime/utils/product.test.js

@@ -1,97 +0,0 @@
-import { it, describe } from "vitest";
-import { getCombineWithProductIds } from "~/src/runtime/utils/product";
-import { advancedAttributeFactory } from "@scayle/storefront-nuxt/dist/test/factories";
-describe("getCombineWithProductIds", () => {
-  it("should return productIds from data", ({ expect }) => {
-    const combineWithAttribute = advancedAttributeFactory.build({
-      key: "combineWith",
-      label: "Kombiniere mit",
-      values: [
-        {
-          fieldSet: [
-            [
-              {
-                value: "206131"
-              }
-            ]
-          ],
-          groupSet: []
-        },
-        {
-          fieldSet: [
-            [
-              {
-                value: "206017"
-              }
-            ]
-          ],
-          groupSet: []
-        },
-        {
-          fieldSet: [
-            [
-              {
-                value: "206012"
-              }
-            ]
-          ],
-          groupSet: []
-        }
-      ]
-    });
-    expect(getCombineWithProductIds(combineWithAttribute)).toStrictEqual([
-      206131,
-      206017,
-      206012
-    ]);
-  });
-  it("should return empty array when attribute is not available", ({ expect }) => {
-    expect(getCombineWithProductIds(void 0)).toStrictEqual([]);
-  });
-  it("should return productIds ignore invalid data", ({ expect }) => {
-    const combineWithAttributeWithInvalidData = advancedAttributeFactory.build({
-      key: "combineWith",
-      label: "Kombiniere mit",
-      values: [
-        {
-          fieldSet: [
-            [
-              {
-                value: "206131"
-              }
-            ],
-            [
-              {
-                value: "TEST"
-              }
-            ]
-          ],
-          groupSet: []
-        },
-        {
-          fieldSet: [
-            [
-              {
-                value: "206017"
-              }
-            ]
-          ],
-          groupSet: []
-        },
-        {
-          fieldSet: [
-            [
-              {
-                value: "206012"
-              }
-            ]
-          ],
-          groupSet: []
-        }
-      ]
-    });
-    expect(
-      getCombineWithProductIds(combineWithAttributeWithInvalidData)
-    ).toStrictEqual([206131, 206017, 206012]);
-  });
-});

package/dist/runtime/utils/seo.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/runtime/utils/seo.test.js

@@ -1,38 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { generateProductSchema } from "~/src/runtime/utils/seo";
-import { variantFactory } from "@scayle/storefront-nuxt/dist/test/factories";
-describe("generateProductSchema", () => {
-  it("should return productSchema from product", () => {
-    const productSchema = generateProductSchema({
-      productName: "productName",
-      brandName: "brandName",
-      variants: [variantFactory.build({ id: 1 })],
-      url: "url",
-      images: [],
-      description: "description"
-    });
-    expect(productSchema).toStrictEqual({
-      "@context": "https://schema.org",
-      "@type": "Product",
-      "brand": {
-        "@type": "Brand",
-        "name": "brandName"
-      },
-      "description": "description",
-      "image": [],
-      "name": "productName",
-      "offers": [
-        {
-          "@type": "Offer",
-          "availability": "https://schema.org/InStock",
-          "itemCondition": "https://schema.org/NewCondition",
-          "mpn": void 0,
-          "price": 1,
-          "priceCurrency": "USD",
-          "sku": "1"
-        }
-      ],
-      "url": "url"
-    });
-  });
-});