/**
 * @license
 * Copyright 2026 Steven Roussey <sroussey@gmail.com>
 * SPDX-License-Identifier: Apache-2.0
 */
import type { WebInvocation } from "../argv";
import type { WebField } from "../commandFields";
export type FormValues = Record<string, string | boolean>;
export declare function initialValues(fields: readonly WebField[]): FormValues;
/**
 * Turns the form into the invocation the server runs.
 *
 * Arguments keep their declared order — they are positional — and a value
 * equal to its default is dropped, so the rendered command line says what you
 * changed rather than restating the command's own defaults back at you.
 */
export declare function toInvocation(fields: readonly WebField[], values: FormValues, path: readonly string[]): WebInvocation;
/**
 * The inverse of {@link toInvocation}: an invocation read back into the form.
 *
 * Arguments are positional, so they fill the argument fields in declared
 * order; options and config land by key. Whatever the invocation does not
 * mention keeps the field's own default, so a partially specified invocation
 * fills what it knows and leaves the rest as the form would have opened.
 */
export declare function valuesFromInvocation(fields: readonly WebField[], invocation: WebInvocation): FormValues;
export declare function formErrors(fields: readonly WebField[], values: FormValues): string[];
/** The fields a form shows before the fold, and the ones it hides behind it. */
export declare function splitFields(fields: readonly WebField[]): {
    readonly args: readonly WebField[];
    readonly inputs: readonly WebField[];
    readonly advanced: readonly WebField[];
};
/** What the widget needs to answer a scoped question, and nothing more. */
export interface WidgetScope {
    readonly path: readonly string[];
    readonly args: readonly string[];
    readonly values: FormValues;
}
/**
 * A scope's content as a string, for use as an effect dependency.
 *
 * Deliberately covers exactly what a widget search sends — the path, the
 * positional arguments and the field values — so two scopes that would produce
 * the same request compare equal however many times the form has re-rendered.
 */
export declare function stableScopeKey(scope: WidgetScope): string;
/**
 * Appends to a comma-separated field rather than replacing it.
 *
 * `--models` and `--extractors` take lists, and picking a second model from a
 * picker that replaces is picking nothing: you get the last one you clicked.
 */
export declare function appendValue(current: string, picked: string): string;