@myparcel-dev/pdk-admin 1.14.2 → 2.0.1

package/src/forms/shipmentOptions/createShipmentOptionsForm.ts

@@ -3,33 +3,23 @@
 
 import {toRaw} from 'vue';
 import {get} from 'lodash-unified';
-import {defineForm, type FormInstance} from '@myparcel-dev/vue-form-builder';
+import {defineForm, type FormInstance, type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
 import {type OneOrMore, toArray} from '@myparcel-dev/ts-utils';
-import {type Plugin} from '@myparcel-dev/pdk-common';
+import {AdminContextKey, type Plugin} from '@myparcel-dev/pdk-common';
 import {addBulkEditNotification} from '../helpers';
 import {createShipmentFormName} from '../../utils';
 import {useModalStore} from '../../stores';
 import {AdminModalKey} from '../../data';
-import {useAdminConfig} from '../../composables';
+import {useAdminConfig, useContext} from '../../composables';
+import {useCapabilitiesAutoClear} from './useCapabilitiesAutoClear';
+import {wireProxyCapabilities} from './wireProxyCapabilities';
 import {type ShipmentOptionsRefs} from './types';
-import {createHideSenderField} from './fields/createHideSenderField';
+import {createShipmentOptionField} from './fields/createShipmentOptionField';
 import {createDeliveryTypeField} from './fields/createDeliveryTypeField';
-import {
-  createAgeCheckField,
-  createCarrierField,
-  createDigitalStampRangeField,
-  createDirectReturnField,
-  createInsuranceField,
-  createPriorityDeliveryField,
-  createLabelAmountField,
-  createLargeFormatField,
-  createOnlyRecipientField,
-  createPackageTypeField,
-  createSameDayDeliveryField,
-  createSignatureField,
-  createReceiptCodeField,
-} from './fields';
-import {ALL_FIELDS, FIELD_CARRIER} from './field';
+import {createCarrierField} from './fields/createCarrierField';
+import {createDigitalStampRangeField, createLabelAmountField, createPackageTypeField} from './fields';
+import {fieldFactoryRegistry} from './fieldFactoryRegistry';
+import {FIELD_CARRIER, FIELD_DELIVERY_TYPE, FIELD_LABEL_AMOUNT, FIELD_MANUAL_WEIGHT, FIELD_PACKAGE_TYPE, FIELD_SHIPMENT_OPTIONS_PREFIX} from './field';
 
 export const createShipmentOptionsForm = (orders?: OneOrMore<Plugin.ModelPdkOrder>): FormInstance => {
   const ordersArray = toArray(orders ?? []).map(toRaw);
@@ -46,40 +36,112 @@ export const createShipmentOptionsForm = (orders?: OneOrMore<Plugin.ModelPdkOrde
 
   const order = ((isBulk ? undefined : ordersArray[0]) ?? {}) as Plugin.ModelContextOrderDataContext;
 
-  const refs = ALL_FIELDS.reduce((acc, fieldName) => {
-    acc[fieldName] = get(order, fieldName);
+  const dynamicContext = useContext(AdminContextKey.Dynamic);
+  const allOptionKeys = collectAllOptionKeys(dynamicContext.carriers);
+  const refs = buildDynamicRefs(order, allOptionKeys);
 
-    return acc;
-  }, {} as ShipmentOptionsRefs);
-
-  refs[FIELD_CARRIER] = get(order, `${FIELD_CARRIER}.externalIdentifier`);
-
-  return defineForm(createShipmentFormName(order.externalIdentifier), {
+  const form = defineForm(createShipmentFormName(order.externalIdentifier), {
     ...(isModal ? config.formConfigOverrides?.modal : null),
     ...config.formConfigOverrides?.shipmentOptions,
-    fields: [
-      // General delivery options
-      createCarrierField(refs, order.inheritedDeliveryOptions),
-
-      createPackageTypeField(refs),
-
-      createDeliveryTypeField(refs),
-
-      createLabelAmountField(refs),
-
-      createDigitalStampRangeField(refs, order),
-
-      // Actual shipment options
-      createAgeCheckField(refs),
-      createSignatureField(refs),
-      createOnlyRecipientField(refs),
-      createDirectReturnField(refs),
-      createLargeFormatField(refs),
-      createHideSenderField(refs),
-      createSameDayDeliveryField(refs),
-      createReceiptCodeField(refs),
-      createInsuranceField(refs),
-      createPriorityDeliveryField(refs),
-    ],
+    fields: createShipmentOptionsFields(refs, order, allOptionKeys),
   });
+
+  if (!isBulk && order.externalIdentifier) {
+    const wired = wireProxyCapabilities(form, order);
+
+    if (wired) {
+      useCapabilitiesAutoClear(
+        form,
+        allOptionKeys,
+        order.externalIdentifier,
+        order.inheritedDeliveryOptions,
+        wired.selection,
+      );
+    }
+  }
+
+  return form;
+};
+
+/**
+ * Collect the union of all option keys across all carriers from the dynamic context.
+ *
+ * Fields are created for every unique option key so they exist when the user
+ * switches carriers. Visibility and disabled state are controlled by
+ * `hasShipmentOption`, which checks whether the currently selected carrier
+ * supports each option.
+ *
+ * Runtime carrier-specific data (isRequired, insuredAmount, etc.) is read
+ * from the currently selected carrier via `getCarrier(form)`, not from
+ * creation-time option data.
+ */
+const collectAllOptionKeys = (carriers: {options?: Record<string, unknown> | null}[]): string[] => {
+  const keys = new Set<string>();
+
+  for (const carrier of carriers) {
+    if (!carrier.options) continue;
+
+    for (const key of Object.keys(carrier.options)) {
+      keys.add(key);
+    }
+  }
+
+  return [...keys];
+};
+
+/**
+ * Build refs dynamically from carrier options and static fields.
+ *
+ * Instead of a hardcoded ALL_FIELDS list, refs are built from the union of
+ * all carrier options in the dynamic context.
+ */
+const buildDynamicRefs = (
+  order: Plugin.ModelContextOrderDataContext,
+  optionKeys: string[],
+): ShipmentOptionsRefs => {
+  const refs: ShipmentOptionsRefs = {};
+
+  // Static field refs
+  refs[FIELD_CARRIER] = get(order, `${FIELD_CARRIER}.carrier`);
+  refs[FIELD_LABEL_AMOUNT] = get(order, FIELD_LABEL_AMOUNT);
+  refs[FIELD_PACKAGE_TYPE] = get(order, FIELD_PACKAGE_TYPE);
+  refs[FIELD_DELIVERY_TYPE] = get(order, FIELD_DELIVERY_TYPE);
+  refs[FIELD_MANUAL_WEIGHT] = get(order, FIELD_MANUAL_WEIGHT);
+
+  // Dynamic shipment option refs from carrier options
+  for (const key of optionKeys) {
+    const fieldName = `${FIELD_SHIPMENT_OPTIONS_PREFIX}.${key}`;
+    refs[fieldName] = get(order, fieldName);
+  }
+
+  return refs;
+};
+
+const createShipmentOptionsFields = (
+  refs: ShipmentOptionsRefs,
+  order: Plugin.ModelContextOrderDataContext,
+  optionKeys: string[],
+): InteractiveElementConfiguration[] => {
+  // Static fields — always present
+  const staticFields = [
+    createCarrierField(refs, order.inheritedDeliveryOptions),
+    createPackageTypeField(refs),
+    createDeliveryTypeField(refs),
+    createLabelAmountField(refs),
+    createDigitalStampRangeField(refs, order),
+  ];
+
+  // Dynamic shipment option fields — driven by carrier.options
+  const dynamicFields = optionKeys.map((key) => {
+    const fieldName = `${FIELD_SHIPMENT_OPTIONS_PREFIX}.${key}`;
+    const factory = fieldFactoryRegistry[key];
+
+    if (factory) {
+      return factory(refs, fieldName);
+    }
+
+    return createShipmentOptionField(refs, fieldName);
+  });
+
+  return [...staticFields, ...dynamicFields];
 };

package/src/forms/shipmentOptions/field.ts

@@ -1,42 +1,18 @@
-import {type Shipment} from '@myparcel-dev/pdk-common';
-
 export type FieldName = string;
 
 const DELIVERY_OPTIONS_PREFIX = 'deliveryOptions';
 
 const PHYSICAL_PROPERTIES_PREFIX = 'physicalProperties';
 
-export const SHIPMENT_OPTIONS = `shipmentOptions`;
-
-const SHIPMENT_OPTIONS_PREFIX = `${DELIVERY_OPTIONS_PREFIX}.${SHIPMENT_OPTIONS}`;
-
-export const CARRIER = 'carrier' satisfies keyof Shipment.ModelDeliveryOptions;
-
-export const LABEL_AMOUNT = 'labelAmount' satisfies keyof Shipment.ModelDeliveryOptions;
-
-export const PACKAGE_TYPE = 'packageType' satisfies keyof Shipment.ModelDeliveryOptions;
-
-export const DELIVERY_TYPE = 'deliveryType' satisfies keyof Shipment.ModelDeliveryOptions;
-
-export const AGE_CHECK = 'ageCheck' satisfies keyof Shipment.ModelShipmentOptions;
-
-export const RECEIPT_CODE = 'receiptCode' satisfies keyof Shipment.ModelShipmentOptions;
-
-export const DIRECT_RETURN = 'return' satisfies keyof Shipment.ModelShipmentOptions;
-
-export const HIDE_SENDER = 'hideSender' satisfies keyof Shipment.ModelShipmentOptions;
-
-export const LARGE_FORMAT = 'largeFormat' satisfies keyof Shipment.ModelShipmentOptions;
+export const SHIPMENT_OPTIONS = 'shipmentOptions';
 
-export const ONLY_RECIPIENT = 'onlyRecipient' satisfies keyof Shipment.ModelShipmentOptions;
+export const CARRIER = 'carrier';
 
-export const SAME_DAY_DELIVERY = 'sameDayDelivery' satisfies keyof Shipment.ModelShipmentOptions;
+export const LABEL_AMOUNT = 'labelAmount';
 
-export const SIGNATURE = 'signature' satisfies keyof Shipment.ModelShipmentOptions;
+export const PACKAGE_TYPE = 'packageType';
 
-export const INSURANCE = 'insurance' satisfies keyof Shipment.ModelShipmentOptions;
-
-export const PRIORITY_DELIVERY = 'priorityDelivery' satisfies keyof Shipment.ModelShipmentOptions;
+export const DELIVERY_TYPE = 'deliveryType';
 
 export const MANUAL_WEIGHT = 'manualWeight';
 
@@ -54,42 +30,6 @@ export const FIELD_PACKAGE_TYPE: FieldName = `${DELIVERY_OPTIONS_PREFIX}.${PACKA
 
 export const FIELD_DELIVERY_TYPE: FieldName = `${DELIVERY_OPTIONS_PREFIX}.${DELIVERY_TYPE}`;
 
-export const FIELD_AGE_CHECK: FieldName = `${SHIPMENT_OPTIONS_PREFIX}.${AGE_CHECK}`;
-
-export const FIELD_DIRECT_RETURN: FieldName = `${SHIPMENT_OPTIONS_PREFIX}.${DIRECT_RETURN}`;
-
-export const FIELD_HIDE_SENDER: FieldName = `${SHIPMENT_OPTIONS_PREFIX}.${HIDE_SENDER}`;
-
-export const FIELD_LARGE_FORMAT: FieldName = `${SHIPMENT_OPTIONS_PREFIX}.${LARGE_FORMAT}`;
-
-export const FIELD_ONLY_RECIPIENT: FieldName = `${SHIPMENT_OPTIONS_PREFIX}.${ONLY_RECIPIENT}`;
-
-export const FIELD_SAME_DAY_DELIVERY: FieldName = `${SHIPMENT_OPTIONS_PREFIX}.${SAME_DAY_DELIVERY}`;
-
-export const FIELD_SIGNATURE: FieldName = `${SHIPMENT_OPTIONS_PREFIX}.${SIGNATURE}`;
-
-export const FIELD_INSURANCE: FieldName = `${SHIPMENT_OPTIONS_PREFIX}.${INSURANCE}`;
-
-export const FIELD_PRIORITY_DELIVERY: FieldName = `${SHIPMENT_OPTIONS_PREFIX}.${PRIORITY_DELIVERY}`;
-
 export const FIELD_MANUAL_WEIGHT: FieldName = `${PHYSICAL_PROPERTIES_PREFIX}.${MANUAL_WEIGHT}`;
 
-export const FIELD_RECEIPT_CODE: FieldName = `${SHIPMENT_OPTIONS_PREFIX}.${RECEIPT_CODE}`;
-
-export const ALL_FIELDS = [
-  FIELD_AGE_CHECK,
-  FIELD_CARRIER,
-  FIELD_DIRECT_RETURN,
-  FIELD_HIDE_SENDER,
-  FIELD_INSURANCE,
-  FIELD_PRIORITY_DELIVERY,
-  FIELD_LABEL_AMOUNT,
-  FIELD_LARGE_FORMAT,
-  FIELD_ONLY_RECIPIENT,
-  FIELD_MANUAL_WEIGHT,
-  FIELD_PACKAGE_TYPE,
-  FIELD_DELIVERY_TYPE,
-  FIELD_SAME_DAY_DELIVERY,
-  FIELD_SIGNATURE,
-  FIELD_RECEIPT_CODE,
-] as const;
+export const FIELD_SHIPMENT_OPTIONS_PREFIX: FieldName = `${DELIVERY_OPTIONS_PREFIX}.${SHIPMENT_OPTIONS}`;

package/src/forms/shipmentOptions/fieldFactoryRegistry.ts

@@ -0,0 +1,26 @@
+import {type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
+import {type ShipmentOptionsRefs} from './types';
+import {createInsuranceField} from './fields/createInsuranceField';
+
+/**
+ * Factory function signature for custom shipment option field creators.
+ *
+ * Uses `string` for fieldName because option names are determined at runtime
+ * from the carrier context and are not a fixed compile-time set.
+ */
+export type FieldFactory = (refs: ShipmentOptionsRefs, fieldName: string) => InteractiveElementConfiguration;
+
+/**
+ * Registry of shipment option names that require custom field rendering.
+ *
+ * Options NOT listed here are rendered as generic TriState toggles by
+ * `createShipmentOptionField`. Each entry maps an option name (as it appears in
+ * `carrier.options`) to its custom factory function.
+ *
+ * Current exceptions:
+ * - `insurance`: renders as a select/dropdown with amount brackets derived from
+ *   `insuredAmount` in the option data.
+ */
+export const fieldFactoryRegistry: Record<string, FieldFactory> = {
+  insurance: createInsuranceField,
+};

package/src/forms/shipmentOptions/fields/createCarrierField.ts

@@ -1,69 +1,159 @@
-import {toValue} from 'vue';
+import {toValue, watch} from 'vue';
+import {snakeCase} from 'lodash-unified';
 import {type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
-import {AdminContextKey, type Plugin} from '@myparcel-dev/pdk-common';
-import {PackageTypeName} from '@myparcel-dev/constants';
+import {AdminContextKey, BackendEndpoint, type CarrierModel, type Plugin} from '@myparcel-dev/pdk-common';
 import {type ShipmentOptionsRefs} from '../types';
-import {FIELD_CARRIER, FIELD_DELIVERY_TYPE, FIELD_INSURANCE, FIELD_PACKAGE_TYPE, PROP_OPTIONS} from '../field';
-import {getDeliveryTypes} from '../../helpers/getDeliveryTypes';
+import {FIELD_CARRIER, FIELD_DELIVERY_TYPE, FIELD_PACKAGE_TYPE, PROP_OPTIONS} from '../field';
 import {
   defineFormField,
-  getInsuranceOptions,
+  getDeliveryTypes,
   getPackageTypes,
   resolveFormComponent,
   setFieldProp,
-  setPostNlAgeCheckSubtext,
   updateFieldsDefaults,
+  useFormCapabilities,
 } from '../../helpers';
-import {createAssetUrl} from '../../../utils';
+import {createAssetUrl, getOrderId} from '../../../utils';
 import {type RadioGroupOption} from '../../../types';
+import {useQueryStore} from '../../../stores';
 import {useFetchCarrier} from '../../../sdk';
 import {AdminComponent} from '../../../data';
-import {useContext, useLanguage, useLocalizedFormatter} from '../../../composables';
+import {useContext, useLanguage} from '../../../composables';
 import {createRef} from './createRef';
 
+type CarrierMeta = {label: string; image?: string};
+
+type OrderCarriersState =
+  | undefined // No query registered (bulk or before wireProxyCapabilities runs) — show all.
+  | 'loading' // Order query is loading — show no options yet.
+  | CarrierModel[]; // Success — only carriers in this list are available.
+
 // eslint-disable-next-line max-lines-per-function
 export const createCarrierField = (
   refs: ShipmentOptionsRefs,
   inheritedDeliveryOptions: Plugin.ModelContextOrderDataContext['inheritedDeliveryOptions'],
 ): InteractiveElementConfiguration => {
   const dynamicContext = useContext(AdminContextKey.Dynamic);
-
-  const formatter = useLocalizedFormatter();
+  const capabilities = useFormCapabilities();
+  const queryStore = useQueryStore();
+  const orderId = getOrderId();
+  const orderModifier = typeof orderId === 'string' ? `${orderId}.order` : undefined;
 
   const {translate} = useLanguage();
 
+  const staticMeta = new Map<string, CarrierMeta>();
+
+  /**
+   * Read the order-capabilities query state. Returns:
+   * - `undefined` when there's no query (bulk path, or pre-wire) → fallback: render all carriers.
+   * - `undefined` when the query is registered but disabled (e.g. order has no country code, so
+   *   `useOrderCapabilitiesQuery`'s `enabled` gate is false). TanStack reports `status: 'pending'`
+   *   indefinitely in that state, so we detect it via `fetchStatus === 'idle'` and fall back to
+   *   the unfiltered carrier list instead of trapping the user in a permanent loading state.
+   * - `'loading'` while the query hasn't resolved → render no options to avoid a flash where
+   *   carriers appear and then a subset disappears once the response lands.
+   * - `CarrierModel[]` on success → render only the carriers in this list (others are hidden).
+   * - On error: treated as `undefined` so the merchant can still operate the form, accepting
+   *   that a stale or empty filter is better than an empty radio.
+   */
+  const readOrderCarriers = (): OrderCarriersState => {
+    if (!orderModifier || !queryStore.has(BackendEndpoint.ProxyCapabilities, orderModifier)) {
+      return undefined;
+    }
+
+    const query = queryStore.get(BackendEndpoint.ProxyCapabilities, orderModifier);
+    const status = toValue(query.status);
+    const fetchStatus = toValue(query.fetchStatus);
+
+    if (status === 'success') {
+      return (toValue(query.data) ?? []) as CarrierModel[];
+    }
+
+    if (status === 'error') {
+      return undefined;
+    }
+
+    if (fetchStatus === 'idle') {
+      return undefined;
+    }
+
+    return 'loading';
+  };
+
+  const computeOptions = (state: OrderCarriersState): RadioGroupOption[] => {
+    if (state === 'loading') return [];
+
+    const validCarrierNames = Array.isArray(state) ? new Set(state.map((c) => c.carrier)) : null;
+    const carriersToRender = validCarrierNames
+      ? dynamicContext.carriers.filter((carrier) => validCarrierNames.has(carrier.carrier ?? ''))
+      : dynamicContext.carriers;
+
+    return carriersToRender.map((carrier): RadioGroupOption => {
+      const name = carrier.carrier ?? '';
+      const meta = staticMeta.get(name);
+
+      return {
+        plainLabel: meta?.label ?? name,
+        value: name,
+        image: meta?.image,
+      };
+    });
+  };
+
   return defineFormField({
     name: FIELD_CARRIER,
     label: 'carrier',
-    ref: createRef<string>(refs, FIELD_CARRIER, PackageTypeName.Package),
+    ref: createRef<string>(refs, FIELD_CARRIER, dynamicContext.shop.defaultCarrier ?? undefined),
     component: resolveFormComponent(AdminComponent.RadioGroup),
     props: {
       options: [],
     },
 
     onBeforeMount: async (field) => {
-      const carrierSelectOptions = await Promise.all(
-        dynamicContext.carriers.map(async (carrier): Promise<RadioGroupOption> => {
-          const query = useFetchCarrier(carrier.name);
+      // Fetch per-carrier metadata (logo + localized human name) once. Stored in `staticMeta`
+      // so the reactive options watcher below can stitch label/image together with the
+      // current order-capabilities filter without re-fetching.
+      await Promise.all(
+        dynamicContext.carriers.map(async (carrier) => {
+          const query = useFetchCarrier(carrier.carrier);
+
           await query.suspense();
 
           const apiCarrier = toValue(query.data);
 
-          let plainLabel = apiCarrier?.human ?? carrier.human ?? '';
-
-          if (!carrier.isDefault) {
-            plainLabel += ` ${carrier.label ?? translate(`carrier_type_${carrier.type}`)}`;
-          }
-
-          return {
-            plainLabel,
-            value: carrier.externalIdentifier ?? apiCarrier?.name ?? '',
+          staticMeta.set(carrier.carrier ?? '', {
+            label: apiCarrier?.human ?? translate(`carrier_${snakeCase(carrier.carrier)}`) ?? '',
             image: apiCarrier?.meta.logo_svg ? createAssetUrl(apiCarrier.meta.logo_svg) : undefined,
-          };
+          });
         }),
       );
 
-      setFieldProp(field, PROP_OPTIONS, carrierSelectOptions);
+      // Reactively rebuild the carrier radio options whenever the order-capabilities query
+      // changes state (loading → success, or weight/cc edits triggering a refetch). Carriers
+      // that aren't valid for the current order context (e.g. weight below the minimum) are
+      // hidden from the radio entirely — preventing the dead-end scenario where the form
+      // populates with packageType / deliveryType radios that have no valid combo. The
+      // RadioGroup component doesn't honor per-option `disabled` flags, so filter is the
+      // only way to express "not available" today.
+      //
+      // Also refresh package/delivery type dropdowns from the same response: weight/cc edits
+      // can shrink the available types for a carrier without changing the chosen carrier, and
+      // `afterUpdate` only runs on carrier change. Without this refresh those dropdowns would
+      // keep stale options after the order-capabilities response narrows.
+      watch(
+        () => readOrderCarriers(),
+        (state) => {
+          setFieldProp(field, PROP_OPTIONS, computeOptions(state));
+
+          const carrier = capabilities.getCarrierCapabilitiesForOrder(field.form);
+
+          if (carrier) {
+            setFieldProp(field.form, FIELD_PACKAGE_TYPE, PROP_OPTIONS, getPackageTypes(carrier));
+            setFieldProp(field.form, FIELD_DELIVERY_TYPE, PROP_OPTIONS, getDeliveryTypes(carrier));
+          }
+        },
+        {immediate: true},
+      );
 
       await field?.afterUpdate?.(field, toValue(field.ref), undefined);
 
@@ -73,11 +163,10 @@ export const createCarrierField = (
     afterUpdate: (field, newCarrier: string) => {
       updateFieldsDefaults(newCarrier, field, inheritedDeliveryOptions);
 
-      setFieldProp(field.form, FIELD_INSURANCE, PROP_OPTIONS, getInsuranceOptions(field, formatter));
-      setFieldProp(field.form, FIELD_PACKAGE_TYPE, PROP_OPTIONS, getPackageTypes(field.form));
-      setFieldProp(field.form, FIELD_DELIVERY_TYPE, PROP_OPTIONS, getDeliveryTypes(field.form));
+      const carrier = capabilities.getCarrierCapabilitiesForOrder(field.form);
 
-      setPostNlAgeCheckSubtext(field);
+      setFieldProp(field.form, FIELD_PACKAGE_TYPE, PROP_OPTIONS, getPackageTypes(carrier));
+      setFieldProp(field.form, FIELD_DELIVERY_TYPE, PROP_OPTIONS, getDeliveryTypes(carrier));
     },
   });
 };

package/src/forms/shipmentOptions/fields/createDigitalStampRangeField.ts

@@ -2,7 +2,6 @@ import {ref, toValue} from 'vue';
 import {get} from 'lodash-unified';
 import {type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
 import {type Plugin, TriState} from '@myparcel-dev/pdk-common';
-import {PackageTypeName} from '@myparcel-dev/constants';
 import {type ShipmentOptionsRefs} from '../types';
 import {FIELD_MANUAL_WEIGHT, FIELD_PACKAGE_TYPE} from '../field';
 import {createDefaultOption, defineFormField, resolveFormComponent} from '../../helpers';
@@ -34,8 +33,9 @@ export const createDigitalStampRangeField = (
     label: 'weight_range',
     ref: ref(selectedValue ?? TriState.Inherit),
     component: resolveFormComponent(AdminComponent.SelectInput),
-    visibleWhen: (field) => PackageTypeName.DigitalStamp === field.form.getValue(FIELD_PACKAGE_TYPE),
-    disabledWhen: (field) => PackageTypeName.DigitalStamp !== field.form.getValue(FIELD_PACKAGE_TYPE),
+    // @TODO Remove package type checks when the context provides visibility restrictions per option.
+    visibleWhen: (field) => field.form.getValue(FIELD_PACKAGE_TYPE) === 'DIGITAL_STAMP',
+    disabledWhen: (field) => field.form.getValue(FIELD_PACKAGE_TYPE) !== 'DIGITAL_STAMP',
     props: {
       subtext: {
         key: 'order_weight',

package/src/forms/shipmentOptions/fields/createInsuranceField.ts

@@ -1,31 +1,52 @@
-import { type InteractiveElementConfiguration } from '@myparcel-dev/vue-form-builder';
-import { type ShipmentOptionsRefs } from '../types';
-import { FIELD_INSURANCE, PROP_OPTIONS, INSURANCE } from '../field';
-import {
-  createHasShipmentOptionWatcher,
-  getInsuranceOptions,
-  isPackageTypePackageOrSmall,
-  resolveFormComponent,
-  setFieldProp,
-} from '../../helpers';
-import { type ElementInstance } from '../../../types';
-import { AdminComponent } from '../../../data';
-import { useLocalizedFormatter } from '../../../composables';
-import { createShipmentOptionField } from './createShipmentOptionField';
-import { createRef } from './createRef';
+import {watch} from 'vue';
+import {type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
+import {type ShipmentOptionsRefs} from '../types';
+import {PROP_OPTIONS} from '../field';
+import {resolveFormComponent, setFieldProp, useFormCapabilities} from '../../helpers';
+import {type ElementInstance} from '../../../types';
+import {AdminComponent} from '../../../data';
+import {useLocalizedFormatter} from '../../../composables';
+import {createShipmentOptionField} from './createShipmentOptionField';
+import {createRef} from './createRef';
 
-export const createInsuranceField = (refs: ShipmentOptionsRefs): InteractiveElementConfiguration => {
+/**
+ * Custom field factory for the insurance shipment option.
+ *
+ * Renders as a select/dropdown instead of a TriState toggle. Insurance amount brackets are
+ * derived from the currently selected carrier's shipment-scoped `insuredAmount` data (min/max)
+ * and refresh automatically whenever that data changes — i.e. on carrier change AND on
+ * packageType / deliveryType / weight / cc change, since those all narrow the shipment-scoped
+ * capabilities response.
+ *
+ * Visibility / disabled state is inherited from {@link createShipmentOptionField} — driven
+ * purely by `hasShipmentOption` (i.e. by the capabilities response). No manual package-type
+ * gating: if insurance isn't valid for the current combination, the API won't include it in
+ * `carrier.options` and the field will hide.
+ */
+export const createInsuranceField = (
+  refs: ShipmentOptionsRefs,
+  fieldName: string,
+): InteractiveElementConfiguration => {
   const formatter = useLocalizedFormatter();
+  const capabilities = useFormCapabilities();
+  let stopWatcher: (() => void) | undefined;
 
-  return createShipmentOptionField(refs, FIELD_INSURANCE, {
-    ref: createRef(refs, FIELD_INSURANCE, 0),
+  return createShipmentOptionField(refs, fieldName, {
+    ref: createRef(refs, fieldName, 0),
     component: resolveFormComponent(AdminComponent.SelectInput),
-    visibleWhen: createHasShipmentOptionWatcher(INSURANCE, false, isPackageTypePackageOrSmall),
-    disabledWhen: createHasShipmentOptionWatcher(INSURANCE, true, isPackageTypePackageOrSmall),
     onBeforeMount(field: ElementInstance) {
-      const insurancePossibilities = getInsuranceOptions(field, formatter);
+      stopWatcher?.();
 
-      setFieldProp(field, PROP_OPTIONS, insurancePossibilities);
+      // Watch the shipment-scoped carrier capabilities directly. The resolver tracks both the
+      // selected carrier (via `form.getValue(FIELD_CARRIER)`) and the shipment-capabilities
+      // query data, so any axis change that updates `insuredAmount` triggers a refresh.
+      stopWatcher = watch(
+        () => capabilities.getCarrierCapabilitiesForShipment(field.form),
+        () => {
+          setFieldProp(field, PROP_OPTIONS, capabilities.getInsuranceOptions(field.form, formatter));
+        },
+        {immediate: true},
+      );
     },
   });
 };

package/src/forms/shipmentOptions/fields/createPackageTypeField.ts

@@ -1,6 +1,5 @@
 import {snakeCase} from 'lodash-unified';
 import {type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
-import {PackageTypeName} from '@myparcel-dev/constants';
 import {type ShipmentOptionsRefs} from '../types';
 import {FIELD_PACKAGE_TYPE, SHIPMENT_OPTIONS} from '../field';
 import {defineFormField, resolveFormComponent} from '../../helpers';
@@ -11,7 +10,7 @@ export const createPackageTypeField = (refs: ShipmentOptionsRefs): InteractiveEl
   return defineFormField({
     name: FIELD_PACKAGE_TYPE,
     label: snakeCase(`${SHIPMENT_OPTIONS}_package_type`),
-    ref: createRef<PackageTypeName>(refs, FIELD_PACKAGE_TYPE, PackageTypeName.Package),
+    ref: createRef<string>(refs, FIELD_PACKAGE_TYPE, 'PACKAGE'),
     component: resolveFormComponent(AdminComponent.RadioGroup),
     // options defined in afterUpdate of `createCarrierField`
   });