@myparcel-dev/pdk-admin 1.14.2 → 2.0.1

package/src/forms/shipmentOptions/fields/createShipmentOptionField.spec.ts

@@ -0,0 +1,177 @@
+import {describe, expect, it, vi} from 'vitest';
+import {ref} from 'vue';
+import {TriState} from '@myparcel-dev/pdk-common';
+import {type InteractiveElementInstance} from '@myparcel-dev/vue-form-builder';
+import {createShipmentOptionField} from './createShipmentOptionField';
+
+/**
+ * Mutable carrier context — tests set this to control what the bag's `getCarrierCapabilitiesForShipment`
+ * and `hasShipmentOption` return without needing per-test mock overrides.
+ */
+let mockCarrier: Record<string, unknown> | undefined;
+
+// Full mock (no importOriginal) to avoid the Vue file import chain
+// that triggers "Install @vitejs/plugin-vue" errors.
+vi.mock('../../helpers', () => ({
+  resolveFormComponent: () => 'MockTriStateInput',
+  defineFormField: (config: Record<string, unknown>) => config,
+  getFieldLabel: (name: string) => name,
+  useFormCapabilities: () => ({
+    getCarrierCapabilitiesForShipment: () => mockCarrier,
+    getCarrierCapabilitiesForOrder: () => mockCarrier,
+    hasShipmentOption: (_form: unknown, option: string) => {
+      return Object.hasOwn((mockCarrier?.options as Record<string, unknown>) ?? {}, option);
+    },
+    getInsuranceOptions: () => [],
+  }),
+}));
+
+/** Create a minimal mock field instance with a reactive ref and mutable props. */
+const createMockField = (name: string, fieldValue = TriState.Inherit) => {
+  return {
+    name,
+    ref: ref(fieldValue),
+    form: {} as never,
+    props: {readOnly: false, disabled: false},
+  } as unknown as InteractiveElementInstance;
+};
+
+/** Create a mock form that resolves fields by name from the given list. */
+const createMockForm = (fields: InteractiveElementInstance[]) => {
+  return {
+    getField: (name: string) => fields.find((f) => f.name === name),
+    getValue: () => undefined,
+  };
+};
+
+describe('createShipmentOptionField', () => {
+  const createRefs = (fieldName: string, value?: unknown) => ({[fieldName]: value});
+
+  it('creates a field with TriState.Inherit default', () => {
+    const fieldName = 'deliveryOptions.shipmentOptions.testOption';
+    const refs = createRefs(fieldName);
+
+    const field = createShipmentOptionField(refs, fieldName);
+
+    expect(field.name).toBe(fieldName);
+  });
+
+  describe('afterUpdate dependency logic', () => {
+    /**
+     * Helper that sets up a POSTNL carrier with `requires` / `excludes` declared on the
+     * `requiresAgeVerification` option (mirroring what the live capabilities response carries),
+     * the dependent fields, and a triggerAfterUpdate to invoke the just-toggled age-check field.
+     *
+     * The `requires` / `excludes` rules live directly on the option entry in the carrier model
+     * — sourced from the shipment-scoped capabilities response on the live path.
+     *
+     * @param optionOverrides - per-option overrides merged into the default carrier options
+     *   (e.g. `{ requiresSignature: { isRequired: true } }`)
+     */
+    const setupAgeVerificationScenario = (optionOverrides: Record<string, Record<string, unknown>> = {}) => {
+      const defaultOptions: Record<string, Record<string, unknown>> = {
+        requiresAgeVerification: {
+          isRequired: false,
+          isSelectedByDefault: false,
+          requires: ['recipientOnlyDelivery', 'requiresSignature'],
+          excludes: ['requiresReceiptCode'],
+        },
+        requiresSignature: {isRequired: false, isSelectedByDefault: false},
+        recipientOnlyDelivery: {isRequired: false, isSelectedByDefault: false},
+        requiresReceiptCode: {isRequired: false, isSelectedByDefault: false},
+      };
+
+      mockCarrier = {
+        carrier: 'POSTNL',
+        options: {...defaultOptions, ...optionOverrides},
+      };
+
+      const signatureField = createMockField('deliveryOptions.shipmentOptions.requiresSignature');
+      const onlyRecipientField = createMockField('deliveryOptions.shipmentOptions.recipientOnlyDelivery');
+      const receiptCodeField = createMockField('deliveryOptions.shipmentOptions.requiresReceiptCode');
+      const form = createMockForm([signatureField, onlyRecipientField, receiptCodeField]);
+
+      const fieldName = 'deliveryOptions.shipmentOptions.requiresAgeVerification';
+      const config = createShipmentOptionField(createRefs(fieldName), fieldName);
+
+      const triggerAfterUpdate = (value: TriState) => {
+        const ageCheckField = {
+          ...createMockField(fieldName, value),
+          form,
+        } as unknown as InteractiveElementInstance;
+
+        config.afterUpdate!(ageCheckField, value, undefined);
+      };
+
+      return {signatureField, onlyRecipientField, receiptCodeField, triggerAfterUpdate};
+    };
+
+    // Enabling 18+ check should force signature + only-recipient ON and lock them.
+    it('forces required-dependency fields ON and readOnly when source is enabled', () => {
+      const {signatureField, onlyRecipientField, triggerAfterUpdate} = setupAgeVerificationScenario();
+
+      triggerAfterUpdate(TriState.On);
+
+      expect(signatureField.ref.value).toBe(TriState.On);
+      expect(signatureField.props.readOnly).toBe(true);
+      expect(onlyRecipientField.ref.value).toBe(TriState.On);
+      expect(onlyRecipientField.props.readOnly).toBe(true);
+    });
+
+    // Enabling 18+ check should force receipt code OFF and lock it.
+    it('forces excluded-dependency fields OFF and readOnly when source is enabled', () => {
+      const {receiptCodeField, triggerAfterUpdate} = setupAgeVerificationScenario();
+
+      triggerAfterUpdate(TriState.On);
+
+      expect(receiptCodeField.ref.value).toBe(TriState.Off);
+      expect(receiptCodeField.props.readOnly).toBe(true);
+    });
+
+    // Disabling 18+ check should unlock dependent fields so the user can edit them again.
+    it('clears readOnly on dependent fields when source is disabled', () => {
+      const {signatureField, onlyRecipientField, receiptCodeField, triggerAfterUpdate} =
+        setupAgeVerificationScenario();
+
+      // First enable to lock the fields…
+      triggerAfterUpdate(TriState.On);
+      // …then disable to unlock them.
+      triggerAfterUpdate(TriState.Off);
+
+      expect(signatureField.props.readOnly).toBe(false);
+      expect(onlyRecipientField.props.readOnly).toBe(false);
+      expect(receiptCodeField.props.readOnly).toBe(false);
+    });
+
+    // When the carrier independently requires an option (isRequired: true), disabling the
+    // dependency source must NOT clear that field's readOnly or change its value. Regression:
+    // previously, turning off 18+ check would blindly set readOnly = false on all dependents,
+    // overriding the carrier's isRequired lock.
+    it('preserves readOnly and value on carrier-required fields when dependency source is disabled', () => {
+      const {signatureField, onlyRecipientField, receiptCodeField, triggerAfterUpdate} =
+        setupAgeVerificationScenario({
+          // Signature is independently required by the carrier
+          requiresSignature: {isRequired: true, isSelectedByDefault: false},
+        });
+
+      // First enable to lock all dependent fields…
+      triggerAfterUpdate(TriState.On);
+
+      // Verify signature was forced ON by the dependency.
+      expect(signatureField.ref.value).toBe(TriState.On);
+      expect(signatureField.props.readOnly).toBe(true);
+
+      // …then disable — signature should stay locked and ON, others should unlock.
+      triggerAfterUpdate(TriState.Off);
+
+      // Signature must remain ON and readOnly because the carrier requires it, regardless of
+      // the 18+ dependency being turned off.
+      expect(signatureField.ref.value).toBe(TriState.On);
+      expect(signatureField.props.readOnly).toBe(true);
+      // Only-recipient is not independently required, so it should unlock.
+      expect(onlyRecipientField.props.readOnly).toBe(false);
+      // Receipt code is an excluded dep, also not independently required.
+      expect(receiptCodeField.props.readOnly).toBe(false);
+    });
+  });
+});

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

