Bring native support for side panel app bars, sticky side bar and changing app bar heading level

[janfaracik]

(Apologies for long title - I truly couldn't think of anything shorter).

This PR brings native support for some of the app bar changes introduced in #6485, rather than the 'one-off' implementations in that PR.

What's changed

• App bars can now be applied to side panels and main panels
• Side panels can now be sticky (with a new class)
• You can now set the heading level for an app bar (e.g. change it to h2 from h1)

As a result of this the implementation of the app bar has changed, you now need to include it in either side panel or main panel (this may break a couple of plugins - I'll fix them).

This is the core change that jenkinsci/design-library-plugin#90 is waiting on, it essentially defines some clearer guidelines for when to use certain page layouts.

Downstream pull requests that need merging after this is released:

• job-config-history-plugin Move app-bar to main panel job-config-history-plugin#239
• credentials-plugin
  • v1 Move app-bar to main panel credentials-plugin#365
  • v2 Move app-bar to main panel credentials-plugin#366
• design-library-plugin - Add guidance on page layouts design-library-plugin#90

Proposed changelog entries

• Developer: Add support for the app-bar component in the sidepanel.

Proposed upgrade guidelines

N/A

Submitter checklist

• (If applicable) Jira issue is well described
• Changelog entries and upgrade guidelines are appropriate for the audience affected by the change (users or developer, depending on the change) and are in the imperative mood. Examples
  • Fill-in the Proposed changelog entries section only if there are breaking changes or other changes which may require extra steps from users during the upgrade
• Appropriate autotests or explanation to why this change has no tests
• New public classes, fields, and methods are annotated with @Restricted or have @since TODO Javadoc, as appropriate.
• New deprecations are annotated with @Deprecated(since = "TODO") or @Deprecated(forRemoval = true, since = "TODO") if applicable.
• New or substantially changed JavaScript is not defined inline and does not call eval to ease future introduction of Content-Security-Policy directives (see documentation on jenkins.io).
• For dependency updates: links to external changelogs and, if possible, full diffs

Desired reviewers

@jenkinsci/sig-ux

Maintainer checklist

Before the changes are marked as ready-for-merge:

• There are at least 2 approvals for the pull request and no outstanding requests for change
• Conversations in the pull request are over OR it is explicit that a reviewer does not block the change
• Changelog entries in the PR title and/or Proposed changelog entries are accurate, human-readable, and in the imperative mood
• Proper changelog labels are set so that the changelog can be generated automatically
• If the change needs additional upgrade steps from users, upgrade-guide-needed label is set and there is a Proposed upgrade guidelines section in the PR title. (example)
• If it would make sense to backport the change to LTS, a Jira issue must exist, be a Bug or Improvement, and be labeled as lts-candidate to be considered (see query).

[github-actions]

Please take a moment and address the merge conflicts of your pull request. Thanks!

[timja]

This looks great but plugins using it already need adapting

• job-config-history-plugin Move app-bar to main panel job-config-history-plugin#239
• credentials-plugin
  • v1 Move app-bar to main panel credentials-plugin#365
  • v2 Move app-bar to main panel credentials-plugin#366
• design-library-plugin - Add guidance on page layouts design-library-plugin#90

Example of what credentials plugin looks like atm:

[janfaracik]

This looks great but plugins using it already need adapting

• job-config-history-plugin
• credentials-plugin
• design-library-plugin

Example of what credentials plugin looks like atm:

Wondering if there's a workaround for this as if we move the app-bars into main-panel for plugins it'll only work for this release, older versions of Jenkins will be missing titles.

[timja]

/label ready-for-merge

---

This PR is now ready for merge, after ~24 hours, we will merge it if there's no negative feedback.

Thanks!

[daniel-beck]

I don't understand why this reuses the app-bar element in the sidepanel. Do we expect sidepanel content to also have associated buttons etc?

[daniel-beck]

"About Jenkins" is broken compared to 2.367:

[daniel-beck]

Per above

[github-actions]

Please take a moment and address the merge conflicts of your pull request. Thanks!

[uhafner]

I like these new ideas! I would recommend, that those views of this PR that now use these new pattern should be completely adapted before we merge this PR. Otherwise it is totally unclear for plugin developers what to do and what to avoid. These core views should be the template for everybody else on how to move forward!

Some elements that are not adapted:

• The side panel action name should be the same as the app bar title ("Updates", "Available Plugins" vs. "Plugins" or "Log Levels" vs. "Logger Configuration"). Maybe this can be done in the framework so I do not need to repeat
• The app bar does only sometimes contain the buttons (Add new logger is correctly in the app bar, Save button of Logger Configuration is at the bottom)

Some bugs:

• Log Recorders -> All Jenkins Logs break the sidebar completely (there is no sidebar anymore)
• Global Tool Configuration and Configure System (and the other elements of the manage screen) have no sidebar anymore

Missing feature:
One thing that I am totally missing: the new sidebar elements should not scroll if I scroll down the page. These parts should use separate viewpoints. It does not make sense to scroll the new sidebar anymore, it is up to the developer to restrict this size.

[daniel-beck]

the new sidebar elements should not scroll if I scroll down the page. These parts should use separate viewpoints. It does not make sense to scroll the new sidebar anymore, it is up to the developer to restrict this size.

@uhafner Could you clarify whether this only applies to sidepanels with app-bar, i.e., would there be some (most) sidepanels that scroll, and some that don't?

[uhafner]

the new sidebar elements should not scroll if I scroll down the page. These parts should use separate viewpoints. It does not make sense to scroll the new sidebar anymore, it is up to the developer to restrict this size.

@uhafner Could you clarify whether this only applies to sidepanels with app-bar, i.e., would there be some (most) sidepanels that scroll, and some that don't?

If possible, all side panels should not scroll with the content. (I'm not sure if this works for the Dashboard view with the side panel widgets). I see no reason why the "links-only" navigation bars should scroll with the content.

Concerns addressed

[janfaracik]

I don't understand why this reuses the app-bar element in the sidepanel. Do we expect sidepanel content to also have associated buttons etc?

I don't see why not really, there isn't a use case yet on Jenkins but it wouldn't hurt to share the same component to make updating both easier in the future.

---

• The side panel action name should be the same as the app bar title ("Updates", "Available Plugins" vs. "Plugins" or "Log Levels" vs. "Logger Configuration"). Maybe this can be done in the framework so I do not need to repeat

That's a very good idea 👍 Not too sure what the best way of doing that right now is, might require a new component I'm not too sure.

• The app bar does only sometimes contain the buttons (Add new logger is correctly in the app bar, Save button of Logger Configuration is at the bottom)

Not too sure on the best spot for 'Save'/'Apply' buttons right now. Thinking that they make more sense on the bottom as you interact with form elements before interacting with the 'Save' buttons.

Some bugs:

• Log Recorders -> All Jenkins Logs break the sidebar completely (there is no sidebar anymore)

• Global Tool Configuration and Configure System (and the other elements of the manage screen) have no sidebar anymore

Sidepanels have been removed from those pages as part of #6907 :) I've updated the 'All Jenkins Logs' pages to use a one column layout now so it should look better.

Missing feature: One thing that I am totally missing: the new sidebar elements should not scroll if I scroll down the page. These parts should use separate viewpoints. It does not make sense to scroll the new sidebar anymore, it is up to the developer to restrict this size.

If I'm understanding correctly, you'd want the sidebar to scroll separately to the main page contents/stick to the top if too short? If so I agree, need to sort out which pages should have side panels first before making a change like that though.

[timja]

re-tested, looks good to me

[NotMyFault]

Thanks for addressing and clarifying the outstanding feedback!

---

This PR is now ready for merge. We will merge it after ~24 hours if there is no negative feedback.
Please see the merge process documentation for more information about the merge process.
Thanks!