@olddevs/ui 0.0.0-stage → 4.0.0

package/src/components/inputs/MaskedInput.tsx

@@ -0,0 +1,288 @@
+"use client";
+
+import {
+  forwardRef,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ComponentPropsWithoutRef,
+  type KeyboardEvent,
+} from "react";
+import { useMessages } from "../../i18n/useMessages.js";
+import {
+  caretAfter,
+  formatMask,
+  maskRemainder,
+  maskTokenAt,
+  rawLengthBefore,
+  unmask,
+  unmaskOverflow,
+  type MaskToken,
+} from "../../lib/mask.js";
+import { TextControl } from "./TextControl.js";
+
+/** Токен маски → то, чего ждали, словами каталога. */
+const EXPECTED: Record<MaskToken, "digit" | "letter" | "any"> = {
+  "9": "digit",
+  a: "letter",
+  "*": "any",
+};
+
+export interface MaskedInputProps extends Omit<
+  ComponentPropsWithoutRef<"input">,
+  "onChange" | "value" | "defaultValue" | "size"
+> {
+  /**
+   * Маска: `9` — цифра, `a` — буква, `*` — цифра или буква; остальное литерал.
+   *
+   * Кит о предметной области не знает: маска приходит пропом, и «телефон» или
+   * «серия паспорта» — знание вызывающего.
+   */
+  mask: string;
+  /** Сырое значение — без литералов маски. Именно оно уходит на сервер. */
+  value: string;
+  /**
+   * Вызывается с обоими представлениями: сырым и показанным.
+   *
+   * Сырое нужно запросу, показанное — тому, кто хранит текст как есть. Отдать
+   * одно — значит заставить половину потребителей форматировать заново.
+   */
+  onChange: (raw: string, formatted: string) => void;
+  /** Классы на оболочку с рамкой. */
+  shellClassName?: string;
+  /**
+   * Показывать формат прямо в поле: `+7 (___) ___-__-__`.
+   *
+   * ПО УМОЛЧАНИЮ ВКЛЮЧЕНО, и это не косметика. До появления трафарета поле не
+   * сообщало формат ВООБЩЕ: `formatMask` подставляет литералы только пока есть
+   * что ставить дальше, поэтому пустое поле показывало пустой прямоугольник, а
+   * наполовину заполненное — обрубок без остатка. Пользователь узнавал формат
+   * методом проб.
+   *
+   * Выключается там, где формат уже сказан рядом и повторять его в поле —
+   * шум: короткая известная маска в плотной таблице, поле под своей подписью
+   * с примером.
+   *
+   * Трафарет — УКРАШЕНИЕ: он `aria-hidden` и скринридеру не достаётся. Формат для
+   * него живёт в подсказке `FormField`, которая с полем связана
+   * (`aria-describedby`), — и это разделение сознательное: постоянная подсказка
+   * доступна и при проверке набранного, а трафарет по мере ввода исчезает.
+   */
+  showMask?: boolean;
+}
+
+/**
+ * Поле с маской ввода.
+ *
+ * СТОИТ НА `TextControl` (прецедент ADR-0009): рамка, фокус, выключенное и
+ * невалидное состояния — его; здесь только механика маски.
+ *
+ * ЗНАЧЕНИЕ СЫРОЕ, ПОКАЗ ОТФОРМАТИРОВАННЫЙ. Хранить формат — значит хранить
+ * решение о показе: маску можно поменять, а записанные с ней скобки останутся
+ * в базе навсегда.
+ *
+ * КАРЕТКА — ТО, РАДИ ЧЕГО КОМПОНЕНТ ВООБЩЕ НУЖЕН. Форматирование на каждом
+ * вводе перерисовывает строку целиком, и браузер ставит каретку в конец;
+ * править середину номера становится невозможно. Поэтому позиция считается по
+ * маске: сколько символов значения стояло левее — столько и останется.
+ *
+ * BACKSPACE ЧЕРЕЗ ЛИТЕРАЛ УДАЛЯЕТ СИМВОЛ ЗНАЧЕНИЯ, а не литерал. Иначе каретка
+ * упирается в `)` и стирание встаёт: литерал удалится, тут же вернётся
+ * форматированием, и нажатие ничего не изменит — дефект, который выглядит как
+ * зависшая клавиша.
+ *
+ * Вставка отдельного обработчика не требует: вставленное приходит тем же
+ * событием ввода, и разбор по маске раскладывает его так же, как набранное
+ * (`unmask` в `lib/mask.ts`).
+ */
+export const MaskedInput = forwardRef<HTMLInputElement, MaskedInputProps>(function MaskedInput(
+  { mask, value, onChange, onKeyDown, showMask = true, ...rest },
+  ref
+) {
+  const innerRef = useRef<HTMLInputElement>(null);
+  useImperativeHandle(ref, () => innerRef.current as HTMLInputElement, []);
+  // Каретка живёт в `ref`: она нужна ровно один раз, сразу после перерисовки.
+  const caret = useRef<number | null>(null);
+
+  const messages = useMessages();
+  /*
+    Что сказать об отброшенном символе.
+
+    Отбрасывание было МОЛЧАЛИВЫМ: `unmask` пропускает не подошедший под токен
+    символ и идёт дальше. Пользователь видел, что нажатие «не сработало», и
+    оставался без объяснения — на этом же эталонная реализация USWDS провалила
+    тест WCAG 3.3.3 (у неё несовпавший символ вдобавок обрывает весь остаток).
+
+    Повторное нажатие той же неподходящей клавиши даёт ТУ ЖЕ строку, и
+    скринридер её не переобъявляет — очереди из объявлений не возникает само
+    собой, без подавления и таймеров.
+  */
+  const [rejection, setRejection] = useState("");
+
+  const formatted = formatMask(value, mask);
+
+  /*
+    Трафарет маски под значением.
+
+    СКРЫТЫЙ ПРЕФИКС ДЕРЖИТ НАБРАННОЕ, а не символы маски: тогда ширины
+    совпадают ПО ПОСТРОЕНИЮ — под цифрой стоит та же цифра, — и остаток
+    начинается ровно там, где кончился ввод. Держи он подчёркивания, совпадение
+    зависело бы от того, одинаковой ли ширины `_` и `8` в шрифте потребителя,
+    то есть было бы случайным.
+
+    Считается из `value` в рендере, а не в обработчике нажатий. У эталонной
+    реализации USWDS обработчик висит на `keyup`, и вставка мышью,
+    автозаполнение и любое программное изменение оставляют трафарет
+    рассинхронизированным с полем.
+
+    `GrayText` в режиме высокой контрастности: система красит весь текст одним
+    цветом, и без этого трафарет стал бы неотличим от набранного — то есть поле
+    показывало бы цифры, которых нет.
+  */
+  const underlay = showMask ? (
+    <>
+      <span className="invisible">{formatted}</span>
+      <span className="text-fg-2 forced-colors:text-[color:GrayText]">
+        {maskRemainder(value, mask)}
+      </span>
+    </>
+  ) : undefined;
+
+  useLayoutEffect(() => {
+    const el = innerRef.current;
+    const at = caret.current;
+    caret.current = null;
+    if (el && at != null) el.setSelectionRange(at, at);
+  });
+
+  const commit = (raw: string, rawCaret: number) => {
+    caret.current = caretAfter(mask, rawCaret);
+    onChange(raw, formatMask(raw, mask));
+  };
+
+  const control = (
+    <TextControl
+      ref={innerRef}
+      underlay={underlay}
+      value={formatted}
+      onChange={(event) => {
+        const shown = event.target.value;
+        const position = event.target.selectionStart ?? shown.length;
+        const raw = unmask(shown, mask);
+
+        /*
+          Набранное пропало: строка показа выросла, а значение не изменилось.
+
+          Вопрос задаётся именно так — «изменилось ли значение», а не «годится
+          ли символ под токен». Разница видна на литерале маски, который сам
+          допустимый символ: в `+7 (999) 999-99-99` литерал `7` — цифра.
+          Пользователь набирает `7` первым (привычка набирать `+7`), `unmask`
+          съедает его как литерал, значение остаётся пустым — и проверка «по
+          токену» считала бы символ принятым и молчала. То есть ровно тот
+          дефект, ради которого объявление и заводилось.
+
+          Сравнение по значению, а не по его длине: правка СЕРЕДИНЫ заполненного
+          поля меняет значение, не меняя длины, и по длине выглядела бы отказом.
+          Она же роняла каретку лишней перерисовкой.
+
+          Длина показа в условии обязательна: без неё удаление литерала (`)`)
+          тоже даёт неизменное значение и объявлялось бы отказом.
+        */
+        const added = shown.length - formatted.length;
+        /*
+          Обрезка ВСТАВКИ — отдельная ветка, и различается она по `inputType`,
+          а не по длине.
+
+          Отличить её от соседей иначе нечем: набор лишнего символа в полном
+          поле тоже даёт переполнение, но это `full`, а правка СЕРЕДИНЫ полного
+          поля выталкивает символ и обязана молчать (см. ниже). Общее у этих
+          двух — пользователь видит, что делает. У вставки не видит: хвост
+          исчезает целиком, и `89161234567` становится `+7 (891) 612-34-56` —
+          чужим, но правдоподобным номером.
+
+          Условие `raw === value` ниже вставку не ловит принципиально: при ней
+          значение МЕНЯЕТСЯ.
+        */
+        const native = event.nativeEvent;
+        const inputType = native instanceof InputEvent ? native.inputType : undefined;
+        /*
+          «Пришло не по одному символу» — вот что на самом деле отличает этот
+          случай, и одного `insertFromPaste` для этого мало:
+
+          - перетаскивание текста мышью даёт `insertFromDrop`;
+          - подстановка из менеджера паролей или строки подсказок телефона —
+            `insertReplacementText`, а программная запись значения приходит
+            обычным `Event`, у которого `inputType` пуст или отсутствует. На мобильном это
+            САМЫЙ частый способ, каким телефон попадает в телефонное поле.
+
+          Отсюда последнее условие: неизвестный `inputType` при `added > 1`.
+          Оно же отделяет эти пути от набора символа в полном поле — там
+          `added === 1`, и отвечать должна ветка `full` ниже.
+        */
+        const bulk =
+          inputType === "insertFromPaste" ||
+          inputType === "insertFromPasteAsQuotation" ||
+          inputType === "insertFromDrop" ||
+          inputType === "insertReplacementText" ||
+          (!inputType && added > 1);
+        const overflow = bulk ? unmaskOverflow(shown, mask) : 0;
+        if (overflow > 0) {
+          setRejection(messages.maskedInput.truncated({ count: overflow }));
+        } else if (added > 0 && raw === value) {
+          // Куда метил ввод: сколько символов значения стоит левее вставленного.
+          const at = rawLengthBefore(mask, Math.max(position - added, 0));
+          const token = maskTokenAt(mask, at);
+          setRejection(
+            token == null
+              ? messages.maskedInput.full
+              : messages.maskedInput.rejected({ expected: EXPECTED[token] })
+          );
+        } else if (rejection) setRejection("");
+
+        // Сколько символов значения оказалось левее каретки — столько и
+        // останется: позиция считается по показанной строке, а не по сдвигу.
+        commit(raw, unmask(shown.slice(0, position), mask).length);
+      }}
+      onKeyDown={(event: KeyboardEvent<HTMLInputElement>) => {
+        // Чужой обработчик вызывается ПЕРВЫМ и может отменить наш `preventDefault`
+        // — иначе он был бы вытеснен спредом, как это уже случилось со `style`
+        // у `TopBar` в ревью 2.1.0.
+        onKeyDown?.(event);
+        if (event.defaultPrevented || event.key !== "Backspace") return;
+
+        const el = event.currentTarget;
+        const start = el.selectionStart ?? 0;
+        if (start !== el.selectionEnd) return;
+
+        const before = rawLengthBefore(mask, start);
+        if (before === 0) return;
+        event.preventDefault();
+        commit(value.slice(0, before - 1) + value.slice(before), before - 1);
+      }}
+      {...rest}
+    />
+  );
+
+  /*
+    Живая область СМОНТИРОВАНА ВСЕГДА, подменяется только текст. Область,
+    вставленная в документ вместе с сообщением, объявляется ненадёжно — часть
+    скринридеров успевает её пропустить. Тот же приём и по той же причине, что
+    в `FileDropzone`.
+
+    `status`, а не `alert`: отброшенная клавиша — не ошибка формы, и перебивать
+    ею текущую речь значит наказывать за опечатку.
+
+    Фрагмент, а не обёртка: обёртка вокруг поля сменила бы разметку всем, кто
+    уже ставит `MaskedInput` в свою раскладку. Область спрятана `sr-only`,
+    выпадает из потока и на раскладку не влияет.
+  */
+  return (
+    <>
+      {control}
+      <span role="status" aria-live="polite" className="sr-only">
+        {rejection}
+      </span>
+    </>
+  );
+});

package/src/components/inputs/NumberInput.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import { forwardRef } from "react";
+import { Button, Group, Input, NumberField } from "react-aria-components";
+import { useFieldDescribedBy, useFieldInvalid } from "../../hooks/useFieldDescription.js";
+import { cn } from "../../lib/cn.js";
+import { useMessages } from "../../i18n/useMessages.js";
+import { FIELD_INPUT_CLASS, FIELD_SHELL_CLASS } from "../../lib/field.js";
+
+export interface NumberInputProps {
+  /** `null` — поле пусто. Это не то же самое, что введённый ноль. */
+  value: number | null;
+  /** Вызывается при смене числа; `null` — поле очищено. */
+  onChange: (value: number | null) => void;
+  /** Наименьшее допустимое значение. */
+  min?: number;
+  /** Наибольшее допустимое значение. */
+  max?: number;
+  /** Шаг изменения кнопками и стрелками клавиатуры. */
+  step?: number;
+  /** Формат отображения: проценты, валюта, единицы. Идёт в `Intl.NumberFormat`. */
+  formatOptions?: Intl.NumberFormatOptions;
+  /** Плейсхолдер в пустом поле. */
+  placeholder?: string;
+  /** Выключает поле и кнопки шага. */
+  disabled?: boolean;
+  /** Показывает поле в состоянии ошибки. */
+  invalid?: boolean;
+  /**
+   * Доступное имя. Обязательно и проверяется компилятором — как у `Toggle`.
+   *
+   * Подпись из `FormField` сюда не дотягивается: react-aria генерирует `id`
+   * внутреннему полю сам, и связать с ним чужой `<label htmlFor>` нечем.
+   * Поэтому имя компонент держит у себя.
+   */
+  label: string;
+  /** Классы на оболочку с рамкой — ширина, скругление, внутренние отступы. */
+  shellClassName?: string;
+  /** Классы на корневой элемент. */
+  className?: string;
+}
+
+const STEP_BUTTON_CLASS =
+  "text-fg-2 hover:text-fg-0 hover:bg-bg-3 flex size-6 shrink-0 items-center justify-center " +
+  "rounded-xs text-[15px] leading-none transition-colors disabled:pointer-events-none disabled:opacity-40";
+
+/**
+ * Числовое поле со ступенями.
+ *
+ * ПУСТОЕ ПОЛЕ ОТДАЁТ `null`, А НЕ НОЛЬ. Ноль — это введённое значение, и
+ * отличать его от «ничего не введено» обязано само значение, а не догадка
+ * потребителя. Та же логика, по которой `Select` отдаёт `null` при очистке.
+ * Внутри react-aria пустоту выражает `NaN`; наружу он не выходит — `NaN`
+ * не равен сам себе, и потребитель, сравнивший его с чем угодно, получил бы
+ * тихо неверный результат.
+ *
+ * Вид рамки, фокуса и выключенного состояния — общий с `TextControl`, из
+ * `lib/field.ts`. Не копия: два поля, стоящие в одной форме рядом, обязаны
+ * фокусироваться одинаково, а копипаст классов расходится — во фронте до
+ * пакета так и вышло с пятью полями поиска.
+ *
+ * Разбор и форматирование по `formatOptions` держит react-aria: локаль, разряды,
+ * знак процента, ввод «1 234,5» — всё это его работа, и повторять её здесь
+ * означало бы писать вторую библиотеку.
+ */
+export const NumberInput = forwardRef<HTMLDivElement, NumberInputProps>(function NumberInput(
+  {
+    value,
+    onChange,
+    min,
+    max,
+    step,
+    formatOptions,
+    placeholder,
+    disabled,
+    invalid,
+    label,
+    shellClassName,
+    className,
+  },
+  ref
+) {
+  const messages = useMessages();
+  // Подсказка или ошибка `FormField`. `NumberField` доводит атрибут до своего
+  // `Input` сам — своего пропа описания у компонента нет, и сливать нечего.
+  const describedBy = useFieldDescribedBy();
+  // Ошибка `FormField` доходит до поля так же, как у `TextControl`; явный
+  // `invalid` сильнее формы.
+  const fieldInvalid = useFieldInvalid();
+  return (
+    <NumberField
+      ref={ref}
+      value={value ?? Number.NaN}
+      onChange={(next) => onChange(Number.isNaN(next) ? null : next)}
+      minValue={min}
+      maxValue={max}
+      step={step}
+      formatOptions={formatOptions}
+      isDisabled={disabled}
+      isInvalid={invalid ?? (fieldInvalid || undefined)}
+      aria-label={label}
+      aria-describedby={describedBy}
+      className={className}
+    >
+      <Group
+        className={cn(
+          FIELD_SHELL_CLASS,
+          "flex items-center gap-1",
+          // Красная рамка невалидного поля переехала в `FIELD_SHELL_CLASS`: там
+          // же живёт сама рамка, и там правило достаётся всем полям на этой
+          // оболочке, а не одному числовому. Атрибут `data-invalid`, который
+          // ловит вариант `invalid:`, по-прежнему висит на этой группе.
+          shellClassName
+        )}
+      >
+        <Button
+          slot="decrement"
+          className={STEP_BUTTON_CLASS}
+          aria-label={messages.numberInput.decrement({ label: label ?? "" })}
+        >
+          −
+        </Button>
+        <Input
+          data-disable-focus-ring="true"
+          placeholder={placeholder}
+          className={cn(FIELD_INPUT_CLASS, "min-w-0 flex-1 text-center tabular-nums")}
+        />
+        <Button
+          slot="increment"
+          className={STEP_BUTTON_CLASS}
+          aria-label={messages.numberInput.increment({ label: label ?? "" })}
+        >
+          +
+        </Button>
+      </Group>
+    </NumberField>
+  );
+});

