@brandup/ui-input 1.0.53 → 1.0.55

package/README.md

@@ -24,13 +24,14 @@ npm i @brandup/ui-input
 | `disabled` | `boolean` | Поле отключено |
 | `required` | `boolean` | Поле обязательно для заполнения |
 | `readonly` | `boolean` | Поле только для чтения (`readonly` или `data-readonly`) |
+| `autoFocus` | `boolean` | Объявлен ли автофокус (`autofocus` или `data-autofocus`) |
 
 ### Методы
 
 | Метод | Описание |
 | --- | --- |
 | `validate(): boolean` | Синхронизирует значение и проверяет его нативным `checkValidity()` |
-| `focus(): void` | Ведёт фокус в контрол и прокручивает его в видимую область |
+| `focus(scroll?): void` | Ведёт фокус в контрол и прокручивает его в видимую область. `scroll` — `ScrollLogicalPosition` для `scrollIntoView`: по умолчанию `"center"` (фокус из кода обычно ведут к тому, что нужно показать), автофокус просит `"nearest"` |
 | `destroy(): void` | Снимает обработчики, возвращает поле-носитель в исходное состояние и удаляет контейнер контрола |
 
 ### Поведение
@@ -40,6 +41,21 @@ npm i @brandup/ui-input
 - Переносит значение в поле-носитель до отправки формы — и в фазе перехвата на документе, чтобы обработчик `submit`, повешенный приложением раньше контрола, тоже увидел актуальное значение.
 - `focus()` ничего не делает у выключенного контрола — как нативный `disabled` input, который игнорирует `focus()` сам. Поле только для чтения фокусируется: это его нативное поведение, текст читают, выделяют и копируют.
 
+### Автофокус
+
+Поле объявляет его нативным `autofocus` либо `data-autofocus`. Браузер разбирает нативный атрибут при разборе разметки, когда контрола ещё нет: поле, скрытое классом уже в разметке, он пропустит, а видимое — сфокусирует, но перенос поля в контейнер контрола этот фокус тут же собьёт (браузер снимает фокус с перемещаемого узла). Так что фокус в любом случае ставит контрол, а атрибут остаётся объявлением намерения. Наследник зовёт `__applyAutoFocus()` в конце своего конструктора — раньше нельзя, ввод контрола ещё не собран.
+
+Фокус ставится через тот же `focus("nearest")`: вид двигается на минимум — страницу ещё не читали, и сдвигать её ради поля, которое и так на виду, не за чем. Автофокус — пожелание разметки, а не команда, поэтому молча отменяется, если:
+
+- поле выключено или только для чтения;
+- вводят пальцем (`(pointer: coarse)`) — экранная клавиатура закрыла бы страницу, которую ещё не читали;
+- пользователь уже прокрутил страницу сам — вид принадлежит ему;
+- фокус держит поле ввода или другой контрол ввода — там уже работают, и двух автофокусов на странице не бывает. Кнопка или ссылка, которой пришли на страницу, автофокусу не помеха.
+
+Контрол, собранный вне документа (страница рендерится во фрагмент и попадает на экран уже собранной), ждёт появления в документе и перепроверяет условия заново — за время ожидания пользователь мог и прокрутить страницу, и уйти в другое поле.
+
+Прокрутку пользователя различает `hasUserScrolled()` из `@brandup/ui-kit`: считаются жесты (колесо, свайп, полоса прокрутки, автопрокрутка средней кнопкой, клавиши прокрутки, действие которых никто не отменил), а не событие `scroll` — его поднимает и программная прокрутка. `UiKitMiddleware` забывает прокрутку при переходе на другую страницу — перед тем, как её нарисуют.
+
 ### Интерфейс IInputControl
 
 ```typescript
@@ -50,9 +66,10 @@ interface IInputControl {
     get disabled(): boolean;
     get required(): boolean;
     get readonly(): boolean;
+    get autoFocus(): boolean;
 
     validate(): boolean;
-    focus(): void;
+    focus(scroll?: ScrollLogicalPosition): void;
     destroy(): void;
 }
 ```
