Skip to content

Commit

Permalink
feat(storybook): add a shared decorator for focus-state and static co…
Browse files Browse the repository at this point in the history 
…lor settings
  • Loading branch information
@castastrophe
castastrophe committed Jan 4, 2024
1 parent d8cba3e commit 400e282
Show file tree
Hide file tree
Showing 375 changed files with 3,715 additions and 6,127 deletions.
4 changes: 3 additions & 1 deletion .env.example
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
CHROMATIC_PROJECT_TOKEN=1234abcd
CHROMATIC_PROJECT_ID="Project:64762974a45b8bc5ca1705a2"
CHROMATIC_BUILD_SCRIPT_NAME="ci:storybook"
# Note: the build script here should be defined in .storybook/package.json
# this is used by the chromatic storybook addon to build the storybook on the fly
CHROMATIC_BUILD_SCRIPT_NAME="build"

# NX settings
NX_PREFER_TS_NODE=true
Expand Down
261 changes: 93 additions & 168 deletions .storybook/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ argTypes: {
_Note:_ In your story, be sure to include the `if: false` override otherwise the control will only show up if you have a `setName` arg and it is equal to `workflow`.
Want to load UI icons instead? Use the following variable import instead:
Want to load UI icons instead? Use the following variable import instead of the above:
```js
argTypes: {
Expand Down Expand Up @@ -205,6 +205,75 @@ label: {
},
```
### args
In a story, the args object contains all the default values for the component. These values will be used to render the component in the storybook preview. The values can be overridden by the user via the controls or by setting a custom args object in a specific story.
The default story should _almost_ always have any empty args object because it is, by nature, using all the default settings.
```js
export const Default = Template.bind({});
Default.args = {};
```
Subsequent stories can override the default args object by setting a new value for the desired property. i.e.,
```js
export const Express = Template.bind({});
Express.args = {
express: true
};
```
Try to focus stories on a single property or set of properties. This will make it easier for users to find the story they are looking for and will help in debugging issues.
#### customStorybookStyles
All stories are wrapped in a custom decorator that applies a few standard display properties to the preview. If you need to override these styles, you can do so by adding a `customStorybookStyles` property to your args object. This should be a string of CSS rules. i.e.,
```js
args: {
customStorybookStyles: {
flexDirection: "column",
alignItems: "flex-start",
},
},
```
The following properties are set on `#root-inner` by default:
```css
display: flex;
gap: 10px;
```
If the display property is updated to something other than `*flex` or `*grid`, the gap property will be removed (`*flex` can equal `flex` or `inline-flex`). As long as the display property is not `contents`, the gap value will be assigned to `padding` instead.
For example, if the display value is set to `block`, the following styles will be applied:
```css
display: block;
padding: 10px;
```
Leveraging an argType in your component that matches `staticColor` with allowed values of `white` or `black` will automatically set the background color of the preview to an appropriate value (white will use `rgb(15, 121, 125)`; black will use `rgb(181, 209, 211)`). If you need to override this value, you can do so by setting the `customStorybookStyles` property to an object with a `backgroundColor` property. i.e.,
```js
args: {
customStorybookStyles: {
backgroundColor: "rgb(238, 14, 189)",
},
},
```
Any settings added by the story will override these values. You can unset a value completely using undefined, i.e.:
```js
customStorybookStyles: {
display: undefined,
},
```
## Templates
The goal of the template files is to create a definition for this component to enforce and demonstrate the allowed semantics and required classNames and settings to achieve the desired output (based on the user's selected controls).
Expand Down Expand Up @@ -240,14 +309,14 @@ All return values for Template functions should be outputting TemplateResults. S
import { html } from "lit";
import { classMap } from "lit/directives/class-map.js";
import { ifDefined } from "lit/directives/if-defined.js";
import { when } from "lit/directives/when.js";
import { Template as Icon } from "@spectrum-css/icon/stories/template.js";
import { Template as Avatar } from "@spectrum-css/avatar/stories/template.js";
import { Template as ClearButton } from "@spectrum-css/clearbutton/stories/template.js";
import "../index.css";
// More on component templates: https://storybook.js.org/docs/web-components/writing-stories/introduction#using-args
export const Template = ({
rootClass = "spectrum-Tag",
size = "m",
Expand All @@ -272,37 +341,32 @@ export const Template = ({
console.warn(e);
}
return html`
<div
class=${classMap({
[rootClass]: true,
[`${rootClass}--size${size?.toUpperCase()}`]:
typeof size !== "undefined",
"is-emphasized": isEmphasized,
"is-disabled": isDisabled,
"is-invalid": isInvalid,
"is-selected": isSelected,
...customClasses.reduce((a, c) => ({ ...a, [c]: true }), {}),
})}
id=${ifDefined(id)}
tabindex="0"
return html`<div
class=${classMap({
[rootClass]: true,
[`${rootClass}--size${size?.toUpperCase()}`]:
typeof size !== "undefined",
"is-emphasized": isEmphasized,
"is-disabled": isDisabled,
"is-invalid": isInvalid,
"is-selected": isSelected,
...customClasses.reduce((a, c) => ({ ...a, [c]: true }), {}),
})}
id=${ifDefined(id)}
tabindex="0"
>
${avatarUrl && !iconName
? Avatar({
${when(avatarUrl && !iconName, () => Avatar({
...globals,
image: avatarUrl,
size: "50",
})
: ""} ${iconName
? Icon({
}))}
${when(iconName, () => Icon({
...globals,
iconName,
customClasses: [`${rootClass}s-itemIcon`],
})
: ""}
}))}}
<span class="${rootClass}s-itemLabel">${label}</span>
${hasClearButton
? ClearButton({
${when(hasClearButton, () => ClearButton({
...globals,
customClasses: [`${rootClass}-clearButton`],
onclick: (evt) => {
Expand All @@ -312,10 +376,8 @@ export const Template = ({
const wrapper = el.closest(rootClass);
wrapper.parentNode.removeChild(wrapper);
},
})
: ""}
</div>
`;
}))}
</div>`;
};
```
Expand All @@ -339,142 +401,5 @@ Runs will generate a JUnit XML file with build results (`chromatic-build-{buildN
Running without publishing to Chromatic? Add the `--dry-run` flag. Need more information to debug a run? Try the `--diagnostics` flag (writes process context information to `chromatic-diagnostics.json`).
# Migration to Storybook 7.0(Draft)
## Updates
---
`*` Added support for handler actions with ```withActions``` on each stories which have action handlers.
Example:
```js
import globalThis from 'global';
+ import { withActions } from '@storybook/addon-actions/decorator';
export default {
component: globalThis.Components.Button,
args: {
label: 'Click Me!',
},
parameters: {
chromatic: { disable: true },
},
};
export const Basic = {
parameters: {
handles: [{ click: 'clicked', contextmenu: 'right clicked' }],
},
+ decorators: [withActions],
};
```
`*` Upgraded to ```Webpack 5``` for improved bundling and performance from ```webpack 4```
`*` @storybook addons dependencies are upgraded to v7 from v6
```js
"@storybook/addon-docs": "^7.0.12",
"@storybook/addon-essentials": "^7.0.12",
"@storybook/api": "^7.0.12",
"@storybook/client-api": "^7.0.12",
"@storybook/components": "^7.0.12",
"@storybook/core-events": "^7.0.12",
"@storybook/manager-api": "^7.0.12",
"@storybook/preview-api": "^7.0.12",
"@storybook/theming": "^7.0.12",
"@storybook/web-components-webpack5": "^7.0.12",
"@whitespace/storybook-addon-html": "^5.1.4",
```
`*` Added a new "Controls" addon for interactive component props editing.
`*` Introduced a new "Docs-only" mode for isolating component documentation.
`*` Improved the addon ecosystem with new and updated addons.
<br></br>
## Breaking Changes
---
`*` client-api is deperacted and preview-api is introduced
```js
- import { useEffect } from '@storybook/client-api';
+ import { useEffect } from '@storybook/preview-api';
```
`*` @storybook/addons is deperacted and replaced with @storybook/manager-api
```js
- import { addons } from '@storybook/addons';
+ import { addons } from '@storybook/manager-api';
```
`*` ```@storybook-webcomponents``` is deprecated. ```@storybook/web-components-webpack'``` is added with webpack 5 support.
```js
- framework: '@storybook/web-components',
+ framework: {
name: '@storybook/web-components-webpack5',
options: {
fastRefresh: true,
builder: { lazyCompilation: true },
},
},
```
`*` Docs is now added to every component on the sidebar with the below code in Storybook 7
```js
docs: {
autodocs: true,
defaultName: 'Docs',
},
```
`*` preview.js is exported as default in Storybook 7
```js
- export const parameters = {
- actions: { argTypesRegex: '^on[A-Z].*' },
- };
+ export default {
+ parameters: {
+ actions: { argTypesRegex: '^on[A-Z].*' },
+ },
+ };
```
## Deprecations(Addons)
---
`*` ```"@storybook/client-api"``` is deprecated
`*` ```"@storybook/addons"``` is deprecated
## Bug Fixes
---
`*` Fixed various issues related to performance, rendering, and compatibility.
`*` Resolved problems with the Storybook UI, including layout glitches and navigation bugs.
`*` Fixed bugs in calender storybook
## Improvements
---
`*` Improved the overall performance and stability of the Storybook development environment.
`*` Enhanced the documentation with updated examples and guides.
`*` Optimized the build process for faster bundling and reduced file sizes.
`*` Upgraded dependencies to their latest versions for improved compatibility and security.
---
<!-- @todo Document the best practices for outputting multiple template examples in one view -->
<!-- @todo Document the best practices for chromatic-only stories and settings -->
21 changes: 15 additions & 6 deletions .storybook/assets/base.css
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
html,
body {
min-block-size: 100%;
}

body {
margin: 0;
font-size: 10px;
Expand Down Expand Up @@ -31,7 +36,7 @@ nav .spectrum-Site-logo {

.docblock-argstable-body td > span:has(select),
.docblock-argstable-body td textarea {
max-width: 280px !important;
max-inline-size: 280px !important;
}

#storybook-explorer-tree {
Expand All @@ -51,7 +56,7 @@ button.sidebar-item {
font-weight: 400 !important;
font-size: 14px !important;
line-height: 1.4em !important;
height: 32px !important;
block-size: 32px !important;
border-radius: 4px !important;
padding-inline-start: 24px !important;
padding-inline-end: 12px !important;
Expand Down Expand Up @@ -122,7 +127,7 @@ select:focus,
}

[role="main"] > div > div:first-child .os-content > div > div > * {
margin-top: 0 !important;
margin-block-start: 0 !important;
}

[role="main"] > div > div:first-child .os-content > div > div > div > a {
Expand Down Expand Up @@ -161,8 +166,8 @@ select:focus,
button::after {
content: "◢";
position: absolute;
bottom: -3px;
right: -1px;
inset-block-end: -3px;
inset-inline-end: -1px;
display: inline-block;
transform: scale(0.5);
color: rgb(177, 177, 177);
Expand Down Expand Up @@ -190,7 +195,7 @@ select:focus,
> div
> div
:is(button, a:not(:has(button)), span) {
height: 32px;
block-size: 32px;
}

[role="main"]
Expand All @@ -202,3 +207,7 @@ select:focus,
:is(button:hover, a:hover:not(:has(button))) {
background-color: rgb(230, 230, 230) !important;
}

.docs-story #root-inner {
margin: 10px;
}
Loading

0 comments on commit 400e282

Please sign in to comment.