Combine Storybooks

[stephiescastle]

The scope of this task has changed from when it was originally created. The old proposal has been collapsed at the end of this comment for record-keeping purposes.

Strategy: include internal and external stories as html templates, similar to what we've done for the rest of Explorer 1 already.

See the below comment for details and continued discussion on this revised scope.

📜 Old proposal using Storybook Composition

https://medium.com/storybookjs/storybook-composition-af0da9084fba

Proposal

Three storybook codebases

• Explorer 1 Design system (this repo)
• WWW
• WCP

Use Storybook's Composition feature to make one storybook

Following the model in this article, the Design System storybook (this repo) will be the "main storybook" that composes the storybooks into one.

High-level task list

If this works and we agree on this architecture, here's a very high-level task list:

• move @jpl/explorer-1 to public npm registry (in progress)
• add storybook to @jpl/explorer-1, ideally with the same add-ons and utilities as WWW (in progress)
• refactor WWW to use @jpl/explorer-1. WWW-specific components can stay in the WWW storybook (in progress)

Possible follow-up tasks

• deploy the WCP storybook beyond the firewall, and import stories as "internal only"
• import WWW stories as "external only"
• OR, include internal and external components as HTML (see comment below)

Additional research needed

On paper this seems feasible, but we need to explore a few things to get a better handle on the effort needed. The below items are not blockers, just a list of things to try/think about how we'd approach it.

• test if this works with storybook-django. If not, determine what needs to change about storybook-django to make this work. Can do a quick proof of concept using the WWW storybook and the storybook-django demo site
• determine strategy for moving Vue components out of WWW into the design system (see Add Vue components #8. We don't want to have this architecture be prohibitive to improving WWW (i.e. we may want to have graphql queries live with each component). This concern may be a non-issue, or it might be too early to tell. It's possible we'll soon want to refactor all of our components using Vue's composition API or something.
• explore if we can use storyshots with the composed storybooks (minor)
• can specific stories be imported instead of everything?

[stephiescastle]

Update: this comment refers to the out-of-date strategy of using Storybook Composition

Old comment

test if this works with storybook-django

Works ✨

Tested locally while running the WCP storybook locally (i.e. http://localhost:7000). Works with all story types: CSF, storiesOf and mdx, though the order of stories isn't consistent with the standalone WCP storybook.

We will need to resolve CORs issues once we deploy. We should also keep in mind where all of these codebases will live, and where the main storybook will live (external vs internal, both in terms of hosting and github repo).

[stephiescastle]

Possible follow-up tasks

• deploy the WCP storybook beyond the firewall, and import stories as "internal only"
• import WWW stories as "external only"

I think another approach would be to manually include these stories as html templates as we've done for the rest of Explorer 1 already.

We originally didn't want to do this for the following reasons:

• building multiple versions of the same component
• requires more maintenance

Advantages to a manual HTML approach:

• We will have complete control over how to display and organize these stories in the main storybook
• This would establish Explorer-1 as the gold source for everything, and we'd be beholden to that as well. Currently, our gold source for external components are the Vue components in WWW. Our gold source for internal components are the Django components in WCP. If we keep our gold source for everything as HTML, then we have a consistent way of presenting the design system as a whole

Importing stories automatically in storybook has the following limitations:

• Imports all stories from the imported storybook, including base components, etc, which results in duplicate stories
• The order and organization of imported stories isn't easily customizable, and also doesn't match the standalone storybook
• We will need to resolve firewall issues so that our Explorer-1 storybook can access the internal storybook.
• We will need to resolve CORS issues to allow our Explorer-1 storybook to access the other storybooks.

[stephiescastle]

More questions to consider, after conversations about adding the header and footer in #172:

• What would be the ideal way to organize our internal and external components?
• How do we want to reflect the blue link/button color for internal usage? Should that live in Storybook, or is that more about policy? The current way we achieve this is by adding CSS overrides to the internal site's SCSS imports.

[Scotchester]

More questions to consider, after conversations about adding the header and footer in #172:

• What would be the ideal way to organize our internal and external components?

I think there are several approaches that could work, but my first instinct would would do something like HeaderExternal and HeaderInternal, at least for cases where there will be two very different versions of a component. If the differences are just styling… (cont'd below)

• How do we want to reflect the blue link/button color for internal usage? Should that live in Storybook, or is that more about policy? The current way we achieve this is by adding CSS overrides to the internal site's SCSS imports.

I would probably control that with a parent class (like the way that the nascent dark mode is activated) and instruct internal sites to apply it to their <body> element, or possibly by providing an internal.css file that overrides the default color variables and instructing internal users to include that in their build. (We could also compile an explorer-1.internal.min.css for those who want to just drop in with no build.)

[stephiescastle]

I think another approach would be to manually include these stories as html templates as we've done for the rest of Explorer 1 already.

Update: during sprint planning on April 12, 2022, devs are in agreement that this approach is the way to go.

[stephiescastle]

Repurposing this issue to capture the need to set up infrastructure for internal and external components.

• component organization
• internal-only styles (ex: apply a body class)