Repos that we’ll change

Whitelabel: https://github.com/rbilabs/intl-whitelabel-app

RBI Sanity Shared Schemas: https://github.com/rbilabs/rbi-sanity-shared-schemas

Whitelabel CMS: https://github.com/rbilabs/intl-whitelabel-cms

Figma: https://www.figma.com/file/sfH3mHXoEUfHbm5qMul0Vn/branch/VNb1dzeeYVV0IphMPJo0lt/Popeyes?type=design&node-id=3189-125398&t=b8GDYgoS6YtWAr0K-0

Solution overview

We’ll extend the “AddOn section” (that we already use for the “Bag with Handles” solution) and add there the new logic to handle add-on free items.

Task summary

RBI Sanity Shared Schemas/Whitelabel CMS:

Task 1: Add a new toggle to enable the “free items” on AddOnSection
- Task 2: Extend the Option item to have new fields
- Task 3: Create a new section (fieldset) for the free-addon modal

Whitelabel:

Task 1: Create a new feature flag (enable-free-addon-on-cart)
- This flag will condition the new logic added in the AddOnsItemsContainer
Task 2: Update types and graphql after changes in the CMS repo
Task 3: Create a new component to show the add-on free modal
Task 4: Add a description on the AddOnsItemsContainer section for the addon-free items
Task 5: Add a logic on AddOnsItemsContainer to show the free item or the paid item
Task 6: Add a logic to deal with the quantity of free items and paid items on the cart
Task 7: Add the informative description to the free item on the cart
Task 8: Adjust the extras modal quantity limit for the free item

Tasks breakdown

RBI Sanity Shared Schemas

Order in UI

New toggle
New items selection section
New fieldset with the fields:
- Modal image field
- Modal title
- Modal description
- Modal text button

Task 1: Add a new toggle to enable the “free items” on AddOnSection

Motivation: this toggle will enable the new feature integration for “free/promotional items” on the cart
Label: Make options in this section as free add-ons
Description: By turning this on, guests will be able to add the options in the list of add-ons for free to their order. You can choose which items in the order are eligible to grant free add-ons and also how many add-on units will be free of charge per item.
Rules:
- Toggle should only be visible by Intl market: hidden: () => !ctx.isIntl

PATH FOR THE SOLUTION

Add the new toggle on /src/schemas/menu/documents/add-on-section.tsx

DOD-LIKE

The initial value for this toggle: FALSE
This toggle should only be visible to Intl market hidden: () => !ctx.isIntl

Task 2: Extend the Option item to have new fields

Motivation: we’ll need to configure the addon free configuration for each add-on (paid) selected on the main page of the section

We’ll have two new fields: “Free addon item” and “Menu items to offer the free item” on the add-on-section-option.ts:

“Free addon Item”

Label: (to be defined)
Description: (to be defined)
Rules:
- Type reference to type item (as the “Option” that we already have on the screen)
- Should be hidden if:
  - !ctx.isIntl AND !ctxTest.document.enableAddonAsFreeItem
- Required/invalid if:
  - context?.document?.enableAddonAsFreeItem && !value (validation prop with custom rule)

“Menu items to offer the free item”

Label: (to be defined)
Description: (to be defined)
Rules:
- Type array to type addOnSectionMenuOptions (suggestion of name… we’ll create the new object that will be used here)
- Should be hidden if:
  - !ctx.isIntl AND !ctxTest.document.enableAddonAsFreeItem
- Required/invalid if:
  - context?.document?.enableAddonAsFreeItem && !value (validation prop with custom rule)

Hide the field Maximum amount

Motivation: we’ll use the sum of the menu items limit to configure on the Whitelabel UI the desired limits for each item (configured on the new object below)

Create the new object (addOnSectionMenuOptions)

File name: add-on-section-menu-options.ts
Folder: ./src/schemas/menu/objects
Put it on the build-shared-schemas: ./src/build-shared-schemas.ts
This file will have a structure similar to the add-on-section-option.ts
Configure the preview on the object to show the item name and the free quantity info

For this object we’ll have:

“Free quantity”

Label: (to be defined)
Description: (to be defined)
Rules:
- validation: (Rule: any) => Rule.min(1)
- initialValue: 1
- Type: number

“Menu item”

Label: (to be defined)
Description: (to be defined)
Rules:
- Type reference to type item (as the “Option” that we already have on the screen)
- validation: (Rule: any) => Rule.required()

DOD-LIKE

Add the new fields on the UI
Create the new object for the menu item options
Follow the rules for each field
- “Free addon item” should be filled if the free addon toggle is ON
- “Menu items to offer the free item” should have at least one item if the free addon toggle is ON
Hide the maximum amount field

Task 3: Create a new section (fieldset) for the free-addon modal

