Intro to Storybook Component Story Format and args

[00:00 - 00:05] So, we've seen our Storybook and its stories. We have a button, a header, and a page.

[00:06 - 00:17] But what exactly makes up a story? Well, it's first of all important to understand that Storybook follows a format called "Component Story Format" which is an open standard based on ESX modules that is portable beyond Storybook.

[00:18 - 00:27] That means that other tools can take advantage of the same format and you have interoperability across technologies. So if we look at this, let's say the button components, we have the button.

[00:28 - 00:30] story_csx file over here. And let's make this bigger.

[00:31 - 00:44] The CSF format consists of, first of all, a default export which we call the meta. And the default export is where you actually define the title of your component which will be reflected on the sidebar.

[00:45 - 00:53] We pass the component so that Storybook uses it internally to get a lot of information. And then we can pass extra information which we'll get into detail later.

[00:54 - 01:11] The second aspect of a CSF file is that it has to have named exports and those named exports are expected to be a story of which could be composed of a render function and some extra annotations. Remember, a story is nothing more than a combination of a component and some extra annotations.

[01:12 - 01:22] And if you look at this, there's like template.bind but what exactly does this mean? Well, essentially, you could easily just define a render function directly in your stories like this.

[01:23 - 01:33] But that also means that you're just repeating code over and over. So the idea of the template is to essentially create a master template of which you define this function which will render your component.

[01:34 - 01:42] And then you can reuse it by cloning that function as well as adding some extra annotations. So what exactly are these arcs things that we see here?

[01:43 - 02:05] So Storybook has a construct called arcs which you could think of something similar than let's say, props but it's used extensively in many parts of Storybook. So given that our render function receives arcs and passes them down to the button as props, by setting primary.arks and putting these things, the primary story will receive those props and the component will render accordingly.

[02:06 - 02:15] So using that logic, let's create a new story and let's set a background caller . Let's say this would be background caller and let's set it as a red.

[02:16 - 02:21] We call the story red, let's say, and once we save it, Storybook will add it to the sidebar. And then there you go.

[02:22 - 02:32] We have a component which is rendering by receiving the label button and then the background caller is red. And like I mentioned before, the arcs are actually used by other tools inside of Storybook.

[02:33 - 02:47] So if we actually open up the panel of add-ons, we could either click here or just press A. We see that there's an add-on called controls and add-on controls detects the arcs for a given story and provides this panel where you can tweak with them.

[02:48 - 02:53] So over here we see, okay, initial value of background caller is red. However, I can actually play around and set it to something else.

[02:54 - 03:04] And that's pretty useful for especially designers to check whether component is correct. So we could basically play around and the component will re-render with those new props.

[03:05 - 03:16] And as you can see in this panel, we have different kinds of controls per prop. So primary is a boolean, a size is actually a radio group and the background caller is a caller picker.

[03:17 - 03:21] But how does that actually work? Well, that comes with another concept called art types.

[03:22 - 03:31] So each of these arcs, they have types such as a string or a boolean or etc. And the control add-ons uses these types to provide you the correct elements in its panel.

[03:32 - 03:43] These types are called art types and they are automatically processed by Story book by using the component which we declared in the meta, which is why we should always declare the component there. And from that, it was able to infer all of these things.

[03:44 - 03:55] However, a background caller, given that we are just setting it this as a string, it can't really be turned into a caller picker unless we set something more complex. So we can do so by defining art types.

[03:56 - 04:07] So if you see in the meta, this was already set in the template. So we're defining the art types for the components of which if you have a prop called background caller, use a control of type caller.

[04:08 - 04:23] And it's interesting that art types by being set on the level of meta, which is basically the component level, they will be applied automatically in each and every story . However, you can also manually set art types to a very specific story, such as the red story.

[04:24 - 04:35] So as an exercise, let's set art types to make the background caller only a select number of colors. So we start by defining the art types property under red.

[04:36 - 04:56] As you can see here, we have auto-completion from the types which is coming from our component story type here. So we set background caller to have a control, let's say inline radio, as well as some options, which is an array of, let's say, red, green, as well as blue.

[04:57 - 05:03] So now we see that component is rendering in red and we only have these three options. So green and blue.

[05:04 - 05:10] And if we check other stories, the background caller is still a caller picker. So that's pretty much how these things work.

[05:11 - 05:24] You can define arcs, which will be passed down to your components as props, and you can define the types of them either manually or they will be automatically inferred by storybook. And another interesting aspect of arcs is that arcs are cascading.

[05:25 - 05:36] And that pretty much means that you can define arcs on the story level, but you can also define arcs at the component level in meta. So if you define arcs over here, it will be applied to every single story.

[05:37 - 05:48] And if we analyze our stories, actually, we see that label button is added in pretty much every single story. So why not just remove it?

