@salla.sa/twilight-components 2.14.590 → 2.14.592

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;
+}

package/dist/components/helpers.js

@@ -240,7 +240,7 @@ function findNearestBranch(branches, userLat, userLon) {
     for (const b of branches) {
         const lat = b.location?.lat != null ? Number(b.location.lat) : Number.NaN;
         const lng = b.location?.lng != null ? Number(b.location.lng) : Number.NaN;
-        if (Number.isNaN(lat) || Number.isNaN(lng) || b.is_open === false)
+        if (Number.isNaN(lat) || Number.isNaN(lng) || !isBranchSelectable(b))
             continue;
         const d = calculateDistance(userLat, userLon, lat, lng);
         if (d < minD) {
@@ -302,4 +302,4 @@ const GEO_ERROR_MESSAGES = {
 };
 const getGeolocationErrorMessage = (errorCode) => GEO_ERROR_MESSAGES[errorCode] ?? 'An error occurred while detecting location';
 
-export { getIntentLongitude as a, bulletDeliveryAPI as b, getIntentCityId as c, getIntentCountryId as d, getIntentRegionId as e, getIntentDistrictId as f, getIntentLatitude as g, hasSessionAddressIntent as h, isSaudiArabia as i, filterBranches as j, findNearestBranch as k, getGeolocationErrorMessage as l, clearApiCache as m, getIntentSubtitle as n, getIntentBranchId as o, isMapOriginIntent as p, isBranchSelectable as q, requireRegionAndDistrictForSA as r, getIntentCountryCode as s };
+export { getIntentLongitude as a, bulletDeliveryAPI as b, getIntentCityId as c, getIntentCountryId as d, getIntentRegionId as e, getIntentDistrictId as f, getIntentLatitude as g, hasSessionAddressIntent as h, isSaudiArabia as i, isBranchSelectable as j, filterBranches as k, getIntentBranchId as l, findNearestBranch as m, getGeolocationErrorMessage as n, clearApiCache as o, getIntentSubtitle as p, isMapOriginIntent as q, requireRegionAndDistrictForSA as r, getIntentCountryCode as s };