UseCheckoutComponent Interface

1/**
2 * Applies mixin for base class for any checkout dedicated building block.
3 *
4 * example:
5 * export default class MyCheckoutInput extends useCheckoutComponent(LightningElement) {
6 *     setAspect(newAspect: CheckoutContainerAspect): void {
7 *         console.log(`dbb newAspect`, JSON.stringify(newAspect));
8 *     }
9 *     private handleButton(): void {
10 *         this.dispatchCommit();
11 *     }
12 * }
13 */
14 export function useCheckoutComponent(
15    superclass: Constructor<LightningElement>
16): Constructor<LightningElement & CheckoutComponent>;

1/**
2 * interface implemented by CheckoutComponentMixin
3 * and required to exist for CheckoutContainerMixin
4 */
5export interface CheckoutComponent extends CheckoutComponentHandlers {
6  /**
7   * notify the container the child component has modified data to put in the form store
8   * the container should start 'dirty form' processing:
9   * - optionally stageAction on this and other components
10   * - save form store data to the server
11   * - report errors
12   */
13  dispatchCommit(): void;
14  /**
15   * notify the DataProvider to update the form with the supplied changes.
16   * the DataProvider catches updateForm errors so components do not need to.
17   * unlike most dispatch functions this one is awaitable.
18   */
19  dispatchUpdateAsync(formRequest: CheckoutFormRequest): Promise<void>;
20  /**
21   * specialized version of dispatchUpdateAsync for setting client side errors.
22   * note: this will never reject or throw, so it's safe not to await if circumstances permit
23   */
24  dispatchUpdateErrorAsync(errorRequest: CheckoutException): Promise<void>;
25  /**
26   * notify the DataProvider to start 'final' processing (the place order button pressed)
27   * returns a Promise to facilitate advanced payment integrations.
28   */
29  dispatchFinalizeAsync(): Promise<void>;
30  /**
31   * notify the DataProvider to call place order API
32   * unlike most dispatch fns this one is awaitable.
33   */
34  dispatchPlaceOrderAsync(): Promise<OrderConfirmation>;
35  /**
36   * ask our container to change our display such as put us in summary mode
37   */
38  dispatchRequestAspect(desiredAspect: CheckoutContainerAspectRequest): void;
39}

