docs: storybook upgrade & renovation

[KaiVandivier]

This is a project to take advantage of new Storybook features to renovate the UI library documentation and make it a more useful tool for readers.

Relates to this proposal at the 'notes' repository

[cooper-joe]

Great stuff @KaiVandivier, thanks for putting this all together.

Some suggestions:

1. Page titles
I think it might be useful to prepend the page titles with ui –, as the DHIS2 logo favicon is used in other situations too, so having the ui – prefix would further clarify what DHIS2 domain this is.
In that case, page titles would look like: ui – actions/button, ui – data display/stacked table.

2. Change "Stories" page heading
Most component pages contain the heading "Stories". This is an internal storybook-specific term and doesn't have any meaning to the components. If this is possible to change, I'd suggest "Variants" instead, which more accurately describes the content.

3. Adjust section titles
I think the sidebar sections could be more descriptive. I suggest:

• Adding a heading for the "...for readers" and "...for maintainers" pages, with the title "About this documentation"
• Change the "Tips for readers" page title to just "For readers"
• Change the "Tips for maintainers" page title to just "For maintainers"
• Change 'UI docs" heading to "Using UI"

4. Custom styles
Am I correct in thinking the only styles we can adjust are those exposed in theme.js? There are some other changes I'd like to make (document link color contrast is not accessible, sidebar headers are difficult to read), but there doesn't seem to be any options available. Any workaround for this?

[KaiVandivier]

Thanks for the great suggestions Joe!

1. Sounds good - I'm looking into how to change the page titles
2. Agreed - I tried to avoid storybook-specific vocabulary in the page for readers too. Would 'Examples' also work for that section heading?
3. 👍
4. It turns out pretty much everything on the page can be configured style-wise: CSS escape hatches

[Mohammer5]

Is the dropdown placement for Selects and Poppers a bug with the component, or a quirk of the Storybook Docs Page? @HendrikThePendric @Mohammer5

Sorry, I didn't see this before.. Could you elaborate what what is going wrong? I just took a brief look at the first single select story's docs tab and it seems to work fine in the iframe?

[KaiVandivier]

@Mohammer5 In the SingleSelect, iframe works around the issue; try looking at SingleSelectField demos on the docs page (which don't use an iframe) - the first demo will usually work, but clicking on one of the later demos opens up the dropdown somewhere else on the page, and you will have to scroll up to see it

[cooper-joe]

2. Agreed - I tried to avoid storybook-specific vocabulary in the page for readers too. Would 'Examples' also work for that section heading?

Yeah, I think Examples is probably a good catch-all, it works even when the examples are not strictly 'variants'.

4. It turns out pretty much everything on the page can be configured style-wise: [CSS escape hatches](https://storybook.js.org/docs/react/configure/theming#css-escape-hatches)

Ok, interesting! I think it's best to keep the scope of this PR as narrow as possible, so I can address the visual style changes I have in a future PR. Perhaps you could include the escape hatch functionality in this PR with a blank stylesheet? Then I can add to it in future.

[KaiVandivier]

Perhaps you could include the escape hatch functionality in this PR with a blank stylesheet? Then I can add to it in future.

Will do! 👍

[KaiVandivier]

Updates:

1. Changed 'meta documentation' page titles and section names
2. Renamed 'Stories' heading to 'Examples' in docs pages
3. Added files for styling the UI with CSS escape hatches: ./storybook/static/manager.css and ./storybook/static/preview.css, linked by manager-head.html and preview-head.html, respectively
4. Document titles: not easy to change, surprisingly -- I'm still looking into it

[KaiVandivier]

The document title might be solved by writing an addon, but that might be best done in another pull request 🤔

[varl]

On the whole, I think this is an improvement that is worthy to go in. Parts that need to change can be dealt with in smaller PRs.

[cooper-joe]

Thanks for making the requested changes. This looks good! I'll be making some separate PR's to deal with minor styling and aesthetics that I noted.

[amcgee]

🎉 great stuff @KaiVandivier !

[dhis2-bot]

🎉 This PR is included in version 6.5.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• npm package (@latest dist-tag)
• npm package (@latest dist-tag)
• npm package (@latest dist-tag)
• npm package (@latest dist-tag)
• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