@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/labeledfield/labeledfieldview.js

@@ -0,0 +1,157 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/labeledfield/labeledfieldview
+ */
+import View from '../view.js';
+import LabelView from '../label/labelview.js';
+import { uid } 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 default class LabeledFieldView extends View {
+    /**
+     * 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, viewCreator) {
+        super(locale);
+        const viewUid = `ck-labeled-field-view-${uid()}`;
+        const statusUid = `ck-labeled-field-view-status-${uid()}`;
+        this.fieldView = viewCreator(this, viewUid, statusUid);
+        this.set('label', undefined);
+        this.set('isEnabled', true);
+        this.set('isEmpty', true);
+        this.set('isFocused', false);
+        this.set('errorText', null);
+        this.set('infoText', null);
+        this.set('class', undefined);
+        this.set('placeholder', undefined);
+        this.labelView = this._createLabelView(viewUid);
+        this.statusView = this._createStatusView(statusUid);
+        this.fieldWrapperChildren = this.createCollection([this.fieldView, this.labelView]);
+        this.bind('_statusText').to(this, 'errorText', this, 'infoText', (errorText, infoText) => errorText || infoText);
+        const bind = this.bindTemplate;
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-labeled-field-view',
+                    bind.to('class'),
+                    bind.if('isEnabled', 'ck-disabled', value => !value),
+                    bind.if('isEmpty', 'ck-labeled-field-view_empty'),
+                    bind.if('isFocused', 'ck-labeled-field-view_focused'),
+                    bind.if('placeholder', 'ck-labeled-field-view_placeholder'),
+                    bind.if('errorText', 'ck-error')
+                ]
+            },
+            children: [
+                {
+                    tag: 'div',
+                    attributes: {
+                        class: [
+                            'ck',
+                            'ck-labeled-field-view__input-wrapper'
+                        ]
+                    },
+                    children: this.fieldWrapperChildren
+                },
+                this.statusView
+            ]
+        });
+    }
+    /**
+     * Creates label view class instance and bind with view.
+     *
+     * @param id Unique id to set as labelView#for attribute.
+     */
+    _createLabelView(id) {
+        const labelView = new LabelView(this.locale);
+        labelView.for = id;
+        labelView.bind('text').to(this, 'label');
+        return labelView;
+    }
+    /**
+     * 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.
+     */
+    _createStatusView(statusUid) {
+        const statusView = new View(this.locale);
+        const bind = this.bindTemplate;
+        statusView.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-labeled-field-view__status',
+                    bind.if('errorText', 'ck-labeled-field-view__status_error'),
+                    bind.if('_statusText', 'ck-hidden', value => !value)
+                ],
+                id: statusUid,
+                role: bind.if('errorText', 'alert')
+            },
+            children: [
+                {
+                    text: bind.to('_statusText')
+                }
+            ]
+        });
+        return statusView;
+    }
+    /**
+     * Focuses the {@link #fieldView}.
+     */
+    focus(direction) {
+        this.fieldView.focus(direction);
+    }
+}

package/src/labeledfield/utils.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+declare const createLabeledDropdown: LabeledFieldViewCreator<DropdownView>;
+export { createLabeledInputNumber, createLabeledInputText, createLabeledTextarea, createLabeledDropdown };

package/src/labeledfield/utils.js

@@ -0,0 +1,176 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/labeledfield/utils
+ */
+import InputTextView from '../inputtext/inputtextview.js';
+import InputNumberView from '../inputnumber/inputnumberview.js';
+import TextareaView from '../textarea/textareaview.js';
+import { createDropdown } from '../dropdown/utils.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.
+ */
+const createLabeledInputText = (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);
+    inputView.on('input', () => {
+        // UX: Make the error text disappear and disable the error indicator as the user
+        // starts fixing the errors.
+        labeledFieldView.errorText = null;
+    });
+    labeledFieldView.bind('isEmpty', 'isFocused', 'placeholder').to(inputView);
+    return inputView;
+};
+/**
+ * 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.
+ */
+const createLabeledInputNumber = (labeledFieldView, viewUid, statusUid) => {
+    const inputView = new InputNumberView(labeledFieldView.locale);
+    inputView.set({
+        id: viewUid,
+        ariaDescribedById: statusUid,
+        inputMode: 'numeric'
+    });
+    inputView.bind('isReadOnly').to(labeledFieldView, 'isEnabled', value => !value);
+    inputView.bind('hasError').to(labeledFieldView, 'errorText', value => !!value);
+    inputView.on('input', () => {
+        // UX: Make the error text disappear and disable the error indicator as the user
+        // starts fixing the errors.
+        labeledFieldView.errorText = null;
+    });
+    labeledFieldView.bind('isEmpty', 'isFocused', 'placeholder').to(inputView);
+    return inputView;
+};
+/**
+ * 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.
+ */
+const createLabeledTextarea = (labeledFieldView, viewUid, statusUid) => {
+    const textareaView = new TextareaView(labeledFieldView.locale);
+    textareaView.set({
+        id: viewUid,
+        ariaDescribedById: statusUid
+    });
+    textareaView.bind('isReadOnly').to(labeledFieldView, 'isEnabled', value => !value);
+    textareaView.bind('hasError').to(labeledFieldView, 'errorText', value => !!value);
+    textareaView.on('input', () => {
+        // UX: Make the error text disappear and disable the error indicator as the user
+        // starts fixing the errors.
+        labeledFieldView.errorText = null;
+    });
+    labeledFieldView.bind('isEmpty', 'isFocused', 'placeholder').to(textareaView);
+    return 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.
+ */
+const createLabeledDropdown = (labeledFieldView, viewUid, statusUid) => {
+    const dropdownView = createDropdown(labeledFieldView.locale);
+    dropdownView.set({
+        id: viewUid,
+        ariaDescribedById: statusUid
+    });
+    dropdownView.bind('isEnabled').to(labeledFieldView);
+    return dropdownView;
+};
+export { createLabeledInputNumber, createLabeledInputText, createLabeledTextarea, createLabeledDropdown };

package/src/labeledinput/labeledinputview.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module ui/labeledinput/labeledinputview
+ */
+import View from '../view.js';
+import LabelView from '../label/labelview.js';
+import type { default as InputView } from '../input/inputview.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/labeledinput/labeledinput.css';
+/**
+ * The labeled input view class.
+ */
+export default class LabeledInputView extends View {
+    /**
+     * The label view.
+     */
+    readonly labelView: LabelView;
+    /**
+     * The input view.
+     */
+    readonly inputView: InputView;
+    /**
+     * The status view for the {@link #inputView}. It displays {@link #errorText} and
+     * {@link #infoText}.
+     */
+    readonly statusView: View;
+    /**
+     * The text of the label.
+     *
+     * @observable
+     */
+    label: string | undefined;
+    /**
+     * The value of the input.
+     *
+     * @observable
+     */
+    value: string | undefined;
+    /**
+     * Controls whether the component is in read-only mode.
+     *
+     * @observable
+     */
+    isReadOnly: boolean;
+    /**
+     * The validation error text. When set, it will be displayed
+     * next to the {@link #inputView} 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 {@link module:ui/inputtext/inputtextview~InputTextView#hasError `hasError`}
+     * of the {@link #inputView} `true`.
+     *
+     * **Note:** Typing in the {@link #inputView} which fires the
+     * {@link module:ui/inputtext/inputtextview~InputTextView#event:input `input` event}
+     * resets this property back to `null`, indicating that the input field can be re–validated.
+     *
+     * @observable
+     */
+    errorText: string | null;
+    /**
+     * The additional information text displayed next to the {@link #inputView} which can
+     * be used to inform the user about the purpose of the input, 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 #errorText} for as long as the value of the input is invalid.
+     *
+     * @observable
+     */
+    infoText: string | null;
+    /**
+     * 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 input view class.
+     *
+     * @param locale The locale instance.
+     * @param InputView Constructor of the input view.
+     */
+    constructor(locale: Locale | undefined, InputView: new (locale: Locale | undefined, statusUid: string) => InputView);
+    /**
+     * Creates label view class instance and bind with view.
+     *
+     * @param id Unique id to set as labelView#for attribute.
+     */
+    private _createLabelView;
+    /**
+     * Creates input view class instance and bind with view.
+     *
+     * @param InputView Input view constructor.
+     * @param inputUid Unique id to set as inputView#id attribute.
+     * @param statusUid Unique id of the status for the input's `aria-describedby` attribute.
+     */
+    private _createInputView;
+    /**
+     * Creates the status view instance. It displays {@link #errorText} and {@link #infoText}
+     * next to the {@link #inputView}. See {@link #_statusText}.
+     *
+     * @param statusUid Unique id of the status, shared with the input's `aria-describedby` attribute.
+     */
+    private _createStatusView;
+    /**
+     * Moves the focus to the input and selects the value.
+     */
+    select(): void;
+    /**
+     * Focuses the input.
+     */
+    focus(): void;
+}