Reorganize "Built-In Components" in Ember Guides

[ijlee2]

Background

• Ember Guides: Components - Built-In Components
• Learning Team meeting notes from August 6, 2020
• https://discuss.emberjs.com/t/ember-octane-and-2-way-binding-what-are-you-recommend/18092

Description

There were 3 problems that inspired the conversation in the Learning Team meeting:

It wasn't clear to a developer that event handling for built-in <Input> component needs (may need) to be different for checkbox and non-checkbox inputs (camel-cased versus dasherized). Since the underlying implementation for these inputs is different (please see References below), we could have separate sub-subsections for checkbox and non-checkbox inputs.

~Our checkbox examples show first and last names (not the best example of a binary/ternary attribute). They will need to be updated to help address https://github.com/ember-learn/guides-source/issues/1480.~ (This has been addressed in #1530.)

I don't think we currently document how to use the {{on}} modifier for native inputs? It'd be good to have a subsection for native inputs for people who want to practice one-way data flow and who want to use fillIn test helper to test native inputs.

Possible TODOs

• [ ] Rename the section from Built-In Components to Input Components

• [ ] Reorganize the section to:

  Input Components
  │
  ├── Native Inputs
  │
  └── Built-In Inputs
    │
    ├── Non-Checkbox Input
    │
    ├── Checkbox Input
    │
    └── Textarea

• [ ] Optional: Check that the event names are correct for the built-in non-checkbox and checkbox input components (if within the ticket scope)

Once the changes are approved for release directory, backport the changes all the way to Ember 3.15.

References

• https://github.com/emberjs/ember.js/blob/master/packages/%40ember/-internals/glimmer/lib/templates/input.hbs (used by <Input> component)
• https://github.com/emberjs/ember.js/blob/master/packages/%40ember/-internals/glimmer/lib/templates/component.hbs (used by <Textarea> component)

[chancancode]

Can we put this on hold? I would love to help direct the effort into cataloging the underlying problems in a systematic way (i.e. writing failing tests) and fixing them upstream rather than propagating the confusion further and documenting even more bugs.

Rename the section from Built-In Components to Input Components

I believe this section is intended to be general enough to encompass any current or future (seems unlikely) built-in components (which is why it's listed under the "Components" section). Notably, I think this is where we could/would talk about <LinkTo> if needed. That's the intention anyway. That said, I am not super opposed to making a dedicated section about forms in general (maybe under "in-depth topics"), but we should probably keep something around in the components section and cross-link between the two?

[ijlee2]

@chancancode I'm open to delaying it.

To provide more context, in the Learning Team meeting, the team agreed to assume that the current documentation (with regards to event names) is correct and only allow moving contents around without modification (this is what I meant by reorganize). This way, we don't increase the scope of the ticket, but do allow the possibility of documenting how to use native inputs with {{on}} modifier.

Does this help address your concerns? (I didn't think about <LinkTo> component before. That explains why the section is currently named Built-In Components. 😄)

[ijlee2]

Let's wait on starting this issue (possibly adding explanation about native inputs) to allow #1543 to complete first.