Promotion V2

flowchart TD

%% BACKEND → PRODUCT
A[Backend API] --> B[Product Model]

B --> |otherAttributes| C[PromotionV1 Data]
B --> |promoMessages| D[PromotionV2 Data]

%% PROMOTIONV1 DECISION
C --> E[Check Feature Flag: hasPdpPromotionalMessage]
E --> |promoMessages is EMPTY| F[Show PromotionV1]
E --> |promoMessages NOT empty| G[Hide PromotionV1]

%% PROMOTIONV2 ENTRY
D --> H[Filter validPromoMessages]
H --> |valid messages exist & hasBulkSaveDiscountPromotion is true| I[Render PromoWidgetBuilder]

%% PROMOTIONV2 TYPE SELECTION
I --> J{promo.type}

J --> |Bulk Save| K[BulkSaveDiscountWidget]
J --> |Free Promo| L[FreePromotionalProductsWidget]
J --> |Multi-Buy| M[MultiBuyDiscount]
J --> |Bundle| N[BundlePromotionalProductsWidget]
J --> |Unknown| O[Hidden]

%% TROLLEY INTERACTION
L --> P[User selects free/bundle items]
N --> P
P --> Q[Add selected items to trolley]

const Product({
  required this.otherAttributes, // PromotionV1 comes inside otherAttributes (ID: 302)
  required this.promoMessages,   // PromotionV2 data
  // ...other fields
});

{
  "data": {
    "other_attributes": [
      {
        "id": 83,
        "key": "Product Review Rating",
        "value": "4.25"
      },
      {
        "id": 302,  // PromotionV1 Uniuqe Id: 302
        "key": "Promo Message", // PromotionV1 keys 
        "value": "<b>ACTIE</b> Deze week 25% korting op Sola waterpassen. Deze actie is geldig t/m 24 november 2025. Kijk <a href=\"https://www.toolstation.nl/search?q=weekdeal\">hier</a> voor alle weekdeals." // PromotionV1 Value in html format to support link click
      },
      {
        "id": 10098,
        "key": "red tag",
        "value": "Weekdeal"
      }
    ],
    "promo_messages": [ // PromotionV2 - Bulk Save Promotion API Response
      {
        "message": "BULK SAVE: Buy More, Save More",
        "headline": "BULK SAVE",
        "sub_heading": "Buy More, Save More",
        "body": null,
        "item_selector": {
          "match": "itemIds",
          "ids": [
            "30852"
          ]
        },
        "group_selector": {
          "list": {
            "match": "itemIds",
            "ids": [
              "30852"
            ]
          },
          "field": "quantity",
          "count": 1,
          "max": 0
        },
        "discount_values": [
          {
            "count": 3,
            "value": 5
          },
          {
            "count": 6,
            "value": 10
          }
        ],
        "discount_table": [
          {
            "qty": "1 - 2",
            "discount": "0%",
            "price": "£0.55"
          },
          {
            "qty": "3 - 5",
            "discount": "5%",
            "price": "£0.52"
          },
          {
            "qty": "6+",
            "discount": "10%",
            "price": "£0.50"
          }
        ]
      },
    ]
  }
}

 List<String> get promotionalMessages {
  return otherAttributes
      .where((attribute) => attribute.id == AttributeId.promotionalMessage)
      .map((attribute) => attribute.value)
      .toList(growable: false);
}

const PromoMessage({
  required this.message,
  required this.headline,
  required this.subHeading,
  required this.body,
  required this.promotionalProducts,
  required this.discountValues,
  this.discountTable,
  this.groupSelector,
});

if (hasPdpPromotionalMessage && promoMessage.isEmpty)
  for (var i = 0; i < promotionalMessages.length; i++)
    Padding(
      padding: horizontalPadding24,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        children: [
          verticalMargin16,
          PromotionalMessage(
            message: promotionalMessages[i],
            expiryDate: promotionalMessageExpiries.elementAtOrNull(i),
          ),
        ],
      ),
    ),

