Este problema de búsqueda rastrea la implementación de los componentes de Glimmer en Ember.js.

El plan

Los componentes de Glimmer.js tienen las siguientes características:

1. Plantillas de "HTML externo" (sin tagName , attributeBindings , etc.)
2. Los argumentos en las plantillas tienen el prefijo @ , como {{@firstName}}
3. Los argumentos se establecen en el componente como this.args
4. Las clases de componentes utilizan la sintaxis de clases de JavaScript
5. El estado del componente mutable se anota con @tracked propiedades
6. Los componentes se invocan mediante la sintaxis <AngleBracket />
7. Los atributos se pueden "distribuir" a través de …attributes

De acuerdo con el espíritu de incrementalismo de Ember, queremos aterrizar esta funcionalidad pieza por pieza a través de un complemento. Esto permite que la comunidad comience a usar funciones y a proporcionar comentarios al principio del proceso.

De hecho, ya hemos comenzado el camino hacia los componentes Glimmer en Ember. Las dos primeras características ya han comenzado a aterrizar:

1. En los componentes de solo plantilla, las plantillas son "HTML externo" (suponiendo que se haya habilitado la función opcional template-only-glimmer-components ).
2. Se puede acceder a los argumentos en la plantilla a través del prefijo @ (por ejemplo, {{@firstName}} ).

Este problema propone terminar el proceso de traer componentes de Glimmer a Ember al permitir que los complementos proporcionen implementaciones de componentes alternativos, y luego transformar el paquete @glimmer/component en un complemento de Ember que implemente la API del componente Glimmer.js.

Dividiremos ese trabajo en fases, cada una de las cuales desbloqueará beneficios para las aplicaciones y complementos existentes de Ember. La fase 0 trata de agregar las primitivas necesarias a Ember.js para admitir implementaciones de componentes alternativos. Las fases 1, 2 y 3 tratan sobre la habilitación incremental de la API del componente Glimmer.js.

Mientras profundizamos en las Fases 0 y 1, postergaremos la exploración de los detalles técnicos de las fases posteriores hasta que las primeras estén más cerca de completarse.

Fase 0: Personalización del comportamiento de los componentes

TL; DR: agregue una API CustomComponentManager a Ember.js para permitir que los complementos implementen la API de componentes personalizados.

Actualmente, se supone que todos los componentes de una aplicación Ember son subclases de Ember.Component . Para admitir API de componentes alternativos en Ember, necesitamos alguna forma de decirle a Ember cuándo y cómo debería cambiar el comportamiento de los componentes.

Cuando decimos "comportamiento de componentes personalizados", nos referimos específicamente a:

1. Cómo se crean las instancias de componentes.
2. Cómo se destruyen las instancias de componentes.
3. Cómo se proporcionan los argumentos a la instancia del componente.
4. Cómo se notifica al componente de estos cambios en el ciclo de vida.

Si bien Glimmer VM introduce el concepto de "administrador de componentes", un objeto que toma estas decisiones, esta API es de muy bajo nivel. Sería prematuro adoptarlos directamente como API pública en Ember porque son difíciles de escribir, fáciles de crear de una manera que rompe otros componentes y aún no son estables.

En su lugar, proponemos una nueva API de Ember llamada CustomComponentManager que implementa un patrón de delegado. El CustomComponentManager proporciona un área de superficie de API más pequeña que el API de Glimmer VM de ComponentManager completo, que permite a los autores de complementos caer en un "pozo del éxito".

Entonces, ¿cómo sabe Ember qué administrador de componentes usar para un componente determinado? La iteración original del RFC de componentes personalizados introdujo el concepto de ComponentDefinition , una estructura de datos que se registró con entusiasmo con Ember y especificó qué administrador de componentes usar.

Uno de los principales beneficios del enfoque ComponentDefinition es que la resolución del administrador de componentes puede ocurrir en el momento de la compilación. Desafortunadamente, eso significa que tenemos que diseñar una API para exactamente cómo se registran, y probablemente significa algún tipo de integración con la canalización de compilación.