package/src/components/inputs/PasswordInput.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+import {
+  forwardRef,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ComponentPropsWithoutRef,
+  type FocusEvent,
+  type KeyboardEvent,
+} from "react";
+import { useMessages } from "../../i18n/useMessages.js";
+import { HiddenIcon, VisibleIcon, WarningIcon } from "../../icons.js";
+import { TextControl } from "./TextControl.js";
+
+export interface PasswordInputProps extends Omit<
+  ComponentPropsWithoutRef<"input">,
+  "type" | "size"
+> {
+  /**
+   * Подпись кнопки показа. Одна на оба состояния — состояние объявляет
+   * `aria-pressed`.
+   */
+  toggleLabel?: string;
+  /**
+   * Показывает предупреждение, когда включён Caps Lock. По умолчанию включено.
+   *
+   * Предупреждение о включённом Caps Lock. Выключается пропом, потому что поле
+   * пароля встречается и там, где подсказка неуместна, — например в диалоге
+   * подтверждения из одного поля.
+   */
+  capsLockWarning?: boolean;
+  /** Классы на оболочку с рамкой — ширина, скругление, внутренние отступы. */
+  shellClassName?: string;
+}
+
+/**
+ * Поле пароля: кнопка показа в слоте, предупреждение о Caps Lock под полем.
+ *
+ * СТОИТ НА `TextControl` СЛОТАМИ, а не на своей оболочке — прямой прецедент
+ * `SearchControl` (ADR-0009). Рамка, фокус, выключенное и невалидное состояния
+ * остаются у `TextControl`; своей рамки компонент не рисует вовсе, иначе
+ * поле пароля фокусировалось бы не так, как соседнее поле в той же форме.
+ *
+ * ЧТО КОМПОНЕНТ ДОБАВЛЯЕТ СВЕРХ СЛОТА — ровно три вещи, и каждая есть причина
+ * его существования:
+ *
+ * 1. **Переключение показа с сохранением каретки.** Смена `type` сбрасывает
+ *    выделение в конец значения, и пользователь, открывший пароль посреди
+ *    правки, терял место. Позиция снимается до переключения и возвращается
+ *    после — без переноса фокуса: кнопку нажали намеренно, и увозить с неё
+ *    фокус значит ломать повторное нажатие с клавиатуры.
+ * 2. **Предупреждение о Caps Lock** — читается из `getModifierState` на
+ *    клавиатурном событии, а не угадывается по регистру введённого: в поле
+ *    пароля символов не видно, а «все заглавные» — законный пароль.
+ * 3. **`autocomplete` пропом.** Значения по умолчанию нет намеренно: вход это
+ *    или смена пароля, знает вызывающий, а кит — нет. Ставьте
+ *    `autoComplete="current-password"` на входе и `"new-password"` в смене.
+ *
+ * У КНОПКИ ПОКАЗА `aria-pressed`, А ПОДПИСЬ ПОСТОЯННАЯ. Без признака
+ * скринридер не сообщит, что пароль сейчас открыт на экране, — а это состояние
+ * безопасности, а не украшение. Подпись при этом не меняется: кнопка, у
+ * которой меняются и имя, и состояние, читается противоречиво («Скрыть
+ * пароль, нажато»).
+ */
+export const PasswordInput = forwardRef<HTMLInputElement, PasswordInputProps>(
+  function PasswordInput(
+    { toggleLabel, capsLockWarning = true, className, shellClassName, disabled, ...rest },
+    ref
+  ) {
+    const messages = useMessages();
+    const innerRef = useRef<HTMLInputElement>(null);
+    useImperativeHandle(ref, () => innerRef.current as HTMLInputElement, []);
+    const [visible, setVisible] = useState(false);
+    const [capsLock, setCapsLock] = useState(false);
+    // Позиция каретки живёт в `ref`, а не в состоянии: она нужна ровно один
+    // раз, сразу после смены `type`, и лишний рендер ради неё не нужен.
+    const caret = useRef<[number, number] | null>(null);
+
+    useLayoutEffect(() => {
+      const el = innerRef.current;
+      const at = caret.current;
+      caret.current = null;
+      // `setSelectionRange` не переносит фокус — поле остаётся там, где было,
+      // а нажатая кнопка не теряет своего.
+      if (el && at) el.setSelectionRange(at[0], at[1]);
+    }, [visible]);
+
+    // Отслеживание Caps Lock заводится ЛЕНИВО: без предупреждения обработчики
+    // не появляются вовсе, и поле остаётся тем же `TextControl` со слотом.
+    const track = capsLockWarning
+      ? {
+          onKeyDown: (event: KeyboardEvent<HTMLInputElement>) => {
+            setCapsLock(event.getModifierState("CapsLock"));
+            rest.onKeyDown?.(event);
+          },
+          onKeyUp: (event: KeyboardEvent<HTMLInputElement>) => {
+            setCapsLock(event.getModifierState("CapsLock"));
+            rest.onKeyUp?.(event);
+          },
+          onBlur: (event: FocusEvent<HTMLInputElement>) => {
+            // Ушли из поля — предупреждение снимается: оно относится к вводу,
+            // а не к состоянию клавиатуры вообще.
+            setCapsLock(false);
+            rest.onBlur?.(event);
+          },
+        }
+      : {};
+
+    const control = (
+      <TextControl
+        ref={innerRef}
+        type={visible ? "text" : "password"}
+        disabled={disabled}
+        className={className}
+        shellClassName={shellClassName}
+        trailing={
+          <button
+            type="button"
+            disabled={disabled}
+            aria-pressed={visible}
+            aria-label={toggleLabel ?? messages.passwordInput.toggle}
+            onClick={() => {
+              const el = innerRef.current;
+              caret.current = el ? [el.selectionStart ?? 0, el.selectionEnd ?? 0] : null;
+              setVisible((shown) => !shown);
+            }}
+            className={
+              "text-fg-3 hover:text-fg-0 flex cursor-pointer items-center rounded-xs " +
+              "transition-colors " +
+              "focus-visible:outline-accent-strong focus-visible:outline-2 focus-visible:outline-offset-2 " +
+              "disabled:pointer-events-none disabled:opacity-50"
+            }
+          >
+            {visible ? <VisibleIcon size={14} aria-hidden /> : <HiddenIcon size={14} aria-hidden />}
+          </button>
+        }
+        {...rest}
+        {...track}
+      />
+    );
+
+    if (!capsLockWarning) return control;
+
+    return (
+      <div className="flex flex-col gap-1">
+        {control}
+        {/*
+          Область объявляется ПУСТОЙ и существует всегда: живой регион,
+          появившийся в разметке вместе со своим текстом, скринридер не
+          объявляет — он обязан быть на месте до того, как текст в нём
+          возникнет. `empty:hidden` убирает её из раскладки, пока текста нет.
+        */}
+        <p role="status" className="text-fg-2 flex items-center gap-1 text-[11px] empty:hidden">
+          {capsLock ? (
+            <>
+              <WarningIcon size={12} aria-hidden />
+              {messages.passwordInput.capsLock}
+            </>
+          ) : null}
+        </p>
+      </div>
+    );
+  }
+);

