import { Message } from "./message.js";
import { Usage, UsageTerm } from "./usage.js";

//#region src/doc.d.ts

/**
 * A documentation entry which describes a specific usage of a command or
 * option.  It includes a subject (the usage), a description, and an optional
 * default value.
 */
interface DocEntry {
  /**
   * The subject of the entry, which is typically a command or option
   * usage.
   */
  readonly term: UsageTerm;
  /**
   * A description of the entry, which provides additional context or
   * information about the usage.
   */
  readonly description?: Message;
  /**
   * An optional default value for the entry, which can be used to
   * indicate what the default behavior is if the command or option is not
   * specified.
   */
  readonly default?: Message;
  /**
   * An optional list of valid choices for the entry, formatted as a
   * comma-separated {@link Message}.  When present and the `showChoices`
   * formatting option is enabled, this is appended to the entry description.
   *
   * @since 0.10.0
   */
  readonly choices?: Message;
}
/**
 * A section in a document that groups related entries together.
 */
interface DocSection {
  readonly title?: string;
  readonly entries: readonly DocEntry[];
}
/**
 * A document page that contains multiple sections, each with its own brief
 * and a list of entries. This structure is used to organize documentation
 * for commands, options, and other related information.
 */
interface DocPage {
  readonly brief?: Message;
  readonly usage?: Usage;
  readonly description?: Message;
  readonly sections: readonly DocSection[];
  /**
   * Usage examples for the program.
   * @since 0.10.0
   */
  readonly examples?: Message;
  /**
   * Author information.
   * @since 0.10.0
   */
  readonly author?: Message;
  /**
   * Information about where to report bugs.
   * @since 0.10.0
   */
  readonly bugs?: Message;
  readonly footer?: Message;
}
/**
 * A documentation fragment that can be either an entry or a section.
 * Fragments are building blocks used to construct documentation pages.
 */
type DocFragment = {
  readonly type: "entry";
} & DocEntry | {
  readonly type: "section";
} & DocSection;
/**
 * A collection of documentation fragments with an optional description.
 * This structure is used to gather fragments before organizing them into
 * a final document page.
 */
interface DocFragments {
  /**
   * An optional brief that provides a short summary for the collection
   * of fragments.
   * @since 0.7.12
   */
  readonly brief?: Message;
  /**
   * An optional description that applies to the entire collection of fragments.
   */
  readonly description?: Message;
  /**
   * An array of documentation fragments that can be entries or sections.
   */
  readonly fragments: readonly DocFragment[];
  /**
   * An optional footer that appears at the bottom of the documentation.
   * @since 0.6.0
   */
  readonly footer?: Message;
}
/**
 * Returns whether a doc entry's term is hidden from documentation.
 * Only term types with a `hidden` field (argument, option, command,
 * passthrough) are checked; other types always return `false`.
 *
 * @param entry The doc entry to check.
 * @returns `true` if the entry should be hidden from documentation.
 * @since 1.0.0
 */
declare function isDocEntryHidden(entry: DocEntry): boolean;
/**
 * Removes duplicate {@link DocEntry} values that share the same surface
 * syntax (same term type and identifying names).  Doc-hidden entries are
 * filtered out first so they cannot influence the ordering of visible
 * entries.  Among the remaining visible entries, the first occurrence is
 * kept and later duplicates are discarded.
 *
 * Positional argument entries are never deduplicated because they are
 * distinguished by position, not by metavar, and {@link DocEntry} does
 * not carry position information.
 *
 * @param entries The entries to deduplicate.
 * @returns A new array with hidden entries removed and duplicates
 *   collapsed, preserving insertion order of visible entries.
 * @since 1.0.0
 */
declare function deduplicateDocEntries(entries: readonly DocEntry[]): DocEntry[];
/**
 * Removes duplicate entries from a list of {@link DocFragment} values.
 * Entry-type fragments are deduplicated by their surface syntax key.
 * Section-type fragments have their entries deduplicated internally.
 *
 * @param fragments The fragments to deduplicate.
 * @returns A new array with duplicate entries removed.
 * @since 1.0.0
 */
declare function deduplicateDocFragments(fragments: readonly DocFragment[]): DocFragment[];
/**
 * Creates a deep clone of a {@link DocEntry}.  The `term` is cloned via
 * {@link cloneUsageTerm}, and `description`, `default`, and `choices`
 * messages are cloned via {@link cloneMessage}.
 *
 * @param entry The documentation entry to clone.
 * @returns A structurally equal but referentially distinct copy.
 * @since 1.0.0
 */
declare function cloneDocEntry(entry: DocEntry): DocEntry;
/**
 * Configuration for customizing default value display formatting.
 *
 * @since 0.4.0
 */
interface ShowDefaultOptions {
  /**
   * Text to display before the default value.
   *
   * @default `" ["`
   */
  readonly prefix?: string;
  /**
   * Text to display after the default value.
   *
   * @default `"]"`
   */
  readonly suffix?: string;
}
/**
 * Configuration for customizing choices display formatting.
 *
 * @since 0.10.0
 */
interface ShowChoicesOptions {
  /**
   * Text to display before the choices list.
   *
   * @default `" ("`
   */
  readonly prefix?: string;
  /**
   * Text to display after the choices list.
   *
   * @default `")"`
   */
  readonly suffix?: string;
  /**
   * Label text to display before the individual choice values.
   *
   * @default `"choices: "`
   */
  readonly label?: string;
  /**
   * Maximum number of choice values to display before truncating with
   * `...`.  Must be at least `1`.  Set to `Infinity` to show all choices.
   *
   * @default `8`
   * @throws {RangeError} If the value is less than `1`.
   */
  readonly maxItems?: number;
}
/**
 * Options for formatting a documentation page.
 */
interface DocPageFormatOptions {
  /**
   * Whether to include ANSI color codes in the output.
   * @default `false`
   */
  colors?: boolean;
  /**
   * Number of spaces to indent terms in documentation entries.
   * @default `2`
   */
  termIndent?: number;
  /**
   * Width allocated for terms before descriptions start.
   * @default `26`
   */
  termWidth?: number;
  /**
   * Maximum width of the entire formatted output.
   */
  maxWidth?: number;
  /**
   * Whether and how to display default values for options and arguments.
   *
   * - `boolean`: When `true`, displays defaults using format `[value]`
   * - `ShowDefaultOptions`: Custom formatting with configurable prefix and suffix
   *
   * Default values are automatically dimmed when `colors` is enabled.
   *
   * @default `false`
   * @since 0.4.0
   *
   * @example
   * ```typescript
   * // Basic usage - shows "[3000]"
   * { showDefault: true }
   *
   * // Custom format - shows "(default: 3000)"
   * { showDefault: { prefix: " (default: ", suffix: ")" } }
   *
   * // Custom format - shows " - defaults to 3000"
   * { showDefault: { prefix: " - defaults to ", suffix: "" } }
   * ```
   */
  showDefault?: boolean | ShowDefaultOptions;
  /**
   * Whether and how to display valid choices for options and arguments
   * backed by enumerated value parsers (e.g., `choice()`).
   *
   * - `boolean`: When `true`, displays choices using format
   *   `(choices: a, b, c)`
   * - `ShowChoicesOptions`: Custom formatting with configurable prefix,
   *   suffix, label, and maximum number of items
   *
   * Choice values are automatically dimmed when `colors` is enabled.
   *
   * @default `false`
   * @since 0.10.0
   *
   * @example
   * ```typescript
   * // Basic usage - shows "(choices: json, yaml, xml)"
   * { showChoices: true }
   *
   * // Custom format - shows "{json | yaml | xml}"
   * { showChoices: { prefix: " {", suffix: "}", label: "" } }
   *
   * // Limit displayed choices
   * { showChoices: { maxItems: 3 } }
   * ```
   */
  showChoices?: boolean | ShowChoicesOptions;
  /**
   * A custom comparator function to control the order of sections in the
   * help output.  When provided, it is used instead of the default smart
   * sort (command-only sections first, then mixed, then option/argument-only
   * sections).  Sections that compare equal (return `0`) preserve their
   * original relative order (stable sort).
   *
   * @param a The first section to compare.
   * @param b The second section to compare.
   * @returns A negative number if `a` should appear before `b`, a positive
   *   number if `a` should appear after `b`, or `0` if they are equal.
   * @since 1.0.0
   *
   * @example
   * ```typescript
   * // Sort sections alphabetically by title
   * {
   *   sectionOrder: (a, b) => (a.title ?? "").localeCompare(b.title ?? "")
   * }
   * ```
   */
  sectionOrder?: (a: DocSection, b: DocSection) => number;
}
/**
 * Formats a documentation page into a human-readable string.
 *
 * This function takes a structured {@link DocPage} and converts it into
 * a formatted string suitable for display in terminals or documentation.
 * The formatting includes proper indentation, alignment, and optional
 * color support.
 *
 * @param programName The name of the program, used in usage lines
 * @param page The documentation page to format
 * @param options Formatting options to customize the output
 * @returns A formatted string representation of the documentation page
 * @throws {TypeError} If `programName` is not a string, is empty,
 * whitespace-only, or contains control characters, if any non-empty
 * section's title is not a string, is empty, whitespace-only, or contains
 * control characters, or if `maxWidth` is not a finite integer.
 * @throws {RangeError} If any entry needs a description column and `maxWidth`
 * is too small to fit the minimum layout (less than `termIndent + 4`), or if
 * `showChoices.maxItems` is less than `1`.
 *
 * @example
 * ```typescript
 * const page: DocPage = {
 *   brief: "A CLI tool",
 *   usage: [{ type: "literal", value: "myapp" }],
 *   sections: [{
 *     title: "Options",
 *     entries: [{
 *       term: { type: "option", short: "-v", long: "--verbose" },
 *       description: "Enable verbose output"
 *     }]
 *   }]
 * };
 *
 * const formatted = formatDocPage("myapp", page, { colors: true });
 * console.log(formatted);
 * ```
 */
declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
//#endregion
export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };