[RFC] Story Globals

[shilman]

Status: in-review; championed by @shilman

Summary

We propose a new field for stories, globals, that allow you to set a context value such as a theme or locale or viewport for that story.

Problem Statement

Storybook globals are the recommended way to store global state such as theme, locale, or viewport. Globals are typically modified by toolbar menus in the UI and they persist across stories.

The problem is that it's not easy to make a story that renders with a specific configuration of globals. For example, if you want a story that always renders in the dark theme to show off a special "dark mode" look or behavior.

You can do this by hand by navigating to the story and selecting "dark" theme via the toolbar menu. However, there is no direct way to do this programmatically.

Non-goals

There are addons, such as Backgrounds and React-intl that use a complex workaround and should be updated to use the new feature.

There are addons, such as Viewport, that don't use globals at all, but should.

All of these addons should be updated, but that's out of scope for this project.

Implementation

To set the globals automatically for a specific story, we propose a new field called globals:

export default { component: Button }

export const Primary = { args: { label: 'Primary', primary: true } }

export const DarkPrimary = {
  ...Primary,
  globals: { theme: 'dark' } // <-- New field
}

This is equivalent to manually selecting the dark theme in the toolbar UI BEFORE navigating to the DarkPrimary story.

It does not change any other aspect of globals behavior. So, for example, if you are in light theme and navigate to the DarkPrimary story, it will set the theme to dark. The theme will stay dark until you set the global manually in the UI, or until you set it programmatically to another value in another story.

Prior Art

Some addons use parameters to achieve this behavior. But this is a convoluted workaround for not having a direct way to set globals in stories.

Examples:

• Backgrounds
• React-intl

Deliverables

• Add a new globals field to @storybook/csf types
• Add logic to update the Storybook store using the new globals field
• Add stories/tests for the new behavior
• Document the new field and its behavior

Risks

No response

Unresolved Questions

• There is currently a field globals in preview.js which stores the values for globals in a Storybook ONCE on startup. This behavior is inconsistent with the new proposed Story globals field, which stores the values before navigating to a story which specifies globals. How should we resolve this, if at all?
• If globals behaved in a "storybook-like" way, we would also be able to set globals at the component-level and these values would cascade at the story/component/project like parameters do. Do we want this?

Alternatives considered / Abandoned Ideas

No response

[domyen]

How would this work with the idea of a "default"?

For example, the viewports addon has defaultViewports which automatically sets a story's viewport to a specific dimensions. However, the viewport resets when you navigate to a new story (presumably because that next story doesn't have a defaultViewport.

If I'm reading right, theme: "dark", will persist the globals. For situations where you have stories like Histogram: default and Histogram: default dark, you'd have to manually click on the global tool in order to switch out of the dark theme. I could see that being pretty cumbersome as you switch between stories, especially when multiple globals are set.

[shilman]

The current proposal does not change the behavior of globals today. Globals are stateful across stories, so if you change the theme to "light" and browse around, all of your stories will render in the "light" mode until you switch to "dark" either manually in the UI or by navigating to a story that sets it to dark.

There's a version of this proposal -- alluded to in the "unresolved questions" section but not explicitly proposed -- where globals cascade between stories/components/project settings and we change the behavior of project-level globals to match the proposed behavior of story globals (a breaking change).

So in your example, you would set { theme: 'light' } in .storybook/preview.js and every time you navigated to a new story, it would show it in "light" mode by default. If you override { theme: 'dark' } in the Histogram: dark story, it will show in dark mode when you navigate to it. But when you navigate to another story, it would set the theme back to "light" (unless the component/story had overridden the default).

In summary:

• The current globals semantics prioritizes the toolbar UI over everything else and you have to jump through hoops to do anything programmatically.
• This RFC keeps the same semantics but makes it easier to set globals at the story level
• The proposal in this comment breaks the semantics but gives a lot more programmatic control and supports the concept of "defaults" like viewports. It also supports the current semantics if you don't set a default value. But it's a breaking change.

@domyen would this satisfy your use case?

@tmeasday also has thought a lot about this behavior, so I'm curious what he thinks.

[domyen]

I think setting globals at the top level preview.ts and cascading down would satisfy this use case. In learning/docs, we'd have to be very explicit when you start using globals that you should set defaults in preview.ts

For example, I believe the pattern @integrayshaun used in a recipe for setting up a theming globals is compatible with what you suggested:

// .storybook/preview.js
import { createGlobalStyle, ThemeProvider } from 'styled-components';
import { withThemeFromJSXProvider } from '@storybook/addon-styling';

import { lightTheme, darkTheme } from '../src/themes';

/* snipped for brevity */

export const decorators = [
  withThemeFromJSXProvider({
  themes: {
    light: lightTheme,
    dark: darkTheme,
  }
  👉 defaultTheme: 'light',
  Provider: ThemeProvider,
})];

[tmeasday]

I don't think this is the right solution to the problem, because it would mean setting a global at the project level would result in the toolbars no longer having an effect.

My suggested solution to this problem:

1. Rename the story/component level key to forceGlobals or globalOverride or similar
2. When you visit a story with that property set, the toolbars addon will disable toolbars for any overridden global[1]
3. When you browse away from the story, the overriden global "goes back" to the previous stateful value.

[1] Any addon that has it's own globals should do the same, e.g. viewports.

[jpzwarte]

From a users' point of view, I think @tmeasday's suggested solution would best match my expectation of how Storybook should behave wrt globals in stories.

[tmeasday]

I actually have this on my TODO list for this week 🚀

[tmeasday]

I have a PR that implements the globalOverrides solution I proposed above.

As part of that PR, @shilman and I were discussing removing the existing parameter-driven behaviour for the same effect from the viewport and backgrounds addon. There are couple of things to consider here:

Viewports

1. You can set a defaultViewport parameter. This has the behaviour of changing the current selected viewport.

2. You can set a list of allowed viewports in a parameter. If that doesn't include the current viewport, it'll try and find another to render:

• the first viewport has the default field set
• else 'responsive'

When this happens it doesn't change the global, meaning when you change stories it'll "revert" to the old global value (like globalOverrides do).

Backgrounds

You can set a list of allowed backgrounds via a parameter.

If the current value isn't in that list, it'll use the default (set via a parameter) in a similar way to the fallback viewport in case 2 above.

---

So:

• There's a bit of an odd inconsistency here in the behaviour of defaultViewport. It feels like the name "default" isn't super clear as to what it means. We'd be happy to make things more consistent here with globalOverrides.

• However globalOverrides don't allow you to limit the list of available items in a list and provide a default if an incompatible option is selected when you browse to the story, which is a feature of both addons.

There's two ways we can go here:

• Deprecate, and eventually drop the ability to restrict the available viewports or backgrounds on a per-component or story basis.

• Add a second feature to allow restricting a global per-story, and specifying a fallback if inconsistent with current value. This could be done via cascading globalTypes (or possibly calling it globalTypesOverrides).

[shilman]

Or we could just go with a fixed argTypes globalTypes schema and lose the ability to change it dynamically based on the current story. This seems unnecessarily complicated to me and my inclination would be to keep things simple unless people are screaming at us for this feature.

[tmeasday]

@shilman I assume you mean globalTypes schema. I'm not quite sure what you are advocating for though. Questions:

1. Would that mean we lose the ability to restrict backgrounds/viewports per story?

unless people are screaming at us for this feature

I guess they wouldn't be screaming ... yet ;)

2. What would you call globalOverrides? Persist with the current name? Rename to globals despite the inconsistency with project-level globals?

[shilman]

@tmeasday

1. Edited. Yes we'd lose the ability to restrict per story. This is a lot simpler!
2. I don't feel strongly about the naming. I guess having preview "globals" and story "globals" get the same name implies cascading where there is none. Perhaps in a perfect world we'd replace preview globals with initialGlobals OR globalTypes.x.initialValue and then call the story globals globals. The former might be an easy codemod.

[JReinhold]

tl;dr I agree with @tmeasday idea:

We should lean into globalTypes, and potentially implement:
a. globalTypes.foo.overrideValue -- instead of globalOverrides.foo.
c. globalTypes.foo.initialValue in project.ts to set the first value for a global (also possible to override at the story level but with questionable utility).

My mental model for preview vs story is that everything cascades and behaves the same on all layers. I know that globalTypes doesn't do that today (I think it should though) but it means we can't really re-use globals since it needs to do two very different things on a story and a preview level to be useful:

A. It wouldn't be useful for a story-level globals to behave like preview-level globals behave today - it needs to override the user's choice.
B. It also would be annoying if both story and preview did that - it would mean that a user choice would be reset whenever a user navigated to a new story.

That's why I like globalTypes.foo.initialValue and globalTypes.foo.value. They do these two different things (A and B) they can cascade to adhere to the mental model (it probably rarely makes sense but it should work).

I like globalTypes.foo.value over globalTypes.foo.overrideValue because its shorter but communicates the same thing to me. Two questions though:

1. Can globalTypes.foo.value/overrideValue be changed by a user or is it locked in the story?
2. If it can be changed, what happens when a user changes it, navigates to another story and back again? Is it reset or the changed?

Personally I'd say that users can still change it and navigating back to the story will put it back to the value the user changed it to - because this is exactly how args work today.

c. globalTypes.foo.initialValue in project.ts to set the first value for a global (also possible to override at the story level but with questionable utility).

How does globalTypes.foo.initialValue differ from globalTypes.foo.defaultValue that we already have today? Typo, or am I missing something?

b. globalTypes.foo.allowedValues & globalTypes.foo.fallbackValue -- to regain the viewports/bgs restriction feature.

I don't know the full context or usage here, but this feels very niche to me and not something we need to support unless users really complain and describe good use cases.

We deprecate / move away from a globals annotation entirely.
a. Alternatively we just make it clear that globals.foo is a shorthand for globals.foo.initialValue.

No strong feelings here. Deprecating/removing globals is annoying to users, keeping it as a shorthand is a confusing API IMO.

Side-note: If we did all of this it would mean that some properties of globalTypes would be valid on a story-level while others wouldn't. Ie. I guess you can't define a new globalTypes.bar in a story, or change globalTypes.foo.toolbar, which I think is unfortunate. But I also understand that supporting that is pretty hard and could expand the scope too much.

[tmeasday]

Thansks @JReinhold I think we are mostly aligning here. Some notes:

Can globalTypes.foo.value/overrideValue be changed by a user or is it locked in the story?
Personally I'd say that users can still change it and navigating back to the story will put it back to the value the user changed it to

I think it's a whole new feature to have "per story persisted globals". My reaction is the utility vs confusion tradeoff feels off there. ie. I think it'd be quite easy to misunderstand what's happening and constantly feel surprised by what happens to globals as you browse around. I'm definitely on the side of keeping it simple in this respect.

My rationale is - if you have a story that's specific to one global, it means it doesn't make sense to change it. If it makes sense to change it, why pick one value? You can always link to the story with the global selected.

How does globalTypes.foo.initialValue differ from globalTypes.foo.defaultValue that we already have today? Typo, or am I missing something?

It's clear from the differing functionality that "default" is ambiguous (in globalTypes it sets the "initial" value, in viewports it "changes" the value, in backgrounds it is a "fallback"). But it probably doesn't make sense to move away from the existing globalTypes.foo.defaultValue key I suppose.

I don't know the full context or usage here, but this feels very niche to me and not something we need to support unless users really complain and describe good use cases.

This is the functionality in backgrounds and viewport where you can restrict a story to only be viewable in a certain subset of backgrounds or viewports.

I think we are coalescing towards removing that, and just allowing you to fix the bg/viewport to single value for a story (via overrides). This is much simpler both in implementation and conceptually. If folks have strong feelings that differ hopefully a deprecation period will flush that out.

No strong feelings here. Deprecating/removing globals is annoying to users, keeping it as a shorthand is a confusing API IMO.

I'm inclined to leave it. Probably better not to change things unless we all feel strongly.

Side-note: If we did all of this it would mean that some properties of globalTypes would be valid on a story-level while others wouldn't. Ie. I guess you can't define a new globalTypes.bar in a story, or change globalTypes.foo.toolbar, which I think is unfortunate. But I also understand that supporting that is pretty hard and could expand the scope too much.