Motivation: configure the add-ons free modal. The fieldset will help the organization, by grouping the fields
Label: (to be defined)
Description: (to be defined)
Rules:
- The fieldset should not be collapsed when appears (DOC)
- All fields should be children of the fieldset
- The fieldset should only be visible if the toggle for add-on free items is ON

We also will have the following fields inside this fieldset:

Image field

Modal toggle (to show/hide on the Whitelabel App):
- Label: (to be defined)
- Description: (to be defined)
Modal title field
- Label: (to be defined)
- Description: (to be defined)
Modal description field
- Label: (to be defined)
- Description: (to be defined)
Modal primary button field
- Label: (to be defined)
- Description: (to be defined)
Rules:
- If the toggle is ON
  - The title and primary button should be filled in and are required. This is needed to prevent the user from publishing the document and to not show an empty modal on the Whitelabel App
  - Description and image fields are optional

PATH FOR THE SOLUTION

For the fieldset, we have the Hero example on the Intl CMS repo and the doc from Sanity above
For the image, we can take a look at the item document from the CMS or other documents that have an image field and make the same

DOD-LIKE

All the fields should be children of the modal fieldset
The fieldset should not be collapsed when appears
Condition the new fieldset to be visible only if the new toggle is TRUE

Whitelabel

Task 2: Update types and graphql after changes in the CMS repo

Add the new props in the add-on-section.graphql query
- Path: src/queries/sanity/fragments/add-on-section.graphql
- Add the new name for the free addon toggle
Create a new fragment for the addOnSectionMenuOptions and update the add-on-section-option.graphql query
- Path: ./src/queries/sanity/fragments/add-on-section-option.graphql
yarn run apollo:generate
Clear the generated file just with the needed changes

Update the Interface for the use-feature-menu-add-on.tsx
- Path: src/hooks/use-feature-menu-add-on.tsx
- Some unit tests will break and we’ll need to adjust them

PATH FOR THE SOLUTION

We are not creating anything 100% new. All the new fields have something similar to the other structures from the add-on. We just need to follow the same pattern

DOD-LIKE

After adding the new interfaces open the AddOnsItemsContainer component and add a console log to see if the values from Sanity will be available in the sections. Do some tests (changing the values on Sanity) to see if all is good

Task 3: Create a new component to show the add-on free modal (PENDING)

Create a new sub-component that will be used on the add-on free promotion info

Rules:
- As we can have multiple sections on Sanity we’ll have to present the modal content with a “pagination” system
  - We can use the nuka-carousel lib (we already have this on the application)
  - We can use simple buttons with arrows on the sides of the modal
- The text for the title, description, and primary button (the orange one) will come from Sanity
- The text for the secondary button will be fixed on the “Not Now” label. We’ll add this to the main en.json file and run the lokalize after that
- If the image is not configured on Sanity the empty space should not be there
- The modal should only be shown
  - If the respective toggle from Sanity is ON
  - If we have on the cartEntries at least one menu item configured for the addon extra item that was added to the cart on the first load
- If the user clicks on the primary button we’ll add all the items that come from Sanity into the cart
  - We can have some combinations here:
    - If we configure on Sanity to have the free item for two menu items and we add the two menu items to the cart we’ll offer to the user 2 free items (1 free item default per menu item)
    - If we configure on Sanity the menu items and fill the “quantity free” field this will be an override and we’ll need to offer the sum of the quantities

PATH FOR THE SOLUTION

He has multiple examples of modals in the application (agreements modal, etc). I don’t see any component that will help us. The Dialog from ctg-components-library did not accept content from what I saw.
For the architecture suggestion:
- The idea is to have a new components folder for this new comp that will be responsible to deal with the modal

Suggested props/interface for the new component

interface IAddOnsFreeModal {
  cartEntries: ICartEntry[]; // this is necessary to know if we'll show the modal based in whats in the cart entries
  addOnSections: IAddOnSection[]; // another option is to receive the addon free from the parent directly
  addItemToCart: (items: IBaseItem) => void;
}

I think that the modal should be responsible for our internal state to know if will be shown or not and if we click on the addToCart we’ll run the handleAddToCart from the parent component

DOD-LIKE

Respect all points from the Rules section
Create the new component folder and necessary files
Implement unit tests
The colors for the background, buttons, and texts should follow the brand theme
Validate the layout on: Web and native devices

Task 4: Add a description on the AddOnsItemsContainer section for the addon-free items

Rules:

If the add-on free toggle is ON we’ll show the description in the section

PATH FOR THE SOLUTION

This text will be fixed on the code but concatenated with the dynamic info. Example:

`You can add up to ${quantityFromSanity} extra ${item.name} for your order. Additional ${item.name} will cost ${item.price}`

OBS: this is only an example and will not be exactly this.

This change new feature will be made inside the AddOnsItemsContainer

DOD-LIKE

Respect all points from the Rules section
The styles should be as Figma
Implement the unit tests
Validate in web and native

