@primer-io/primer-js 0.1.9 → 0.2.0

package/dist/primer-loader.d.ts

@@ -198,6 +198,24 @@ export interface PropertyDeclaration<Type = unknown, TypeHint = unknown> {
 	 * the property changes.
 	 */
 	readonly noAccessor?: boolean;
+	/**
+	 * When `true`, uses the initial value of the property as the default value,
+	 * which changes how attributes are handled:
+	 *  - The initial value does *not* reflect, even if the `reflect` option is `true`.
+	 *    Subsequent changes to the property will reflect, even if they are equal to the
+	 *     default value.
+	 *  - When the attribute is removed, the property is set to the default value
+	 *  - The initial value will not trigger an old value in the `changedProperties` map
+	 *    argument to update lifecycle methods.
+	 *
+	 * When set, properties must be initialized, either with a field initializer, or an
+	 * assignment in the constructor. Not initializing the property may lead to
+	 * improper handling of subsequent property assignments.
+	 *
+	 * While this behavior is opt-in, most properties that reflect to attributes should
+	 * use `useDefault: true` so that their initial values do not reflect.
+	 */
+	useDefault?: boolean;
 }
 /**
  * Map of properties to PropertyDeclaration options. For each property an
@@ -556,6 +574,11 @@ declare abstract class ReactiveElement extends HTMLElement implements ReactiveCo
 	 * @category updates
 	 */
 	hasUpdated: boolean;
+	/**
+	 * Records property default values when the
+	 * `useDefault` option is used.
+	 */
+	private __defaultValues?;
 	/**
 	 * Properties that should be reflected when updated.
 	 */
@@ -593,13 +616,7 @@ declare abstract class ReactiveElement extends HTMLElement implements ReactiveCo
 	 * Fixes any properties set on the instance before upgrade time.
 	 * Otherwise these would shadow the accessor and break these properties.
 	 * The properties are stored in a Map which is played back after the
-	 * constructor runs. Note, on very old versions of Safari (<=9) or Chrome
-	 * (<=41), properties created for native platform properties like (`id` or
-	 * `name`) may not have default values set in the element constructor. On
-	 * these browsers native properties appear on instances and therefore their
-	 * default value will overwrite any element default (e.g. if the element sets
-	 * this.id = 'id' in the constructor, the 'id' will become '' since this is
-	 * the native platform default).
+	 * constructor runs.
 	 */
 	private __saveInstanceProperties;
 	/**
@@ -640,7 +657,7 @@ declare abstract class ReactiveElement extends HTMLElement implements ReactiveCo
 	 * overridden, `super.attributeChangedCallback(name, _old, value)` must be
 	 * called.
 	 *
-	 * See [using the lifecycle callbacks](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#using_the_lifecycle_callbacks)
+	 * See [responding to attribute changes](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes)
 	 * on MDN for more information about the `attributeChangedCallback`.
 	 * @category attributes
 	 */
@@ -2393,12 +2410,65 @@ export declare class InitializedPayments {
 	toArray(): InitializedPaymentMethod[];
 	size(): number;
 }
