@asteby/storefront-react 0.4.0 → 0.6.0

package/dist/promotions.d.ts

@@ -0,0 +1,243 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { PromotionAnnouncement, PromotionMessages, CartPromotions, CartRecommendation, Money } from '@asteby/storefront';
+
+/**
+ * Pure mechanics of the entry pop-up (frequency, exclusions, crawlers, triggers). No DOM, no React:
+ * every function takes its inputs, so each rule is a row in a table test.
+ */
+type PromoFrequency = 'session' | 'days' | 'campaign';
+/** Paths where a promotional pop-up is never shown (cart, payment, thanks, account, auth, legal, editor previews). */
+declare const DEFAULT_PROMO_EXCLUDED_PATHS: readonly string[];
+type PathPattern = string | RegExp;
+/** `/mx/carrito` and `/carrito` both reduce to `/carrito` (an optional 2-letter market/locale segment is ignored). */
+declare function stripMarketPrefix(pathname: string): string;
+/** True when the pop-up must not appear on `pathname`. Case-insensitive; the market prefix does not matter. */
+declare function isExcludedPath(pathname: string, patterns?: readonly PathPattern[]): boolean;
+/** Known crawlers and automation (`navigator.webdriver`). They never get the pop-up. */
+declare function isCrawler(userAgent: string | null | undefined, webdriver?: boolean): boolean;
+/** Storage seam: cookie for cross-tab memory, sessionStorage for "once per session". Replaceable in tests and shops. */
+type PromoSeenStore = {
+    get(name: string): string | null;
+    set(name: string, value: string, options: {
+        days?: number;
+        session?: boolean;
+    }): void;
+};
+declare const PROMO_COOKIE = "sf_promo";
+declare function memorySeenStore(): PromoSeenStore & {
+    data: Map<string, string>;
+};
+/** Default store: `sessionStorage` for session frequency, a first-party cookie otherwise. Fails closed to memory. */
+declare function browserSeenStore(): PromoSeenStore;
+type SeenRecord = {
+    id: string;
+    version: number;
+    at: number;
+};
+declare function serializeSeen(r: SeenRecord): string;
+declare function parseSeen(raw: string | null | undefined): SeenRecord | null;
+type FrequencyInput = {
+    id: string;
+    version: number;
+    frequency: PromoFrequency;
+    /** Window for `days` (default 7). */
+    days?: number;
+    seen: SeenRecord | null;
+    now: number;
+};
+/**
+ * Frequency rule. A new `version` of the same announcement shows again.
+ * - `session`: once per browser session (the store is the session store).
+ * - `days`: once every N days.
+ * - `campaign`: once per campaign version.
+ */
+declare function frequencyAllows({ id, version, frequency, days, seen, now }: FrequencyInput): boolean;
+type PromoWindow = {
+    starts_at?: string | null;
+    ends_at?: string | null;
+};
+/** Inside the campaign dates (unparseable dates are ignored: the server decides, not the clock of a bad value). */
+declare function withinWindow({ starts_at, ends_at }: PromoWindow, now: number): boolean;
+type PromoTrigger = {
+    /** Show after N ms. `false` disables the timer. Default 5000. */
+    delayMs?: number | false;
+    /** Show on the Nth page view of the session. `false` disables. Default 2. */
+    pageviews?: number | false;
+    /** Show after scrolling this share of the page (0-100). `false` disables. Default 40. */
+    scrollPercent?: number | false;
+};
+declare const DEFAULT_PROMO_TRIGGER: Required<PromoTrigger>;
+declare function resolveTrigger(t?: PromoTrigger | null): Required<PromoTrigger>;
+/** Scroll depth as a percentage of the scrollable height (UI measure only). */
+declare function scrollDepthPercent(scrollY: number, viewportHeight: number, docHeight: number): number;
+/** Only same-site paths are valid CTAs (`/colecciones/x`). Anything else (`//evil`, `https:`, `javascript:`) is dropped. */
+declare function safeInternalPath(href: string | null | undefined): string | null;
+
+type PromoPopupEvent = {
+    type: 'view';
+    id: string;
+    version: number;
+    via: 'delay' | 'pageviews' | 'scroll';
+} | {
+    type: 'close';
+    id: string;
+    how: 'esc' | 'x' | 'backdrop';
+} | {
+    type: 'cta';
+    id: string;
+};
+type PromoPopupProps = {
+    /** Content as data from `GET /storefront/promotions`. `null`/absent: nothing happens. Amounts are the engine's. */
+    announcement: PromotionAnnouncement | null | undefined;
+    /** Current path, from the router (so route changes are seen). Default: `location.pathname`. */
+    pathname?: string;
+    /** Paths where the pop-up never appears. Default: cart, payment, thanks, account, auth, legal, editor. */
+    excludePaths?: readonly PathPattern[];
+    /** Overrides `announcement.frequency` (default `days`). */
+    frequency?: PromoFrequency;
+    /** Window for `days` (default `announcement.frequency_days` or 7). */
+    frequencyDays?: number;
+    /** Overrides `announcement.trigger`. Defaults: 5 s, second page view or 40 % scroll, whichever comes first. */
+    trigger?: PromoTrigger;
+    locale?: string;
+    messages?: Partial<PromotionMessages>;
+    /** Where "already seen" is remembered. Default: cookie `sf_promo` (7 days) or sessionStorage for `session`. */
+    store?: PromoSeenStore;
+    /** Analytics hook: view, close (how) and CTA. No personal data. */
+    onEvent?: (event: PromoPopupEvent) => void;
+    /** Renders the CTA (use your router's `Link`). Default: a plain `<a href>`. */
+    renderCta?: (props: {
+        href: string;
+        label: string;
+        onClick: () => void;
+        className?: string;
+    }) => ReactNode;
+    /** Test hooks. */
+    now?: () => number;
+    userAgent?: string;
+    webdriver?: boolean;
+    className?: string;
+};
+/**
+ * Entry pop-up mechanism. The CONTENT is data (`announcement`); this component only decides when to show it.
+ *
+ * - Client only: it renders nothing on the server and on the first client render, so SSR/SEO and hydration
+ *   are untouched and the pop-up never delays the LCP.
+ * - Shown at most per `frequency` (session / every N days / once per campaign version), never on excluded
+ *   paths, to crawlers or outside the campaign dates.
+ * - Accessible: native `<dialog>` (focus trap, inert background), Esc, a 44x44 close button, labelled title,
+ *   focus returns to where it was, no entry animation (nothing to disable for `prefers-reduced-motion`).
+ */
+declare function PromoPopup(props: PromoPopupProps): react.JSX.Element | null;
+
+type ProgressBarProps = {
+    /** Visible text (also `aria-valuetext`). */
+    text: string;
+    /** 0-100, from the server. */
+    percent: number;
+    label: string;
+    showBar?: boolean;
+    milestones?: {
+        id: string;
+        label: string;
+        threshold: string;
+        reached: boolean;
+        position: number;
+    }[];
+    state: string;
+    kind: 'discount' | 'shipping';
+    className?: string;
+};
+/**
+ * One accessible bar: color is never the only signal (text states the remaining amount; milestones are text).
+ * The fill width is the server percentage; the transition is off for `prefers-reduced-motion`.
+ */
+declare function PromoProgressBar({ text, percent, label, showBar, milestones, state, kind, className }: ProgressBarProps): react.JSX.Element;
+type CartProgressBarsProps = {
+    /** `Cart.promotions` exactly as the server sent it. */
+    promotions: CartPromotions | null | undefined;
+    locale?: string;
+    messages?: Partial<PromotionMessages>;
+    /** Show the tier milestones under the discount bar. Default true. */
+    showMilestones?: boolean;
+    className?: string;
+};
+/**
+ * Automatic-discount bar and free-shipping bar of the cart (or drawer). Pure view of `Cart.promotions`:
+ * `remaining`, `percent` and `reached` come from OPS; the shop never subtracts or divides.
+ * Renders nothing without promotions.
+ */
+declare function CartProgressBars({ promotions, locale: localeProp, messages, showMilestones, className }: CartProgressBarsProps): react.JSX.Element | null;
+
+type CrossSellAddResult = void | {
+    ok?: boolean;
+    error?: 'sold_out' | 'failed';
+};
+type CrossSellModalProps = {
+    open: boolean;
+    /** `Cart.promotions` of the CURRENT cart; after an add, pass the new cart's and the modal updates. */
+    promotions: CartPromotions | null | undefined;
+    recommendations: CartRecommendation[];
+    /** Total saved so far, from the server (`cart.cost.discount`). */
+    totalSaved: Money;
+    /**
+     * The shop adds the variant (server action / fetcher) and then re-renders with the new `promotions` and
+     * `recommendations`. Return `{ error: 'sold_out' }` for a 409 so the card tells the buyer to pick another flavor.
+     */
+    onAdd: (input: {
+        productId: string;
+        variantId: string;
+        recommendation: CartRecommendation;
+    }) => Promise<CrossSellAddResult> | CrossSellAddResult;
+    /** "Continuar al pago". The shop navigates to payment. */
+    onContinue: () => void;
+    /** "Continuar sin agregar", X, Esc or backdrop. The shop marks the modal as seen and navigates to payment. */
+    onSkip: (reason: 'skip' | 'esc' | 'x' | 'backdrop') => void;
+    locale?: string;
+    messages?: Partial<PromotionMessages>;
+    /** Renders a card image (use your `Image`). Default: a lazy `<img>` of the featured image. */
+    renderImage?: (rec: CartRecommendation) => ReactNode;
+    className?: string;
+};
+/**
+ * Pre-payment upsell modal ("Completa tu compra y desbloquea más").
+ *
+ * Mechanism only: the shop decides when to open it (once per cart, JS only) and what "continue" means.
+ * Every number comes from the server: remaining amount, rewards, progress, total saved, and the
+ * "Desbloquea tu 5 %" tag (`unlocks`). Add errors stay on their card; the rest stays usable.
+ * Accessible: native dialog, labelled title, focus starts on the title (not on a buy button), Esc = skip,
+ * `role="progressbar"` with spoken remaining amount, level changes announced via `aria-live`.
+ */
+declare function CrossSellModal(props: CrossSellModalProps): react.JSX.Element | null;
+
+type OrderNoteStatus = 'idle' | 'dirty' | 'saving' | 'saved' | 'error';
+type OrderNoteProps = {
+    /** Saved note (`Cart.note`). */
+    value: string | null | undefined;
+    /** Persists the note (`client.carts.setNote` through the shop action). Must resolve once stored. Throw to show the error. */
+    onSave: (note: string | null) => Promise<void> | void;
+    /** Autosave debounce in ms. Default 800. `false`: save only on blur / button. */
+    debounceMs?: number | false;
+    /**
+     * No-JS form: `<form method="post" action>` with a hidden `intent` and a "Guardar nota" button, hidden once the
+     * component hydrates (the autosave takes over). The shop's route action handles it.
+     */
+    form?: {
+        action?: string;
+        method?: 'post';
+        intent?: string;
+        intentName?: string;
+    };
+    locale?: string;
+    messages?: Partial<PromotionMessages>;
+    className?: string;
+    maxLength?: number;
+};
+/**
+ * "Añadir nota" for the order. A real `<textarea>` with a visible label; the server enforces 1000 characters and
+ * plain text. With JavaScript it autosaves (debounced, on blur) and announces "Guardada"; without it, the form posts.
+ */
+declare function OrderNote({ value, onSave, debounceMs, form, locale: localeProp, messages, className, maxLength }: OrderNoteProps): react.JSX.Element;
+
+export { CartProgressBars, type CartProgressBarsProps, type CrossSellAddResult, CrossSellModal, type CrossSellModalProps, DEFAULT_PROMO_EXCLUDED_PATHS, DEFAULT_PROMO_TRIGGER, type FrequencyInput, OrderNote, type OrderNoteProps, type OrderNoteStatus, PROMO_COOKIE, type PathPattern, type ProgressBarProps, type PromoFrequency, PromoPopup, type PromoPopupEvent, type PromoPopupProps, PromoProgressBar, type PromoSeenStore, type PromoTrigger, type PromoWindow, type SeenRecord, browserSeenStore, frequencyAllows, isCrawler, isExcludedPath, memorySeenStore, parseSeen, resolveTrigger, safeInternalPath, scrollDepthPercent, serializeSeen, stripMarketPrefix, withinWindow };