Enhance contextual-components & helpers

[cibernox]

I found myself in need of a way of creating something similar to contextual components but instead of creating a component and curry arguments, I wanted to do the same with a helper.

After drafting an RFC, checking previous art of the subject and chat about it on slack I realized that the matter is a bit more complicated that I naively thought at first.

I want to push this forward on an RFC but I want to write this issue first so we can list the motivation an requirement that the RFC has to consider.

Motivation

Essentially the same motivation that anyone would have to desire contextual components:

• Dynamically invoke a helper by its name
• Wrap a helper with some arguments and options and pass/yield it so when finally invoked on a different context the developer only has to provide missing information or overrides.
• Allows to hide complexity from the public API of helpers.
• Once privately-scoped components/helpers are implemented as defined in Module Unification #143, it allows to expose those private components in a controlled way.

The naive idea that wouldn't work, and why

It seemed obvious that if we have a {{component}} keyword that allows to dynamically invoke components by its name and also to wrap components and attribututes into an ComponentDefinition, the only feature we need is a symmetrical {{helper}} keyword that does
the same thing with helpers.

You can read this thread in discuss, but the basic problem with this idea is:

• While it is easy to disambiguate when the {{component}} helper is used to invoke a component and when it's used to create a contextual component, given the "eager" nature of helpers, there is no way of know the intention of the user. Example:

{{my-component 
  closeButton=(component "x-button" onClick=(action "close"))
  formatDate=(helper "moment-format" "Do MMM [at] H:MM" locale="es-ES")}}

The closeButton attribute is clearly creating a closure component with an onClick option bundling it together in a ComponentDefinition that can later on be rendered providing extra elements.

The (helper "moment-format") part is not clear tho. The intention of the user is to invoke the moment-format helper with the given arguments or is instead creating a contextual helper and pass it to my-component?

There is no way of telling what the user wants to do with helpers using a single keyword like {{component}}. We'd need a different syntax to disambiguate.

Constraints and other relevant information for the solution

Listed here without any particular order.

• It must disambiguate "helper/component invocation" from "helper/component wrapping".
• Currying of arguments must work as with closure actions: Invocation of a closure helper appends arguments at the end.
• Options are merged as with Object.assign. Options passed in invocation win over those the component/helper has closed over.
• The distinction of components/helpers is fuzzy for some people, specially for those with react background, because it reminds a lot to functional components. Is it possible that both are going to converge with glimmer-components? If so, this feature should be designed with that in mind, and the keywords should be the same for helpers and components.
• As an addition argument for the previous point, in the new Module Unification (Module Unification #143), both helpers and components are conflated under the components collection (if that is the correct term). This reinforces my idea that the keywords for wrap/invoke components/helper should be the same.
• Support for glimmer-components. Although the exact API has not been spec'ed yet, initial strawman seems to take ver seriously the distinction between attributes and properties. The syntax of this RFC should take that into account)
• I don't know this first hand, but I've been told that there is some fundamental incompatibility between the way glimmer-components are going to work and the way the existing {{component}} helper works that would require a new approach anyway. I'm not sure if that fundamental problem is the one I mentioned in the previous point or there is more to the story.
• Element Modifiers: I know little-to-nothing about them apart that they exist in @mixonic's mind. How can they affect this proposal? Can they also be wrapped/invoked?
• Is this a feature that can be spiked into an addon? My guts say "probably not".
• There was some conversation about making the {{component}} keyword be statically analysable. Perhaps it's not relevant for this RFC, but it worth mentioning it.

The action plan, teaching issues and such would be discussed in an eventual RFC.

Pinging people that might want to read this: @mixonic @Serabe @locks

[cibernox]

From the previous requirements I conclude that if we want to handle components and helpers with the same syntax, we need two keywords.

The name is not very important at this point, but let's pretend the keywords are invoke-component and wrap-component.

We know that it has to support glimmer components. The syntax of glimmer components is, according to the last rumours, going to have @foo= values for properties and foo= for attributes, so those helpers should respect that syntax.

Aternative 1: curly-braces syntax for components and helpers

The idea is that the helpers receive the first argument, determine if it's a component or a helper and pass the arguments as received, which means that
arguments with an @ sign become properties in the component instance and those without @ become properties.

Invocation:

{{#invoke-component "my-button" class="btn btn-success" @loadingMessage="Wait please ..."}}
  Submit!
{{/invoke-component}}
{{!-- equivalent to <my-button class="btn btn-success" @loadingMessage="Wait please ...">Submit!</my-button> --}}

{{invoke-component "moment-format" today "YYYY-MM-DD" locale="fr"}}
{{!-- equivalent to {{moment-format today "YYYY-MM-DD" locale="fr"}} --}}

{{invoke-component "my-component" title=(invoke-component "moment-format" date)}}
{{!-- equivalent to <my-component class={{moment-format date}}>Submit!</my-component> --}}

Contextual components/helpers creation:

<my-form class="my-form" @submitBtn={{wrap-component "x-button" class="btn btn-success" @loadingMsg="Please wait..."}}></my-form>

{{!-- Later on, inside the my-form.hbs template --}}
{{invoke-component submitBtn @anotherAttr="foo" aria-hidden="true"}}

<my-calendar @format-date={{wrap-component "moment-format" locale="fr" format="YYYY-MM-DD"}}></my-calendar>
{{!-- Later on, inside the my-calendar.hbs template --}}
Today is {{invoke-component format-date today}} and tomorrow is {{invoke-component format-date tomorrow}}

Shorthand invocation of contextual glimmer-components:

{{!-- my-form.hbs --}}
{{yield hash=(
  format-created-at=(wrap-component "moment-format" model.createdAt)
  cancel-btn=(wrap-component "form-button" class="btn-warning" @onClick=(action "cancel"))
  submit-btn=(wrap-component "form-button" class="btn-sucess" @onClick=(action "submit"))
)}}

<my-form @model={{model}} as |f|>
  <p>This moment was created at {{f.format-created-at "YYYY-MM-DD"}}</p> {{!-- Invoke a helper --}}
  <f::cancel-button>Abort</f::cancel-button>
  <f::submit-button>Save</f::submit-button>
</my-form>

[Serabe]

I am all in favor of adding this feature since it would allow to create better public APIs for components like the ones in the ember-power family.

One option to avoid the wrap Vs. invoke helpers might be to restrict it to the dot syntax: if a property path resolves to either a component or a helper, it would be just rendered as such.

I would need to know more about current implementation of contextual components, since last time I checked (July? August?) it was partially coded as an special case. Maybe @zackthehuman can help a bit here.

I'm all in for investigating this further. Great work, @mixonic!

[cibernox]

@Serabe What do you mean to restrict it to the dot syntax? With components is easy, but components are eager, so {{my-foo format-today=(helper "moment-format" today)}} is ambiguous in the sense that you don't know if you want to wrap the helper to later on invoke it with {{format-today}} or you want to call it inmmedialtly and use the generated value in JS-land.

[rwjblue]

This was replaced by #432 which is merged, and awaiting implementation. Closing this issue in favor of tracking the progress of that RFC.