[05:49 - 05:55] In fact, the secondary story doesn't even need to have arcs anymore. And then we set the arcs on the meta level.

[05:56 - 06:02] So let's do arcs. And once again, we also have auto completion because of our component meta type over here.

[06:03 - 06:09] Let's set the label to, let's say, hello world. So this will apply hello world to every single component.

[06:10 - 06:17] However, we see that this is not really called hello world. And that means essentially that this button has a persisted state from the arts we changed before.

[06:18 - 06:49] We can click on this button that will reset the arcs to the default ones and we 'll see hello world as well as in every single story that we have here. And following the same concept, if we were to have a prop or an arc that is actually complex, let's just say it's called user and then it's got name, let's say, young, and then an age of 30, we actually can set one specific property, let's say here, user, and then name, John.

[06:50 - 07:05] And storybook will actually not override it, but merge it so that you can define partial data over here and also override partial data over there. And that is very useful for more complex scenarios, which is not a case, of course, in our button.

[07:06 - 07:15] And we were saying about all of these auto completions, both in the meta and the story, but how does that actually work? Well, first of all, storybook contains a few types in TypeScript.

[07:16 - 07:28] They're called story, meta, component story and component meta. Component story and component meta are types specifically to storybook react, where you can pass as a generic the type of your component.

[07:29 - 07:36] The props from your component will be automatically inferred by that type. And then you get arcs and arc types and so on and so forth.

[07:37 - 07:49] And the interesting thing here is that we're only typing our template for our stories. And this is just being cloned, but at the same time you see that the primary and secondary stories, they have the correct types.

[07:50 - 08:09] And this is only possible if you have a specific configuration in your TS config file, which is either strict mode to be true, or if you don't want strict, but you still want that functionality, there is a strict bind call apply flag that you have to set to true. In this case, because this project already contains this, it's not a problem.

[08:10 - 08:21] But if you see this problem happening at your project, that might be as well the reason. So we went through one of the stories and we see that the stories is a Type Script file, the header and the page as well.

[08:22 - 08:25] However, the introduction stories are not. So this is MDX.

[08:26 - 08:31] Well, the first thing is in the previous lesson, we removed the index entries here. So that's why you don't see in the sidebar.

[08:32 - 08:39] Just make sure to add it back. So let's do that right now.

[08:40 - 08:49] And once again, we made changes to main JS, which means that we have to run Storybook again. So in the meantime, let's just check this introduction stories MDX.

[08:50 - 09:02] So Storybook also allows you to write and author stories by using a markdown syntax, which also allows you to add components on that as well. It follows the same concepts.

[09:03 - 09:06] You have meta, you also have stories. So it's pretty similar over here.

[09:07 - 09:17] But the added benefit is that you can actually add arbitrary text to document things. So in this example, we have an introduction story that actually contains just links and other cool stuff.

[09:18 - 09:26] And that's pretty helpful, especially if you want to own board your colleagues at your company. It's always helpful to have an introduction page in your Storybook to help them with that.

[09:27 - 09:39] And one last thing to discuss is the file structure and the naming of your stories. So if we look at the button stories, we have example slash button in the title.

[09:40 - 09:52] Storybook uses the title property to define how your component will be shown on the sidebar. So if we actually call this, let's say component slash button, Storybook will change it in a way that will separate from this example category.

[09:53 - 10:06] And now we have a separate category called components and button and a good practices to normally follow the structure of your files. So for example, if you have a folder called components and you have a component called badge, you should have component slash badge.

[10:07 - 10:28] However, if you go deeper, such as pages, homepage, components, restaurant section, you should also have the same thing on Storybook and it will actually group these things for you. So if we go back and we let's say components and then atomic slash button, Storybook will actually group this out over here.

[10:29 - 10:37] And let's just make this a bit more fun. And let's change the header as well to be components slash atomic slash header.

[10:38 - 10:46] So by having those two things in the same category, Storybook will add them to the same folder. And that's basically how you can organize your components in the sidebar.

[10:47 - 10:53] And by looking at the header component, we actually see something new. We have parameters over here in the layout of full screen.

[10:54 - 10:59] So what does that mean? If you look at the button, it actually has a padding around it.

[11:00 - 11:09] But if you look at the header, it is actually closely together with the frame. The reason for that is that normally headers or pages, we don't want to render them with some spacing.

[11:10 - 11:23] So if we actually remove this layout here, we will see that the header will render with the padding. And Storybook provides you a way to configure that by other passing layout of full screen, padded or centered.

[11:24 - 11:40] And the layout will be changed accordingly based on this property. And parameters can also be used to configure Storybook add-ons, which are essentially these configurations here with the on the top as well as the spannels, which we'll get into detail in the next lesson. So I'll see you in the next one.