storybook-addon-tag-badges/dist/index.d.ts

Display Storybook tags as badges in the sidebar and toolbar.

import React, { ComponentProps, FC, ReactNode } from 'react';
import { TooltipMessage } from '@storybook/components';
import { HashEntry } from '@storybook/manager-api';
import { getTagParts as getTagParts$1, getTagPrefix as getTagPrefix$1, getTagSuffix as getTagSuffix$1 } from 'src/utils/tag';
import { API_HashEntry } from '@storybook/types';

/**
 * 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;
    /** The background colour of the badge (optional). */
    bgColor?: string;
    /** The border colour of the badge (optional). */
    borderColor?: string;
    /** The foreground (text) colour of the badge (optional). */
    fgColor?: string;
    /** The tooltip text to display when hovering over the badge (optional). */
    tooltip?: string | 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: {
    entry: HashEntry;
    getTagParts: typeof getTagParts$1;
    getTagPrefix: typeof getTagPrefix$1;
    getTagSuffix: typeof getTagSuffix$1;
    tag: string;
}) => Badge) | Badge;

/**
 * Display options for badges in a part of the UI. If `true`, displays for any type of item.
 * If `false`, never displays. If a string or string array, each string is a type of HashEntry
 * for which the badge will be shown (e.g. 'docs' or 'story').
 */
type DisplayOptionItem<T> = boolean | T | {
    skipInherited?: boolean;
    type: T;
} | {
    skipInherited: boolean;
    type?: T;
};
/**
 * Display options for badges in a part of the UI. If `true`, displays for any type of item.
 * If `false`, never displays. If a string or string array, each string is a type of HashEntry
 * for which the badge will be shown (e.g. 'docs' or 'story').
 */
type DisplayOption<T> = DisplayOptionItem<T> | DisplayOptionItem<T>[];
/**
 * 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 the sidebar.
     */
    sidebar?: DisplayOption<Exclude<API_HashEntry['type'], 'root'>>;
    /**
     * Controls the display of badges in the toolbar.
     */
    toolbar?: DisplayOption<Exclude<API_HashEntry['type'], 'root' | 'component' | 'group'>>;
}

/**
 * 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 defaultConfig: TagBadgeParameters;

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

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

export { type Badge, type BadgeOrBadgeFn, type Display, Sidebar, type TagBadgeParameters, type TagPattern, type TagPatterns, defaultConfig, getTagParts, getTagPrefix, getTagSuffix, matchTag, matchTags, renderLabel };