@shipengine/elements 0.34.0 → 0.36.0

package/src/elements/account-settings/account-settings.d.ts

@@ -1,8 +1,70 @@
 /// <reference types="react" />
+/**
+ * # Account Settings Component Props
+ *
+ * - These are the base props that will be passed into the `<AccountSettings />` component.
+ *
+ * @see {@link AccountSettings.Component | This prop types usage in the `<AccountSettings /> component`}
+ */
 export type ComponentProps = {
+    /**
+     * This callback function will be used to house the logic you wish to execute when the
+     * user saves new changes to their account settings.
+     */
     onSaveSettings: () => void;
 };
+/**
+ * # Account Settings Component
+ *
+ * - The `<AccountSettings />` component is used to display the user's account settings, as well as
+ * allowing them to make changes to various aspects of their account.
+ *
+ * @param onSaveSettings Any `void` function you wish to execute when the user saves any changes
+ * to their account settings.
+ *
+ * @returns Element An EmotionJSX.Element that will render the `<AccountSettings />` component
+ * with all the appropriate wrappers.
+ *
+ * @example
+ * You can see how the `<Component />` is used in the `createElement` function call below.
+ * ```tsx
+ * export const Element = alchemy.createElement(Component, ErrorFallback, {
+ *   css: { height: "100%", maxWidth: "800px", minWidth: "440px", width: "100%" },
+ *   resources: { en },
+ * });
+ * ```
+ *
+ * <br />
+ *
+ * @see {@link AccountSettings.Element | The **Element** created to render `<AccountSettings />`}
+ */
 export declare const Component: ({ onSaveSettings }: ComponentProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ * # Registered Account Settings Element
+ *
+ * - This is the registered `<AccountSettings />` element that will be used to render the
+ * `<AccountSettings.Element />` component.
+ *
+ * @param ElementProps The props, callbacks, and resources necessary to render
+ * the `<AccountSettings.Element />` component.
+ *
+ * @example
+ * The `<Component />` is the source JSX that is rendered when you make use of the `AccountSettings`
+ * Element directly. Here is a brief example of how you would use it within your application.
+ * ```tsx
+ * <AccountSettings.Element
+ *   onSaveSettings={() => console.log('Settings Saved!')}
+ * />
+ * ```
+ *
+ * <br />
+ *
+ * @see {@link AccountSettings.ComponentProps | The **props** that can be passed into the `<AccountSettings.Element />` component}
+ * @see {@link ListCarriers.Component | The `<List-Carriers />` component used to view connected carriers}
+ * @see {@link ManageWarehouses.Component | The `<ManageWarehouses />` component used to add, update, or remove warehouses}
+ * @see {@link PaymentMethodSettings | The `<PaymentMethodSettings />` component used to manage payment methods}
+ * @see {@link ManageFunding | The `<ManageFunding />` component used to manage funding rules and add funds to a carrier account}
+ */
 export declare const Element: ({ resources, ...props }: ComponentProps & {
     resources?: {
         en: {
@@ -114,6 +176,32 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                     };
                 };
                 settings: {
+                    /**
+                     * # Registered Account Settings Element
+                     *
+                     * - This is the registered `<AccountSettings />` element that will be used to render the
+                     * `<AccountSettings.Element />` component.
+                     *
+                     * @param ElementProps The props, callbacks, and resources necessary to render
+                     * the `<AccountSettings.Element />` component.
+                     *
+                     * @example
+                     * The `<Component />` is the source JSX that is rendered when you make use of the `AccountSettings`
+                     * Element directly. Here is a brief example of how you would use it within your application.
+                     * ```tsx
+                     * <AccountSettings.Element
+                     *   onSaveSettings={() => console.log('Settings Saved!')}
+                     * />
+                     * ```
+                     *
+                     * <br />
+                     *
+                     * @see {@link AccountSettings.ComponentProps | The **props** that can be passed into the `<AccountSettings.Element />` component}
+                     * @see {@link ListCarriers.Component | The `<List-Carriers />` component used to view connected carriers}
+                     * @see {@link ManageWarehouses.Component | The `<ManageWarehouses />` component used to add, update, or remove warehouses}
+                     * @see {@link PaymentMethodSettings | The `<PaymentMethodSettings />` component used to manage payment methods}
+                     * @see {@link ManageFunding | The `<ManageFunding />` component used to manage funding rules and add funds to a carrier account}
+                     */
                     title: string;
                     billing: {
                         title: string;
@@ -162,6 +250,32 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                     "requires-additional-handling": string;
                     addOns: string;
                     contentDescription: string;
+                    /**
+                     * # Registered Account Settings Element
+                     *
+                     * - This is the registered `<AccountSettings />` element that will be used to render the
+                     * `<AccountSettings.Element />` component.
+                     *
+                     * @param ElementProps The props, callbacks, and resources necessary to render
+                     * the `<AccountSettings.Element />` component.
+                     *
+                     * @example
+                     * The `<Component />` is the source JSX that is rendered when you make use of the `AccountSettings`
+                     * Element directly. Here is a brief example of how you would use it within your application.
+                     * ```tsx
+                     * <AccountSettings.Element
+                     *   onSaveSettings={() => console.log('Settings Saved!')}
+                     * />
+                     * ```
+                     *
+                     * <br />
+                     *
+                     * @see {@link AccountSettings.ComponentProps | The **props** that can be passed into the `<AccountSettings.Element />` component}
+                     * @see {@link ListCarriers.Component | The `<List-Carriers />` component used to view connected carriers}
+                     * @see {@link ManageWarehouses.Component | The `<ManageWarehouses />` component used to add, update, or remove warehouses}
+                     * @see {@link PaymentMethodSettings | The `<PaymentMethodSettings />` component used to manage payment methods}
+                     * @see {@link ManageFunding | The `<ManageFunding />` component used to manage funding rules and add funds to a carrier account}
+                     */
                     confirmation: string;
                     dimensions: {
                         length: string;
@@ -209,6 +323,7 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 rates: {
                     uspsMediaMailAcknowledgement: string;
                     uspsFirstClassMailAcknowledgement_leof: string;
+                    dhlExpressTermsAcknowledgement: string;
                 };
                 shipToAddressFormFields: string;
                 sections: {
@@ -460,6 +575,13 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                     directSignature: string;
                     none: string;
                     signature: string;
+                    /**
+                     *  # Account Settings Element Props
+                     *
+                     *  - These are the base props that will be passed into the `<AccountSettings />` element.
+                     *
+                     *  @see {@link AccountSettings.Element | See the full type that `typeof Element` will return}
+                     */
                     verbalConfirmation: string;
                 };
                 customs: {
@@ -595,11 +717,16 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                     ounces: string;
                     pounds_one: string;
                     pounds_other: string;
+                    kilogram: string;
+                    gram: string;
                 };
                 units: {
-                    in: string;
+                    inch: string;
                     lbs: string;
                     oz: string;
+                    centimeter: string;
+                    gram: string;
+                    kilogram: string;
                 };
                 "VGhlIHNlbGVjdGVkIHNlcnZpY2UgaW5jbHVkZXMgaW5zdXJhbmNlIGZvciBhbiBpbnN1cmVkIGFtb3VudCB1cCB0byAkMTAwLgo=": string;
                 "VGhlIHNlbGVjdGVkIHNlcnZpY2UgaW5jbHVkZXMgaW5zdXJhbmNlIGZvciBhbiBpbnN1cmVkIGFtb3VudCB1cCB0byAkNTAuCg==": string;
@@ -608,6 +735,7 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBVUFMgd2VpZ2h0IGxpbWl0IHBlciBwYWNrYWdlIGlzIDE1MCBsYnMu: string;
                 UGxlYXNlIGFkZCBhIFN0YW1wcy5jb20gYWNjb3VudCB0byBTaGlwRW5naW5lIGluIG9yZGVyIHRvIGNyZWF0ZSBzaGlwcGluZyBsYWJlbHMu: string;
                 QSBzaGlwcGluZyBlcnJvciBvY2N1cnJlZDogTWlzc2luZyBvciBpbnZhbGlkIHNoaXBwZXIgbnVtYmVy: string;
+                QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBNaXNzaW5nIG9yIGludmFsaWQgc2hpcHBlciBuYW1l: string;
                 "QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBNaXNzaW5nIG9yIGludmFsaWQgc2hpcCB0byBTdGF0ZVByb3ZpbmNlQ29kZQ==": string;
                 "QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBJbnZhbGlkIHNvbGQgdG8gc3RhdGUgcHJvdmluY2UgY29kZS4gVmFsaWQgbGVuZ3RoIGlzIDAgdG8gNSBhbHBoYW51bWVyaWM=": string;
             };
@@ -627,4 +755,11 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
         };
     } | undefined;
 }) => import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ *  # Account Settings Element Props
+ *
+ *  - These are the base props that will be passed into the `<AccountSettings />` element.
+ *
+ *  @see {@link AccountSettings.Element | See the full type that `typeof Element` will return}
+ */
 export type ElementProps = React.ComponentProps<typeof Element>;

package/src/elements/configure-shipment/configure-shipment.d.ts

@@ -8,6 +8,7 @@ export type RateFormFeatures = {
     enableGlobalPostFiltering?: boolean;
     labelLayout?: boolean;
     nicknameRate?: boolean;
+    requireDhlTermsAcknowledgement?: boolean;
     saveRate?: boolean;
 };
 export type ConfigureShipmentFeatures = {

package/src/elements/configure-shipment/hooks/use-rates-form.d.ts

@@ -12,8 +12,8 @@ export type UseRatesFormProps = {
 };
 export declare const useRatesForm: ({ onBeforeLabelCreate, onLabelCreateFailure, onLabelCreateSuccess, onRateSaved, onRatesCalculated, onShipmentUpdated, printLabelLayout, shipment, }: UseRatesFormProps) => {
     carriers: SE.Carrier[] | undefined;
-    displayableErrors: string[] | undefined;
     displayableLabelErrors: string[] | undefined;
+    displayableRateErrors: string[] | undefined;
     errors: SE.CodedError[] | undefined;
     isLoading: boolean;
     labelErrors: SE.CodedError[] | undefined;
@@ -22,7 +22,7 @@ export declare const useRatesForm: ({ onBeforeLabelCreate, onLabelCreateFailure,
     onSave: ({ carrierId, serviceCode }: Pick<SE.Rate, "carrierId" | "serviceCode">) => Promise<void>;
     onSubmit: (rateId: string) => Promise<void>;
     rates: SE.Rate[] | undefined;
-    requestRates: (shipment: SE.SalesOrderShipment) => Promise<void>;
+    requestRates: (shipment: SE.SalesOrderShipment, isInternational: boolean) => Promise<void>;
     resetLabel: () => void;
     resetRates: () => void;
     shipment: SE.SalesOrderShipment | undefined;

package/src/elements/configure-shipment/hooks/use-rates-with-cache.d.ts

@@ -25,6 +25,6 @@ export declare const useRatesWithCache: ({ shipment, onRatesCalculated }: UseRat
         shipment_id: string;
         status: "error" | "working" | "completed" | "partial";
     } | undefined;
-    requestRates: (shipment: SE.SalesOrderShipment) => Promise<void>;
+    requestRates: (shipment: SE.SalesOrderShipment, isInternational: boolean) => Promise<void>;
     resetRates: () => void;
 };

package/src/elements/configure-shipment/hooks/use-request-rates.d.ts

@@ -6,6 +6,6 @@ export declare const useRequestRates: ({ onRatesCalculated }: UseRequestRatesPro
     ratesCalculating: boolean;
     ratesErrors: SE.CodedError[] | null;
     ratesResponse: SE.RateResponse | undefined;
-    requestRates: (shipment: SE.SalesOrderShipment) => Promise<void>;
+    requestRates: (shipment: SE.SalesOrderShipment, isInternational: boolean) => Promise<void>;
     resetRates: () => void;
 };

package/src/elements/configure-shipment/hooks/use-shipment-form.d.ts

@@ -13,6 +13,7 @@ export type UseShipmentFormProps = {
     shipment?: SE.SalesOrderShipment;
 };
 export declare const useShipmentForm: ({ compatibleCountryCodes, onAddressValidation, onApplyPreset, onChangeAddress, onShipmentUpdated, onSubmit, salesOrder, shipment, }: UseShipmentFormProps) => {
+    accountSettings: SE.AccountSettings | undefined;
     addressLoading: boolean;
     addressPreference: import("../../../components/templates").AddressPreference | undefined;
     carriers: SE.Carrier[] | undefined;

package/src/elements/list-carriers/list-carriers.d.ts

@@ -1,5 +1,36 @@
 import { OnboardingProps } from "../../components/templates";
+/**
+ * # List-Carriers Props
+ *
+ * @see {@link ListCarriers.Component | The `<List-Carriers />` component}
+ */
 export type ComponentProps = {
+    /**
+     * `features` is a set of feature flags you would like to enable or disable in this component.
+     */
     features?: OnboardingProps["features"];
 };
+/**
+ * # List-Carriers Component
+ *
+ * @param ComponentProps The base props that will be passed into the `<List-Carriers />` component.
+ *
+ * @returns Element A React element that renders the `<List-Carriers />` component allowing users
+ * to view a list of carriers that are connected to their ShipEngine account. This component is
+ * composed in the `<AccountSettings />` Element.
+ *
+ * @example
+ * ```tsx
+ * (() => {
+ *   const features = useFeatures("Global");
+ *
+ *   return <ListCarriers.Component features={features} />;
+ * })();
+ * ```
+ *
+ * <br />
+ *
+ * @see {@link ListCarriers.ComponentProps | The props that are passed into the `<List-Carriers />` component}
+ * @see {@link AccountSettings.Element | The `<AccountSettings />` component renders the `<List-Carriers />` component}
+ */
 export declare const Component: ({ features }: ComponentProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/elements/manage-warehouses/manage-warehouses.d.ts

@@ -1,5 +1,39 @@
 import { Templates } from "../../components";
+/**
+ * # Manage Warehouses Props
+ *
+ * - These are the base props that will be passed into the `<ManageWarehouses />` component.
+ *
+ * @see {@link ManageWarehouses.Component | The `<ManageWarehouses />` component}
+ */
 export type ComponentProps = {
+    /**
+     * `onWarehouseAddressValidation` is an optional callback function that will be invoked when a
+     * warehouse address is validated.
+     */
     onWarehouseAddressValidation?: (originAddressPreference: Templates.AddressPreference, returnAddressPreference?: Templates.AddressPreference) => Promise<void> | void;
 };
+/**
+ * # Manage Warehouses Component
+ *
+ * - The `<ManageWarehouses />` component is used to manage warehouses on a user's ShipEngine account. Users can add, update, or make warehouses inactive.
+ * `<AccountSettings />` Element.
+ *
+ * @param ComponentProps The base props that will be passed into the `<ManageWarehouses />` component.
+ *
+ * @returns Element A React element that renders the `<ManageWarehouses />` component allowing users
+ * to manage warehouses on their ShipEngine account.
+ *
+ * @example
+ * ```tsx
+ * export const ManageWarehousesExample = () => {
+ *   return <ManageWarehouses.Component />;
+ * };
+ * ```
+ *
+ * <br />
+ *
+ * @see {@link ManageWarehouses.ComponentProps | The props that are passed into the `<ManageWarehouses />` component}
+ * @see {@link AccountSettings.Element | The `<AccountSettings />` component renders the `<ManageWarehouses />` component}
+ */
 export declare const Component: ({ onWarehouseAddressValidation }: ComponentProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/elements/onboarding/onboarding.d.ts

@@ -1,12 +1,89 @@
 /// <reference types="react" />
 import { OnboardingProps } from "../../components/templates";
+/**
+ * # Onboarding Component Props
+ *
+ * - These are the base props that will be passed into the `<Onboarding />` component.
+ *
+ * @see {@link Onboarding.Component | This prop types usage in the `<Onboarding />` component}
+ */
 export type ComponentProps = {
+    /**
+     * `features` is a set of feature flags you would like to enable or disable in this component.
+     */
     features?: OnboardingProps["features"];
+    /**
+     * `onboardingAddress` is the address that will be used to create the warehouse for the user
+     * during the onboarding process.
+     */
     onboardingAddress?: OnboardingProps["onboardingAddress"];
+    /**
+     * `onCompleteOnboarding` is a callback function that will be invoked once the onboarding process
+     * is completed.
+     */
     onCompleteOnboarding: () => void;
+    /**
+     * `partnerName` is the name of the partner that is using the Onboarding component. This is typically
+     * the name of the entity that owns the host application.
+     */
     partnerName?: OnboardingProps["partnerName"];
 };
+/**
+ * # Onboarding Component
+ *
+ * - The `<Onboarding />` component is used to onboard a new user to the ShipEngine platform. This
+ * component will allow the user to create a warehouse, register a carrier, and create a funding
+ * source for their account. This is everything a user needs to begin fulfilling their shipments
+ * using the ShipEngine Platform.
+ *
+ * @param ComponentProps The base props that will be passed into the `<Onboarding />` component.
+ *
+ * @returns Element An EmotionJSX.Element that will render the `<Onboarding />` component
+ * with all the appropriate wrappers.
+ *
+ * @example
+ * You can see how the `<Component />` is used in the `createElement` function call below.
+ * ```tsx
+ * export const Element = alchemy.createElement(Component, ErrorFallback, {
+ *   css: {
+ *     height: "100%",
+ *     maxWidth: "800px",
+ *     minWidth: "440px",
+ *     overflow: "auto",
+ *     scrollbarGutter: "stable both-edges",
+ *     width: "100%",
+ *   },
+ *   resources: { en },
+ * });
+ * ```
+ *
+ * <br />
+ *
+ * @see {@link Onboarding.Element | The **Element** created to render `<Onboarding />`}
+ */
 export declare const Component: ({ features, onboardingAddress, onCompleteOnboarding, partnerName, }: ComponentProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ * # Registered Onboarding Element
+ *
+ * - This is the registered `<Onboarding />` element that will be used to render the
+ * `<Onboarding.Element />` component.
+ *
+ * @param ElementProps The props, callbacks, and resources necessary to render
+ * the `<Onboarding.Element />` component.
+ *
+ * @example
+ * The `<Component />` is the source JSX that is rendered when you make use of the `Onboarding`
+ * Element directly. Here is a brief example of how you would use it within your application.
+ * ```tsx
+ * <Onboarding.Element
+ *   onCompleteOnboarding={() => console.log('Onboarding Complete!')}
+ * />
+ * ```
+ *
+ * <br />
+ *
+ * @see {@link Onboarding.ComponentProps | The **props** that can be passed into the `<Onboarding.Element />` component}
+ */
 export declare const Element: ({ resources, ...props }: ComponentProps & {
     resources?: {
         en: {
@@ -213,6 +290,7 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 rates: {
                     uspsMediaMailAcknowledgement: string;
                     uspsFirstClassMailAcknowledgement_leof: string;
+                    dhlExpressTermsAcknowledgement: string;
                 };
                 shipToAddressFormFields: string;
                 sections: {
@@ -240,7 +318,9 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 };
                 steps: {
                     register: string;
-                    carriers: string;
+                    carriers: string; /**
+                     * `features` is a set of feature flags you would like to enable or disable in this component.
+                     */
                     addresses: string;
                     billing: string;
                 };
@@ -599,11 +679,16 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                     ounces: string;
                     pounds_one: string;
                     pounds_other: string;
+                    kilogram: string;
+                    gram: string;
                 };
                 units: {
-                    in: string;
+                    inch: string;
                     lbs: string;
                     oz: string;
+                    centimeter: string;
+                    gram: string;
+                    kilogram: string;
                 };
                 "VGhlIHNlbGVjdGVkIHNlcnZpY2UgaW5jbHVkZXMgaW5zdXJhbmNlIGZvciBhbiBpbnN1cmVkIGFtb3VudCB1cCB0byAkMTAwLgo=": string;
                 "VGhlIHNlbGVjdGVkIHNlcnZpY2UgaW5jbHVkZXMgaW5zdXJhbmNlIGZvciBhbiBpbnN1cmVkIGFtb3VudCB1cCB0byAkNTAuCg==": string;
@@ -612,6 +697,7 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
                 QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBVUFMgd2VpZ2h0IGxpbWl0IHBlciBwYWNrYWdlIGlzIDE1MCBsYnMu: string;
                 UGxlYXNlIGFkZCBhIFN0YW1wcy5jb20gYWNjb3VudCB0byBTaGlwRW5naW5lIGluIG9yZGVyIHRvIGNyZWF0ZSBzaGlwcGluZyBsYWJlbHMu: string;
                 QSBzaGlwcGluZyBlcnJvciBvY2N1cnJlZDogTWlzc2luZyBvciBpbnZhbGlkIHNoaXBwZXIgbnVtYmVy: string;
+                QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBNaXNzaW5nIG9yIGludmFsaWQgc2hpcHBlciBuYW1l: string;
                 "QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBNaXNzaW5nIG9yIGludmFsaWQgc2hpcCB0byBTdGF0ZVByb3ZpbmNlQ29kZQ==": string;
                 "QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBJbnZhbGlkIHNvbGQgdG8gc3RhdGUgcHJvdmluY2UgY29kZS4gVmFsaWQgbGVuZ3RoIGlzIDAgdG8gNSBhbHBoYW51bWVyaWM=": string;
             };
@@ -631,4 +717,9 @@ export declare const Element: ({ resources, ...props }: ComponentProps & {
         };
     } | undefined;
 }) => import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ * # Onboarding Element Props
+ *
+ * @see {@link Onboarding.Element | See the full type that `typeof Element` will return}
+ */
 export type ElementProps = React.ComponentProps<typeof Element>;