@shipengine/elements 0.33.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipengine/elements",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "peerDependencies": {
     "@packlink/giger": "*",
     "react-i18next": "*",

package/src/components/add-funds-form/add-funds-form.d.ts

@@ -1,5 +1,12 @@
 /// <reference types="react" />
+import { SE } from "@shipengine/alchemy";
+/**
+ * @internal
+ *
+ * # Add Funds Form Provider
+ */
 export type AddFundsFormProvider = {
+    error?: SE.CodedError[] | null;
     isCustomAmount?: boolean;
     isSubmitted?: boolean;
     isSubmitting?: boolean;
@@ -7,6 +14,13 @@ export type AddFundsFormProvider = {
     selectedAmount?: number;
     submit?: () => void;
 };
+/**
+ * @internal
+ *
+ * # Add Funds Form Props
+ *
+ * @see {@link AddFundsForm | The `<AddFundsForm />` component using these props}
+ */
 export type AddFundsFormProps = {
     carrierId: string;
     children?: (addFundsForm: AddFundsFormProvider) => React.ReactElement;
@@ -15,8 +29,14 @@ export type AddFundsFormProps = {
     onSuccess?: () => void;
 };
 /**
- * Form for adding funds to a carrier's account.
+ * @internal
+ *
+ * # Add Funds Form Component
+ *
+ * - Form for adding funds to a carrier's account.
+ *
+ * If a `render child` is provided, external control is assumed and the cancel / submit buttons are hidden.
  *
- * If a render child is provided, external control is assumed and the cancel / submit buttons are hidden.
+ * @see {@link AddFundsFormProps | The props that are passed into the `<AddFundsForm />` component}
  */
 export declare const AddFundsForm: ({ carrierId, children, onCancel, onSuccess, minimumAmount, }: AddFundsFormProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/add-funds-form/add-funds-schema.d.ts

@@ -1,4 +1,15 @@
 import { z } from "zod";
+/**
+ * @internal
+ *
+ * # Add Funds Form Schema
+ *
+ * - A util function to create a dynamic form schema based on the mininum amount
+ * passed into the function.
+ *
+ * @param minimumAmount - The minimum amount that can be added to the account. This defaults to
+ * 10 if nothing is passed in.
+ */
 export declare const getAddFundsSchema: (minimumAmount?: number) => z.ZodEffects<z.ZodObject<{
     funds: z.ZodObject<z.extendShape<{
         amount: z.ZodNumber;
@@ -31,7 +42,22 @@ export declare const getAddFundsSchema: (minimumAmount?: number) => z.ZodEffects
         currency: import("@shipengine/js-api").Currency;
     };
 }>;
+/**
+ * @internal
+ *
+ * # Add Funds Form Schema
+ */
 type AddFundsFormSchema = ReturnType<typeof getAddFundsSchema>;
+/**
+ * @internal
+ *
+ * # Add Funds Form Schema
+ */
 export type AddFundsFormFields = z.input<AddFundsFormSchema>;
+/**
+ * @internal
+ *
+ * # Add Funds Form Schema
+ */
 export type AddFundsFormPayload = z.output<AddFundsFormSchema>;
 export {};

package/src/components/address-preference-context/address-preference-context.d.ts

@@ -30,9 +30,17 @@ export type AddressPreferenceProviderProps = {
         passengerData: InternalValidateAddressPayload["data"];
         returnAddress?: SE.Address | undefined;
     }) => Promise<void> | void;
+    userInput?: {
+        originAddress: SE.Address;
+        returnAddress?: SE.Address | undefined;
+    };
 };
 export type AddressPreferenceValue = {
     data: InternalValidateAddressPayload["data"];
+    userInput?: {
+        originAddress: SE.Address;
+        returnAddress?: SE.Address | undefined;
+    };
     validateAddress: (payload: InternalValidateAddressPayload) => Promise<void>;
     validationPreference?: ValidationPreference;
 };

package/src/components/auto-funding-form/auto-funding-form.d.ts

@@ -1,10 +1,32 @@
+/**
+ * @internal
+ *
+ * # Auto Funding Form Props
+ *
+ * - These are the base props that will be passed into the `<AutoFundingForm />` component.
+ *
+ * @see {@link AutoFundingForm | The `<AutoFundingForm />` component}
+ */
 export type AutoFundingFormProps = {
+    /**
+     * `carrierId` is the unique identifier for the carrier provider you wish to configure
+     * auto-funding rules for.
+     */
     carrierId: string;
 };
 /**
+ * @internal
+ *
+ * # Auto Funding Form Component
+ *
  * This form that allows users to enable or disable auto funding, and
  * configure auto funding rules in ShipEngine API.
  *
  * @param carrierId The carrierId of the carrier provider you wish to configure auto-funding rules for.
+ *
+ * @returns Element A React element that renders the Auto Funding Form allowing users to configure
+ * auto-funding rules for a given carrier provider.
+ *
+ * @see {@link AutoFundingFormProps | The props that are passed into the `<AutoFundingForm />` component}
  */
 export declare const AutoFundingForm: ({ carrierId }: AutoFundingFormProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/auto-funding-form/auto-funding-schema.d.ts

@@ -1,4 +1,11 @@
 import { z } from "zod";
+/**
+ * @internal
+ *
+ * # Auto Funding Form Schema
+ *
+ * @see {@link AutoFundingForm | Auto Funding Form component using this schema}
+ * */
 export declare const autoFundingSchema: z.ZodObject<{
     isEnabled: z.ZodBoolean;
     lowBalancePurchaseThreshold: z.ZodObject<z.extendShape<{
@@ -49,5 +56,15 @@ export declare const autoFundingSchema: z.ZodObject<{
         currency: import("@shipengine/js-api").Currency;
     };
 }>;
+/**
+ * @internal
+ *
+ * # Auto Funding Form Fields
+ */
 export type AutoFundingFormFields = z.input<typeof autoFundingSchema>;
+/**
+ * @internal
+ *
+ * # Auto Funding Form Payload
+ */
 export type AutoFundingFormPayload = z.output<typeof autoFundingSchema>;

package/src/components/button-group/button-group.d.ts

@@ -1,7 +1,36 @@
 import * as React from "react";
+/**
+ * @internal
+ *
+ * # Button Group Props
+ *
+ * - These are the base props that will be passed  into the `<ButtonGroup />` component.
+ *
+ * @see {@link ButtonGroup | This prop types usage in the `<ButtonGroup />` component}
+ */
 export type ButtonGroupProps = {
+    /**
+     * `children` is the list of buttons you wish to group together.
+     */
     children: React.ReactNode;
+    /**
+     * `justify` is the optional alignment of the buttons within the group.
+     */
     justify?: "start" | "center" | "end";
+    /**
+     * `toolbar` is an optional boolean that will be used to determine if the buttons should be
+     * arranged in an optional way to display in a toolbar.
+     */
     toolbar?: boolean;
 } & React.ComponentPropsWithoutRef<"div">;
+/**
+ * @internal
+ *
+ * # Button Group Component
+ *
+ * - The `<ButtonGroup />` is a composition component used to group buttons together that are
+ * passed in as children.
+ *
+ * @see {@link ButtonGroupProps | The props that are passed into the `<ButtonGroup />` component}
+ */
 export declare const ButtonGroup: ({ children, justify, toolbar, ...props }: ButtonGroupProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/carrier-balance/carrier-balance.d.ts

@@ -1,5 +1,28 @@
+/**
+ * @internal
+ *
+ * # Carrier Balance Props
+ *
+ * @see {@link CarrierBalance | The `<CarrierBalance />` component}
+ */
 export type CarrierBalanceProps = {
+    /**
+     * `balance` is the current balance for the carrier if there is one.
+     */
     balance?: number;
+    /**
+     * `carrierId` is the unique identifier for the carrier provider you wish to get the balance for.
+     */
     carrierId?: string;
 };
+/**
+ * @internal
+ *
+ * # Carrier Balance
+ *
+ * - The `<CarrierBalance />` component is used to display the current balance for a given
+ * carrier provider.
+ *
+ * @see {@link CarrierBalanceProps | The props for the `<CarrierBalance />` component}
+ */
 export declare const CarrierBalance: ({ balance, carrierId }: CarrierBalanceProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/collapsible-panel/collapsible-panel.d.ts

@@ -1,9 +1,41 @@
 import { WithChildrenCommonProps } from "@packlink/giger";
 import { SE } from "@shipengine/alchemy";
+/**
+ * @internal
+ *
+ * # Collapsible Panel Props
+ *
+ * @see {@link CollapsiblePanel | This prop types usage in the `<CollapsiblePanel />` component}
+ */
 export type CollapsiblePanelProps = WithChildrenCommonProps<{
+    /**
+     * `errors` is an optional array of ShipEngine errors that will be displayed in
+     * the `<SaveStatus />`.
+     */
     errors?: SE.CodedError[] | null;
+    /**
+     * `initialExpanded` is an optional boolean that will be used to determine if the panel
+     * should be expanded or collapsed by default.
+     */
     initialExpanded?: boolean;
+    /**
+     * `isSaving` is an optional boolean that will be used to determine if the panel
+     * should display a bust state while work is being done.
+     */
     isSaving?: boolean;
+    /**
+     * `title` is an optional string that will be used to display the title of the panel.
+     */
     title?: string;
 }>;
+/**
+ * @internal
+ *
+ * # Collapsible Panel Component
+ *
+ * - The `<CollapsiblePanel />` composition component is used to group content together that can
+ * be expanded or collapsed.
+ *
+ * @see {@link CollapsiblePanelProps | The props that are passed into the `<CollapsiblePanel />` component}
+ */
 export declare const CollapsiblePanel: ({ errors, initialExpanded, isSaving, children, title, }: CollapsiblePanelProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/copy/copy-button.d.ts

@@ -1,4 +1,8 @@
 /**
+ * @internal
+ *
+ * # Copy Button
+ *
  * A copy button that copies the content to the users' clipboard and displays a
  * checkmark on click.
  */

package/src/components/cube/cube.d.ts

@@ -1,5 +1,21 @@
 /// <reference types="react" />
+/**
+ * @internal
+ *
+ * # Cube Props
+ *
+ * @see {@link Cube | The `<Cube />` component}
+ */
 export type CubePropTypes = {
     animate?: boolean;
 } & React.ComponentPropsWithoutRef<"div">;
+/**
+ * @internal
+ *
+ * # Cube Component
+ *
+ * - This is a spinning cube that is used to display a loading state.
+ *
+ * @see {@link CubePropTypes | The props that are passed into the `<Cube />` component}
+ */
 export declare const Cube: ({ animate, ...props }: CubePropTypes) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/date-range-combo/date-range-combo.d.ts

@@ -1,5 +1,12 @@
 /// <reference types="react" />
 import { DateRange, DateRangeOption } from "../../hooks";
+/**
+ * @internal
+ *
+ * # Date Range Combo Props
+ *
+ * @see {@link DateRangeCombo | This prop types usage in the `<DateRangeCombo />` component}
+ */
 export type DateRangeComboProps = {
     children?: (renderedComponent: JSX.Element) => React.ReactNode;
     onChange: (nextOption: DateRangeOption | undefined, nextCustomRange: [Date, Date] | undefined) => Promise<void> | void;
@@ -9,4 +16,11 @@ export type DateRangeComboProps = {
         selectedOption?: DateRangeOption;
     };
 };
+/**
+ * @internal
+ *
+ * # Date Range Combo Component
+ *
+ * @see {@link DateRangeComboProps | This is the type of the props used in the `<DateRangeCombo />` component}
+ */
 export declare const DateRangeCombo: ({ children: renderChildren, onChange, options, values: { customRange, selectedOption }, }: DateRangeComboProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/date-range-select/date-range-select.d.ts

@@ -1,8 +1,14 @@
 import { DateRangeOption } from "../../hooks";
+/**
+ * @internal
+ */
 export type DateRangeSelectProps = {
     fullWidth?: boolean;
     onChange: (nextOption: DateRangeOption) => void | Promise<void>;
     options: DateRangeOption[];
     value?: DateRangeOption;
 };
+/**
+ * @internal
+ */
 export declare const DateRangeSelect: ({ fullWidth, onChange, options, value }: DateRangeSelectProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/error-fallback/error-fallback.d.ts

@@ -1,9 +1,20 @@
+/**
+ * @internal
+ *
+ * # Error Fallback Props
+ *
+ * @see {@link ErrorFallback | The `<ErrorFallback />` component}
+ */
 export interface ErrorFallbackProps {
     error: Error | string;
 }
 /**
+ * @internal
+ *
+ * # Error Fallback Component
+ *
  * Fallback component for the Elements ErrorBoundary
  *
- * @see {@link registerElement}
+ * @see {@link ErrorFallbackProps | The props that are passed into the `<ErrorFallback />` component}
  */
 export declare const ErrorFallback: ({ error }: ErrorFallbackProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/field-label/field-label.d.ts

@@ -1,4 +1,9 @@
 /// <reference types="react" />
+/**
+ * @internal
+ *
+ * # Field Label Props
+ */
 export type FieldLabelProps = {
     children: React.ReactNode;
     label?: string;
@@ -6,4 +11,9 @@ export type FieldLabelProps = {
     weight?: "bold" | "normal";
     withInput?: boolean;
 };
+/**
+ * @internal
+ *
+ * # Field Label Component
+ */
 export declare const FieldLabel: ({ children, label, subLabel, weight, withInput, }: FieldLabelProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/form-portal/form-portal.d.ts

@@ -1,6 +1,11 @@
 /// <reference types="react" />
 import { Interpolation, Theme } from "@emotion/react";
 declare const variants: readonly ["well"];
+/**
+ * @internal
+ *
+ * # Form Portal Props
+ */
 type FormPortalProps = {
     children: React.ReactNode;
     css?: Interpolation<Theme>;
@@ -9,6 +14,10 @@ type FormPortalProps = {
     variant?: typeof variants[number];
 };
 /**
+ * @internal
+ *
+ * # Form Portal Component
+ *
  * A drop-in replacement for the `<form>` tag that allows nested forms.
  *
  * Via portals, the <form> tag is mounted as a sibling of the app root. The form's

package/src/components/fund-and-purchase/fund-and-purchase.d.ts

@@ -1,4 +1,11 @@
 import { Control } from "react-hook-form";
+/**
+ * @internal
+ *
+ * # Fund And Purchase Props
+ *
+ * @see {@link FundAndPurchase | The `<FundAndPurchase />` component using these props}
+ */
 export type FundAndPurchaseProps = {
     balance?: number;
     carrierId?: string;
@@ -12,8 +19,14 @@ export type FundAndPurchaseProps = {
     purchaseAmount: number;
 };
 /**
+ * @internal
+ *
+ * # Fund And Purchase Component
+ *
  * Fund and Purchase handles the label purchase submission UX, ensuring that a user
  * has the necessary funds available and can add them if not. It allows a single button
  * to submit the funding form followed by the purchase form.
+ *
+ * @see {@link FundAndPurchaseProps | The props that are passed into the `<FundAndPurchase />` component}
  */
 export declare const FundAndPurchase: ({ balance: uspsBalance, carrierId, className, control, disabled, isFundingEnabled, isFundingRequired, onSave, purchaseAmount, onPurchase, }: FundAndPurchaseProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/inline-label/inline-label.d.ts

@@ -1,10 +1,20 @@
 /// <reference types="react" />
 import { WithConditionalCSSProp } from "@emotion/react/types/jsx-namespace";
 import { ITypographyProps } from "@packlink/giger";
+/**
+ * @internal
+ *
+ * # Inline Label Props
+ */
 export type InlineLabelProps = {
     children: React.ReactElement;
     isLabelRight?: boolean;
     label: string;
     labelProps?: WithConditionalCSSProp<ITypographyProps<"span">>;
 };
+/**
+ * @internal
+ *
+ * # Inline Label Component
+ */
 export declare const InlineLabel: ({ children, label, isLabelRight, labelProps, }: InlineLabelProps) => import("@emotion/react/types/jsx-namespace").EmotionJSX.Element;

package/src/components/items-breakdown/items-breakdown.d.ts

@@ -1,4 +1,9 @@
 import { SE } from "@shipengine/alchemy";
+/**
+ * @internal
+ *
+ * # Items Breakdown - Item Props
+ */
 export type Item = {
     detail: string;
     name: string;
@@ -8,7 +13,17 @@ export type Item = {
     totalValue?: SE.Money;
     value?: SE.Money;
 };
+/**
+ * @internal
+ *
+ * # Items Breakdown Props
+ */
 export type ItemsBreakdownProps = {
     items: Item[];
 };
+/**
+ * @internal
+ *
+ * # Items Breakdown Component
+ */
 export declare const ItemsBreakdown: ({ items }: ItemsBreakdownProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/label-layout/label-layout.d.ts

@@ -1,4 +1,9 @@
 export type LabelLayoutProps = {
     display: "settings" | "purchase";
 };
+/**
+ * @namespace LabelLayout
+ *
+ * # Label Layout Component
+ */
 export declare const LabelLayout: ({ display }: LabelLayoutProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/link-action/link-action.d.ts

@@ -7,10 +7,20 @@ declare const icons: {
     readonly download: IconNames.DOWNLOAD;
     readonly retry: IconNames.CIRCULAR_ARROW;
 };
+/**
+ * @internal
+ *
+ * # Link Action Props
+ */
 export type LinkActionProps = {
     icon?: keyof typeof icons;
     isBold?: boolean;
     title: string;
 } & ILinkProps;
+/**
+ * @internal
+ *
+ * # Link Action Component
+ */
 export declare const LinkAction: ({ css, icon, isDisabled, isLoading, title, isBold, ...props }: LinkActionProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export {};

package/src/components/loader/loader.d.ts

@@ -1,2 +1,7 @@
 import { ISpinnerProps } from "@packlink/giger";
+/**
+ * @internal
+ *
+ * # Loader Component
+ */
 export declare const Loader: (props: ISpinnerProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/manage-funding/manage-funding.d.ts

@@ -1,4 +1,30 @@
+/**
+  # Manage Funding Props
+ *
+ * - These are the base props that will be passed into the `<ManageFunding />` component.
+ *
+ * @see {@link ManageFunding | The `<ManageFunding />` component}
+ */
 export type ManageFundingProps = {
+    /**
+     * `carrierId` is the unique identifier for the carrier provider you wish to manage funding for.
+     */
     carrierId: string;
 };
+/**
+ * @namespace ManageFunding
+ *
+ * # Manage Funding Component
+ *
+ * - The `<ManageFunding />` component is used to manage funding rules and add funds to a carrier
+ * account, and is composed in the `<AccountSettings />` component.
+ *
+ * @param ManageFundingProps The base props that will be passed into the `<ManageFunding />` component.
+ *
+ * @returns Element A React element that renders the `<ManageFunding />` component allowing users
+ * manage funding rules and add funds to their carrier accounts.
+ *
+ * @see {@link ManageFundingProps | The props that are passed into the `<ManageFunding />` component}
+ * @see {@link AccountSettings.Element | The `<AccountSettings />` component renders the `<ManageFunding />` component}
+ */
 export declare const ManageFunding: ({ carrierId }: ManageFundingProps) => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/payment-method-settings/payment-method-settings.d.ts

@@ -1 +1,20 @@
+/**
+ * # Payment Method Settings Component
+ *
+ * - The `<PaymentMethodSettings />` component is used to manage the users payment information
+ * and is composed in the `<AccountSettings />` component. For example, users can update their
+ * billing information.
+ *
+ * @returns Elements A React element that renders the `<PaymentMethodSettings />` component
+ * allowing uses to configure their payment settings.
+ *
+ * @example
+ * ```tsx
+ * <PaymentMethodSettings />
+ * ```
+ *
+ * <br />
+ *
+ * @see {@link AccountSettings.Element | The `<AccountSettings />` component renders the `<PaymentMethodSettings />` component}
+ */
 export declare const PaymentMethodSettings: () => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/portal/portal.d.ts

@@ -1,10 +1,19 @@
 /// <reference types="react" />
+/**
+ * @internal
+ *
+ * # Portal Props
+ */
 export type PortalProps<T> = {
     children: React.ReactNode;
     target?: React.RefObject<T> | HTMLElement | null;
 };
 /**
- * A no-frills wrapper around React.createPortal for more elegant DOM composition
+ * @internal
+ *
+ * # Portal
+ *
+ * - A no-frills wrapper around React.createPortal for more elegant DOM composition
  *
  * @category Components
  *

package/src/components/powered-by-shipengine/powered-by-shipengine.d.ts

@@ -1 +1,9 @@
+/**
+ * @internal
+ *
+ * # Powered By ShipEngine Component
+ *
+ * - The `<PoweredByShipEngine />` composition component is used to render the
+ * "Powered By ShipEngine" logo throughout the various elements.
+ */
 export declare const PoweredByShipEngine: () => import("@emotion/react/jsx-runtime").JSX.Element;

package/src/components/section/section.d.ts

@@ -1,5 +1,10 @@
 /// <reference types="react" />
 import { WithChildrenCommonProps } from "@packlink/giger";
+/**
+ * @internal
+ *
+ * # Section Props
+ */
 export type SectionProps = WithChildrenCommonProps<{
     bold?: boolean;
     /** Element to render at the right part of the summary */
@@ -7,4 +12,9 @@ export type SectionProps = WithChildrenCommonProps<{
     /** Title to show */
     title?: string;
 }>;
+/**
+ * @internal
+ *
+ * # Section Component
+ */
 export declare const Section: ({ bold, title, children, rightContent, ...rest }: SectionProps) => import("@emotion/react/jsx-runtime").JSX.Element;