storybook-addon-tag-badges/dist/manager-helpers.d.ts

Display Storybook tags as badges in the sidebar and toolbar.

import { TooltipMessage } from 'storybook/internal/components';
import { HashEntry } from 'storybook/manager-api';
import { CSSObject } from 'storybook/theming';
import { API_HashEntry } from 'storybook/internal/types';
import React$1, { FC, ReactNode } from 'react';
import { Of } from '@storybook/addon-docs/blocks';

/**
 * Represents a pattern for matching tags.
 * It can be a string, a RegExp, or an object where only the prefix
 * or suffix of the tag is matched.
 */
type TagPattern = string | RegExp | {
    prefix?: string | RegExp;
    suffix?: string | RegExp;
};
/**
 * Collection of tag patterns.
 */
type TagPatterns = TagPattern | TagPattern[];

/**
 * Splits a tag into a prefix and suffix, separated by a colon.
 * If no colons are present, `suffix` is `null`. If more than one
 * colons are present, `suffix` is a concatenation of all the parts
 * beyond the first one.
 * @param tag The tag being queried.
 * @returns The prefix and suffix.
 */
declare function getTagParts(tag: string): {
    prefix: string;
    suffix: string | null;
};
/**
 * Gets the prefix of a tag, i.e. the part before the
 * colon if it contains one, or the whole tag otherwise.
 * @param tag The tag being queried.
 * @returns The prefix or the whole tag.
 */
declare function getTagPrefix(tag: string): string;
/**
 * Gets the suffix of a tag, i.e. the part after the
 * colon if it contains one, or `null` otherwise.
 * @param tag The tag being queried.
 * @returns The suffix if it exists.
 */
declare function getTagSuffix(tag: string): string | null;
/**
 * Checks if a given tag matches any of the provided patterns.
 * Patterns can be regular expressions, strings, or objects with prefix and suffix patterns.
 * @param tag The tag to match against the patterns.
 * @param patterns The pattern or patterns to match the tag against.
 * @returns `true` if the tag matches any of the patterns, `false` otherwise.
 */
declare function matchTag(tag: string, patterns: TagPatterns): boolean;
/**
 * Filters an array of tags based on the provided pattern configuration.
 * @param tags An array of tags to filter.
 * @param config The pattern configuration to match tags against.
 * @returns An array of tags that match the given pattern configuration.
 */
declare function matchTags(tags: string[], config: TagPatterns): string[];

/**
 * Properties of a badge to be displayed.
 */
interface Badge {
    /** The text content of the badge. */
    text: string;
    /** Either a style preset provided by the addon, or a custom emotion object. */
    style?: 'grey' | 'green' | 'turquoise' | 'blue' | 'purple' | 'pink' | 'red' | 'orange' | 'yellow' | CSSObject;
    /** The tooltip text to display when hovering over the badge (optional). */
    tooltip?: string | React.ComponentProps<typeof TooltipMessage>;
}
/**
 * Either a Badge config or a function that generates it from a tag and HashEntry.
 * The function receives the current HashEntry and tag content, and a `getTagParts`
 * helper function to extract the prefix and suffix of the tag. It must return a
 * Badge config object.
 */
type BadgeOrBadgeFn = ((params: {
    context: 'mdx' | 'sidebar' | 'toolbar';
    entry: HashEntry | undefined;
    getTagParts: typeof getTagParts;
    getTagPrefix: typeof getTagPrefix;
    getTagSuffix: typeof getTagSuffix;
    tag: string;
}) => Badge) | Badge;

/**
 * Display options for badges in MDX pages. Only applicable to components
 * and stories referenced in MDX files.
 */
type MDXDisplayOptionItem = boolean | Exclude<API_HashEntry['type'], 'root' | 'group' | 'docs'>;
type MDXDisplayOptions = MDXDisplayOptionItem | MDXDisplayOptionItem[];
/**
 * Display options for badges in the sidebar. Each item in the array must be an object with a
 * skipInherited property to describe inheritance behaviour and an item type.
 */
