@shipengine/elements 0.34.0 → 0.36.0

package/src/hooks/use-page-layout.d.ts

@@ -3,9 +3,33 @@ type PageLayoutContextValue = {
     FooterPortal: React.FC<PropsWithChildren>;
     HeaderPortal: React.FC<PropsWithChildren>;
 };
-type PageLayoutProviderProps = {
+/**
+ * @internal
+ *
+ * # Page Layout Props
+ *
+ * @see {@link PageLayoutProvider | The `<PageLayoutProvider />` component}
+ */
+export type PageLayoutProviderProps = {
+    /**
+     * `children` are the elements that will be rendered inside the page layout.
+     */
     children: React.ReactNode;
 };
+/**
+ * @internal
+ *
+ * # Page Layout Component
+ *
+ * @see {@link PageLayoutProviderProps | The props passed into the `<PageLayoutProvider />` component}
+ */
 export declare const PageLayoutProvider: ({ children }: PageLayoutProviderProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+/**
+ * @internal
+ *
+ * # Page Layout Hook
+ *
+ * @category Hooks
+ */
 export declare const usePageLayout: () => PageLayoutContextValue;
 export {};

package/src/hooks/use-root-portal.d.ts

@@ -3,17 +3,30 @@ type RootPortalProviderProps = {
     children: React.ReactNode;
 };
 /**
+ * @internal
+ *
+ * # Root Portal Provider
+ *
  * Provides access to a top-level 'root-portal' DOM node, adjacent the app 'root' div
  *
  * @category Providers
  *
- * @see {@link ElementsProvider}
+ * @see {@link useRootPortal | The associated `hook` for this provider}
  */
 export declare const RootPortalProvider: ({ children }: RootPortalProviderProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 /**
- * Must be used within {@link RootPortalProvider}
+ * @internal
+ *
+ * # Root Portal Provider Hook
+ *
+ * The `useRootPortal` hook provides access to a top-level 'root-portal' DOM node, adjacent
+ * the app 'root' div.
+ *
+ * -  Must be used within {@link RootPortalProvider | a `<RootPortalProvider />`}
  *
  * @category Elements Hooks
+ *
+ * @see {@link RootPortalProvider | The associated `provider` for this hook}
  */
 export declare const useRootPortal: () => HTMLDivElement;
 export {};

package/src/hooks/use-run-once-on-true.d.ts

@@ -1,5 +1,9 @@
 /**
- * Runs a callback once and only once when a condition is true.
+ * @internal
+ *
+ * # Run Once On True Hook
+ *
+ * - Runs a callback once and only once when a condition is true.
  *
  * @param conditionalEffect A logical expression ending with a callback
  * @example useRunOnceOnTrue(testValue && anotherTestValue && (() => console.log("Hello world!")));

package/src/hooks/use-scrub-errors.d.ts

@@ -5,10 +5,13 @@ type UseScrubErrorsProps = {
     scrubber: (e: SE.CodedError) => string;
 };
 /**
+ * @internal
+ *
+ * # Scrub Errors Hook
+ *
  * Generic error pretty printer
- * @param errors
- * @param predicate
- * @param scrubber
+ *
+ * @category Hooks
  */
 export declare const useScrubErrors: ({ scrubber, errors, predicate }: UseScrubErrorsProps) => string[] | undefined;
 export {};

package/src/hooks/use-toggle.d.ts

@@ -1,5 +1,9 @@
 /**
- * Create a boolean that can be toggled or set to a specific value
+ * @internal
+ *
+ * # Toggle Hook
+ *
+ * - Create a boolean that can be toggled or set to a specific value
  *
  * @example
  * ```tsx

package/src/locales/en/index.d.ts

@@ -202,6 +202,7 @@ declare const _default: {
         rates: {
             uspsMediaMailAcknowledgement: string;
             uspsFirstClassMailAcknowledgement_leof: string;
+            dhlExpressTermsAcknowledgement: string;
         };
         shipToAddressFormFields: string;
         sections: {
@@ -588,11 +589,16 @@ declare const _default: {
             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;
@@ -601,6 +607,7 @@ declare const _default: {
         QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBVUFMgd2VpZ2h0IGxpbWl0IHBlciBwYWNrYWdlIGlzIDE1MCBsYnMu: string;
         UGxlYXNlIGFkZCBhIFN0YW1wcy5jb20gYWNjb3VudCB0byBTaGlwRW5naW5lIGluIG9yZGVyIHRvIGNyZWF0ZSBzaGlwcGluZyBsYWJlbHMu: string;
         QSBzaGlwcGluZyBlcnJvciBvY2N1cnJlZDogTWlzc2luZyBvciBpbnZhbGlkIHNoaXBwZXIgbnVtYmVy: string;
+        QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBNaXNzaW5nIG9yIGludmFsaWQgc2hpcHBlciBuYW1l: string;
         "QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBNaXNzaW5nIG9yIGludmFsaWQgc2hpcCB0byBTdGF0ZVByb3ZpbmNlQ29kZQ==": string;
         "QSBzaGlwcGluZyBjYXJyaWVyIGVycm9yIG9jY3VycmVkOiBJbnZhbGlkIHNvbGQgdG8gc3RhdGUgcHJvdmluY2UgY29kZS4gVmFsaWQgbGVuZ3RoIGlzIDAgdG8gNSBhbHBoYW51bWVyaWM=": string;
     };

package/src/schemas/shipengine/money.d.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 import { SE } from "@shipengine/alchemy";
 /**
+ * @internal
+ *
+ * # Money Schema
+ *
  * @category Form Validation
  */
 export declare const moneySchema: z.ZodObject<{

package/src/schemas/shipengine/phone.d.ts

@@ -1,10 +1,18 @@
 import { CountryCode } from "libphonenumber-js/min";
 import { z } from "zod";
 /**
+ * @internal
+ *
+ * # Phone utils
+ *
  * @category Form Validation
  */
 export declare const phoneSchema: (defaultCountryCode?: CountryCode) => z.ZodEffects<z.ZodString, string, string>;
 /**
+ * @internal
+ *
+ * # Phone utils
+ *
  * @category Form Validation
  */
 export declare const phoneSchemaUnvalidated: z.ZodString;

package/src/types/carrier-metadata.d.ts

@@ -1,4 +1,9 @@
 import { CarrierConnection, SE } from "@shipengine/alchemy";
+/**
+ * @internal
+ *
+ * # Carrier Metadata - Terms
+ */
 export type CarrierTerm = {
     description: string;
     name: string;
@@ -6,11 +11,21 @@ export type CarrierTerm = {
     url: string;
     version: string;
 };
+/**
+ * @internal
+ *
+ * # Carrier Metadata - Terms
+ */
 export type CarrierTerms = {
     content: string[];
     links: CarrierTerm[];
     title: string;
 };
+/**
+ * @internal
+ *
+ * # Carrier Metadata
+ */
 export type CarrierMetadata = {
     carrierCode: CarrierConnection["carrierCode"];
     logo: string;
@@ -20,6 +35,11 @@ export type CarrierMetadata = {
     shortname: string;
     terms?: CarrierTerms;
 };
+/**
+ * @internal
+ *
+ * # Carrier Metadata - Features
+ */
 export type CarriersFeatures = {
     enabledCarriers?: SE.Carrier["carrierCode"][];
 };

package/src/utilities/create-dictionary.d.ts

@@ -1,4 +1,8 @@
 /**
+ * @internal
+ *
+ * # Create Dictionary Utility Function
+ *
  * @category Utilities
  */
 export declare const createDictionary: <T extends object, U>(items: T[] | undefined, getEntry: (item: T, partialResults: Record<string, U | undefined>) => Record<string, U | undefined>) => Record<string, U | undefined>;

package/src/utilities/date.d.ts

@@ -1,42 +1,92 @@
 /**
+ * @internal
+ *
+ * # Date Utils - getDaysInMonth
+ *
  * @category Utilities
  */
 export declare const formatDate: (date: string, locale?: string) => string;
 /**
+ * @internal
+ *
+ * # Date Utils - formatDateDDMMYY
+ *
  * @category Utilities
  */
 export declare const formatDateDDMMYY: (date: string, locale?: string) => string;
 /**
+ * @internal
+ *
+ * # Date Utils - getDaysInMonth
+ *
  * @category Utilities
  */
 export declare const daysAfter: (days: number, date?: Date) => Date;
 /**
+ * @internal
+ *
+ * # Date Utils - getDaysInMonth
+ *
  * @category Utilities
  */
 export declare const nextDayCutoff: (cutoff: number, date?: Date) => Date;
 /**
+ * @internal
+ *
+ * # Date Utils - getDaysInMonth
+ *
  * @category Utilities
  */
 export declare const mostRecent: (...dates: Date[]) => Date;
 /**
+ * @internal
+ *
+ * # Date Utils - getDaysInMonth
+ *
  * @category Utilities
  */
 export declare const omitTime: (shipDate?: string) => Date;
 /**
+ * @internal
+ *
+ * # Date Utils - getExpirationYears
+ *
  * @category Utilities
  */
 export declare const getExpirationYears: (yearsValid: number) => string[];
 /**
+ * @internal
+ *
+ * # Date Utilities - HasCreationDate Type
+ *
  * @category Utilities
  */
-type HasCreationDate = {
+export type HasCreationDate = {
     createdAt: string;
 };
+/**
+ * @internal
+ *
+ * # Date Utilities - sortByCreationDate
+ *
+ * @category Utilities
+ */
 export declare const sortByCreationDate: (a: HasCreationDate, b: HasCreationDate, order?: "asc" | "desc") => number;
 /**
+ * @internal
+ *
+ * # Date Utilities - isNowOrInTheFuture
+ *
  * @category Utilities
  */
 export declare const isNowOrInTheFuture: (shipDate?: string) => boolean;
+/**
+ * @internal
+ *
+ * # Date Utilities - getRelativeDates
+ *
+ * @category Utilities
+ */
 export declare const getRelativeDates: (from?: Date) => {
     firstDayOfMonth: Date;
     lastDayOfTheMonth: Date;
@@ -45,4 +95,3 @@ export declare const getRelativeDates: (from?: Date) => {
     previousMonthLastDay: Date;
     thirtyDaysAgo: Date;
 };
-export {};

package/src/utilities/error.d.ts

@@ -1,5 +1,11 @@
 import { SE } from "@shipengine/alchemy";
 /**
+ * @internal
+ *
+ * # Create Coded Errors Utlity Function
+ *
+ * - This function extracts errors from our `Axios Responses`.
+ *
  * @category Utilities
  */
 export declare const createCodedErrors: (err: any) => any;
@@ -7,11 +13,19 @@ type HasMessage = {
     message: string;
 };
 /**
- * Joins a list of error-like object's messages and throws them as a single error.
+ * @internal
+ *
+ * - Joins a list of error-like object's messages and throws them as a single error.
+ *
+ * @category Utilities
  */
 export declare function throwJoinedMessages(errors: HasMessage[]): never;
 /**
- * If any CodedErrors exist, throw them all as a single error, otherwise assert errors is null.
+ * @internal
+ *
+ * - If any CodedErrors exist, throw them all as a single error, otherwise assert errors is null.
+ *
+ * @category Utilities
  */
 export declare function throwAny(errors: SE.CodedError[] | null): asserts errors is null;
 export {};

package/src/utilities/feature-flags.d.ts

@@ -1,3 +1,184 @@
+/**
+ * @namespace featureFlags
+ *
+ * - The `featureFlags` namespace contains all the feature flags available throughout the
+ * application. All features are scoped by name to the component they are intended for.
+ *
+ * @example
+ * ```tsx
+ * export const featureFlags = {
+ *   ConfigureSalesOrderShipment: {
+ *     compatibleCountryCodes: ["AU", "CA", "FR", "DE", "GB", "IL", "IT", "NO", "ES", "SE", "US"],
+ *     rateForm: {
+ *       enableFunding: false,
+ *       enableGlobalPostFiltering: false,
+ *       labelLayout: false,
+ *       nicknameRate: true,
+ *       saveRate: true,
+ *     },
+ *     shipmentForm: {
+ *       browseRates: true,
+ *       includeShipsuranceInsurance: true,
+ *       includeThirdPartyInsurance: true,
+ *       selectService: true,
+ *       shippingPresets: false,
+ *     },
+ *   },
+ *   Global: {
+ *     carriers: {
+ *       enabledCarriers: ["stamps_com", "ups", "dhl_express_walleted"],
+ *     },
+ *     presentation: {
+ *       poweredByShipEngine: false,
+ *     },
+ *   },
+ *   ViewShipment: {
+ *     shipment: {
+ *       schedulePickup: true,
+ *     },
+ *   },
+ * } as const;
+ * ```
+ */
+export declare const featureFlags: {
+    /**
+     * `ConfigureSalesOrderShipment` all scoped feature flags for the shipment configuration
+     * section of the `<PurchaseLabel />` element.
+     */
+    readonly ConfigureSalesOrderShipment: {
+        /**
+         * `compatibleCountryCodes` is a list of all supported `countries` available in ShipEngine
+         * Elements.
+         */
+        readonly compatibleCountryCodes: readonly ["AU", "CA", "FR", "DE", "GB", "IL", "IT", "NO", "ES", "SE", "US"];
+        /**
+         *  `rateForm` all scoped feature flags for the `rate form` section of the `<PurchaseLabel />`
+         *  element.
+         */
+        readonly rateForm: {
+            /**
+             * `enableFunding` enables the `funding` section of the rate form.
+             */
+            readonly enableFunding: false;
+            /**
+             * `enableGlobalPostFiltering` enables the `global post filtering` on all rates fetched
+             * in the rates form.
+             */
+            readonly enableGlobalPostFiltering: false;
+            /**
+             * `labelLayout` enables the `label layout` section of the `<PurchaseLabel /> element.
+             */
+            readonly labelLayout: false;
+            /**
+             * `nicknameRate` enables showing the `carrier nickname` when rates are fetched.
+             */
+            readonly nicknameRate: true;
+            readonly requireDhlTermsAcknowledgement: false;
+            /**
+             * `saveRate` enables the `save rate` button in the rate form. This allows users to save a
+             * `rateId` for a shipment to be purchased later.
+             */
+            readonly saveRate: true;
+        };
+        /**
+         * `shipmentForm` all scoped feature flags for the `shipment form` section of the
+         * `<PurchaseLabel />` element.
+         */
+        readonly shipmentForm: {
+            /**
+             * `browseRates` enables the `browse rates` button in the shipment form. This allows users
+             * to browse rates for a shipment with varying shipment configurations. This is useful for
+             * rate shopping.
+             */
+            readonly browseRates: true;
+            /**
+             * `includeShipsuranceInsurance` enables the `shipsurance insurance` feature, allowing users
+             * to select Shipsurance when insuring their shipment.
+             */
+            readonly includeShipsuranceInsurance: true;
+            /**
+             * `includeThirdPartyInsurance` enables the `third party insurance` feature, allowing users
+             * to opt for third party insurance when insuring their shipment.
+             */
+            readonly includeThirdPartyInsurance: true;
+            /**
+             * `selectService` enables the `select service` feature, allowing users to select a service
+             * when rate shopping across multiple carrier providers.
+             */
+            readonly selectService: true;
+            /**
+             * `shippingPresets` enables the `shipping presets` feature, allowing users to pass in a set
+             * of shipping presets they wish to use within the shipment form of the `<PurchaseLabel />`
+             * element.
+             */
+            readonly shippingPresets: false;
+        };
+    };
+    /**
+     * `Global` all feature flags that are intended for use anywhere in ShipEngine Elements.
+     */
+    readonly Global: {
+        /**
+         * All global `carrier` related feature flags.
+         */
+        readonly carriers: {
+            /**
+             * `enabledCarriers` is a list of all `carriers` that are enabled for use in ShipEngine
+             * Elements.
+             */
+            readonly enabledCarriers: readonly ["stamps_com", "ups", "dhl_express_walleted"];
+        };
+        /**
+         * All global `presentation` related feature flags.
+         */
+        readonly presentation: {
+            /**
+             * `poweredByShipEngine` enables the `powered by ShipEngine` logo in the footer various
+             * elements.
+             */
+            readonly poweredByShipEngine: false;
+        };
+    };
+    /**
+     * `ViewShipment` all scoped feature flags for the `<ViewShipment />` element.
+     */
+    readonly ViewShipment: {
+        /**
+         * `shipment` all shipment related features available in the `<ViewShipment />` element.
+         */
+        readonly shipment: {
+            /**
+             * `schedulePickup` enables the `schedule pickup` button in the `<ViewShipment />` element,
+             * allowing users to schedule pick-ups for their shipments.
+             */
+            readonly schedulePickup: true;
+        };
+    };
+};
+/**
+ * @internal
+ *
+ * # Feature Flags - featureFlagComponentNameLookup
+ */
 export declare const featureFlagComponentNameLookup: (componentName: string) => string;
+/**
+ * @internal
+ *
+ * # Feature Flags - getFeatures
+ */
 export declare const getFeatures: (...element: string[]) => any;
+/**
+ * # Feature Flags - useFeatures
+ *
+ * - The `useFeatures` hook is used to retrieve the feature flags for a given component.
+ *
+ * @example
+ * ```tsx
+ * const features = useFeatures("Global");
+ * ```
+ *
+ * <br />
+ *
+ * @see {@link featureFlags | All available `Feature Flags`}
+ */
 export declare const useFeatures: (...element: string[]) => any;

package/src/utilities/form-logger.d.ts

@@ -1,5 +1,9 @@
 import { FieldValues, ResolverResult, UseFormHandleSubmit } from "react-hook-form";
 /**
+ * @internal
+ *
+ * # Form Logger
+ *
  * @description
  * This will log the values that are submitted to the validation resolver
  * (only REGISTERED form fields) and the results of that validation.

package/src/utilities/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./create-dictionary";
 export * from "./date";
 export * from "./error";
+export * from "./feature-flags";
 export * from "./form-logger";
 export * from "./money";
 export * from "./predicates";
@@ -9,4 +10,3 @@ export * from "./shipengine";
 export * from "./string";
 export * from "./styles";
 export * from "./validation";
-export * from "./feature-flags";

package/src/utilities/money.d.ts

@@ -1,6 +1,31 @@
 import { SE } from "@shipengine/alchemy";
+/**
+ * @internal
+ *
+ * # Money Utils - currency Symbol
+ */
 export declare const currencySymbol: Record<SE.Currency, string>;
+/**
+ * @internal
+ *
+ * # Money Utils - formatMoney
+ */
 export declare const formatMoney: (value: SE.Money, locale?: string) => string;
+/**
+ * @internal
+ *
+ * # Money Utils - calculateTotal
+ */
 export declare const calculateTotal: (...values: SE.Money[]) => number;
+/**
+ * @internal
+ *
+ * # Money Utils - formatCreditCardNumber
+ */
 export declare const formatCreditCardNumber: (cc: string) => string;
+/**
+ * @internal
+ *
+ * # Money Utils - formatExpiration
+ */
 export declare const formatExpiration: (exp: string) => string;

package/src/utilities/predicates/isString.d.ts

@@ -1 +1,8 @@
+/**
+ * @internal
+ *
+ * # String Predicate Utilities
+ *
+ * @category Utilities
+ */
 export declare const isString: (x: unknown) => x is string;

package/src/utilities/rates.d.ts

@@ -1,5 +1,19 @@
 import { SE } from "@shipengine/alchemy";
-export declare const getRateRequiresAcknowledgement: (serviceCode: string, packageType: string) => boolean;
+/**
+ * @internal
+ *
+ * # Rates Utilities - getRateRequiresAcknowledgement
+ *
+ * @category Utilities
+ */
+export declare const getRateRequiresAcknowledgement: (serviceCode: string, packageType: string, requireDhlTermsAcknowledgement: boolean) => boolean;
+/**
+ * @internal
+ *
+ * # Rates Utilities - getTotalRateAmount
+ *
+ * @category Utilities
+ */
 export declare const getTotalRateAmount: (rateCosts?: {
     confirmationAmount?: SE.Money;
     insuranceAmount?: SE.Money;
@@ -7,4 +21,11 @@ export declare const getTotalRateAmount: (rateCosts?: {
     shippingAmount?: SE.Money;
     taxAmount?: SE.Money;
 }) => number;
+/**
+ * @internal
+ *
+ * # Rates Utilities - overrideCarrierCodes
+ *
+ * @category Utilities
+ */
 export declare const overrideCarrierCodes: (carrier: string, overrides: object) => never;