import { FC, HTMLAttributes, ReactElement, ReactNode } from 'react';

/**
 * A built-in component that allows you to display content in a visually appealing card format. It
 * includes options for adding an icon, title, link and an image to related content.
 *
 * @example
 * ### Grouped cards
 *
 * <Cards>
 *   <Cards.Card
 *     icon={<WarningIcon />}
 *     title="Callout"
 *     href="/docs/built-ins/callout"
 *   />
 *   <Cards.Card
 *     icon={<CardsIcon />}
 *     title="Tabs"
 *     href="/docs/built-ins/tabs"
 *   />
 *   <Cards.Card
 *     icon={<OneIcon />}
 *     title="Steps"
 *     href="/docs/built-ins/steps"
 *   />
 * </Cards>
 *
 * ### Single card
 *
 * <br />
 * <Cards.Card
 *   icon={<BoxIcon />}
 *   title="About Nextra"
 *   href="/about"
 *   arrow
 * />
 *
 * @usage
 * ### Grouped cards
 *
 * Import the `<Cards>` component to your page, which includes the `<Card>` component.
 *
 * Then, optionally import the icons that you want to use. To create a set of cards, follow the
 * example below where the `<Cards.Card>` component is used to create a card and the `<Cards>`
 * component is used to group multiple cards together.
 *
 * ```mdx filename="MDX"
 * import { Cards } from 'nextra/components'
 * import { CardsIcon, OneIcon, WarningIcon } from '../path/with/your/icons'
 *
 * <Cards>
 *   <Cards.Card
 *     icon={<WarningIcon />}
 *     title="Callout"
 *     href="/docs/built-ins/callout"
 *   />
 *   <Cards.Card
 *     icon={<CardsIcon />}
 *     title="Tabs"
 *     href="/docs/built-ins/tabs"
 *   />
 *   <Cards.Card
 *     icon={<OneIcon />}
 *     title="Steps"
 *     href="/docs/built-ins/steps"
 *   />
 * </Cards>
 * ```
 *
 * ### Single card
 *
 * A `<Card>` not wrapped in a `<Cards>` component will not be grouped with other cards. This can
 * be useful if you want to display a single card in a different format than the other cards on the
 * page.
 *
 * ```mdx filename="MDX"
 * <Cards.Card
 *   icon={<BoxIcon />}
 *   title="About Nextra"
 *   href="/about"
 *   arrow
 * />
 * ```
 */
declare const Cards: FC<{
    /**
     * Number of columns.
     * @default 3
     */
    num?: number;
} & HTMLAttributes<HTMLDivElement>> & {
    displayName: string;
    Card: FC<{
        title: string;
        icon?: ReactElement;
        arrow?: boolean;
        href: string;
        children?: ReactNode;
        /** CSS class name. */
        className?: string;
    }>;
};

export { Cards };