-export interface OnCheckoutCompletePayload {
+export interface PaymentData {
+	paymentMethodType: string;
+}
+export interface PrepareHandler {
+	continuePaymentCreation: () => void;
+	abortPaymentCreation: () => void;
+}
+export interface PaymentCompleteData {
 	payment: Payment | null;
+	status: "success" | "pending" | "error";
+	error?: PrimerClientError;
 }
-export interface OnCheckoutFailurePayload {
-	error: PrimerClientError;
-	payment?: Payment;
+/**
+ * PrimerJS is a wrapper class that provides a stable API for interfacing with the Primer SDK
+ * while hiding direct access to the legacy headless instance.
+ */
+export declare class PrimerJS {
+	private headlessInstance;
+	private paymentMethods;
+	onPaymentStart?: () => void;
+	onPaymentPrepare?: (data: PaymentData, handler: PrepareHandler) => void;
+	onPaymentComplete?: (data: PaymentCompleteData) => void;
+	constructor(headlessInstance: PrimerHeadlessCheckout);
+	/**
+	 * Set the initialized payment methods
+	 * @internal - This is only used internally by the SDK
+	 */
+	setPaymentMethods(methods: InitializedPayments): void;
+	/**
+	 * Refetches a new client session from merchant backend.
+	 */
+	refreshSession(): Promise<void>;
+	/**
+	 * Returns the cached list of payment methods.
+	 */
+	getPaymentMethods(): PaymentMethodInfo[];
+	/**
+	 * Internal method to handle the onPaymentStart callback
+	 * @internal - This is only used internally by the SDK
+	 */
+	handlePaymentStart(): void;
+	/**
+	 * Internal method to handle the onBeforePaymentCreate callback and transform it to onPaymentPrepare
+	 * @internal - This is only used internally by the SDK
+	 */
+	handleBeforePaymentCreate(data: PaymentData, originalHandler: {
+		continuePaymentCreation: () => void;
+		abortPaymentCreation: () => void;
+	}): void;
+	/**
+	 * Internal method to handle payment completion (success)
+	 * @internal - This is only used internally by the SDK
+	 */
+	handlePaymentComplete(payment: Payment | null): void;
+	/**
+	 * Internal method to handle payment failure
+	 * @internal - This is only used internally by the SDK
+	 */
+	handlePaymentFailure(error: PrimerClientError, payment?: Payment): void;
 }
 export interface CardSubmitSuccessPayload {
 	result: unknown;
@@ -2410,14 +2480,12 @@ export interface PrimeAchErrorPayload {
 	error: Error;
 }
 export interface PrimerEvents {
-	"primer-state-changed": CustomEvent<SdkStateContext>;
-	"primer-oncheckout-complete": CustomEvent<OnCheckoutCompletePayload>;
-	"primer-oncheckout-failure": CustomEvent<OnCheckoutFailurePayload>;
-	"primer-payment-methods-updated": CustomEvent<InitializedPayments>;
-	"primer-checkout-initialized": CustomEvent<PrimerHeadlessCheckout>;
-	"primer-card-network-change": CustomEvent<CardNetworksContext>;
-	"primer-card-submit-success": CustomEvent<CardSubmitSuccessPayload>;
-	"primer-card-submit-errors": CustomEvent<CardSubmitErrorsPayload>;
+	"primer:state-change": CustomEvent<SdkStateContext>;
+	"primer:methods-update": CustomEvent<InitializedPayments>;
+	"primer:ready": CustomEvent<PrimerJS>;
+	"primer:card-network-change": CustomEvent<CardNetworksContext>;
+	"primer:card-success": CustomEvent<CardSubmitSuccessPayload>;
+	"primer:card-error": CustomEvent<CardSubmitErrorsPayload>;
 	"primer-ach-error": CustomEvent<PrimeAchErrorPayload>;
 	"primer-ach-bank-details-collected": CustomEvent;
 	"primer-ach-mandate-confirmed": CustomEvent;
@@ -2437,10 +2505,8 @@ declare class PrimerEventsController implements ReactiveController {
 	dispatchEvent<K extends keyof PrimerEvents>(type: K, detail: PrimerEvents[K]["detail"]): void;
 	dispatchSdkState(sdkState: SdkStateContext): void;
 	dispatchPaymentMethods(paymentMethods: InitializedPayments): void;
-	dispatchCheckoutInitialized(checkoutInstance: PrimerHeadlessCheckout): void;
+	dispatchCheckoutInitialized(checkoutInstance: PrimerJS): void;
 	dispatchCardNetworkChange(network: CardNetworksContext): void;
-	dispatchOnCheckoutComplete(payment: Payment | null): void;
-	dispatchOnCheckoutFailure(error: PrimerClientError, payment?: Payment): void;
 	dispatchFormSubmitSuccess(result: unknown): void;
 	dispatchFormSubmitErrors(errors: unknown): void;
 }
@@ -2733,6 +2799,146 @@ declare class StyleProcessingController implements ReactiveController {
 	 */
 	hostDisconnected(): void;
 }
+interface ReactiveControllerHost$1 {
+	/**
+	 * Adds a controller to the host, which sets up the controller's lifecycle
+	 * methods to be called with the host's lifecycle.
+	 */
+	addController(controller: ReactiveController$1): void;
+	/**
+	 * Removes a controller from the host.
+	 */
+	removeController(controller: ReactiveController$1): void;
+	/**
+	 * Requests a host update which is processed asynchronously. The update can
+	 * be waited on via the `updateComplete` property.
+	 */
+	requestUpdate(): void;
+	/**
+	 * Returns a Promise that resolves when the host has completed updating.
+	 * The Promise value is a boolean that is `true` if the element completed the
+	 * update without triggering another update. The Promise result is `false` if
+	 * a property was set inside `updated()`. If the Promise is rejected, an
+	 * exception was thrown during the update.
+	 *
+	 * @return A promise of a boolean that indicates if the update resolved
+	 *     without triggering another update.
+	 */
+	readonly updateComplete: Promise<boolean>;
+}
+interface ReactiveController$1 {
+	/**
+	 * Called when the host is connected to the component tree. For custom
+	 * element hosts, this corresponds to the `connectedCallback()` lifecycle,
+	 * which is only called when the component is connected to the document.
+	 */
+	hostConnected?(): void;
+	/**
+	 * Called when the host is disconnected from the component tree. For custom
+	 * element hosts, this corresponds to the `disconnectedCallback()` lifecycle,
+	 * which is called the host or an ancestor component is disconnected from the
+	 * document.
+	 */
+	hostDisconnected?(): void;
+	/**
+	 * Called during the client-side host update, just before the host calls
+	 * its own update.
+	 *
+	 * Code in `update()` can depend on the DOM as it is not called in
+	 * server-side rendering.
+	 */
+	hostUpdate?(): void;
+	/**
+	 * Called after a host update, just before the host calls firstUpdated and
+	 * updated. It is not called in server-side rendering.
+	 *
+	 */
+	hostUpdated?(): void;
+}
+interface ComplexAttributeConverter$1<Type = unknown, TypeHint = unknown> {
+	/**
+	 * Called to convert an attribute value to a property
+	 * value.
+	 */
+	fromAttribute?(value: string | null, type?: TypeHint): Type;
+	/**
+	 * Called to convert a property value to an attribute
+	 * value.
+	 *
+	 * It returns unknown instead of string, to be compatible with
+	 * https://github.com/WICG/trusted-types (and similar efforts).
+	 */
+	toAttribute?(value: Type, type?: TypeHint): unknown;
+}
+type AttributeConverter$1<Type = unknown, TypeHint = unknown> = ComplexAttributeConverter$1<Type> | ((value: string | null, type?: TypeHint) => Type);
+interface PropertyDeclaration$1<Type = unknown, TypeHint = unknown> {
+	/**
+	 * When set to `true`, indicates the property is internal private state. The
+	 * property should not be set by users. When using TypeScript, this property
+	 * should be marked as `private` or `protected`, and it is also a common
+	 * practice to use a leading `_` in the name. The property is not added to
+	 * `observedAttributes`.
+	 */
+	readonly state?: boolean;
+	/**
+	 * Indicates how and whether the property becomes an observed attribute.
+	 * If the value is `false`, the property is not added to `observedAttributes`.
+	 * If true or absent, the lowercased property name is observed (e.g. `fooBar`
+	 * becomes `foobar`). If a string, the string value is observed (e.g
+	 * `attribute: 'foo-bar'`).
+	 */
+	readonly attribute?: boolean | string;
+	/**
+	 * Indicates the type of the property. This is used only as a hint for the
+	 * `converter` to determine how to convert the attribute
+	 * to/from a property.
+	 */
+	readonly type?: TypeHint;
+	/**
+	 * Indicates how to convert the attribute to/from a property. If this value
+	 * is a function, it is used to convert the attribute value a the property
+	 * value. If it's an object, it can have keys for `fromAttribute` and
+	 * `toAttribute`. If no `toAttribute` function is provided and
+	 * `reflect` is set to `true`, the property value is set directly to the
+	 * attribute. A default `converter` is used if none is provided; it supports
+	 * `Boolean`, `String`, `Number`, `Object`, and `Array`. Note,
+	 * when a property changes and the converter is used to update the attribute,
+	 * the property is never updated again as a result of the attribute changing,
+	 * and vice versa.
+	 */
+	readonly converter?: AttributeConverter$1<Type, TypeHint>;
+	/**
+	 * Indicates if the property should reflect to an attribute.
+	 * If `true`, when the property is set, the attribute is set using the
+	 * attribute name determined according to the rules for the `attribute`
+	 * property option and the value of the property converted using the rules
+	 * from the `converter` property option.
+	 */
+	readonly reflect?: boolean;
+	/**
+	 * A function that indicates if a property should be considered changed when
+	 * it is set. The function should take the `newValue` and `oldValue` and
+	 * return `true` if an update should be requested.
+	 */
+	hasChanged?(value: Type, oldValue: Type): boolean;
+	/**
+	 * Indicates whether an accessor will be created for this property. By
+	 * default, an accessor will be generated for this property that requests an
+	 * update when set. If this flag is `true`, no accessor will be created, and
+	 * it will be the user's responsibility to call
+	 * `this.requestUpdate(propertyName, oldValue)` to request an update when
+	 * the property changes.
+	 */
+	readonly noAccessor?: boolean;
+}
+declare global {
+	interface SymbolConstructor {
+		readonly metadata: unique symbol;
+	}
+}
+declare global {
+	var litPropertyMetadata: WeakMap<object, Map<PropertyKey, PropertyDeclaration$1>>;
+}
 declare const sourceLocale = `en`;
 declare const targetLocales = [
 	`ar`,
@@ -3942,6 +4148,62 @@ export interface HostedInputHost extends ReactiveControllerHost, LitElement {
 	label: string;
 	requestUpdate: ReactiveControllerHost["requestUpdate"];
 }
+interface ReactiveControllerHost$1 {
+	/**
+	 * Adds a controller to the host, which sets up the controller's lifecycle
+	 * methods to be called with the host's lifecycle.
+	 */
+	addController(controller: ReactiveController$1): void;
+	/**
+	 * Removes a controller from the host.
+	 */
+	removeController(controller: ReactiveController$1): void;
+	/**
+	 * Requests a host update which is processed asynchronously. The update can
+	 * be waited on via the `updateComplete` property.
+	 */
+	requestUpdate(): void;
+	/**
+	 * Returns a Promise that resolves when the host has completed updating.
+	 * The Promise value is a boolean that is `true` if the element completed the
+	 * update without triggering another update. The Promise result is `false` if
+	 * a property was set inside `updated()`. If the Promise is rejected, an
+	 * exception was thrown during the update.
+	 *
+	 * @return A promise of a boolean that indicates if the update resolved
+	 *     without triggering another update.
+	 */
+	readonly updateComplete: Promise<boolean>;
+}
+interface ReactiveController$1 {
+	/**
+	 * Called when the host is connected to the component tree. For custom
+	 * element hosts, this corresponds to the `connectedCallback()` lifecycle,
+	 * which is only called when the component is connected to the document.
+	 */
+	hostConnected?(): void;
+	/**
+	 * Called when the host is disconnected from the component tree. For custom
+	 * element hosts, this corresponds to the `disconnectedCallback()` lifecycle,
+	 * which is called the host or an ancestor component is disconnected from the
+	 * document.
+	 */
+	hostDisconnected?(): void;
+	/**
+	 * Called during the client-side host update, just before the host calls
+	 * its own update.
+	 *
+	 * Code in `update()` can depend on the DOM as it is not called in
+	 * server-side rendering.
+	 */
+	hostUpdate?(): void;
+	/**
+	 * Called after a host update, just before the host calls firstUpdated and
+	 * updated. It is not called in server-side rendering.
+	 *
+	 */
+	hostUpdated?(): void;
+}
 export interface TaskFunctionOptions {
 	signal: AbortSignal;
 }
@@ -4036,8 +4298,8 @@ declare class Task<const T extends ReadonlyArray<unknown> = ReadonlyArray<unknow
 	private _resolveTaskComplete?;
 	private _rejectTaskComplete?;
 	private _taskComplete?;
-	constructor(host: ReactiveControllerHost, task: TaskConfig<T, R>);
-	constructor(host: ReactiveControllerHost, task: TaskFunction<T, R>, args?: ArgsFunction<T>);
+	constructor(host: ReactiveControllerHost$1, task: TaskConfig<T, R>);
+	constructor(host: ReactiveControllerHost$1, task: TaskFunction<T, R>, args?: ArgsFunction<T>);
 	hostUpdate(): void;
 	hostUpdated(): void;
 	private _getArgs;
@@ -4572,11 +4834,6 @@ declare global {
  * @returns {Promise<void>} A promise that resolves when loading is complete
  */
 export declare function loadPrimer(): Promise<void>;
-declare global {
-	interface HTMLElementTagNameMap {
-		"primer-checkout": PrimerCheckoutComponent;
-	}
-}
 
 export {
 	AchPaymentComponent as AchPayment,