/**
* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
*/
/**
* @module ui/labeledfield/labeledfieldview
*/
import { View } from "../view.js";
import { LabelView } from "../label/labelview.js";
import type { FocusableView } from "../focuscycler.js";
import { type ViewCollection } from "../viewcollection.js";
import { type Locale } from "@ckeditor/ckeditor5-utils";
import "../../theme/components/labeledfield/labeledfieldview.css";
/**
* The labeled field view class. It can be used to enhance any view with the following features:
*
* * a label,
* * (optional) an error message,
* * (optional) an info (status) text,
*
* all bound logically by proper DOM attributes for UX and accessibility.  It also provides an interface
* (e.g. observable properties) that allows controlling those additional features.
*
* The constructor of this class requires a callback that returns a view to be labeled. The callback
* is called with unique ids that allow binding of DOM properties:
*
* ```ts
* const labeledInputView = new LabeledFieldView( locale, ( labeledFieldView, viewUid, statusUid ) => {
* 	const inputView = new InputTextView( labeledFieldView.locale );
*
* 	inputView.set( {
* 		id: viewUid,
* 		ariaDescribedById: statusUid
* 	} );
*
* 	inputView.bind( 'isReadOnly' ).to( labeledFieldView, 'isEnabled', value => !value );
* 	inputView.bind( 'hasError' ).to( labeledFieldView, 'errorText', value => !!value );
*
* 	return inputView;
* } );
*
* labeledInputView.label = 'User name';
* labeledInputView.infoText = 'Full name like for instance, John Doe.';
* labeledInputView.render();
*
* document.body.append( labeledInputView.element );
* ```
*
* See {@link module:ui/labeledfield/utils} to discover ready–to–use labeled input helpers for common
* UI components.
*/
export declare class LabeledFieldView<TFieldView extends FocusableView = FocusableView> extends View {
	/**
	* The field view that gets labeled.
	*/
	readonly fieldView: TFieldView;
	/**
	* The label view instance that describes the entire view.
	*/
	readonly labelView: LabelView;
	/**
	* The status view for the {@link #fieldView}. It displays {@link #errorText} and
	* {@link #infoText}.
	*/
	readonly statusView: View;
	/**
	* A collection of children of the internal wrapper element. Allows inserting additional DOM elements (views) next to
	* the {@link #fieldView} for easy styling (e.g. positioning).
	*
	* By default, the collection contains {@link #fieldView} and {@link #labelView}.
	*/
	readonly fieldWrapperChildren: ViewCollection;
	/**
	* The text of the label.
	*
	* @observable
	*/
	label: string | undefined;
	/**
	* Controls whether the component is in read-only mode.
	*
	* @observable
	*/
	isEnabled: boolean;
	/**
	* An observable flag set to `true` when {@link #fieldView} is empty (`false` otherwise).
	*
	* @readonly
	* @observable
	* @default true
	*/
	isEmpty: boolean;
	/**
	* An observable flag set to `true` when {@link #fieldView} is currently focused by
	* the user (`false` otherwise).
	*
	* @readonly
	* @observable
	* @default false
	*/
	isFocused: boolean;
	/**
	* The validation error text. When set, it will be displayed
	* next to the {@link #fieldView} as a typical validation error message.
	* Set it to `null` to hide the message.
	*
	* **Note:** Setting this property to anything but `null` will automatically
	* make the `hasError` of the {@link #fieldView} `true`.
	*
	* @observable
	*/
	errorText: string | null;
	/**
	* The additional information text displayed next to the {@link #fieldView} which can
	* be used to inform the user about its purpose, provide help or hints.
	*
	* Set it to `null` to hide the message.
	*
	* **Note:** This text will be displayed in the same place as {@link #errorText} but the
	* latter always takes precedence: if the {@link #errorText} is set, it replaces
	* {@link #infoText}.
	*
	* @observable
	* @default null
	*/
	infoText: string | null;
	/**
	* (Optional) The additional CSS class set on the dropdown {@link #element}.
	*
	* @observable
	*/
	class: string | undefined;
	/**
	* The content of the `placeholder` attribute of the {@link #fieldView}.
	*
	* @observable
	*/
	placeholder: string | undefined;
	/**
	* The combined status text made of {@link #errorText} and {@link #infoText}.
	* Note that when present, {@link #errorText} always takes precedence in the
	* status.
	*
	* @see #errorText
	* @see #infoText
	* @see #statusView
	* @private
	* @observable
	*/
	_statusText: string | null;
	/**
	* Creates an instance of the labeled field view class using a provided creator function
	* that provides the view to be labeled.
	*
	* @param locale The locale instance.
	* @param viewCreator A function that returns a {@link module:ui/view~View}
	* that will be labeled. The following arguments are passed to the creator function:
	*
	* * an instance of the `LabeledFieldView` to allow binding observable properties,
	* * an UID string that connects the {@link #labelView label} and the labeled field view in DOM,
	* * an UID string that connects the {@link #statusView status} and the labeled field view in DOM.
	*/
	constructor(locale: Locale | undefined, viewCreator: LabeledFieldViewCreator<TFieldView>);
	/**
	* Creates label view class instance and bind with view.
	*
	* @param id Unique id to set as labelView#for attribute.
	*/
	private _createLabelView;
	/**
	* Creates the status view instance. It displays {@link #errorText} and {@link #infoText}
	* next to the {@link #fieldView}. See {@link #_statusText}.
	*
	* @param statusUid Unique id of the status, shared with the {@link #fieldView view's}
	* `aria-describedby` attribute.
	*/
	private _createStatusView;
	/**
	* Focuses the {@link #fieldView}.
	*/
	focus(direction?: 1 | -1): void;
}
/**
* A creator function that returns a focusable view to be labeled by a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView}
* instance.
*/
export type LabeledFieldViewCreator<TFieldView extends FocusableView> = (labeledFieldView: LabeledFieldView, viewUid: string, statusUid: string) => TFieldView;