@myparcel-dev/pdk-admin 1.14.2 → 2.0.1

package/src/forms/helpers/useFormCapabilities.ts

@@ -0,0 +1,176 @@
+import {toValue} from 'vue';
+import {type FormInstance} from '@myparcel-dev/vue-form-builder';
+import {AdminContextKey, BackendEndpoint, type CarrierModel, TriState} from '@myparcel-dev/pdk-common';
+import {FIELD_CARRIER} from '../shipmentOptions/field';
+import {getOrderId} from '../../utils';
+import {type AdminContext, type SelectOption} from '../../types';
+import {useQueryStore, type ResolvedQuery} from '../../stores';
+import {Format, type Formatter} from '../../composables';
+
+interface InsuranceAmountData {
+  insuredAmount?: {
+    min: {amount: number; currency: string};
+    max: {amount: number; currency: string};
+    default: {amount: number; currency: string};
+  };
+}
+
+/**
+ * Bag of capability resolvers, each pre-bound to a Pinia store + orderId snapshot captured at
+ * the composable's invocation time. Returned by {@link useFormCapabilities}.
+ *
+ * The functions are plain — they don't call `useQueryStore()` / `getOrderId()` on each
+ * invocation, so they're safe to call from outside Vue setup context (e.g. inside
+ * vue-form-builder's `visibleWhen` / `disabledWhen` / `readOnlyWhen` / `afterUpdate`
+ * watchEffect-driven re-evaluators, where `inject()` is not available).
+ */
+export type FormCapabilities = {
+  /**
+   * Resolve the chosen carrier's order-level capability data — destination + weight scope only.
+   * Used to populate carrier / packageType / deliveryType dropdowns. `requires` / `excludes`
+   * are NEVER populated through this path; they only appear on `getCarrierCapabilitiesForShipment`.
+   */
+  getCarrierCapabilitiesForOrder: (form: FormInstance) => CarrierModel | undefined;
+
+  /**
+   * Resolve the chosen carrier's shipment-level capability data — narrowed to the full
+   * selection (carrier + packageType + deliveryType + cc + weight). Three return states:
+   *
+   * 1. **Shipment-narrow carrier** — query is `success` AND its results contain the chosen
+   *    carrier. Returns that carrier with the narrow option set.
+   * 2. **Order-level fallback** — query isn't registered, loading, or errored. Falls back to
+   *    `getCarrierCapabilitiesForOrder` so transient loading windows don't empty the form.
+   * 3. **`undefined`** — query is `success` but its results don't contain the chosen carrier.
+   *    Server has confirmed the combo is invalid; consumers must handle gracefully.
+   */
+  getCarrierCapabilitiesForShipment: (form: FormInstance) => CarrierModel | undefined;
+
+  /**
+   * Whether the chosen shipment configuration supports a given option. Reads from the
+   * shipment-scoped carrier; falls through to order-level data when shipment data isn't
+   * available yet.
+   */
+  hasShipmentOption: (form: FormInstance, option: string) => boolean;
+
+  /**
+   * Insurance amount bracket options derived from the currently selected carrier's
+   * `insuredAmount` data. Amounts in the context are in cents; emitted values are strings
+   * representing cent amounts so they round-trip through form select inputs unchanged.
+   */
+  getInsuranceOptions: (form: FormInstance, formatter: Formatter) => SelectOption[];
+};
+
+/**
+ * Closure-factory composable that captures Pinia + orderId references ONCE at its
+ * setup-context invocation, and returns plain resolver functions pre-bound to those captures.
+ *
+ * Why this exists: form-builder's `visibleWhen` / `disabledWhen` / `readOnlyWhen` / `afterUpdate`
+ * re-evaluators run inside an internal `watchEffect`, NOT inside Vue setup. Calling
+ * `useQueryStore()` / `useContext()` / `getOrderId()` from those callbacks fires Vue's
+ * `inject() can only be used inside setup()` warning AND can return a disconnected store
+ * instance, breaking reactive dep tracking on `queries.value[modifier]`.
+ *
+ * Capturing once here, then closing over those references in the returned resolvers, gives
+ * factories a single seam to call from setup — `const capabilities = useFormCapabilities()` — without
+ * threading a context object through every helper signature.
+ *
+ * Pinia is a singleton, so all `useFormCapabilities()` callers within the same Pinia instance
+ * reference the same underlying store. The dynamic-context entry in the store is itself a
+ * TanStack query whose `data` is reactive — `useFetchContextQuery` refetches `Dynamic` on
+ * window focus, so we read `query.data` live on every resolver call rather than snapshotting
+ * the carriers array at setup time.
+ */
+export const useFormCapabilities = (): FormCapabilities => {
+  const queryStore = useQueryStore();
+  const dynamicContextQuery = queryStore.get(BackendEndpoint.FetchContext, AdminContextKey.Dynamic) as ResolvedQuery<
+    BackendEndpoint.FetchContext
+  >;
+  const orderId = getOrderId();
+
+  const orderModifier = typeof orderId === 'string' ? `${orderId}.order` : undefined;
+  const shipmentModifier = typeof orderId === 'string' ? `${orderId}.shipment` : undefined;
+
+  const carriersFromQuery = (modifier: string): CarrierModel[] | undefined => {
+    if (!queryStore.has(BackendEndpoint.ProxyCapabilities, modifier)) return undefined;
+
+    const query = queryStore.get(BackendEndpoint.ProxyCapabilities, modifier);
+
+    if (toValue(query.status) !== 'success') return undefined;
+
+    return (toValue(query.data) ?? []) as CarrierModel[];
+  };
+
+  const liveDynamicCarriers = (): CarrierModel[] => {
+    const data = toValue(dynamicContextQuery.data) as AdminContext<AdminContextKey.Dynamic> | undefined;
+
+    return data?.carriers ?? [];
+  };
+
+  const getCarrierCapabilitiesForOrder = (form: FormInstance): CarrierModel | undefined => {
+    const chosenCarrier = form.getValue(FIELD_CARRIER);
+
+    if (orderModifier) {
+      const carriers = carriersFromQuery(orderModifier);
+      const fromQuery = carriers?.find((carrier) => carrier.carrier === chosenCarrier);
+
+      if (fromQuery) return fromQuery;
+    }
+
+    return liveDynamicCarriers().find((carrier) => carrier.carrier === chosenCarrier);
+  };
+
+  const getCarrierCapabilitiesForShipment = (form: FormInstance): CarrierModel | undefined => {
+    if (!shipmentModifier) return getCarrierCapabilitiesForOrder(form);
+
+    const carriers = carriersFromQuery(shipmentModifier);
+
+    if (!carriers) return getCarrierCapabilitiesForOrder(form);
+
+    const chosenCarrier = form.getValue(FIELD_CARRIER);
+
+    return carriers.find((carrier) => carrier.carrier === chosenCarrier);
+  };
+
+  const hasShipmentOption = (form: FormInstance, option: string): boolean => {
+    const carrier = getCarrierCapabilitiesForShipment(form);
+
+    return Object.hasOwn(carrier?.options ?? {}, option);
+  };
+
+  const getInsuranceOptions = (form: FormInstance, formatter: Formatter): SelectOption[] => {
+    // Insurance bracket steps: €250 increments below €500, €500 increments above. Switching
+    // step size at the threshold keeps the dropdown short for high-value shipments.
+    const STEP_BELOW_THRESHOLD = 250;
+    const STEP_ABOVE_THRESHOLD = 500;
+    const STEP_THRESHOLD = 500;
+
+    const carrier = getCarrierCapabilitiesForShipment(form);
+    const insuranceData = (carrier?.options?.insurance ?? {}) as InsuranceAmountData;
+
+    const min = insuranceData.insuredAmount?.min.amount ? insuranceData.insuredAmount.min.amount / 100 : 0;
+    const max = insuranceData.insuredAmount?.max.amount ? insuranceData.insuredAmount.max.amount / 100 : 0;
+
+    if (max === 0) return [];
+
+    const insurancePossibilities: number[] = [];
+
+    for (let i = min; i <= max; i += i < STEP_THRESHOLD ? STEP_BELOW_THRESHOLD : STEP_ABOVE_THRESHOLD) {
+      insurancePossibilities.push(i * 100);
+    }
+
+    return [
+      {label: 'option_default', value: TriState.Inherit},
+      ...insurancePossibilities.map((amount) => ({
+        plainLabel: formatter.format(Format.Currency, amount / 100),
+        value: amount.toString(),
+      })),
+    ];
+  };
+
+  return {
+    getCarrierCapabilitiesForOrder,
+    getCarrierCapabilitiesForShipment,
+    hasShipmentOption,
+    getInsuranceOptions,
+  };
+};