En su lugar, proponemos una API para configurar el administrador de un componente en tiempo de ejecución mediante una anotación en la clase del componente. Este paso incremental permite que el trabajo en administradores de componentes personalizados continúe mientras se diseña una solución a más largo plazo.

Descubrimiento del administrador de componentes personalizados

En esta iteración, los componentes deben optar explícitamente por los administradores de componentes alternativos. Lo hacen a través de una función especial componentManager , exportada por Ember, que anota en tiempo de ejecución qué administrador de componentes debe usarse para una clase de componente en particular:

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

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

Eventualmente, esto podría convertirse en un decorador de clases:

import { componentManager } from '@ember/custom-component-manager';

export default @componentManager('glimmer') class {
  // ...
}

La primera vez que se invoca este componente, Ember inspecciona la clase para ver si tiene una anotación de administrador de componentes personalizada. Si es así, usa el valor de la cadena para realizar una búsqueda en el contenedor. En el ejemplo anterior, Ember pediría al contenedor el objeto con la clave del contenedor component-manager:glimmer .

Por lo tanto, los complementos pueden usar la semántica de resolución normal para proporcionar administradores de componentes personalizados. Nuestro complemento de componentes Glimmer puede exportar un administrador de componentes desde addon/component-managers/glimmer.js que se descubrirá automáticamente a través de las reglas de resolución normales.

Si bien esta API es detallada y no particularmente ergonómica, las aplicaciones y los complementos pueden abstraerla introduciendo su propia clase base con la anotación. Por ejemplo, si un complemento llamado turbo-component quisiera proporcionar un administrador de componentes personalizado, podría exportar una clase base como esta:

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

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

Los usuarios de este complemento pueden subclasificar la clase base TurboComponent para definir componentes que usen el administrador de componentes correcto:

import TurboComponent from 'turbo-component';

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

API de componentes personalizados

Ningún componente es una isla y, por razones de compatibilidad con versiones anteriores, es importante que la introducción de una nueva API de componentes no rompa los componentes existentes.

Un ejemplo de esto es la API de jerarquía de vistas existente. Los componentes Ember pueden inspeccionar su componente principal a través de la propiedad parentView . Incluso si el padre no es Ember.Component , los componentes secundarios de Ember deberían tener una propiedad parentView no nula.

Actualmente, el CurlyComponentManager en Ember es responsable de mantener este estado, así como otro "estado de alcance" ambiental como el objetivo de las acciones.

Para evitar que los administradores de componentes mal implementados violen invariantes en el sistema existente, usamos un patrón de composición para personalizar el comportamiento mientras ocultamos las esquinas afiladas de la API subyacente.

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) {
  }
});

Fase 1: Componentes de Ember Object Glimmer

La clase base Component en Ember admite una larga lista de características, muchas de las cuales ya no se utilizan mucho. Estas funciones pueden imponer un costo de rendimiento, incluso cuando no se utilizan.

Como primer paso, queremos proporcionar una forma de participar en la API simplificada del componente Glimmer.js a través del paquete @glimmer/component . Para facilitar la migración, proporcionaremos una implementación de la clase base Glimmer Component que hereda de Ember.Object en @glimmer/component/compat .

A continuación, se muestra un ejemplo de cómo se ve un "componente Ember-Glimmer":

// 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>

Características destacables de estos componentes:

• Las plantillas son HTML externo . Debido a que la plantilla de ejemplo anterior no tiene un solo elemento raíz, esto se representa como un "componente sin etiquetas".
• Las acciones son solo funciones en el componente y no necesitan estar anidadas en el hash actions .
• Los argumentos se establecen en la propiedad args lugar de establecer propiedades individuales en el componente directamente.
• Usan el modelo de objetos Ember . Esto significa que las herramientas como las propiedades calculadas y los mixins con los que los desarrolladores de Ember ya están familiarizados continúan funcionando.

Igual de importante es lo que no está incluido:

