[QUEST] Glimmer Components in Ember

This quest issue tracks the implementation of Glimmer components in Ember.js.

The Plan

Glimmer.js components have the following features:

1. “Outer HTML” templates (no tagName, attributeBindings, etc.)
2. Arguments in templates are @ prefixed, like {{@firstName}}
3. Arguments are set on the component as this.args
4. Component classes use JavaScript class syntax
5. Mutable component state is annotated with @tracked properties
6. Components are invoked via <AngleBracket /> syntax
7. Attributes can be “splatted” via …attributes

In keeping with Ember’s spirit of incrementalism, we want to land this functionality piece by piece via an addon. This allows the community to start using features and providing feedback early in the process.

In fact, we’ve already started down the road to Glimmer components in Ember. The first two features have already started to land:

1. In template-only components, templates are “outer HTML” (assuming the template-only-glimmer-components optional feature has been enabled.)
2. Arguments can be accessed in the template via the @ prefix (e.g. {{@firstName}}).

This issue proposes finishing the process of bringing Glimmer components to Ember by allowing addons to provide alternate component implementations, then transforming the @glimmer/component package into an Ember addon that implements the Glimmer.js component API.

We’ll break that work into phases, each one unlocking benefits for existing Ember apps and addons. Phase 0 is about adding the necessary primitives to Ember.js to support alternate component implementations. Phases 1, 2 and 3 are about incrementally enabling Glimmer.js component API.

While we go into depth on Phases 0 and 1, we will defer exploring the technical details of later phases until the first phases are closer to completion.

Phase 0: Customizing Component Behavior

TL;DR: Add a CustomComponentManager API to Ember.js to allow addons to implement custom component API.

Currently, all components in an Ember app are assumed to be subclasses of Ember.Component. In order to support alternate component APIs in Ember, we need some way to tell Ember when and how component behavior should change.

When we say “custom component behavior,” we specifically mean:

1. How component instances are created.
2. How component instances are destroyed.
3. How arguments are provided to the component instance.
4. How the component is notified of these lifecycle changes.

While Glimmer VM introduces the concept of a “component manager,” an object that makes these decisions, this API is very low level. It would be premature to adopt them directly as public API in Ember because they are difficult to write, easy to author in a way that breaks other components, and not yet stable.

Instead, we propose a new Ember API called CustomComponentManager that implements a delegate pattern. The CustomComponentManager provides a smaller API surface area than the full-fledged ComponentManager Glimmer VM API, which allows addon authors to fall into a “pit of success.”

So how does Ember know which component manager to use for a given component? The original iteration of the Custom Components RFC introduced the concept of a ComponentDefinition, a data structure that was eagerly registered with Ember and specified which component manager to use.

One of the major benefits of the ComponentDefinition approach is that component manager resolution can happen at build time. Unfortunately, that means we have to design an API for exactly how these get registered, and likely means some sort of integration with the build pipeline.

Instead, we propose an API for setting a component’s manager at runtime via an annotation on the component class. This incremental step allows work on custom component managers to continue while a longer term solution is designed.

Custom Component Manager Discovery

In this iteration, components must explicitly opt-in to alternate component managers. They do this via a special componentManager function, exported by Ember, that annotates at runtime which component manager should be used for a particular component class:

import { componentManager } from '@ember/custom-component-manager';
import EmberObject from '@ember/object';
    
export default componentManager(EmberObject.extend({
  // ...
}), 'glimmer');

Eventually, this could become a class decorator:

import { componentManager } from '@ember/custom-component-manager';
    
export default @componentManager('glimmer') class {
  // ...
}

The first time this component is invoked, Ember inspects the class to see if it has a custom component manager annotation. If so, it uses the string value to perform a lookup on the container. In the example above, Ember would ask the container for the object with the container key component-manager:glimmer.

Addons can thus use normal resolution semantics to provide custom component managers. Our Glimmer component addon can export a component manager from addon/component-managers/glimmer.js that will get automatically discovered through normal resolution rules.

While this API is verbose and not particularly ergonomic, apps and addons can abstract it away by introducing their own base class with the annotation. For example, if an addon called turbo-component wanted to provide a custom component manager, it could export a base class like this:

// addon/index.js
import EmberObject from '@ember/object';
import { componentManager } from '@ember/custom-component-manager';

