@brandup/ui-textbox

Компонент текстового поля. Заменяет стандартные <input> и <textarea>, добавляя расширенное поведение: счётчик символов, кнопку копирования, фильтрацию ввода по типу, валидацию и опциональное форматирование текста (жирный, курсив, зачёркивание, подчёркивание).

Вся работа с редактируемой областью вынесена в @brandup/ui-richeditor: TextBox создаёт скрытое поле формы и компонует над ним RichEditor. Экземпляр редактора доступен через свойство editor.

Установка

npm i @brandup/ui-textbox

Использование

<input id="name" type="text" placeholder="Введите имя" />

import TextBox from "@brandup/ui-textbox";
import { CHANGE_EVENT, ChangeEventData } from "@brandup/ui-textbox";

const inputElem = document.getElementById("name") as HTMLInputElement;
const textbox = new TextBox(inputElem);

textbox.on(CHANGE_EVENT, (data: ChangeEventData) => {
    console.log(data.value);
});

Поддерживаемые типы

TextBox принимает <input> со следующими значениями атрибута type:

| Тип | Поведение | |---|---| | text | Обычный текст | | email | Фильтрует недопустимые символы, ограничивает длину до 256 символов (RFC 5321) | | url | URL-адрес | | tel | Телефон | | number | Только цифры, вставка фильтруется |

Для многострочного ввода передайте <textarea>.

Data-атрибуты

| Атрибут | Описание | |---|---| | data-symbolcounter | Показывает счётчик введённых символов (и максимума, если задан maxlength) | | data-autofocus | Автофокус при инициализации (игнорируется на touch-устройствах) | | data-copy-button | Добавляет кнопку копирования значения в буфер обмена | | data-allow-empty-strings | Разрешает значение из одних пробелов | | data-readonly | Альтернативный способ задать режим только для чтения | | data-format | Включает форматирование текста (только для type="text") | | data-format-tools | Состав инструментов форматирования через пробел (по умолчанию все): bold italic strike underline | | data-format-storage | Формат хранения значения: html (по умолчанию) или markdown | | data-format-md-bold | Markdown-маркер для жирного (по умолчанию **) | | data-format-md-italic | Markdown-маркер для курсива (по умолчанию *) | | data-format-md-strike | Markdown-маркер для зачёркивания (по умолчанию ~~) | | data-format-md-underline | Markdown-маркер для подчёркивания (по умолчанию ++) |

Форматирование текста

Атрибут data-format включает панель форматирования с инструментами: жирный, курсив, зачёркивание, подчёркивание. Панель всплывает над контролом, пока он в фокусе (класс состояния focused). Работает поверх существующего contenteditable-редактора, поэтому доступно только для текстового ввода (type="text" и <textarea>).

<!-- все инструменты, хранение в HTML -->
<textarea data-content-script="textbox" data-format></textarea>

<!-- только жирный и курсив, хранение в Markdown -->
<input
    type="text"
    data-content-script="textbox"
    data-format
    data-format-tools="bold italic"
    data-format-storage="markdown"
/>

Состав инструментов — data-format-tools

Список через пробел из значений bold, italic, strike, underline. Неизвестные значения игнорируются. Если атрибут не задан — включаются все инструменты.

Применение формата

• Формат — переключатель (toggle): повторное применение к уже отформатированному тексту снимает его.
• Форматирование применяется к слову целиком: если курсор стоит внутри слова без выделения или выделена лишь его часть — формат охватывает всё слово. При выделении части нескольких слов каждая граница доводится до целого слова. Исходное выделение/каретка после применения сохраняются (слово не выделяется автоматически).
• Режим набора: если под кареткой нет слова (курсор между пробелами или поле пустое), кнопка/хоткей не форматируют текст, а включают «ожидающий» формат — он подсветится активным и применится к следующему введённому тексту. Режим сбрасывается при перемещении каретки, клике или потере фокуса.
• Кнопка инструмента подсвечивается (active), когда выделение целиком отформатировано этим инструментом или активен режим набора.
• Реализация работает на стандартном Selection/Range API — без устаревшего document.execCommand, поэтому разметка всегда семантическая (<b>, <i>, <s>, <u>) и предсказуема между браузерами.