package/src/forms/pluginSettings/createPluginSettingsForm.ts

@@ -1,4 +1,3 @@
-import {get as lodashGet} from 'lodash-unified';
 import {BackendEndpoint, type Plugin} from '@myparcel-dev/pdk-common';
 import {defineForm, type FormInstance} from '@myparcel-dev/vue-form-builder';
 import {useStoreQuery} from '../../composables';
@@ -6,6 +5,7 @@ import {SubmitButton} from '../../components';
 import {executeAction} from '../../actions';
 import {type PluginSettingsTabsContext} from './types';
 import {generateFormFields} from './generateFormFields';
+import {resolveSettingsValues} from './resolveSettingsValues';
 
 export const createPluginSettingsForm = (
   id: string,
@@ -16,7 +16,7 @@ export const createPluginSettingsForm = (
 
   const mutation = useStoreQuery(BackendEndpoint.UpdatePluginSettings);
 
-  const values = lodashGet(pluginSettings, id, {});
+  const values = resolveSettingsValues(pluginSettings, id);
 
   const generatedFields = generateFormFields({fields: view.elements, values}, `${id}.`);
 

package/src/forms/pluginSettings/filterPluginSettingsView.spec.ts

@@ -0,0 +1,158 @@
+import {describe, expect, it} from 'vitest';
+import {type Plugin} from '@myparcel-dev/pdk-common';
+import {OrderMode} from '../../data';
+import {filterPluginSettingsView} from './filterPluginSettingsView';
+
+const createField = (name: string, component = 'ToggleInput'): Plugin.Field => ({
+  name,
+  $component: component,
+  label: `label_${name}`,
+});
+
+const createDivider = (heading: string): Plugin.Field =>
+  ({
+    $component: 'SettingsDivider',
+    $wrapper: false,
+    level: 2,
+    heading,
+    content: `${heading}_description`,
+  } as Plugin.Field);
+
+const createSettingsView = (overrides: Partial<Plugin.SettingsView> = {}): Plugin.SettingsView => ({
+  id: 'test',
+  title: 'test',
+  elements: null,
+  children: null,
+  ...overrides,
+});
+
+const createOrderView = (): Plugin.SettingsView =>
+  createSettingsView({
+    id: 'order',
+    title: 'settings_order_title',
+    elements: [
+      createDivider('settings_order_general_title'),
+      createField('conceptShipments'),
+      createField('processDirectly', 'SelectInput'),
+      createField('sendReturnEmail'),
+      createField('saveCustomerAddress'),
+      createField('shareCustomerInformation'),
+      createDivider('settings_order_status_title'),
+      createField('statusOnLabelCreate', 'SelectInput'),
+      createField('statusWhenLabelScanned', 'SelectInput'),
+      createDivider('settings_order_track_trace_title'),
+      createField('trackTraceInEmail'),
+      createField('trackTraceInAccount'),
+    ],
+  });
+
+const createFullView = (): Plugin.ModelContextPluginSettingsViewContext =>
+  ({
+    order: createOrderView(),
+    label: createSettingsView({id: 'label', title: 'Labels'}),
+    customs: createSettingsView({id: 'customs', title: 'Customs'}),
+    checkout: createSettingsView({id: 'checkout', title: 'Checkout'}),
+    carrier: createSettingsView({id: 'carrier', title: 'Carriers'}),
+  } as Plugin.ModelContextPluginSettingsViewContext);
+
+const getFieldNames = (elements: Plugin.Field[] | null): string[] =>
+  (elements ?? []).filter((el) => el.name).map((el) => el.name!);
+
+const getTabIds = (view: Plugin.ModelContextPluginSettingsViewContext): string[] => Object.keys(view);
+
+describe('filterPluginSettingsView', () => {
+  describe('Shipments mode', () => {
+    it('keeps all General section fields visible', () => {
+      const result = filterPluginSettingsView(createFullView(), OrderMode.Shipments);
+      const fieldNames = getFieldNames(result.order.elements);
+
+      expect(fieldNames).toContain('conceptShipments');
+      expect(fieldNames).toContain('saveCustomerAddress');
+      expect(fieldNames).toContain('processDirectly');
+      expect(fieldNames).toContain('sendReturnEmail');
+      expect(fieldNames).toContain('shareCustomerInformation');
+    });
+
+    it('keeps all tabs visible', () => {
+      const result = filterPluginSettingsView(createFullView(), OrderMode.Shipments);
+
+      expect(getTabIds(result)).toEqual(['order', 'label', 'customs', 'checkout', 'carrier']);
+    });
+  });
+
+  describe('OrderV1 mode', () => {
+    it('hides conceptShipments and saveCustomerAddress', () => {
+      const result = filterPluginSettingsView(createFullView(), OrderMode.OrderV1);
+      const fieldNames = getFieldNames(result.order.elements);
+
+      expect(fieldNames).not.toContain('conceptShipments');
+      expect(fieldNames).not.toContain('saveCustomerAddress');
+    });
+
+    it('keeps other General section fields visible', () => {
+      const result = filterPluginSettingsView(createFullView(), OrderMode.OrderV1);
+      const fieldNames = getFieldNames(result.order.elements);
+
+      expect(fieldNames).toContain('processDirectly');
+      expect(fieldNames).toContain('sendReturnEmail');
+      expect(fieldNames).toContain('shareCustomerInformation');
+    });
+
+    it('keeps all tabs visible', () => {
+      const result = filterPluginSettingsView(createFullView(), OrderMode.OrderV1);
+
+      expect(getTabIds(result)).toEqual(['order', 'label', 'customs', 'checkout', 'carrier']);
+    });
+  });
+
+  describe('OrderV2 mode (hybrid: surfaces the same fields and tabs as Shipments)', () => {
+    it('keeps all General section fields visible, including the shipment-export-only ones', () => {
+      const result = filterPluginSettingsView(createFullView(), OrderMode.OrderV2);
+      const fieldNames = getFieldNames(result.order.elements);
+
+      expect(fieldNames).toContain('conceptShipments');
+      expect(fieldNames).toContain('saveCustomerAddress');
+      expect(fieldNames).toContain('processDirectly');
+      expect(fieldNames).toContain('sendReturnEmail');
+      expect(fieldNames).toContain('shareCustomerInformation');
+    });
+
+    it('keeps the General section divider in place', () => {
+      const result = filterPluginSettingsView(createFullView(), OrderMode.OrderV2);
+      const elements = result.order.elements ?? [];
+
+      const hasGeneralDivider = elements.some(
+        (el) => (el as Record<string, unknown>).heading === 'settings_order_general_title',
+      );
+
+      expect(hasGeneralDivider).toBe(true);
+    });
+
+    it('keeps all tabs visible (label and customs return alongside Shipments-mode behaviour)', () => {
+      const result = filterPluginSettingsView(createFullView(), OrderMode.OrderV2);
+
+      expect(getTabIds(result)).toEqual(['order', 'label', 'customs', 'checkout', 'carrier']);
+    });
+
+    it('keeps non-General sections in the order tab', () => {
+      const result = filterPluginSettingsView(createFullView(), OrderMode.OrderV2);
+      const fieldNames = getFieldNames(result.order.elements);
+
+      expect(fieldNames).toContain('statusOnLabelCreate');
+      expect(fieldNames).toContain('statusWhenLabelScanned');
+      expect(fieldNames).toContain('trackTraceInEmail');
+      expect(fieldNames).toContain('trackTraceInAccount');
+    });
+  });
+
+  it('does not mutate the input view', () => {
+    const view = createFullView();
+    const originalOrderElements = [...(view.order.elements ?? [])];
+    const originalTabIds = Object.keys(view);
+
+    filterPluginSettingsView(view, OrderMode.OrderV2);
+
+    expect(Object.keys(view)).toEqual(originalTabIds);
+    expect(view.order.elements).toEqual(originalOrderElements);
+  });
+});

package/src/forms/pluginSettings/filterPluginSettingsView.ts

@@ -0,0 +1,96 @@
+import {type Plugin} from '@myparcel-dev/pdk-common';
+import {OrderMode} from '../../data';
+
+const GENERAL_SECTION_HEADING = 'settings_order_general_title';
+
+/**
+ * Settings only relevant when the plugin creates shipments via the shipments API —
+ * that covers Shipments mode and the V2 hybrid (manual export). Order v1 uses the
+ * fulfilment-orders path instead, so these settings are hidden there.
+ *
+ * @TODO INT-1590: revisit when sales-channel detection lands — under V2 with an
+ *       active sales channel these settings should be hidden again.
+ */
+const SHIPMENT_EXPORT_FIELDS: ReadonlySet<string> = new Set(['conceptShipments', 'saveCustomerAddress']);
+
+// @TODO INT-1590: restore tab hiding once sales-channel detection lands; under V2
+//       with an active sales channel the label and customs tabs become irrelevant
+//       again (the sales channel handles fulfilment end-to-end).
+// const ORDER_V2_HIDDEN_TABS: ReadonlySet<string> = new Set(['label', 'customs']);
+
+const isSettingsDivider = (field: Plugin.Field): boolean => {
+  return field.$component === 'SettingsDivider';
+};
+
+const isGeneralDivider = (field: Plugin.Field): boolean => {
+  return isSettingsDivider(field) && (field as Record<string, unknown>).heading === GENERAL_SECTION_HEADING;
+};
+
+const filterOrderElements = (elements: Plugin.Field[], orderMode: OrderMode): Plugin.Field[] => {
+  let inGeneralSection = false;
+
+  return elements.filter((field) => {
+    if (isGeneralDivider(field)) {
+      inGeneralSection = true;
+    } else if (isSettingsDivider(field)) {
+      inGeneralSection = false;
+    }
+
+    if (!inGeneralSection) {
+      return true;
+    }
+
+    // @TODO INT-1590: restore the V2-divider hiding for active-sales-channel state.
+    // if (isSettingsDivider(field)) {
+    //   return orderMode !== OrderMode.OrderV2;
+    // }
+
+    if (SHIPMENT_EXPORT_FIELDS.has(field.name ?? '')) {
+      return orderMode !== OrderMode.OrderV1;
+    }
+
+    // @TODO INT-1590: restore the V2 general-section hiding for active-sales-channel state.
+    // return orderMode !== OrderMode.OrderV2;
+    return true;
+  });
+};
+
+/**
+ * Filter the plugin-settings view for the active order mode.
+ *
+ * Today the V2 hybrid surfaces all the same tabs and fields as Shipments mode so
+ * manual export keeps working. Only Order v1 hides the shipment-export-specific
+ * fields, because v1 uses fulfilment orders instead.
+ *
+ * @TODO INT-1590: once sales-channel detection lands, re-introduce tab hiding for
+ *       V2 with an active sales channel — the label/customs tabs and shipment-export
+ *       fields become irrelevant when the sales channel handles fulfilment
+ *       end-to-end.
+ */
+export const filterPluginSettingsView = (
+  view: Plugin.ModelContextPluginSettingsViewContext,
+  orderMode: OrderMode,
+): Plugin.ModelContextPluginSettingsViewContext => {
+  // @TODO INT-1590: restore the V2 tab-hiding step using ORDER_V2_HIDDEN_TABS
+  //       (declared as commented constant above) once sales-channel detection lands.
+  // const entries = Object.entries(view).filter(([tabId]) => {
+  //   return !(orderMode === OrderMode.OrderV2 && ORDER_V2_HIDDEN_TABS.has(tabId));
+  // });
+  const entries = Object.entries(view);
+
+  return Object.fromEntries(
+    entries.map(([tabId, tabView]) => {
+      if (tabId !== 'order' || !tabView.elements) {
+        return [tabId, tabView];
+      }
+
+      return [
+        tabId,
+        {
+          ...tabView,
+          elements: filterOrderElements(tabView.elements, orderMode),
+        },
+      ];
+    }),
+  ) as Plugin.ModelContextPluginSettingsViewContext;
+};

package/src/forms/pluginSettings/index.ts

@@ -2,5 +2,6 @@ export * from './createFormTab';
 export * from './createPluginSettingsForm';
 export * from './createPluginSettingsTabs';
 export * from './createPluginSettingsTabsComponent';
+export * from './filterPluginSettingsView';
 export * from './generateFormFields';
 export * from './types';

package/src/forms/pluginSettings/resolveSettingsValues.spec.ts

@@ -0,0 +1,62 @@
+import {describe, expect, it} from 'vitest';
+import {resolveSettingsValues} from './resolveSettingsValues';
+
+describe('resolveSettingsValues', () => {
+  const pluginSettings = {
+    order: {
+      conceptShipments: true,
+      processDirectly: '-1',
+    },
+    carrier: {
+      '*': {
+        exportSignature: 0,
+        exportAgeCheck: 0,
+        allowSignature: true,
+        allowOnlyRecipient: true,
+      },
+      POSTNL: {
+        exportSignature: 1,
+        exportAgeCheck: 0,
+        allowSignature: true,
+        allowOnlyRecipient: false,
+      },
+    },
+  };
+
+  // Direct match — carrier-specific settings exist.
+  it('returns carrier-specific values when they exist', () => {
+    const values = resolveSettingsValues(pluginSettings, 'carrier.POSTNL');
+
+    expect(values).toEqual(pluginSettings.carrier.POSTNL);
+  });
+
+  // Wildcard fallback — no carrier-specific settings saved yet.
+  it('falls back to wildcard values when carrier key does not exist', () => {
+    const values = resolveSettingsValues(pluginSettings, 'carrier.DHL_FOR_YOU');
+
+    expect(values).toEqual(pluginSettings.carrier['*']);
+  });
+
+  // Top-level key without sub-keys — no wildcard needed.
+  it('resolves top-level settings directly', () => {
+    const values = resolveSettingsValues(pluginSettings, 'order');
+
+    expect(values).toEqual(pluginSettings.order);
+  });
+
+  // Neither specific key nor wildcard exists — returns empty object.
+  it('returns empty object when neither key nor wildcard exists', () => {
+    const values = resolveSettingsValues(pluginSettings, 'nonexistent.section');
+
+    expect(values).toEqual({});
+  });
+
+  // Carrier-specific values take precedence over wildcard.
+  it('does not merge wildcard — carrier-specific values fully override', () => {
+    const values = resolveSettingsValues(pluginSettings, 'carrier.POSTNL');
+
+    // POSTNL has allowOnlyRecipient: false, wildcard has true.
+    // Should use the carrier-specific value, not the wildcard.
+    expect(values).toHaveProperty('allowOnlyRecipient', false);
+  });
+});

package/src/forms/pluginSettings/resolveSettingsValues.ts

@@ -0,0 +1,16 @@
+import {get as lodashGet} from 'lodash-unified';
+
+/**
+ * Resolve settings values for a given form ID, falling back to the wildcard
+ * key when no carrier-specific settings have been saved yet.
+ *
+ * Example: "carrier.POSTNL" → try pluginSettings.carrier.POSTNL first,
+ * fall back to pluginSettings.carrier.* if it doesn't exist.
+ */
+export const resolveSettingsValues = (
+  pluginSettings: Record<string, unknown>,
+  id: string,
+): Record<string, unknown> => {
+  return (lodashGet(pluginSettings, id)
+    ?? lodashGet(pluginSettings, id.replace(/\.[^.]+$/, '.*'), {})) as Record<string, unknown>;
+};

package/src/forms/shipmentOptions/createShipmentOptionsForm.spec.ts

@@ -0,0 +1,108 @@
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {useContext} from '../../composables';
+import {FIELD_SHIPMENT_OPTIONS_PREFIX} from './field';
+import {createShipmentOptionsForm} from './createShipmentOptionsForm';
+
+vi.mock('../../composables', () => ({
+  useAdminConfig: vi.fn(() => ({formConfigOverrides: {}})),
+  useContext: vi.fn(),
+}));
+
+vi.mock('../../stores', () => ({
+  useModalStore: vi.fn(() => ({opened: undefined})),
+}));
+
+vi.mock('../helpers', () => ({
+  addBulkEditNotification: vi.fn(),
+}));
+
+vi.mock('../../utils', () => ({
+  createShipmentFormName: vi.fn(() => 'shipment-form'),
+}));
+
+vi.mock('@myparcel-dev/vue-form-builder', () => ({
+  defineForm: vi.fn((_name: string, config: {fields: unknown[]}) => config),
+  MagicForm: {name: 'MagicForm', render: () => null},
+}));
+
+vi.mock('./fields', () => ({
+  createDigitalStampRangeField: () => ({name: '__static_digitalStampRange'}),
+  createLabelAmountField: () => ({name: '__static_labelAmount'}),
+  createPackageTypeField: () => ({name: '__static_packageType'}),
+}));
+
+vi.mock('./fields/createCarrierField', () => ({
+  createCarrierField: () => ({name: '__static_carrier'}),
+}));
+
+vi.mock('./fields/createDeliveryTypeField', () => ({
+  createDeliveryTypeField: () => ({name: '__static_deliveryType'}),
+}));
+
+vi.mock('./fields/createShipmentOptionField', () => ({
+  createShipmentOptionField: (_refs: unknown, name: string) => ({name}),
+}));
+
+vi.mock('./fieldFactoryRegistry', () => ({
+  fieldFactoryRegistry: {},
+}));
+
+const mockedUseContext = vi.mocked(useContext);
+
+const dynamicOptionKeys = (form: unknown): string[] => {
+  const fields = (form as {fields: {name: string}[]}).fields;
+  const prefix = `${FIELD_SHIPMENT_OPTIONS_PREFIX}.`;
+
+  return fields.filter((f) => f.name.startsWith(prefix)).map((f) => f.name.slice(prefix.length));
+};
+
+describe('createShipmentOptionsForm — dynamic option fields from carrier context', () => {
+  beforeEach(() => {
+    mockedUseContext.mockReset();
+  });
+
+  it('creates a field for the union of option keys across carriers', () => {
+    mockedUseContext.mockReturnValue({
+      carriers: [
+        {options: {signature: {}, insurance: {}}},
+        {options: {insurance: {}, ageCheck: {}}},
+      ],
+    } as never);
+
+    const form = createShipmentOptionsForm();
+
+    expect(dynamicOptionKeys(form).sort()).toEqual(['ageCheck', 'insurance', 'signature']);
+  });
+
+  it('does not throw when a carrier has no options field', () => {
+    mockedUseContext.mockReturnValue({carriers: [{}]} as never);
+
+    expect(() => createShipmentOptionsForm()).not.toThrow();
+    expect(dynamicOptionKeys(createShipmentOptionsForm())).toEqual([]);
+  });
+
+  it('does not throw when options is explicitly null', () => {
+    mockedUseContext.mockReturnValue({carriers: [{options: null}]} as never);
+
+    expect(() => createShipmentOptionsForm()).not.toThrow();
+  });
+
+  it('skips carriers without options but still collects keys from siblings', () => {
+    mockedUseContext.mockReturnValue({
+      carriers: [
+        {options: {signature: {}}},
+        {},
+        {options: null},
+        {options: {ageCheck: {}}},
+      ],
+    } as never);
+
+    expect(dynamicOptionKeys(createShipmentOptionsForm()).sort()).toEqual(['ageCheck', 'signature']);
+  });
+
+  it('produces no dynamic option fields for an empty carrier list', () => {
+    mockedUseContext.mockReturnValue({carriers: []} as never);
+
+    expect(dynamicOptionKeys(createShipmentOptionsForm())).toEqual([]);
+  });
+});