@@ -1,25 +1,107 @@
-import {type Shipment, TriState} from '@myparcel-dev/pdk-common';
-import {type InteractiveElementConfiguration} from '@myparcel-dev/vue-form-builder';
+import {type InteractiveElementConfiguration, type InteractiveElementInstance} from '@myparcel-dev/vue-form-builder';
+import {TriState} from '@myparcel-dev/pdk-common';
 import {type ShipmentOptionsRefs} from '../types';
-import {type FieldName} from '../field';
-import {createHasShipmentOptionWatcher, defineFormField, getFieldLabel, resolveFormComponent} from '../../helpers';
+import {FIELD_SHIPMENT_OPTIONS_PREFIX} from '../field';
+import {defineFormField, getFieldLabel, resolveFormComponent, useFormCapabilities} from '../../helpers';
+import {setFieldRef} from '../../form-builder/utils/createValueSetter';
 import {AdminComponent} from '../../../data';
 import {createRef} from './createRef';
 
+/**
+ * Creates a generic shipment option field as a TriState toggle.
+ *
+ * Default factory for any option from `carrier.options` that doesn't have a custom factory in
+ * `fieldFactoryRegistry`. `requires` / `excludes` are sourced from the shipment-scoped
+ * response (`getCarrierCapabilitiesForShipment`); they're absent while the shipment query is loading or
+ * falling back to order-level data — locking doesn't run during those windows.
+ *
+ * `useFormCapabilities()` is called at factory invocation (setup-time) so visibility, disabled,
+ * readOnly and afterUpdate handlers close over a captured Pinia store + orderId — no
+ * `inject()` calls during form-builder's watchEffect-driven re-evaluators.
+ */
 export const createShipmentOptionField = (
   refs: ShipmentOptionsRefs,
-  fieldName: FieldName,
+  fieldName: string,
   config?: Partial<InteractiveElementConfiguration>,
 ): InteractiveElementConfiguration => {
-  const name = (fieldName.split('.').pop() ?? fieldName) as keyof Shipment.ModelShipmentOptions;
+  const name = fieldName.split('.').pop() ?? fieldName;
+  const capabilities = useFormCapabilities();
 
   return defineFormField({
     name: fieldName,
     component: resolveFormComponent(AdminComponent.TriStateInput),
     ref: createRef(refs, fieldName, TriState.Inherit),
     label: getFieldLabel(name),
-    visibleWhen: createHasShipmentOptionWatcher(name),
-    disabledWhen: createHasShipmentOptionWatcher(name, true),
+    visibleWhen: ({form}) => capabilities.hasShipmentOption(form, name),
+    // Disabled when the carrier doesn't support this option.
+    // Required options use readOnlyWhen instead, keeping them enabled
+    // so their value is included in the form body by getEnabledValues().
+    disabledWhen: ({form}) => !capabilities.hasShipmentOption(form, name),
+    // Read-only prevents the TriState "inherit" toggle from being used,
+    // fully locking the field when the carrier requires this option.
+    readOnlyWhen: ({form}) => {
+      return capabilities.getCarrierCapabilitiesForShipment(form)?.options?.[name]?.isRequired === true;
+    },
+
+    afterUpdate(field, value) {
+      const carrier = capabilities.getCarrierCapabilitiesForShipment(field.form);
+      const option = carrier?.options?.[name];
+
+      if (!option) {
+        return;
+      }
+
+      // Enforce isRequired: revert any user change back to TriState.On.
+      if (option.isRequired === true && value !== TriState.On) {
+        setFieldRef(field, TriState.On);
+
+        return;
+      }
+
+      const isEnabled = TriState.On === value;
+
+      for (const requiredOption of option.requires ?? []) {
+        const targetFieldName = `${FIELD_SHIPMENT_OPTIONS_PREFIX}.${requiredOption}`;
+        const targetField = field.form.getField(targetFieldName);
+
+        if (!targetField) {
+          continue;
+        }
+
+        if (isEnabled) {
+          setFieldRef(targetField as InteractiveElementInstance, TriState.On);
+          targetField.props.readOnly = true;
+        } else {
+          // Only clear readOnly if the carrier doesn't independently require this option.
+          const isRequiredByCarrier = carrier?.options?.[requiredOption]?.isRequired === true;
+
+          if (!isRequiredByCarrier) {
+            targetField.props.readOnly = false;
+          }
+        }
+      }
+
+      for (const excludedOption of option.excludes ?? []) {
+        const targetFieldName = `${FIELD_SHIPMENT_OPTIONS_PREFIX}.${excludedOption}`;
+        const targetField = field.form.getField(targetFieldName);
+
+        if (!targetField) {
+          continue;
+        }
+
+        if (isEnabled) {
+          setFieldRef(targetField as InteractiveElementInstance, TriState.Off);
+          targetField.props.readOnly = true;
+        } else {
+          const isRequiredByCarrier = carrier?.options?.[excludedOption]?.isRequired === true;
+
+          if (!isRequiredByCarrier) {
+            targetField.props.readOnly = false;
+          }
+        }
+      }
+    },
+
     ...config,
   });
 };

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

