@ckeditor/ckeditor5-ui 48.2.0 → 48.3.0-alpha.0

package/dist/labeledfield/labeledfieldview.d.ts

@@ -1,187 +1,187 @@
 /**
- * @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
- */
+* @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';
+* @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.
- */
+* 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;
+	/**
+	* 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.
- */
+* 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;

package/dist/labeledfield/utils.d.ts

@@ -1,123 +1,123 @@
 /**
- * @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
- */
+* @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/utils
- */
-import { InputTextView } from '../inputtext/inputtextview.js';
-import { InputNumberView } from '../inputnumber/inputnumberview.js';
-import { TextareaView } from '../textarea/textareaview.js';
-import { type DropdownView } from '../dropdown/dropdownview.js';
-import type { LabeledFieldViewCreator } from './labeledfieldview.js';
+* @module ui/labeledfield/utils
+*/
+import { InputTextView } from "../inputtext/inputtextview.js";
+import { InputNumberView } from "../inputnumber/inputnumberview.js";
+import { TextareaView } from "../textarea/textareaview.js";
+import { type DropdownView } from "../dropdown/dropdownview.js";
+import type { LabeledFieldViewCreator } from "./labeledfieldview.js";
 /**
- * A helper for creating labeled inputs.
- *
- * It creates an instance of a {@link module:ui/inputtext/inputtextview~InputTextView input text} that is
- * logically related to a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled view} in DOM.
- *
- * The helper does the following:
- *
- * * It sets input's `id` and `ariaDescribedById` attributes.
- * * It binds input's `isReadOnly` to the labeled view.
- * * It binds input's `hasError` to the labeled view.
- * * It enables a logic that cleans up the error when user starts typing in the input.
- *
- * Usage:
- *
- * ```ts
- * const labeledInputView = new LabeledFieldView( locale, createLabeledInputText );
- * console.log( labeledInputView.fieldView ); // A text input instance.
- * ```
- *
- * @param labeledFieldView The instance of the labeled field view.
- * @param viewUid A UID string that allows DOM logical connection between the
- * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#labelView labeled view's label} and the input.
- * @param statusUid A UID string that allows DOM logical connection between the
- * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the input.
- * @returns The input text view instance.
- */
+* A helper for creating labeled inputs.
+*
+* It creates an instance of a {@link module:ui/inputtext/inputtextview~InputTextView input text} that is
+* logically related to a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled view} in DOM.
+*
+* The helper does the following:
+*
+* * It sets input's `id` and `ariaDescribedById` attributes.
+* * It binds input's `isReadOnly` to the labeled view.
+* * It binds input's `hasError` to the labeled view.
+* * It enables a logic that cleans up the error when user starts typing in the input.
+*
+* Usage:
+*
+* ```ts
+* const labeledInputView = new LabeledFieldView( locale, createLabeledInputText );
+* console.log( labeledInputView.fieldView ); // A text input instance.
+* ```
+*
+* @param labeledFieldView The instance of the labeled field view.
+* @param viewUid A UID string that allows DOM logical connection between the
+* {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#labelView labeled view's label} and the input.
+* @param statusUid A UID string that allows DOM logical connection between the
+* {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the input.
+* @returns The input text view instance.
+*/
 declare const createLabeledInputText: LabeledFieldViewCreator<InputTextView>;
 /**
- * A helper for creating labeled number inputs.
- *
- * It creates an instance of a {@link module:ui/inputnumber/inputnumberview~InputNumberView input number} that is
- * logically related to a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled view} in DOM.
- *
- * The helper does the following:
- *
- * * It sets input's `id` and `ariaDescribedById` attributes.
- * * It binds input's `isReadOnly` to the labeled view.
- * * It binds input's `hasError` to the labeled view.
- * * It enables a logic that cleans up the error when user starts typing in the input.
- *
- * Usage:
- *
- * ```ts
- * const labeledInputView = new LabeledFieldView( locale, createLabeledInputNumber );
- * console.log( labeledInputView.fieldView ); // A number input instance.
- * ```
- *
- * @param labeledFieldView The instance of the labeled field view.
- * @param viewUid A UID string that allows DOM logical connection between the
- * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#labelView labeled view's label} and the input.
- * @param statusUid A UID string that allows DOM logical connection between the
- * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the input.
- * @returns The input number view instance.
- */
+* A helper for creating labeled number inputs.
+*
+* It creates an instance of a {@link module:ui/inputnumber/inputnumberview~InputNumberView input number} that is
+* logically related to a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled view} in DOM.
+*
+* The helper does the following:
+*
+* * It sets input's `id` and `ariaDescribedById` attributes.
+* * It binds input's `isReadOnly` to the labeled view.
+* * It binds input's `hasError` to the labeled view.
+* * It enables a logic that cleans up the error when user starts typing in the input.
+*
+* Usage:
+*
+* ```ts
+* const labeledInputView = new LabeledFieldView( locale, createLabeledInputNumber );
+* console.log( labeledInputView.fieldView ); // A number input instance.
+* ```
+*
+* @param labeledFieldView The instance of the labeled field view.
+* @param viewUid A UID string that allows DOM logical connection between the
+* {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#labelView labeled view's label} and the input.
+* @param statusUid A UID string that allows DOM logical connection between the
+* {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the input.
+* @returns The input number view instance.
+*/
 declare const createLabeledInputNumber: LabeledFieldViewCreator<InputNumberView>;
 /**
- * A helper for creating labeled textarea.
- *
- * It creates an instance of a {@link module:ui/textarea/textareaview~TextareaView textarea} that is
- * logically related to a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled view} in DOM.
- *
- * The helper does the following:
- *
- * * It sets textarea's `id` and `ariaDescribedById` attributes.
- * * It binds textarea's `isReadOnly` to the labeled view.
- * * It binds textarea's `hasError` to the labeled view.
- * * It enables a logic that cleans up the error when user starts typing in the textarea.
- *
- * Usage:
- *
- * ```ts
- * const labeledTextarea = new LabeledFieldView( locale, createLabeledTextarea );
- * console.log( labeledTextarea.fieldView ); // A textarea instance.
- * ```
- *
- * @param labeledFieldView The instance of the labeled field view.
- * @param viewUid A UID string that allows DOM logical connection between the
- * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#labelView labeled view's label} and the textarea.
- * @param statusUid A UID string that allows DOM logical connection between the
- * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the textarea.
- * @returns The textarea view instance.
- */
+* A helper for creating labeled textarea.
+*
+* It creates an instance of a {@link module:ui/textarea/textareaview~TextareaView textarea} that is
+* logically related to a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled view} in DOM.
+*
+* The helper does the following:
+*
+* * It sets textarea's `id` and `ariaDescribedById` attributes.
+* * It binds textarea's `isReadOnly` to the labeled view.
+* * It binds textarea's `hasError` to the labeled view.
+* * It enables a logic that cleans up the error when user starts typing in the textarea.
+*
+* Usage:
+*
+* ```ts
+* const labeledTextarea = new LabeledFieldView( locale, createLabeledTextarea );
+* console.log( labeledTextarea.fieldView ); // A textarea instance.
+* ```
+*
+* @param labeledFieldView The instance of the labeled field view.
+* @param viewUid A UID string that allows DOM logical connection between the
+* {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#labelView labeled view's label} and the textarea.
+* @param statusUid A UID string that allows DOM logical connection between the
+* {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view's status} and the textarea.
+* @returns The textarea view instance.
+*/
 declare const createLabeledTextarea: LabeledFieldViewCreator<TextareaView>;
 /**
- * A helper for creating labeled dropdowns.
- *
- * It creates an instance of a {@link module:ui/dropdown/dropdownview~DropdownView dropdown} that is
- * logically related to a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled field view}.
- *
- * The helper does the following:
- *
- * * It sets dropdown's `id` and `ariaDescribedById` attributes.
- * * It binds input's `isEnabled` to the labeled view.
- *
- * Usage:
- *
- * ```ts
- * const labeledInputView = new LabeledFieldView( locale, createLabeledDropdown );
- * console.log( labeledInputView.fieldView ); // A dropdown instance.
- * ```
- *
- * @param labeledFieldView The instance of the labeled field view.
- * @param viewUid A UID string that allows DOM logical connection between the
- * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#labelView labeled view label} and the dropdown.
- * @param statusUid A UID string that allows DOM logical connection between the
- * {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view status} and the dropdown.
- * @returns The dropdown view instance.
- */
+* A helper for creating labeled dropdowns.
+*
+* It creates an instance of a {@link module:ui/dropdown/dropdownview~DropdownView dropdown} that is
+* logically related to a {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView labeled field view}.
+*
+* The helper does the following:
+*
+* * It sets dropdown's `id` and `ariaDescribedById` attributes.
+* * It binds input's `isEnabled` to the labeled view.
+*
+* Usage:
+*
+* ```ts
+* const labeledInputView = new LabeledFieldView( locale, createLabeledDropdown );
+* console.log( labeledInputView.fieldView ); // A dropdown instance.
+* ```
+*
+* @param labeledFieldView The instance of the labeled field view.
+* @param viewUid A UID string that allows DOM logical connection between the
+* {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#labelView labeled view label} and the dropdown.
+* @param statusUid A UID string that allows DOM logical connection between the
+* {@link module:ui/labeledfield/labeledfieldview~LabeledFieldView#statusView labeled view status} and the dropdown.
+* @returns The dropdown view instance.
+*/
 declare const createLabeledDropdown: LabeledFieldViewCreator<DropdownView>;
 export { createLabeledInputNumber, createLabeledInputText, createLabeledTextarea, createLabeledDropdown };