feat: Add bind function to simulate @bind directive

[linkdotnet]

Pull request description

Addresses and fixes #747

If the design is okay with you I would update the documentation and all necessary documents.

PR meta checklist

• Pull request is targeted at main branch for code
  or targeted at stable branch for documentation that is live on bunit.dev.
• Pull request is linked to all related issues, if any.
• I have read the CONTRIBUTING.md document.

Code PR specific checklist

• My code follows the code style of this project and AspNetCore coding guidelines.
• My change requires a change to the documentation.
  • I have updated the documentation accordingly.
• I have updated the appropriate sub section in the CHANGELOG.md.
• I have added, updated or removed tests to according to my changes.
  • All tests passed.

[linkdotnet]

I went ahead and added the documentation and stuff. So from my side everything is set and done.
Let me know your thoughts.

[egil]

Thanks Steven. This is a good start!

I have added some suggestions in this review and played around with the code locally. There are some rough edges that needs sanding here, code docs needs to be more precise, and we have to make sure we handle edge cases where users do something unexpected. E.g. what if the user choses the ValueChanged property instead of the Value property in the parameterSelector.

A thing I would like us to get better at is writing good error/exception messages in more places, like we do with the missing JSInterop setup messages, that basically tells the user what is wrong, and what to do about it. The last part is a game changer for people, and should help them get things working more easily. The changes in this PR could be the first place in the component parameter builder we start doing that.

[linkdotnet]

I added a very verbose way for the user in terms of the inline-documentation plus the exception. Let me know if the direction fits for you.

[egil]

pushed a few suggestions. let me know what you think

[linkdotnet]

pushed a few suggestions. let me know what you think

Thanks for the better documentation. Seeing the code right now I am still unsure whether or not a chapter in the documentation is more helpful to a certain degree.

Let's assume a user uses Bind inside a EditForm where the ValueExpression is mandatory. Now we give him the opportunity to not pass anything to it, which will lead to a default on our side ("binding" it to initalValue). In the real world this should be bound to the property in the Model-DTO, which is not necessarily the initialValue the user passes in.
I am not 100% sure if this can lead to extremely hard debug able tests.
Are users aware of that fact in the first place?

Guess I'll add some "e2e" tests

[linkdotnet]

Guess I'll add some "e2e" tests

After rethinking that, that should not be a problem as initially thought. The only thing is when someone derived from EditForm and implements its own logic, which is highly unliekly.

Anyway I pushed a small change which replaces string.Replace with something like a TrimEnd.
If we have something like that:

public class MyComponent : ComponentBase
{
    [Parameter] public DateTime LastChanged { get; set; }
    [Parameter] public EventCallback<DateTime> LastChangedChanged { get; set; }
}

And the user binds to the wrong property: p => p.Bind(v => v.LastChangedChanged, ...) the helptext in the exception should not tell v => v.Last but v => v.LastChanged. Hope that makes sense.
Do you normally test the message of an exception?

[egil]

Guess I'll add some "e2e" tests

After rethinking that, that should not be a problem as initially thought. The only thing is when someone derived from EditForm and implements its own logic, which is highly unliekly.

It's always good to have a few "e2e" tests that uses the Bind method against a real component and checks that we have the expected values in the component.

Perhaps compared to how the @bind directive does it, e.g. we should see the same values passed into the component under test.

Basically render the same component twice using both methods, and then compare the properties to each other. They should be the same.

In a .razor test file, this can be done from the same test.

Anyway I pushed a small change which replaces string.Replace with something like a TrimEnd.
If we have something like that:

public class MyComponent : ComponentBase
{
    [Parameter] public DateTime LastChanged { get; set; }
    [Parameter] public EventCallback<DateTime> LastChangedChanged { get; set; }
}

And the user binds to the wrong property: p => p.Bind(v => v.LastChangedChanged, ...) the helptext in the exception should not tell v => v.Last but v => v.LastChanged. Hope that makes sense.
Do you normally test the message of an exception?

I don't normally test the content of the error message, but do inspect it manually. It seems too unstable. But in certain cases a "contains" check makes sense.

[linkdotnet]

I added an e2e test. The original idea was to compare against ctx.Render(@<MyComponent @bind-Value=".." but that doesn't work for the reasons given in #761.

[linkdotnet]

I added an e2e test which tests the expected behavior from an user point of view. If you see open points, let me know

[egil]

I pushed some changes, but dont have time to make the test pass.

The bunit.web.testcomponents project and related test project is deprecated and just kept around for those users who still has a dependency on it, but we should not add new stuff to it.

However, there is nothing wrong with chaning bunit.core.test and bunit.web.test into razor project types so we can write tests in .razor files in them. Thats what I changed in the latest commit.

[linkdotnet]

I pushed some changes, but dont have time to make the test pass.

The bunit.web.testcomponents project and related test project is deprecated and just kept around for those users who still has a dependency on it, but we should not add new stuff to it.

However, there is nothing wrong with chaning bunit.core.test and bunit.web.test into razor project types so we can write tests in .razor files in them. Thats what I changed in the latest commit.

Okay. Will check that later including the CHANGELOG.md thingy. Unfortunately not so much time right now

[egil]

Going on an extended weekend thing, but will hopefully have time tomorrow. But yeah, we're not in a rush with this, so better get it right than fast.

[linkdotnet]

I pushed some changes, but dont have time to make the test pass.

The bunit.web.testcomponents project and related test project is deprecated and just kept around for those users who still has a dependency on it, but we should not add new stuff to it.

However, there is nothing wrong with chaning bunit.core.test and bunit.web.test into razor project types so we can write tests in .razor files in them. Thats what I changed in the latest commit.

Seems like you fixed it. Nice one ;)

[egil]

I think this is done. What do you think?

(this should be a squash merge)

[linkdotnet]

I think this is done. What do you think?

(this should be a squash merge)

Looks good to me. Thanks for updating