[Bug]: addon-doc does not show component description and proptypes

[SalahAdDin]

Describe the bug

It is something weird happening with out project: for some stories description and prop types are shown, but for other ones, they are not:

/**
 * Insights Hero component: anchors the Insights Landing page
 * - Clear hierarchy: eyebrow, headline (H1), summary, author, CTAs
 * - Supports topical variants, optional background image/video
 * - Multiple CTAs: Explore, Download, Subscribe
 * - Mobile-first, responsive, accessible
 */
export default function InsightsHero({
  eyebrow,
  headline,
  summary,
  date,
  authors,
  downloadLink,
  subscribeLink,
  topicalVariant,
  backgroundImageUrl,
  backgroundVideoUrl,
  className = "",
}) {

... 

}

InsightsHero.propTypes = {
  /** Section or breadcrumb label shown next to the back link. */
  eyebrow: PropTypes.string.isRequired,
  /** Main H1 headline for the hero. */
  headline: PropTypes.string.isRequired,
  /** Short descriptive paragraph under the headline. */
  summary: PropTypes.string.isRequired,
  /** Published date string rendered inside a `<time>` element. */
  date: PropTypes.string.isRequired,
  /** Optional list of authors displayed in the CTA column. */
  authors: PropTypes.arrayOf(
    PropTypes.shape({
      /** Author display name. */
      name: PropTypes.string.isRequired,
      /** Optional author URL; if present the name is rendered as a link. */
      url: PropTypes.string,
    })
  ),
  /** Optional download CTA with URL and description. */
  downloadLink: PropTypes.shape({
    /** Absolute or relative URL to the download resource. */
    href: PropTypes.string.isRequired,
    /** Short description shown under the Download heading. */
    description: PropTypes.string.isRequired,
  }),
  /** Optional subscribe CTA with URL and description. */
  subscribeLink: PropTypes.shape({
    /** Absolute or relative URL to the subscription page. */
    href: PropTypes.string.isRequired,
    /** Short description shown under the Subscribe heading. */
    description: PropTypes.string.isRequired,
  }),
  /** Variant key appended to the root as `hero-insights--{variant}` for theming. */
  topicalVariant: PropTypes.string,
  /** Background image URL when no video is provided; alt falls back to headline. */
  backgroundImageUrl: PropTypes.string,
  /** Background video URL; plays inline, muted, looping; takes precedence over image. */
  backgroundVideoUrl: PropTypes.string,
  /** Additional class names to append to the hero root element. */
  className: PropTypes.string,
};

This works.

import { useEffect, useState } from "react";
import { createPortal } from "react-dom";
import PropTypes from "prop-types";

/**
 * Portal
 * Renders arbitrary React children into an existing DOM element by id.
 *
 * Props
 * - children: React node to render inside the external container.
 * - containerId: The id of the target DOM element where content should mount.
 *   Defaults to "wtw-portal-root".
 *
 * Behavior
 * - Waits for the target container to exist in the DOM, retrying on the next
 *   animation frame until found. While waiting, renders nothing (returns null).
 * - Once available, mounts children via ReactDOM.createPortal.
 *
 * Notes
 * - This avoids creating duplicate containers if the target element is
 *   introduced later (e.g., by a layout component, navbar, or Storybook decorator).
 */
function Portal({ children, containerId = "wtw-portal-root" }) {
  const [container, setContainer] = useState(null);

  useEffect(() => {
    let rafId = null;

    const findContainer = () => {
      const el = document.getElementById(containerId);
      if (el) {
        setContainer(el);
      } else {
        rafId = requestAnimationFrame(findContainer);
      }
    };

    findContainer();

    return () => {
      if (rafId) cancelAnimationFrame(rafId);
    };
  }, [containerId]);

  if (!container) return null;

  return createPortal(children, container);
}

Portal.propTypes = {
  /** React node rendered into the portal target. */
  children: PropTypes.node.isRequired,
  /** Target container id (string). Should match an existing element in the document (e.g., "wtw-navbar-search"). */
  containerId: PropTypes.string,
};

export default Portal;

This does not work.

What is the difference?

Reproduction link

https://stackblitz.com/edit/github-tmyakrbd?file=src%2FPortal.stories.js

Reproduction steps

1. Setup the project
2. Setup Storybook with autodocs
3. Write the component and its story.
4. Run storybook.
5. Go to the component Story main documentation.
6. Check the configuration.

System

❯ npx storybook@latest info
Need to install the following packages:
storybook@10.0.5
Ok to proceed? (y) y

npm warn deprecated inflight@1.0.6: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
npm warn deprecated rimraf@2.6.3: Rimraf versions prior to v4 are no longer supported
npm warn deprecated glob@7.2.3: Glob versions prior to v9 are no longer supported

Storybook Environment Info:

  System:
    OS: macOS 15.7.1
    CPU: (12) arm64 Apple M4 Pro
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 22.15.1 - ~/.local/state/fnm_multishells/43024_1762447728785/bin/node
    Yarn: 1.22.22 - ~/.local/state/fnm_multishells/43024_1762447728785/bin/yarn <----- active
    npm: 10.9.2 - ~/.local/state/fnm_multishells/43024_1762447728785/bin/npm
    pnpm: 10.12.1 - ~/.local/state/fnm_multishells/43024_1762447728785/bin/pnpm
  Browsers:
    Chrome: 142.0.7444.60
    Safari: 26.0.1
  npmPackages:
    @storybook/addon-a11y: ^10.0.4 => 10.0.4 
    @storybook/addon-designs: ^11.0.1 => 11.0.1 
    @storybook/addon-docs: ^10.0.4 => 10.0.4 
    @storybook/addon-onboarding: ^10.0.4 => 10.0.4 
    @storybook/addon-themes: ^10.0.4 => 10.0.4 
    @storybook/addon-vitest: ^10.0.4 => 10.0.4 
    @storybook/react-vite: ^10.0.4 => 10.0.4 
    eslint-plugin-storybook: ^10.0.4 => 10.0.4 
    storybook: ^10.0.4 => 10.0.4

Additional context

No response

[dosubot[bot]]

The difference is in how the components are exported. Storybook's docs extraction works reliably when you use an inline default export like export default function InsightsHero(...) { ... }. When you define a function and then export it separately (e.g., function Portal(...) { ... } export default Portal;), Storybook's docgen may not always associate the prop types and descriptions with the component, so they don't show up in the docs. This is a limitation in how export names are resolved during static analysis (source).

To fix this, change your export to use the inline default export style:

export default function Portal({ children, containerId = "wtw-portal-root" }) {
  // ...
}

This should make prop types and descriptions appear in Storybook docs for all your components. This pattern is the most robust for autodocs and prop extraction in Storybook 10 with React and Vite (example issue).

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[SalahAdDin]

The difference is in how the components are exported. Storybook's docs extraction works reliably when you use an inline default export like export default function InsightsHero(...) { ... }. When you define a function and then export it separately (e.g., function Portal(...) { ... } export default Portal;), Storybook's docgen may not always associate the prop types and descriptions with the component, so they don't show up in the docs. This is a limitation in how export names are resolved during static analysis (source).

To fix this, change your export to use the inline default export style:

export default function Portal({ children, containerId = "wtw-portal-root" }) {
// ...
}

This should make prop types and descriptions appear in Storybook docs for all your components. This pattern is the most robust for autodocs and prop extraction in Storybook 10 with React and Vite (example issue).

To reply, just mention @dosu.

How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other

export default function Portal({ children, containerId = "wtw-portal-root" }) {
  const [container, setContainer] = useState(null);

  useEffect(() => {
    let rafId = null;

    const findContainer = () => {
      const el = document.getElementById(containerId);
      if (el) {
        setContainer(el);
      } else {
        rafId = requestAnimationFrame(findContainer);
      }
    };

    findContainer();

    return () => {
      if (rafId) cancelAnimationFrame(rafId);
    };
  }, [containerId]);

  if (!container) return null;

  return createPortal(children, container);
}

Portal.propTypes = {
  /** React node rendered into the portal target. */
  children: PropTypes.node.isRequired,
  /** Target container id (string). Should match an existing element in the document (e.g., "wtw-navbar-search"). */
  containerId: PropTypes.string,
};

It does not work.

[SalahAdDin]

This does work:

 argTypes: {
    containerId: {
      control: "text",
      description:
        "DOM id of the target container where children are portaled.",
      table: {
        category: "Portal Props",
        type: { summary: "string" },
        defaultValue: { summary: '"wtw-portal-root"' },
      },
    },
    children: {
      description: "React node rendered into the portal target.",
      table: {
        category: "Portal Props",
        type: { summary: "ReactNode" },
      },
    },
  },

[yannbf]

Hey @SalahAdDin it seems that your component is not using any JSX. The react-docgen package searches for functions that return JSX, and therefore can't extract the data for that component.

[SalahAdDin]

So, what's the right way to document this component?

[SalahAdDin]

Same question for memoized components:

import { useId, useMemo, memo } from "react";
import { createPropsComparator } from "@utils/propsComparator";
import PropTypes from "prop-types";

import "./Quote.scss";

/**
 * A stylized quotation block with attribution and optional media (portrait/logo),
 * used to highlight key statements within articles or pages.
 */
function QuoteBase({
  text,
  name,
  title,
  variant,
  type = "personal",
  cite,
  additionalQuote,
}) {
...
};