export default componentManager(EmberObject.extend({
  // ...
}), 'turbo');

Users of this addon could subclass the TurboComponent base class to define components that use the correct component manager:

import TurboComponent from 'turbo-component';

export default TurboComponent.extend({
  didInsertElementQuickly() {
    // ...
  }
});

Custom Component API

No component is an island, and for backwards compatibility reasons, it’s important that the introduction of new component API don’t break existing components.

One example of this is the existing view hierarchy API. Ember components can inspect their parent component via the parentView property. Even if the parent is not an Ember.Component, the child Ember components should still have a non-null parentView property.

Currently, the CurlyComponentManager in Ember is responsible for maintaining this state, as well as other ambient “scope state” like the target of actions.

To prevent poorly implemented component managers from violating invariants in the existing system, we use a compositional pattern to customize behavior while hiding the sharp corners of the underlying API.

import CustomComponentManager from "@ember/custom-component-manager";

export default new CustomComponentManager({
  // major and minor Ember version this manager targets
  version: "3.1",
  create({ ComponentClass, args }) {
    // Responsible for instantiating the component class and passing provided
    // component arguments.
    // The value returned here is passed as `component` in the below hooks.
  },
  getContext(component) {
    // Returns the object that serves as the root scope of the component template.
    // Most implementations should return `component`, so the component's properties
    // are looked up in curly expressions.
  },
  update(component, args) {
    // Called whenever the arguments to a component change.
  },
  destroy(component) {
  }
});

Phase 1: Ember Object Glimmer Components

The Component base class in Ember supports a long list of features, many of which are no longer heavily used. These features can impose a performance cost, even when they are unused.

As a first step, we want to provide a way to opt in to the simplified Glimmer.js component API via the @glimmer/component package. To ease migration, we will provide an implementation of the Glimmer Component base class that inherits from Ember.Object at @glimmer/component/compat.

Here’s an example of what an “Ember-Glimmer component” looks like:

// src/ui/components/user-profile/component.js
import Component from '@glimmer/component/compat';
import { computed } from '@ember/object';

export default Component({
  fullName: computed('args.firstName', 'args.lastName', function() {
    let { firstName, lastName } = this.args
    return `${firstName} ${lastName}`;
  })
  
  isAdmin: false,
  
  toggleAdmin() {
    this.set('isAdmin', !this.isAdmin);
  }
});

{{!-- src/ui/components/user-profile/template.hbs --}}
<h1>{{fullName}}</h1>
<p>
  Welcome back, {{@firstName}}!
  {{#if isAdmin}}
    <strong>You are an admin.</strong>
  {{/if}}
</p>
<button {{action toggleAdmin}}>Toggle Admin Status</button>

Notable characteristics of these components:

• Templates are outer HTML. Because the example template above does not have a single root element, this renders as a “tagless component”.
• Actions are just functions on the component and don’t need to be nested in the actions hash.
• Arguments are set on the args property rather than setting individual properties on the component directly.
• They use the Ember object model. This means tools like computed properties and mixins that Ember developers are already familiar with continue to work.

Just as important is what is not included:

• @tracked properties will not be supported until Phase 3.
• No layout or template properties on the component.
• No methods or properties relating to the view hierarchy, such as childViews, parentView, nearestWithProperty, etc.
• No tagName, attributeBindings, or other custom JavaScript DSL for modifying the root element.
• No send or sendAction for dispatching events.
• No mandatory ember-view class or auto-generated guid element ID.
• No manual rerender() method.
• No attrs property (use args instead).
• Passed arguments are “unidirectional” and don’t create two-way bindings.
• Passed arguments are not set as properties on the component instance, avoiding the possibility of hard-to-debug naming collisions.
• No this.$() to create a jQuery object for the component element.
• No manual appendTo of components into the DOM.
• No support for the following lifecycle events:
  • willInsertElement
  • didRender
  • willRender
  • willClearRender
  • willUpdate
  • didReceiveAttrs
  • didUpdateAttrs
  • parentViewDidChange
• No on() event listener for component lifecycle events; hooks must be implemented as methods.

One interesting side effect of this set of features is that it dovetails with the effort to enable JavaScript classes. In conjunction with the design proposed in the ES Classes RFC, we can provide an alternate implementation of the above component:

// src/ui/components/user-profile/component.js
import Component from '@glimmer/component/compat';
import { computed } from 'ember-decorators/object';

export default class extends Component {
  isAdmin = false;

  @computed('args.firstName', 'args.lastName')
  get fullName() {
    let { firstName, lastName } = this.args;
    return `${firstName} ${lastName}`;
  })

  toggleAdmin() {
    this.set('isAdmin', !this.isAdmin);
  }
});