• @tracked propiedades
• No hay propiedades layout o template en el componente.
• No hay métodos o propiedades relacionados con la jerarquía de vistas, como childViews , parentView , nearestWithProperty , etc.
• No tagName , attributeBindings u otro DSL JavaScript personalizado para modificar el elemento raíz.
• No send o sendAction para enviar eventos.
• No hay ember-view clase obligatoria o ID de elemento guid generado automáticamente.
• Sin método rerender() manual.
• Sin propiedad attrs (use args lugar).
• Los argumentos aprobados son "unidireccionales" y no crean enlaces bidireccionales.
• Los argumentos pasados ​​no se establecen como propiedades en la instancia del componente, lo que evita la posibilidad de colisiones de nombres difíciles de depurar.
• No this.$() para crear un objeto jQuery para el elemento del componente.
• No hay appendTo de componentes manuales en el DOM.
• No hay soporte para los siguientes eventos del ciclo de vida:
  
  
  
  • willInsertElement
  
  
  • didRender
  
  
  • willRender
  
  
  • willClearRender
  
  
  • willUpdate
  
  
  • didReceiveAttrs
  
  
  • didUpdateAttrs
  
  
  • parentViewDidChange
  
  
• Sin detector de eventos on() para los eventos del ciclo de vida de los componentes; los ganchos deben implementarse como métodos.

Un efecto secundario interesante de este conjunto de características es que encaja con el esfuerzo de habilitar clases de JavaScript . Junto con el diseño propuesto en el RFC de clases de ES , podemos proporcionar una implementación alternativa del componente anterior:

// 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);
  }
});

Fase 2 - Sintaxis de corchetes angulares

La fase 2 permite invocar componentes mediante corchetes angulares ( <UserAvatar @user={{currentUser}} /> ) además de curlies ( {{my-component user=currentUser}} ). Debido a que esta sintaxis elimina la ambigüedad entre los argumentos de los componentes y los atributos HTML, esta función también permite "distribuir" los atributos pasados ​​en la plantilla del componente a través de …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}} />

Esto generaría una salida similar a la siguiente:

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

Fase 3 - Propiedades rastreadas

La fase 3 habilita las propiedades rastreadas a través del decorador @tracked en Ember. Se están resolviendo los detalles de la interoperabilidad entre el modelo de objetos de Ember y las propiedades rastreadas. Una vez que las propiedades rastreadas aterrizan, los usuarios podrán soltar el módulo @glimmer/component/compat y usar la clase base del componente normal, que no es Ember.Object.

Junto con la función "autotrack" recientemente fusionada (que infiere las dependencias de propiedades calculadas automáticamente), esto debería resultar en una mayor simplificación del código de la aplicación:

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

export default class extends Component {
  <strong i="24">@tracked</strong> isAdmin = false;

  <strong i="25">@tracked</strong> get fullName() {
    let { firstName, lastName } = this.args;
    return `${firstName} ${lastName}`;
  }

  toggleAdmin() {
    this.isAdmin = !this.isAdmin;
  }
}

Preguntas y respuestas

¿Puedo volver a agregar cosas como el nombre de clase ember-view o el atributo id generado automáticamente a los componentes de Glimmer para que sean compatibles con CSS existente?

Si. Ejemplo:

<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);
  }
}

Recursos

• # canal st-glimmer-components en la comunidad de Ember Slack
  
  
  
  • Estamos coordinando el trabajo aquí.
  
  
• RFC de componente personalizado
• custom-component-manager sucursal
  
  
  
  • Rama en progreso de Ember.js con implementación CustomComponentManager detrás de una marca de función
  
  
• tracked sucursal
  
  
  
  • Rama en progreso de Ember.js con trabajo en interoperabilidad entre propiedades @tracked y objetos Ember
  
  

Tareas

Usaremos las listas a continuación para realizar un seguimiento del trabajo en curso. A medida que aprendamos más durante la implementación, agregaremos o eliminaremos elementos de la lista.

API de administrador de componentes personalizados

• [x] Actualice el RFC del componente personalizado para reflejar los cambios anteriores (@chancancode)
  
  
  
  • https://github.com/emberjs/rfcs/pull/213#issuecomment -370494713
  
  
• [x] Agregar glimmer-custom-component-manager marca
• [x] Implementar la función componentManager
  
  
  
  • [x] Exponer como { componentManager } from '@ember/custom-component-manager'
  
  
