import { VitePWAOptions } from 'vite-plugin-pwa';
import { transformerTwoslash } from '@shikijs/vitepress-twoslash';
import { groupIconVitePlugin } from 'vitepress-plugin-group-icons';
import { LlmsConfig } from 'vitepress-plugin-llmstxt';
import { TransformContext, DefaultTheme, UserConfig } from 'vitepress';
import { DeepNonNullable, PackageJSON } from '@dovenv/core/utils';
import { RSSOptions } from 'vitepress-plugin-rss';
import * as _dovenv_core from '@dovenv/core';
import { CommandUtils, getCommandUtils } from '@dovenv/core';

type OgImageOpts = {
    /** Title for the og image */
    title: string;
    /** Description for the og image */
    desc: string;
    /** Text for the og image */
    text?: string;
    /** Image path for the og image */
    image: string;
    /**
     * Output path for the og image
     *
     * @default './build/og.png'
     */
    output?: string;
    /**
     * Width for the og image
     *
     * @default 1200
     */
    width?: number;
    /**
     * Height for the og image
     *
     * @default 600
     */
    height?: number;
    /** Colors for the og image */
    color?: {
        primary?: string;
        /** Secondary color for the theme. */
        secondary?: string;
        /** Tertiary color for the theme. */
        terciary?: string;
        /** Fourth color for the theme. */
        fourth?: string;
        text?: string;
        bg?: string;
    };
    /**
     * Border radius for the og image
     *
     * @default '20px'
     */
    radius?: string;
    /**
     * Google Font family name for the og image
     *
     * @default 'Open+Sans'
     * @see https://fonts.google.com/
     */
    fontFamily?: string;
};

type Meta = {
    /**
     * If true, the og|twitter image will be generated from the docs configuration data.
     *
     * **Default**: true if does not exist 'public/banner.png'
     */
    autoImage?: boolean | Partial<Omit<OgImageOpts, 'output'>>;
    shared?: {
        /** The title of the shared link */
        title?: string;
        /** A brief description of the content */
        description?: string;
        image?: string;
        url?: string;
    };
    og?: {
        /** Title for the Open Graph metadata. */
        title?: string;
        /** Description for the Open Graph metadata. */
        description?: string;
        /** Image URL for the Open Graph metadata. */
        image?: string;
        /** URL for the site, used in Open Graph metadata. */
        url?: string;
        /** Type for the Open Graph metadata. */
        type?: string;
        /** Site name for Open Graph metadata. */
        siteName?: string;
    } | false;
    twitter?: {
        /** The title of the shared link */
        title?: string;
        /** A brief description of the content */
        description?: string;
        image?: string;
        url?: string;
        /** Domain name */
        domain?: string;
        /** The type of Twitter card, such as summary, summary_large_image, or app... */
        card?: string;
        /**
         * Twitter account associated with the site.
         *
         * @example "@pigeonposse_"
         */
        site?: string;
        /**
         * The Twitter acoount of the content creator
         *
         * @example "@pigeonposse_"
         */
        creator?: string;
    } | false;
    /**
     * Custom metadata
     *
     * @example
     * ```js
     * [{ name: 'twitter:label1', content: 'Genre' }]
     * // Result:
     * <meta name="twitter:label1" content="Genre">
     * ```
     */
    custom?: {
        [key: string]: string;
    }[];
    onPage?: (data: {
        context: TransformContext;
        config: RequiredDocsConfig;
    }) => (Promise<TransformContext['head'] | void> | TransformContext['head'] | void);
};

type PwaOptions = Partial<VitePWAOptions>;

type Theme = DefaultTheme.Config;
type SocialLink = DefaultTheme.SocialLinkIcon;
type Sidebar = Theme['sidebar'];
type Nav = Theme['nav'];
type SocialLinks = Theme['socialLinks'];
type Link = {
    text: string;
    desc: string;
    /**
     * Icons IDs: https://simpleicons.org/.
     */
    icon: SocialLink;
    link: string;
};
type Links = (Link | {
    text: string;
    desc: string;
    items: Link[];
})[];
type Colors = {
    text?: string;
    text2?: string;
    text3?: string;
    bg?: string;
    bgAlt?: string;
    bgSoft?: string;
    bgOpacity?: string;
    shadow?: string;
    divider?: string;
};
type RequiredDocsConfig = DocsConfig & DeepNonNullable<Pick<DocsConfig, 'input' | 'output' | 'docsPath' | 'logo' | 'favicon' | 'name' | 'desc' | 'styles' | 'lang' | 'titleTemplate'>> & {
    license: {
        type: string;
    };
};
type DocsConfig = {
    /**
     * Input directory for documentation files.
     *
     * @default './docs'
     */
    input?: string;
    /**
     * Output directory for the built documentation.
     *
     * @default './build'
     */
    output?: string;
    /**
     * Logo URL for the documentation site.
     *
     * @default '/logo.png'
     */
    logo?: string;
    /**
     * Favicon URL for the documentation site.
     *
     * @default '/favicon.png'
     */
    favicon?: string;
    /**
     * Name of the project or documentation.
     *
     * @default 'DOVENV'
     */
    name?: string;
    /**
     * titleTemplate for the documentation site.
     */
    titleTemplate?: (data: {
        title: string;
        name: string;
    }) => string;
    /**
     * Short description of the project or documentation.
     *
     * @default 'Workspace documentation'
     */
    /**
     * Language code for the documentation, e.g., 'en' for English.
     *
     * @default 'en'
     */
    lang?: string;
    /**
     * Path to the documentation files. Used for editLink in pages.
     *
     * @default 'docs'
     */
    docsPath?: string;
    /** License information for the project. */
    license?: {
        /**
         * Type of license (e.g., MIT, GPL).
         *
         * @default 'MIT'
         */
        type?: string;
        /** URL to the full license text. */
        url?: string;
    };
    desc?: string;
    /** A shorter version of the description for better display. */
    shortDesc?: string;
    /** URL of the project or documentation site. */
    url?: string;
    /** Repository URL for the project. */
    repoURL?: string | false;
    /** URL for the project's issue tracker or bug reports. */
    bugsURL?: string | false;
    /** URL for funding or sponsorship of the project. */
    fundingURL?: string | false;
    /** Additional URL for more resources or links related to the project. */
    moreURL?: string | false;
    /** NPM package URL for the project. */
    npmURL?: string | false;
    /** Version of the project. */
    /** CHANGELOG url of the project. */
    changelogURL?: string | false;
    /** Contributing url of the project. */
    contributingURL?: string | false;
    version?: string;
    /** Array of previous versions of the project, each with a name and a URL. */
    oldVersions?: {
        /** The name or label of the old version, e.g., "v1.0", "Legacy". */
        name: string;
        /** URL where the old version documentation */
        url: string;
    }[];
    /** Custom styles for the documentation site. */
    styles?: {
        /** Color scheme for the documentation site. */
        color?: {
            /** Primary color for the theme. */
            primary?: string;
            /** Secondary color for the theme. */
            secondary?: string;
            /** Tertiary color for the theme. */
            terciary?: string;
            /** Fourth color for the theme. */
            fourth?: string;
            /** Dark mode colors for the theme. */
            dark?: Colors;
            /** Light mode colors for the theme. */
            light?: Colors;
        };
        /** Border radius for elements in the theme. */
        radius?: string;
    };
    meta?: Meta;
    /**
     * Open Graph meta tags for better link previews on social media.
     *
     * @deprecated
     */
    og?: {
        /** Description for the Open Graph metadata. */
        description?: string;
        /** Image URL for the Open Graph metadata. */
        image?: string;
        /** Title for the Open Graph metadata. */
        title?: string;
        /** URL for the site, used in Open Graph metadata. */
        url?: string;
        /** Site name for Open Graph metadata. */
        siteName?: string;
        /** Twitter account associated with the site. */
        twitterAccount?: string;
    };
    /** Configuration options for RSS feed. */
    rss?: RSSOptions;
    /** Configuration options for PWA (Progressive Web App) support. */
    pwa?: Partial<PwaOptions> | false;
    /** Custom CSS for the documentation site. */
    css?: string;
    /** Footer configuration with links and copyright information. */
    footer?: {
        /** Links to various social platforms or contact methods. */
        links?: {
            /** Website link for the project or organization. */
            web?: string;
            /** Email link for contacting the project or organization. */
            email?: string;
            /** Twitter link for the project or organization. */
            twitter?: string;
            /** Instagram link for the project or organization. */
            instagram?: string;
            /** Medium link for articles or blogs related to the project. */
            medium?: string;
        };
        /** Copyright information for the project. */
        copy?: {
            /** Name to display in copyright notices. */
            name?: string;
            /** URL for the copyright holder or organization. */
            url?: string;
        };
    };
    /**
     * Configuration for LLMs text files.
     *
     * @see https://llmstxt.org/
     */
    llms?: LlmsConfig | false;
    /** Sidebar configuration for navigation within the documentation. */
    sidebar?: Sidebar;
    /** Active or desactivated sidebar autogenerated */
    autoSidebar?: {
        /**
         * Display the "Get started" section in the sidebar.
         *
         * @default true
         */
        intro?: boolean;
        /**
         * Display the "Reference" section in the sidebar.
         *
         * @default true
         */
        reference?: boolean;
        /**
         * Display the "Contribute" section in the sidebar.
         *
         * @default true
         */
        contribute?: boolean;
        /**
         * Display the "About" section in the sidebar.
         *
         * @default true
         */
        about?: boolean;
    };
    /** Navigation configuration for links at the top of the documentation. */
    nav?: Nav;
    /**
     * Additional navigation links.
     * Icons IDs: https://simpleicons.org/.
     */
    navLinks?: SocialLinks;
    /** Server-related configurations, including file watching settings. */
    server?: {
        /** Files that trigger a hot reload on changes. */
        hotReloadFiles?: string[];
        /** Files that trigger a server restart on changes. */
        restartFiles?: string[];
    };
    /** Contributors information including their details and social links. */
    contributors?: {
        /** Avatar image for the member. */
        avatar: string;
        /** Name of the member. */
        name: string;
        /** Title to be shown below member's name (e.g., Developer). */
        title?: string;
        /** Organization that the member belongs to. */
        org?: string;
        /** URL for the organization. */
        orgLink?: string;
        /** Description for the member. */
        desc?: string;
        /**
         * Social links for the member (e.g., GitHub, Twitter).
         * Icons IDs: https://simpleicons.org/.
         */
        links?: SocialLinks;
        /** URL for the sponsor page for the member. */
        sponsor?: string;
        /** Text for the sponsor link. Defaults to 'Sponsor'. */
        actionText?: string;
    }[];
    /** Additional links to display in a special page. */
    links?: Links;
    /** Data related to downloads and version releases. */
    download?: {
        /**
         * Optional grouping of download items by category.
         * Each key in the object represents a group name and maps to a string label.
         *
         * @example
         * {
         *   "extension": "extension",
         *   "app": "app",
         * }
         */
        groups?: {
            [key: string]: string;
        };
        /**
         * Optional list of downloadable items, where each key represents an item identifier.
         * Each item includes details such as name, URL, and optionally a logo and type.
         */
        items?: {
            [key: string]: {
                /** Name of the downloadable item */
                name: string;
                /** URL to access the downloadable item */
                url: string;
                /** Optional URL for the logo or icon associated with the item */
                logo?: string;
                /** Optional type/category of the item, e.g., "pdf", "image" */
                type?: string;
            };
        };
    };
    /** Group icon options */
    groupIcon?: Parameters<typeof groupIconVitePlugin>[0] | false;
    /** Twoslash options */
    twoslash?: Parameters<typeof transformerTwoslash>[0] | false;
    /** VitePress user configuration for additional options. */
    vitepress?: UserConfig;
    /**
     * Settings for experimental options.
     *
     * **Use at your own risk**.
     */
    experimental?: {
        /**
         * Disable temp directory during compilation.
         * The temp directory is used to store documentation files in the output directory during the compilation process.
         * Used to allow input paths with '../'.
         *
         * @default false
         */
        noTempDirOnBuild?: boolean;
    };
};

/**
 * Configuration for auto PWA assets generation.
 *
 * **Requires**: `@vite-pwa/assets-generator`.
 *
 * @type {PwaOptions['pwaAssets']}
 * @example
 * const docsConfig = {
 *  pwa: {
 *    pwaAssets: autoPWAConfig
 *  }
 * }
 */
declare const autoPWAConfig: PwaOptions['pwaAssets'];

/**
 * Defines a configuration object for the dovenv documentation plugin.
 *
 * @param   {( DocsConfig | DocsConfig[] )[]} config - The configuration object.
 * @returns {DocsConfig}                             The defined configuration object.
 */
declare const defineConfig: (...config: (DocsConfig | DocsConfig[])[]) => DocsConfig;

/**
 * Extracts and constructs documentation configuration from package JSON data.
 *
 * @param   {PackageJSON}         pkgData - The package JSON data object.
 * @returns {Promise<DocsConfig>}         A promise that resolves to a `DocsConfig` object containing extracted configuration details like funding URL, bugs URL, license, homepage URL, description, name, version, and contributors.
 */
declare const getPkgConfig: (pkgData: PackageJSON) => Promise<DocsConfig>;

type Response<T> = Promise<T> | T;
type Config = DocsConfig | ((utils: CommandUtils) => Response<DocsConfig>);
type DocsParams = {
    config?: Config;
    utils: CommandUtils;
    opts?: {
        packageJsonPath?: string;
        configPath?: string;
        debug?: boolean;
        port?: number;
    };
};

declare class DocsCore {
    #private;
    protected utils: DocsParams['utils'];
    opts: DocsParams['opts'];
    constructor({ utils, opts, }: DocsParams);
    /**
     * __Starts the development server__.
     *
     * This command is a wrapper of the `npx vitepress dev` command.
     *
     * @param {string[]} [flags] - Flags to pass to the underlying `vitepress dev`
     *                           command. The `--force` flag is always passed to ensure the server starts
     *                           without prompting the user.
     */
    dev(flags?: string[]): Promise<void>;
    /**
     * __Builds the documentation site__.
     *
     * This command is a wrapper of the `npx vitepress build` command.
     *
     * @param {string[]} [flags] - Flags to pass to the underlying `vitepress build`
     *                           command. This allows for customization and control over the build process.
     */
    build(flags?: string[]): Promise<void>;
    /**
     * __Starts the preview server__.
     *
     * This command is a wrapper of the `npx vitepress preview` command.
     *
     * @param {string[]} [flags] - Flags to pass to the underlying `vitepress preview`
     *                           command. This allows for customization and control over the preview process.
     */
    preview(flags?: string[]): Promise<void>;
    /**
     * Generate assets for PWA.
     *
     * @param {string[]} [flags] - Flags to pass '@vite-pwa/assets-generator' cli.
     * @see https://vite-pwa-org.netlify.app/assets-generator/cli.html
     */
    generatePWAassets(flags?: string[]): Promise<void>;
    publishToCloudflare(opts: {
        dir: string;
        name: string;
    }): Promise<void>;
}
/**
 * Creates DOCUMENTATION instance.
 *
 * @param   {Omit<DocsParams, 'utils'>}             [args]  - Optional arguments excluding 'utils'.
 * @param   {Parameters<typeof getCommandUtils>[0]} [utils] - Optional utilities parameters.
 * @returns {Promise<DocsCore>}                             A promise that resolves to an instance of DocsCore.
 */
declare const docs: (args?: Omit<DocsParams, "utils">, utils?: Parameters<typeof getCommandUtils>[0]) => Promise<DocsCore>;

/**
 * Define a `dovenv` configuration that creates a documentation site for your workspace.
 *
 * @param   {DocsParams['config'] }         [config] - The configuration object.
 * @returns {DocsParams['utils']['config']}          The dovenv configuration object.
 */
declare const docsPlugin: (config?: DocsParams["config"]) => _dovenv_core.Config;

export { autoPWAConfig, docsPlugin as default, defineConfig, docs, docsPlugin, getPkgConfig };
export type { Config, DocsConfig, DocsParams };