@shopware/helpers 0.0.0-canary-20250116171244

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2023 Shopware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# shopware/frontends - helpers
+
+Welcome to `@shopware/helpers` package.
+
+For getting started documentation visit [https://frontends.shopware.com/](https://frontends.shopware.com/)
+
+Documentation specific for this package: [helpers](https://frontends.shopware.com/packages/helpers.html)
+
+## Reusable classes
+
+The `helpersCssClasses` variable, defined in the `cms/layoutClasses.ts` helper file, comprises an array of class names utilized within the CMS.
+
+To enhance type support, a union type `HelpersCssClasses` is defined, which encompasses all class names present in the `helpersCssClasses` array.
+
+```ts
+const visibilityMap: Record<CmsVisibility, HelpersCssClasses> = {
+  mobile: "max-md:hidden",
+  tablet: "md:max-lg:hidden",
+  desktop: "lg:hidden",
+};
+```
+
+These classes can be integrated into a custom template, thereby ensuring consistency across different packages. For example as a `safelist` classes in unocss configuration file
+
+```ts
+import { helpersCssClasses } from "@shopware/helpers";
+
+export default defineConfig({
+  safelist: helpersCssClasses,
+});
+```
+
+<!-- AUTO GENERATED CHANGELOG -->
+
+## Changelog
+
+Full changelog for stable version is available [here](https://github.com/shopware/frontends/blob/main/packages/helpers/CHANGELOG.md)
+
+### Latest changes: 0.0.0-canary-20250116171244
+
+### Minor Changes
+
+- [#1602](https://github.com/shopware/frontends/pull/1602) [`bb7d1cb`](https://github.com/shopware/frontends/commit/bb7d1cbc4204ff1d48f77416f94f550bc235e5ed) Thanks [@patzick](https://github.com/patzick)! - Switch from `@shopware-pwa/helpers-next` to `@shopware/helpers` package.
+
+- [#1602](https://github.com/shopware/frontends/pull/1602) [`bb7d1cb`](https://github.com/shopware/frontends/commit/bb7d1cbc4204ff1d48f77416f94f550bc235e5ed) Thanks [@patzick](https://github.com/patzick)! - Switch from `@shopware-pwa/cms-base` to `@shopware/cms-base-layer` package.

package/dist/index.d.mts

@@ -0,0 +1,617 @@
+/**
+ * Get product free shipping property
+ *
+ * @param {Product} product product entity
+ * @returns {boolean} product free shipping
+ *
+ * @public
+ *
+ * @category Product
+ */
+declare function getProductFreeShipping<T extends {
+    shippingFree: boolean;
+}>(product?: T): boolean;
+
+/**
+ * gets the cover image
+ *
+ * @param {Product | LineItem | OrderLineItem} object Object containing media object
+ *
+ * @public
+ *
+ * @category Product
+ */
+declare function getMainImageUrl<T extends {
+    cover?: {
+        media?: {
+            url: string;
+        };
+    };
+} | {
+    media?: Array<{
+        media?: {
+            url?: string;
+        };
+    }>;
+} | {
+    cover?: {
+        url: string;
+    };
+}>(object: T): string;
+
+/**
+ * @beta
+ *
+ * @param {Product} product product entity
+ *
+ * @category Product
+ */
+declare function getProductName<T extends {
+    name: string;
+}>({ product }?: {
+    product?: T;
+}): string | null;
+
+/**
+ * @public
+ */
+type UiMediaGalleryItemUrl = {
+    url: string;
+};
+/**
+ * @public
+ */
+type UiMediaGalleryItem = {
+    icon: UiMediaGalleryItemUrl;
+    mobile: UiMediaGalleryItemUrl;
+    desktop: UiMediaGalleryItemUrl;
+};
+/**
+ * @public
+ */
+type UiProductOption = {
+    label: string;
+    value: string;
+    code: string;
+    color: string | null;
+};
+/**
+ * @public
+ */
+type UiProductProperty = {
+    name: string;
+    value: string | null;
+};
+/**
+ * @public
+ */
+type UiProductReview = {
+    id: string;
+    author?: string;
+    date: string;
+    message?: string;
+    rating?: number;
+};
+
+/**
+ * Format product reviews to ui-interfaces
+ *
+ * @param {Product} product product entity
+ *
+ * @public
+ *
+ * @category Product
+ */
+declare function getProductReviews<T extends {
+    id: string;
+    productReviews?: Array<{
+        id: string;
+        externalUser?: string;
+        customerId?: string;
+        createdAt: string;
+        content: string;
+        points?: number;
+    }>;
+}>({ product }?: {
+    product?: T;
+}): UiProductReview[];
+
+/**
+ * @beta
+ */
+type TierPrice = {
+    label: string;
+    quantity: number;
+    unitPrice: number;
+};
+/**
+ * Get the prices depending on quantity added to cart.
+ * Tier prices can be set in `Advanced pricing` tab in `Product view` (admin panel)
+ *
+ * @param {Product} product product entity
+ *
+ * @returns TierPrice[]
+ * @beta
+ */
+declare function getProductTierPrices<T extends {
+    calculatedPrices?: Array<{
+        unitPrice: number;
+        quantity: number;
+    }>;
+}>(product?: T): TierPrice[];
+
+/**
+ * Get product url. The priority is SEO url and then technical url.
+ *
+ * @param {Product} product product entity
+ *
+ * @public
+ *
+ * @category Product
+ */
+declare function getProductUrl<T extends {
+    id: string;
+    seoUrls?: Array<{
+        seoPathInfo?: string;
+    }>;
+}>(product?: T): string;
+
+/**
+ * Get product rating average property
+ *
+ * @param product product entity
+ *
+ * @public
+ *
+ * @category Product
+ *
+ * @returns {number | null} product rating average
+ */
+declare function getProductRatingAverage<T extends {
+    ratingAverage: number;
+}>(product: T): number | null;
+
+type CalculatedPrice$1 = {
+    unitPrice?: number;
+    listPrice?: {
+        price: number;
+    };
+};
+/**
+ * Get the calculated list price
+ *
+ * @param {ProductWithCalculatedPrice} product product entity
+ * @returns (number|undefined)
+ *
+ * @beta
+ */
+declare function getProductCalculatedListingPrice<T extends {
+    calculatedPrice?: CalculatedPrice$1;
+    calculatedPrices?: CalculatedPrice$1[];
+}>(product?: T): number | undefined;
+
+type CalculatedPrice = {
+    unitPrice: number;
+};
+/**
+ *
+ * @param {ProductWithCalculatedPrice} product product entity
+ *
+ * @returns {number | undefined} product fromPrice
+ * @category Product
+ */
+declare function getProductFromPrice<T extends {
+    calculatedPrice?: CalculatedPrice;
+    calculatedPrices?: CalculatedPrice[];
+}>(product: T): number | undefined;
+
+/**
+ * Get product route information for Vue router.
+ *
+ * Returns product URL and route informations for resolving SEO url.
+ * Use it with combination of `<RouterLink>` or `<NuxtLink>` in Vue.js or Nuxt.js projects.
+ *
+ * @public
+ * @category Product
+ * @category Routing
+ */
+declare function getProductRoute<T extends {
+    id: string;
+    seoUrls?: Array<{
+        seoPathInfo?: string;
+    }>;
+}>(product?: T): {
+    path: string;
+    state: {
+        routeName: string;
+        foreignKey: string | undefined;
+    };
+};
+
+/**
+ * Get URL for category.
+ * Some link {@link isLinkCategory}
+ *
+ * @param {Category} category category entity
+ *
+ * @public
+ */
+declare function getCategoryUrl<T extends {
+    type: string;
+    externalLink?: string;
+    seoUrls?: {
+        seoPathInfo: string;
+    }[];
+    internalLink?: string;
+    id: string;
+    linkType?: string;
+}>(category: T): string;
+
+/**
+ * gets the cover image
+ *
+ * @param {Category} category category entity
+ *
+ * @public
+ */
+declare function getCategoryImageUrl<T extends {
+    media?: {
+        url: string;
+    };
+    type: string;
+}>(category: T): string;
+
+/**
+ * Gather breadcrumbs from category
+ *
+ */
+declare function getCategoryBreadcrumbs<T extends {
+    translated?: {
+        breadcrumb?: string[];
+    };
+    breadcrumb?: string[];
+}>(category: T, options?: {
+    /**
+     * Start at specific index if your navigation
+     * contains root names which should not be visible.
+     */
+    startIndex?: number;
+}): {
+    name: string;
+}[];
+
+/**
+ * Get category/navigation route information for Vue Router.
+ *
+ * Returns category or navigation URL and route informations for resolving SEO url.
+ * Use it with combination of `<RouterLink>` or `<NuxtLink>` in Vue.js or Nuxt.js projects.
+ *
+ * Example:
+ * ```html
+ * <RouterLink :to="getCategoryRoute(navigationElement)">
+ * ```
+ *
+ * @public
+ * @category Category
+ * @category Routing
+ */
+declare function getCategoryRoute<T extends {
+    type: string;
+    externalLink?: string;
+    seoUrls?: {
+        seoPathInfo: string;
+    }[];
+    internalLink?: string;
+    id: string;
+    linkType?: string;
+}>(category: T): string | {
+    path: string;
+    state: {
+        routeName: string;
+        foreignKey: string | undefined;
+    };
+};
+
+type GenericCms = {
+    visibility?: {
+        [key in CmsVisibility]?: boolean;
+    };
+    cssClass?: string | null;
+    backgroundColor?: string | null;
+    backgroundMedia?: {
+        url: string;
+    } | null;
+    backgroundMediaMode?: string | null;
+    sizingMode?: string | null;
+    marginBottom?: string | null;
+    marginLeft?: string | null;
+    marginRight?: string | null;
+    marginTop?: string | null;
+};
+type CmsBlock = GenericCms & {
+    apiAlias: "cms_block";
+};
+type CmsSection = GenericCms & {
+    apiAlias: "cms_section";
+};
+type CmsSlot = GenericCms & {
+    apiAlias: "cms_slot";
+};
+type CmsVisibility = "mobile" | "tablet" | "desktop" | string;
+/**
+ * @beta
+ */
+type LayoutConfiguration = {
+    layoutStyles: {
+        backgroundColor?: string | null;
+        backgroundImage?: string | null;
+        backgroundSize?: string | null;
+        sizingMode?: string | null;
+        marginBottom?: string | null | undefined;
+        marginLeft?: string | null | undefined;
+        marginRight?: string | null | undefined;
+        marginTop?: string | null | undefined;
+    };
+    cssClasses: {
+        [cssClass: string]: boolean;
+    } | null;
+};
+/**
+ * Get layout configuration for CMS content
+ *
+ * @param content CMS content
+ *
+ * @category CMS (Shopping Experiences)
+ */
+declare function getCmsLayoutConfiguration<T extends CmsBlock | CmsSection | CmsSlot>(content: T): LayoutConfiguration;
+
+declare function getBackgroundImageUrl<T extends {
+    backgroundMedia?: {
+        metaData?: {
+            width?: number;
+            height?: number;
+        };
+    };
+}>(url: string, element: T): string;
+
+type UrlRoute = {
+    path?: string;
+    state?: {
+        routeName?: string;
+        foreignKey?: string;
+    };
+};
+type UrlRouteOutput = Omit<UrlRoute, "path"> & {
+    path: string;
+};
+declare function buildUrlPrefix(url: string | UrlRoute, prefix: string): UrlRouteOutput;
+
+declare const helpersCssClasses: string[];
+type HelpersCssClasses = (typeof helpersCssClasses)[number];
+
+declare function isMaintenanceMode<T extends {
+    code?: string;
+}>(errors: [T]): boolean;
+
+/**
+ * Replace text placeholder with param value
+ *
+ * @param {string} key
+ * @param {} params
+ * @returns {string}
+ */
+declare function getCmsTranslate(key: string, params?: {
+    [key: string]: string | number | null | undefined;
+} | null): string;
+
+/**
+ * Build the breadcrumbs for the CMS page
+ *
+ * @param page
+ * @returns
+ */
+declare function getCmsBreadcrumbs<T extends {
+    translated: {
+        name: string;
+    };
+}>(page: T): {
+    name: string;
+}[];
+
+type Category = {
+    apiAlias: "category";
+};
+type LandingPage = {
+    apiAlias: "landing_page";
+};
+type Product = {
+    apiAlias: "product";
+    media?: {
+        thumbnails?: Array<{
+            width: number;
+            url: string;
+        }>;
+    };
+};
+type CmsPageResponse = {
+    resourceType: "frontend.navigation.page" | "frontend.detail.page" | "frontend.landing.page";
+    product: Product;
+    category: Category;
+    landingPage: LandingPage;
+};
+
+/**
+ * Returns the main page object depending of the type of the CMS page.
+ *
+ * @category CMS (Shopping Experiences)
+ */
+declare function getCmsEntityObject(response: CmsPageResponse): Product | Category | LandingPage;
+/**
+ * Predicate function to check if the entity is a product.
+ *
+ * @category CMS (Shopping Experiences)
+ */
+declare function isProduct<T extends {
+    apiAlias: string;
+}>(entity: T | Product): entity is Product;
+declare function isCategory<T extends {
+    apiAlias: string;
+}>(entity: T | Category): entity is Category;
+declare function isLandingPage<T extends {
+    apiAlias: string;
+}>(entity: T | LandingPage): entity is LandingPage;
+
+/**
+ * Get translated property from the given object.
+ *
+ * @param {T} element object with translated property
+ *
+ * @public
+ */
+declare function getTranslatedProperty<T>(element: T | undefined | null | never, property: keyof T): string;
+
+type ListingFilter = {
+    label: string;
+    code: string;
+    id: string;
+    name: string;
+};
+/**
+ * @beta
+ */
+declare function getListingFilters<T extends Record<string, any>>(aggregations: T | undefined | null): ListingFilter[];
+
+type Options = {
+    direction?: "ltr" | "rtl";
+    removeDecimals?: boolean;
+    removeCurrency?: boolean;
+};
+/**
+ * Get formatted price
+ *
+ * @param value price value
+ * @param currency currency symbol
+ * @param options formatting options (direction, removeDecimals, removeCurrency)
+ *
+ * @public
+ */
+declare function getFormattedPrice(value: string | number, currency: string, options?: Options): string;
+
+/**
+ * Download file
+ *
+ */
+declare function downloadFile<T>(file: T, name: string): void;
+
+/**
+ * Returns the biggest thumbnail url from the media object
+ *
+ * @param media image object
+ *
+ * @public
+ * @category Media
+ */
+declare function getBiggestThumbnailUrl<T extends {
+    thumbnails?: Array<{
+        width: number;
+        url: string;
+    }>;
+}>(media?: T): string | undefined;
+
+type ProductMedia = {
+    id: string;
+    fileName: string;
+    accessGranted: boolean;
+};
+/**
+ * Prepare media object
+ *
+ * @param {OrderLineItem} lineItem order item
+ *
+ * @public
+ * @category Media
+ */
+declare function getMedia<T extends {
+    downloads?: Array<{
+        id: string;
+        accessGranted: boolean;
+        media: {
+            fileName: string;
+            fileExtension: string;
+        };
+    }>;
+}>(lineItem: T): ProductMedia[];
+
+/**
+ * Returns the smallest thumbnail url from the media object
+ *
+ * @param media image object
+ *
+ * @public
+ * @category Media
+ */
+declare function getSmallestThumbnailUrl<T extends {
+    thumbnails?: Array<{
+        width: number;
+        url: string;
+    }>;
+}>(media?: T): string | undefined;
+
+/**
+ * Returns the srcset attribute for the image, for available breakpoints
+ *
+ * @param media image object
+ *
+ * @public
+ * @category Media
+ */
+declare function getSrcSetForMedia<T extends {
+    thumbnails?: Array<{
+        width: number;
+        url: string;
+    }>;
+}>(media?: T): string | undefined;
+
+/**
+ *  Get shipping delivery time
+ *
+ */
+declare function getShippingMethodDeliveryTime<T extends {
+    deliveryTime?: {
+        translated: {
+            name: string;
+        };
+    };
+}>(shippingMethod: T): string | undefined;
+
+/**
+ * Get translated language name
+ *
+ * @param {Language} language
+ * @returns {string}
+ */
+declare function getLanguageName<T extends {
+    translationCode?: {
+        translated: {
+            name: string;
+        };
+    };
+}>(language: T): string;
+
+/**
+ * Add/remove slash from the relative path
+ *
+ * @param {string} relativeUrl
+ * @param {boolean} slash
+ */
+declare function relativeUrlSlash(relativeUrl: string, slash?: boolean): string;
+
+declare function urlIsAbsolute(url: string): boolean;
+
+declare function canUseQuoteActions<T extends {
+    stateMachineState?: {
+        technicalName: string;
+    };
+}>(quote: T): boolean;
+
+export { type HelpersCssClasses, type LayoutConfiguration, type TierPrice, type UiMediaGalleryItem, type UiMediaGalleryItemUrl, type UiProductOption, type UiProductProperty, type UiProductReview, buildUrlPrefix, canUseQuoteActions, downloadFile, getBackgroundImageUrl, getBiggestThumbnailUrl, getCategoryBreadcrumbs, getCategoryImageUrl, getCategoryRoute, getCategoryUrl, getCmsBreadcrumbs, getCmsEntityObject, getCmsLayoutConfiguration, getCmsTranslate, getFormattedPrice, getLanguageName, getListingFilters, getMainImageUrl, getMedia, getProductCalculatedListingPrice, getProductFreeShipping, getProductFromPrice, getProductName, getProductRatingAverage, getProductReviews, getProductRoute, getProductTierPrices, getProductUrl, getShippingMethodDeliveryTime, getSmallestThumbnailUrl, getSrcSetForMedia, getTranslatedProperty, helpersCssClasses, isCategory, isLandingPage, isMaintenanceMode, isProduct, relativeUrlSlash, urlIsAbsolute };