Component API consistency about brand

[rezrah]

👋 @stefankp - thanks for bringing this up.

We'll need to discuss this in detail at our next maintainer sync to find the right solution going forward, but in the meantime here are my immediate thoughts..

<Component heading="..." />

We will occasionally use this prop based API where we want - or sometimes need - to restrict the appearance and implementation of the prop through an abstraction. While I agree it's not composable API like we offer elsewhere, the tradeoff here is that it's faster to implement and render while achieving our intended guardrails.

<Component>
  <Heading>...</Heading>
</Component>

<Component>
  <Component.Heading>...</Component.Heading>
</Component>

Definitely agree the differences aren't immediately clear 😅. The context here, is that namespaced versions do a lot more under the hood than non-namespaced equivalents. It's also meant to indicate that the entire API for Heading is available to you on the former. Component.Heading however, could have an entirely different API and is not necessarily equivalent to Heading. We always try to go with the former first, but when there's too many defaults required, we end up namespacing.

This API suggests to me that I could pass in more than one component (or other), but actually only the first one is accepted.

This either should be documented or fixed so that we batch the rendering of multiple Text child types. I think this is an easy one to fix, we can take this away.

Hero

Just an FYI that the Hero component will be refactored eventually... here a related issue.

[stefankp]

@rezrah I think we should prefer the composable APIs when possible. Exception could be when a component only has required inputs with no optional customization. Looking forward to the Hero refactor 👌

[rezrah]

Closing this issue as..

• A revised hero has now shipped with a composable API
• We'll be writing up the ADR in contributor documentation in Q1
• Nuances around filtering of children on certain components will be captured and explained in their respective documentation.
• We already have established precedent for writing composable component API's, which is being used in all net new components.

[rezrah]

Next steps:

• Await feedback from @stefankp et al
• Document API conventions and rationales in an ADR