Hierarchy of displayed labels does not seem to operate as expected

[alexlibby]

Thank you for your help on a previous ticket - I'm making progress!

I've been playing around with labels in my repo, which I'm attaching to stories for a single component and not setting at a global level. I've noticed however that labels don't seem to display as intended / I expected:

1. If I create a custom label in preview.js, such as this one:

   const preview = {
   parameters: {
   controls: {},
   badgesConfig: {
     MyCustomBadge: {
       title: "My Custom Badge",
       styles: {
         backgroundColor: "#00C7AC",
         borderColor: "red",
         color: "#FFFFFF",
       },
     },
   },
   },
   };

   I can only get it to display it at all if it is set to my default (fall-back) story in Storybook 8 - it does not render if only set against individual entries. It also renders against all stories in my file (4, including the fallback); I have different labels attached to other stories in the same file, and these do not override the default. I have set this custom label in a map in my stories file, like this - I believe this is the right location, but the documentation doesn't seem to make this clear:

   const BADGES = {
   ...BADGE,
   MY_CUSTOM_BADGE: "MyCustomBadge",
   };

   I have tried passing the "MyCustomBadge" value in on its own too, and not set a map, but this doesn't work for me.

2. If I set an empty array for my badges property against default like this:

   parameters: {
   badges: [],
   },

   I was expecting it to not show for that story, but the relevant label(s) to show on other stories for that component in the same stories file - instead, I see all (four) stories show the same label as is set for the default fallback (in this case BETA).

3. I've also tried setting badges: ["deprecated"], instead of badges: BADGES.DEPRECATED at a story level (this assuming I am using a map) - this doesn't seem to be respected either, as it's still showing BETA, which is set on the fallback story (as per above).

I feel I must be missing something - can you please help and advise?

[tetarchus]

Hi @alexlibby,

Where abouts are you expecting to see the badge? If it's on the Docs page, this may be due to the plugin not having access to the specific stories' parameters at that level. To clarify where they should appear:

• If set in preview.parameters.badges (globally) they will show on all autodocs and stories that don't have their own badges parameter
• If set on the meta export of a story they will show on the Docs page, and any stories that don't have their own stories parameter.
• If set on an individual story, they will only show when looking at that story in the sidebar (not its docs page)

This is a limitation of parameters in storybook in that accessing them only gets you the "closest" value to the current story, but it is something I am looking to resolve in future if possible.

Testing with https://github.com/tetarchus/storybook-addon-badges/blob/next/src/stories/Button.stories.tsx, I get the following:

• Docs in the sidebar shows the beta badge (defined in meta.paramters.badges)
• AllBadges shows all badges (defined in the stories own parameters.badges)
• JustCustom only shows the MyCustomBadge (defined in the stories own parameters.badges)
• Deprecated only shows the deprecated badge (defined in the stories own parameters.badges)
• Fallback shows the beta badge (defined in meta.paramters.badges as it doesn't override those badges).

[alexlibby]

Hi - thanks for helping again!

At present, this is what I have set up:

• main.js: only the reference to the addon, nothing else
• preview.js: config for MyCustomBadge, lifted off the documentation, and set under badgesConfig (inside the badges config object).

If I set the following, using DEPRECATED as an example, I get:

• preview.parameters.badges: I get DEPRECATED across all stories and docs (my docs are not autogenerated), but one variant in my Breadcrumbs.stories.js file has an entry for badges: in it, set to BETA, and another has MY_CUSTOM_BADGE, which is also not visible.
• preview.parameters.badges: DEPRECATED is set as before, but if BETA is set in the default fall-back, I get BETA on all docs and stories.
• preview.parameters.badges: If I remove the entry used in the previous 2 tests, I still get BETA set across all stories and docs files, with no reference to DEPRECATED anywhere.
• If I set BETA as the only entry against a story (in this case Default, and not the default fallback one), and comment out any reference to the custom one I created in the stories file, and in preview.js, I don't get anything displayed at all.

For all of the above, I checked both the story entry on the left, as well as the docs file.

My hope is to at least display a badge on each component that relates to its status or its variants. For example, if STABLE is set globally, but a component has a BETA badge against it, it should display BETA, not STABLE. Likewise, if the component's single variant is ALPHA status, this should be set, not STABLE. The same applies for any other variants held within the same stories file (my Breadcrumbs component has 1 fallback, 1 main story and 2 variants).

In terms of display - I am less worried about whether it displays on the docs page, so if displaying it on a per component basis is only possible for components, not docs, then that is OK. At the moment though, I'm seeing the same entry displayed on all (as per above), which makes me think something isn't respecting the order!

Does this help?

[tetarchus]

Thanks for confirming. Can I check what version of Storybook you are currently running? Running with latest (8.2.9) I seem to get what you're expecting with:

// .storybook/preview.js
const preview = {
  parameters: {
    badges: ['stable'],
    badgesConfig: {
      MyCustomBadge: {
        title: 'My Custom Badge',
        styles: {
          backgroundColor: '#00C7AC',
          borderColor: 'red',
          color: '#FFFFFF',
        },
      },
    },
  }
};

// Button.stories.js
const meta = {
  title: 'Example/ButtonWithGlobal',
  component: Button,
 // parameters: { badges: [BADGES.BETA] }, // If uncommented, the fallback will be `beta`
  tags: ['autodocs'],
}

export const Deprecated = {
  args: {
    label: 'Button',
  },
  parameters: { badges: [BADGE.DEPRECATED] },
};

const Fallback = {
  args: {
    size: 'large',
    label: 'Button',
  },
};

const Empty = {
  args: { ...Fallback.args },
  parameters: { badges: [] },
};

With this setup:

• Docs will show Stable
• Deprecated will show Deprecated
• Fallback will show Stable
• Empty shows no badges

If a badges parameter is added to the meta object (meta.parameters.badges) then all stories should fall back to those badges instead of the globals, which is what I'm seeing in my tests.

[alexlibby]

Interesting...to answer your first question, I'm using Storybook 8.2.9; it's been updated a couple of times, but only patch release updates (I think from 8.2.7?). I used npx sb init --builder @storybook/builder-vite to create it, and let it auto configure support for Svelte.

I have spotted a couple of things that might have a bearing though:

• I'm not using tags: ['autodocs'] - is there any chance this might have an effect? I can't immediately think why if it did, but it is different to what I'm running!
• My stories file format is a little different to yours - here is an example:

  
  export default {
  title: "<TITLE>",
  component: Breadcrumbs,
  argTypes: {
  BreadcrumbItems: levels,
  image: { control: "boolean" },
  },
  };

export const Default = (args) => ({ Component: Breadcrumbs, props: { ...args, breadcrumbItems: [ { href: "/", text: "Dashboard" }, { href: "/reports", text: "Annual reports" }, { href: "/reports/2024", text: "2024" }, ], }, parameters: { badges: ["beta"], }, });

If I were to compare, would I be right in thinking that my `default` template is the same as your `Fallback` one, or is it actually `meta`? I have Default in all of my story files, plus 1-3 extra variants; all start with a capital. The only instance of a name starting with lower case is the `default`, which is my fall-back template. 

I've tried adding a `const meta...` block in, but I'm not sure it's helped - mine had a title, component entry and the parameters block, but no `autodocs` entry. The only way I could get that to show was spreading it into my default fallback ("default") - this displayed BETA (which was set in meta) across docs and component pages. I tried the same with the custom badge, which also displayed across all files. At this point, my Default template had a DEPRECATED badge set on it - this did not display at all with the meta block set.

I've also tried setting the badges: parameter in the meta block, and then having a second parameters block in a story, to see if the latter overrides the former - this does not change: it shows the one in meta, which is the custom badge, and not the DEPRECATED one.

Any ideas?

[tetarchus]

So the meta is the default export for a story file, so parameters applied in your export default should apply to all stories in the file:

export default {
  title: "<TITLE>",
  component: Breadcrumbs,
  argTypes: {
    BreadcrumbItems: levels,
    image: { control: "boolean" },
  },
  parameters: {
    badges: ['beta'], // applies to all stories.
  }
};

It looks like your stories use a render function style, rather the object style of CSF3 (from memory I think you're using CSF2, unless this is a svelte-specific method of defining stories).

I'll have a quick check and see if I can confirm.

[tetarchus]

From memory (and a quick check of the docs), if you're rendering using a function, rather than the object definition, parameters doesn't exist directly within the return.

Can you try removing the parameters from the returned object of the Default story, and add a new line underneath with Default.parameters = { badges: ['beta'] }; and see if that solves it for you?

[alexlibby]

Success - thankyou! I tried moving the parameters piece outside of the exported function as you mention, and that seems to have done the trick. I can now set whichever status I want on each story, while still have a badges: [] entry in the meta block to not set a default like this:

const meta = { title: "Garnet UI Library/Navigation Components/Breadcrumbs", component: Breadcrumbs, parameters: { badges: [], }, };

I suspect it may not actually be needed, but it has the effect of not setting a status for the docs file, while still having statuses set for each of the components as needed. I'll do some more testing, but so far so good...I am thinking though - maybe we should do something about editing the documentation, to make it clearer what people need to do?

[tetarchus]

Excellent.

Yeah, I've made some notes of some documentation pieces to add, and some tests to add for different frameworks etc. so that I have some more examples.

Thanks for raising as it's definitely given some insight into use cases and shortcomings of the docs.

[alexlibby]

You're welcome - thank you for the prompt fixing! If I can be of any help with more use cases, please shout.