From e9c827ba41cc841e2313278289823fb92c26118b Mon Sep 17 00:00:00 2001 From: Alon Bukai Date: Tue, 26 Jun 2018 09:52:42 +0300 Subject: [PATCH 01/10] First Draft Ember Data Deprecate Transforms --- text/0000-ember-data-deprecate-transforms.md | 66 ++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 text/0000-ember-data-deprecate-transforms.md diff --git a/text/0000-ember-data-deprecate-transforms.md b/text/0000-ember-data-deprecate-transforms.md new file mode 100644 index 0000000000..5e36affe08 --- /dev/null +++ b/text/0000-ember-data-deprecate-transforms.md @@ -0,0 +1,66 @@ +- Start Date: 2018-06-24 +- RFC PR: (leave this empty) +- Ember Issue: (leave this empty) + +# (Ember Data Deprecate Transforms) + +## Summary + +> This RFC suggests deprecating Ember Data [transforms](https://www.emberjs.com/api/ember-data/release/classes/DS.Transform). + +Example: + +```javascript +// app/models/person.js +import DS from 'ember-data'; + +export default DS.Model.extend({ + name: DS.attr('string'), //<-- + age: DS.attr('number'), //<-- + admin: DS.attr('boolean'), //<-- + birthday: DS.attr('date') //<-- +}); +``` + +## Motivation + +> Ember Data `transforms` have, for some time, been the cause of confusion for Ember Data users. Anything that can be done with `transforms` can also be done using Serializers. +> +> Part of the confusion was aided by the [no-empty-attrs](https://github.com/ember-cli/eslint-plugin-ember/blob/master/docs/rules/no-empty-attrs.md) ESLint Plugin Ember Rule. This rule was included as a recommended rule at one point in time in the plugin. +> +> `Transforms` are not *types*. They allow serializing and deserializing model `attrs`. However their use often causes people to assume that they are *types*. +> +> Another issue, `transforms` can have a bad effect on performance when they are used incorrectly, or at all. +> +> tl;dr `Transforms` are confusing and don't provide any added value that can't be achieved using serializers. + +## Detailed design + +> `Transforms` will be deprecated and any use of `transforms` will cause a deprecation warning, notifying the user that this method is deprecated and providing a link to an explanation of how to achieve the same outcome with serializers. +> +> An Ember Addon can be built to help any current users of `transforms` migrate to not using them over time. + +## How we teach this + +> We need to remove mentions of `transforms` in the Ember Guides and API: +> [Defining Models](https://guides.emberjs.com/release/models/defining-models/#toc_transforms), +> [Customizing Serializers](https://guides.emberjs.com/release/models/customizing-serializers/#toc_creating-custom-transformations), +> [API DS.Transform](https://www.emberjs.com/api/ember-data/release/classes/DS.Transform) +> +> Instead of these we will need to teach how to do the same things that were possible with `transforms` but with serializers. +> +> Once we remove the use of `transforms` from the guides and instead explain how to use serializers to achieve the same result, new users will learn to use serializers and not `transforms`. + +## Drawbacks + +> Currently `transforms` are being used and taught and deprecating them will remove a long used feature of Ember Data. +> +> We will need to write up more information on serializers to cover for the lack of `transforms`. However this isn't necessarily a bad thing. + +## Alternatives + +> We could not do this and just leave `transforms` as part of Ember Data. We could try to educate users about the actual uses of `transforms` and remove any notions of using them as `attr` *types*. + +## Unresolved questions + +> ? From 36c43ad6d3d5a97ec742630d1a649536add114ea Mon Sep 17 00:00:00 2001 From: Alon Bukai Date: Wed, 5 Jun 2019 09:25:45 +0300 Subject: [PATCH 02/10] feat: Splarguments first draft --- text/0000-argument-spread-splarguments.md | 81 +++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 text/0000-argument-spread-splarguments.md diff --git a/text/0000-argument-spread-splarguments.md b/text/0000-argument-spread-splarguments.md new file mode 100644 index 0000000000..a155ca124e --- /dev/null +++ b/text/0000-argument-spread-splarguments.md @@ -0,0 +1,81 @@ +- Start Date: 2019-06-05 +- Relevant Team(s): Ember.js +- RFC PR: (after opening the RFC PR, update this with a link to it and update the file name) +- Tracking: (leave this empty) + +# Forwarding Component Arguments with "Splarguments" + +## Summary + +Currently it is possible to forward element attributes and modifiers(?) into child components for use as "splattributes" +such as, `...attributes`. This RFC proposes adding similar syntax and functionality for arguments such as, `...arguments`. + +## Motivation + +The reason for doing this is to allow less verbose component templates where the verbosity only makes the template harder to read. +Having the ability to spread arguments would make reading deeply nested component invocations much cleaner and nicer. + + +For example, given the following invocation: +```hbs + +``` +...and the following layout for the `Foo` component: +```hbs + +``` +... and the following layout for the `Bar` component: +```hbs +
@foo
+``` +Ember will render the folliwing HTML content: +```html +
bar
+``` + +A possible example in the wild could be +[ember-power-select](https://github.com/cibernox/ember-power-select/blob/master/addon/templates/components/power-select.hbs). +This component has to explicitely pass on many arguments to its child components. With "splarguments" half or more of this template could +be cut down. + +## Detailed design + +> This is the bulk of the RFC. + +> Explain the design in enough detail for somebody +familiar with the framework to understand, and for somebody familiar with the +implementation to implement. This should get into specifics and corner-cases, +and include examples of how the feature is used. Any new terminology should be +defined here. + +## How we teach this + +> What names and terminology work best for these concepts and why? How is this +idea best presented? As a continuation of existing Ember patterns, or as a +wholly new one? + +> Would the acceptance of this proposal mean the Ember guides must be +re-organized or altered? Does it change how Ember is taught to new users +at any level? + +> How should this feature be introduced and taught to existing Ember +users? + +## Drawbacks + +> Why should we *not* do this? Please consider the impact on teaching Ember, +on the integration of this feature with other existing and planned features, +on the impact of the API churn on existing apps, etc. + +> There are tradeoffs to choosing any path, please attempt to identify them here. + +## Alternatives + +> What other designs have been considered? What is the impact of not doing this? + +> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem. + +## Unresolved questions + +> Optional, but suggested for first drafts. What parts of the design are still +TBD? From 871ea7b6f7aa010b53df65b73d972b42c2ceca90 Mon Sep 17 00:00:00 2001 From: Alon Bukai Date: Thu, 6 Jun 2019 10:04:21 +0300 Subject: [PATCH 03/10] Renamed, change wording and added another example Updated regarding pzuraqs' comments. --- ...uments.md => 0000-spreadable-arguments.md} | 36 ++++++++++++++++--- 1 file changed, 32 insertions(+), 4 deletions(-) rename text/{0000-argument-spread-splarguments.md => 0000-spreadable-arguments.md} (57%) diff --git a/text/0000-argument-spread-splarguments.md b/text/0000-spreadable-arguments.md similarity index 57% rename from text/0000-argument-spread-splarguments.md rename to text/0000-spreadable-arguments.md index a155ca124e..723c91230e 100644 --- a/text/0000-argument-spread-splarguments.md +++ b/text/0000-spreadable-arguments.md @@ -3,16 +3,16 @@ - RFC PR: (after opening the RFC PR, update this with a link to it and update the file name) - Tracking: (leave this empty) -# Forwarding Component Arguments with "Splarguments" +# Forwarding Component Arguments with Spreadable Arguments ## Summary -Currently it is possible to forward element attributes and modifiers(?) into child components for use as "splattributes" -such as, `...attributes`. This RFC proposes adding similar syntax and functionality for arguments such as, `...arguments`. +Currently it is possible to forward element attributes and modifiers into child components using the spread-like +`...attributes` syntax. This RFC proposes adding a similar syntax and functionality for component arguments: `...arguments`. ## Motivation -The reason for doing this is to allow less verbose component templates where the verbosity only makes the template harder to read. +Spreadable Arguments, or `"Splarguments"`, will allow less verbose component templates, especially where the verbosity only makes the template harder to read. Having the ability to spread arguments would make reading deeply nested component invocations much cleaner and nicer. @@ -33,6 +33,34 @@ Ember will render the folliwing HTML content:
bar
``` +An additional benefit of Spreadable Arguments is that is can reduce the maintenance burden of components used today. +A great use case to showcase this is when a component is wrapped by another component. Currently we have to explicitely forward every argument to the child component: + +```hbs + +``` +This is very verbose and doesn't provide any benefits to the reader of the template. Having to pass all of these arguments down the component tree becomes annoying to read and hard to maintain. Imagine if we now have to add a new argument, `@arg3` to our `Foo` component. We would need to go through *every* single component invocation that is wrapping `Foo`. + + +An example of this wrapping pattern can be shown using a branded `Button` component. This component has many specific components that wrap the base component to provide button "types". + +Button Type Components: +```hbs + +