import { HelpTheme, HelpThemeFactory } from "./theme.mjs";
import { osc8, visibleWidth } from "./ansi.mjs";
import { CommandSchema } from "../schema/command.mjs";
import "../schema/index.mjs";
import { Colors } from "ansispeck";
//#region src/core/help/index.d.ts
/** Options for customising help output. */
interface HelpOptions {
  /** Maximum line width (columns). Defaults to 80. */
  readonly width?: number;
  /** Binary/program name shown in the usage line. Defaults to command name. */
  readonly binName?: string;
  /** Program version passed to function-form examples as `meta.version`. */
  readonly version?: string;
  /**
   * Order of flags in the `Flags:` table.
   *
   * - `'alphabetical'` — short-aliased flags first, then alphabetical by name.
   * - `'declaration'` — the order `.flag()` was called.
   *
   * Ignored when {@link HelpOptions.sortFlags} is set.
   *
   * @defaultValue `'alphabetical'`
   */
  readonly flagOrder?: 'alphabetical' | 'declaration';
  /**
   * Custom comparator over flag long names for the `Flags:` table. When set,
   * it wins over {@link HelpOptions.flagOrder}.
   *
   * @defaultValue `undefined` (use `flagOrder`)
   */
  readonly sortFlags?: (a: string, b: string) => number;
  /**
   * Emit OSC 8 hyperlinks where link metadata is available (currently the
   * root-help header name/version configured via `CLIBuilder.links()`).
   * Defaults to `false`; `CLIBuilder.execute()`/`.run()` enable it
   * automatically when stdout is a TTY.
   */
  readonly hyperlinks?: boolean;
  /**
   * Render the default command's arguments and flags inline in root help.
   *
   * Only affects root-level help. When `false`, root help lists commands and
   * defers default-command details to `<bin> --help`-style hints.
   *
   * @defaultValue `true`
   */
  readonly inlineDefault?: boolean;
  /**
   * List the default command in the root `Commands:` table.
   *
   * By default the default command is treated as the root surface and omitted
   * from the command list (its args/flags render inline instead).
   *
   * @defaultValue `false`
   */
  readonly showDefaultInCommands?: boolean;
  /**
   * Show the `Run '<bin> <command> --help' for more information.` footer.
   *
   * Defaults to showing the hint only when visible subcommands exist; set
   * explicitly to force it on or off.
   */
  readonly footer?: boolean;
  /** @internal Whether this usage line is being rendered as merged root/default help. */
  readonly isDefaultHelp?: boolean;
  /**
   * Gated ANSI palette used to style help output. Identity formatters mean
   * plain text. `CLIBuilder.execute()`/`.run()` thread the output channel's
   * `out.color` here automatically, so styling follows the same policy as
   * handler output (TTY + color support, no `--json`, `NO_COLOR` honored).
   *
   * @defaultValue `undefined` (plain text)
   */
  readonly colors?: Colors;
  /**
   * Theme overrides merged over the built-in help theme. Receives the gated
   * palette; never invoked when color is off, so overrides cannot leak
   * escapes into piped output.
   *
   * @defaultValue `undefined` (built-in theme)
   */
  readonly theme?: HelpThemeFactory;
}
/** Formatted flag entry for the flags table. @internal */
interface FlagEntry {
  /** Preformatted flag names and value hint for the left table column. */
  readonly left: string;
  /** Preformatted help text for the description table column. */
  readonly description: string;
}
/**
 * Build the ordered help sections without joining them.
 *
 * @internal
 * @param schema - The {@link CommandSchema} to render.
 * @param options - Optional {@link HelpOptions} for width/bin name.
 * @returns Array of section strings (usage, description, commands, args, flags, examples).
 */
declare function formatHelpSections(schema: CommandSchema, options?: HelpOptions): readonly string[];
/**
 * Generate help text from a command schema.
 *
 * Low-level formatter: most applications reach this through `--help`,
 * `help <command>`, or root help rendering in `CLIBuilder`. Call
 * `formatHelp()` directly when embedding DreamCLI help text into custom UIs,
 * tests, or generated docs.
 *
 * Sections rendered (in order):
 * 1. **Usage** line — `program <command> [flags] <args>`
 * 2. **Description** — the command's `.description()` text
 * 3. **Commands** — subcommands table (if any, skips hidden)
 * 4. **Arguments** — positional args table (if any)
 * 5. **Flags** — flags table with type hints and defaults
 * 6. **Examples** — usage examples (if any)
 *
 * @param schema - The command schema to render help for.
 * @param options - Formatting options (width, binary name).
 * @returns The formatted help string.
 *
 * @example
 * ```ts
 * const text = formatHelp(deploy.schema, { binName: 'mycli' });
 * ```
 */
declare function formatHelp(schema: CommandSchema, options?: HelpOptions): string;
/**
 * Render a titled two-column flag block from pre-built {@link FlagEntry} rows.
 *
 * Shared by the per-command `Flags:` section and the root-help `Global options:`
 * block (built-in flags), so column alignment and description wrapping stay
 * identical across both. Returns `''` when there are no entries.
 *
 * @param title - Section heading (e.g. `'Flags:'`, `'Global options:'`), pre-styled by the caller.
 * @param entries - Formatted left/description rows.
 * @param width - Terminal width for description wrapping.
 * @returns Multi-line block string, or `''` when `entries` is empty.
 * @internal
 */
declare function formatFlagEntriesBlock(title: string, entries: readonly FlagEntry[], width: number): string;
//#endregion
export { type FlagEntry, type HelpOptions, type HelpTheme, type HelpThemeFactory, formatFlagEntriesBlock, formatHelp, formatHelpSections, osc8, visibleWidth };