[Task](ui): Update and solidify PageHeader component

[franzheidl]

Overview

Problem Statement

The currently implemented PageHeader does not reflect the latest visual design and does have some stability / robustness / alignment issues, API issues, and does not support theming as much as we need it to going forward with theming support.

Goal

Implement the updated visual design of the PageHeader, make the component more robust, improve element alignment, improve its API, and extend its support for theming.

Context

This design update of the PageHeader components is necessary as a preparation to enable us to roll out additional themes and increase its stability and flexibility as a component.

Task Outcome

Have the updated PageHeader in Juno and all apps using the most current version of Juno ui-components, while not breaking apps due to breaking changes in the API of the component.

Details

Description

This task covers multiple aspects of the component:

Visual Design

The component need updating its outer margins/paddings in both verical and horizontal direction. See Figma for details and exact values:

Figma Pageheader Component

Layout Robustness

The layout of the component needs improving. Make sure the logo and/or any children passed to the component never manage to alter the dimensions of the PageHeader, and all elements incl. any logo passed in always center-align in the vertical axis. See Technical Details below for more details.

API Updates

Add applicationName prop, deprecate heading

Currently, the component has a heading prop that accepts a string to be rendered as the application name in the header. The naming of this prop is unfortunate as it is semantically wrong and not self-explanatory.
To improve the API, implement an applicationName prop for the exact same purpose. Keep the heading for backwards compatibility but mark as deprecated in the code and documentation. This will need to exist as long as we have apps that use it. Once we have changed all apps to use the new prop, we can remove it.

Implement href prop

In order to be consistent with multiple other components, add an href prop that accepts a string/url to complement the onClick prop we already have, so users can use either a JS-handler or a plain href anchor to link to the homepage of their app.
Depending on what markup we end up in order to make our layout more robust, both logo and application name should be wrapped in an <a> element OR be wrapped in individual element if href is passed. The onClick handler should be applied to both following the same logic.
As an end result we expect an onClick handler to be executed when clicking the logo AND/OR the application name; if an href was passed, we expect the link to be called when clicking the logo AND/OR the application name. An <a> element should only ever be created if href was passed.

Theming / CSS Variables

In order to allow for better theming support, we need to introduce more design token / CSS variables for the header background, border, and the application name. See Technical Details below for an in-depth table of variables and their mappings.

Storybook Code Examples

The code examples in storybook for PageHeader appear to be broken, especially the ones where children are passed to the component. Fix these in order to move towards a better, more robust and well-documented component.

Estimation

• Priority: High
• Effort: Medium
• Status: Backlog, Unrefined

Acceptance Criteria

• Visual design updates are implemented:
  • Margins/paddings are updated
• The component layout is more robust:
  • Large logos do not increase or stretch the component vertically
  • any children, application name and logo are always vertically centered
• The API has been updated:
  • applicationName prop is introduced
  • heading is deprecated, its value forwarded to applicationName
  • href is introduced
  • When href was passed, clicking both the logo and/or the application name should point to that link.
  • When no href was passed, no <a> should be created
  • When an onClick handler was passed, it should be executed when the logo and/or the application name was clicked.
• Better Theming support is implemented:
  • Variables are implemented and used as per the table under Technical Details
• (New) Fix Storybook code examples

Technical Notes

Design

Note some of the elements shown in the design files are child components that do not need to be implemented now, such as the user avatar, user menu, search field, and additional header options (notifications icon, mode switch) . These are or may be WIP and are NOT in scope of this implementation ticket.

For colors, we are using a pseudo-token system at the moment which is not 100% aligned with the variables in our code, refer to the table below under Design Tokens / CSS Variables for the exact variables to use.

For dimensions, Figma shows px, in the implementation use the corresponding value in rem.

Layout Robustness

Currently, the PageHeader consists of a two-column grid layout that takes care of the horizontal distribution of its parts. The columns each contain a flex box element that takes care of vertical alignment. For some reasons, the logo does not seem to be part of this setup. In the past and in some cases (example app?), elements in the header did not seem to align vertically as expected. Investigate and improve alignment. A sensible lead would be to include the logo in the grid setup as well, but there may be better apporaches(?).

API

Prop	Type	Default	Notes
applicationName	string or ReactElement	""	Replaces heading which will be deprecated
heading	string	""	Already exists, deprecate. Forwad to applicationName if passed
href	string (url)	""	To be added as an option to use a link to the app's home page. Make sure both logo and application name element point to that link if passed.
onClick	func	null	Already exists. Make sure both logo and application name element execute this handler if passed.