Phase 2 - Angle Bracket Syntax

Phase 2 enables invoking components via angle brackets (<UserAvatar @user={{currentUser}} />) in addition to curlies ({{my-component user=currentUser}}). Because this syntax disambiguates between component arguments and HTML attributes, this feature also enables “splatting” passed attributes into the component template via …attributes.

{{! src/ui/components/UserAvatar/template.hbs }}
<div ...attributes> {{! <-- attributes will be inserted here }}
  <h1>Hello, {{@firstName}}!</h1>
</div>

<UserAvatar @user={{currentUser}} aria-expanded={{isExpanded}} />

This would render output similar to the following:

<div aria-expanded="true">
  <h1>Hello, Steven!</h1>
</div>

Phase 3 - Tracked Properties

Phase 3 enables tracked properties via the @tracked decorator in Ember. The details of the interop between Ember’s object model and tracked properties is being worked out. Once tracked properties land, users will be able to drop the @glimmer/component/compat module and use the normal, non-Ember.Object component base class.

In tandem with the recently-merged “autotrack” feature (which infers computed property dependencies automatically), this should result in further simplification of application code:

import Component, { tracked } from '@glimmer/component';

export default class extends Component {
  @tracked isAdmin = false;
  
  @tracked get fullName() {
    let { firstName, lastName } = this.args;
    return `${firstName} ${lastName}`;
  }
  
  toggleAdmin() {
    this.isAdmin = !this.isAdmin;
  }
}

Q&A

Can I add back things like the ember-view class name or auto-generated id attribute to Glimmer components for compatibility with existing CSS?

Yes. Example:

<div class="ember-view" id="{{uniqueId}}">
  Component content goes here.
</div>

import Component from '@glimmer/component';
import { guidFor } from '@ember/object/internals';

export default class extends Component {
  get uniqueId() {
    return guidFor(this);
  }
}

Resources

• #st-glimmer-components channel on the Ember community Slack
  • We’re coordinating the work here.
• Custom Component RFC
• custom-component-manager branch
  • In-progress branch of Ember.js with CustomComponentManager implementation behind a feature flag
• tracked branch
  • In-progress branch of Ember.js with work on interop between @tracked properties and Ember objects

Tasks

We’ll use the lists below to track ongoing work. As we learn more during implementation, we will add or remove items on the list.

Custom Component Manager API

• Update Custom Component RFC to reflect changes above (@chancancode)
  • https://github.com/emberjs/rfcs/pull/213#issuecomment-370494713
• Add glimmer-custom-component-manager feature flag
• Implement componentManager function
  • Expose as { componentManager } from '@ember/custom-component-manager'
• Resolver needs to detect annotated classes
• Resolver needs to look up specified component manager
  • Guidance for addon authors about where to put component managers so they are discovered
  • How does this work with Module Unification? (@mixonic)
• Implement CustomComponentManager API
  • Define the CustomComponentManagerDelegate interface
    • version
    • create()
    • getContext()
    • update()
    • destroy?()
    • didCreate?()
    • didUpdate?()
    • getView?()
  • Validate version property upon creation
  • Internals
    • Preserve childViews and parentView in existing components
    • Instrument for rendering performance
    • Instrument for compatibility with Ember Inspector

Glimmer Component Addon

• Support using sparkles-components addon
  • Base class should import and add componentManager annotation when consumed from Ember
  • CustomComponentManager implementation should be discoverable via Ember’s container
• Support using @glimmer/component as an Ember addon
  • Preserve existing behavior when consumed from Glimmer.js
  • import Component from '@glimmer/component' provides plain JavaScript base class
  • import Component from '@glimmer/component/compat' provides Ember.Object base class lookup
• Lifecycle Hooks
  • static create(injections)
  • didInsertElement()
  • willDestroy()
  • didUpdate()
  • Event delegation-invoked methods (click() etc.) should not be triggered
