@brandup/ui-input 1.0.48 → 1.0.50

package/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://dev.azure.com/brandup/BrandUp%20Core/_apis/build/status%2FBrandUp%2Fbrandup-ui-kit?branchName=main)](https://dev.azure.com/brandup/BrandUp%20Core/_build/latest?definitionId=81&branchName=main)
 
-Абстрактный базовый класс для компонентов ввода в форме. Обеспечивает единый интерфейс для `HTMLInputElement`, `HTMLTextAreaElement` и `HTMLSelectElement`.
+Общая база компонентов ввода в форме: абстрактные классы `InputControl` и `EditorInputControl`, а также LESS-миксин для поля-носителя значения. Пакет ничего не рендерит сам — им пользуются `@brandup/ui-textbox`, `@brandup/ui-messageeditor` и `@brandup/ui-dropdown`.
 
 ## Установка
 
@@ -10,38 +10,40 @@
 npm i @brandup/ui-input
 ```
 
+> **Версии.** `@brandup/ui-textbox`, `@brandup/ui-messageeditor` и `@brandup/ui-dropdown` подключают из этого пакета не только TypeScript, но и LESS (см. [LESS](#less)). Пакеты кита версионируются одной сборкой CI и рассчитаны друг на друга: обновляя любой из них, обновляйте и `@brandup/ui-input`. Иначе сборка стилей падает ещё до TypeScript — на `@import` отсутствующего `input.less` либо на неизвестном миксине `.ui-input-hidden-value`.
+
 ## InputControl
 
-`InputControl<T, TEvents>` — абстрактный класс, от которого наследуются все компоненты ввода (`TextBox`, `MessageEditor`, `DropDown`). Расширяет `UIElementBound` из `@brandup/ui`.
+`InputControl<T, TEvents>` — абстрактный класс, от которого наследуются все компоненты ввода. Расширяет `UIElementBound` из `@brandup/ui`. Параметр `T` — тип поля-носителя: `HTMLInputElement`, `HTMLTextAreaElement` или `HTMLSelectElement`.
 
 ### Свойства
 
 | Свойство | Тип | Описание |
 | --- | --- | --- |
-| `form` | `HTMLFormElement \| null` | Форма, к которой привязан элемент |
-| `disabled` | `boolean` | Элемент отключён |
-| `required` | `boolean` | Элемент обязателен для заполнения |
-| `readonly` | `boolean` | Элемент только для чтения (`readonly` или `data-readonly`) |
+| `form` | `HTMLFormElement \| null` | Форма, к которой привязано поле-носитель |
+| `disabled` | `boolean` | Поле отключено |
+| `required` | `boolean` | Поле обязательно для заполнения |
+| `readonly` | `boolean` | Поле только для чтения (`readonly` или `data-readonly`) |
 
 ### Методы
 
 | Метод | Описание |
 | --- | --- |
-| `validate(): boolean` | Проверяет значение через нативный `checkValidity()`. Возвращает `true`, если значение валидно |
-| `focus(): void` | Устанавливает фокус и прокручивает элемент в видимую область |
-| `destroy(): void` | Снимает все обработчики и освобождает ресурсы |
+| `validate(): boolean` | Синхронизирует значение и проверяет его нативным `checkValidity()` |
+| `focus(): void` | Ведёт фокус в контрол и прокручивает его в видимую область |
+| `destroy(): void` | Снимает обработчики, возвращает поле-носитель в исходное состояние и удаляет контейнер контрола |
 
 ### Поведение
 
-- Добавляет CSS-класс `ui-input` на корневой элемент.
-- При инициализации добавляет классы `required`, `readonly`, `disabled` в зависимости от состояния элемента.
-- Перехватывает событие `invalid` нативного поля и делегирует валидацию через `validate()`.
-- Перехватывает `submit` формы: если элемент невалиден — останавливает отправку и вызывает `focus()`.
+- Добавляет CSS-класс `ui-input` на корневой элемент, а также `required`, `readonly`, `disabled` — по состоянию поля.
+- Гасит показ нативной подсказки валидации (`invalid`): поле уведено с экрана, привязать подсказку не к чему. Само решение о валидности остаётся за браузером, а состояние видно по классу `invalid`.
+- Переносит значение в поле-носитель до отправки формы — и в фазе перехвата на документе, чтобы обработчик `submit`, повешенный приложением раньше контрола, тоже увидел актуальное значение.
+- `focus()` ничего не делает у выключенного контрола — как нативный `disabled` input, который игнорирует `focus()` сам. Поле только для чтения фокусируется: это его нативное поведение, текст читают, выделяют и копируют.
 
 ### Интерфейс IInputControl
 
 ```typescript