@@ -1,15 +1,6 @@
-export * from './createAgeCheckField';
-export * from './createCarrierField';
 export * from './createDigitalStampRangeField';
-export * from './createDirectReturnField';
 export * from './createInsuranceField';
 export * from './createLabelAmountField';
-export * from './createLargeFormatField';
-export * from './createOnlyRecipientField';
 export * from './createPackageTypeField';
-export * from './createPriorityDeliveryField';
 export * from './createRef';
-export * from './createSameDayDeliveryField';
 export * from './createShipmentOptionField';
-export * from './createSignatureField';
-export * from './createReceiptCodeField';

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

@@ -0,0 +1,347 @@
+import {describe, expect, it, vi, beforeEach} from 'vitest';
+import {effectScope, nextTick, ref, type Ref} from 'vue';
+import {BackendEndpoint, type CarrierModel, TriState} from '@myparcel-dev/pdk-common';
+import {FIELD_CARRIER, FIELD_DELIVERY_TYPE, FIELD_PACKAGE_TYPE, FIELD_SHIPMENT_OPTIONS_PREFIX} from './field';
+
+type FakeQuery = {
+  status: ReturnType<typeof ref<string>>;
+  data: ReturnType<typeof ref<unknown>>;
+};
+
+const queries = new Map<string, FakeQuery>();
+
+const queryStoreMock = {
+  has: (endpoint: BackendEndpoint, modifier: string) => queries.has(`${endpoint}.${modifier}`),
+  get: (endpoint: BackendEndpoint, modifier: string) =>
+    queries.get(`${endpoint}.${modifier}`) ?? {status: ref('idle'), data: ref(undefined)},
+};
+
+/**
+ * Create the shipment-query entry up front (in `loading` state) so the auto-clear's watcher
+ * sees a registered query at setup; subsequent state transitions mutate the same refs and
+ * are reactively visible to the watcher.
+ */
+const registerShipmentQuery = (orderId: string): FakeQuery => {
+  const entry: FakeQuery = {status: ref('loading'), data: ref(undefined)};
+
+  queries.set(`${BackendEndpoint.ProxyCapabilities}.${orderId}.shipment`, entry);
+
+  return entry;
+};
+
+const notificationStoreMock = {
+  add: vi.fn(),
+  remove: vi.fn(),
+};
+
+const translateMock = vi.fn((key: unknown) => {
+  if (typeof key === 'string') return key;
+  const k = (key as {key: string}).key;
+  const a = (key as {args?: Record<string, string>}).args;
+
+  return a ? `${k}(${Object.entries(a).map(([k2, v]) => `${k2}=${v}`).join(',')})` : k;
+});
+
+const getCarrierCapabilitiesForOrderMock = vi.fn();
+const addCapabilitiesClearNotificationMock = vi.fn();
+
+vi.mock('../../stores', () => ({
+  useQueryStore: () => queryStoreMock,
+  useNotificationStore: () => notificationStoreMock,
+}));
+
+vi.mock('../../composables', () => ({
+  useLanguage: () => ({translate: translateMock}),
+}));
+
+vi.mock('../helpers', () => ({
+  addCapabilitiesClearNotification: addCapabilitiesClearNotificationMock,
+  CAPABILITIES_CLEARED_NOTIFICATION_ID: 'capabilities_cleared',
+  useFormCapabilities: () => ({getCarrierCapabilitiesForOrder: getCarrierCapabilitiesForOrderMock}),
+}));
+
+const setFieldRefMock = vi.fn();
+
+vi.mock('../form-builder/utils/createValueSetter', () => ({
+  setFieldRef: setFieldRefMock,
+}));
+
+const buildForm = (initial: Record<string, unknown>) => {
+  const fieldByName = new Map<string, {name: string; ref: Ref<unknown>}>();
+
+  Object.keys(initial).forEach((name) => {
+    fieldByName.set(name, {name, ref: ref(initial[name])});
+  });
+
+  return {
+    // `state` proxies into each field's ref so test assertions read the same source the
+    // auto-clear is watching — `state[name]` reads `fieldByName.get(name).ref.value`.
+    state: new Proxy({} as Record<string, unknown>, {
+      get: (_, name: string) => fieldByName.get(name)?.ref.value,
+    }),
+    getValue: <T,>(name: string): T => fieldByName.get(name)?.ref.value as T,
+    getField: (name: string) => {
+      if (!fieldByName.has(name)) {
+        fieldByName.set(name, {name, ref: ref(undefined)});
+      }
+
+      return fieldByName.get(name);
+    },
+    setExternally: (name: string, value: unknown) => {
+      const field = fieldByName.get(name);
+
+      if (field) {
+        (field.ref as Ref<unknown>).value = value;
+      } else {
+        fieldByName.set(name, {name, ref: ref(value)});
+      }
+    },
+  };
+};
+
+beforeEach(() => {
+  queries.clear();
+  notificationStoreMock.add.mockClear();
+  notificationStoreMock.remove.mockClear();
+  translateMock.mockClear();
+  getCarrierCapabilitiesForOrderMock.mockReset();
+  addCapabilitiesClearNotificationMock.mockClear();
+  setFieldRefMock.mockReset();
+});
+
+const buildCarrier = (overrides: Partial<CarrierModel>): CarrierModel =>
+  ({
+    carrier: 'POSTNL',
+    packageTypes: [],
+    deliveryTypes: [],
+    options: {},
+    ...overrides,
+  }) as CarrierModel;
+
+/**
+ * Wire `setFieldRef` to mutate the form state so the auto-clear's silent rewrites surface
+ * via subsequent `form.getValue(...)` reads.
+ */
+const wireSetFieldRef = (form: ReturnType<typeof buildForm>) => {
+  setFieldRefMock.mockImplementation((field: {name: string}, value: unknown) => {
+    form.setExternally(field.name, value);
+  });
+};
+
+describe('useCapabilitiesAutoClear', () => {
+  it('on carrier change with shipment-empty: applies inherited defaults silently (no notification)', async () => {
+    const form = buildForm({
+      [FIELD_CARRIER]: 'DPD',
+      [FIELD_PACKAGE_TYPE]: 'PACKAGE',
+      [FIELD_DELIVERY_TYPE]: 'PICKUP',
+    });
+
+    wireSetFieldRef(form);
+    // Order-query "available carriers" — getCarrierCapabilitiesForOrder resolves through form.getValue(FIELD_CARRIER)
+    // so the order watcher sees fresh data for whichever carrier is currently selected.
+    const orderCarriers = [
+      buildCarrier({carrier: 'DPD', packageTypes: ['PACKAGE'], deliveryTypes: ['PICKUP']}),
+      buildCarrier({carrier: 'POSTNL', packageTypes: ['PACKAGE'], deliveryTypes: ['STANDARD']}),
+    ];
+
+    getCarrierCapabilitiesForOrderMock.mockImplementation((f: {getValue: (n: string) => unknown}) =>
+      orderCarriers.find((c) => c.carrier === f.getValue(FIELD_CARRIER)),
+    );
+    const shipmentEntry = registerShipmentQuery('order-1');
+
+    const selection = ref({carrier: 'DPD', packageType: 'PACKAGE', deliveryType: 'PICKUP'}) as Ref<{
+      carrier?: string;
+      packageType?: string;
+      deliveryType?: string;
+    }>;
+
+    const scope = effectScope();
+    const {useCapabilitiesAutoClear} = await import('./useCapabilitiesAutoClear');
+
+    scope.run(() => {
+      useCapabilitiesAutoClear(
+        form as never,
+        ['signature'],
+        'order-1',
+        {POSTNL: {packageType: 'PACKAGE', deliveryType: 'STANDARD'}} as never,
+        selection,
+      );
+    });
+
+    // User switches DPD → POSTNL; new combo not in shipment results.
+    form.setExternally(FIELD_CARRIER, 'POSTNL');
+    selection.value = {carrier: 'POSTNL', packageType: 'PACKAGE', deliveryType: 'PICKUP'};
+    shipmentEntry.status.value = 'success';
+    shipmentEntry.data.value = [];
+    await nextTick();
+
+    expect(form.state[FIELD_PACKAGE_TYPE]).toBe('PACKAGE');
+    expect(form.state[FIELD_DELIVERY_TYPE]).toBe('STANDARD');
+    expect(addCapabilitiesClearNotificationMock).not.toHaveBeenCalled();
+
+    scope.stop();
+  });
+
+  it('on packageType change with shipment-empty: reverts that axis to its prior value WITH notification', async () => {
+    const form = buildForm({
+      [FIELD_CARRIER]: 'POSTNL',
+      [FIELD_PACKAGE_TYPE]: 'PACKAGE',
+      [FIELD_DELIVERY_TYPE]: 'STANDARD',
+    });
+
+    wireSetFieldRef(form);
+    getCarrierCapabilitiesForOrderMock.mockReturnValue(
+      buildCarrier({carrier: 'POSTNL', packageTypes: ['PACKAGE', 'MAILBOX'], deliveryTypes: ['STANDARD']}),
+    );
+    const shipmentEntry = registerShipmentQuery('order-1');
+
+    const selection = ref({carrier: 'POSTNL', packageType: 'PACKAGE', deliveryType: 'STANDARD'}) as Ref<{
+      carrier?: string;
+      packageType?: string;
+      deliveryType?: string;
+    }>;
+
+    const scope = effectScope();
+    const {useCapabilitiesAutoClear} = await import('./useCapabilitiesAutoClear');
+
+    scope.run(() => {
+      useCapabilitiesAutoClear(form as never, ['signature'], 'order-1', {} as never, selection);
+    });
+
+    // User changes packageType to MAILBOX. Shipment query confirms invalid combo.
+    form.setExternally(FIELD_PACKAGE_TYPE, 'MAILBOX');
+    selection.value = {carrier: 'POSTNL', packageType: 'MAILBOX', deliveryType: 'STANDARD'};
+    shipmentEntry.status.value = 'success';
+    shipmentEntry.data.value = [];
+    await nextTick();
+
+    expect(form.state[FIELD_PACKAGE_TYPE]).toBe('PACKAGE');
+    expect(addCapabilitiesClearNotificationMock).toHaveBeenCalledTimes(1);
+
+    const lines = addCapabilitiesClearNotificationMock.mock.calls[0][2] as string[];
+
+    expect(lines[0]).toContain('capabilities_cleared_field_reverted');
+
+    scope.stop();
+  });
+
+  it('on packageType change with no prior valid value: clears the field and notifies cleared (not reverted)', async () => {
+    const form = buildForm({
+      [FIELD_CARRIER]: 'POSTNL',
+      [FIELD_PACKAGE_TYPE]: undefined,
+      [FIELD_DELIVERY_TYPE]: 'STANDARD',
+    });
+
+    wireSetFieldRef(form);
+    getCarrierCapabilitiesForOrderMock.mockReturnValue(
+      buildCarrier({carrier: 'POSTNL', packageTypes: ['MAILBOX'], deliveryTypes: ['STANDARD']}),
+    );
+    const shipmentEntry = registerShipmentQuery('order-1');
+
+    const selection = ref({carrier: 'POSTNL', packageType: undefined, deliveryType: 'STANDARD'}) as Ref<{
+      carrier?: string;
+      packageType?: string;
+      deliveryType?: string;
+    }>;
+
+    const scope = effectScope();
+    const {useCapabilitiesAutoClear} = await import('./useCapabilitiesAutoClear');
+
+    scope.run(() => {
+      useCapabilitiesAutoClear(form as never, [], 'order-1', {} as never, selection);
+    });
+
+    // First-ever packageType pick is MAILBOX → invalid combo, no prior valid value to revert to.
+    form.setExternally(FIELD_PACKAGE_TYPE, 'MAILBOX');
+    selection.value = {carrier: 'POSTNL', packageType: 'MAILBOX', deliveryType: 'STANDARD'};
+    shipmentEntry.status.value = 'success';
+    shipmentEntry.data.value = [];
+    await nextTick();
+
+    expect(form.state[FIELD_PACKAGE_TYPE]).toBeUndefined();
+    const lines = addCapabilitiesClearNotificationMock.mock.calls[0][2] as string[];
+
+    expect(lines[0]).toContain('capabilities_cleared_field_cleared');
+
+    scope.stop();
+  });
+
+  it('on shipment success+matched: clears orphaned active options silently when carrier changed', async () => {
+    const optionField = `${FIELD_SHIPMENT_OPTIONS_PREFIX}.signature`;
+    const form = buildForm({
+      [FIELD_CARRIER]: 'DPD',
+      [FIELD_PACKAGE_TYPE]: 'PACKAGE',
+      [FIELD_DELIVERY_TYPE]: 'PICKUP',
+      [optionField]: TriState.On,
+    });
+
+    wireSetFieldRef(form);
+    getCarrierCapabilitiesForOrderMock.mockReturnValue(buildCarrier({carrier: 'DPD'}));
+    const shipmentEntry = registerShipmentQuery('order-1');
+
+    const selection = ref({carrier: 'DPD', packageType: 'PACKAGE', deliveryType: 'PICKUP'}) as Ref<{
+      carrier?: string;
+      packageType?: string;
+      deliveryType?: string;
+    }>;
+
+    const scope = effectScope();
+    const {useCapabilitiesAutoClear} = await import('./useCapabilitiesAutoClear');
+
+    scope.run(() => {
+      useCapabilitiesAutoClear(form as never, ['signature'], 'order-1', {} as never, selection);
+    });
+
+    // User switches to POSTNL; shipment response success but POSTNL.options has no signature.
+    form.setExternally(FIELD_CARRIER, 'POSTNL');
+    selection.value = {carrier: 'POSTNL', packageType: 'PACKAGE', deliveryType: 'PICKUP'};
+    shipmentEntry.status.value = 'success';
+    shipmentEntry.data.value = [buildCarrier({carrier: 'POSTNL', options: {}})];
+    await nextTick();
+
+    expect(form.state[optionField]).toBe(TriState.Inherit);
+    // Silent — option clearing during a carrier change does not produce a notification.
+    expect(addCapabilitiesClearNotificationMock).not.toHaveBeenCalled();
+
+    scope.stop();
+  });
+
+  it('readShipmentSnapshot uses the debounced selection.carrier (not form.getValue) to avoid the race', async () => {
+    const form = buildForm({
+      [FIELD_CARRIER]: 'POSTNL',
+      [FIELD_PACKAGE_TYPE]: 'PACKAGE',
+      [FIELD_DELIVERY_TYPE]: 'STANDARD',
+    });
+
+    wireSetFieldRef(form);
+    getCarrierCapabilitiesForOrderMock.mockReturnValue(
+      buildCarrier({carrier: 'POSTNL', packageTypes: ['PACKAGE'], deliveryTypes: ['STANDARD']}),
+    );
+    const shipmentEntry = registerShipmentQuery('order-1');
+
+    // Form (live) is on POSTNL; debounced selection still on DPD; shipment results contain only DPD.
+    const selection = ref({carrier: 'DPD', packageType: 'PACKAGE', deliveryType: 'PICKUP'}) as Ref<{
+      carrier?: string;
+      packageType?: string;
+      deliveryType?: string;
+    }>;
+
+    const scope = effectScope();
+    const {useCapabilitiesAutoClear} = await import('./useCapabilitiesAutoClear');
+
+    scope.run(() => {
+      useCapabilitiesAutoClear(form as never, [], 'order-1', {} as never, selection);
+    });
+
+    shipmentEntry.status.value = 'success';
+    shipmentEntry.data.value = [buildCarrier({carrier: 'DPD', options: {}})];
+    await nextTick();
+
+    // Form's live POSTNL doesn't match DPD-only results, but the snapshot is computed against
+    // the debounced selection (DPD), which matches → state === 'matched', no rollback fires.
+    expect(addCapabilitiesClearNotificationMock).not.toHaveBeenCalled();
+    expect(form.state[FIELD_PACKAGE_TYPE]).toBe('PACKAGE');
+
+    scope.stop();
+  });
+});