@ckeditor/ckeditor5-ui 0.0.0-internal-20241017.0

package/src/input/inputbase.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @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/input/inputbase
+ */
+import View from '../view.js';
+import { FocusTracker, type Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The base input view class.
+ */
+export default abstract class InputBase<TElement extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement> extends View<TElement> {
+    /**
+     * Stores information about the editor UI focus and propagates it so various plugins and components
+     * are unified as a focus group.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * The value of the input.
+     *
+     * @observable
+     */
+    value: string | undefined;
+    /**
+     * The `id` attribute of the input (i.e. to pair with a `<label>` element).
+     *
+     * @observable
+     */
+    id: string | undefined;
+    /**
+     * The `placeholder` attribute of the input.
+     *
+     * @observable
+     */
+    placeholder: string | undefined;
+    /**
+     * The `tabindex` attribute of the input.
+     *
+     * @observable
+     */
+    tabIndex: number | undefined;
+    /**
+     * The `aria-label` attribute of the input.
+     *
+     * @observable
+     */
+    ariaLabel: string | undefined;
+    /**
+     * Controls whether the input view is in read-only mode.
+     *
+     * @observable
+     */
+    isReadOnly: boolean;
+    /**
+     * Set to `true` when the field has some error. Usually controlled via
+     * {@link module:ui/labeledinput/labeledinputview~LabeledInputView#errorText}.
+     *
+     * @observable
+     */
+    hasError: boolean;
+    /**
+     * The `id` of the element describing this field, e.g. when it has
+     * some error; it helps screen readers read the error text.
+     *
+     * @observable
+     */
+    ariaDescribedById: string | undefined;
+    /**
+     * An observable flag set to `true` when the input is currently focused by the user.
+     * Set to `false` otherwise.
+     *
+     * @readonly
+     * @observable
+     * @default false
+     */
+    isFocused: boolean;
+    /**
+     * An observable flag set to `true` when the input contains no text, i.e.
+     * when {@link #value} is `''`, `null`, or `false`.
+     *
+     * @readonly
+     * @observable
+     * @default true
+     */
+    isEmpty: boolean;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Moves the focus to the input and selects the value.
+     */
+    select(): void;
+    /**
+     * Focuses the input.
+     */
+    focus(): void;
+    /**
+     * Resets the value of the input
+     */
+    reset(): void;
+    /**
+     * Updates the {@link #isEmpty} property value on demand.
+     */
+    protected _updateIsEmpty(): void;
+    /**
+     * Sets the `value` property of the {@link #element DOM element} on demand.
+     */
+    private _setDomElementValue;
+}

package/src/input/inputbase.js

@@ -0,0 +1,114 @@
+/**
+ * @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/input/inputbase
+ */
+import View from '../view.js';
+import { FocusTracker } from '@ckeditor/ckeditor5-utils';
+/**
+ * The base input view class.
+ */
+export default class InputBase extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        this.set('value', undefined);
+        this.set('id', undefined);
+        this.set('placeholder', undefined);
+        this.set('tabIndex', undefined);
+        this.set('isReadOnly', false);
+        this.set('hasError', false);
+        this.set('ariaDescribedById', undefined);
+        this.set('ariaLabel', undefined);
+        this.focusTracker = new FocusTracker();
+        this.bind('isFocused').to(this.focusTracker);
+        this.set('isEmpty', true);
+        const bind = this.bindTemplate;
+        this.setTemplate({
+            tag: 'input',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-input',
+                    bind.if('isFocused', 'ck-input_focused'),
+                    bind.if('isEmpty', 'ck-input-text_empty'),
+                    bind.if('hasError', 'ck-error')
+                ],
+                id: bind.to('id'),
+                placeholder: bind.to('placeholder'),
+                tabindex: bind.to('tabIndex'),
+                readonly: bind.to('isReadOnly'),
+                'aria-invalid': bind.if('hasError', true),
+                'aria-describedby': bind.to('ariaDescribedById'),
+                'aria-label': bind.to('ariaLabel')
+            },
+            on: {
+                input: bind.to((...args) => {
+                    this.fire('input', ...args);
+                    this._updateIsEmpty();
+                }),
+                change: bind.to(this._updateIsEmpty.bind(this))
+            }
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.focusTracker.add(this.element);
+        this._setDomElementValue(this.value);
+        this._updateIsEmpty();
+        // Bind `this.value` to the DOM element's value.
+        // We cannot use `value` DOM attribute because removing it on Edge does not clear the DOM element's value property.
+        this.on('change:value', (evt, name, value) => {
+            this._setDomElementValue(value);
+            this._updateIsEmpty();
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+    }
+    /**
+     * Moves the focus to the input and selects the value.
+     */
+    select() {
+        this.element.select();
+    }
+    /**
+     * Focuses the input.
+     */
+    focus() {
+        this.element.focus();
+    }
+    /**
+     * Resets the value of the input
+     */
+    reset() {
+        this.value = this.element.value = '';
+        this._updateIsEmpty();
+    }
+    /**
+     * Updates the {@link #isEmpty} property value on demand.
+     */
+    _updateIsEmpty() {
+        this.isEmpty = isInputElementEmpty(this.element);
+    }
+    /**
+     * Sets the `value` property of the {@link #element DOM element} on demand.
+     */
+    _setDomElementValue(value) {
+        this.element.value = (!value && value !== 0) ? '' : value;
+    }
+}
+function isInputElementEmpty(domElement) {
+    return !domElement.value;
+}

package/src/input/inputview.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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/input/inputview
+ */
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import InputBase from './inputbase.js';
+import '../../theme/components/input/input.css';
+/**
+ * The input view class.
+ */
+export default class InputView extends InputBase {
+    /**
+     * Corresponds to the `inputmode` DOM attribute. Can be `text`, `numeric`, `decimal`, etc.
+     *
+     * @observable
+     * @default 'text'
+     */
+    inputMode: string;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}
+/**
+ * Fired when the user types in the input. Corresponds to the native
+ * DOM `input` event.
+ *
+ * @eventName ~InputView#input
+ */
+export type InputViewInputEvent = {
+    name: 'input';
+    args: [InputEvent];
+};

package/src/input/inputview.js

@@ -0,0 +1,24 @@
+/**
+ * @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
+ */
+import InputBase from './inputbase.js';
+import '../../theme/components/input/input.css';
+/**
+ * The input view class.
+ */
+export default class InputView extends InputBase {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        this.set('inputMode', 'text');
+        const bind = this.bindTemplate;
+        this.extendTemplate({
+            attributes: {
+                inputmode: bind.to('inputMode')
+            }
+        });
+    }
+}