QuoteBase.propTypes = {
  text: PropTypes.string.isRequired,
  name: (props, propName, componentName) => {
    const isContentType = props.type === "content";
    const value = props[propName];
    if (
      !isContentType &&
      (value === undefined || value === null || value === "")
    ) {
      return new Error(
        `Prop '${propName}' is required in '${componentName}' when 'type' is not 'content'.`
      );
    }

    if (value != null && typeof value !== "string") {
      return new Error(
        `Invalid prop '${propName}' supplied to '${componentName}': expected a string.`
      );
    }

    return null;
  },
  title: (props, propName, componentName) => {
    const isPersonalType = props.type === "personal";
    const value = props[propName];

    if (
      isPersonalType &&
      (value === undefined || value === null || value === "")
    ) {
      return new Error(
        `Prop '${propName}' is required in '${componentName}' when 'type' is 'personal'.`
      );
    }

    if (value != null && typeof value !== "string") {
      return new Error(
        `Invalid prop '${propName}' supplied to '${componentName}': expected a string.`
      );
    }

    return null;
  },
  type: PropTypes.oneOf(["personal", "content"]),
  variant: (props, propName, componentName) => {
    const isPersonalType = props.type === "personal";
    const value = props[propName];

    if (isPersonalType) {
      if (value == null) return null; // optional, default handled in render

      if (value !== "standard" && value !== "feature") {
        return new Error(
          `Invalid prop '${propName}' in '${componentName}': expected 'standard' or 'feature'.`
        );
      }

      return null;
    }

    if (value !== undefined) {
      return new Error(
        `Prop '${propName}' is not applicable in '${componentName}' when 'type' is 'content'.`
      );
    }

    return null;
  },
  cite: PropTypes.string,
  additionalQuote: (props, propName, componentName) => {
    const isPersonalType = props.type === "personal";
    const value = props[propName];

    if (isPersonalType && value != null) {
      return new Error(
        `Prop '${propName}' is not allowed in '${componentName}' when 'type' is 'personal'.`
      );
    }

    if (value == null) return null; // optional

    if (typeof value !== "object") {
      return new Error(
        `Invalid prop '${propName}' in '${componentName}': expected an object.`
      );
    }

    if (typeof value.text !== "string") {
      return new Error(
        `Invalid '${propName}.text' in '${componentName}': expected a string.`
      );
    }

    if (value.title != null && typeof value.title !== "string") {
      return new Error(
        `Invalid '${propName}.title' in '${componentName}': expected a string when provided.`
      );
    }

    return null;
  },
};

const Quote = memo(
  QuoteBase,
  createPropsComparator({
    shallow: ["text", "name", "title", "variant", "type", "cite"],
    deep: {
      additionalQuote: ["text", "title"],
    },
  })
);

Quote.propTypes = QuoteBase.propTypes;

export default Quote;

Story:

It should show also additional notes!

[SalahAdDin]

What about the following example @yannbf:

import { useEffect } from "react";
import PropTypes from "prop-types";

import { initScrollGradient } from "./scrollGradient";

function ScrollGradientDemo({
  startSelector,
  startColorVar,
  endColorVar,
  threshold,
}) {
  useEffect(() => {
    const controller = initScrollGradient({
      startSelector,
      startColorVar,
      endColorVar,
      threshold,
    });
    return () => controller?.destroy?.();
  }, [startSelector, startColorVar, endColorVar, threshold]);

  return (
    <div>
      <section
        style={{ height: "120vh", display: "grid", placeItems: "center" }}
        id="first-section">
        <h1 data-gradient-start>Scroll down</h1>
      </section>
      <section
        style={{ height: "120vh", display: "grid", placeItems: "center" }}
        id="second-section">
        <p>Keep scrolling to see the background and theme change.</p>
      </section>
      <section
        style={{ height: "120vh", display: "grid", placeItems: "center" }}
        id="third-section">
        <p>
          Another section for keeping scrolling to see the background and theme
          change.
        </p>
      </section>
    </div>
  );
}

ScrollGradientDemo.propTypes = {
  /** CSS selector for the element where gradient progression starts. */
  startSelector: PropTypes.string,
  /** Starting color (hex) for the blended background. */
  startColorVar: PropTypes.string,
  /** Ending color (hex) for the blended background. */
  endColorVar: PropTypes.string,
  /** Scroll progress at which the end color is fully reached (0–1). */
  threshold: PropTypes.number,
};

export default {
  title: "Utilities/ScrollGradient",
  component: ScrollGradientDemo,
  parameters: {
    layout: "fullscreen",
    docs: {
      description: {
        component:
          "Scroll-driven background gradient that blends between colors and updates theme variables.",
      },
    },
  },
  argTypes: {
    startSelector: { control: "text" },
    startColorVar: { control: "color" },
    endColorVar: { control: "color" },
    threshold: {
      control: { type: "range", min: 0, max: 1, step: 0.01 },
    },
  },
};

export const Playground = {
  args: {
    startSelector: "[data-gradient-start]",
    threshold: 0.6,
  },
};

Result: