import { NonEmptyString } from "./nonempty.cjs";

//#region src/message.d.ts

/**
 * Represents a single term in a message, which can be a text, an option
 * name, a list of option names, a metavariable, a value, or a list of
 * consecutive values.
 */
type MessageTerm =
/**
 * A plain text term in the message.
 */
{
  /**
   * The type of the term, which is always `"text"` for plain text.
   */
  readonly type: "text";
  /**
   * The text content of the term.
   */
  readonly text: string;
}
/**
 * An option name term in the message, which can be a single
 * option name.  Although it is named option name, it can also
 * represent a subcommand.
 */ | {
  /**
   * The type of the term, which is `"optionName"` for a single option name.
   */
  readonly type: "optionName";
  /**
   * The name of the option, which can be a short or long option name.
   * For example, `"-f"` or `"--foo"`.
   */
  readonly optionName: string;
}
/**
 * A list of option names term in the message, which can be a
 * list of option names.
 */ | {
  /**
   * The type of the term, which is `"optionNames"` for a list of option
   * names.
   */
  readonly type: "optionNames";
  /**
   * The list of option names, which can include both short and long
   * option names.  For example, `["--foo", "--bar"]`.
   */
  readonly optionNames: readonly string[];
}
/**
 * A metavariable term in the message, which can be a single
 * metavariable.
 */ | {
  /**
   * The type of the term, which is `"metavar"` for a metavariable.
   */
  readonly type: "metavar";
  /**
   * The metavariable name, which is a string that represents
   * a variable in the message.  For example, `"VALUE"` or `"ARG"`.
   */
  readonly metavar: NonEmptyString;
}
/**
 * A value term in the message, which can be a single value.
 */ | {
  /**
   * The type of the term, which is `"value"` for a single value.
   */
  readonly type: "value";
  /**
   * The value, which can be any string representation of a value.
   * For example, `"42"` or `"hello"`.
   */
  readonly value: string;
}
/**
 * A list of values term in the message, which can be a
 * list of values.
 */ | {
  /**
   * The type of the term, which is `"values"` for a list of consecutive
   * values.
   */
  readonly type: "values";
  /**
   * The list of values, which can include multiple string
   * representations of consecutive values.  For example, `["42", "hello"]`.
   */
  readonly values: readonly string[];
}
/**
 * An environment variable term in the message, which represents
 * an environment variable name.
 * @since 0.5.0
 */ | {
  /**
   * The type of the term, which is `"envVar"` for an environment variable.
   */
  readonly type: "envVar";
  /**
   * The environment variable name, which is a string that represents
   * an environment variable. For example, `"PATH"` or `"API_URL"`.
   */
  readonly envVar: string;
}
/**
 * A command-line term in the message, which represents
 * a command-line example or snippet.
 * @since 0.6.0
 */ | {
  /**
   * The type of the term, which is `"commandLine"` for a command-line example.
   */
  readonly type: "commandLine";
  /**
   * The command-line string, which can be a complete command with arguments.
   * For example, `"myapp completion bash > myapp-completion.bash"`.
   */
  readonly commandLine: string;
}
/**
 * An explicit single-line break term in the message.
 * @since 0.10.0
 */ | {
  /**
   * The type of the term, which is `"lineBreak"` for an explicit line break.
   */
  readonly type: "lineBreak";
}
/**
 * A URL term in the message, which represents a clickable hyperlink.
 * @since 0.10.0
 */ | {
  /**
   * The type of the term, which is `"url"` for a URL.
   */
  readonly type: "url";
  /**
   * The URL object representing the hyperlink.
   */
  readonly url: URL;
};
/**
 * Type representing a message that can include styled/colored values.
 * This type is used to create structured messages that can be
 * displayed to the user with specific formatting.
 */
type Message = readonly MessageTerm[];
/**
 * Creates a deep clone of a {@link MessageTerm}.  Most variants contain only
 * primitive fields and are cloned via object spread.  The `url` variant
 * receives a new `URL` object (since `structuredClone` cannot handle `URL`
 * on Node.js), and array-valued fields (`optionNames`, `values`) are
 * shallow-copied.
 *
 * @param term The message term to clone.
 * @returns A structurally equal but referentially distinct copy.
 * @since 1.0.0
 */
declare function cloneMessageTerm(term: MessageTerm): MessageTerm;
/**
 * Creates a deep clone of a {@link Message} array and all of its terms.
 *
 * @param msg The message to clone.
 * @returns A structurally equal but referentially distinct copy.
 * @since 1.0.0
 */
