Custom Components API

[chancancode]

rendered

[knownasilya]

What can the component instance be? Just Ember.Component or can it be a web component/dom node?

[chancancode]

Do you mean the component instance or the comtext object?

The component instance is for your own internal use, so it could be anything. It's whatever you returned from create.

The comtext object is the template context (what {{this}} resolves to). It could also be any object. (Technically it can be a dom node but it won't do what you want.)

[chancancode]

You can already render a DOM node today. e.g. if a helper or property lookup returns a DOM node, it already works

[knownasilya]

The component instance is for your own internal use, so it could be anything. It's whatever you returned from create.

Not sure I understand the reasoning behind returning anything.

[chancancode]

The reason is to hide internal book-keeping information from your users. For example, Ember does something like this today:

class CurlyComponentManager {
  create(definition, args) {
    let { factory } = definition.meta;

    return factory.create({
      ...args.named,
      [INTERNAL_STUFF]: foo,
      [DEFINITELY_PRIVATE_API]: bar,
      [YOU_ARE_NOT_SUPPOSED_TO_TOUCH_THIS]: baz,
      [OH_GOD_PLEASE_DEFINITELY_DONT_CHANGE_THIS]: bat
    });
  }

  getContext(component) {
    return component;
  }

  // ...
}

This works, but we are stashing a lot of internal stuff on the Ember.Component instance.

It would be better to do this instead:

class CurlyComponentManager {
  create(definition, args) {
    let { factory } = definition.meta;

    let component = factory.create(args.named);

    let metadata = {
      [INTERNAL_STUFF]: foo,
      [DEFINITELY_PRIVATE_API]: bar,
      [YOU_ARE_NOT_SUPPOSED_TO_TOUCH_THIS]: baz,
      [OH_GOD_PLEASE_DEFINITELY_DONT_CHANGE_THIS]: bat
    });

    return { component, metadata };
  }

  getContext({ component }) {
    return component;
  }

  // ...
}

This way, you won't leak the internals to your users.

[tragiclifestories]

Typo ("manger" -> "manager")

[chancancode]

Fixed!

[tragiclifestories]

There's a couple more of those mangers lying around. Festive 🎄

[GavinJoyce]

typo: if on one of

[tim-evans]

Typo; meatadata 🍖

[MiguelMadero]

Shouldn't this return entry instead of instance?

[joukevandermaas]

I have a question on the scope of this RFC. Given the announcements at EmberConf, I sort of assume that the Glimmer/Ember integration can use this RFC as a building block. However, from the text in this RFC it appears that the layout/template of a component is an opaque thing, while Glimmer components also introduce new template syntax/semantics:

• using @ to mark component parameters vs. DOM attributes
• using angle-bracket syntax to invoke components
• maybe more(?)

Is supporting that kind of semantics change in scope of this RFC? If so, how would I do something like that?

[locks]

I have a question on the scope of this RFC. Given the announcements at EmberConf, I sort of assume that the Glimmer/Ember integration can use this RFC as a building block.

That's exactly what this is ;) I think Tom and Yehuda mentioned in the keynote that the more successful experimentations in the Ember ecosystem came by providing primitives from which third-parties can build on, namely fastboot and engines.

This RFC is the primitive that will unlock the possibility of using different kinds of components, one of them is angle bracket components, whose details you mention will likely be discussed in a follow-up RFC. You will notice that Glimmer.js components are very barebones at the moment, partially due to this.

[NLincoln]

Would it be out of scope for this RFC to support changes to how components are rendered?

For example, say I have a google maps component that works like this:

