Story Decoration

/**
 * Main decorator for adding info addon to stories
 * @param {Object|string} options - Configuration options or simple text content
 * @returns {Function} Storybook decorator function that can be used globally or per-story
 */
function withInfo(options);

import { withInfo } from "@storybook/addon-info";
import { addDecorator } from "@storybook/react";

// Global decorator with default options
addDecorator(withInfo);

// Global decorator with custom options
addDecorator(
  withInfo({
    inline: true,
    header: false,
    source: true,
    propTables: [Button, Input],
  })
);

// Per-story usage
export default {
  title: "Components/Button",
  decorators: [withInfo],
};

// Per-story with options
export default {
  title: "Components/Button", 
  decorators: [
    withInfo({
      text: "Button component documentation",
      inline: true,
    }),
  ],
};

/**
 * Core component that renders story information panels
 * @param {Object} props - Story component props
 */
function Story(props);

interface StoryProps {
  /** Story context with kind and name */
  context?: StoryContext;
  /** Info text content (string or React node) */
  info?: string | React.ReactNode;
  /** Components to show prop tables for */
  propTables?: Array<Function>;
  /** Components to exclude from prop tables */
  propTablesExclude?: Array<Function>;
  /** Function to compare prop table components */
  propTableCompare: Function;
  /** Display info inline vs overlay */
  showInline?: boolean;
  /** Show story header */
  showHeader?: boolean;
  /** Show source code */
  showSource?: boolean;
  /** Styles function or object */
  styles: Function;
  /** Story children (the actual story content) */
  children?: React.ReactNode;
  /** Custom markdown components */
  components?: Object;
  /** Prop table component to use */
  PropTable: React.ComponentType;
  /** Max object keys in prop display */
  maxPropObjectKeys: number;
  /** Max array length in prop display */
  maxPropArrayLength: number;
  /** Max props per line in source */
  maxPropsIntoLine: number;
  /** Max string length in prop display */
  maxPropStringLength: number;
  /** Props to exclude from tables */
  excludedPropTypes?: Array<string>;
}

interface StoryContext {
  /** Story category/group name */
  kind: string;
  /** Individual story name */
  name: string;
}

interface InfoOptions {
  /** Display info inline instead of overlay button (default: false) */
  inline?: boolean;
  /** Show header with component name and description (default: true) */
  header?: boolean;
  /** Display the source code of story component (default: true) */
  source?: boolean;
  /** Array of components to show prop tables for (default: []) */
  propTables?: Array<React.ComponentType>;
  /** Array of components to exclude from prop tables (default: []) */
  propTablesExclude?: Array<React.ComponentType>;
  /** Custom function to compare components for prop tables */
  propTableCompare?: PropTableCompareFunction;
  /** Custom styles object or function to override default styles */
  styles?: Object | StylesFunction;
  /** Custom markdown component overrides for text rendering */
  components?: { [key: string]: React.ComponentType };
  /** Maximum props to display per line in source code (default: 3) */
  maxPropsIntoLine?: number;
  /** Maximum object keys to display in prop values (default: 3) */
  maxPropObjectKeys?: number;
  /** Maximum array length to display in prop values (default: 3) */
  maxPropArrayLength?: number;
  /** Maximum string length to display in prop values (default: 50) */
  maxPropStringLength?: number;
  /** Custom prop table component to replace default PropTable */
  TableComponent?: React.ComponentType;
  /** Array of prop names to exclude from prop tables (default: []) */
  excludedPropTypes?: Array<string>;
  /** Text content to display in info panel (supports markdown) */
  text?: string;
}

interface PropTableCompareFunction {
  /**
   * Custom function to determine if an element matches a component for prop table display
   * @param element - React element from the story
   * @param Component - Component type to compare against
   * @returns Boolean indicating if they match
   */
  (element: React.ReactElement, Component: React.ComponentType): boolean;
}

interface StylesFunction {
  /**
   * Function to customize addon styles
   * @param defaultStyles - Default style object
   * @returns Modified styles object
   */
  (defaultStyles: Object): Object;
}

/**
 * @deprecated Use withInfo options parameter instead
 * Sets global default options for the info addon
 * @param {Object} newDefaults - Default options to merge
 * @returns {Function} Deprecated function
 */
function setDefaults(newDefaults);

// OLD (deprecated)
import { setDefaults } from "@storybook/addon-info";
setDefaults({ inline: true });

// NEW (recommended) 
import { withInfo } from "@storybook/addon-info";
addDecorator(withInfo({ inline: true }));

// Custom comparison for React Hot Loader compatibility
const customPropTableCompare = (element, Component) => {
  return typeof reactHotLoaderGlobal === 'undefined'
    ? element.type === Component
    : reactHotLoaderGlobal.areComponentsEqual(element.type, Component);
};

addDecorator(
  withInfo({
    propTableCompare: customPropTableCompare,
  })
);

// Style function approach
const customStyles = (defaultStyles) => ({
  ...defaultStyles,
  button: {
    ...defaultStyles.button,
    base: {
      ...defaultStyles.button.base,
      backgroundColor: '#ff0000',
      color: 'white',
    },
  },
  infoBody: {
    ...defaultStyles.infoBody,
    fontFamily: 'monospace',
  },
});

addDecorator(withInfo({ styles: customStyles }));

// Disable info for specific stories
export const HiddenInfo = () => <Component />;
HiddenInfo.story = {
  parameters: {
    info: { disable: true },
  },
};