True. Will ponder that a bit.

Right now we are only suggesting adding one field you can override at the story level (globalTypes.foo.value), with the possibility of maybe supporting others in the future (allowedValues, fallbackValue). I'm on the fence about whether we should plan for more (and use globalTypes) or for what we have (which would push me towards just using globalOverrides, a separate namespace).

[shilman]

Here is an alternative proposal that combines @tmeasday 's proposed UI behavior with an args-style cascading semantics

Let's consider the following preview.js:

// preview.js
export default {
  globals: { theme: 'light' },
}

There are a few cases to consider:

UI mode

1. what is the behavior when the user sets the theme from the toolbar UI?
2. what is the behavior when the user navigates to a story that does not set the theme?
3. what is the behavior when the user navigates to a story that does set the the theme?

Test mode

1. what is the behavior when testing a story that does not set the theme?
2. what is the behavior when testing a story that does set the theme?

Current behavior

Semantics

• preview.js globals specifies the initial value
• There is no stylized way to specify theme at the story level, but it is achievable via parameters and a custom addon that updates the global value via a parameters setting

UI mode

1. When a user sets the theme in the UI, it updates the currently set value.
2. When a user navigates to a story that does not set the theme, it uses the currently stored value
3. When a user navigates to a story that does set the theme, it updates the currently stored value

Test mode

1. When a user tests a story that does not set the theme, it uses the initial value as specified in preview.js because each test should be run in isolation
2. When a user tests a story that does set the theme, it uses the story's theme value

Proposed behavior

Semantics

• preview.js globals is deprecated and replaced with initialGlobals
• Users can specify globals at the component/story that has similar cascading semantics to args
• We may restore preview.js globals in 10.0 after the globals => initialGlobals migration is complete

UI mode

1. When a user sets the theme in the UI, it updates the currently set value.
2. When a user navigates to a story that does not set the theme, it uses the currently stored value
3. When a user navigates to a story that does set the theme, it uses the story's value but does not update the currently stored value. It also disables the theme selector in the toolbar while you're on that story.

Test mode

1. When a user tests a story that does not set the theme, it uses the initial value as specified in preview.js because each test should be run in isolation
2. When a user tests a story that does set the theme, it uses the story's theme value

Argument

The semantics has changed so technically this is a breaking change. However:

1. The test mode behavior has not changed, so tests shouldn't break
2. The UI mode behavior is a breaking change, but this proposal substantially changes the UI behavior ANYWAY, so it is an acceptable breaking change for a minor release.

To mitigate the impact, we could also add a new annotation initialGlobals or globalTypes.x.initialValue and automigrate current globals to that.

[tmeasday]

To put the proposed UX another way, (& being intentionally vague about the names, see further discussion below):

In SB

We have 3 "layers" of globals defined:

1. The "initial globals" defined via a CSF annotation, at the project, component or story level.
2. The "globals state" as reflected in the URL bar (also stored in local storage) on a user's machine.

• Note this is the layer that is changed by the toolbars etc.

3. The "overridden globals" defined by a different CSF annotation, and a component or story level [no real reason to override at the project level]

The lower layers override the higher layers any time we render a story.

Outside SB (eg. in tests)

There is no layer 2 or statefulness of any kind.

So layer 3 & layer 1 essentially behave the same (unless you define both, in which case 3 overrides 1), meaning there's no reason to prefer one over the other.

What should we call the annotations (layers 1 & 3)?

Proposal 1: globals and globalOverrides

The issue here is that it is easy to set globals on a story, visit that story, and expect to see that global. You might be surprised in SB that it's acting as an "initial global".

NOTE: that is what will happening in at testing context, so this won't break anyone's tests.

Proposal 1: initialGlobals and globals

This naming probably makes more sense for SB, as it's clear that "initial globals" don't last.

When writing a test and not thinking about SB, you'd likely set globals, not initialGlobals. This might mean when you then looked at the global in SB you'd be surprised that the value was fixed and unchangable.

That's not necessarily an issue as that's what'll end up being set on the context anyway.

[Alternatively globalTypes.X.initialValue rather than initialGlobals].