fix(core)!: changed the order expected from open

[dk949]

This is inline with documentation and the way diff expects it's return
values.

This is a breaking change, however, I think it will mostly affect hooks,
not the core functionality. Namely this will change the value passed for
winnr to post_open and may cause block_end to not be called.

This also only people who were using open as a function, rather than a
string, and have already swapped the two values.

Also updated type of files in README. This is not a breaking change as using the argument as a string[] will have resulted in an error.

[willothy]

First of all thanks for the PR! Sorry it took me so long to get to this, I've been super busy with work and haven't had much time for nvim. Really appreciate the docs fix, but before I merge is there a reason you want to change the order of the return values from open()? I'd like to avoid breaking existing configs unless this is super important.

[dk949]

Hi 👋

It's a little hard to remember now exactly why I did this 😅 but I think the logic was:

1. Flatten.OpenHandler is (or was at the time) documented to return window, buffer?
2. Making the second value the optional one makes function more ergonomic to write and call (you are able to bind only one value in return and in assignment)
3. The diff callback already expects this order, so this makes the API more consistent

Here is an example of how I have been using this : https://github.com/dk949/nvim/blob/new-config/lua/config/plugins/flatten.lua#L32-L48