• Element Access
  • this.bounds
  • this.element computed property alias to this.bounds
  • Element modifier-based API for exposing elements
• Arguments
  • this.args is available in the constructor
  • this.args is updated before didUpdate is called
  • this.args should not trigger an infinite re-render cycle (need to verify)
• Documentation
  • How to install
  • Caveats
    • Canary-only
    • Pre-1.0
  • Ember-Glimmer “compat” components
    • Outer HTML templates
    • Lifecycle hooks
    • Defining computed properties
      • How to depend on args
  • Migration Guide / Glimmer Components for…
    • Guides for writing effective Glimmer components for people familiar with other libraries
    • Glimmer Components for Ember Developers
    • Glimmer Components for React Developers
    • Glimmer Components for Angular Developers
    • Glimmer Components for COBOL Developers

Open Questions

1. What are the best practices for actions? Is this something we need to allow component managers to hook into?
2. How do you use bare JavaScript classes (those with no static create() method) as component classes? The protocol for initializing a component seems simple but is surprisingly tricky.
3. Where is the best place to document “addon APIs” like CustomComponentManager?
4. How do we handle CustomComponentManager versioning?

[dbbk]

Regarding this;

{{! src/ui/components/UserAvatar/template.hbs }}
<div ...attributes> {{! <-- attributes will be inserted here }}
  <h1>Hello, {{@firstName}}!</h1>
</div>

I don’t understand why curly brackets are used to denote dynamic variables ({{@firstName}}), but not the splatted attributes? To me visually it looks like <div ...attributes> is what’s going to be rendered. For consistency wouldn’t this be better as <div {{...attributes}}>?

[tomdale]

@dbbk The biggest reason we don’t require {{...attributes}} is because it’s not syntactically ambiguous with a normal attribute, like the other cases where we require curlies, and four fewer characters seemed easier to type and less visually noisy.

I think it may also cause people to assume attributes is a property in scope, but it’s not—you can’t do <SomeComponent something={{attributes}} />, for example, which that syntax would suggest. It also more strongly implies that spread syntax works in other positions when it doesn’t.

There has been some suggestion of adopting both @arguments as a special template binding and adding ... spread syntax in Handlebars, but that needs design and implementation that is not on the immediate roadmap. I wouldn’t be totally surprised if in the future we replaced ...attributes with {{...@attributes}} or something like it.

@Gaurav0 The Glimmer component API would go through the RFC process before being enabled by default in Ember apps, should we ever want to do that. One nice thing about the custom component manager approach is that we don’t canonize a “next generation” API but can let different designs compete on their merits via the addon ecosystem.

@Turbo87 Great suggestion, I’ll add a migration guide to the list. We should show existing patterns and how to approach solving the same problem with the new API.

I’ll address the case of didReceiveAttrs() specifically since you brought it up. Usually people use this hook to do some initialization of component state based on passed arguments, but in practice this means you can do a fair bit of unnecessary in these hooks, e.g. to initialize values that never end up getting used. And of course people do end up doing shocking things in these hooks that are on the rendering hot path.

The alternative is to switch from “push-based” initialization to “pull-based” initialization. For example, if you wanted to do some computation to generate or initialize the value of a component property, you would instead use a tracked computed property. This ensures the work is only done for values that actually get used. Example:

Instead of this:

import Component from "@ember/component";
import { computed } from "@ember/object";

export default Component.extend({
  didReceiveAttrs() {
    this.set('firstName', this.attrs.firstName || 'Tobias');
    this.set('lastName', this.attrs.lastName || 'Bieniek');
  },

  fullName: computed('firstName', 'lastName', function() {
    return `${this.firstName} ${this.lastName}`;
  })
});

Do this:

import Component, { tracked } from "@glimmer/component";

export default class extends Component {
  @tracked get firstName() {
    return this.args.firstName || 'Tobias';
  }

  @tracked get lastName() {
    return this.args.lastName || 'Bieniek';
  }

  @tracked get fullName() {
    return `${this.firstName} ${this.lastName}`;
  }
}

I’ll admit I was skeptical of this at first, but @wycats persuaded me, and in my experience building a big Glimmer.js app over the last year or so, we never ran into a use case for didReceiveAttrs that couldn’t be modeled with more-efficient computed properties.