declare function cloneMessage(msg: Message): Message;
/**
 * Creates a structured message with template strings and values.
 *
 * This function allows creating messages where specific values can be
 * highlighted or styled differently when displayed to the user.
 *
 * @example
 * ```typescript
 * const error = message`Expected number between ${min} and ${max}, got ${value}`;
 * const concat = message`${optionName("--age")}: ${error}`;
 * ```
 *
 * @param message Template strings array (from template literal).
 * @param values Values to be interpolated into the template.
 * @returns A structured Message object.
 */
declare function message(message: TemplateStringsArray, ...values: readonly (MessageTerm | Message | string)[]): Message;
/**
 * Creates a {@link MessageTerm} for plain text.  Usually used for
 * dynamically generated messages.
 * @param text The plain text to be included in the message.
 * @returns A {@link MessageTerm} representing the plain text.
 */
declare function text(text: string): MessageTerm;
/**
 * Creates a {@link MessageTerm} for an option name.
 * @param name The name of the option, which can be a short or long option name.
 *             For example, `"-f"` or `"--foo"`.
 * @returns A {@link MessageTerm} representing the option name.
 */
declare function optionName(name: string): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a list of option names.
 * @param names The list of option names, which can include both short and long
 *              option names. For example, `["--foo", "--bar"]`.
 * @returns A {@link MessageTerm} representing the list of option names.
 */
declare function optionNames(names: readonly string[]): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a metavariable.
 * @param metavar The metavariable name, which is a string that represents
 *                a variable in the message. For example, `"VALUE"` or
 *                `"ARG"`.
 * @returns A {@link MessageTerm} representing the metavariable.
 */
declare function metavar(metavar: NonEmptyString): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a single value.  However, you usually
 * don't need to use this function directly, as {@link message} string template
 * will automatically create a {@link MessageTerm} for a value when
 * you use a string in a template literal.
 * @param value The value, which can be any string representation of a value.
 *              For example, `"42"` or `"hello"`.
 * @returns A {@link MessageTerm} representing the value.
 */
declare function value(value: string): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a list of consecutive values.
 * @param values The list of consecutive values, which can include multiple
 *               string representations of consecutive values.
 *               For example, `["42", "hello"]`.
 * @returns A {@link MessageTerm} representing the list of values.
 * @throws {TypeError} If the values array is empty.
 */
declare function values(values: readonly string[]): MessageTerm;
/**
 * Creates a {@link MessageTerm} for an environment variable.
 * @param envVar The environment variable name, which is a string that represents
 *               an environment variable. For example, `"PATH"` or `"API_URL"`.
 * @returns A {@link MessageTerm} representing the environment variable.
 * @since 0.5.0
 */
declare function envVar(envVar: string): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a command-line example.
 * @param commandLine The command-line string, which can be a complete command
 *                    with arguments. For example,
 *                    `"myapp completion bash > myapp-completion.bash"`.
 * @returns A {@link MessageTerm} representing the command-line example.
 * @since 0.6.0
 */
declare function commandLine(commandLine: string): MessageTerm;
/**
 * Creates a {@link MessageTerm} for an explicit single-line break.
 *
 * Unlike single `\n` in `text()` terms (which are treated as soft breaks and
 * normalized to spaces), this term always renders as a hard line break.
 *
 * @returns A {@link MessageTerm} representing an explicit line break.
 * @since 0.10.0
 */
declare function lineBreak(): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a URL.
 * @param url The URL, which can be a URL object or a string that can be parsed
 *            as a URL. For example, `"https://example.com"` or
 *            `new URL("https://example.com")`.
 * @returns A {@link MessageTerm} representing the URL.
 * @throws {RangeError} If the URL string cannot be parsed.
 * @since 0.10.0
 */
declare function url(url: string | URL): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a URL (alias for {@link url}).
 *
 * This is an alias for the {@link url} function, provided for convenience
 * when you want to avoid potential naming conflicts with the `url()` value
 * parser from `@optique/core/valueparser`.
 *
 * @param href The URL, which can be a URL object or a string that can be parsed
 *             as a URL. For example, `"https://example.com"` or
 *             `new URL("https://example.com")`.
 * @returns A {@link MessageTerm} representing the URL.
 * @throws {RangeError} If the URL string cannot be parsed.
 * @since 0.10.0
 */
declare function link(href: string | URL): MessageTerm;
/**
 * Options for the {@link valueSet} function.
 * @since 0.9.0
 */
