@shipengine/elements 2.26.4 → 2.27.0

package/dist/cjs/elements/customs-form/customs-form-element.cjs

@@ -0,0 +1,294 @@
+'use strict';
+
+var jsxRuntime = require('@emotion/react/jsx-runtime');
+var useShipmentMetadata = require('../../hooks/options/use-shipment-metadata.cjs');
+var giger = require('@shipengine/giger');
+var validation = require('../../utilities/validation.cjs');
+var React = require('react');
+var reactHookForm = require('react-hook-form');
+var reactI18next = require('react-i18next');
+var customsForms = require('../purchase-label/components/customs-forms/customs-forms.cjs');
+var shipmentSchema = require('../purchase-label/components/shipment-form/shipment-schema.cjs');
+var customsFormTypes = require('./customs-form-types.cjs');
+var useWindsorFramework = require('../purchase-label/hooks/use-windsor-framework.cjs');
+var index = require('../../locales/en/index.cjs');
+var createElement = require('../../create-element/create-element.cjs');
+var buttonGroup = require('../../components/button-group/button-group.cjs');
+var errorFallback = require('../../components/error-fallback/error-fallback.cjs');
+
+/**
+ * # Customs Form Element Component
+ *
+ * - The `<CustomsForm />` component is a standalone element that wraps the `CustomsForms`
+ * component with its own form management. This allows you to use customs forms independently
+ * outside of the full `PurchaseLabel` workflow while managing its own internal form state.
+ *
+ * @param CustomsFormProps The props necessary to render the `<CustomsForm />` component.
+ *
+ * @returns Element An EmotionJSX.Element that will render the `<CustomsForm />` 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 = createElement(Component, ErrorFallback, {
+ *   css: { width: "100%" },
+ *   resources: { en },
+ * });
+ * ```
+ *
+ * <br />
+ *
+ * @see {@link CustomsForm.Element | The **Element** created to render `<CustomsForm />`}
+ */
+const Component = ({
+  shipment,
+  betaEnableWindsorFramework = false,
+  currency,
+  harmonizedTariffCodes,
+  onModify,
+  onSubmit,
+  onCancel,
+  className,
+  "data-testid": dataTestId
+}) => {
+  var _a, _b, _c, _d, _e, _f;
+  const {
+    t
+  } = reactI18next.useTranslation();
+  // Track additional state for tax identifiers and products that aren't directly in the form
+  const [taxIdentifiers, setTaxIdentifiers] = React.useState(shipment.taxIdentifiers || []);
+  // We onliy support a single package within Elements, so track products for only first package
+  const [products, setProducts] = React.useState(((_b = (_a = shipment.packages) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.products) || []);
+  // Get shipment metadata to determine form requirements
+  const {
+    isCustomsRequired,
+    isCanadaDeliveredDutyEligible,
+    isContentDescriptionRequired,
+    hasAllZeroMeasurements
+  } = useShipmentMetadata.useShipmentMetadata(shipment);
+  const {
+    requiresWindsorFramework
+  } = useWindsorFramework.useWindsorFramework(shipment, betaEnableWindsorFramework);
+  // Get the shipment schema for form validation
+  const shipmentSchema$1 = React.useMemo(() => {
+    var _a, _b, _c, _d, _e, _f;
+    return shipmentSchema.getShipmentSchema({
+      isCustomsRequired,
+      requiresWindsorFramework,
+      isContentDescriptionRequired,
+      requireMeasurements: !hasAllZeroMeasurements,
+      dimensionsUnit: (_c = (_b = (_a = shipment.packages) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.dimensions) === null || _c === void 0 ? void 0 : _c.unit,
+      weightUnit: (_f = (_e = (_d = shipment.packages) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.weight) === null || _f === void 0 ? void 0 : _f.unit
+    });
+  }, [isCustomsRequired, requiresWindsorFramework, isContentDescriptionRequired, hasAllZeroMeasurements, shipment.packages]);
+  // Create form with shipment data
+  const form = reactHookForm.useForm({
+    defaultValues: {
+      __mode: "browse_rates",
+      customs: shipment.customs ? {
+        contents: shipment.customs.contents,
+        nonDelivery: shipment.customs.nonDelivery
+      } : undefined,
+      packages: ((_c = shipment.packages) === null || _c === void 0 ? void 0 : _c.map(pkg => ({
+        type: {
+          code: pkg.packageCode || "package",
+          carrierId: null,
+          packageId: pkg.packageId
+        },
+        products: pkg.products || [],
+        dimensions: pkg.dimensions ? {
+          length: pkg.dimensions.length,
+          width: pkg.dimensions.width,
+          height: pkg.dimensions.height
+        } : null,
+        weight: pkg.weight ? {
+          whole: Math.floor(pkg.weight.value),
+          fractional: Math.round(pkg.weight.value % 1 * 16) // Convert decimal to oz
+        } : null,
+        contentDescription: pkg.contentDescription,
+        insuredValue: pkg.insuredValue
+      }))) || [{
+        type: {
+          code: "package",
+          carrierId: null,
+          packageId: null
+        },
+        products: [],
+        dimensions: null,
+        weight: null,
+        contentDescription: null,
+        insuredValue: null
+      }],
+      advancedOptions: {
+        additionalHandling: (_d = shipment.advancedOptions) === null || _d === void 0 ? void 0 : _d.additionalHandling,
+        canadaDeliveredDuty: (_e = shipment.advancedOptions) === null || _e === void 0 ? void 0 : _e.canadaDeliveredDuty,
+        windsorFrameworkDetails: (_f = shipment.advancedOptions) === null || _f === void 0 ? void 0 : _f.windsorFrameworkDetails
+      },
+      shipDate: new Date().toLocaleDateString(),
+      shipmentId: shipment.shipmentId
+    },
+    resolver: validation.validationResolver(shipmentSchema$1),
+    mode: "onChange"
+  });
+  // Watch for form changes and call onModify
+  const watchedValues = form.watch();
+  // Create updated shipment data with current form values and tracked state
+  const getUpdatedShipment = React.useCallback(() => {
+    var _a;
+    return Object.assign(Object.assign({}, shipment), {
+      customs: watchedValues.customs,
+      taxIdentifiers,
+      packages: ((_a = watchedValues.packages) === null || _a === void 0 ? void 0 : _a.map((pkg, index) => {
+        var _a, _b, _c;
+        return Object.assign(Object.assign(Object.assign({}, (_a = shipment.packages) === null || _a === void 0 ? void 0 : _a[index]), pkg), {
+          products: index === 0 ? products : pkg.products || ((_c = (_b = shipment.packages) === null || _b === void 0 ? void 0 : _b[index]) === null || _c === void 0 ? void 0 : _c.products) || []
+        });
+      })) || [],
+      advancedOptions: Object.assign(Object.assign({}, shipment.advancedOptions), watchedValues.advancedOptions)
+    });
+  }, [shipment, watchedValues, taxIdentifiers, products]);
+  React.useEffect(() => {
+    if (onModify && form.formState.isDirty) {
+      // Extract customs data from the updated shipment
+      const updatedShipment = getUpdatedShipment();
+      const customsData = customsFormTypes.extractCustomsFormData(updatedShipment);
+      onModify(customsData);
+    }
+  }, [watchedValues, onModify, form.formState.isDirty, shipment, getUpdatedShipment]);
+  // Update tracked state when shipment changes
+  React.useEffect(() => {
+    var _a, _b;
+    setTaxIdentifiers(shipment.taxIdentifiers || []);
+    setProducts(((_b = (_a = shipment.packages) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.products) || []);
+  }, [shipment]);
+  // Handle form submission
+  const handleSubmit = React.useCallback(e => {
+    e.preventDefault();
+    if (onSubmit) {
+      const updatedShipment = getUpdatedShipment();
+      const customsData = customsFormTypes.extractCustomsFormData(updatedShipment);
+      void onSubmit(customsData);
+    }
+  }, [onSubmit, getUpdatedShipment]);
+  // Handle dirty state changes
+  const handleDirty = React.useCallback(() => {
+    // This is called by CustomsForms when the form becomes dirty
+  }, []);
+  // Handle customs updates - this updates the form and triggers onModify
+  const handleUpdateCustoms = React.useCallback((_customs, products) => {
+    setProducts(products);
+    const updatedShipment = getUpdatedShipment();
+    // Trigger onModify with the updated data
+    if (onModify) {
+      const customsData = customsFormTypes.extractCustomsFormData(updatedShipment);
+      onModify(customsData);
+    }
+    return Promise.resolve(updatedShipment);
+  }, [getUpdatedShipment, onModify]);
+  // Handle tax identifier updates - this updates our tracked state and triggers onModify
+  const handleUpdateTaxableIds = React.useCallback(updatedTaxIds => {
+    setTaxIdentifiers(updatedTaxIds);
+    const updatedShipment = Object.assign(Object.assign({}, getUpdatedShipment()), {
+      taxIdentifiers: updatedTaxIds
+    });
+    // Trigger onModify with the updated data
+    if (onModify) {
+      const customsData = customsFormTypes.extractCustomsFormData(updatedShipment);
+      onModify(customsData);
+    }
+    return Promise.resolve(updatedShipment);
+  }, [getUpdatedShipment, onModify]);
+  // Create enhanced shipment with current tracked state for CustomsForms
+  const enhancedShipment = React.useMemo(() => {
+    var _a;
+    return Object.assign(Object.assign({}, shipment), {
+      taxIdentifiers,
+      packages: ((_a = shipment.packages) === null || _a === void 0 ? void 0 : _a.map((pkg, index) => Object.assign(Object.assign({}, pkg), {
+        products: index === 0 ? products : pkg.products || []
+      }))) || []
+    });
+  }, [shipment, taxIdentifiers, products]);
+  return jsxRuntime.jsx("div", {
+    className: className,
+    "data-testid": dataTestId,
+    children: jsxRuntime.jsxs("form", {
+      onSubmit: handleSubmit,
+      children: [jsxRuntime.jsx(customsForms.CustomsForms, {
+        currency: currency,
+        form: form,
+        harmonizedTariffCodes: harmonizedTariffCodes,
+        isCanadaDeliveredDutyEligible: isCanadaDeliveredDutyEligible,
+        onDirty: handleDirty,
+        onUpdateCustoms: handleUpdateCustoms,
+        onUpdateTaxableIds: handleUpdateTaxableIds,
+        requiresWindsorFramework: requiresWindsorFramework,
+        shipment: enhancedShipment
+      }), (onSubmit || onCancel) && jsxRuntime.jsxs(buttonGroup.ButtonGroup, {
+        justify: "end",
+        children: [onCancel && jsxRuntime.jsx(giger.Button, {
+          bold: false,
+          onClick: onCancel,
+          type: "button",
+          variant: giger.ButtonVariant.OUTLINED,
+          children: t("actions.cancel")
+        }), onSubmit && jsxRuntime.jsx(giger.Button, {
+          bold: false,
+          disabled: !form.formState.isValid || form.formState.isSubmitting,
+          type: "submit",
+          variant: giger.ButtonVariant.FILLED,
+          children: form.formState.isSubmitting ? t("actions.submitting") : t("actions.submit")
+        })]
+      })]
+    })
+  });
+};
+Component.displayName = "CustomsForm";
+/**
+ * # Registered Customs Form Element
+ *
+ * - This is the registered `<CustomsForm />` element that will be used to render the
+ * `<CustomsForm.Element />` component.
+ *
+ * @param ElementProps The props, callbacks, and resources necessary to render
+ * the `<CustomsForm.Element />` component.
+ *
+ * @example
+ * The `<Component />` is the source JSX that is rendered when you make use of the `CustomsForm`
+ * Element directly. Here is a brief example of how you would use it within your application.
+ * ```tsx
+ * <CustomsForm.Element
+ *   shipment={salesOrderShipment}
+ *   currency={SE.Currency.USD}
+ *   harmonizedTariffCodes={htsCodes}
+ *   betaEnableWindsorFramework={true}
+ *   onModify={(customsData) => {
+ *     console.log('Customs form modified:', customsData);
+ *   }}
+ *   onSubmit={async (customsData) => {
+ *     console.log('Customs form submitted:', customsData);
+ *     await updateShipmentCustoms(customsData);
+ *   }}
+ *   onCancel={() => {
+ *     console.log('Form cancelled');
+ *   }}
+ * />
+ * ```
+ *
+ * <br />
+ *
+ * @see {@link CustomsForm.ComponentProps | The **props** that can be passed into the `<CustomsForm.Element />` component}
+ *
+ * @see {@link PurchaseLabel.Element | See how this element is used within the full label purchase workflow `<PurchaseLabel.Element />`}
+ */
+const Element = createElement.createElement(Component, errorFallback.ErrorFallback, {
+  css: {
+    width: "100%"
+  },
+  resources: {
+    en: index
+  }
+});
+
+exports.Component = Component;
+exports.Element = Element;

package/dist/cjs/elements/customs-form/customs-form-element.stories.cjs

@@ -0,0 +1,243 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _tslib = require('../../_virtual/_tslib.cjs');
+var jsxRuntime = require('@emotion/react/jsx-runtime');
+var addonActions = require('@storybook/addon-actions');
+var reactApi = require('@shipengine/react-api');
+var customsFormElement = require('./customs-form-element.cjs');
+var shipment = require('../../factories/shipengine/shipment.cjs');
+
+var customsFormElement_stories = {
+  title: "Label Workflow/Nested Elements/CustomsForm Element",
+  component: customsFormElement.Element,
+  parameters: {
+    controls: {
+      expanded: false
+    },
+    previewTabs: {
+      "storybook/docs/panel": {
+        hidden: true
+      }
+    },
+    viewMode: "story",
+    docs: {
+      description: {
+        component: "A higher-order component that wraps CustomsForms with its own react-hook-form context, allowing it to be used outside of existing form contexts."
+      }
+    }
+  },
+  argTypes: {
+    shipment: {
+      control: false,
+      description: "The shipment data to populate the form with"
+    },
+    currency: {
+      control: {
+        type: "select"
+      },
+      options: Object.values(reactApi.SE.Currency),
+      description: "Currency for monetary values"
+    },
+    betaEnableWindsorFramework: {
+      control: {
+        type: "boolean"
+      },
+      description: "Enable Windsor Framework features"
+    },
+    onModify: {
+      action: "onModify",
+      description: "Called when form data changes"
+    },
+    onSubmit: {
+      action: "onSubmit",
+      description: "Called when form is submitted"
+    },
+    onCancel: {
+      action: "onCancel",
+      description: "Called when cancel button is clicked"
+    }
+  }
+};
+const Template = args => {
+  return jsxRuntime.jsx("div", {
+    style: {
+      maxWidth: "800px",
+      padding: "20px"
+    },
+    children: jsxRuntime.jsx(customsFormElement.Element, Object.assign({}, args))
+  });
+};
+// Create mock shipment data for different scenarios
+const createMockShipment = (isInternational = true, hasCustoms = true) => {
+  return shipment.salesOrderShipmentFactory.build({}, {
+    transient: {
+      isInternational
+    },
+    associations: {
+      customs: hasCustoms ? {
+        contents: reactApi.SE.CustomsContentsType.MERCHANDISE,
+        nonDelivery: reactApi.SE.CustomsNonDeliveryType.RETURN_TO_SENDER
+      } : undefined
+    }
+  });
+};
+const Default = Template.bind({});
+Default.args = {
+  shipment: createMockShipment(true, true),
+  currency: reactApi.SE.Currency.USD,
+  onModify: addonActions.action("onModify"),
+  onSubmit: addonActions.action("onSubmit"),
+  onCancel: addonActions.action("onCancel")
+};
+Default.storyName = "Default International Shipment";
+const DomesticShipment = Template.bind({});
+DomesticShipment.args = {
+  shipment: createMockShipment(false, false),
+  currency: reactApi.SE.Currency.USD,
+  onModify: addonActions.action("onModify"),
+  onSubmit: addonActions.action("onSubmit")
+};
+DomesticShipment.storyName = "Domestic Shipment (No Customs)";
+const CanadaDeliveredDuty = Template.bind({});
+CanadaDeliveredDuty.args = {
+  shipment: shipment.salesOrderShipmentFactory.build({}, {
+    transient: {
+      isInternational: true
+    },
+    associations: {
+      shipTo: {
+        countryCode: "CA",
+        name: "John Doe",
+        phone: "555-123-4567",
+        addressLine1: "123 Main St",
+        cityLocality: "Toronto",
+        stateProvince: "ON",
+        postalCode: "M5V 3A8"
+      },
+      shipFrom: {
+        countryCode: "US",
+        name: "Warehouse",
+        phone: "555-987-6543",
+        addressLine1: "456 Warehouse Ave",
+        cityLocality: "Los Angeles",
+        stateProvince: "CA",
+        postalCode: "90210"
+      },
+      customs: {
+        contents: reactApi.SE.CustomsContentsType.GIFT,
+        nonDelivery: reactApi.SE.CustomsNonDeliveryType.RETURN_TO_SENDER
+      }
+    }
+  }),
+  currency: reactApi.SE.Currency.USD,
+  onModify: addonActions.action("onModify"),
+  onSubmit: addonActions.action("onSubmit")
+};
+CanadaDeliveredDuty.storyName = "Canada Delivered Duty Eligible";
+const WithWindsorFramework = Template.bind({});
+WithWindsorFramework.args = {
+  shipment: shipment.salesOrderShipmentFactory.build({}, {
+    transient: {
+      isInternational: true
+    },
+    associations: {
+      shipTo: {
+        countryCode: "IE",
+        // Ireland - EU country for Windsor Framework
+        name: "Jane Smith",
+        phone: "353-1-234-5678",
+        addressLine1: "789 Dublin St",
+        cityLocality: "Dublin",
+        stateProvince: "Dublin",
+        postalCode: "D01 F5P2"
+      },
+      shipFrom: {
+        countryCode: "GB",
+        // UK for Windsor Framework
+        name: "UK Warehouse",
+        phone: "44-20-7946-0958",
+        addressLine1: "123 London Rd",
+        cityLocality: "London",
+        stateProvince: "England",
+        postalCode: "SW1A 1AA"
+      },
+      customs: {
+        contents: reactApi.SE.CustomsContentsType.MERCHANDISE,
+        nonDelivery: reactApi.SE.CustomsNonDeliveryType.RETURN_TO_SENDER
+      }
+    }
+  }),
+  currency: reactApi.SE.Currency.GBP,
+  betaEnableWindsorFramework: true,
+  onModify: addonActions.action("onModify"),
+  onSubmit: addonActions.action("onSubmit")
+};
+WithWindsorFramework.storyName = "With Windsor Framework";
+const WithExistingProducts = Template.bind({});
+WithExistingProducts.args = {
+  shipment: shipment.salesOrderShipmentFactory.build({}, {
+    transient: {
+      isInternational: true
+    },
+    associations: {
+      customs: {
+        contents: reactApi.SE.CustomsContentsType.MERCHANDISE,
+        nonDelivery: reactApi.SE.CustomsNonDeliveryType.RETURN_TO_SENDER
+      }
+    }
+  }),
+  currency: reactApi.SE.Currency.USD,
+  harmonizedTariffCodes: [{
+    code: "6109.10.00",
+    description: "T-shirts, singlets and other vests, knitted or crocheted, of cotton"
+  }, {
+    code: "6912.00.48",
+    description: "Ceramic tableware, kitchenware, other household articles"
+  }],
+  onModify: addonActions.action("onModify"),
+  onSubmit: addonActions.action("onSubmit")
+};
+WithExistingProducts.storyName = "With Existing Products";
+const InteractiveExample = Template.bind({});
+InteractiveExample.args = {
+  shipment: createMockShipment(true, true),
+  currency: reactApi.SE.Currency.USD,
+  onModify: data => {
+    addonActions.action("onModify")(data);
+    console.log("Form modified:", data);
+  },
+  onSubmit: data => _tslib.__awaiter(void 0, void 0, void 0, function* () {
+    addonActions.action("onSubmit")(data);
+    console.log("Form submitted:", data);
+    // Simulate async operation
+    yield new Promise(resolve => setTimeout(resolve, 1000));
+    alert("Form submitted successfully! Check the console for data.");
+  }),
+  onCancel: () => {
+    addonActions.action("onCancel")();
+    console.log("Form cancelled");
+    alert("Form cancelled!");
+  }
+};
+InteractiveExample.storyName = "Interactive Example";
+const WithoutButtons = Template.bind({});
+WithoutButtons.args = {
+  shipment: createMockShipment(true, true),
+  currency: reactApi.SE.Currency.USD,
+  onModify: addonActions.action("onModify"),
+  // Explicitly set to undefined to override default actions and hide buttons
+  onSubmit: undefined,
+  onCancel: undefined
+};
+WithoutButtons.storyName = "Without Buttons (Form Only)";
+
+exports.CanadaDeliveredDuty = CanadaDeliveredDuty;
+exports.Default = Default;
+exports.DomesticShipment = DomesticShipment;
+exports.InteractiveExample = InteractiveExample;
+exports.WithExistingProducts = WithExistingProducts;
+exports.WithWindsorFramework = WithWindsorFramework;
+exports.WithoutButtons = WithoutButtons;
+exports.default = customsFormElement_stories;

package/dist/cjs/elements/customs-form/customs-form-schema.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+var reactApi = require('@shipengine/react-api');
+var zod$1 = require('zod');
+var zod = require('../../extensions/zod.cjs');
+var canadaDdp = require('../../types/canada-ddp.cjs');
+var money = require('../../schemas/shipengine/money.cjs');
+
+zod.extendZod();
+/**
+ * Creates a Zod schema for customs form data
+ */
+const getCustomsFormSchema = ({
+  isCustomsRequired = true,
+  requiresWindsorFramework = false
+} = {}) => {
+  const customsSchema = zod$1.z.object({
+    customs: zod$1.z.object({
+      contents: zod$1.z.nativeEnum(reactApi.SE.CustomsContentsType),
+      nonDelivery: zod$1.z.nativeEnum(reactApi.SE.CustomsNonDeliveryType)
+    }),
+    products: isCustomsRequired ? zod$1.z.array(zod$1.z.object({
+      countryOfOrigin: zod$1.z.string().nullishDefault(undefined),
+      description: zod$1.z.string().nullishDefault(undefined),
+      harmonizedTariffCode: zod$1.z.string().nullishDefault(undefined),
+      quantity: zod$1.z.number().int().positive(),
+      value: money.moneySchema
+    })).min(1, "At least one product is required") : zod$1.z.array(zod$1.z.object({
+      countryOfOrigin: zod$1.z.string().nullishDefault(undefined),
+      description: zod$1.z.string().nullishDefault(undefined),
+      harmonizedTariffCode: zod$1.z.string().nullishDefault(undefined),
+      quantity: zod$1.z.number().int().positive(),
+      value: money.moneySchema
+    })).optional(),
+    taxIdentifiers: zod$1.z.array(zod$1.z.any()).optional(),
+    // SE.TaxIdentifier type is complex, using any for now
+    advancedOptions: zod$1.z.object({
+      canadaDeliveredDuty: zod$1.z.nativeEnum(canadaDdp.CanadaDeliveredDutyOptions).nullish(),
+      windsorFrameworkDetails: requiresWindsorFramework ? zod$1.z.object({
+        movementIndicator: zod$1.z.nativeEnum(reactApi.SE.MovementIndicator),
+        notAtRisk: zod$1.z.boolean().optional().default(false)
+      }) : zod$1.z.object({
+        movementIndicator: zod$1.z.nativeEnum(reactApi.SE.MovementIndicator),
+        notAtRisk: zod$1.z.boolean().optional().default(false)
+      }).optional()
+    }).optional()
+  });
+  return customsSchema;
+};
+/**
+ * Default schema for customs forms
+ */
+const defaultCustomsFormSchema = getCustomsFormSchema({
+  isCustomsRequired: true,
+  requiresWindsorFramework: false
+});
+
+exports.defaultCustomsFormSchema = defaultCustomsFormSchema;
+exports.getCustomsFormSchema = getCustomsFormSchema;

package/dist/cjs/elements/customs-form/customs-form-types.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+var reactApi = require('@shipengine/react-api');
+var canadaDdp = require('../../types/canada-ddp.cjs');
+
+/**
+ * Extracts customs form data from a `SalesOrderShipment` object.
+ *
+ * - This utility function transforms a `SalesOrderShipment` (or `Shipment`) into the `CustomsFormData`
+ * structure used by the `CustomsForm`. It extracts products from the first package and gathers
+ * all relevant customs information into a flat structure.
+ *
+ * @param shipment - The `SalesOrderShipment` to extract customs data from
+ * @returns CustomsFormData object containing customs information
+ *
+ * @example
+ * ```tsx
+ * const customsData = extractCustomsFormData(shipment);
+ * ```
+ *
+ * @see {@link CustomsFormData | The structure of the returned data}
+ */
+const extractCustomsFormData = shipment => {
+  var _a, _b, _c, _d, _e, _f;
+  // Extract products from the first package (customs forms typically work with single package)
+  const products = ((_b = (_a = shipment.packages) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.products) || [];
+  return {
+    customs: {
+      contents: ((_c = shipment.customs) === null || _c === void 0 ? void 0 : _c.contents) || reactApi.SE.CustomsContentsType.MERCHANDISE,
+      nonDelivery: ((_d = shipment.customs) === null || _d === void 0 ? void 0 : _d.nonDelivery) || reactApi.SE.CustomsNonDeliveryType.RETURN_TO_SENDER
+    },
+    products,
+    taxIdentifiers: shipment.taxIdentifiers,
+    advancedOptions: {
+      canadaDeliveredDuty: (_e = shipment.advancedOptions) === null || _e === void 0 ? void 0 : _e.canadaDeliveredDuty,
+      windsorFrameworkDetails: (_f = shipment.advancedOptions) === null || _f === void 0 ? void 0 : _f.windsorFrameworkDetails
+    }
+  };
+};
+/**
+ * Returns default values for a new customs form.
+ *
+ * - Use this utility function when you need to initialize a customs form with sensible defaults
+ * before any shipment data is available. Sets MERCHANDISE as contents type and RETURN_TO_SENDER
+ * as the non-delivery option.
+ *
+ * @returns CustomsFormData object with default values
+ *
+ * @see {@link CustomsFormData | The structure of the returned data}
+ */
+const getDefaultCustomsFormValues = () => ({
+  customs: {
+    contents: reactApi.SE.CustomsContentsType.MERCHANDISE,
+    nonDelivery: reactApi.SE.CustomsNonDeliveryType.RETURN_TO_SENDER
+  },
+  products: [],
+  advancedOptions: {
+    canadaDeliveredDuty: canadaDdp.CanadaDeliveredDutyOptions.RECIPIENT_PAYS
+  }
+});
+
+exports.extractCustomsFormData = extractCustomsFormData;
+exports.getDefaultCustomsFormValues = getDefaultCustomsFormValues;

package/dist/cjs/elements/customs-form/index.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+var customsFormElement = require('./customs-form-element.cjs');
+var customsFormTypes = require('./customs-form-types.cjs');
+
+
+
+exports.CustomsForm = customsFormElement;
+exports.extractCustomsFormData = customsFormTypes.extractCustomsFormData;
+exports.getDefaultCustomsFormValues = customsFormTypes.getDefaultCustomsFormValues;

package/dist/cjs/elements/index.cjs

@@ -16,6 +16,8 @@ var selectLabelLayoutElement = require('./select-label-layout/select-label-layou
 var paymentMethodSettingsElement = require('./payment-method-settings/payment-method-settings-element.cjs');
 var carrierServices = require('../workflows/carrier-services/carrier-services.cjs');
 var transactionHistoryElement = require('./transaction-history/transaction-history-element.cjs');
+var customsFormElement = require('./customs-form/customs-form-element.cjs');
+var customsFormTypes = require('./customs-form/customs-form-types.cjs');
 
 
 
@@ -36,3 +38,6 @@ exports.SelectLabelLayout = selectLabelLayoutElement;
 exports.PaymentMethodSettings = paymentMethodSettingsElement;
 exports.CarrierServices = carrierServices;
 exports.TransactionHistory = transactionHistoryElement;
+exports.CustomsForm = customsFormElement;
+exports.extractCustomsFormData = customsFormTypes.extractCustomsFormData;
+exports.getDefaultCustomsFormValues = customsFormTypes.getDefaultCustomsFormValues;