Add library removal confirmation to service edit form (PP-2408) (#170)

## Description

- Adds support for allowing/disallowing the disassociation of a library
from a service integration via the `ServiceEditForm` and its child
components. The check is performed synchronously, in real time, when
removal is requested via UI interaction.
- Adds documentation to help avoid accidental misuse of the
`ServiceEditForm.removeLibrary` method.

The mechanism separates (1) the function of removing a library
association from (2) the function of approving that removal.

The default behavior is to allow disassociation. Subclasses of
`ServiceEditForm` may override this behavior.

## Motivation and Context

This capability enables future real-time verification that a removal is
allowed or intended (e.g., via confirmation dialog).

[Jira PP-2408]

## How Has This Been Tested?

- New and updated tests.
- All tests pass locally.
- [CI
tests](https://github.com/ThePalaceProject/circulation-admin/actions/runs/17103293415)
passed.

## Checklist:

- [x] - I have updated the documentation accordingly.
- [x] All new and existing tests passed.

Author: tdilauro

src/components/ServiceEditForm.tsx

@@ -10,7 +10,6 @@ import {
   ProtocolData,
   ServiceData,
   ServicesData,
-  SettingData,
 } from "../interfaces";
 import { clearForm } from "../utils/sharedFunctions";
 import { FetchErrorData } from "@thepalaceproject/web-opds-client/lib/interfaces";
@@ -27,6 +26,7 @@ export interface ServiceEditFormProps<T> {
   extraFormSection?: any;
   extraFormKey?: string;
   adminLevel?: number;
+  libraryRemovalAllowed?: (library: LibraryWithSettingsData) => boolean;
 }
 
 export interface ServiceEditFormState {
@@ -345,6 +345,7 @@ export default class ServiceEditForm<
               <WithRemoveButton
                 disabled={disabled}
                 onRemove={() => this.removeLibrary(library)}
+                confirmRemoval={() => this.isLibraryRemovalPermitted(library)}
                 ref={library.short_name}
               >
                 {this.props.data &&
@@ -588,6 +589,31 @@ export default class ServiceEditForm<
     return this.state.expandedLibraries.indexOf(library.short_name) !== -1;
   }
 
+  /**
+   * Controls whether library associations may be removed via UI interaction.
+   * Subclasses may override this method to control removal.
+   * @param library The library to remove.
+   */
+  isLibraryRemovalPermitted(library: LibraryWithSettingsData): boolean {
+    // library should be provided on every call.
+    // It is not used here, but might be in subclass implementations.
+    // Removal is permitted by default.
+    return true;
+  }
+
+  /**
+   * Removes the association with the given library from a service's state.
+   *
+   * NB: This method is used indirectly via `onRemove` by `sharedFunctions.clearForm`
+   * to clean up form state; therefore, care should be taken to avoid any side
+   * effects not needed for updating the state. Anything done by this method
+   * can happen whenever user interaction or `clearForm` triggers `onRemove`.
+   *
+   * Update or override `isLibraryRemovalPermitted` to control library removal
+   * via UI interaction.
+   *
+   * @param library
+   */
   removeLibrary(library) {
     const libraries = this.state.libraries.filter(
       (stateLibrary) => stateLibrary.short_name !== library.short_name

src/components/WithRemoveButton.tsx

@@ -5,6 +5,7 @@ import TrashIcon from "./icons/TrashIcon";
 export interface WithRemoveButtonProps {
   disabled: boolean;
   onRemove: () => void;
+  confirmRemoval?: () => boolean;
 }
 
 /** When wrapped around an element, renders a remove button next to the element. */
@@ -37,6 +38,12 @@ export default class WithRemoveButton extends React.Component<
 
   onClick(e: Event) {
     e.preventDefault();
+
+    // Don't remove if confirmation function is present and returns false.
+    if (this.props.confirmRemoval && !this.props.confirmRemoval()) {
+      return;
+    }
+    // Otherwise, we can proceed with removal.
     !this.props.disabled && this.props.onRemove();
   }
 }

src/components/__tests__/ServiceEditForm-test.tsx

@@ -1009,4 +1009,79 @@ describe("ServiceEditForm", () => {
       expect(nameInput.props().value).to.equal("new service");
     });
   });
+
+  describe("library removal confirmation", () => {
+    let serviceEditFormInstance;
+    let isLibraryRemovalPermittedSpy;
+    let removeLibrarySpy;
+
+    beforeEach(() => {
+      save = stub().returns(new Promise<void>((resolve) => resolve()));
+      wrapper = mount(
+        <TestServiceEditForm
+          disabled={false}
+          data={servicesData}
+          save={save}
+          item={serviceData}
+          urlBase={urlBase}
+          listDataKey="services"
+        />
+      );
+      serviceEditFormInstance = wrapper.instance();
+      removeLibrarySpy = spy(serviceEditFormInstance, "removeLibrary");
+    });
+
+    afterEach(() => {
+      isLibraryRemovalPermittedSpy.restore();
+      removeLibrarySpy.restore();
+    });
+
+    const shouldRemoveLibrary = () => {
+      const libraryToRemove = serviceData.libraries[0];
+      const removeButton = wrapper.find(WithRemoveButton).at(0).find("button.remove-btn");
+
+      removeButton.simulate("click");
+
+      expect(isLibraryRemovalPermittedSpy.calledOnce).to.be.true;
+      expect(isLibraryRemovalPermittedSpy.calledWith(libraryToRemove)).to.be.true;
+      expect(isLibraryRemovalPermittedSpy.returned(true)).to.be.true;
+
+      // Library removal should be performed.
+      expect(removeLibrarySpy.calledOnce).to.be.true;
+      expect(removeLibrarySpy.calledWith(libraryToRemove)).to.be.true;
+
+      // Ensure that the library was removed from state.
+      wrapper.update();
+      expect(wrapper.state("libraries")).to.deep.equal([]);
+    };
+
+    it("should allow removal by default", () => {
+      isLibraryRemovalPermittedSpy = spy(serviceEditFormInstance, "isLibraryRemovalPermitted");
+      shouldRemoveLibrary();
+    });
+
+    it("should allow remove if isLibraryRemovalPermitted returns true", () => {
+      isLibraryRemovalPermittedSpy = stub(serviceEditFormInstance, "isLibraryRemovalPermitted").returns(true);
+      shouldRemoveLibrary();
+    });
+
+    it("should not allow remove if isLibraryRemovalPermitted returns false", () => {
+      isLibraryRemovalPermittedSpy = stub(serviceEditFormInstance, "isLibraryRemovalPermitted").returns(false);
+      const libraryToRemove = serviceData.libraries[0];
+      const removeButton = wrapper.find(WithRemoveButton).at(0).find("button.remove-btn");
+
+      removeButton.simulate("click");
+
+      expect(isLibraryRemovalPermittedSpy.calledOnce).to.be.true;
+      expect(isLibraryRemovalPermittedSpy.calledWith(libraryToRemove)).to.be.true;
+      expect(isLibraryRemovalPermittedSpy.returned(false)).to.be.true;
+
+      // Library disassociation should NOT be performed.
+      expect(removeLibrarySpy.notCalled).to.be.true;
+
+      // Ensure that the library was NOT removed from state.
+      wrapper.update();
+      expect(wrapper.state("libraries")).to.deep.equal(serviceData.libraries);
+    });
+  });
 });

src/components/__tests__/WithRemoveButton-test.tsx

@@ -43,5 +43,27 @@ describe("WithRemoveButton", () => {
       removeBtn.simulate("click");
       expect(onRemove.callCount).to.equal(0);
     });
+
+    it("calls onRemove when confirmation returns true", () => {
+      const confirmRemoval = stub().returns(true);
+      wrapper.setProps({ confirmRemoval });
+      const removeBtn = wrapper.find(".remove-btn").hostNodes();
+
+      removeBtn.simulate("click");
+
+      expect(confirmRemoval.callCount).to.equal(1);
+      expect(onRemove.callCount).to.equal(1);
+    });
+
+    it("does not call onRemove when confirmation returns false", () => {
+      const confirmRemoval = stub().returns(false);
+      wrapper.setProps({ confirmRemoval });
+      const removeBtn = wrapper.find(".remove-btn").hostNodes();
+
+      removeBtn.simulate("click");
+
+      expect(confirmRemoval.callCount).to.equal(1);
+      expect(onRemove.callCount).to.equal(0);
+    });
   });
 });