package/src/components/inputs/PhoneInput.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import { forwardRef } from "react";
+import { MaskedInput, type MaskedInputProps } from "./MaskedInput.js";
+
+export interface PhoneInputProps extends Omit<MaskedInputProps, "mask"> {
+  /**
+   * Маска номера: один формат, он не подбирается по вводу. По умолчанию — российская (`RU_PHONE_MASK`).
+   *
+   * Проп есть именно потому, что умолчание — выбор, а не истина: другой стране
+   * нужен другой формат, и менять его должно быть просто.
+   */
+  mask?: string;
+}
+
+/** Российский формат. Умолчание, а не единственно возможное. */
+export const RU_PHONE_MASK = "+7 (999) 999-99-99";
+
+/**
+ * Поле телефона: `MaskedInput` с телефонной маской и телефонными атрибутами.
+ *
+ * ЧЕГО КОМПОНЕНТ НЕ ДЕЛАЕТ — важнее того, что делает. Он **не разбирает
+ * номер, не хранит справочник стран и не валидирует**. Формат один и
+ * фиксированный, задаётся пропом.
+ *
+ * Спека обещала «формат из локали», и обещание снято сознательно (ADR-0024):
+ * `Intl` телефоны не форматирует вовсе, а честный разбор — это
+ * `libphonenumber` весом в сотни килобайт, то есть peer-зависимость, которую
+ * админке без телефонов тащить не за что. Маска под один формат неверна для
+ * остальных стран, и компонент об этом говорит прямо, а не делает вид.
+ *
+ * Кит здесь ВПЕРВЫЕ знает о предметной области, и граница проведена узко:
+ * маска, `inputMode="tel"` и `autocomplete="tel"` — всё. `Form` от валидации
+ * отказался осознанно, и телефон этого не пересматривает: правила «настоящий
+ * ли это номер» остаются у того, кто его отправляет.
+ *
+ * Наружу, как и у `MaskedInput`, идут оба представления: сырые цифры для
+ * запроса и отформатированное для показа.
+ */
+export const PhoneInput = forwardRef<HTMLInputElement, PhoneInputProps>(function PhoneInput(
+  { mask = RU_PHONE_MASK, ...rest },
+  ref
+) {
+  return (
+    <MaskedInput
+      ref={ref}
+      mask={mask}
+      inputMode="tel"
+      autoComplete="tel"
+      // Спред идёт последним: и режим клавиатуры, и автозаполнение —
+      // умолчания, а не запреты.
+      {...rest}
+    />
+  );
+});