CSF: Allow overridding globals at the story level

[tmeasday]

Closes: #23347 #27709 #27524 #27523

What I did

• Change the behavior of globals so that userGlobals and storyGlobals are separate in state.
  • userGlobals are globals set via toolbars/addons etc. These are dynamic and change-able.
  • userGlobals are initialized using initialGlobals.
  • storyGlobals are set via a .globals property on the meta or story inside *.stories.* files.
  • storyGlobals are fixed in place, and cannot be changed.
• initialGlobals is introduced as a concept.
  • These can only be set in a preview.* file. Addons can set them too.
  • initialGlobals are used to determine if a global's value should appear in the URL or not.
• globals is still available and results from shallow-merging userGlobals and storyGlobals.
• the useGlobals hook now return a third value: storyGlobals.
• decorators now receive an extra context property: storyGlobals.

---

• Adddon Viewport is configured slightly differently (see MIGRATION.md).
• Addon Backgrounds is configured slightly differently (see MIGRATION.md).
• Addon Themes now has an extra parameter disable, allowing the disabling of the tool per story.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

1. Create & run a sandbox
2. Visit localhost:6006/?path=/story/lib-preview-api-globals--overrides to see basics
3. Visit localhost:6006/?path=/story/addons-toolbars-globals--override to see toolbar behaviour
4. Test of the background & viewport addon (they use globals)
5. in the sandbox follow this migration:

   storybook/MIGRATION.md

   Lines 429 to 463 in 6141b5b

   	// .storybook/preview.js
   	export const parameters = {
   	backgrounds: {
   	- values: [
   	- { name: 'twitter', value: '#00aced' },
   	- { name: 'facebook', value: '#3b5998' },
   	- ],
   	+ options: {
   	+ twitter: { name: 'twitter', value: '#00aced' },
   	+ facebook: { name: 'facebook', value: '#3b5998' },
   	+ },
   	},
   	};
   	```
   	Setting an override value should now be done via a `globals` property on your component/meta or story itself:
   	```ts
   	// Button.stories.ts
   	export default {
   	component: Button,
   	globals: {
   	backgrounds: { value: 'twitter' },
   	},
   	};
   	```
   	This locks that story to the `twitter` background, it cannot be changed by the addon UI.
   	### New parameters format for addon viewport
   	> ! You need to set the feature flag `viewportStoryGlobals` to `true` in your `.storybook/main.ts` to use the new format.
   	The `addon-viewport` addon now uses a new format for parameters. The `viewport` parameter is now an object with a `viewports` key that contains the viewport values.

6. Now test backgrounds and viewports again
   • take note that the URL should not contain the property/value when the value matches the initialGlobal
   • you should be able to setup initialGlobals in preview.ts and change the default value. example:

     export const initialGlobals = { viewport: { value: "phone" } };

7. Test the inheritance of globals by
   • setup a initialGlobal value
   • set the same global on a meta
   • set the same global on a story
   • expect to see the value set on the story
   • disable the value on the story, and expect the meta's value to be shown.
8. Test the new context values by creating a decorator:

   export const decorators = [(StoryFn, { globals, storyGlobals, userGlobals }) => {
   	console.log({ globals, storyGlobals, userGlobals });
   	return Story();
   }];

   This should show the correct info when navigating stories, and changing globals

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This pull request has been released as version 0.0.0-pr-26654-sha-49d01553. Try it out in a new sandbox by running npx storybook@0.0.0-pr-26654-sha-49d01553 sandbox or in an existing project with npx storybook@0.0.0-pr-26654-sha-49d01553 upgrade.

More information

Published version	0.0.0-pr-26654-sha-49d01553
Triggered by	@ndelangen
Repository	storybookjs/storybook
Branch	tom/23347-story-globals
Commit	49d01553
Datetime	Fri Aug 2 11:46:36 UTC 2024 (1722599196)
Workflow run	10215034516

To request a new release of this pull request, mention the @storybookjs/core team.

core team members can create a new canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=26654

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 49d0155. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 1 target

• nx run-many -t build --parallel=3

---

Sent with 💌 from NxCloud.

[shilman]

This is great! We might want to do the other addons in a separate PR or separate PRs to scrutinize each one a little more.

[kylegach]

Fwiw, I'm good with the globalOverrides name. It's perhaps a bit clunky, relative to globals, but I think it's necessary to communicate that the behavior is different.

@tmeasday — Should this PR contain docs?

[valentinpalkovic]

What are the implications on the docs page? Currently, it seems that globally set globals via the toolbar either don’t have an effect, are invisible in doc mode, or are applied to all stories simultaneously. Is it considered to apply story-specific globals also on the docs page (especially for autodocs)? How do we/addon authors communicate if particular globals only apply in the story view and not in the docs view?

[tmeasday]

@valentinpalkovic:

If a story sets story.globals, what happens in docs mode?

1. Currently story.globals only triggers a GLOBALS_UPDATED event (and thus changes a toolbar for instance) if the story is selected (ie in story mode). So visiting a docs page with an overridding story would have no effect on toolbars.

2. However, the story itself will get rendered (in docs mode) with the overridden global. You can see that if you visit https://630511d655df72125520f051-xlmbsytljj.chromatic.com/?path=/story/lib-preview-api-globals.

How do we/addon authors communicate if particular globals only apply in the story view and not in the docs view?

I think generally speaking globals do apply in docs view. It would only be specific addons (the one I am thinking of is viewports) that do things in the manager that don't "work" in docs mode.