@salla.sa/twilight-components 2.14.589 → 2.14.591

package/dist/collection/shared/offer-stages.js

@@ -0,0 +1,453 @@
+/*!
+ * Crafted with ❤ by Salla
+ */
+/**
+ * Multi-stage promotion progress.
+ *
+ * Pure, component-agnostic helpers for turning a shopper's current cart value
+ * plus a list of stage thresholds into "which stage is Locked / Current /
+ * Completed, and how full is each segment".
+ *
+ * Deliberately NOT shared with `salla-tiered-offer`'s `TierUtils`:
+ *  - `TierUtils.findCurrentTierIndex` is 1-based with `0` overloaded to mean
+ *    "no tier reached", which cannot express "stage 0 is reached".
+ *  - It takes `TieredOfferTier[]`, a shape a conditional-offer `Discount` does
+ *    not share a single field with.
+ *  - It assumes its caller already sorted; the conditional-offer payload is
+ *    emitted UNSORTED by the backend.
+ *
+ * So this module takes plain numbers, is 0-based, uses an explicit
+ * `NO_STAGE_REACHED` sentinel, and sorts defensively on every call.
+ *
+ * ONE deliberate exception to "pure": `getCurrencyDecimals()` reads the store's money
+ * precision off `salla.config` so that `getRemainingToStage()` can round AT THE SOURCE
+ * and every consumer — including the `products_count` path that never touches
+ * `salla.money()` — benefits without each of them remembering to. It is fully guarded and
+ * falls back to `DEFAULT_CURRENCY_DECIMALS`, so a missing SDK degrades rather than throws;
+ * callers that want it hermetic can pass the measure and stub `salla.config`.
+ *
+ * ---------------------------------------------------------------------------
+ * WHO DECIDES A TIER IS UNLOCKED
+ * ---------------------------------------------------------------------------
+ * The ENGINE does, and it now says so: every `details.discounts[]` entry carries
+ * `is_applied`. Threshold arithmetic here is a PROJECTION ("how far to go"), never a
+ * CLAIM about what the engine granted, because the engine's formula
+ *
+ *     ($subtotal - $alreadyAppliedDiscount) - $excludedItemsAmount >= min_spend
+ *
+ * uses two terms that are not in the payload at all. On beta a gift tier at `min_spend`
+ * 300 with `current_value` 300 rendered as unlocked while the engine had refused it (the
+ * gift's own price is in that tier's excluded set), so no arithmetic over shipped keys
+ * could ever have agreed with it.
+ *
+ * BUT `is_applied` IS NOT "THE SHOPPER IS PAST THIS TIER". It answers a narrower
+ * question, and reading it as the broader one is what produced the second beta report.
+ * `CartOfferDiscount::apply()` walks the tiers, keeps the LAST one whose conditions pass
+ * and calls `discountItem()` ONCE after the loop, so a cart offer grants EXACTLY ONE
+ * reward — the best qualifying tier. Every earlier tier is therefore `is_applied: false`
+ * even for a shopper who sailed past it: its reward is SUPERSEDED, not out of reach. A
+ * cart at `current_value` 510 came back as `false / false / true` and the badge row read
+ * LOCKED / LOCKED / CHECKED, which is unreadable as a progress stepper.
+ *
+ * So there are TWO questions and this module answers both, separately:
+ *  - "which tier gave the reward" — the single winner, `appliedIndex`.
+ *  - "is the shopper past this tier"  — cumulative, `met`, which is what the ✓, the
+ *    strikethrough, the lock and the "N of M" count render from.
+ *
+ * The passed tiers carry a ✓ AND a strikethrough while the tier ahead carries a lock.
+ * Struck-through means superseded, so a ✓ means THRESHOLD PASSED, not REWARD GRANTED.
+ *
+ * Hence the split, and it is load-bearing:
+ *  - `met` / `metCount` / `nextUnmetIndex` / `allMet` are the ENGINE-DERIVED verdict.
+ *    Render from these.
+ *  - `appliedIndex` names the one tier that actually paid out. Diagnostics only so far.
+ *  - `lastReachedIndex` / `currentIndex` / `isComplete` / `fills` / `overallPercentage`
+ *    are pure threshold projections. Use them for distance and bar geometry only.
+ *
+ * `is_applied` is TRI-STATE, because twilight and the Store package deploy independently:
+ * absent means "this backend does not report it yet" and falls back to the arithmetic,
+ * while `false` is a real verdict and outranks the arithmetic. See `readAppliedFlag`.
+ *
+ * `salla-tiered-offer` keeps its own copy of the defensive ascending sort and the
+ * completed/total ratio; that duplication is deliberate and not migrated here.
+ */
+/** Explicit sentinel: no stage has been reached yet (or there is no next stage). */
+export const NO_STAGE_REACHED = -1;
+export var OfferStageState;
+(function (OfferStageState) {
+    OfferStageState["LOCKED"] = "locked";
+    OfferStageState["CURRENT"] = "current";
+    OfferStageState["COMPLETED"] = "completed";
+})(OfferStageState || (OfferStageState = {}));
+function parseNumeric(value) {
+    const parsed = typeof value === 'number' ? value : parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * Read one tier's `is_applied` as a tri-state.
+ *
+ * `true`/`false` booleans are what `CartOffersTransformer` casts and emits. The numeric
+ * and string spellings are accepted too because the `s-source: mobile` pipeline already
+ * stringifies numeric fields in this very payload (`end_value`), and reading a `0` there
+ * as "absent" would silently restore the bug this exists to fix.
+ *
+ * EVERYTHING ELSE — key missing, `undefined`, `null`, `''`, an object — is ABSENT, not
+ * `false`: a value we cannot interpret is not the engine saying no, and must degrade to
+ * the arithmetic fallback rather than lock a tier the shopper has genuinely earned.
+ */
+export function readAppliedFlag(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 1 || value === 0)
+        return value === 1;
+    if (value === 'true' || value === '1')
+        return true;
+    if (value === 'false' || value === '0')
+        return false;
+    return undefined;
+}
+/**
+ * Coerce a cart VALUE. Falling back to 0 is correct here: an unreadable
+ * `current_value`/`start_value` means "the shopper has made no progress".
+ */
+function toFiniteNumber(value) {
+    return parseNumeric(value) ?? 0;
+}
+/**
+ * Whether a THRESHOLD is usable.
+ *
+ * Thresholds get the opposite policy to values: an unparseable threshold is DROPPED,
+ * never coerced to 0, because a 0 threshold is satisfied by an empty cart and would
+ * render as an already-COMPLETED stage — reintroducing exactly the synthetic-zeroth-
+ * checkpoint bug this component was rewritten to remove.
+ *
+ * Callers that keep their own parallel array of stage objects MUST filter it with this
+ * predicate so their index alignment with `progress.thresholds` survives the drop.
+ */
+export function isUsableThreshold(value) {
+    return parseNumeric(value) !== null;
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(value, max));
+}
+/**
+ * Fill of one segment as a 0..100 percentage.
+ * A zero-width (or inverted) segment — which duplicate thresholds produce — has
+ * no gradient to show, so it is all-or-nothing rather than a division by zero.
+ */
+function segmentFill(value, from, to) {
+    if (to <= from) {
+        return value >= to ? 100 : 0;
+    }
+    return clamp(((value - from) / (to - from)) * 100, 0, 100);
+}
+/**
+ * Stable ascending sort of arbitrary items by a numeric threshold accessor.
+ *
+ * Ties are broken by `getIdentity` when supplied and readable on BOTH sides — the tier
+ * `id` (0 = base tier, 1..N = configured options in the order the engine walks them), so
+ * two tiers sharing a `min_spend` order by what they ARE rather than by where they
+ * happened to land in an unsorted payload. Without it (or when either id is unreadable)
+ * ties keep their original relative order, which is the previous behaviour exactly.
+ */
+export function sortByThreshold(items, getThreshold, getIdentity) {
+    return (items ?? [])
+        .map((item, index) => ({
+        item,
+        index,
+        threshold: toFiniteNumber(getThreshold(item)),
+        identity: getIdentity ? parseNumeric(getIdentity(item)) : null,
+    }))
+        .sort((a, b) => {
+        if (a.threshold !== b.threshold)
+            return a.threshold - b.threshold;
+        if (a.identity !== null && b.identity !== null && a.identity !== b.identity) {
+            return a.identity - b.identity;
+        }
+        return a.index - b.index;
+    })
+        .map(({ item }) => item);
+}
+/**
+ * Derive the full stage picture from the server's `current_value`.
+ *
+ * @param currentValue the server-computed cart value — never recomputed client-side.
+ * @param rawThresholds each stage's `min_spend`, in any order.
+ * @param rawStartValue the baseline the first segment fills from (`details.start_value`).
+ * @param rawApplied each stage's `is_applied`, POSITIONALLY ALIGNED WITH `rawThresholds`
+ *        before any sorting or dropping happens here. Omit it and every tier reads as
+ *        absent, i.e. the threshold behaviour, unchanged.
+ * @param rawTierValues each stage's OWN `current_value`, aligned the same way. A tier
+ *        without a readable one is measured by `currentValue`, so omitting it — an older
+ *        backend — changes nothing. See `OfferStageProgress.values`.
+ */
+export function computeOfferStageProgress(currentValue, rawThresholds, rawStartValue = 0, rawApplied = [], rawTierValues = []) {
+    // Unparseable thresholds are dropped, not zeroed — see `isUsableThreshold`.
+    //
+    // The flag travels WITH its threshold through both the drop and the sort. Sorting two
+    // parallel arrays separately is how an `is_applied` ends up on the wrong tier, and a
+    // misattributed verdict is worse than no verdict at all. The tier's own value rides
+    // along for the same reason.
+    const entries = (rawThresholds ?? [])
+        .map((threshold, index) => ({
+        index,
+        threshold: parseNumeric(threshold),
+        applied: readAppliedFlag(rawApplied?.[index]),
+        tierValue: parseNumeric(rawTierValues?.[index]),
+    }))
+        .filter((entry) => entry.threshold !== null)
+        .sort((a, b) => a.threshold - b.threshold || a.index - b.index);
+    const thresholds = entries.map(entry => entry.threshold);
+    const applied = entries.map(entry => entry.applied);
+    const hasEngineVerdict = applied.some(flag => flag !== undefined);
+    const startValue = toFiniteNumber(rawStartValue);
+    if (!thresholds.length) {
+        return {
+            thresholds,
+            met: [],
+            applied,
+            appliedIndex: NO_STAGE_REACHED,
+            hasEngineVerdict,
+            metCount: 0,
+            nextUnmetIndex: NO_STAGE_REACHED,
+            allMet: false,
+            lastReachedIndex: NO_STAGE_REACHED,
+            currentIndex: NO_STAGE_REACHED,
+            isComplete: false,
+            value: Math.max(0, toFiniteNumber(currentValue)),
+            values: [],
+            startValue,
+            fills: [],
+            overallPercentage: 0,
+        };
+    }
+    const finalThreshold = thresholds[thresholds.length - 1];
+    // THE CLAMP: a stale or overshooting `current_value` must never produce a
+    // >100% bar or an out-of-range stage index.
+    const value = clamp(toFiniteNumber(currentValue), 0, Math.max(0, finalThreshold));
+    // Each tier against ITS OWN progress where the backend sent one — see `values`. A tier
+    // value that is missing or unreadable is not "no progress": it is "not reported", and
+    // falls back to the offer-level value rather than to 0.
+    const values = entries.map(({ tierValue }) => tierValue === null ? value : clamp(tierValue, 0, Math.max(0, finalThreshold)));
+    let lastReachedIndex = NO_STAGE_REACHED;
+    for (let index = 0; index < thresholds.length; index++) {
+        if (values[index] >= thresholds[index]) {
+            lastReachedIndex = index;
+        }
+    }
+    const isComplete = lastReachedIndex === thresholds.length - 1;
+    const currentIndex = isComplete ? NO_STAGE_REACHED : lastReachedIndex + 1;
+    const fills = thresholds.map((threshold, index) => segmentFill(values[index], index === 0 ? startValue : thresholds[index - 1], threshold));
+    const overallPercentage = isComplete
+        ? 100
+        : clamp(((lastReachedIndex + 1 + (fills[currentIndex] ?? 0) / 100) / thresholds.length) * 100, 0, 100);
+    // ---------------------------------------------------------------------------------
+    // THE DECISION — three cases, in this order.
+    //
+    // (1) THE ENGINE GRANTED A TIER. `appliedIndex` is the HIGHEST tier flagged `true`, and
+    //     every tier up to and including it is met. A cart offer pays out ONCE, at the best
+    //     qualifying tier, so the earlier tiers are `false` because they were SUPERSEDED —
+    //     the shopper is past them. Closing the prefix is what stops a lock rendering below
+    //     a ✓ (the beta screenshot: `false / false / true` at `current_value` 510).
+    //
+    //     HIGHEST, not first, and read AFTER the ascending sort: the payload arrives
+    //     unsorted, so "the last tier the engine kept" is only "the furthest tier reached"
+    //     once the rows are in threshold order. A NON-CONTIGUOUS set — `[true, false, true]`
+    //     — should be impossible for a single-winner engine, but if one ever arrives the
+    //     highest wins and the whole prefix reads met. That is deliberate: the alternative
+    //     is the un-steppable row this fix exists to remove, and a superset of ✓ merely
+    //     over-credits a tier the shopper has demonstrably paid past.
+    //
+    // (2) THE ENGINE SPOKE AND GRANTED NOTHING. Everything is locked, whatever the
+    //     thresholds say. This is the OTHER beta cart — `current_value` 510, zero discount,
+    //     every tier `false` — and it is the case `is_applied` was introduced for. The
+    //     arithmetic MUST NOT be consulted here or the bug comes straight back.
+    //
+    // (3) THIS BACKEND REPORTS NOTHING (`hasEngineVerdict` false — no tier carried a
+    //     readable flag). Only then does the cumulative threshold comparison run, exactly
+    //     as before `is_applied` shipped. Twilight and the Store package deploy
+    //     independently, so this path is live, not theoretical.
+    //
+    // Cases (1) and (2) are split on the WINNER, not on each tier's own flag, so `??` vs
+    // `||` no longer decides a single row on its own. The tri-state still decides which
+    // CASE we are in: an unreadable flag is absent (case 3), an explicit `false` is an
+    // answer that keeps us in cases 1-2. A mixed payload — some tiers flagged, some not,
+    // which no current backend emits — is treated as having spoken: only a `true` can name
+    // the winner, so an unflagged tier can never be one.
+    // ---------------------------------------------------------------------------------
+    let appliedIndex = NO_STAGE_REACHED;
+    for (let index = 0; index < applied.length; index++) {
+        if (applied[index] === true) {
+            appliedIndex = index;
+        }
+    }
+    // Case (3) closes the prefix at `lastReachedIndex` rather than comparing tier by tier.
+    // With one value for every tier the two are the same statement; with per-tier values
+    // it is what keeps `met` a prefix, on the same single-winner reasoning as case (1).
+    const met = hasEngineVerdict
+        ? thresholds.map((_, index) => index <= appliedIndex)
+        : thresholds.map((_, index) => index <= lastReachedIndex);
+    const metCount = met.filter(Boolean).length;
+    const nextUnmetIndex = met.findIndex(isMet => !isMet); // -1 === NO_STAGE_REACHED
+    const allMet = nextUnmetIndex === NO_STAGE_REACHED;
+    return {
+        thresholds,
+        met,
+        applied,
+        appliedIndex,
+        hasEngineVerdict,
+        metCount,
+        nextUnmetIndex,
+        allMet,
+        lastReachedIndex,
+        currentIndex,
+        isComplete,
+        value,
+        values,
+        startValue,
+        fills,
+        overallPercentage,
+    };
+}
+/**
+ * Locked / Current / Completed for one 0-based stage index — from `met`, so a tier the
+ * engine withheld outright reads LOCKED even with its threshold met, and every tier the
+ * shopper has passed on the way to a granted one reads COMPLETED.
+ *
+ * - Completed: `met[index]` — index at or below the winner.
+ * - Current:   exactly `nextUnmetIndex`, the first tier ABOVE the winner.
+ * - Locked:    every other unmet stage, and any out-of-range index.
+ */
+export function getStageState(index, progress) {
+    if (index >= 0 && progress.met[index]) {
+        return OfferStageState.COMPLETED;
+    }
+    if (index === progress.nextUnmetIndex && index !== NO_STAGE_REACHED) {
+        return OfferStageState.CURRENT;
+    }
+    return OfferStageState.LOCKED;
+}
+/**
+ * How the offer MEASURES its thresholds, which is also what its remainder rounds to.
+ *
+ * Mirrors `OfferType` in `salla-conditional-offer/interfaces.ts` without importing it —
+ * this module stays free of the component's payload types (see the header) — so a caller
+ * maps `details.based_on` onto it at the call site.
+ */
+export var OfferStageMeasure;
+(function (OfferStageMeasure) {
+    /** `order_amount` — a money value, rounded to the store's currency precision. */
+    OfferStageMeasure["CURRENCY"] = "currency";
+    /** `products_count` — whole products, so the remainder is a whole number. */
+    OfferStageMeasure["COUNT"] = "count";
+})(OfferStageMeasure || (OfferStageMeasure = {}));
+/**
+ * The precision to fall back to when the store publishes none.
+ *
+ * 2 is the platform default (SAR/USD/AED); a store on a 3-decimal currency (KWD, BHD)
+ * that reports its precision gets 3, and only a store that reports NOTHING readable
+ * lands here.
+ */
+export const DEFAULT_CURRENCY_DECIMALS = 2;
+/**
+ * Hard ceiling on the precision a store can ask for.
+ *
+ * The value comes off `salla.config`, i.e. off the wire, and `Math.pow(10, n)` with a
+ * large `n` reintroduces the very float noise this rounding exists to remove (and with
+ * an absurd `n`, an `Infinity` factor and a `NaN` remainder). 4 matches the cap
+ * `salla-cart-summary-card.roundToCurrency()` already applies to the same problem.
+ */
+const MAX_CURRENCY_DECIMALS = 4;
+/**
+ * Read one candidate precision, or `null` when it is not a usable one.
+ *
+ * Strict on purpose. `salla.config.get()` returns THE KEY ITSELF for a key the store did
+ * not publish (`config.ts:50`), so an unpublished `store.currency.decimals` arrives as
+ * the string `"store.currency.decimals"` — truthy, non-null, and fatal to a `?? 2`
+ * fallback, which is why this parses and range-checks rather than nullish-coalescing.
+ */
+function readDecimals(raw) {
+    const parsed = typeof raw === 'number' ? raw : parseFloat(raw);
+    if (!Number.isFinite(parsed))
+        return null;
+    const decimals = Math.trunc(parsed);
+    return decimals >= 0 && decimals <= MAX_CURRENCY_DECIMALS ? decimals : null;
+}
+/**
+ * The store's money precision — THE ONE IMPURITY IN THIS MODULE (see the header note).
+ *
+ * Asked in the order the platform answers it:
+ *  1. `salla.config.currency()` — the ACTIVE currency's own precision, which is the only
+ *     source that can differ per currency (a store displaying KWD wants 3 while its SAR
+ *     prices want 2).
+ *  2. `salla.config.get('store.currency.decimals')` — the store-level key
+ *     `salla-bought-together.tsx:142` already rounds its basket total by.
+ *  3. `DEFAULT_CURRENCY_DECIMALS`.
+ *
+ * Every step is guarded: this runs inside `render()`, where an SDK that is not on the
+ * page yet (or a `config` that throws) must degrade to the default, never take the banner
+ * down.
+ */
+export function getCurrencyDecimals() {
+    try {
+        const sdk = typeof salla !== 'undefined' ? salla : undefined;
+        const fromCurrency = readDecimals(sdk?.config?.currency?.()?.decimals);
+        if (fromCurrency !== null)
+            return fromCurrency;
+        const fromConfig = readDecimals(sdk?.config?.get?.('store.currency.decimals'));
+        if (fromConfig !== null)
+            return fromConfig;
+    }
+    catch (_) {
+        // No SDK, or a config that threw — the default is the answer.
+    }
+    return DEFAULT_CURRENCY_DECIMALS;
+}
+/**
+ * Float noise allowed when rounding a remainder UP, in units of the display precision.
+ * `300 - 289.6` is `10.399999999999977`, which must still read as exactly 10.40 rather
+ * than tip over to 10.41.
+ */
+const CEIL_TOLERANCE = 1e-6;
+/**
+ * How much more of the cart value is needed to reach the given stage, rounded UP at the
+ * display precision. Never negative.
+ *
+ * `threshold - value` is raw IEEE-754 subtraction over two server-sent floats, so
+ * `300 - 289.599993` is `10.400007000000012`. Nothing downstream cleans that up:
+ * `salla.money()` only swaps digits and appends a symbol (`base/src/helpers/numbers.ts:74-84`).
+ * Rounding here, at the source, covers every consumer, including the `products_count`
+ * path that never reaches `salla.money`.
+ *
+ * Rounding goes UP, never to the nearest unit: the displayed amount must be enough to
+ * unlock the tier. Rounding 10.400007 to 10.40 asks for an amount that leaves the cart
+ * at 299.999993, still below the threshold. Float noise is guarded (see `CEIL_TOLERANCE`)
+ * so an exact 10.40 stays 10.40.
+ *
+ * A count remainder is a WHOLE number, because `salla.lang.choice('blocks.header.products_count', 10.4)`
+ * matches no plural interval and a shopper cannot add 0.4 of a product.
+ *
+ * Only the derived remainder is rounded. `progress.values` and `progress.thresholds` are
+ * server facts and stay as sent: rounding them would move the unlocked/locked boundary,
+ * which is the engine's call.
+ *
+ * A positive remainder never becomes 0: `getGuidanceMessage` drops its line on
+ * `remaining <= 0`, so a genuinely unmet tier must still ask for at least one unit of the
+ * precision (0.01 for a 2-decimal currency, 1 for a count). Exact zero, a met tier,
+ * still returns 0.
+ */
+export function getRemainingToStage(index, progress, measure = OfferStageMeasure.CURRENCY) {
+    const threshold = progress.thresholds[index];
+    if (threshold === undefined) {
+        return 0;
+    }
+    // The distance to a tier is measured in THAT tier's own progress — see `values`.
+    const raw = Math.max(0, threshold - (progress.values?.[index] ?? progress.value));
+    if (raw === 0)
+        return 0;
+    const decimals = measure === OfferStageMeasure.COUNT ? 0 : getCurrencyDecimals();
+    const factor = Math.pow(10, decimals);
+    const rounded = Math.ceil(raw * factor - CEIL_TOLERANCE) / factor;
+    // Still owed something, but only float noise above zero: ask for one unit.
+    return rounded > 0 ? rounded : 1 / factor;
+}