cconst PromoWidgetBuilder({
  super.key,
  required this.promo, // PromoMessage Type
  required this.productCode, // ProductCode String
});

  if (hasBulkSaveDiscountPromotion && validPromoMessages.isNotEmpty) ...[
  ListView.separated(
    shrinkWrap: true,
    physics: const NeverScrollableScrollPhysics(),
    itemCount: validPromoMessages.length,
    separatorBuilder: (_, _) => verticalMargin16,
    itemBuilder: (context, index) {
      final promo = validPromoMessages[index];
      return PromoWidgetBuilder(
        key: Key('promotion-builder-widget-$index'),
        promo: promo,
        productCode: product.code,
      );
    },
  ),
],

  List<PromoMessage> get validPromoMessages {
  return product.promoMessages.where((promo) => promo.isValidPromo).toList();
}

  bool get isValidPromo => type != PromoType.unknown;

switch (promo.type) {
  case PromoType.bulkSave:
    return BulkSaveDiscountWidget(...);
  case PromoType.freePromo:
    return FreePromotionalProductsWidget(...);
  case PromoType.multiBuy:
    return MultiBuyDiscount(...);
  case PromoType.bundle:
    return BundlePromotionalProductsWidget(...);
  case PromoType.unknown:
    return emptyWidget;
}

BulkSaveDiscountWidget(
  message: promo.message,        // Used only when both headline & subHeading are empty
  headline: headline,            // Main heading (red text)
  subHeading: subHeading,        // Subheading displayed below the headline
  discountRows: discountRows,    // Used to build the discount table (quantity tiers)
);

FreePromotionalProductsWidget(
  headline: headline,                                 // Main heading (red text)
  subHeading: subHeading,                             // Subheading below the headline
  body: body,                                         // Explanation for the offer
  promotionalProducts: excludedProducts,              // Products eligible for free offer (excluding the root PDP item)
  onUpdateSelectedPromotionalProduct: bloc.onUpdateSelectedPromotionalProduct, // Handles checkbox selections and adds items to trolley
);

MultiBuyDiscount(
  headline: headline,     // Main heading (red text)
  subHeading: subHeading, // Subheading below the headline
  body: body,            // Explanation text for the offer
);

BundlePromotionalProductsWidget(
  headline: headline,                     // Main heading (red text)
  subHeading: subHeading,                 // Subheading below the headline
  body: body,                             // Explanation text for the bundle
  promotionalProducts: excludedProducts,  // Products included in the bundle (excluding root PDP product)
);

 void onUpdateSelectedPromotionalProduct({
    int? quantity,
    required bool isChecked,
    required PromotionalProduct promotionalProduct,
  }) {
    final selectedPromotionalProducts = currentState.selectedPromotionalProducts.toList();
    final index = selectedPromotionalProducts.indexWhere(
      (e) => promotionalProduct.code == e.promotionalProduct.code,
    );
    final isAlreadyInList = index != -1;

    if (!isChecked) {
      if (isAlreadyInList) {
        selectedPromotionalProducts.removeAt(index);
        _state.add(currentState.copyWith(selectedPromotionalProducts: selectedPromotionalProducts));
      }
    } else {
      if (isAlreadyInList) {
        selectedPromotionalProducts[index] = PromotionalProductWithQuantity(
          promotionalProduct: promotionalProduct,
          quantity: quantity,
        );
        _state.add(currentState.copyWith(selectedPromotionalProducts: selectedPromotionalProducts));
      } else {
        selectedPromotionalProducts.add(
          PromotionalProductWithQuantity(
            promotionalProduct: promotionalProduct,
            quantity: quantity,
          ),
        );
        _state.add(currentState.copyWith(selectedPromotionalProducts: selectedPromotionalProducts));
      }
    }
  }

  const PromotionalProduct({
    required this.code,       // Productcode (String)
    required this.name,       // Product Name (String)
    required this.image,      // Product Image (String)
    required this.priceGross, // Product Price with VAT
    required this.priceNet,   // Product Price without VAT
  });

  bool get hasPdpPromotionalMessage => isFeatureFlagEnabled(FeatureFlag.pdpPromotionalMessage);

    bool get hasBulkSaveDiscountPromotion => isFeatureFlagEnabled(FeatureFlag.pdpBulkSaveDiscountPromotion);