@@ -66,6 +83,8 @@ interface IInputControl {
 | `__focusValue(): void` | Хук: куда именно ведёт фокус контрола. По умолчанию — поле-носитель; общие проверки и прокрутку делает `focus()` |
 | `__requestSubmit(): void` | Неявная отправка формы (Enter), как у обычного `input`: через `form.requestSubmit()` с первой кнопкой отправки |
 | `__submitForm(): void` | Досылает форме синтетический `submit` — движкам без `requestSubmit()` |
+| `__applyAutoFocus(): boolean` | Ставит автофокус, если поле его объявило. Зовётся наследником в конце конструктора; возвращает, поставлен ли фокус сейчас (отложенный до появления в документе даёт `false`) |
+| `static isAutoFocus(valueElem: HTMLElement): boolean` | Объявлен ли автофокус: `autofocus` либо `data-autofocus`. Статический — нужен и до `super(...)` |
 | `static isReadonly(valueElem: HTMLElement): boolean` | Признано ли поле только для чтения: атрибут `readonly` либо `data-readonly` (последний нужен полям без нативного атрибута, например `select`). Статический, потому что режим нужен и до `super(...)` — он влияет на сборку разметки контрола |
 | `static prepareValueElem(valueElem, container, inputClass)` | Переносит собственные классы поля на контейнер, а класс-скрыватель — на поле |
 
@@ -114,6 +133,7 @@ class MyInput extends InputControl<HTMLInputElement> {
 | `setValue(value: string): void` | Передаёт значение редактору — тот нормализует его и поднимет своё изменение |
 | `hasValue(): boolean` | Есть ли непустое значение |
 | `onChange(handler): void` | Подписка на событие изменения контрола (имя события задаёт `EditorControlInit.changeEvent`) |
+| `caret` | Куда контрол ставит каретку при фокусе из кода (`EditorControlInit.caret`, по умолчанию `end`) |
 
 ### Защищённые члены
 
@@ -151,11 +171,33 @@ export interface ValueEditor {
 export interface EditorControlInit {
     /** Имя события изменения контрола — на него подписывает onChange. */
     changeEvent: string;
-    /** Ставить ли при focus() каретку в конец текста, если её ещё не было. */
+    /** Куда ставить каретку при фокусе из кода. По умолчанию — в конец текста. */
+    caret?: FocusCaret;
+    /** @deprecated Замещён caret и учитывается, только если тот не задан: true — "end", false — "start". */
     focusAtEnd?: boolean;
 }
 ```
 
+### FocusCaret
+
+Куда встаёт каретка, когда фокус в контрол ставят из кода — автофокусом или вызовом `focus()`. Фокус мышью и с клавиатуры это не трогает: там место каретки выбирает пользователь.
+
+| Режим | Поведение |
+| --- | --- |
+| `end` | В конец текста — по умолчанию: фокус получают, чтобы продолжать писать, а не чтобы вставлять перед написанным |
+| `start` | В начало текста |
+| `all` | Выделить весь текст, чтобы следующий ввод его заменил |
+
+Режим по умолчанию доверен редактору: каретку, уже стоявшую в содержимом, он бережёт сам — правку продолжают там, где её прервали. `start` и `all` этому не подчиняются: их просили явно, поэтому контрол ставит их сам и после редактора.
+
+Режим из разметки разбирает `parseFocusCaret(value)` — всё, кроме объявленных режимов, даёт `end`:
+
+```typescript
+import { parseFocusCaret } from "@brandup/ui-input";
+
+const caret = parseFocusCaret(valueElem.dataset.caret);
+```
+
 ### Порядок конструирования
 
 Редактор создаёт наследник: его опции замыкаются на `this` и собираются только после `super(...)`. Сразу после создания редактор обязан уйти в `__attachEditor` — до этого момента базовый класс уже привязал элемент, повесил слушатели формы и включил авторазрушение по удалению из DOM, но редактора у него ещё нет. Методы базы этот промежуток терпят (падение конструктора наследника не оставляет на странице обработчиков, которые ломали бы отправку любой формы), но контрол без редактора не работает.

package/package.json

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

package/source/editor-control.ts

@@ -21,11 +21,32 @@ export interface ValueEditor {
 	destroy(): void;
 }
 
+/**
+ * Куда встаёт каретка, когда фокус в контрол ставят из кода — автофокусом или вызовом
+ * {@link InputControl.focus}: в начало текста, в конец или на весь текст выделением, чтобы
+ * следующий ввод его заменил.
+ *
+ * Фокус мышью и с клавиатуры это не трогает: там место каретки выбирает пользователь.
+ */
+export type FocusCaret = "start" | "end" | "all";
+
+/** Разбирает режим каретки из разметки: всё, кроме объявленных режимов, — режим по умолчанию. */
+export const parseFocusCaret = (value: string | null | undefined): FocusCaret =>
+	value === "start" || value === "all" ? value : "end";
+
 /** Что базовому классу нужно знать о конкретном контроле. */
 export interface EditorControlInit {
 	/** Имя события изменения контрола — на него подписывает {@link EditorInputControl.onChange}. */
 	changeEvent: string;
-	/** Ставить ли при {@link EditorInputControl.focus} каретку в конец текста, если её ещё не было. */
+	/**
+	 * Куда ставить каретку при фокусе из кода. По умолчанию — в конец текста: фокус получают,
+	 * чтобы продолжать писать, а не чтобы вставлять перед написанным.
+	 */
+	caret?: FocusCaret;
+	/**
+	 * @deprecated Замещён {@link caret} и учитывается, только если тот не задан: `true` — то же,
+	 * что `"end"`, `false` — `"start"`.
+	 */
 	focusAtEnd?: boolean;
 }
 
@@ -148,6 +169,14 @@ export abstract class EditorInputControl<TEditor extends ValueEditor, TChangeDat
 	 */
 	protected __refreshValidity(): void {}
 
+	/** Куда контрол ставит каретку при фокусе из кода (см. {@link EditorControlInit.caret}). */
+	get caret(): FocusCaret {
+		const { caret, focusAtEnd } = this.__init;
+		if (caret) return caret;
+
+		return focusAtEnd === false ? "start" : "end"; // устаревший флаг, пока его ещё передают
+	}
+
 	onChange(handler: (e: TChangeData) => void) {
 		// имя события у каждого контрола своё — типизацию даёт TEvents наследника
 		this.on(this.__init.changeEvent as keyof TEvents & string, handler as never);
@@ -172,9 +201,31 @@ export abstract class EditorInputControl<TEditor extends ValueEditor, TChangeDat
 	 * Поле-носитель уведено с экрана (visibility: collapse) и в браузере фокус не принимает —
 	 * ведём фокус в редактор. Проверки состояния и прокрутку к контролу делает базовый
 	 * {@link InputControl.focus}.
+	 *
+	 * Каретку ставим по режиму контрола (см. {@link EditorControlInit.caret}). Режим по умолчанию
+	 * доверяем редактору: своё место каретки, если оно было, он бережёт сам — правку продолжают
+	 * там, где прервали. Начало и выделение всего текста этому не подчиняются: их просили явно,
+	 * поэтому ставим их сами и после редактора.
 	 */
 	protected override __focusValue(): void {
-		this.__editor?.focus(this.__init.focusAtEnd);
+		if (!this.__editor) return;
+
+		const caret = this.caret;
+		const editable = this.__editor.editable;
+
+		this.__editor.focus(caret === "end");
+		if (caret === "end") return;
+
+		const selection = editable.ownerDocument.defaultView?.getSelection();
+		if (!selection) return;
+
+		if (caret === "all") return selection.selectAllChildren(editable);
+
+		const range = editable.ownerDocument.createRange();
+		range.selectNodeContents(editable);
+		range.collapse(true); // схлопываем к началу содержимого
+		selection.removeAllRanges();
+		selection.addRange(range);
 	}
 
 	override destroy(): void {

package/source/input.ts

@@ -1,4 +1,8 @@
 import { UIElementBound } from "@brandup/ui";
+// Из кита берём ровно два признака и берём их напрямую: его общий вход тянет за собой попап,
+// модальное окно, стили и @brandup/ui-app — базе ввода это не нужно, а сборке пакета мешает.
+import { isCoarsePointer } from "@brandup/ui-kit/source/utils/compatibility";
+import { hasUserScrolled } from "@brandup/ui-kit/source/utils/user-scroll";
 import "./input.less";
 
 type InputType = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
@@ -6,6 +10,66 @@ type FormInput<T> = T extends InputType ? T : never;
 
 export const INPUT_CSS_CLASS = "ui-input";
 
+/** Контрол, ждущий появления в документе: `__onConnected` возвращает `true`, когда дождался. */
+interface ConnectedWaiter {
+	__onConnected(): boolean;
+}
+
+/**
+ * Ждущие контролы — слабыми ссылками, и наблюдатель один на документ.
+ *
+ * Один на документ, потому что вставку страницы видит любой, а каждый лишний наблюдатель платит
+ * обходом всех мутаций документа. Слабыми, потому что контрол, собранный во фрагмент и там же
+ * выброшенный, ждать иначе не перестанет: авторазрушение снимает контрол, удалённый из документа,
+ * а никогда не вставленный не удаляют — сильная ссылка держала бы и его, и всё его дерево
+ * до ухода со страницы.
+ *
+ * Наблюдатель живёт, только пока есть кого ждать: последнее снятое ожидание его отключает.
+ */
+const connectedWaiters = new Map<Document, { observer: MutationObserver; waiters: Set<WeakRef<ConnectedWaiter>> }>();
+
+function waitConnected(doc: Document, waiter: WeakRef<ConnectedWaiter>): void {
+	let entry = connectedWaiters.get(doc);
+
+	if (!entry) {
+		const observer = new MutationObserver(() => {
+			const current = connectedWaiters.get(doc);
+			if (!current) return;
+
+			for (const ref of [...current.waiters]) {
+				const pending = ref.deref();
+				if (!pending || pending.__onConnected()) current.waiters.delete(ref); // убранный сборщиком тоже отжил
+			}
+
+			if (!current.waiters.size) stopObserving(doc);
+		});
+
+		connectedWaiters.set(doc, (entry = { observer, waiters: new Set() }));
+		observer.observe(doc, { childList: true, subtree: true });
+	}
+
+	entry.waiters.add(waiter);
+}
+
+function stopWaitConnected(doc: Document, waiter: WeakRef<ConnectedWaiter>): void {
+	const entry = connectedWaiters.get(doc);
+	if (!entry?.waiters.delete(waiter) || entry.waiters.size) return;
+
+	stopObserving(doc);
+}
+
+function stopObserving(doc: Document): void {
+	connectedWaiters.get(doc)?.observer.disconnect();
+	connectedWaiters.delete(doc);
+}
+
+/** Принимает ли элемент ввод текста — то есть значит ли фокус на нём, что в нём работают. */
+const isTextEntry = (elem: Element): boolean =>
+	elem instanceof HTMLInputElement ||
+	elem instanceof HTMLTextAreaElement ||
+	elem instanceof HTMLSelectElement ||
+	(elem instanceof HTMLElement && elem.isContentEditable);
+
 export abstract class InputControl<T extends InputType, TEvents = {}>
 	extends UIElementBound<TEvents>
 	implements IInputControl
@@ -17,11 +81,18 @@ export abstract class InputControl<T extends InputType, TEvents = {}>
 	private __overrides?: ValueElemOverrides;
 	private __isValidating?: boolean; // true, когда выполняется checkValidity в validate.
 
+	/** Объявлен ли автофокус; ставит его наследник вызовом {@link __applyAutoFocus}. */
+	readonly autoFocus: boolean;
+
+	/** Ожидание появления контрола в документе — только пока автофокус отложен. */
+	private __autoFocusWait?: WeakRef<ConnectedWaiter>;
+
 	constructor(typeName: string, elem: HTMLElement, valueElem: FormInput<T>, overrides?: ValueElemOverrides) {
 		super(typeName, elem);
 
 		this.__valueElem = valueElem;
 		this.__overrides = overrides;
+		this.autoFocus = InputControl.isAutoFocus(valueElem);
 
 		// то, что раньше делал _onRenderElement-override; теперь применяем после super, чтобы видеть valueElem
 		elem.classList.add(INPUT_CSS_CLASS);
@@ -43,6 +114,23 @@ export abstract class InputControl<T extends InputType, TEvents = {}>
 		return valueElem.hasAttribute("readonly") || valueElem.hasAttribute("data-readonly");
 	}
 
+	/**
+	 * Объявлен ли автофокус: нативный `autofocus` либо `data-autofocus` — второй нужен разметке,
+	 * которой нативный атрибут не подходит по другим причинам (валидаторы, серверный рендер).
+	 *
+	 * Браузер разбирает нативный атрибут при разборе разметки, когда контрола ещё нет: поле,
+	 * скрытое классом уже в разметке, он пропустит, а видимое — сфокусирует, но перенос поля
+	 * в контейнер контрола этот фокус тут же собьёт (браузер снимает фокус с перемещаемого узла).
+	 * Так что фокус в любом случае ставит контрол — см. {@link __applyAutoFocus}, — а атрибут
+	 * остаётся объявлением намерения.
+	 *
+	 * Статический, потому что контролам это нужно и до `super(...)`; после конструирования
+	 * то же самое отдаёт {@link autoFocus}.
+	 */
+	protected static isAutoFocus(valueElem: HTMLElement): boolean {
+		return valueElem.hasAttribute("autofocus") || valueElem.hasAttribute("data-autofocus");
+	}
+
 	/**
 	 * Готовит поле-носитель к обёртке контейнером контрола: класс-скрыватель переезжает на поле,
 	 * а собственные классы поля — на контейнер, чтобы оформление из разметки применялось к тому,
@@ -181,12 +269,17 @@ export abstract class InputControl<T extends InputType, TEvents = {}>
 	 *
 	 * Поле только для чтения фокусируется: это его нативное поведение — текст читают,
 	 * выделяют и копируют, и уводить от него клавиатуру нельзя.
+	 *
+	 * `scroll` — насколько двигать вид: по умолчанию контрол выводится в середину экрана, потому
+	 * что фокус из кода обычно ведут к тому, что нужно показать (ошибка формы, шаг мастера).
+	 * Автофокус просит `"nearest"` — там страницу ещё не читали, и сдвигать её ради поля,
+	 * которое и так на виду, не за чем.
 	 */
-	focus(): void {
+	focus(scroll: ScrollLogicalPosition = "center"): void {
 		if (this.disabled) return;
 
 		this.__focusValue();
-		this.element.scrollIntoView({ block: "center", inline: "center" });
+		this.element.scrollIntoView({ block: scroll, inline: scroll });
 	}
 
 	/**
@@ -198,6 +291,76 @@ export abstract class InputControl<T extends InputType, TEvents = {}>
 		this.__valueElem.focus();
 	}
 
+	/**
+	 * Ставит фокус в контрол, если поле объявило автофокус (см. {@link isAutoFocus}). Зовёт
+	 * наследник в конце своего конструктора: базовый отработал раньше, чем собран ввод контрола
+	 * (редактор привязывается уже после `super(...)`), и фокусировать там было бы нечего.
+	 *
+	 * Отказывает молча, потому что автофокус — пожелание разметки, а не команда:
+	 * - выключенное поле фокус не принимает, а поле только для чтения нечего править;
+	 * - вводят пальцем — экранная клавиатура закрыла бы страницу, которую ещё не читали;
+	 * - пользователь уже прокрутил страницу сам — вид принадлежит ему;
+	 * - фокус держит поле ввода или другой контрол — там уже работают.
+	 *
+	 * @returns Поставлен ли фокус сейчас; отложенный до появления в документе даёт `false`.
+	 */
+	protected __applyAutoFocus(): boolean {
+		if (!this.autoFocus) return false;
+
+		// Контрол собирают и вне документа: страница рендерится во фрагмент и попадает на экран
+		// уже собранной. В неподключённый элемент браузер фокус не ставит, а прокручивать нечего,
+		// поэтому ждём появления в документе — и там же перепроверяем условия заново: за время
+		// ожидания пользователь мог и прокрутить страницу, и встать в другое поле.
+		if (!this.element.isConnected) {
+			this.__waitConnected();
+			return false;
+		}
+
+		this.__stopWaitConnected();
+
+		if (this.disabled || this.readonly || isCoarsePointer() || hasUserScrolled()) return false;
+
+		// Чужой фокус не отбираем: его держит либо поле ввода — там уже печатают, — либо контрол
+		// ввода, инициализированный раньше (двух автофокусов на странице не бывает). Кнопка или
+		// ссылка, которой пришли на страницу, автофокусу не помеха: фокус на ней остался от клика,
+		// а не ради ввода. Фокус внутри самого контрола — тем более.
+		const active = this.__valueElem.ownerDocument.activeElement;
+		if (active && !this.element.contains(active) && (isTextEntry(active) || active.closest(`.${INPUT_CSS_CLASS}`)))
+			return false;
+
+		this.focus("nearest");
+
+		return true;
+	}
+
+	/** Ждёт появления контрола в документе, чтобы поставить отложенный автофокус. */
+	private __waitConnected() {
+		if (this.__autoFocusWait) return;
+
+		// приведение — ради приватного метода: реестру ожиданий нужен только он
+		this.__autoFocusWait = new WeakRef(this as unknown as ConnectedWaiter);
+		waitConnected(this.__valueElem.ownerDocument, this.__autoFocusWait);
+	}
+
+	/**
+	 * Контрол появился в документе — ставим отложенный автофокус. Не приватный только потому,
+	 * что зовут его снаружи класса — из реестра ожиданий этого модуля.
+	 */
+	protected __onConnected(): boolean {
+		if (!this.element.isConnected) return false;
+
+		this.__applyAutoFocus(); // подключённый контрол сам снимет ожидание
+
+		return true;
+	}
+
+	private __stopWaitConnected() {
+		if (!this.__autoFocusWait) return;
+
+		stopWaitConnected(this.__valueElem.ownerDocument, this.__autoFocusWait);
+		this.__autoFocusWait = undefined;
+	}
+
 	/**
 	 * Возвращает поле-носитель в исходное состояние: снимает класс, которым контрол увёл его
 	 * с экрана, возвращает подменённые атрибуты и вынимает поле из контейнера, а сам контейнер
@@ -219,6 +382,8 @@ export abstract class InputControl<T extends InputType, TEvents = {}>
 	}
 
 	override destroy() {
+		this.__stopWaitConnected();
+
 		if (this.form && this.__submitEvent) this.form.removeEventListener("submit", this.__submitEvent);
 
 		if (this.__submitCaptureEvent)
@@ -250,8 +415,9 @@ export interface IInputControl {
 	get disabled(): boolean;
 	get required(): boolean;
 	get readonly(): boolean;
+	get autoFocus(): boolean;
 
 	validate(): boolean;
-	focus(): void;
+	focus(scroll?: ScrollLogicalPosition): void;
 	destroy(): void;
 }