@ikas/bp-storefront 0.130.0 → 0.132.0

package/dist/functions/models/campaign-offer/index.d.ts

@@ -1,12 +1,20 @@
 import { IkasProductOffer } from "../../../storefront-models/src";
 /**
- * Checks whether a product offer has been accepted in the current cart's campaign offers.
+ * Checks whether the product offer is already in the cart as an ACCEPTED campaign offer for the
+ * PRODUCT target page type. This is a **cart-state check** and is independent of
+ * `productOffer.isSelected` (the UI toggle state set by `acceptProductOffer`). Use it to disable
+ * the selection UI and show an "already in cart" state when the offer has been added.
+ *
+ * Example state combinations:
+ * - `isSelected=true`,  `isAcceptedProductOffer=false` — user selected it in UI, not yet in cart
+ * - `isSelected=true`,  `isAcceptedProductOffer=true`  — selected AND in cart (disable toggle)
+ * - `isSelected=false`, `isAcceptedProductOffer=false` — deselected, not in cart
  *
  * @ai-category CampaignOffer
  * @ai-related acceptProductOffer, rejectProductOffer
  *
- * @param productOffer - The product offer to check acceptance status for.
- * @returns True if the offer is accepted for the PRODUCT target page type in the cart, false otherwise.
+ * @param productOffer - The product offer to check.
+ * @returns True if the offer's campaign offer is in the cart as ACCEPTED for PRODUCT target page type, false otherwise.
  *
  * @example
  * ```typescript
@@ -20,12 +28,14 @@ import { IkasProductOffer } from "../../../storefront-models/src";
  */
 export declare function isAcceptedProductOffer(productOffer: IkasProductOffer): boolean;
 /**
- * Accepts a product offer by setting its isSelected flag to true.
+ * Sets `productOffer.isSelected = true` — a **UI toggle** marking the offer as selected by the
+ * user. This does NOT add the offer to the cart; cart inclusion happens through the add-to-cart
+ * flow. See `isAcceptedProductOffer` for the independent cart-state check.
  *
  * @ai-category CampaignOffer
  * @ai-related isAcceptedProductOffer, rejectProductOffer
  *
- * @param productOffer - The product offer to accept.
+ * @param productOffer - The product offer to mark as selected in the UI.
  * @returns void
  *
  * @example

package/dist/functions/models/order/index.d.ts

@@ -324,6 +324,10 @@ export declare function getIkasOrderFormattedOrderedAt(order: IkasOrder): string
  * import { getIkasOrderPackageStatusTranslation } from "@ikas/bp-storefront";
  * const statusLabel = getIkasOrderPackageStatusTranslation(order); // e.g. "Delivered"
  * ```
+ *
+ * NOTE: Pass the `IkasOrder` directly — NOT an `IkasDisplayedPackage` returned by
+ * `getIkasOrderDisplayedPackages()`. The function reads `order.orderPackageStatus` from the
+ * order itself.
  */
 export declare function getIkasOrderPackageStatusTranslation(order: IkasOrder): string;
 /**

package/dist/functions/models/product/filter/index.d.ts

@@ -142,8 +142,14 @@ export declare function getFilterKeyList(filter: IkasProductFilter): string[];
 /**
  * Returns the filter values sorted and filtered for display, respecting the configured sort type (alphabetical, product count, or custom).
  *
+ * NOTE on numeric filter suffixes: for `NUMBER_RANGE` / `NUMBER_RANGE_LIST` filters, decide the
+ * display suffix from `filter.type` — NOT by blanket-applying the store currency symbol. The
+ * canonical convention used by the serel theme templates is:
+ * - `filter.type === "DISCOUNT_RATIO"` → `"%"`
+ * - otherwise (including `"PRICE"`) → `getProductListCurrencySymbol(productList)`
+ *
  * @ai-category ProductFilter, Filtering, ProductList
- * @ai-related getFilterValueList, getFilterKeyList, selectFilterValue
+ * @ai-related getFilterValueList, getFilterKeyList, selectFilterValue, getProductListCurrencySymbol
  *
  * @param filter - The product filter whose values to retrieve and sort for display.
  * @returns A sorted array of filter values, excluding unselected values with zero result count.

package/dist/functions/models/product/index.d.ts

@@ -525,9 +525,11 @@ export declare function getProductAvailableStockLocations(product: IkasProduct):
 export declare function getProductOptionSet(product: IkasProduct): Promise<boolean>;
 export declare function initProductOptionSet(productOptionSet: IkasProductOptionSet): void;
 /**
- * Initialize bundle product data for a product.
- * If an `editLineID` URL param is present, restores bundle selections from the cart line item;
- * otherwise loads bundle products for the currently selected variant.
+ * Initialize bundle product data for a product — the canonical entry point for product detail
+ * pages. Calls `getBundleProductsOfVariant` internally to fetch bundle data, then binds variant
+ * selections and quantities. If an `editLineID` URL param is present, restores bundle selections
+ * from the matching cart line item (used for cart edit flow); otherwise loads bundle products for
+ * the currently selected variant.
  *
  * @ai-category Product, ProductDetail
  * @ai-related getBundleProductsOfVariant, getSelectedProductVariant, isBundleProductQuantityEditable
@@ -547,8 +549,13 @@ export declare function initProductOptionSet(productOptionSet: IkasProductOption
  */
 export declare function initBundleProducts(product: IkasProduct): Promise<void>;
 /**
- * Fetch and attach bundle product data for a specific variant.
- * Loads the full product data for each bundle product and caches the results on the parent product.
+ * Fetch and attach bundle product data for a specific variant. Loads the full product data for
+ * each bundle product and caches the results on the parent product.
+ *
+ * NOTE: Fetching alone does NOT bind variant selections or quantities. On a product detail page,
+ * prefer `initBundleProducts(product)` — it calls this function and then initializes selections,
+ * quantities, and the cart-edit (`editLineID`) flow. Use `getBundleProductsOfVariant` directly
+ * only when you need to re-fetch for a different variant without full re-initialization.
  *
  * @ai-category Product, Variant
  * @ai-related initBundleProducts, setProductOfBundleProduct, getSelectedProductVariant

package/dist/router/index.d.ts

@@ -61,15 +61,19 @@ export declare class Router {
      * @ai-category Navigation
      * @ai-related navigate, goBack
      *
-     * @param pageType - The type of page to navigate to (INDEX, CART, CHECKOUT, PRODUCT, LOGIN, etc.)
+     * @param pageType - The type of page to navigate to. Typed as `IkasThemePageType`.
      * @param slug - Optional slug for pages that require it (e.g., product slug, order ID)
      * @param queryParams - Optional query parameters to add to the URL
      * @param shallow - If true, only update URL without full navigation (default: false)
      * @param newTab - If true, open in a new browser tab (default: false)
      *
-     * Page types: INDEX, ACCOUNT, ADDRESSES, FAVORITE_PRODUCTS, FORGOT_PASSWORD, LOGIN,
-     * REGISTER, ORDERS, ORDER_DETAIL, BLOG_INDEX, BLOG, BLOG_CATEGORY, CART, CHECKOUT,
-     * CUSTOM, RAFFLE, RAFFLE_DETAIL, SEARCH, NOT_FOUND
+     * Accepted page types (`IkasThemePageType`): INDEX, ACCOUNT, ADDRESSES, FAVORITE_PRODUCTS,
+     * FORGOT_PASSWORD, LOGIN, REGISTER, ORDERS, ORDER_DETAIL, BLOG_INDEX, BLOG, BLOG_CATEGORY,
+     * CART, CHECKOUT, CUSTOM, RAFFLE, RAFFLE_DETAIL, SEARCH, NOT_FOUND.
+     *
+     * TypeScript note: `pageType` is typed as `IkasThemePageType`, not `string`. If you are
+     * passing a value that TypeScript infers as `string` (e.g. from a lookup map keyed by tab
+     * name), cast with `as IkasThemePageType` or type the source map with `Record<..., IkasThemePageType>`.
      *
      * @example
      * ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikas/bp-storefront",
-  "version": "0.130.0",
+  "version": "0.132.0",
   "description": "A framework for the ikas blueprint storefronts.",
   "author": "ikas",
   "license": "ISC",