-import { IInputControl } from "@brandup/ui-input";
+import type { IInputControl } from "@brandup/ui-input";
 
 interface IInputControl {
     get form(): HTMLFormElement | null;
@@ -55,6 +57,29 @@ interface IInputControl {
 }
 ```
 
+### Защищённые члены для наследников
+
+| Член | Описание |
+| --- | --- |
+| `__valueElem` | Поле-носитель значения |
+| `__syncValue(): void` | Хук: довести значение до поля-носителя, если контрол держит его отдельно. Зовётся перед каждым чтением значения снаружи |
+| `__focusValue(): void` | Хук: куда именно ведёт фокус контрола. По умолчанию — поле-носитель; общие проверки и прокрутку делает `focus()` |
+| `__requestSubmit(): void` | Неявная отправка формы (Enter), как у обычного `input`: через `form.requestSubmit()` с первой кнопкой отправки |
+| `__submitForm(): void` | Досылает форме синтетический `submit` — движкам без `requestSubmit()` |
+| `static isReadonly(valueElem: HTMLElement): boolean` | Признано ли поле только для чтения: атрибут `readonly` либо `data-readonly` (последний нужен полям без нативного атрибута, например `select`). Статический, потому что режим нужен и до `super(...)` — он влияет на сборку разметки контрола |
+| `static prepareValueElem(valueElem, container, inputClass)` | Переносит собственные классы поля на контейнер, а класс-скрыватель — на поле |
+
+`ValueElemOverrides` описывает, что контрол навязал полю и что вернуть при `destroy`:
+
+```typescript
+export interface ValueElemOverrides {
+    /** Класс, добавленный полю контролом (обычно уводит его с экрана). */
+    class?: string;
+    /** Подменённые атрибуты: имя и исходное значение (`null` — атрибута не было). */
+    attrs?: [name: string, value: string | null][];
+}
+```
+
 ### Создание собственного компонента
 
 ```typescript
@@ -74,3 +99,100 @@ class MyInput extends InputControl<HTMLInputElement> {
     }
 }
 ```
+
+## EditorInputControl
+
+`EditorInputControl<TEditor, TChangeData, TEvents>` — база контролов, где ввод идёт не в само поле, а в редактор рядом: поле-носитель уводится с экрана, но остаётся в форме (отправка, валидация, `FormData`). На нём построены `TextBox` и `MessageEditor`.
+
+Класс берёт на себя общую механику: синхронизацию отложенного изменения редактора с полем, зеркало фокуса классом `focused` на корневом элементе, гашение нативного `change` скрытого поля, выравнивание редактора после `form.reset()` и снятие всего этого при `destroy()`. Доменное — фильтры ввода, подсветка, кнопки — остаётся в наследниках.
+
+### Публичные методы
+
+| Метод | Описание |
+| --- | --- |
+| `getValue(): string` | Значение поля-носителя; сначала доводит отложенное изменение редактора |
+| `setValue(value: string): void` | Передаёт значение редактору — тот нормализует его и поднимет своё изменение |
+| `hasValue(): boolean` | Есть ли непустое значение |
+| `onChange(handler): void` | Подписка на событие изменения контрола (имя события задаёт `EditorControlInit.changeEvent`) |
+
+### Защищённые члены
+
+| Член | Описание |
+| --- | --- |
+| `__editor` | Редактор контрола. Появляется только после `__attachEditor` |
+| `__listenerAbort` | `AbortController`, одним сигналом снимающий слушатели контрола и таймеры наследников |
+| `__attachEditor(editor): void` | Передать базовому классу созданный редактор — с этого момента им владеет база |
+| `__refreshValidity(): void` | Хук: освежить собственное ограничение контрола (`setCustomValidity`) на поле-носителе. Зовётся при каждой синхронизации значения |
+| `static wrapValueElem(valueElem, container, inputClass, editable, disabled)` | Скрыть поле-носитель, подменить `tabindex` (в фокус попадает редактируемый элемент) и обернуть поле контейнером |
+
+### ValueEditor
+
+Структурный контракт редактора — ровно то, что зовёт база. Не тип из `@brandup/ui-richeditor`: этот пакет — общая база всех контролов ввода, и потребители без редактора (например, dropdown) не должны тянуть его за собой. `RichEditor` подходит под контракт как есть, но подойдёт и любая другая реализация.
+
+```typescript
+export interface ValueEditor {
+    /** Редактируемый элемент — он принимает фокус вместо уведённого с экрана поля-носителя. */
+    readonly editable: HTMLElement;
+    /** Заменяет содержимое редактора; редактор нормализует значение и поднимает своё изменение. */
+    setValue(value: string): void;
+    /** Доставляет отложенное изменение немедленно — перед чтением значения извне. */
+    flushChange(): void;
+    /** Фокус в редактор; `atEnd` — ставить ли каретку в конец текста, если её ещё не было. */
+    focus(atEnd?: boolean): void;
+    destroy(): void;
+}
+```
+
+### EditorControlInit
+
+Что базовому классу нужно знать о конкретном контроле — передаётся последним аргументом `super(...)`.
+
+```typescript
+export interface EditorControlInit {
+    /** Имя события изменения контрола — на него подписывает onChange. */
+    changeEvent: string;
+    /** Ставить ли при focus() каретку в конец текста, если её ещё не было. */
+    focusAtEnd?: boolean;
+}
+```
+
+### Порядок конструирования
+
+Редактор создаёт наследник: его опции замыкаются на `this` и собираются только после `super(...)`. Сразу после создания редактор обязан уйти в `__attachEditor` — до этого момента базовый класс уже привязал элемент, повесил слушатели формы и включил авторазрушение по удалению из DOM, но редактора у него ещё нет. Методы базы этот промежуток терпят (падение конструктора наследника не оставляет на странице обработчиков, которые ломали бы отправку любой формы), но контрол без редактора не работает.
+
+```typescript
+import { EditorInputControl, type ValueEditor } from "@brandup/ui-input";
+
+const CHANGE_EVENT = "myeditor-change";
+
+class MyEditorControl extends EditorInputControl<MyEditor, ChangeData, MyEditorEvents> {
+    constructor(valueElem: HTMLInputElement) {
+        const editable = document.createElement("div");
+        const container = document.createElement("div");
+        container.appendChild(editable);
+
+        // скрыть поле, подменить tabindex и обернуть контейнером
+        MyEditorControl.wrapValueElem(valueElem, container, "myeditor-input", editable, valueElem.disabled);
+
+        super("My.EditorControl", container, valueElem, { class: "myeditor-input", attrs: [] }, {
+            changeEvent: CHANGE_EVENT,
+        });
+
+        this.__attachEditor(new MyEditor(editable, { value: valueElem.value }));
+    }
+}
+```
+
+## LESS
+
+`source/input.less` содержит рецепт поля-носителя, уведённого с экрана: поле остаётся в форме (отправка, валидация, `FormData`), но не показывается — вводом управляет UI контрола. Общего класса у поля нет: каждый контрол вешает свой (`textbox-input`, `messageeditor-input`, `ui-dropdown-input`), поэтому рецепт оформлен миксином.
+
+```less
+@import (reference) "@brandup/ui-input/source/input.less";
+
+.my-control-input {
+    .ui-input-hidden-value();
+}
+```
+
+Так его подключают `@brandup/ui-textbox`, `@brandup/ui-messageeditor` и `@brandup/ui-dropdown` — см. предупреждение о версиях в начале файла.

package/package.json

@@ -24,12 +24,12 @@
     "email": "it@brandup.online"
   },
   "license": "Apache-2.0",
-  "version": "1.0.48",
+  "version": "1.0.50",
   "main": "source/index.ts",
   "types": "source/index.ts",
   "dependencies": {
     "@brandup/ui": "^2.0.9",
-    "@brandup/ui-kit": "^1.0.48"
+    "@brandup/ui-kit": "^1.0.50"
   },
   "files": [
     "source",

package/source/editor-control.ts

@@ -0,0 +1,186 @@
+import { InputControl, type ValueElemOverrides } from "./input";
+
+/** Поле формы, которое контрол на редакторе оставляет носителем значения. */
+type EditorValueElem = HTMLInputElement | HTMLTextAreaElement;
+
+/**
+ * Редактор, которому контрол доверяет ввод значения. Структурный интерфейс, а не тип из
+ * `@brandup/ui-richeditor`: этот пакет — общая база всех контролов ввода, и потребители без
+ * редактора (например, dropdown) не должны тянуть его за собой. `RichEditor` подходит под
+ * интерфейс как есть; членов здесь ровно столько, сколько зовёт общая механика базового класса.
+ */
+export interface ValueEditor {
+	/** Редактируемый элемент — он принимает фокус вместо уведённого с экрана поля-носителя. */
+	readonly editable: HTMLElement;
+	/** Заменяет содержимое редактора; редактор нормализует значение и поднимает своё изменение. */
+	setValue(value: string): void;
+	/** Доставляет отложенное изменение немедленно — перед чтением значения извне. */
+	flushChange(): void;
+	/** Фокус в редактор; `atEnd` — ставить ли каретку в конец текста, если её ещё не было. */
+	focus(atEnd?: boolean): void;
+	destroy(): void;
+}
+
+/** Что базовому классу нужно знать о конкретном контроле. */
+export interface EditorControlInit {
+	/** Имя события изменения контрола — на него подписывает {@link EditorInputControl.onChange}. */
+	changeEvent: string;
+	/** Ставить ли при {@link EditorInputControl.focus} каретку в конец текста, если её ещё не было. */
+	focusAtEnd?: boolean;
+}
+
+/**
+ * Контрол ввода, где значением управляет редактор в соседнем редактируемом элементе, а исходное
+ * поле остаётся носителем значения и участвует в форме. Общая механика таких контролов
+ * (textbox, messageeditor): синхронизация отложенного изменения редактора с полем, зеркало
+ * фокуса, гашение нативного change скрытого поля, обёртка поля контейнером и снятие всего
+ * этого при destroy. Всё доменное — фильтры ввода, подсветка, кнопки — остаётся в наследниках.
+ *
+ * Редактор создаёт наследник: опции редактора замыкаются на `this` и собираются только после
+ * `super(...)`. Сразу после создания наследник обязан передать редактор в {@link __attachEditor}.
+ */
+export abstract class EditorInputControl<TEditor extends ValueEditor, TChangeData, TEvents = {}> extends InputControl<
+	EditorValueElem,
+	TEvents
+> {
+	/**
+	 * Редактор контрола; назначается в {@link __attachEditor} сразу после `super(...)`.
+	 *
+	 * До этого момента его нет, и промежуток не пустой: базовый конструктор уже привязал
+	 * элемент, повесил слушатели формы и включил авторазрушение по удалению из DOM. Если
+	 * конструктор наследника упадёт после `super(...)`, эти слушатели останутся жить на
+	 * недостроенном контроле — поэтому каждый метод базы, трогающий редактор, обязан
+	 * терпеть его отсутствие. Наружу тип объявлен непустым: наследники работают с редактором
+	 * уже после привязки, и разбирать `undefined` в каждом их обращении было бы шумом.
+	 */
+	protected __editor!: TEditor;
+	/** Слушатели контрола снимаются одним сигналом — он же гасит и таймеры наследников. */
+	protected __listenerAbort = new AbortController();
+	private __init: EditorControlInit;
+
+	constructor(
+		typeName: string,
+		elem: HTMLElement,
+		valueElem: EditorValueElem,
+		overrides: ValueElemOverrides | undefined,
+		init: EditorControlInit
+	) {
+		super(typeName, elem, valueElem, overrides);
+
+		this.__init = init;
+
+		// гасим нативный change скрытого поля
+		this.__valueElem.addEventListener(
+			"change",
+			(e: Event) => {
+				e.preventDefault();
+				e.stopImmediatePropagation();
+			},
+			{ signal: this.__listenerAbort.signal }
+		);
+	}
+
+	/**
+	 * Скрывает поле-носитель и оборачивает его контейнером контрола: {@link prepareValueElem}
+	 * плюс подмена tabindex — в фокус попадает редактируемый элемент, а не уведённое с экрана
+	 * поле. Статический, потому что вызывается до `super(...)`; подменённый tabindex наследник
+	 * возвращает через {@link ValueElemOverrides}.
+	 */
+	protected static wrapValueElem(
+		valueElem: EditorValueElem,
+		container: HTMLElement,
+		inputClass: string,
+		editable: HTMLElement,
+		disabled: boolean
+	) {
+		InputControl.prepareValueElem(valueElem, container, inputClass);
+
+		editable.tabIndex = disabled ? -1 : valueElem.tabIndex;
+		valueElem.tabIndex = -1;
+
+		valueElem.insertAdjacentElement("afterend", container);
+		container.insertAdjacentElement("afterbegin", valueElem);
+	}
+
+	/**
+	 * Принимает созданный наследником редактор: с этого момента им владеет базовый класс —
+	 * он его синхронизирует, фокусирует и разрушает. Заодно зеркалит фокус редактируемого
+	 * элемента классом на корневом элементе контрола — состояние поля показывает весь контрол.
+	 */
+	protected __attachEditor(editor: TEditor): void {
+		this.__editor = editor;
+
+		const { signal } = this.__listenerAbort;
+		const editable = editor.editable;
+
+		// состояние фокуса контрола — на корневом элементе
+		editable.addEventListener("focus", () => !this.disabled && this.element.classList.add("focused"), { signal });
+		editable.addEventListener("blur", () => !this.disabled && this.element.classList.remove("focused"), { signal });
+
+		// form.reset() возвращает поле-носитель к defaultValue, а редактор об этом сам не узнал бы —
+		// следующая синхронизация перезаписала бы сброс обратно. Сброс применяется после события,
+		// поэтому выравниваем редактор отложенно и только если сброс не отменили; разрушенный
+		// к этому моменту контрол трогать нечего — его выдаёт снятый сигнал.
+		this.form?.addEventListener(
+			"reset",
+			(e) => {
+				window.setTimeout(() => {
+					if (!signal.aborted && !e.defaultPrevented) this.__editor?.setValue(this.__valueElem.defaultValue);
+				});
+			},
+			{ signal }
+		);
+	}
+
+	// Редактор откладывает событие изменения при печати, поэтому копия значения в поле формы
+	// отстаёт. Базовый класс зовёт этот хук перед каждым чтением значения снаружи —
+	// валидация, отправка формы, сбор FormData.
+	protected override __syncValue(): void {
+		if (!this.__editor) return; // редактора ещё (или уже) нет — синхронизировать нечего
+
+		this.__editor.flushChange();
+		this.__refreshValidity();
+	}
+
+	/**
+	 * Освежает собственное ограничение контрола на поле-носителе (setCustomValidity) — зовётся
+	 * при каждой синхронизации значения. По умолчанию собственных ограничений нет.
+	 */
+	protected __refreshValidity(): void {}
+
+	onChange(handler: (e: TChangeData) => void) {
+		// имя события у каждого контрола своё — типизацию даёт TEvents наследника
+		this.on(this.__init.changeEvent as keyof TEvents & string, handler as never);
+	}
+
+	hasValue(): boolean {
+		return !!this.getValue();
+	}
+
+	getValue(): string {
+		this.__syncValue(); // значение читают снаружи — отложенное изменение сюда обязано попасть
+		return this.__valueElem.value.trim();
+	}
+
+	setValue(value: string): void {
+		// редактор нормализует значение и поднимет своё изменение — оно и синхронизирует
+		// поле-носитель, и вызовет событие изменения контрола
+		this.__editor?.setValue(value?.trim() ?? "");
+	}
+
+	/**
+	 * Поле-носитель уведено с экрана (visibility: collapse) и в браузере фокус не принимает —
+	 * ведём фокус в редактор. Проверки состояния и прокрутку к контролу делает базовый
+	 * {@link InputControl.focus}.
+	 */
+	protected override __focusValue(): void {
+		this.__editor?.focus(this.__init.focusAtEnd);
+	}
+
+	override destroy(): void {
+		this.__listenerAbort.abort();
+		this.__editor?.destroy();
+
+		super.destroy(); // снимет слушатели формы и вернёт поле-носитель в исходный вид
+	}
+}

package/source/index.ts

@@ -1 +1,2 @@
 export * from "./input";
+export * from "./editor-control";

package/source/input.less

@@ -1 +1,15 @@
-// Тут могут быть общие стили для класса ui-input.
+// Общие стили контролов ввода (ui-input).
+
+// Поле-носитель значения, уведённое с экрана: остаётся в форме (отправка, валидация, FormData),
+// но не показывается — вводом управляет UI контрола. Общего класса у поля нет: каждый контрол
+// вешает свой (textbox-input, messageeditor-input, ui-dropdown-input), поэтому рецепт оформлен
+// миксином — потребители подключают этот файл через `@import (reference)` и вызывают миксин
+// в своём правиле.
+.ui-input-hidden-value() {
+	opacity: 0;
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	outline: none;
+	visibility: collapse;
+}

package/source/input.ts

@@ -32,6 +32,17 @@ export abstract class InputControl<T extends InputType, TEvents = {}>
 		this.__initForm();
 	}
 
+	/**
+	 * Признан ли элемент полем только для чтения: нативный атрибут `readonly` либо `data-readonly` —
+	 * последний нужен полям, у которых нативного атрибута нет (например, `select`).
+	 *
+	 * Статический, потому что контролам это нужно и до `super(...)` — режим влияет на сборку
+	 * их разметки; после конструирования то же самое отдаёт getter {@link readonly}.
+	 */
+	protected static isReadonly(valueElem: HTMLElement): boolean {
+		return valueElem.hasAttribute("readonly") || valueElem.hasAttribute("data-readonly");
+	}
+
 	/**
 	 * Готовит поле-носитель к обёртке контейнером контрола: класс-скрыватель переезжает на поле,
 	 * а собственные классы поля — на контейнер, чтобы оформление из разметки применялось к тому,
@@ -56,7 +67,7 @@ export abstract class InputControl<T extends InputType, TEvents = {}>
 		return this.__valueElem.required;
 	}
 	get readonly(): boolean {
-		return this.__valueElem.hasAttribute("readonly") || this.__valueElem.hasAttribute("data-readonly");
+		return InputControl.isReadonly(this.__valueElem);
 	}
 
 	/**
@@ -162,11 +173,31 @@ export abstract class InputControl<T extends InputType, TEvents = {}>
 		return result;
 	}
 
+	/**
+	 * Фокус в контрол. Выключенное поле фокус не принимает — как нативный `disabled` input:
+	 * раньше это выходило само собой (браузер игнорирует `focus()` на выключенном поле),
+	 * но контрол на редакторе уводит фокус в свой элемент, а тот выключение не запрещает,
+	 * — поэтому запрет объявлен здесь, рядом с таким же в {@link __requestSubmit}.
+	 *
+	 * Поле только для чтения фокусируется: это его нативное поведение — текст читают,
+	 * выделяют и копируют, и уводить от него клавиатуру нельзя.
+	 */
 	focus(): void {
-		this.__valueElem.focus();
+		if (this.disabled) return;
+
+		this.__focusValue();
 		this.element.scrollIntoView({ block: "center", inline: "center" });
 	}
 
+	/**
+	 * Куда именно ведёт фокус контрола. По умолчанию — поле-носитель; контролы, у которых
+	 * ввод идёт в другом элементе, подменяют его здесь, а общие проверки и прокрутку
+	 * оставляют базовому {@link focus}.
+	 */
+	protected __focusValue(): void {
+		this.__valueElem.focus();
+	}
+
 	/**
 	 * Возвращает поле-носитель в исходное состояние: снимает класс, которым контрол увёл его
 	 * с экрана, возвращает подменённые атрибуты и вынимает поле из контейнера, а сам контейнер