interface ValueSetOptions {
  /**
   * The locale(s) to use for list formatting.  Can be a BCP 47 language tag
   * string, an array of language tags, an `Intl.Locale` object, or an array
   * of `Intl.Locale` objects.  If not specified, the system default locale
   * is used.
   */
  readonly locale?: string | readonly string[] | Intl.Locale | readonly Intl.Locale[];
  /**
   * The type of list to format:
   *
   * - `"conjunction"`: "A, B, and C" (default)
   * - `"disjunction"`: "A, B, or C"
   * - `"unit"`: "A, B, C"
   *
   * @default `"conjunction"`
   */
  readonly type?: "conjunction" | "disjunction" | "unit";
  /**
   * The style of the list formatting:
   *
   * - `"long"`: "A, B, and C" (default)
   * - `"short"`: "A, B, & C"
   * - `"narrow"`: "A, B, C"
   *
   * @default `"long"`
   */
  readonly style?: "long" | "short" | "narrow";
  /**
   * A fallback text to return when the values array is empty.  When provided
   * and the values array is empty, a {@link Message} containing a single text
   * term with this string is returned instead of an empty {@link Message}.
   * An empty string produces an empty {@link Message}.
   *
   * @since 1.0.0
   */
  readonly fallback: string;
}
/**
 * Creates a {@link Message} for a formatted list of values using the
 * `Intl.ListFormat` API.  This is useful for displaying choice lists
 * in error messages with proper locale-aware formatting.
 *
 * Each value in the list becomes a separate value term, and the separators
 * (commas, "and", "or", etc.) become text terms.  This allows each value
 * to be styled independently while respecting the locale's list formatting
 * conventions.
 *
 * A fallback must be provided for when the values array is empty.  This can
 * be either a simple string (shorthand) or an options object with a
 * `fallback` field.  When the values array is empty, the fallback text
 * is returned as a single text term.  An empty fallback string produces
 * an empty {@link Message}.
 *
 * @example
 * ```typescript
 * // English conjunction (default): "error", "warn", and "info"
 * const msg1 = message`Expected one of ${
 *   valueSet(["error", "warn", "info"], "")
 * }.`;
 *
 * // English disjunction: "error", "warn", or "info"
 * const msg2 = message`Expected ${
 *   valueSet(["error", "warn", "info"], { fallback: "", type: "disjunction" })
 * }.`;
 *
 * // Fallback for empty list:
 * const msg3 = message`Expected one of ${valueSet([], "(none)")}.`;
 * // → "Expected one of (none)."
 * ```
 *
 * @param values The list of values to format.
 * @param fallbackOrOptions A fallback string for empty lists, or an options
 *                          object including the fallback and formatting
 *                          options such as locale and list type.
 * @returns A {@link Message} with alternating value and text terms.
 * @throws {TypeError} If the fallback parameter is missing or invalid.
 * @since 0.9.0
 */
declare function valueSet(values: readonly string[], fallbackOrOptions: string | ValueSetOptions): Message;
/**
 * Options for the {@link formatMessage} function.
 */
interface MessageFormatOptions {
  /**
   * Whether to use colors in the formatted message.  If `true`,
   * the formatted message will include ANSI escape codes for colors.
   * If `false`, the message will be plain text without colors.
   *
   * Can also be an object with additional color options:
   *
   * - `resetSuffix`: String to append after each ANSI reset sequence (`\x1b[0m`)
   *   to maintain parent styling context.
   *
   * @default `false`
   */
  readonly colors?: boolean | {
    /**
     * String to append after each ANSI reset sequence to maintain
     * parent styling context (e.g., `"\x1b[2m"` for dim text).
     */
    readonly resetSuffix?: string;
  };
  /**
   * Whether to use quotes around values in the formatted message.
   * If `true`, values will be wrapped in quotes (e.g., `"value"`).
   * If `false`, values will be displayed without quotes.
   * @default `true`
   */
  readonly quotes?: boolean;
  /**
   * The maximum width of the formatted message.  If specified,
   * the message will be wrapped to fit within this width.
   * If not specified, the message will not be wrapped.
   * @default `undefined`
   */
  readonly maxWidth?: number;
}
/**
 * Formats a {@link Message} into a human-readable string for
 * the terminal.
 * @param msg The message to format, which is an array of
 *              {@link MessageTerm} objects.
 * @param options Optional formatting options to customize the output.
 * @returns A formatted string representation of the message.
 */
declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
//#endregion
export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };