feat: mp-3076-kiva-credit-tip-toggle

[infante-jaime]

MP-3076 — Checkout: balance-toward-tip toggle (variant b)

Adds the checkout toggle that lets lenders choose whether their Kiva Credit pays
the tip, for the tip-from-balance experiment (epic MP-3000). The UI persists the
preference and renders the backend-owned manifest — no client-side allocation math.

6 files, +413/−3. Layout/cosmetic changes that were originally in this PR have
been split out to MP-3154 at review request.

How it works

The toggle — KivaCreditTipToggle.vue

Renders in the tip row for variant b when the lender is logged in, has balance

$0, has a loan in the basket, and a tip > $0. Hidden at a $0 tip and returns
with its previous state when a tip comes back.

State is read from Manifest.applyKivaCreditToDonation (added to
initializeCheckout); changes call the merged updateKivaCreditDonationPreference
mutation, which returns the rebuilt manifest with totals, then emit the existing
refreshtotals. Failures toast and refresh so a stale basket recovers.

Tracking fires basket / click / tip-from-balance-toggle-on|off on explicit
changes only — nothing fires for the default state.

Seeding the default-off — the eng call the ticket left open

Treatment has to default OFF, but applyKivaCreditToDonation is a Boolean! that
can't distinguish "never chose" from "chose yes", so the value alone can't drive
seeding. On the first eligible render of a variant-b basket still reading true,
the component fires the mutation once with false and records the basket id in a
kvtipseeded cookie; a marked basket is never re-seeded, so an explicit lender
choice is never overwritten. The toggle stays hidden until the manifest and the
rendered state agree.

Known edge case: clearing that cookie while the preference is ON re-seeds it off
on the next eligible render. Accepted trade-off of client-side seeding.

Assignment — read once in CheckoutPage.created() and provided to descendants
via provide/inject, following the existing customTipDefaultVersion pattern in
the same file. No exposure tracking here; MP-3077 owns that.

Testing

10 specs covering control, seeding, re-seed protection, each hide condition,
tip-zero reappearance, persistence + tracking, and the failure/revert path.
Full suite green (330 files / 5,166 tests); ESLint, Stylelint and GraphQL lint clean.

Manually verified on dev: seeding fires exactly once per basket, the choice
survives reloads, on/off events fire, $0-tip hides and restores, control unchanged.

Before launch (not in this PR)

• Prod settings manager: uiexp.checkout_tip_from_balance_toggle plus appending
  checkout_tip_from_balance_toggle to ui.active_experiments. No space after
  the comma — the resolver splits on , without trimming, so a leading space
  makes the key silently unmatched. Dev is configured.
• Experiment tracking key (EXP-MP-3006-Aug2026 vs a rename) still needs settling
  in the epic before MP-3077 wires exposure.
• FYI: Figma's text-secondary is #505050 (gray-600) while @kiva/kv-tokens ships
  #757575 — the label uses tw-text-gray-600 to match the design.

[dyersituations]

Changes look good, and I tested it locally, but I want to get at least one more set of eyes on the changes before I approve due to this being such a critical part of Kiva. @infante-jaime thanks for digging into the questions I added comments for!

[infante-jaime]

Changes look good, and I tested it locally, but I want to get at least one more set of eyes on the changes before I approve due to this being such a critical part of Kiva. @infante-jaime thanks for digging into the questions I added comments for!

thanks for reviewing! good questions make better code.

[roger-in-kiva]

Looks like tablet and medium screens (1024px) is not fitting well:

Also ensure mobile is like expected:

[infante-jaime]

Looks like tablet and medium screens (1024px) is not fitting well:

Also ensure mobile is like expected:

fixed. there's also a copy ticket coming that shortens the cta to "learn more", so this'll look neater once that lands — worth another look then.

updated the text early just to make it fit better

[cristhianDt]

@infante-jaime probably is not related but I saw the toggle first then I decided No donation to Kiva then this checkbox broke the design (desktop and tablet), look

[cristhianDt]

spacing is greater than mocks also margin-top, try to remove the margin-bottom of the copy container (should fix the margin-top issue)

[infante-jaime]

fixed

[cristhianDt]

(optional) no a big issue just check the gab I keep seeing 16px, mocks has 8px > https://www.figma.com/design/H0RJzgOoeuFmdH8ggDX2c1/Donations-from-deposits?node-id=122-4616&m=dev and margin-top 16px not 8px

[infante-jaime]

@infante-jaime probably is not related but I saw the toggle first then I decided No donation to Kiva then this checkbox broke the design (desktop and tablet), look

actually as weird as it looks is how it is in dev checking with design if we can update that by taking the toggle space

[cristhianDt]

the feature and integration looks good, great job @infante-jaime, just an edge case to confirm (already commented)

here my TCs executed:

Legend: ✅ OK (tested & passing)

#	Test case	Precondition	Expected	Status
1	Toggle appears for eligible user	Variant b, logged in, balance > $0, loan in basket, tip > $0	Toggle renders in the tip row	✅
2	Seed cookie saved on first render	N°1, kvtipseeded absent	kvtipseeded cookie set to basket id	✅
3	First render seeds OFF	N°1, basket preference untouched	One updateKivaCreditDonationPreference(false) fires; toggle shows OFF; no tip-from-balance-toggle-on/off analytics on default	✅
3b	No re-seed on second refresh (cookie present)	After N°3, don't clear cookie or touch toggle → refresh again	No mutation fires; toggle stays OFF (proves once-per-basket seeding)	✅
4	No balance → toggle hidden	Variant b, user with no Kiva credit / $0 balance	Toggle not rendered; no seeding mutation	✅
5	Zero the tip → toggle hides	Toggle visible, then set tip/donation to $0	Toggle disappears (or disabled); no errant mutation	✅
6	Re-add positive tip → toggle reappears with persisted state	After N°5, set tip back to a positive amount	Toggle reappears in previously selected state; no re-seed mutation	✅
7	Toggle ON applies balance to tip	Toggle visible OFF	...(true) fires; credit rises, amount due drops; event basket / click / tip-from-balance-toggle-on	✅
8	Toggle OFF returns to deposit state	Toggle ON	...(false) fires; tip becomes amount due, payment form appears; event basket / click / tip-from-balance-toggle-off	✅
9	Persistence across reload	Toggle set to a non-default state	After full reload, toggle returns in same state; totals match	✅
10	Hidden with no loan (toggle ON path)	Add loans + tip → toggle ON → remove all loans	Toggle hidden; donation stays with credit applied (= platform default, not a bug)	✅
10b	Hidden with no loan (toggle OFF path)	Add loans + tip → toggle OFF → remove all loans	Toggle hidden; credit withheld from donation (honors explicit choice)	✅
11	Control (variant a) unchanged	Force variant a, otherwise eligible	No toggle; no mutation; balance applies to tip as today	✅
12	Reset outside the variant	Basket at preference false in b, then render under variant a	One ...(true) fires; kvtipseeded removed; totals revert; payment form waits for new amount	✅

[cristhianDt]

I dont have any other feedback, just the spacing thread

[dyersituations]

@infante-jaime the spacing issues are not currently affecting control? Just want to make sure if this gets merged that the non-experiment/current experience isn't changed. We'll be releasing ui soon.

[infante-jaime]

@infante-jaime the spacing issues are not currently affecting control? Just want to make sure if this gets merged that the non-experiment/current experience isn't changed. We'll be releasing ui soon.

This shouldnt be an issue by design there are no ui changes for the control just in the experiment and in this particular case is the toggle spacing.

So I guess we are good to go and any layout concerns can be addressed here

[kiva-robot]

🎉 This PR is included in version 3.92.0-rc.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[kiva-robot]

🎉 This PR is included in version 3.92.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