package/src/inputnumber/inputnumberview.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @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/inputnumber/inputnumberview
+ */
+import InputView from '../input/inputview.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The number input view class.
+ */
+export default class InputNumberView extends InputView {
+    /**
+     * The value of the `min` DOM attribute (the lowest accepted value) set on the {@link #element}.
+     *
+     * @observable
+     * @default undefined
+     */
+    min: number | undefined;
+    /**
+     * The value of the `max` DOM attribute (the highest accepted value) set on the {@link #element}.
+     *
+     * @observable
+     * @default undefined
+     */
+    max: number | undefined;
+    /**
+     * The value of the `step` DOM attribute set on the {@link #element}.
+     *
+     * @observable
+     * @default undefined
+     */
+    step: number | undefined;
+    /**
+     * Creates an instance of the input number view.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param options The options of the input.
+     * @param options.min The value of the `min` DOM attribute (the lowest accepted value).
+     * @param options.max The value of the `max` DOM attribute (the highest accepted value).
+     * @param options.step The value of the `step` DOM attribute.
+     */
+    constructor(locale?: Locale, { min, max, step }?: {
+        min?: number;
+        max?: number;
+        step?: number;
+    });
+}

package/src/inputnumber/inputnumberview.js

@@ -0,0 +1,40 @@
+/**
+ * @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/inputnumber/inputnumberview
+ */
+import InputView from '../input/inputview.js';
+/**
+ * The number input view class.
+ */
+export default class InputNumberView extends InputView {
+    /**
+     * Creates an instance of the input number view.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param options The options of the input.
+     * @param options.min The value of the `min` DOM attribute (the lowest accepted value).
+     * @param options.max The value of the `max` DOM attribute (the highest accepted value).
+     * @param options.step The value of the `step` DOM attribute.
+     */
+    constructor(locale, { min, max, step } = {}) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set('min', min);
+        this.set('max', max);
+        this.set('step', step);
+        this.extendTemplate({
+            attributes: {
+                type: 'number',
+                class: [
+                    'ck-input-number'
+                ],
+                min: bind.to('min'),
+                max: bind.to('max'),
+                step: bind.to('step')
+            }
+        });
+    }
+}

package/src/inputtext/inputtextview.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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/inputtext/inputtextview
+ */
+import InputView from '../input/inputview.js';
+import type { Locale } from '@ckeditor/ckeditor5-utils';
+/**
+ * The text input view class.
+ */
+export default class InputTextView extends InputView {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}

package/src/inputtext/inputtextview.js

@@ -0,0 +1,27 @@
+/**
+ * @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/inputtext/inputtextview
+ */
+import InputView from '../input/inputview.js';
+/**
+ * The text input view class.
+ */
+export default class InputTextView extends InputView {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        this.extendTemplate({
+            attributes: {
+                type: 'text',
+                class: [
+                    'ck-input-text'
+                ]
+            }
+        });
+    }
+}

package/src/label/labelview.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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/label/labelview
+ */
+import View from '../view.js';
+import { type Locale } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/label/label.css';
+/**
+ * The label view class.
+ */
+export default class LabelView extends View {
+    /**
+     * An unique id of the label. It can be used by other UI components to reference
+     * the label, for instance, using the `aria-describedby` DOM attribute.
+     */
+    readonly id: string;
+    /**
+     * The text of the label.
+     *
+     * @observable
+     */
+    text: string | undefined;
+    /**
+     * The `for` attribute of the label (i.e. to pair with an `<input>` element).
+     *
+     * @observable
+     */
+    for: string | undefined;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale?: Locale);
+}

package/src/label/labelview.js

@@ -0,0 +1,41 @@
+/**
+ * @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/label/labelview
+ */
+import View from '../view.js';
+import { uid } from '@ckeditor/ckeditor5-utils';
+import '../../theme/components/label/label.css';
+/**
+ * The label view class.
+ */
+export default class LabelView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale) {
+        super(locale);
+        this.set('text', undefined);
+        this.set('for', undefined);
+        this.id = `ck-editor__label_${uid()}`;
+        const bind = this.bindTemplate;
+        this.setTemplate({
+            tag: 'label',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-label'
+                ],
+                id: this.id,
+                for: bind.to('for')
+            },
+            children: [
+                {
+                    text: bind.to('text')
+                }
+            ]
+        });
+    }
+}

package/src/labeledfield/labeledfieldview.d.ts

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