@asteby/storefront-react 0.11.0 → 0.12.0

package/dist/checkout.d.ts

@@ -1,6 +1,250 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
-import { ShippingRate, PickupOption, Money } from '@asteby/storefront';
+import { ReactNode, InputHTMLAttributes, SelectHTMLAttributes, RefObject } from 'react';
+import { Address, CartLine, CartCost, Money, ShippingRate, PickupOption } from '@asteby/storefront';
+
+type FieldMessages = {
+    valueMissing: string;
+    /** Required radio group (delivery, payment). */
+    choiceMissing: string;
+    email: string;
+    tel: string;
+    pattern: string;
+    /** `{n}` = minimum length. */
+    tooShort: string;
+    /** A field the server rejected. */
+    server: string;
+    /** Error summary title, `{n}` = number of fields. */
+    summaryOne: string;
+    summaryMany: string;
+    optional: string;
+};
+/** Messages for a locale (`es*` default, `en*`), with optional overrides. */
+declare function fieldMessages(locale?: string | null, overrides?: Partial<FieldMessages> | null): FieldMessages;
+/** Field name -> error text. */
+type FieldErrors = Record<string, string>;
+type ErrorSummaryItem = {
+    name: string;
+    id: string;
+    label: string;
+    message: string;
+};
+type Control = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+/**
+ * The error text for a control, from its validity. A control can bring its own text with `data-sf-error` (any
+ * failure) or `title` (pattern mismatch, the HTML convention).
+ */
+declare function validationMessage(el: Control, m?: FieldMessages): string | null;
+type UseFieldErrorsOptions = {
+    locale?: string;
+    messages?: Partial<FieldMessages>;
+    /** Fields the server rejected (e.g. from the action), shown with `serverMessages[name]` or the generic text. */
+    serverFields?: Iterable<string> | null;
+    serverMessages?: Record<string, string> | null;
+};
+type FieldErrorsState = {
+    errors: FieldErrors;
+    /** Non-null after a submit with problems (or with server errors): render it in `<ErrorSummary>`. */
+    summary: ErrorSummaryItem[] | null;
+    /** Changes every time a new summary appears, so `<ErrorSummary>` focuses it again. */
+    summaryKey: number;
+    clear: () => void;
+};
+/**
+ * Inline validation for the page `<form>`. Listens to the form (no wrapping component): leaving a field with a value
+ * checks it; typing in a field with an error clears it when fixed; a submit or `reportValidity()` with problems
+ * collects them (the browser's bubbles are replaced by the inline texts) for the summary.
+ */
+declare function useFieldErrors(formRef: RefObject<HTMLFormElement | null>, options?: UseFieldErrorsOptions): FieldErrorsState;
+type ErrorSummaryProps = {
+    items: readonly ErrorSummaryItem[] | null;
+    /** Changes when a new summary must take focus (`useFieldErrors().summaryKey`). */
+    focusKey?: number;
+    locale?: string;
+    messages?: Partial<FieldMessages>;
+    title?: ReactNode;
+    className?: string;
+    classNames?: Partial<Record<'title' | 'list' | 'link', string>>;
+};
+/**
+ * The list of problems after a submit, above the form: `role="alert"`, takes focus, one link per field (moves the
+ * focus to it). Renders nothing without items.
+ */
+declare function ErrorSummary({ items, focusKey, locale, messages, title, className, classNames: cx }: ErrorSummaryProps): react.JSX.Element | null;
+type CheckoutFieldClassNames = Partial<Record<'root' | 'label' | 'optional' | 'input' | 'hint' | 'error', string>>;
+type BaseFieldProps = {
+    name: string;
+    label: string;
+    /** Field id. Default: the name. */
+    id?: string;
+    /** Error text (from `useFieldErrors().errors[name]` or the server). */
+    error?: string | null;
+    /** Help under the label ("we only use it for the delivery"). */
+    hint?: ReactNode;
+    /** Marks the label "(optional)" and drops `required`. */
+    optional?: boolean;
+    classNames?: CheckoutFieldClassNames;
+    locale?: string;
+    messages?: Partial<FieldMessages>;
+};
+type CheckoutFieldProps = BaseFieldProps & Omit<InputHTMLAttributes<HTMLInputElement>, 'name' | 'id'> & {
+    as?: 'input';
+};
+type CheckoutSelectProps = BaseFieldProps & Omit<SelectHTMLAttributes<HTMLSelectElement>, 'name' | 'id'> & {
+    as: 'select';
+    children: ReactNode;
+};
+/**
+ * One labelled field: label (with "(optional)"), hint, the control and its error text, wired with `aria-describedby`
+ * and `aria-invalid`. Required unless `optional`. `as="select"` renders a `<select>` with the given options.
+ */
+declare function CheckoutField(props: CheckoutFieldProps | CheckoutSelectProps): react.JSX.Element;
+
+type AddressFieldKey = 'zip' | 'province' | 'city' | 'neighborhood' | 'address1' | 'address2' | 'reference';
+type ContactFieldKey = 'email' | 'phone' | 'first_name' | 'last_name';
+type AddressFieldsMessages = Record<AddressFieldKey | ContactFieldKey, string> & {
+    provincePlaceholder: string;
+    address1Hint: string;
+    referenceHint: string;
+    emailHint: string;
+    phoneHint: string;
+    lookupFilled: string;
+};
+declare function addressFieldsMessages(locale?: string | null, overrides?: Partial<AddressFieldsMessages> | null): AddressFieldsMessages;
+type FieldLayoutClassNames = CheckoutFieldClassNames & {
+    /** Extra class of a field that should span the whole row in a two-column grid. */
+    wide?: string;
+    /** Extra class of a field that fits half a row. */
+    half?: string;
+};
+type Common = {
+    /** Inline errors by field name (`useFieldErrors().errors`). */
+    errors?: FieldErrors;
+    locale?: string;
+    messages?: Partial<AddressFieldsMessages>;
+    fieldMessages?: Partial<FieldMessages>;
+    classNames?: FieldLayoutClassNames;
+};
+type ContactFieldsProps = Common & {
+    defaults?: Partial<Record<ContactFieldKey, string | null>>;
+    /** Form names. Default: the keys. */
+    names?: Partial<Record<ContactFieldKey, string>>;
+    /** Phone format from the shop or region (e.g. `{ pattern: '[0-9 +()-]{10,}', title: '10 dígitos' }`). */
+    phone?: {
+        pattern?: string;
+        title?: string;
+        minLength?: number;
+    };
+    /** Explain why e-mail and phone are needed (default true). */
+    hints?: boolean;
+};
+/** E-mail, phone, given and family name with their autofill tokens and the right mobile keyboards. */
+declare function ContactFields({ defaults, names, errors, phone, hints, locale, messages, fieldMessages: fm, classNames: cx }: ContactFieldsProps): react.JSX.Element;
+/** What a postal-code lookup answers. Every field optional: only what the source knows. */
+type PostalCodeInfo = {
+    province?: string | null;
+    city?: string | null;
+    neighborhoods?: readonly string[] | null;
+};
+type AddressFieldsProps = Common & {
+    defaults?: Partial<Pick<Address, 'zip' | 'province' | 'city' | 'neighborhood' | 'address1' | 'address2' | 'reference'>> | null;
+    /** Form names. Default: the keys (the `AddressInput` fields of the Storefront API). */
+    names?: Partial<Record<AddressFieldKey, string>>;
+    /** ISO country of the address (hidden field `country_code`). */
+    countryCode: string;
+    /** States of the country (from the region config). With them, "State" is a `<select>`; the value sent is `name`. */
+    provinces?: ReadonlyArray<{
+        code?: string | null;
+        name: string;
+    }> | null;
+    /** Postal-code format of the country (from the region config), e.g. `{ pattern: '[0-9]{5}', maxLength: 5, inputMode: 'numeric', title: '5 dígitos' }`. */
+    postalCode?: {
+        pattern?: string;
+        maxLength?: number;
+        inputMode?: 'numeric' | 'text';
+        title?: string;
+    };
+    /**
+     * Fills state and city (and suggests colonias) from the postal code, when the shop has a source (a same-origin
+     * route over a postal-code catalog). Called once the code matches `postalCode.pattern` (or on leaving the field).
+     * Never overwrites what the buyer typed.
+     */
+    lookupPostalCode?: (zip: string) => Promise<PostalCodeInfo | null>;
+    /** Show the colonia field: `true` (default, optional), `'required'`, or `false`. */
+    neighborhood?: boolean | 'required';
+    /** Show the delivery references field (default true, optional). */
+    reference?: boolean;
+    /** Rendered after the fields (e.g. "save this address"). */
+    children?: ReactNode;
+};
+/**
+ * Shipping address in the order buyers fill it: postal code, state, city, colonia, street and number, interior and
+ * references. Autofill tokens: `postal-code`, `address-level1/2/3`, `address-line1/2`. The postal code uses the
+ * numeric keyboard when the country format is numeric.
+ */
+declare function AddressFields(props: AddressFieldsProps): react.JSX.Element;
+
+type OrderSummaryMessages = {
+    title: string;
+    subtotal: string;
+    discount: string;
+    shipping: string;
+    /** Shipping not chosen yet. */
+    shippingPending: string;
+    /** Shipping being saved / re-read. */
+    updating: string;
+    free: string;
+    taxes: string;
+    /** Taxes already inside the prices, `{amount}`. */
+    taxesIncluded: string;
+    total: string;
+    /** `{n}` = quantity. */
+    quantity: string;
+    show: string;
+    hide: string;
+};
+declare function orderSummaryMessages(locale?: string | null, overrides?: Partial<OrderSummaryMessages> | null): OrderSummaryMessages;
+type OrderSummaryClassNames = Partial<Record<'root' | 'title' | 'lines' | 'line' | 'media' | 'qty' | 'lineTitle' | 'variant' | 'linePrice' | 'totals' | 'row' | 'discount' | 'muted' | 'free' | 'total' | 'note', string>>;
+type OrderSummaryProps = {
+    lines: readonly CartLine[];
+    /** `cart.cost` as the server sends it. */
+    cost: CartCost;
+    /** The delivery is being saved and the cart re-read: shipping and total say so (`aria-busy`). */
+    updating?: boolean;
+    /** Picture of a line (e.g. `<ProductImage>`), 48-64 px. The quantity badge sits on it. */
+    renderLineMedia?: (line: CartLine) => ReactNode;
+    renderAmount?: (amount: Money) => ReactNode;
+    /** Heading. `false` hides it (the disclosure already names the block). */
+    title?: ReactNode | false;
+    /** Heading level. Default 2. */
+    headingLevel?: 2 | 3;
+    locale?: string;
+    messages?: Partial<OrderSummaryMessages>;
+    classNames?: OrderSummaryClassNames;
+    /** Rendered between the lines and the totals (e.g. a discount code form). */
+    children?: ReactNode;
+};
+/** Lines and totals of the order. The total row is `aria-live`, so a new total after choosing delivery is announced. */
+declare function OrderSummary(props: OrderSummaryProps): react.JSX.Element;
+type OrderSummaryDisclosureProps = {
+    /** Total shown on the collapsed bar (`cart.cost.total`). */
+    total: Money;
+    updating?: boolean;
+    renderAmount?: (amount: Money) => ReactNode;
+    locale?: string;
+    messages?: Partial<OrderSummaryMessages>;
+    /** Start open (default closed). */
+    defaultOpen?: boolean;
+    className?: string;
+    classNames?: Partial<Record<'summary' | 'label' | 'total' | 'panel', string>>;
+    /** Usually an `<OrderSummary title={false} … />`. */
+    children: ReactNode;
+};
+/**
+ * Phones: the order summary as a collapsed bar at the top ("Show order summary · $1,234.00"). Native `<details>`:
+ * works without JavaScript, the server HTML is already the final layout (no shift on hydration). Show it only on
+ * narrow screens and the full summary on wide ones (the shop's CSS).
+ */
+declare function OrderSummaryDisclosure({ total, updating, renderAmount, locale: loc, messages, defaultOpen, className, classNames: cx, children }: OrderSummaryDisclosureProps): react.JSX.Element;
 
 type BrandMarkProps = {
     /** Provider identifier (`fedex`, `oxxo`, `mercadopago`, `7eleven`…). Unknown keys get a neutral monogram. */
@@ -107,6 +351,15 @@ type DeliveryMessages = {
     loading: string;
     /** The quote expired or changed and the rates were reloaded. */
     requoted: string;
+    /** Tag of the recommended rate that balances price and arrival time (`layout="recommended"`). */
+    bestValue: string;
+    /** Toggle of the other rates, `{n}` = how many. */
+    moreOptions: string;
+    /** Title of the group of rates without a carrier. */
+    otherCarriers: string;
+    /** The rates could not be quoted (`error`). */
+    error: string;
+    retry: string;
 };
 /** Messages for a locale (`es*` default, `en*`), with optional overrides. */
 declare function deliveryMessages(locale?: string | null, overrides?: Partial<DeliveryMessages> | null): DeliveryMessages;
@@ -159,7 +412,7 @@ declare function isQuoteChange(err: {
  */
 declare function matchRate<R extends Pick<ShippingRate, 'id' | 'carrier' | 'service_code' | 'title'>>(previous: Pick<ShippingRate, 'carrier' | 'service_code' | 'title'> | null | undefined, rates: readonly R[]): R | null;
 
-type DeliveryOptionsClassNames = Partial<Record<'root' | 'option' | 'radio' | 'mark' | 'body' | 'title' | 'carrier' | 'service' | 'eta' | 'badges' | 'badge' | 'price' | 'free' | 'note' | 'partial' | 'skeleton', string>>;
+type DeliveryOptionsClassNames = Partial<Record<'root' | 'option' | 'radio' | 'mark' | 'body' | 'title' | 'carrier' | 'service' | 'eta' | 'badges' | 'badge' | 'price' | 'free' | 'note' | 'partial' | 'skeleton' | 'more' | 'moreSummary' | 'group' | 'groupTitle' | 'error' | 'retry', string>>;
 type DeliveryOptionsProps = {
     rates: readonly ShippingRate[];
     pickup?: readonly PickupOption[];
@@ -193,6 +446,21 @@ type DeliveryOptionsProps = {
     messages?: Partial<DeliveryMessages>;
     renderAmount?: (amount: Money) => ReactNode;
     classNames?: DeliveryOptionsClassNames;
+    /**
+     * `list` (default): every rate, as the server orders them. `recommended`: up to `recommendedCount` rates (cheapest,
+     * fastest and the best balance, tagged) and the rest under "Show more options (N)", grouped by carrier so the carrier
+     * name is not repeated on every row. Repeated services are dropped (the cheapest stays). Works without JavaScript
+     * (`<details>`); it opens by itself when the chosen rate is inside.
+     */
+    layout?: 'list' | 'recommended';
+    /** Rates recommended in `layout="recommended"`. Default 3. */
+    recommendedCount?: number;
+    /**
+     * The rates could not be quoted (provider down, timeout): one friendly alert instead of the list, with a retry button
+     * when `onRetry` is set. `true` uses the default text; a string replaces it.
+     */
+    error?: boolean | string;
+    onRetry?: () => void;
     /** `data-testid` of every radio. */
     testId?: string;
     /** Rows the shop renders before the rates (e.g. "home delivery, rates after the address"). */
@@ -209,4 +477,55 @@ type DeliveryOptionsProps = {
  */
 declare function DeliveryOptions(props: DeliveryOptionsProps): react.JSX.Element;
 
-export { type Brand, type BrandKind, BrandMark, type BrandMarkProps, type BrandMarkSource, type DeliveryMessages, DeliveryOptions, type DeliveryOptionsClassNames, type DeliveryOptionsProps, type QuoteNote, type RateBadge, brandKey, brandLogo, brandName, deliveryMessages, findBrand, isQuoteChange, listBrands, matchRate, quoteDeadline, quoteNote, rateBadges, rateCarrier, rateEta, rateService };
+/**
+ * Which carrier rates to show first. Pure: no DOM, no amounts computed (costs are only compared, as the server sends
+ * them). A long quote (10+ services, several per carrier) becomes up to three recommended rows (the cheapest, the
+ * fastest and the best balance of both) plus the rest grouped by carrier, so the buyer compares three things instead of
+ * scanning a flat list.
+ */
+
+/** Why a rate is recommended. `best_value` balances price and arrival time. */
+type RateTag = 'cheapest' | 'fastest' | 'best_value';
+type RecommendedRate<R extends ShippingRate = ShippingRate> = {
+    rate: R;
+    tags: RateTag[];
+};
+type RateGroup<R extends ShippingRate = ShippingRate> = {
+    /** Brand key of the carrier (`fedex`), or `''` for rates without one. */
+    key: string;
+    /** Carrier as the server sends it (first rate of the group), for `BrandMark` and the group name. */
+    carrier: string | null;
+    rates: R[];
+};
+type RecommendRatesOptions = {
+    /** How many rates to recommend. Default 3. */
+    count?: number;
+    /**
+     * With this many rates or fewer every rate is recommended (no "more options"): hiding one or two rates behind a
+     * toggle costs more than it saves. Default `count + 1`.
+     */
+    collapseAfter?: number;
+    /** Drop repeated services (same carrier and service, e.g. quoted by two providers), keeping the cheapest. Default true. */
+    dedupe?: boolean;
+};
+type RecommendedRates<R extends ShippingRate = ShippingRate> = {
+    recommended: RecommendedRate<R>[];
+    /** Everything else, grouped by carrier; groups ordered by their cheapest rate, rates by cost. */
+    more: RateGroup<R>[];
+    /** Number of rates in `more`. */
+    moreCount: number;
+};
+/** Repeated services (same carrier, same service code or title, same arrival): only the cheapest stays. Order kept. */
+declare function dedupeRates<R extends ShippingRate>(rates: readonly R[]): R[];
+/**
+ * Up to `count` recommended rates and the rest by carrier.
+ * - **cheapest**: lowest cost (only when every rate shares the currency); a tie goes to the faster one.
+ * - **fastest**: fewest business days; a tie goes to the cheaper one. Only when some rate is strictly faster than the
+ *   cheapest, so the tag always tells the buyer something.
+ * - **best_value**: the remaining rate with the best combined position in price and in time (sum of ranks), a tie goes
+ *   to the cheaper one. Fills the remaining slots.
+ * Recommended rows come back cheapest first. Pickup is not a rate and is never hidden (the component shows it apart).
+ */
+declare function recommendRates<R extends ShippingRate>(input: readonly R[], options?: RecommendRatesOptions): RecommendedRates<R>;
+
+export { type AddressFieldKey, AddressFields, type AddressFieldsMessages, type AddressFieldsProps, type Brand, type BrandKind, BrandMark, type BrandMarkProps, type BrandMarkSource, CheckoutField, type CheckoutFieldClassNames, type CheckoutFieldProps, type CheckoutSelectProps, type ContactFieldKey, ContactFields, type ContactFieldsProps, type DeliveryMessages, DeliveryOptions, type DeliveryOptionsClassNames, type DeliveryOptionsProps, ErrorSummary, type ErrorSummaryItem, type ErrorSummaryProps, type FieldErrors, type FieldErrorsState, type FieldLayoutClassNames, type FieldMessages, OrderSummary, type OrderSummaryClassNames, OrderSummaryDisclosure, type OrderSummaryDisclosureProps, type OrderSummaryMessages, type OrderSummaryProps, type PostalCodeInfo, type QuoteNote, type RateBadge, type RateGroup, type RateTag, type RecommendRatesOptions, type RecommendedRate, type RecommendedRates, type UseFieldErrorsOptions, addressFieldsMessages, brandKey, brandLogo, brandName, dedupeRates, deliveryMessages, fieldMessages, findBrand, isQuoteChange, listBrands, matchRate, orderSummaryMessages, quoteDeadline, quoteNote, rateBadges, rateCarrier, rateEta, rateService, recommendRates, useFieldErrors, validationMessage };