type SidebarDisplayOptionItem = boolean | {
    skipInherited: boolean;
    type: Exclude<API_HashEntry['type'], 'root'>;
};
type SidebarDisplayOptions = SidebarDisplayOptionItem | SidebarDisplayOptionItem[];
/**
 * Display options for badges in MDX pages. Only applicable to docs and stories
 * which are the two types that have a preview canvas, and thus, a toolbar.
 */
type ToolbarDisplayOptionItem = boolean | Exclude<API_HashEntry['type'], 'root' | 'component' | 'group'>;
type ToolbarDisplayOptions = ToolbarDisplayOptionItem | ToolbarDisplayOptionItem[];
/**
 * The types of HashEntries for which badges will be displayed in different parts of the Storybook UI.
 */
interface Display {
    /**
     * Controls the display of badges in MDX pages with associated components.
     */
    mdx?: MDXDisplayOptions;
    /**
     * Controls the display of badges in the sidebar.
     */
    sidebar?: SidebarDisplayOptions;
    /**
     * Controls the display of badges in the toolbar.
     */
    toolbar?: ToolbarDisplayOptions;
}

/**
 * Configuration that maps a tag or tag matching pattern to the config
 * that can render a badge, and to display conditions.
 */
interface TagBadgeParameter {
    /**
     * Controls where badges are rendered and for what type of content.
     */
    display?: Display;
    /**
     * Defines the string, RegExp or tag structures to match against
     * for this badge config to be used.
     */
    tags: TagPatterns;
    /**
     * Defines the appearance and content of the badge to display. Can be
     * a function that dynamically generates a badge based on the matched
     * content and tag.
     */
    badge: BadgeOrBadgeFn;
}
/**
 * Parameters of this addon. Each item maps a tag or tag matching pattern
 * to the config that can render a badge, and to display conditions.
 */
type TagBadgeParameters = TagBadgeParameter[];

declare const newBadge: TagBadgeParameter;
declare const preReleaseBadge: TagBadgeParameter;
declare const deprecatedBadge: TagBadgeParameter;
declare const outdatedBadge: TagBadgeParameter;
declare const dangerBadge: TagBadgeParameter;
declare const codeOnlyBadge: TagBadgeParameter;
declare const versionBadge: TagBadgeParameter;
declare const defaultConfig: TagBadgeParameters;

declare const DISPLAY_DEFAULTS: {
    mdx: ("component" | "story")[];
    sidebar: ({
        type: "story";
        skipInherited: true;
    } | {
        type: "docs";
        skipInherited: true;
    } | {
        type: "component";
        skipInherited: false;
    } | {
        type: "group";
        skipInherited: false;
    })[];
    toolbar: ("docs" | "story")[];
};

declare function renderLabel(item: API_HashEntry): React$1.JSX.Element | undefined;

interface SidebarProps {
    children: ReactNode;
    item: API_HashEntry;
    hasStatusWithUI?: boolean;
}
declare const Sidebar: FC<SidebarProps>;

declare const CustomBadge: React$1.FC<Badge>;

interface MDXBadgesProps {
    /**
     * Specify where to get the Badge tags from. Must be a CSF file's default export or a CSF story.
     * If not specified, the tags will be extracted from the meta of the attached CSF file.
     */
    of?: Of;
}
declare const MDXBadges: FC<MDXBadgesProps>;

export { type Badge, type BadgeOrBadgeFn, CustomBadge, type Display, MDXBadges, type MDXDisplayOptions, Sidebar, type SidebarDisplayOptions, type TagBadgeParameters, type TagPattern, type TagPatterns, type ToolbarDisplayOptions, codeOnlyBadge, dangerBadge, defaultConfig, DISPLAY_DEFAULTS as defaultDisplay, deprecatedBadge, getTagParts, getTagPrefix, getTagSuffix, matchTag, matchTags, newBadge, outdatedBadge, preReleaseBadge, renderLabel, versionBadge };