import { Colors, Formatter } from "ansispeck";
//#region src/core/help/theme.d.ts
/**
 * Semantic styling roles for help output.
 *
 * Roles that appear inside wrap-eligible description text (`defaultValue`,
 * `annotation`, `deprecated`) should stick to foreground colors and `dim` —
 * a styled span may cross a soft-wrap boundary, and while color/dim carry
 * invisibly across the continuation indent, `underline`/`inverse`/background
 * styles would visibly paint it.
 */
interface HelpTheme {
  /** Section headings: `Usage:`, `Arguments:`, `Flags:`, `Commands:`, `Examples:`, `Global options:`. */
  readonly sectionTitle: Formatter;
  /** Binary / command path in the usage line. */
  readonly usageBin: Formatter;
  /** Flag forms in the flags table: `-f, --force`. */
  readonly flag: Formatter;
  /** Grammar tokens: `<string>`, `<command>`, `[flags]`, value hints. */
  readonly placeholder: Formatter;
  /** Command names in `Commands:` tables. */
  readonly command: Formatter;
  /** Positional arg tokens: `<file>`, `[out]...`. */
  readonly arg: Formatter;
  /** Default-value annotations: `(default: 8080)`. */
  readonly defaultValue: Formatter;
  /** Metadata annotations: `[env: X]`, `[config: a.b]`, `[prompt]`, `[required]`, ` (default)`. */
  readonly annotation: Formatter;
  /** Deprecation labels: `[deprecated]`, `[deprecated: use --x]`. */
  readonly deprecated: Formatter;
  /** Program name in the root-help header. */
  readonly headerName: Formatter;
  /** Version (`vX.Y.Z`) in the root-help header. */
  readonly headerVersion: Formatter;
  /** The `$` prompt marker in `Examples:`. */
  readonly examplePrompt: Formatter;
}
/**
 * User theme customization: receives the gated palette and returns role
 * overrides merged over the default theme.
 *
 * The palette formatters are identity functions when color is disabled, and
 * the factory itself is only invoked when color is enabled — style
 * unconditionally, gating is the framework's job.
 */
type HelpThemeFactory = (colors: Colors) => Partial<HelpTheme>;
/**
 * The built-in help theme (clap/cargo conventions).
 *
 * @param c - Palette to build formatters from (typically the gated `out.color`).
 * @internal
 */
declare function defaultHelpTheme(c: Colors): HelpTheme;
/**
 * Resolve the effective help theme from a palette and optional user factory.
 *
 * When the palette renders no styling (color disabled — its formatters are
 * identity functions), the user factory is **never invoked**: even a factory
 * that emits raw escapes cannot leak them into color-off output. When color
 * is enabled, factory overrides merge over {@linkcode defaultHelpTheme}.
 *
 * @param colors - Gated palette, or `undefined` for a color-off theme.
 * @param theme - Optional user overrides factory.
 * @internal
 */
declare function resolveHelpTheme(colors: Colors | undefined, theme: HelpThemeFactory | undefined): HelpTheme;
//#endregion
export { type HelpTheme, type HelpThemeFactory, defaultHelpTheme, resolveHelpTheme };