[amplify-libraries][Flutter] Document copyWithModelFieldValues for null fields

[AzazelSensei]

Description of changes:

Flutter copyWith on generated models treats a null argument as "keep the current value", so it cannot clear a nullable field. The generated copyWithModelFieldValues API does that via ModelFieldValue.value(null).

Added that to the Flutter DataStore update snippet and the GraphQL mutate example.

Related GitHub issue #, if available:

aws-amplify/amplify-flutter#5019

Instructions

Which product(s) are affected by this PR (if applicable)?

• amplify-cli
• amplify-ui
• amplify-studio
• amplify-hosting
• amplify-libraries

Which platform(s) are affected by this PR (if applicable)?

• JS
• Swift
• Android
• Flutter
• React Native

Checks

• Does this PR conform to the styleguide?

• Does this PR include filetypes other than markdown or images? Please add or update unit tests accordingly.

• Are any files being deleted with this PR? If so, have the needed redirects been created?

• Are all links in MDX files using the MDX link syntax rather than HTML link syntax?

When this PR is ready to merge, please check the box below

• Ready to merge

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[cadivus]

Hi @AzazelSensei,
thanks for your PR! I have two comments about it.

[cadivus]

Your PR covers gen 1 only. Do you want to apply the changes for gen 2 as well?

• https://github.com/AzazelSensei/docs/blob/72cdeb75ae55350bc0cd6be6167fa5e9c8b212ac/src/pages/%5Bplatform%5D/frontend/data/mutate-data/index.mdx
• https://github.com/AzazelSensei/docs/blob/72cdeb75ae55350bc0cd6be6167fa5e9c8b212ac/src/pages/%5Bplatform%5D/build-a-backend/data/mutate-data/index.mdx

[AzazelSensei]

Applied the Callout and oldPost/newPost on the DataStore snippet, and added the same copyWithModelFieldValues note on the gen 2 Flutter mutate pages.

[cadivus]

Hi @AzazelSensei,
thanks for the fixes! I found two more things when I had a second look:

• https://github.com/AzazelSensei/docs/blob/38c84cb4e2605a24cdbd9675a64a861622255e23/src/pages/%5Bplatform%5D/build-a-backend/data/data-modeling/relationships/index.mdx?plain=1#L266
• https://github.com/AzazelSensei/docs/blob/38c84cb4e2605a24cdbd9675a64a861622255e23/src/pages/%5Bplatform%5D/build-a-backend/data/data-modeling/relationships/index.mdx?plain=1#L690

Don't we have the second problem here? If so, I think

final memberWithRemovedTeam = existingMember.copyWith(team: null);
final memberRemoveRequest = ModelMutations.update(memberWithRemovedTeam);
final memberRemoveResponse = await Amplify.API.mutate(request: memberRemoveRequest).response;

should be

final memberWithRemovedTeam = existingMember.copyWithModelFieldValues(
  teamId: ModelFieldValue.value(null),
);
final memberRemoveRequest = ModelMutations.update(memberWithRemovedTeam);
final memberRemoveResponse = await Amplify.API.mutate(request: memberRemoveRequest).response;

and similar.

final cartWithRemovedCustomer = existingCart.copyWith(customer: null);
final cartRemoveRequest = ModelMutations.update(cartWithRemovedCustomer);
final cartRemoveResponse = await Amplify.API.mutate(request: cartRemoveRequest).response;

should be.

final cartWithRemovedCustomer = existingCart.copyWithModelFieldValues(
  customerId: ModelFieldValue.value(null),
);
final cartRemoveRequest = ModelMutations.update(cartWithRemovedCustomer);
final cartRemoveResponse = await Amplify.API.mutate(request: cartRemoveRequest).response;

[AzazelSensei]

Updated the two Flutter belongs-to unlink examples to copyWithModelFieldValues with ModelFieldValue.value(null).