• [x] El solucionador necesita detectar clases anotadas
• [x] El solucionador debe buscar el administrador de componentes especificado
  
  
  
  • [] Orientación para los autores de complementos sobre dónde colocar los administradores de componentes para que sean descubiertos
  
  
  • [] ¿Cómo funciona esto con la unificación de módulos? (@mixonic)
  
  
• [x] Implementar CustomComponentManager API
  
  
  
  • [x] Definir la interfaz CustomComponentManagerDelegate
  
  
  • [x] version
  
  
  • [x] create()
  
  
  • [x] getContext()
  
  
  • [x] update()
  
  
  • [x] destroy?()
  
  
  • [x] didCreate?()
  
  
  • [x] didUpdate?()
  
  
  • [x] getView?()
  
  
  • [x] Validar la propiedad version al momento de la creación
  
  
  • [x] Internos
  
  
  • [x] Conservar childViews y parentView en componentes existentes
  
  
  • [] Instrumento para el rendimiento de renderizado
  
  
  • [] Instrumento de compatibilidad con Ember Inspector
  
  

Complemento de componente Glimmer

• [x] Asistencia con el complemento sparkles-components
  
  
  
  • [x] La clase base debe importar y agregar componentManager anotación cuando se consume desde Ember
  
  
  • [x] La implementación de CustomComponentManager debería ser detectable a través del contenedor de Ember
  
  
• [] Admite el uso de @glimmer/component como complemento de Ember
  
  
  
  • [] Conservar el comportamiento existente cuando se consume desde Glimmer.js
  
  
  • [] import Component from '@glimmer/component' proporciona una clase base de JavaScript simple
  
  
  • [] import Component from '@glimmer/component/compat' proporciona Ember.Object clase base
    
    buscar
  
  
• [] Ganchos del ciclo de vida
  
  
  
  • [x] estático create(injections)
  
  
  • [x] didInsertElement()
  
  
  • [x] willDestroy()
  
  
  • [x] didUpdate()
  
  
  • [x] Los métodos invocados por delegación de eventos ( click() etc.) no deben activarse
  
  
• [] Acceso al elemento
  
  
  
  • [] this.bounds
  
  
  • [] this.element alias de propiedad calculado en this.bounds
  
  
  • [] API basada en modificadores de elementos para exponer elementos
  
  
• [] Argumentos
  
  
  
  • [x] this.args está disponible en el constructor
  
  
  • [x] this.args se actualiza antes de que se llame a didUpdate
  
  
  • [] this.args no debería activar un ciclo de renderizado infinito (es necesario verificarlo)
  
  
• [] Documentación
  
  
  
  • [ ] Cómo instalar
  
  
  • [] Advertencias
  
  
  • [] Solo canario
  
  
  • [] Pre-1.0
  
  
  • [] Componentes "compatibles" de Ember-Glimmer
  
  
  • [] Plantillas HTML externas
  
  
  • [] Ganchos del ciclo de vida
  
  
  • [] Definición de propiedades calculadas
    
    
    
    
    
    • [] Cómo depender de args
    
    
    
  
  
  • [] Guía de migración / Componentes de Glimmer para ...
  
  
  • Guías para escribir componentes Glimmer eficaces para personas familiarizadas con otras bibliotecas
  
  
  • [] Componentes Glimmer para desarrolladores de Ember
  
  
  • [] Componentes de Glimmer para desarrolladores de React
  
  
  • [] Componentes Glimmer para desarrolladores angulares
  
  
  • [] Componentes Glimmer para desarrolladores COBOL
  
  

Preguntas abiertas

1. ¿Cuáles son las mejores prácticas para las acciones? ¿Es esto algo a lo que debemos permitir que los administradores de componentes se conecten?
2. ¿Cómo se usan las clases de JavaScript desnudas (aquellas sin método create() estático) como clases de componentes? El protocolo para inicializar un componente parece simple pero sorprendentemente complicado.
3. ¿Cuál es el mejor lugar para documentar "API adicionales" como CustomComponentManager ?
4. ¿Cómo manejamos el control CustomComponentManager versiones