docs(custom-esbuild): align the HTML transformer signature

[arturovt]

Closes #1690

[just-jeb]

Not sure if it actually closes #1690 - it does align the docs with actual implementation but from what I read there is a request for adding options (similarly to custom-webpack builder).

[arturovt]

We can align the docs for now and then I’ll think on implementing options as a feature.

[just-jeb]

Sure thing, just saying that aligning the docs won't close #1690 🙂

[arturovt]

However, how do we include target options as the first parameter when the HTML transformer is called by Angular with only the HTML content? We are not responsible for its invocation with only a single parameter.

// angular-cli
return indexHtmlTransformer && content ? await indexHtmlTransformer(content) : content;

We can certainly make adjustments on our end, but I'm hesitant to modify the contract exposed by their API. If they didn't include target options for this builder, there might be a specific reason for it.

The target options only include target and configuration properties. Here, target can be either build or server, while configuration can be development, production, or any other value.

In this builder, the target is typically always set to build, as the application builder inherently possesses conjunctive functionality.

Which means the only property may be used is the configuration.

I can talk to one of the Angular CLI team members who worked on the application builder to understand the exact reasons for its removal. I'm not sure if they gonna decide to bring it back.

[shisukei]

@arturovt I'm not sure if this is ideal, but from what I've seen, at the post-bundle time, if there is an index transformation function specified, then this function is called with the index content as a parameter.

Considering that the context is available in buildCustomEsbuildApplication (or in executeCustomDevServerBuilder), wouldn't it be acceptable to wrap this in a custom function? For instance, if we take the current code of this file, we would replace line 30 with something like this:
return { codePlugins, indexHtmlTransformer: (indexHtml) => indexHtmlTransformer(context, indexHtml) } as ApplicationBuilderExtensions;

Not sure, but it seems to be a similar approach with custom-webpack (source code).

[just-jeb]

@arturovt Exactly what @shisukei said, we can create a wrapper function and use the target params from the closure, just like we do in custom-webpack.