Design Tokens / CSS Variables

In order to support theming to the desired extent, we need to introduce the following CSS variables:

Property	@theme Variable	Per-Mode Variable	Juno Light	Juno Dark
pageheader bg color	--background-color-theme-pageheader	--color-pageheader-background	--color-white	--color-juno-grey-blue-10
bottom border color	--border-color-theme-pageheader	--color-pageheader-border	--color-juno-grey-light-7	--color-juno-grey-blue-3
application name color default	--text-color-theme-pageheader-appname-default	--color-pageheader-appname-text-default	--color-text-highest*	--color-text-highest*
application name color hover	--text-color-theme-pageheader-appname-hover	--color-pageheader-appname-text-hover	--color-text-highest*	--color-text-highest*
application name color active	--text-color-theme-pageheader-appname-active	--color-pageheader-appname-text-active	--color-text-highest*	--color-text-highest*

• The native Juno theme does not visually differentiate the interactive states of the application name in terms of color, however the next theme to be implemented will, so we need to implement these variables already.

Storybook Code Examples

The code examples for PageHeader show incorrect or incomplete code examples: Passed children are not visible or only as a fragment, passed handlers show minimized or fragmented. These need investigating and fixing.

Considerations

Dependencies

These updates to the PageHeader component will affect all applications that use it, either via AppShell or standalone.

Risks

None(?)

Questions

None so far.

QA

• Perform a code review
• Ensure all AC have been fulfilled
• Manually test whether the above changes work as expected without causing any regressions across the following platforms:
  • Storybook
  • Example App
  • (Optional?) Other Apps
• Validate all storybook code examples are correct
• Leave PR, ticking the criteria tested above
• Make sure existing tests for the component pass
• Add new tests for new funcitonalities/props, make sure these pass as well
• Code examples in storybook are correct and non-fragmented

Additional Links

Here’s a older ticket for only the alignment issues in the current PageHeader:
[Improvement](ui): Enhance PageHeader Layout for Vertical Alignment · Issue #1050 · cloudoperators/juno

Once this ticket is implemented, #1050 can be closed. Optionally, we can close the #1050 once this one is refined and ready for implementation.

[guoda-puidokaite]

Some questions:

• What should the relationship be between href and onClick? Both execute on click of logo/header, if passed. Which should take precedence, if both passed? From my understanding, onClick is mainly used for the same function href will now serve, so should href take precedence? Or the more customisable one, what makes sense from the background of this new ticket? Also, does it make sense to have both? I guess... if user wants to override default behaviour?
• Do we want any checks for href structure? Probably not, dev is responsible and can pass anything they want as usual?
• I'm guessing href should open in same tab/window?

CC: @edda

[edda]

• What should the relationship be between href and onClick? Both execute on click of logo/header, if passed. Which should take precedence, if both passed? From my understanding, onClick is mainly used for the same function href will now serve, so should href take precedence? Or the more customisable one, what makes sense from the background of this new ticket? Also, does it make sense to have both? I guess... if user wants to override default behaviour?

What you use depends on your app. If you can't route internally via link then it makes more sense to implement an onClick handler. It doesn't make sense to pass both. But if it happens I would give precedence to onClick working under the assumption that people potentially implement more complex behaviour in it.

• Do we want any checks for href structure? Probably not, dev is responsible and can pass anything they want as usual?
• I'm guessing href should open in same tab/window?

Yes, no validation on the href, it's the responsibility of the app developer to enter a valid link
Yes, same tab/window (if users want to open in a new tab/window, they can decide to do this manually using browser functionality

[guoda-puidokaite]

Bug Found 🐞

Question: How should the PageHeader behave and arrange on small screen? @franzheidl

---

Issue - Production Behaviour (when screen gets small):

Current Branch State:

[guoda-puidokaite]

Bug Found 🐞

There's extra space added below the content in PopupMenu due to prop <HeadlessMenu as="div". The default block-level behaviour of <div> introduces spacing that seems to be affecting the layout. If used in PageHeader, alignment is skewed. We need to fix this.

[franzheidl]

Appreciate your attention to this, Guoda. However, this is what we would expect the header to behave where we currently are.

We are aware of non-ideal behaviour on small screens for a number of our components, but we have de-prioritized these issues for now, so fixing/improving the behaviour of Pageheader on small screens is out of scope for now.