fix: Clear search form when resource type changes

Previously only invalid parameter names were cleared. Now all filter
and parameter rows reset to their initial empty state, avoiding
confusion from stale search criteria.

Author: johngrimes

openspec/changes/archive/2026-02-16-clear-search-form-on-resource-type-change/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-16

openspec/changes/archive/2026-02-16-clear-search-form-on-resource-type-change/design.md

@@ -0,0 +1,36 @@
+## Context
+
+The `ResourceSearchForm` component maintains local state for the selected
+resource type, FHIRPath filter rows, and search parameter rows. When the user
+changes the resource type, a `useEffect` hook detects the change and removes any
+parameter selections that are no longer valid for the new type. However, it
+leaves parameter values and FHIRPath filter expressions intact, which creates a
+confusing experience.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Reset all filter rows and parameter rows to their initial empty state when the
+  resource type changes.
+
+**Non-Goals:**
+
+- Persisting search state across resource type changes (e.g. remembering filters
+  per type).
+- Changing the initial default state of the form.
+
+## Decisions
+
+Replace the existing `useEffect` that selectively clears invalid parameters with
+a simpler reset that returns filters and parameter rows to their initial state
+(one empty row each). This is simpler than the current logic and matches user
+expectations — switching resource type is a fresh search context.
+
+The `idCounter` ref should also be reset so that IDs restart cleanly.
+
+## Risks / Trade-offs
+
+- Users who intentionally share filter expressions across resource types will
+  need to re-enter them. This is an acceptable trade-off given the confusion
+  caused by stale values.

openspec/changes/archive/2026-02-16-clear-search-form-on-resource-type-change/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+When the user changes the resource type on the resources page, the search
+parameter rows and FHIRPath filter expressions remain populated with values from
+the previous resource type. This is confusing because those values are likely
+irrelevant to the new resource type, and the user must manually clear them
+before entering new search criteria.
+
+## What Changes
+
+- Reset all search parameter rows (name and value) to a single empty row when
+  the resource type changes.
+- Reset all FHIRPath filter rows to a single empty row when the resource type
+  changes.
+
+## Capabilities
+
+### New Capabilities
+
+(none)
+
+### Modified Capabilities
+
+- `search-parameter-form`: The form currently only clears invalid parameter
+  names on resource type change. The new behaviour fully resets all form fields
+  (parameter rows and filter rows) to their initial empty state.
+
+## Impact
+
+- `ui/src/components/resources/ResourceSearchForm.tsx` - The resource type
+  change handler needs to reset filters and parameter rows instead of selectively
+  clearing invalid parameters.

openspec/changes/archive/2026-02-16-clear-search-form-on-resource-type-change/specs/search-parameter-form/spec.md

@@ -0,0 +1,28 @@
+## MODIFIED Requirements
+
+### Requirement: Parameter dropdown populated by resource type
+
+The parameter name dropdown in each search parameter row SHALL display the
+search parameters available for the currently selected resource type, as
+extracted from the CapabilityStatement. Each option SHALL show the parameter
+name, with the parameter type displayed as a badge next to it.
+
+#### Scenario: Parameter list updates on resource type change
+
+- **WHEN** the user changes the selected resource type from Patient to
+  Observation
+- **THEN** the parameter dropdown options SHALL update to show search parameters
+  declared for Observation, and all search parameter rows SHALL be reset to a
+  single empty row
+
+#### Scenario: No search parameters available
+
+- **WHEN** the selected resource type has no declared search parameters
+- **THEN** the parameter dropdown SHALL be empty and display placeholder text
+  indicating no parameters are available
+
+#### Scenario: FHIRPath filters reset on resource type change
+
+- **WHEN** the user has entered FHIRPath filter expressions and then changes the
+  selected resource type
+- **THEN** all FHIRPath filter rows SHALL be reset to a single empty row

openspec/changes/archive/2026-02-16-clear-search-form-on-resource-type-change/tasks.md

@@ -0,0 +1,15 @@
+## 1. Tests
+
+- [x] 1.1 Write tests verifying that changing the resource type resets search
+      parameter rows to a single empty row
+- [x] 1.2 Write tests verifying that changing the resource type resets FHIRPath
+      filter rows to a single empty row
+
+## 2. Implementation
+
+- [x] 2.1 Replace the selective parameter-clearing useEffect with a full form
+      reset (filters and parameter rows) on resource type change
+
+## 3. Verification
+
+- [x] 3.1 Run the full UI test suite and verify all tests pass

openspec/specs/search-parameter-form/spec.md

@@ -65,15 +65,21 @@ name, with the parameter type displayed as a badge next to it.
 - **WHEN** the user changes the selected resource type from Patient to
   Observation
 - **THEN** the parameter dropdown options SHALL update to show search parameters
-  declared for Observation, and any previously selected parameters that are not
-  valid for Observation SHALL be cleared
+  declared for Observation, and all search parameter rows SHALL be reset to a
+  single empty row
 
 #### Scenario: No search parameters available
 
 - **WHEN** the selected resource type has no declared search parameters
 - **THEN** the parameter dropdown SHALL be empty and display placeholder text
   indicating no parameters are available
 
