RFC: Page component API

[lucasaarcoverde]

Problem

The Page component has now been reviewed at the design level and is working as it should.

The main issue with this component is that we are trying to match some design specs, which should be at the documentation/Figma level, at the code level, and this ended up creating complexity in the component usage.

For example, to use a button on the Page you don’t need to check for the Button component doc but for the PageHeaderButton doc, and is necessary also to understand what’s the difference between them.

Why this matters?

Using a simple page layout requires a lot of understanding of the component itself (PageHeaderTop, PageHeaderTitle, PageHeaderButton, PageHeaderActions, etc.) which brings an unnecessary complexity.

Proposal

My proposal is to give more power to the user and let them guide how they will implement the PageHeader layout while avoiding specific components with hidden styles and properties.

Full Example

Before

<Page>
  <PageHeader onPopNavigation={() => {}}>
    <PageHeaderTop>
      <PageHeaderTitle>
        {title}
        <PageHeaderTags>
          <PageHeaderTag label="Short text" />
        </PageHeaderTags>
      </PageHeaderTitle>
      <PageHeaderActions>
        <PageHeaderButton>Create</PageHeaderButton>
        <PageHeaderMenuButton state={state} />
        <Menu state={state} aria-label="actions">
	  {menuItems}
        </Menu>
      </PageHeaderActions>
    </PageHeaderTop>
    <PageHeaderBottom>
      <TabList state={tabs}>
        {tabs}
      </TabList>
    </PageHeaderBottom>
  </PageHeader>
  <PageContent>
    {content}
  </PageContent>
</Page>

After

<Page>
  <PageHeader onPopNavigation={() => {}}>
    <Flex justify="space-between">
      <Flex>
	{/* The PHTitle renders the onPopNavigation button */}
        <PageHeaderTitle>{title}</PageHeaderTitle>
        <Stack direction="row">
          <Tag size="large" label="Short text" />
        </Stack>
      </Flex>
      <PageHeaderActions>
        <Button size="large">Create</Button>
        <MenuButton state={state} 
          size="large"
	  variant="tertiary"
	  bleedX
	  labelHidden
        />
        <Menu state={state} aria-label="actions">
	  {menuItems}
        </Menu>
      </PageHeaderActions>
    </Flex>
    <TabList state={tabs}>
      {tabs}
    </TabList>
  </PageHeader>
  <PageContent>
    {content}
  </PageContent>
</Page>

Title

Before

<Page>
  <PageHeader onPopNavigation={() => {}}>
    <PageHeaderTop>
      <PageHeaderTitle>{title}</PageHeaderTitle>
    </PageHeaderTop>
  </PageHeader>
  <PageContent>
    {content}
  </PageContent>
</Page>

After

<Page>
  <PageHeader onPopNavigation={() => {}}>
    <PageHeaderTitle>{title}</PageHeaderTitle>
  </PageHeader>
  <PageContent>
    {content}
  </PageContent>
</Page>

With tags

Before

<Page>
  <PageHeader>
    <PageHeaderTop>
      <PageHeaderTitle>
        {title}
        <PageHeaderTags>
          <PageHeaderTag label="Short text" />
        </PageHeaderTags>
      </PageHeaderTitle>
    </PageHeaderTop>
  </PageHeader>
  <PageContent>
    {content}
  </PageContent>
</Page>

After

<Page>
  <PageHeader onPopNavigation={() => {}}>
    <Flex>
      <PageHeaderTitle>{title}</PageHeaderTitle>
      <Stack direction="row">
        <Tag label="Short text" size="large" />
      </Stack>
    </Flex>
  </PageHeader>
  <PageContent>
    {content}
  </PageContent>
</Page>

With actions

Before

<Page>
  <PageHeader>
    <PageHeaderTop>
      <PageHeaderTitle>Product #123</PageHeaderTitle>
      <PageHeaderActions>
        <PageHeaderButton variant="secondary" />
        <PageHeaderButton>Create</PageHeaderButton>
        <PageHeaderMenuButton state={state} />
        <Menu state={state} aria-label="actions">
          <MenuItem label="Create" icon={<IconPlus />} />
        </Menu>
      </PageHeaderActions>
    </PageHeaderTop>
  </PageHeader>
  <PageContent>
    {content}
  </PageContent>
</Page>

After

<Page>
  <PageHeader onPopNavigation={() => {}}>
    <Flex justify="space-between">
      <PageHeaderTitle>{title}</PageHeaderTitle>
      <PageHeaderActions>
        <Button variant="secondary" size="large" />
        <Button size="large">Create</Button>
        <MenuButton state={state} />
	  <Menu state={state}>
	    <MenuItem label="Create" icon={<IconPlus />} />
 	  </Menu>
      </PageHeaderActions>
    </Flex>
  </PageHeader>
  <PageContent>
    {content}
  </PageContent>
</Page>

Pros

• It gives more power to the user since now he/she is responsible for implementing the layout with the correct behavior
• No need to understand several specific components such as PageHeaderButton, PageHeaderMenuButton, or PageHeaderTag.
• Less hidden styles or component properties usage

Cons

• The user needs to guarantee more design specs

Unresolved questions

• Should we have documented a “code language”? Something that would define and help in the component implementation

What's next

• Implement the proposed change

[anitavincent]

If we are leaving the layout to the user, does it still make sense to have some layout components like PageHeaderActions? Does it do something other than layout? This is more of a reflective question

[anitavincent]

I don't understand what you mean by code language. Do you mean like examples of code that match the common design specs?

[lucasaarcoverde]

You can think of code language as something similar to the usage of the state property in our components, we know when to use and how to use it even though we don't have a clear definition anywhere

In the case of the page component, I saw that we have a lot of auxiliary components such as PageHeaderTop, and PageHeaderButton whose objective is to help the user to follow a design specification, but once we started to use we understood that it brings an unnecessary complexity and learning curve since it has some hidden behaviors. So we could have documented that we don't try to match those kind of design specs in the components, in those cases we let it to the users