Task 5: Add a logic on AddOnsItemsContainer to show the free item and the paid item

The behavior that we want on the UI is to show the desired addon (free or paid) based on the below rules. We’ll not want to see the two items in the section at the same time. It’s always one or the other.

Rules:

Hide the paid item:
- If the max quantity of free items is selected on the cart
Show the paid item:
- If the max quantity of free items was not selected yet
Show the free or paid item:
- Besides the logic above we also need to see if the match happens = The configured menu item(s) on Sanity match with what we have added to the cart
OBS: This will be something dynamic as the user can edit the items or add new items that can affect this

PATHS FOR THE SOLUTION (2 options)

We can adjust the methods responsible to render the items inside the section to have this behavior
We can create a new subcomponent to be responsible to render the items

DOD-LIKE

Respect all points from the Rules section
Implement new unit tests for the new behavior

Task 6: Add a logic to deal with the quantity of free items and paid items on the cart

As we’ll have the two items on the cart we’ll need to follow some behaviors

Rules:

Case 1:
- The client configures on Sanity that we’ll offer 4 free ketchup for “The sandwich menu” item
- The user adds all the free items but decides to add an extra paid ketchup
- If the user changes the quantity of “The sandwich menu” to 2
  - Now we’ll offer 8 free items for the client (always double from what’s in Sanity)
  - With that, we’ll need to remove the paid ketchup and add 1 to the free items (4 → 5). The client should not pay for an item if the free quantity has been increased
Case 2:
- The client configures on Sanity that we’ll offer 4 free ketchup for “The sandwich menu” item
- The user changes the quantity of “The sandwich menu” to 2
- Now the user selects all 8 free ketchup items on the cart
- Then, the user decides to change the quantity of “The sandwich menu” to 1 again
  - Now we’ll need to remove 4 from the free quantity (8 → 4)
Case 3:
- The client configures on Sanity that we’ll offer 4 free ketchup for “The sandwich menu” item and for the 4 for some chicken
- The user adds “The sandwich menu” on the cart
- Now he has 4 free ketchups available to select
- The user goes out of the checkout page and goes to the menu. Then, selects the chicken
- Now the user has 8 free ketchups available (4 + 4)
…. and so on hahahaha, this can be very dynamic

PATH FOR THE SOLUTION

First of all, we’ll need to look at what’s configured on Sanity (the free quantity field)
…Work in progress…

DOD-LIKE

Respect all points from the Rules section

Task 7: Add the informative description to the free item on the cart

I think that we’ll not need to involve the back end for this functionality. My main idea is to let this responsibility for the FE application (to reduce the complexity)

Rules:

The quantity of free offered items must be the sum of all the offered items (considering the configuration of the menu item on Sanity)
This quantity can also change by the combination of the items on the cart
Condition this description to be shown only if our flag is ON, the free toggle is ON and the price is zero (just to be secure about the behavior)

PATHS FOR THE SOLUTION (2 options)

Use the useFeatureMenuAddOn to get the information from Sanity and develop the new logic inside the cart-item (./src/components/cart-item/index.tsx) component (shown above)
Create a new context/hook that will be responsible to get this information and share between the components (description in the addon section and on cart-item)

DOD-LIKE

Respect all points from the Rules section
The styles should be as Figma
Implement new unit tests

Task 8: Adjust the extras modal quantity limit for the free item

Rules:

The quantity limit should respect the following rule:
- sum the free quantity limits from Sanity (looking into each menu item because we can have all the items at the same time depending on the case)
- Respect the maximum limit that is configured on Sanity (the default is 9). Well always need to respect this limit:
  - Even if the sum is equal 10 and the limit is 9 the maximum will be 9
- If the maximum was reached the “+” button will be disabled

PATH FOR THE SOLUTION

As the modal is already using the data from Sanity we’ll just need to develop this new logic for the limit
- Create a new method to handle this
- If we choose the creation of a new hook/context (task 7) perhaps we can catch this info from there and just use it on the modal when our flag is ON

DOD-LIKE

Respect all points from the Rules section
Implement new unit tests

Technical refinement (work in progress)

Solution overview

Task summary

Tasks breakdown

RBI Sanity Shared Schemas

Order in UI

Task 1: Add a new toggle to enable the “free items” on AddOnSection

Task 2: Extend the Option item to have new fields

Task 3: Create a new section (fieldset) for the free-addon modal

Whitelabel

Task 2: Update types and graphql after changes in the CMS repo

Task 3: Create a new component to show the add-on free modal (PENDING)

Task 4: Add a description on the AddOnsItemsContainer section for the addon-free items

Task 5: Add a logic on AddOnsItemsContainer to show the free item and the paid item

Task 6: Add a logic to deal with the quantity of free items and paid items on the cart

Task 7: Add the informative description to the free item on the cart

Task 8: Adjust the extras modal quantity limit for the free item