{{#google-map as |map|}}
  {{#map.marker as |marker|}}
    {{#marker.info-window}}
      This is rendered in the markers info window
    {{/marker.info-window}}
  {{/map.marker}}
{{/google-map}}

Currently the info window content is rendered into the DOM, and then google maps moves the element into its own internal structure. elements for markers, etc are also rendered. It would be amazing if there was a way to control how the element is inserted into the DOM, possibly like this?

class MapsComponentManager {
  render(/* dom, element: HTMLElement */) {
    // no-op since we don't want these rendered
  }
}

// components/google-map/info-window.js
Ember.Component.extend({
  didInsertElement() {
    this._super(...arguments);
    // despite the component not being directly rendered, it's element 
    // is still available as a property on the component itself as usual
    assert(this.element);
  }
});

The render api could also be exposed on components instead of component managers instead.

[MiguelMadero]

@chancancode this looks super useful and I like the idea of providing the primitives and to allow experimentation outside of ember core. However, while in this case, I think the primitives look right, is only once we start building on top of those that we realize if they work or not. I think we may need some time to experiment with this a throw a few different use cases to them before solidifying this or "committing" to an API. I'm mainly thinking of my use case for ember-cli-hot-loader, but I think the same would apply to liquid-fire and angle brackets...
What do you think?

How could we get a "POC" of this or something on the alpha channel to start playing? Is there something we could help with?

[twokul]

First pass on registering custom component manager landed in Ember (emberjs/ember.js#15254) and allows one to do the following:

{{use-component-manager "nyan-cat"}}

{{nyan-cat}}

where {{nyan-cat}} component management (parsing arguments, (re)rendering, destruction) is going to be deferred to nyan-cat component manager. This should work both for classic and module unification layouts resolvable under component-managers/nyan-cat.

[knownasilya]

Is there a glimmer component manager yet?

[rwjblue]

Yes

[knownasilya]

I'm assuming this has to be imported manually to work, and isn't included in ember yet.

[rwjblue]

Yep, the only thing landed in ember (behind a feature flag that is disabled by default) is the ability to specify a custom manager.

[knownasilya]

Great 👍 So you can also use curly components in a glimmerjs app?

[auvipy]

sorry for noise, just curious if there is any further development on this?

[chancancode]

Hello everyone! Sorry for the delay. We had some new breakthroughs at the December core team face-to-face meeting. I updated the RFC to reflect the new development and this should be ready for another round of review, and hopefully FCP soon.

CHANGELOG:

✂️ typescript
✂️ component definitions
✂️ other overly abstract stuff
✂️ ember inspector stuff (seems like we can just do it automatically)
✂️ open/unresolved questions
✔️ #embraceTheObjectModel
➕ added nwe typos

You can read the current version here. The previous version is still available here, for reference.

[rwjblue]

I love the update! Thanks for putting so much time into it!

I left a number of inline comments / questions, but I had additional question that didn't really fit in a specific section:

• In the Capabilities section, we describe a future where these capabilities can and will be iterated, but do not mention how that iteration will happen. Is it safe to assume any changes (new capabilities, optional flags, etc) will be made via this same RFC process? How will these capabilities be discoverable? API docs only? Do we anticipate guides?

[rwjblue]

s/in the apps/in apps/?

[rwjblue]

s/core features/core feature/

[rwjblue]

s/mode/model/ (I think)

[rwjblue]

This should suggest re-exporting in its app/ tree (where the "real" implementation is in its own addon/ tree), and it should also describe what this looks like in module unification layouts.

[rwjblue]

I think I would prefer the actual class to be the second argument, and that the return value from the helper function must be used (e.g. we should not guarantee a mutation based solution). This in practice gives us much more flexibility (we could subclass to "stamp" the object, if we wanted to).

With those changes, folks could do the following:

export default setComponentManager('awesome', EmberObject.extend({
  // ...snip...
})

[rwjblue]

How do we expect addon authors to manage their Ember version support with the capabilities section? We do not provide a way for them to provide the same manager with varying compatibility, do they then need to do build time work to ensure to only ship the manager actually needed by the host app?

[rwjblue]

/featuers/features/

[rwjblue]

s/clearify/clarify/

[rwjblue]

s/Flex's "sustain"/flexi-sustain/

[rwjblue]

I don't think this is good enough. We need to maintain a canonical list of capabilities that are supported (and any options that were allowed with each).

[chancancode]

I think I have addressed all the feedback so far!

[chancancode]

I updated the RFC to add some details about the support policy of component manager APIs

[rwjblue]

This was discussed in todays core team call, and with the last round of updates we are happy to get this moved into final comment period.

Please take a 🆕 👀 .....

[chancancode]

I would like to point out that this is not intended to be the ultimate API that solves every use case. Rather, this is the MVP of the framework that allows adding extensions that would solve those use cases. So I would appreciate feedback to focus on whether that framework is flexible enough to eventually support the use case you have in mind, rather than whether it is sufficient to support that today as proposed.

[runspired]

I think to avoid confusion we should remove the theoretical flexi-sustain implementation from the RFC as its not an adequate implementation.

I chatted with @chancancode a bit this morning about the current state of this RFC and have no objections to it; however, I do want to document that while it hopes to be a primitive upon which things such as flexi-sustain could be built, additional RFCs would be needed on top of this MVP.

[chancancode]

I updated it to remove the mention

[RobbieTheWagner]

I'd love to see some support for flexi-sustain and similiar things, but I realize it might be out of scope here.

[rtm]

"descendants"

[wycats]

Since 12 days have passed with no additional unaddressed comments, I'm going to merge this RFC.