Хоткеи

Ctrl/Cmd+B — жирный, Ctrl/Cmd+I — курсив, Ctrl/Cmd+U — подчёркивание. Зачёркивание включается только кнопкой. Хоткеи отключённых инструментов перехватываются, чтобы не срабатывало форматирование браузера.

Формат хранения — data-format-storage

Значение синхронизируется в скрытое поле в выбранном формате:

| Значение | Хранение | Поддерживаемые теги/маркеры | |---|---|---| | html (по умолчанию) | Санитизированный HTML | <b>, <i>, <s>, <u>, переводы строк через <br> | | markdown | Лёгкая разметка | **жирный**, *курсив*, ~~зачёркнутый~~, ++подчёркнутый++ |

Маркеры для каждого инструмента настраиваются атрибутами data-format-md-<tool> (актуально только при data-format-storage="markdown"):

<textarea
    data-content-script="textbox"
    data-format
    data-format-storage="markdown"
    data-format-md-italic="_"
    data-format-md-bold="__"
></textarea>

При разборе маркеры применяются по убыванию длины, поэтому более длинный маркер (__) корректно срабатывает раньше короткого-префикса (_). Маркеры разных инструментов должны различаться.

Markdown-режим не имеет стандартного маркера для подчёркивания — по умолчанию используется ++текст++. Глубоко вложенные комбинации форматов (например, жирный внутри курсива) гарантированно сохраняются только в режиме html.

API

Методы

| Метод | Описание | |---|---| | getValue(): string | Возвращает текущее значение (обрезает пробелы по краям) | | setValue(value: string): void | Устанавливает значение программно | | hasValue(): boolean | true, если значение не пустое | | validate(): boolean | Валидирует значение, добавляет/снимает класс invalid | | focus(): void | Устанавливает фокус, прокручивает в видимую область | | destroy(): void | Восстанавливает исходный DOM-элемент и освобождает ресурсы |

Свойства

| Свойство | Тип | Описание | |---|---|---| | type | TextBoxType | Тип ввода: "text" | "email" | "url" | "tel" | "number" | | multyline | boolean | true для <textarea> | | maxlength | number | Максимальная длина (из атрибута maxlength) | | copyButton | boolean | Наличие кнопки копирования | | symbolCounter | boolean | Наличие счётчика символов | | placeholder | string \| null | Текст-заглушка | | format | boolean | Включено ли форматирование | | formatStorage | FormatStorage | Формат хранения: "html" | "markdown" | | formatTools | FormatTool[] | Включённые инструменты форматирования | | formatMarkers | FormatMarkers | Markdown-маркеры по инструментам (с учётом переопределений) |

Событие textbox-change

Генерируется при каждом изменении значения.

import { CHANGE_EVENT, ChangeEventData } from "@brandup/ui-textbox";

textbox.on(CHANGE_EVENT, (data: ChangeEventData) => {
    console.log(data.value);   // текущее значение
    console.log(data.textbox); // ссылка на экземпляр TextBox
});

// Или через helper-метод
textbox.onChange((data) => { ... });

Нормализация пробелов

Когда редактирование логически завершено (поле теряет фокус), а также после инициализации и setValue, текст нормализуется:

• повторяющиеся пробелы/табы схлопываются в один;
• пробелы по краям каждой строки обрезаются.

Форматирование и переносы строк (<br>/блоки) при этом сохраняются. Во время набора текста пробелы не трогаются — нормализация выполняется только по завершении. Если нормализация изменила значение, при потере фокуса генерируется событие textbox-change.

CSS-классы состояний

| Класс | Условие | |---|---| | focused | Поле в фокусе | | invalid | Значение не прошло валидацию | | incorrect | Введён недопустимый символ (мигает, затем снимается) | | required | Атрибут required задан | | readonly | Режим только для чтения | | disabled | Элемент отключён | | active | На кнопке панели форматирования — формат активен для текущего выделения |