[RFC] API for component parts, shorthand, and variants

[levithomason]

👉 I've scoped this discussion to icon to illustrate the point, but the concept applies to all props.

---

Problem

We need to solidify our API pattern for dealing with the icon prop. The prop name icon can mean different things in different contexts. It also creates conflicting APIs in some cases.

Consider all the forms of icon in the API currently:

Icon parts

Component parts are named parts within a component. Example, a Button can contain an icon, therefore, there is an icon part of the button.

The parts of a component standardize the areas that we target for styling, accessibility, and shorthand props.

Icon shorthand

We have shorthand props to make defining component parts, like icon, very simple and powerful:

<Button icon='user' />
<Button icon={{ name: 'user', color: 'red' }} />

Icon component variants

Here is where we hit an issue. Some components have a variation or type of the name "icon".

There is a difference between a component "containing an icon" and a component that is an of the type "icon".

See some examples

Header "containing an icon" vs an "Icon Header" type Header...

A "Button containing an icon" vs an "icon button". Notice the box model changes to fit the icon..

The list of components with special formatting for the icon only case continues.

API

Currently, we use a boolean prop of the name icon to signify the icon variant:

<Button icon />
<Header icon />
<Menu icon />

The issue is that you cannot simultaneously define an "icon part" with shorthand and specify the "icon variant" with a boolean. Passing any value to icon={...} in order to define the icon itself negates the ability to pass a boolean to specify if the component is of type icon or not.

Proposals

We need a different name for signifying the icon variant. The icon prop should be used for defining the icon only.

1. iconOnly - this works in cases such as the Button and Menu where you are saying "this component contains an icon only". However, it fails in cases like the Header where the icon variant can coexist with other content, just formatted differently.
2. type="icon" - scoping the type or variant works in all cases, but conflicts with other props like <Input type="" />.
3. variant="icon" - This also works but seems to push us toward moving all variants into this enum. That breaks type safety and makes it difficult to compose multiple variants like <Menu variant="vertical icon".

---

We need more ideas and a robust solution to dealing with names that conflict across component type, shorthand, and variants. Feedback welcome!

[levithomason]

Solved, we'll use the iconOnly pattern for now. We're open to changes once we get the specifications process going. We want data driven answers to these, not a pot of opinions.