Documentation Should Include x-bind caveat for x-spread

[alexstandiford]

Thanks so much for your work on Alpine. I've really enjoyed using it so-far!

In the docs, this is mentioned for x-for:

When the directive being "spread" is x-for, you should return a normal expression string from the callback. For example: 'x-for' { return 'item in items' }.

However it appears that this also applies to x-bind:, as well.

// Won't work.
{
	['x-bind:value']() { this.value },
}

// Will work
{
	['x-bind:value']() { return this.value },
}

I'm unsure if this is an error on my part, a part of a bigger problem, or if it's simply something that should be specified in the docs. Either way, I only figured it out by sheer luck.

Here's the error that crops up when return is not included in the callback:

Uncaught TypeError: expression.match is not a function

It appears to happen in handleAttributeBindingDirective on this line:

      if (value === undefined && expression.match(/\./)) {

[HugoDF]

This is a JavaScript issue mostly, if you don't return anything, then there's no output

We might want to handle the failure more gracefully + like you said docs, what would you have expected in the docs?

[alexstandiford]

I think maybe some kind of caveat that makes it clear that returning something is sometimes necessary, and a warning in the console that notifies a function that expected to return something, returned nothing would be really helpful.

[HugoDF]

Yeah, I think the fact you're calling it a caveat is part of the issue. In the majority of cases (exception being event handlers) you're expected to return something. Any idea how we would make that clear?

a warning in the console that notifies a function that expected to return something, returned nothing

the problem with this is that null/undefined/other "nothing" values might be valid outputs 🤔 it really depends if that part of the code expects an expression (which would have to be a string) or a value (in which case I'm not sure how we would do the check), I'll let others chime in and have a look at the code.

[SimoTod]

The latest version shouldn't throw the error. However, this is just going to hide the real problem which is the fact that your code doesn't return anything so it translates to x-bind:value with no value.

Generally speaking, you are always suppose to return something when using spread, the same value you would write in the directive using plain HTML.
E.g. x-text="foo" translateto'x-text' { return 'foo' }`

If you don't return anything, you'll probably see empty tags where you are expecting a value.

[alexstandiford]

For me the confusion stemmed from the example in the documentation does not show a return statement, where in most cases a return statement would be necessary. I understand that a return statement isn't necessary in the example, and get why, but it still tripped me up.
https://github.com/alpinejs/alpine#x-spread

Maybe the update is as simple as providing a different, or additional example that uses a return statement?

There's plenty of scenarios in Alpine where you don't explicitly use the return keyword in the x- syntax for directives, and I didn't expect to need to use return. It makes perfect sense that you should use return, and I get that, but my point is that Alpine sometimes breaks that expectation in other places and it wasn't clear to me that I should use return here.

So yeah, I get that it's not a "caveat", but I do think, at least in the context of Alpine, it does muddle expectations and would benefit from being a bit more explicit in the docs.

[SimoTod]

In the same example, a few lines below, it uses return for x-show.
I understand the confusion anyway, maybe a rewording of the paragraph would help.

[alexstandiford]

Yeah, actually that's how I was able to figure it out. I noticed that used a return statement, but the wording makes the behavior sound specific to x-for.