1/**
2 * ComponentRegistration delegates CheckoutContainerSubscriptionPayload to these handlers in the derived component implementation
3 */
4export interface CheckoutComponentHandlers {
5    /**
6     * called on connect. derived classes should expose this key the DOM
7     * if DOM ordering of container children is needed.
8     * container classes combine a DOM query with sortSubscribers to break
9     * through the otherwise opaque CheckoutComponentReference.
10     * e.g. this.setAttribute('data-checkout-domkey', suggestedDomKey)
11     */
12    setDomKey(suggestedDomKey: string): string;
13    /**
14     * display hints from container such as summary mode, stencil, etc.
15     * @param newAspect update checkout mode and stage
16     */
17    setAspect(newAspect: CheckoutContainerAspect): void;
18    /**
19     * derived class must implement REPORT_VALIDITY_SAVE calls reportValidity if defined.
20     * derived class must implement CHECK_VALIDITY_UPDATE or do equivalent before dispatchCommit.
21     * unsummarize if an error encountered to ensure it is seen
22     *
23     * aside: this subsumes all of CheckoutSavable's reportValidity, checkValidity, checkoutSave, placeOrder
24     *
25     * @param _checkoutStage used to synchronize processing and responses across components
26     * @returns a Promise that resolves false if processing should be blocked
27     *          should always return true if uninterested in a stage.
28     */
29    stageAction(checkoutStage: CheckoutStage): Promise<boolean>;

1/**
2 * where in the linear steps of checkout process, affects stageAction/reportValidity responses
3 * note: these are unordered, stageAction should only use equality checks.
4 */
5export enum CheckoutStage {
6    // commit (user edit) stages that lead to form save (checkout API update)
7    //
8    // CHECK_VALIDITY_UPDATE may skip update if component updates itself on each change before dispatchCommit
9    CHECK_VALIDITY_UPDATE = 'CHECK_VALIDITY_UPDATE',
10    REPORT_VALIDITY_SAVE = 'REPORT_VALIDITY_SAVE',
11    // finalize stages that lead to place order
12    BEFORE_PAYMENT = 'BEFORE_PAYMENT',
13    PAYMENT = 'PAYMENT',
14    BEFORE_PLACE_ORDER = 'BEFORE_PLACE_ORDER',
15    PLACE_ORDER = 'PLACE_ORDER',
16}

1/**
2 * Used for nested checkout containers to specify how they are displayed
3 */
4export type CheckoutContainerAspect = {
5  /**
6   * truthy indicates DP is initializing, preparing for the place order step,
7   * or reached an unrecoverable error.
8   * input controls should render as readonly
9   *
10   * WARNING! when disabled or readonly lightning-input.reportValidity always
11   *          returns true; therefore, defer setting controls to read-only
12   *          unless they pass checkValidity.
13   *          Otherwise they break stageAction(REPORT_VALIDITY_SAVE)
14   */
15  readOnlyIfValid: boolean,
16  /**
17   * truthy indicates expandable child sections should show as collapsed
18   * typically this indicates the section is in a future accordion step, or in
19   * a past or future subway step.
20   */
21  collapse: boolean,
22  /**
23   * truthy indicates summarizable components should render as summarized
24   *
25   * component may ignore summary: true requests, and if needed respond
26   * with dispatchRequestAspect(false) to ask their containers to become unsummarized;
27   * useful because errors are not typically rendered nor fixable in
28   * summarized components.
29   */
30  summary: boolean,
31};
32/**
33 * Used by components to ask their container to change how they are displayed
34 */
35export type CheckoutContainerAspectRequest = {
36  /**
37   * true container should enter summary mode, false should leave it
38   * Children inform containers they can be summarized.
39   */
40  summarizable: boolean,
41  /**
42   * if truthy there are no options and summarized container can hide edit button
43   */
44  uneditable?: boolean,
45};

1/**
2 * holds current state of checkout from the checkout api overlayed with
3 * with unpersisted client side changes and related meta-data.
4 */
5export type CheckoutFormOverlay = CheckoutInformation & {
6  /**
7   * captured billing details
8   */
9  billingInfo?: CheckoutBillingInfo,
10  /**
11   * captured client side exceptions
12   */
13  notifications?: FormNotification[],
14  /**
15   * computed meta information about the overlay
16   */
17  formStatus?: CheckoutFormStatus,
18};
19/**
20 * billing information that is not necessarily represented
21 * in the checkout session
22 */
23export type CheckoutBillingInfo = {
24  address?: Address,
25  email?: string,
26};
27/**
28 * computed meta information about the form like is
29 * there data that should be saved
30 */
31export type CheckoutFormStatus = CheckoutFormActivity & {
32  /**
33   * true if persistForm should be called
34   * does not  account for inconguent data, billing info, etc.
35   * cleared by persistForm (sometimes) and revertForm
36   */
37  dirty: boolean,
38  /**
39   * true if some data typically saved by persistForm is incomplete
40   * for example only some of the fields required to save
41   * contactInfo have been set.
42   * promoted (cleared) to dirty (set) when updateform gets missing data.
43   * cleared by revertForm
44   */
45  incongruent: boolean,
46  /**
47   * indicates if billingInfo.address explicitly set
48   */
49  useShippingAddressForBilling: boolean,
50};
51/**
52 * used to add and remove client side notifications returned in the overlay.
53 * note: overlay's server side errors are not affected by adding or removing these.
54 * note: new client side notifications are appended to the overlay array
55 */
56export type FormNotification = {
57  /**
58   * unique ID used to clear all client notifications added in previous requests that
59   * had the same groupId.
60   */
61  groupId: string,
62  /**
63   * pass a unique type that can control where in the UI the exception renders.
64   */
65  type?: RequestErrorType,
66  /**
67   * the l10n string to display in the UI as the notification body.
68   * when detail falsey clear all client side set exceptions of this groupId.
69   */
70  detail?: string,
71  /**
72   * optional unique error class identifier which can be used to further customize
73   * the notification.
74   *
75   * Examples are the Error.name (PaymentAuthorizationError)
76   * or Error.message (CheckoutError.NO_DELIVERY_ADDRESSES)
77   */
78  code?: string,
79};

1/**
2 * used by components to update the unpersisted client side data.
3 * assumes all contents are "validated" with checkValidity
4 */
5export type CheckoutFormRequest = {
6  /**
7   * caller short hand for deliveryGroups.items[0]
8   */
9  defaultDeliveryGroup?: CheckoutFormRequestDeliveryGroup,
10  contactInfo?: ContactInfo,
11  billingInfo?: {
12    /**
13     * in FormRequest send null to revert to useShippingAddressForBilling
14     */
15    address?: Address | null,
16    email?: string,
17  },
18  notifications?: FormNotification[],
19};
20/**
21 * selectable fields of a DeliveryGroup
22 */
23export type CheckoutFormRequestDeliveryGroup = {
24  /**
25   * notice changing the deliveryAddress results in all existing
26   * availableDeliveryMethods and any selectedDeliveryMethod (even
27   * an explictly set one) to be removed from the overlay until the
28   * new deliveryAddress is saved.
29   */
30  deliveryAddress?: Address,
31  desiredDeliveryDate?: string,
32  shippingInstructions?: string,
33  /**
34   * in FormRequest send null to revert to existing selection
35   *
36   * notice an invalid (or no longer valid) delivery method selection
37   * is ignored (the xisting selection (if any) shows in the overlay
38   *
39   * notice that by default changing the deliveryAddress will not
40   * clear any explicitly set selectedDeliveryMethodId.  if a caller
41   * wants to reset to the default (cheapest) delivery method when
42   * changing addresses they must also explicitly clear any previous
43   * selectedDeliveryMethodId setting.
44   */
45  selectedDeliveryMethodId?: string | null,
46};