+#### Scenario: FHIRPath filters reset on resource type change
+
+- **WHEN** the user has entered FHIRPath filter expressions and then changes the
+  selected resource type
+- **THEN** all FHIRPath filter rows SHALL be reset to a single empty row
+
 ### Requirement: Search parameters included in search request
 
 When the user submits the search form, any search parameter rows with both a

ui/src/components/resources/ResourceSearchForm.tsx

@@ -88,19 +88,14 @@ export function ResourceSearchForm({
   // Available search parameters for the currently selected resource type.
   const availableParams = searchParams?.[resourceType] ?? [];
 
-  // Track previous resource type to clear invalid selections on change.
+  // Reset all form fields when the resource type changes, since the previous
+  // search criteria are unlikely to be relevant to the new type.
   const prevResourceType = useRef(resourceType);
   if (prevResourceType.current !== resourceType) {
     prevResourceType.current = resourceType;
-    const validNames = new Set(availableParams.map((p) => p.name));
-    const needsClear = paramRows.some((row) => row.paramName && !validNames.has(row.paramName));
-    if (needsClear) {
-      setParamRows(
-        paramRows.map((row) =>
-          row.paramName && !validNames.has(row.paramName) ? { ...row, paramName: "" } : row,
-        ),
-      );
-    }
+    idCounter.current = 1;
+    setFilters([{ id: 0, expression: "" }]);
+    setParamRows([{ id: 0, paramName: "", value: "" }]);
   }
 
   const handleSubmit = () => {

ui/src/components/resources/__tests__/ResourceSearchForm.test.tsx

@@ -674,7 +674,7 @@ describe("ResourceSearchForm", () => {
       expect(screen.queryByRole("option", { name: /gender/i })).not.toBeInTheDocument();
     });
 
-    it("clears selected parameter when resource type changes and selection is invalid", async () => {
+    it("resets parameter rows to a single empty row when resource type changes", async () => {
       const user = userEvent.setup();
       render(
         <ResourceSearchForm
@@ -686,19 +686,63 @@ describe("ResourceSearchForm", () => {
         />,
       );
 
-      // Select "gender" parameter for Patient.
+      // Select "gender" parameter for Patient and enter a value.
       const paramDropdown = screen.getAllByRole("combobox")[1];
       await user.click(paramDropdown);
       await user.click(screen.getByRole("option", { name: /gender/i }));
+      const valueInput = screen.getByPlaceholderText(/e\.g\., male/i);
+      await user.type(valueInput, "male");
 
-      // Change resource type to Observation (which doesn't have "gender").
+      // Add a second parameter row.
+      await user.click(screen.getByRole("button", { name: /add parameter/i }));
+      expect(screen.getAllByPlaceholderText(/e\.g\., male/i)).toHaveLength(2);
+
+      // Change resource type to Observation.
       const resourceTypeCombobox = screen.getAllByRole("combobox")[0];
       await user.click(resourceTypeCombobox);
       await user.click(screen.getByRole("option", { name: "Observation" }));
 
-      // The parameter dropdown should no longer show "gender".
+      // Should be back to a single empty parameter row.
+      const valueInputs = screen.getAllByPlaceholderText(/e\.g\., male/i);
+      expect(valueInputs).toHaveLength(1);
+      expect(valueInputs[0]).toHaveValue("");
+
+      // The parameter dropdown should be cleared (no selection).
       const updatedParamDropdown = screen.getAllByRole("combobox")[1];
-      expect(updatedParamDropdown).not.toHaveTextContent("gender");
+      expect(updatedParamDropdown).toHaveTextContent("Select parameter...");
+    });
+
+    it("resets FHIRPath filter rows to a single empty row when resource type changes", async () => {
+      const user = userEvent.setup();
+      render(
+        <ResourceSearchForm
+          onSubmit={mockOnSubmit}
+          isLoading={false}
+          disabled={false}
+          resourceTypes={defaultResourceTypes}
+          searchParams={mockSearchParams}
+        />,
+      );
+
+      // Enter a FHIRPath filter expression.
+      const filterInput = screen.getByPlaceholderText(/gender = 'female'/i);
+      await user.type(filterInput, "active = true");
+
+      // Add a second filter row and fill it in.
+      await user.click(screen.getByRole("button", { name: /add filter/i }));
+      const filterInputs = screen.getAllByPlaceholderText(/gender = 'female'/i);
+      expect(filterInputs).toHaveLength(2);
+      await user.type(filterInputs[1], "gender = 'male'");
+
+      // Change resource type to Observation.
+      const resourceTypeCombobox = screen.getAllByRole("combobox")[0];
+      await user.click(resourceTypeCombobox);
+      await user.click(screen.getByRole("option", { name: "Observation" }));
+
+      // Should be back to a single empty filter row.
+      const updatedFilterInputs = screen.getAllByPlaceholderText(/gender = 'female'/i);
+      expect(updatedFilterInputs).toHaveLength(1);
+      expect(updatedFilterInputs[0]).toHaveValue("");
     });
 
     it("displays help text for search parameters section", () => {