@salla.sa/twilight-components 2.14.590 → 2.14.591

package/dist/types/components/salla-conditional-offer/salla-conditional-offer.d.ts

@@ -1,20 +1,666 @@
 import { type Offer } from "./interfaces";
-import type { Product } from "@salla.sa/twilight/types/common";
+import { type CartFreeGiftItem } from "../../shared/cart-free-gifts";
 export declare class SallaConditionalOffer {
     offer: Offer;
-    products: Record<string, Pick<Product, 'image' | 'url' | 'name' | 'price'>>;
     isLoading: boolean;
     canRender: boolean;
+    /** Free-gift cart LINES belonging to this offer — the "ادارة العرض" card. */
+    gifts: CartFreeGiftItem[];
+    /**
+     * How many LINES the cart holds — `null` while that is genuinely UNKNOWN.
+     *
+     * TRI-STATE on purpose, and the whole of the empty-cart fix rests on it. `0` renders
+     * NOTHING; `null` renders normally. Collapsing the two would hide the banner on every
+     * populated cart for as long as the first `details()` request is in flight, which is
+     * the flicker this must not trade one bug for.
+     */
+    cartItemCount: number | null;
+    /** The tooltip is open while hovered OR while pinned by a click (the mobile path). */
+    isTooltipHovered: boolean;
+    isTooltipPinned: boolean;
+    /** "ادارة العرض" — open by default, the gifts card starts expanded. */
+    isGiftsOpen: boolean;
+    /**
+     * The ⓘ TRIGGER's own wrapper — the popover's positioning context, and the element
+     * "inside vs outside" is measured against.
+     *
+     * Deliberately NOT the heading. The heading spans the offer TITLE as well, so
+     * anchoring there put the popover's edge at the start of the text and left the caret
+     * pointing at a word instead of at the icon that opened it.
+     */
+    private infoAnchorEl?;
+    private infoTriggerEl?;
+    /** The popover itself, measured (never re-rendered) by `positionTooltip`. */
+    private tooltipEl?;
+    /**
+     * What makes this instance's `id`s its OWN. The banner can legitimately mount more than
+     * once on a page, and with fixed ids the second instance's `aria-describedby` /
+     * `aria-controls` resolve to the FIRST one's popover and gifts card.
+     */
+    private instanceId;
+    /**
+     * Monotonic generation counter guarding `refresh()`. Two cart mutations in quick succession issue
+     * two `offers()` requests, and nothing guarantees they SETTLE in the order they were
+     * sent — without this, a slow first response can land after a fast second one and
+     * render a `current_value` that is already stale.
+     */
+    private refreshGeneration;
+    /** The same guard for the independent gift-lines lookup. */
+    private giftsGeneration;
+    /**
+     * The open coalescing window: the timer that will run the ONE refresh pass a burst of
+     * `cart::updated` events is entitled to. `null` whenever no burst is in flight.
+     *
+     * The generation guards above are untouched by this and still do their own job — the
+     * window collapses events that have not been ASKED about yet, they discard answers to
+     * questions that have since been superseded, and a burst that straddles the window
+     * (an event arriving while a pass is already in flight) needs both.
+     */
+    private cartRefreshTimer;
+    /**
+     * "A burst has been seen and its pass has not run yet."
+     *
+     * Survives a disconnect on purpose, exactly as `skeletonDeadline` does: a theme that
+     * MOVES the host in the DOM mid-burst (disconnect + reconnect, same instance) would
+     * otherwise drop the trailing pass and rest on pre-burst data forever, since nothing
+     * re-runs `refresh()` but another `cart::updated`. `connectedCallback` re-arms it.
+     */
+    private cartRefreshPending;
+    /**
+     * Set once `load()` has asked for `cart::updated`, and never cleared: it is what lets
+     * `connectedCallback` tell a RECONNECT (put the listener back) from the first connect,
+     * which runs before `componentWillLoad` and must leave the subscription to it.
+     */
+    private wantsCartUpdates;
+    /** Whether `cartUpdatedHandler` is on `cart::updated` RIGHT NOW — the double-registration guard. */
+    private isListeningToCartUpdates;
+    /** The armed cart-lookup retry; `null` whenever none is. See `CART_LOOKUP_RETRY_DELAYS_MS`. */
+    private cartLookupRetryTimer;
+    /** How many of those retries this episode has SPENT — the bound. */
+    private cartLookupRetries;
+    /** "A retry is owed" — survives a disconnect for the same reason `cartRefreshPending` does. */
+    private cartLookupRetryPending;
+    /**
+     * Set by the ONE branch of `refresh()` that returns without asking for the offer: the
+     * cart was reported empty.
+     *
+     * That branch is right whenever the report is, and unrecoverable whenever it is not —
+     * nothing re-runs `refresh()` except `cart::updated`, which a shopper who never
+     * touches the cart never emits. So the branch now leaves this behind, and the cart
+     * lookup it kicks off clears it by re-running `refresh()` if the count comes back
+     * `>= 1`. See both sites; the latch is what keeps that to a recovery rather than a
+     * second offer request on every load.
+     */
+    private deferredByEmptyCart;
+    /** Set by `disconnectedCallback`, so a late response cannot set state on a dead host. */
+    private isDisconnected;
+    /** Backstop timer that guarantees the skeleton is never a resting state. */
+    private skeletonWatchdog;
+    /**
+     * WHEN the current skeleton must be gone by — the authority, with `skeletonWatchdog`
+     * demoted to a mere handle.
+     *
+     * A timer handle answers "is a timer pending", which is not the question. The question
+     * is "is this skeleton past its deadline", and the two come apart precisely when it
+     * matters: a handle that was cleared, consumed, or never armed reads exactly like one
+     * that is still counting down. Keeping the deadline as a timestamp means the watchdog
+     * can always be REBUILT from state — which is what `ensureSkeletonIsWatched` does, on
+     * every render, so a skeleton on screen can never be one nothing is watching.
+     *
+     * `0` means "not loading"; anything else is an absolute `Date.now()` deadline.
+     */
+    private skeletonDeadline;
+    /** The host element — the thing that gets MOVED; see `relocateIntoItemsColumn`. */
+    hostEl: HTMLElement;
+    /** Latched once the host sits in the items column, so it can never be moved twice. */
+    private hasRelocated;
+    /** `componentDidRender` fires BEFORE the first `componentDidLoad`; this orders them. */
+    private hasLoaded;
+    /** Observer waiting for a column that the parser has not emitted yet. */
+    private relocationObserver;
+    /** Deadline that bounds that wait. */
+    private relocationWatchTimer;
+    /** Set when the wait expired: stop re-arming, keep the cheap per-render retry. */
+    private relocationWatchExpired;
+    /** "No column found" is said ONCE per instance, not on every render. */
+    private relocationLogged;
+    /**
+     * SYNCHRONOUS on purpose — an `async` version of this hook is what made the whole
+     * component invisible.
+     *
+     * Stencil awaits whatever `componentWillLoad` returns BEFORE it calls `render()` for
+     * the first time (`dispatchHooks` → `enqueue(maybePromise, () => updateComponent(...))`).
+     * An `async componentWillLoad` chaining round trips inside that promise leaves the host
+     * element literally empty for the whole chain, and FOREVER if the last of them never
+     * settles.
+     *
+     * Same posture as `salla-cart-summary-card` ("Sync: returning a promise would make
+     * Stencil defer first paint"): paint now, fill in as the data lands.
+     */
     componentWillLoad(): void;
-    private getProducts;
-    private updateInitialOfferValue;
-    private updateOfferValues;
+    /**
+     * Logging that CANNOT throw.
+     *
+     * `salla.logger.warn` is not safe to call during init: `base/src/logger.ts` opens every
+     * call with `if (!salla.config.isDebug()) return;`, so it raises a TypeError whenever
+     * `salla.config` has not been installed yet — precisely the window `componentWillLoad`
+     * runs in. Every recovery path in this component used to log BEFORE it recovered, so a
+     * single throw in here silently skipped the recovery it was announcing.
+     */
+    private safeLog;
+    /**
+     * Cleared on RECONNECT, not just set on disconnect. `componentWillLoad` runs once per
+     * instance, so an element that a theme moves in the DOM (disconnect + reconnect keeps
+     * the same instance) would otherwise stay permanently latched as "dead" and stop
+     * updating on every later `cart::updated`.
+     */
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    componentDidLoad(): void;
+    /**
+     * Whether the host currently puts anything on the page.
+     *
+     * Gates the relocation: a host that renders nothing contributes no layout and must not
+     * be moved around the document either. It becomes true on the render that first paints
+     * real content, and `componentDidRender` runs inside the same frame as that render —
+     * before the browser paints it — so the move still lands ahead of the first visible
+     * pixel and there is no jump.
+     */
+    private isShowingSomething;
+    /**
+     * Every later render re-attempts the move. Free once it has happened (one boolean
+     * read), and it is what covers the ordinary late-arrival case without any timer: the
+     * skeleton paints while the row is still being parsed, and the render that replaces it
+     * with the offer runs against a complete DOM.
+     */
+    componentDidRender(): void;
+    /**
+     * Move the host into the cart-items column.
+     *
+     * The theme mounts this component ABOVE the two-column row (`cart.twig`), so it spans
+     * the items column AND the order summary; the design puts it above the ITEMS only,
+     * with the summary starting level with it. Theme changes are out of scope, so the
+     * component places itself.
+     *
+     * MOVING rather than re-sizing is deliberate. A moved host inherits whatever width the
+     * column has — at every breakpoint, in RTL and LTR, and on a resize — and on mobile,
+     * where the column is the only column, the move is a no-op visually, which is exactly
+     * the mobile layout. A hard-coded `calc(100% - 384px)` is raed's number and would
+     * be wrong in any other theme.
+     *
+     * NEVER throws, and never leaves the component unrendered: a cart whose column cannot
+     * be identified keeps the full-width banner. That is a degraded LAYOUT, not a degraded
+     * component.
+     */
+    private relocateIntoItemsColumn;
+    /**
+     * The cart-items column, found WITHOUT depending on any single theme's class names.
+     *
+     * From the host OUTWARDS: at each level look at the elements that FOLLOW it — the row
+     * is always a later sibling, never an ancestor — and inside each of them look for a
+     * cart ITEM row. The column is then that row's own child which contains the item, i.e.
+     * precisely the element whose width the banner should inherit.
+     *
+     * Scoping to following siblings is what stops an unrelated `form[id^="item-"]` (a
+     * mini-cart drawer, a footer widget) from being mistaken for the cart.
+     */
+    private findItemsColumn;
+    private getFollowingSiblings;
+    /** The child of `row` that holds the cart items, if `row` is the two-column row. */
+    private findColumnWithin;
+    /**
+     * Walk up from `node` to the DIRECT CHILD of `ancestor` that contains it.
+     *
+     * Not "the parent of the item rows": a theme that nests them (`col > ul > li > form`)
+     * would hand back the `<ul>`, and a banner is not a list item. The row's own child is
+     * the column in every shape.
+     */
+    private climbToChildOf;
+    private matches;
+    /**
+     * Wait for a column that does not exist YET, then stop waiting.
+     *
+     * Bounded on both sides: the observer is disconnected the moment the move succeeds, and
+     * a deadline retires it if it never does. Where there is no `MutationObserver` (older
+     * browsers, and the spec DOM) this degrades to the per-render retry in
+     * `componentDidRender`, which is the path that matters anyway.
+     */
+    private watchForItemsColumn;
+    private stopWatchingForItemsColumn;
+    /** Said ONCE per instance: the full-width banner is a layout note, not a per-render alarm. */
+    private logNoItemsColumn;
+    /**
+     * Guarantee that a raised skeleton has a live deadline behind it — idempotent, cheap,
+     * and called from EVERY path that can leave one on screen (`startLoading`,
+     * `connectedCallback`, and `componentDidRender`).
+     *
+     * This is the structural answer to "a skeleton with nothing watching it". The old shape
+     * armed the timer only inside `startLoading()`, and only when the HANDLE happened to be
+     * null — so any path that raised `isLoading` without going through that guard, or that
+     * left a stale-looking handle behind, produced a shimmer that nothing would ever end.
+     * Re-checking on every render means the invariant is restored by the very act of
+     * painting the skeleton, whatever raised it.
+     *
+     * The deadline is set ONCE per loading episode and never pushed out, so a stream of
+     * `cart::updated` events cannot extend a skeleton indefinitely.
+     */
+    private ensureSkeletonIsWatched;
+    private clearSkeletonWatchdog;
+    /**
+     * The ONLY way INTO the skeleton. Raising it and arming the watchdog that ends it are
+     * deliberately the SAME operation — keeping them apart is what let `refresh()` show a
+     * skeleton that nothing was watching. The existing deadline is kept rather than
+     * refreshed, so a stream of `cart::updated` events cannot push it out indefinitely.
+     */
+    private startLoading;
+    /**
+     * The ONLY way out of the skeleton, so the watchdog can never outlive it. Every
+     * terminal state — loaded, no-eligible-offer, error — goes through here.
+     */
+    private stopLoading;
+    /**
+     * The async half of the load, deliberately NOT awaited by `componentWillLoad` so it
+     * can never gate the first paint. Every state it sets is `@State`, so each step
+     * re-renders on its own.
+     *
+     * NOTHING here is allowed to disable the component permanently.
+     */
+    private load;
+    /**
+     * `salla.onReady()`, bounded.
+     *
+     * The previous shape caught a REJECTED bootstrap but could not catch a never-settling
+     * one, even though its comment claimed to — and an unbounded await here is the single
+     * point at which the whole component can hang with nothing logged. Racing a timer
+     * turns "the SDK never signals ready" from fatal into "we ask a few seconds early",
+     * which `refresh()` already handles non-terminally and retries on `cart::updated`.
+     *
+     * Never rejects, and absorbs a synchronous throw from `onReady` itself.
+     */
+    private waitForSdk;
+    /**
+     * The `cart::updated` payload is ignored for everything EXCEPT the item count — it may
+     * legitimately arrive with no `items` at all (`api.cart.latest` is not in
+     * `CartPresenter::$routesWithItems`). Refetch and take the server's `current_value`.
+     *
+     * `count` is the one field that is safe to read here, and reading it is what fixes the
+     * live removal path. `SallaCartEvent.updated()` dispatches `{ ...data.cart }`
+     * (twilight/src/event/cart.js:114) and writes `count` from that same object into
+     * `cart.summary` one line above it, so the field is first-class — unlike `items`, which
+     * genuinely is not. Taking it SYNCHRONOUSLY, before any request goes out, is the point:
+     * see `readCartCountFromEvent`.
+     *
+     * Two independent refetches fan out from here and are NOT chained: the offer payload
+     * (thresholds + reward labels) and the gift cart LINES. The gift lookup is shared
+     * process-wide (`shared/cart-free-gifts`), so the item-offer badges, the summary card
+     * and this banner still cost ONE `details()` request between them per mutation.
+     *
+     * Both of those refetches are COALESCED — see `CART_UPDATE_COALESCE_MS`. Only the
+     * count read below is per-event.
+     *
+     * ONE reference per instance rather than an inline closure, because `salla.event.off`
+     * can only remove the exact function `on` was given.
+     */
+    private cartUpdatedHandler;
+    /**
+     * Put `cartUpdatedHandler` on `cart::updated` — at most ONCE, however many paths ask
+     * (`load()`, the SDK-ready retry, a reconnect).
+     *
+     * Never throws, and reports whether the listener is on: `salla.event.on` can throw
+     * this early (see `load()`), and the caller decides what a failure is worth.
+     */
+    private subscribeToCartUpdates;
+    /** The other half of `subscribeToCartUpdates` — see `disconnectedCallback`. */
+    private unsubscribeFromCartUpdates;
+    /**
+     * The second attempt for a subscription that threw before the SDK was up.
+     *
+     * Hung off `salla.onReady()` ITSELF, not off `waitForSdk()`: that wait gives up after
+     * `ON_READY_TIMEOUT_MS` so that it cannot hold the first paint, and an SDK that comes
+     * up later than that is exactly the one this is for. Floating for the same reason —
+     * nothing in `load()` awaits it, so a bootstrap that never settles costs the listener
+     * and nothing else.
+     */
+    private subscribeWhenSdkIsReady;
+    /**
+     * Open (or extend) the coalescing window, so a burst of `cart::updated` events buys ONE
+     * refresh pass instead of two server round trips each. See `CART_UPDATE_COALESCE_MS`.
+     *
+     * Restarting the timer on every event is what makes this trailing-edge: the pass runs
+     * `CART_UPDATE_COALESCE_MS` after the LAST event, never after the first, so the burst
+     * can never settle on a cart state the shopper has already moved past.
+     */
+    private scheduleCartRefresh;
+    /**
+     * The one pass a burst is entitled to — byte for byte what the `cart::updated` handler
+     * used to do inline, minus the count read that now happens per event.
+     *
+     * The disconnect guard comes FIRST and leaves the flag ALONE, so a host that went away
+     * between the last event and the end of its window stays owed the pass rather than
+     * silently forfeiting it. Unreachable in practice — `disconnectedCallback` clears the
+     * timer — but the two must not disagree about who owes what.
+     *
+     * Past that, the flag is cleared BEFORE the work, not after: an event that arrives
+     * while this pass is in flight must be able to open a NEW window (and it does —
+     * `scheduleCartRefresh` sets the flag again), and clearing afterwards would swallow it.
+     */
+    private runCartRefresh;
+    /**
+     * Take the cart's item count straight off the `cart::updated` payload.
+     *
+     * THIS IS THE FIX FOR THE LIVE REMOVAL PATH, and it exists because the request-based
+     * count cannot answer there. When the shopper deletes their last line the cart id goes
+     * away, and BOTH cart endpoints then reject rather than reporting an empty cart:
+     * `details()` resolves its id through `getCurrentCartId(false, …, allowCreate=false)`,
+     * which returns `null` for a guest with no stored cart id, and throws `CartNotCreated`
+     * (twilight/src/api/cart.js:192-199); `offers()` throws through the same door
+     * (cart.js:869-874). `refreshCartFreeGifts()` has meanwhile invalidated the shared
+     * cache, so the count resolves to `null` — "unknown" — and an unknown count renders the
+     * banner. That is the beta regression: a cart that is empty, reported as unknowable.
+     *
+     * The payload has none of that dependency. It is delivered synchronously, by the same
+     * event that told us the cart changed, and it cannot fail, hang, or lose a race.
+     *
+     * Two sources, in order: the payload's own `count`, then the `cart.summary.count` the
+     * same emitter wrote a line earlier. Both are strict — see `toCartCount` — so a payload
+     * that states nothing leaves the previous value untouched rather than reading as empty.
+     */
+    private readCartCountFromEvent;
+    /**
+     * The SECONDARY count, for a `cart::updated` that carried no usable `count` of its own.
+     *
+     * `SallaCartEvent.updated()` writes `cart.summary.count` from `data.cart`
+     * (twilight/src/event/cart.js:102-110) SYNCHRONOUSLY, immediately before it dispatches
+     * the event — so inside a `cart::updated` handler this value is as fresh as the payload
+     * and comes from the same object. `mobileBridge._cart` falls back to exactly this, for
+     * exactly this reason.
+     *
+     * ONLY safe from inside that handler, which is why it is private to
+     * `readCartCountFromEvent` and never consulted at mount: on a cold load the same key
+     * can hold a count left over from a previous session, and trusting it there would hide
+     * the banner on a cart that is not empty.
+     *
+     * Read through the public `salla.storage` facade; wrapped, because storage is not
+     * guaranteed to be installed and a throw here must cost nothing.
+     */
+    private readCartCountFromStorage;
+    /**
+     * Coerce a reported count, STRICTLY. Only a finite, non-negative number is an answer;
+     * `undefined`, `null`, a string and a negative all mean "not stated", which leaves the
+     * previous value alone — the degenerate `{ fromLatestFetched }` payload
+     * (event/cart.js:85) must never read as an empty cart.
+     */
+    private toCartCount;
+    private getFreeLabel;
+    /**
+     * Read a `blocks.cart_offer.*` translation.
+     *
+     * `salla.lang.get` returns the KEY VERBATIM when a translation is missing, which would
+     * put "blocks.cart_offer.congrats" in front of a shopper. A missing key reads as its
+     * `EN_FALLBACKS` entry instead, with the same `:placeholder` substitution.
+     */
+    private trans;
+    /**
+     * The ONLY eligibility question worth asking: does this store have the feature?
+     *
+     * `salla.config.get` is a plain object read and cannot throw, but the whole thing is
+     * still wrapped: this predicate is called from a lifecycle hook, and "the SDK is not
+     * on the page yet" must degrade to "not eligible *yet*", never to an exception.
+     */
+    private isEnabled;
+    /**
+     * ONE banner, even when several cart offers are live the FIRST conditional
+     * offer carrying at least one checkpoint wins and the rest are ignored. Merging them
+     * would produce a badge row whose tiers belong to different promotions.
+     */
+    private fetchOffer;
+    /**
+     * The single entry point for "ask the server what this cart is entitled to".
+     *
+     * Runs on the initial load AND on every `cart::updated`, and is IDEMPOTENT and
+     * REVERSIBLE in both directions — `canRender` is derived from this pass alone, so a
+     * cart that becomes eligible after starting out ineligible turns the component back
+     * on. No state set here is a one-way door.
+     */
+    private refresh;
+    /**
+     * The single gate on rendering anything at all: an AFFIRMATIVE "the cart holds at
+     * least one item".
+     *
+     * Deliberately not `!== 0` and not a truthy test. `cartItemCount` is `null` until
+     * something answers, and `null` must read as "do not render" — the default is hidden,
+     * and only a real, non-negative count of 1 or more opens the gate.
+     */
+    private hasCartItems;
+    /**
+     * Whether this pass's response should be discarded: a newer `refresh()` has since
+     * been issued (so this one describes an older cart), or the host is gone. Answers
+     * "whose data wins" ONLY — never "should the skeleton stay up"; see the `finally`
+     * in `refresh()`.
+     */
+    private isSuperseded;
+    /**
+     * The two things this component needs from the CART itself: how many lines it holds,
+     * and which of them are this offer's free gifts.
+     *
+     * ONE lookup for both. `getCartItemCount` and `getCartFreeGiftItems` are two
+     * projections of the same shared `details()` response and share its cache, its
+     * in-flight promise and its generation guard, so asking for both costs exactly one
+     * request — and, more importantly, the count and the gift lines can never describe
+     * two different cart states.
+     *
+     * Never rejects: a failing lookup is a missing "ادارة العرض" card and an UNKNOWN
+     * count, not a missing promotion and not an empty cart.
+     */
+    private loadCart;
+    /**
+     * Arm the next cart-lookup retry, unless one is already armed or the episode has spent
+     * its attempts. See `CART_LOOKUP_RETRY_DELAYS_MS`.
+     *
+     * The attempt is SPENT when the timer fires, not when it is armed, so a timer a
+     * disconnect cleared is re-armed by `connectedCallback` without costing one.
+     */
+    private scheduleCartLookupRetry;
+    /**
+     * End the retry episode: a lookup answered, or the cart changed under it. The count
+     * goes back to zero so a LATER failure gets its own full set of attempts.
+     */
+    private clearCartLookupRetry;
+    /**
+     * Keep only the gift lines this offer granted.
+     *
+     * `CartItemTransformer::getFreeGiftData` emits `offer_id` OPTIMUS-ENCODED, exactly
+     * like `CartOffersTransformer` emits `id`, so the two join directly. When the offer id
+     * is unreadable we fall back to every gift line rather than hiding the card: only one
+     * cart offer can be applied to a cart at a time, so an unmatched gift is far more
+     * likely to be an id-shape surprise than another promotion's product.
+     */
+    private selectOwnGifts;
+    /**
+     * Stages in ascending threshold order — the payload itself is UNSORTED.
+     *
+     * LOAD-BEARING: this filter and sort must mirror what `computeOfferStageProgress`
+     * does internally, because every renderer pairs `stages[i]` with
+     * `progress.thresholds[i]`. Both drop unusable thresholds via `isUsableThreshold` and
+     * both sort ascending and stably, so the two arrays stay index-aligned.
+     */
+    private getStages;
+    /**
+     * The tier picture: the ENGINE'S verdict per tier plus the threshold projection.
+     *
+     * `is_applied` is passed positionally from THIS array, so the flag can never be
+     * attributed to the wrong tier — `stages[i]`, `progress.thresholds[i]`,
+     * `progress.met[i]` and `progress.applied[i]` are one row. Alignment matters more
+     * than ever now: the winner's INDEX decides where the ✓ run stops.
+     *
+     * Each tier's OWN `current_value` rides along the same way. It is what the distance in
+     * the guidance line is measured against, and a tier that carries none — every tier, on
+     * an older backend — is measured by the offer-level value exactly as before.
+     */
+    private getProgress;
+    /**
+     * A tier's render key. `id` is the stable identity across refetches; the array
+     * position is the last resort for a backend that does not send one.
+     */
+    private tierKey;
+    /**
+     * How this offer MEASURES its thresholds, as `offer-stages` names it .
+     *
+     * The remainder is rounded to the measure — whole products for `products_count`,
+     * store currency precision for everything else — so `formatRequirement` is handed a
+     * value its formatter can actually render. A `products_count` offer is the one that
+     * MUST be told apart: `salla.lang.choice` matches a fraction against no plural
+     * interval and answers "no products".
+     */
+    private stageMeasure;
+    /**
+     * Format a cart value (a threshold, or a remaining amount/quantity) the way the
+     * offer is measured: money for `order_amount`, a pluralised item count for
+     * `products_count`. May return HTML (`salla.money`), so callers use `innerHTML`.
+     */
+    private formatRequirement;
+    /**
+     * The shopper-facing reward text, SERVER-RENDERED.
+     *
+     * Never re-derived here. `reward_label` already carries the type-specific wording,
+     * the currency the value was converted to, and the merchant's own theme-translation
+     * overrides. Empty (free_shipping, unknown types) means "render nothing", which is
+     * why every caller has a reward-less sentence to fall back to.
+     */
+    private getRewardText;
+    /**
+     * Guidance toward the first tier ABOVE the one the engine granted. Empty once
+     * that is the last tier (then the congratulations line renders instead).
+     *
+     * The TARGET comes from the verdict (`nextUnmetIndex`), the DISTANCE from the
+     * arithmetic — which is legitimate here, because "add :remaining" is a projection
+     * about the shopper's cart, not a claim about what the engine did. It is measured in
+     * the TARGET tier's own `current_value` when the backend sends one (see `getProgress`).
+     *
+     * Without that the two can disagree: the engine can withhold a tier whose threshold is
+     * already met, because its own excluded-product set is not in the payload. Then the distance
+     * is 0 and "Add SAR 0 and get a free gift" is false in both halves, so the line is
+     * dropped rather than rendered — and we do NOT skip ahead to a farther tier, which
+     * would advertise a reward past a nearer one the shopper cannot have. Nothing is the
+     * honest answer; the tooltip still shows the tier as locked.
+     */
+    private getGuidanceMessage;
+    /** One tooltip row's sentence: "spend X, get Y", both halves from the offer payload. */
+    private getTierSentence;
+    /**
+     * The reward-TYPE icon shown in a tooltip row's circle.
+     *
+     * `fixed` is the awkward one: the design draws the Saudi Riyal glyph, but a store
+     * selling in USD must not. `sicon-sar` is used on exactly the same condition
+     * `salla.money()` uses to swap the currency for that glyph
+     * (`base/src/helpers/numbers.ts:78-86`), and a currency-neutral banknote otherwise.
+     */
+    private getRewardIcon;
+    private usesSarSymbol;
+    private get isTooltipOpen();
+    private toggleTooltip;
+    private closeTooltip;
+    /**
+     * WHY THIS IS NOT `salla-tooltip`.
+     *
+     * It is a fair question — the component exists, it is shared, and this component used
+     * to depend on it (master renders a `<salla-tooltip theme="dark">` product preview off
+     * the badge avatars). That usage was hover-only, non-interactive and string-sized, and
+     * it is exactly the shape `salla-tooltip` is built for. The ⓘ popover this design asks
+     * for is not, and the gap is not one prop wide:
+     *
+     *  - VISIBILITY IS PRIVATE TO IT. `show` is `@State`, flipped only by the component's
+     *    own `mouseover`/`mouseout` window listeners (salla-tooltip.tsx:26-38). There is no
+     *    `open` prop and no way for an owner to pin it, so the CLICK path — which is the
+     *    ONLY way this popover opens on a touch device — cannot be expressed at all.
+     *  - IT IS DELIBERATELY UNREACHABLE. `pointer-events: none` (salla-tooltip.scss:20).
+     *    A pinned panel the shopper cannot hover or scroll is not a mobile path.
+     *  - NO DISMISSAL MODEL. Escape and outside-click do not exist there, because with
+     *    hover-only visibility there is nothing to dismiss.
+     *  - NO POSITIONING TO REUSE. It is pinned by two hand-tuned magic percentages —
+     *    `translateX(-63%)` and `translateX(-72%)` under `:dir(ltr)` — with a caret nailed
+     *    to `left: 50%` and never re-aimed. There is no viewport clamp, so the exact
+     *    behaviour this method exists for is the one piece it does not have.
+     *  - IT IS SIZED FOR A STRING. `max-width: 150px` / `width: 190px` default,
+     *    `max-width: 330px` dark. This panel is a title, a description and one row per
+     *    tier.
+     *  - IT ANCHORS BY GLOBAL ID. `document.getElementById(targetId)` at `componentDidLoad`
+     *    (salla-tooltip.tsx:40-43). The ⓘ trigger has no stable document-unique id, and the
+     *    banner can legitimately mount more than once on a page.
+     *
+     * Closing all six is not "a prop, not a hack" — it is a controlled-visibility API, a
+     * dismissal model, an anchoring change and a positioning engine, i.e. a rewrite of all
+     * 55 lines of it. And `salla-tooltip` is SHARED: `salla-comment-item` and `salla-wallet`
+     * both pass a plain `text` + `targetId` and depend on precisely the hover-only,
+     * `pointer-events: none`, magic-percentage behaviour above, with a single spec between
+     * them that asserts its exact rendered HTML. Rewriting it under them to serve this
+     * banner trades a scoped 90 lines here for a silent regression surface there.
+     *
+     * So the bespoke implementation stays, and stays SMALL: everything below is the clamp
+     * and the caret. The resting position is plain CSS.
+     *
+     * Keep the popover pointing at the ⓘ icon AND inside the viewport.
+     *
+     * The CSS already centres it on the trigger — that is the resting answer, and it is
+     * correct in RTL and LTR alike because centring is symmetric, which is exactly why the
+     * rules are written with physical `left`/`translateX` rather than `inset-inline-*`.
+     * Anything logical would have to be mirrored again here, in a coordinate space
+     * (`getBoundingClientRect`) that is physical no matter what the document direction is.
+     *
+     * All this adds on top is the CLAMP: at narrow widths a popover centred on an icon
+     * that sits near the edge of the screen would hang off it, so the box is nudged back
+     * inside and the caret is shifted by the same amount in the opposite direction, so it
+     * stays over the icon while the box moves out from under it.
+     *
+     * Written as CSS CUSTOM PROPERTIES on the element, never as `@State`: this runs from
+     * `componentDidRender`, and anything that re-entered render() from here would loop.
+     */
+    private positionTooltip;
+    private setTooltipOffsets;
+    /**
+     * A resize changes which edge the popover is up against, so the clamp has to be
+     * re-derived. Cheap: `positionTooltip` returns on its first line unless the popover is
+     * actually open.
+     */
+    handleWindowResize(): void;
+    handleDocumentKeydown(event: KeyboardEvent): void;
+    /**
+     * Outside click dismisses a PINNED tooltip. `composedPath` rather than
+     * `event.target`, so a click on a slotted/nested element still resolves to the
+     * anchor; `contains` is the fallback for the (test) environments that lack it.
+     */
+    handleDocumentClick(event: MouseEvent): void;
+    /**
+     * The `id` of one of this instance's own elements. EVERY id and every reference to it
+     * (`aria-describedby`, `aria-controls`) goes through here, so the two cannot drift.
+     */
+    private elementId;
+    /**
+     * The badge row: one small circle per tier, joined by short connectors.
+     *
+     * Tier count is VARIABLE, so the row is a nowrap flex line that scrolls
+     * horizontally inside a bounded width instead of squeezing the message beside it.
+     * RTL correctness comes from the markup: a plain flex row inherits the document's
+     * `dir`, so tier 1 lands on the leading edge and the scroll origin follows it in both
+     * directions. Do not add physical left/right offsets here.
+     */
+    private renderBadges;
+    /**
+     * Spec §4 — the ⓘ popover: title, the merchant's offer message, then one row per tier.
+     *
+     * The prose is `details.rules`, NEVER `offer.description` — see `readOfferRules`.
+     */
     private renderTooltip;
-    private getCheckpointContent;
-    private getOfferType;
-    private clamp;
-    private mapValueRanges;
-    private getCheckPointView;
+    /**
+     * "ادارة العرض". Rendered TWICE with complementary responsive visibility rather than
+     * moved with `order:`: desktop wants it inline with the banner row, mobile wants a
+     * full-width bar BELOW the gifts card, and those are different places
+     * in the flow, not a different order within one flex line.
+     */
+    private renderGiftsToggle;
+    /** Spec §5 — the gifts card: one read-only row per gift line. */
+    private renderGiftsCard;
+    private renderGiftRow;
     private getLoadingSkeletonView;
     render(): any;
 }