@olddevs/ui 0.0.0-stage → 4.0.1

package/src/components/inputs/FormField.tsx

@@ -0,0 +1,235 @@
+"use client";
+
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useId,
+  type ComponentPropsWithoutRef,
+  type ReactNode,
+} from "react";
+import {
+  FieldDescriptionProvider,
+  FieldInvalidProvider,
+  FieldLabelProvider,
+} from "../../hooks/useFieldDescription.js";
+import { cn } from "../../lib/cn.js";
+
+/** Раскладка поля: подпись над полем или в колонке слева. */
+export type FieldLayout = "stack" | "side";
+
+/**
+ * Ось раскладки, приходящая от `FormLayout`.
+ *
+ * @internal Провайдер ставит `FormLayout`; напрямую он потребителю не нужен —
+ * поле берёт ось у ближайшей раскладки, а явный проп её перекрывает.
+ */
+const FieldLayoutContext = createContext<FieldLayout | null>(null);
+
+/** @internal */
+export const FieldLayoutProvider = FieldLayoutContext.Provider;
+
+export interface FormFieldProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  /** Подпись над полем. */
+  label: ReactNode;
+  /**
+   * `id` поля, к которому относится подпись.
+   *
+   * Без него подпись остаётся просто текстом: клик по ней не фокусирует поле,
+   * а скринридер не называет поле её словами. Проп необязателен, потому что
+   * `id` знает только вызывающий, а придумывать его здесь через `useId` нечем —
+   * поле лежит в `children`, и подставить ему атрибут отсюда невозможно.
+   */
+  htmlFor?: string;
+  /** Пояснение под полем. */
+  hint?: ReactNode;
+  /**
+   * Сообщение об ошибке. По умолчанию заменяет `hint`; с `hintPersistent` подсказка
+   * остаётся, и ошибка встаёт под ней.
+   *
+   * Две строки под полем, одна из которых противоречит другой, — источник шума:
+   * пояснение говорит, как заполнять, ошибка — что заполнено неверно, и вместе
+   * они заставляют читать обе, чтобы понять, какая ещё действует.
+   */
+  error?: ReactNode;
+  /**
+   * Подсказка остаётся под полем и при ошибке; ошибка встаёт под ней.
+   *
+   * Для подсказки-ПРАВИЛА (формат, ограничение: «8–64 символа, цифра и
+   * буква»): прятать её ровно тогда, когда пользователь ошибся, значит отнять
+   * инструкцию в момент, когда она нужнее всего. Подсказка-пояснение («как к
+   * вам обращаться») по-прежнему заменяется ошибкой — это умолчание
+   * (ADR-0065).
+   */
+  hintPersistent?: boolean;
+  /**
+   * Отметка обязательного поля рядом с подписью.
+   *
+   * Только отметка: валидацию она не включает и не заменяет. Кит показывает
+   * состояние формы, а вычисляет его потребитель — правила обязательности это
+   * знание домена.
+   */
+  required?: boolean;
+  /**
+   * Раскладка: `stack` — подпись над полем, `side` — подпись в колонке слева.
+   *
+   * Ось живёт ЗДЕСЬ, а не в `FormLayout`, потому что подпись рисует это поле:
+   * перенести её в левую колонку снаружи невозможно — она лежит внутри
+   * собственного флекса компонента. Разбор — ADR-0025.
+   *
+   * Без пропа ось берётся у ближайшего `FormLayout`, а без него — `stack`, и
+   * разметка не меняется ни на узел.
+   */
+  layout?: FieldLayout;
+  /** Поле, к которому относится подпись. */
+  children?: ReactNode;
+}
+
+/**
+ * Подпись, поле и пояснение — одним блоком.
+ *
+ * СВЯЗЬ ПОДПИСИ С ПОЛЕМ — ЧЕРЕЗ `htmlFor`, и её стоит проставлять всегда:
+ *
+ *     <FormField label="Название" htmlFor="cat-name">
+ *       <TextControl id="cat-name" … />
+ *     </FormField>
+ *
+ * Раньше связи не было вовсе и подделывать её было нечем — отсюда прежняя
+ * докстрока «связать может только вызывающий». Это верно и сейчас: `id`
+ * по-прежнему приходит снаружи. Изменилось то, что теперь для этого есть проп,
+ * а не только совет обернуть весь блок в `<label>` на стороне вызова.
+ *
+ * ШИРИНА КОЛОНКИ ПОДПИСЕЙ — ПЕРЕМЕННАЯ `--form-label-w`, а не `subgrid`.
+ * `subgrid` выровнял бы подписи по общему треку, но требует, чтобы поле было
+ * прямым элементом внешнего грида с известным числом дорожек, — а при двух
+ * колонках и строке во всю ширину их то две, то четыре. Переменная же
+ * работает и вне `FormLayout`: поле с `layout="side"` стоит само по себе.
+ *
+ * Длинная подпись переносится ВНУТРИ своей колонки и не двигает поле — это и
+ * есть требование «не ломает соседний ряд».
+ *
+ * Прежняя версия экспортировала ещё и `inputStyle` — объект инлайн-стилей
+ * поля. Он не переносится: разбор показал ноль использований во всём фронте,
+ * то есть экспорт держался сам за себя.
+ */
+export const FormField = forwardRef<HTMLDivElement, FormFieldProps>(function FormField(
+  { label, htmlFor, hint, error, hintPersistent, required, layout, children, className, ...rest },
+  ref
+) {
+  const inherited = useContext(FieldLayoutContext);
+  const side = (layout ?? inherited ?? "stack") === "side";
+
+  /*
+    Одно сообщение — один `id`: по умолчанию под полем ровно одна строка,
+    ошибка ЗАМЕНЯЕТ подсказку. Второй `id` нужен только подсказке, которая
+    остаётся рядом с ошибкой (`hintPersistent`).
+  */
+  const messageId = useId();
+  const hintId = useId();
+  const keepHint = hintPersistent === true && error != null && Boolean(hint);
+  // `id` подписи уходит в контекст: поле, которое нельзя назвать через
+  // `<label for>` (`contenteditable`), ссылается на неё `aria-labelledby`.
+  const labelId = useId();
+
+  const message =
+    error != null ? (
+      // `role="alert"` — иначе скринридер не объявит появившуюся ошибку вовсе:
+      // она возникает после отправки, когда фокус уже не на этом поле.
+      //
+      // Роль и `aria-describedby` тут не спорят, а делят обязанности: роль
+      // объявляет ошибку В МОМЕНТ ПОЯВЛЕНИЯ, описание — при входе в поле
+      // позже. Без второго пользователь, вернувшийся к полю через Tab, не
+      // услышит, что с ним не так.
+      <div id={messageId} role="alert" className="text-danger-strong text-[11px]">
+        {error}
+      </div>
+    ) : hint ? (
+      <div id={messageId} className="text-fg-3 text-[11px]">
+        {hint}
+      </div>
+    ) : null;
+
+  /*
+    Описания нет — в контекст уходит `undefined`, и поле не получает
+    `aria-describedby` вовсе. Пустая строка или висящий `id` несуществующего
+    узла хуже отсутствия: скринридер молча пропускает ссылку в никуда, и
+    дефект не виден ни в разметке, ни в тесте.
+  */
+  const describedBy =
+    message != null ? (keepHint ? `${hintId} ${messageId}` : messageId) : undefined;
+  // Подсказка над ошибкой: её читают первой, ошибку дочитывают в конце.
+  const messages = keepHint ? (
+    <>
+      <div id={hintId} className="text-fg-3 text-[11px]">
+        {hint}
+      </div>
+      {message}
+    </>
+  ) : (
+    message
+  );
+  const invalid = error != null;
+
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        side
+          ? // Колонка подписей фиксированной ширины, поле — во всё остальное.
+            // `minmax(0,1fr)` вместо `1fr`: без него длинное значение внутри
+            // поля растягивает дорожку и выдавливает поле за пределы формы.
+            "grid grid-cols-[var(--form-label-w,12rem)_minmax(0,1fr)] items-start gap-x-4"
+          : "flex flex-col gap-1.5",
+        className
+      )}
+      {...rest}
+    >
+      <label
+        id={labelId}
+        htmlFor={htmlFor}
+        className={cn(
+          "text-fg-2 text-[11px] font-bold tracking-wide uppercase",
+          // Отступ равен верхнему отступу поля (`py-[10px]`): без него подпись
+          // висела бы над первой строкой значения, а не рядом с ней.
+          side && "pt-2.5"
+        )}
+      >
+        {label}
+        {required && (
+          // `aria-hidden`: звёздочка это визуальный сигнал, а обязательность
+          // объявляет само поле через `required`/`aria-required`. Прочитанная
+          // вслух, она превратилась бы в «звёздочка» посреди подписи.
+          <span aria-hidden className="text-danger-strong ml-0.5">
+            *
+          </span>
+        )}
+      </label>
+      {/*
+        Провайдеры не добавляют ни одного узла: разметка поля без подсказки и
+        без ошибки остаётся ровно такой же, какой была до появления описаний.
+        Единственное отличие от прежней — `id` на самой подписи.
+      */}
+      <FieldLabelProvider value={labelId}>
+        <FieldDescriptionProvider value={describedBy}>
+          <FieldInvalidProvider value={invalid}>
+            {side ? (
+              // Поле, пояснение и ошибка уезжают в ОДНУ колонку целиком, а не по
+              // ячейке на узел. Иначе второй ребёнок (диапазон «от» и «до», поле с
+              // кнопкой рядом) попадал в следующий ряд под подпись — грид
+              // раскладывает детей по ячейкам, а не по смыслу.
+              <div className="flex flex-col gap-1.5">
+                {children}
+                {messages}
+              </div>
+            ) : (
+              <>
+                {children}
+                {messages}
+              </>
+            )}
+          </FieldInvalidProvider>
+        </FieldDescriptionProvider>
+      </FieldLabelProvider>
+    </div>
+  );
+});

package/src/components/inputs/FormLayout.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import { forwardRef, type ComponentPropsWithoutRef, type CSSProperties } from "react";
+import { cn } from "../../lib/cn.js";
+import { FieldLayoutProvider } from "./FormField.js";
+
+export interface FormLayoutProps extends ComponentPropsWithoutRef<"div"> {
+  /** Число колонок. На узких экранах колонка всегда одна — это делает CSS. */
+  columns?: 1 | 2;
+  /** Где стоят подписи полей: над полем или в колонке слева. */
+  labels?: "top" | "side";
+  /**
+   * Ширина колонки подписей — любая длина CSS.
+   *
+   * Проп, а не только переменная, потому что ширина зависит от самых длинных
+   * подписей ЭТОЙ формы, а не от темы: подобрать её глобально нельзя.
+   */
+  labelWidth?: string;
+}
+
+/**
+ * Раскладка формы: колонки и место подписей.
+ *
+ * ОТВЕЧАЕТ ТОЛЬКО ЗА ПОЗИЦИЮ УЗЛОВ. Ни валидации, ни состава полей, ни
+ * состояния: `Form` отказался от собственной валидации осознанно, и раскладка
+ * этого не пересматривает. Признак нарушения границы проверяемый — проп,
+ * который влияет не на позицию узлов, а на их состав (ADR-0025).
+ *
+ * СЕТКА НА CSS, А НЕ РАСЧЁТ В JS. Одна колонка на узких экранах включается
+ * медиазапросом: раскладка, зависящая от `matchMedia`, до гидратации
+ * показывает неверную, и первый кадр формы приходится на неё.
+ *
+ * ПОДПИСИ СЛЕВА — ЭТО ОСЬ `FormField`, А НЕ ЭТОГО КОМПОНЕНТА. Раскладка лишь
+ * передаёт её контекстом: подпись рисует поле, и перенести её снаружи
+ * невозможно. Отсюда следствие, которое стоит знать заранее: `labels="side"`
+ * действует на `FormField` и молча не применяется к чужим детям — `<input>`
+ * потребителя раскладка позиционирует, но подписи у него не видит.
+ *
+ * `Fieldset` отдельным компонентом не заводится: группировка с подписью — это
+ * родные `<fieldset>` и `<legend>`, и обёртка вокруг них не добавила бы
+ * ничего, кроме имени в экспорте.
+ */
+export const FormLayout = forwardRef<HTMLDivElement, FormLayoutProps>(function FormLayout(
+  { columns = 1, labels = "top", labelWidth, className, style, ...rest },
+  ref
+) {
+  return (
+    // «Сверху» у поля называется `stack`: у раскладки это место подписи, у поля
+    // — способ сложить свои узлы. Переименовывать одно в другое хуже, чем
+    // сопоставить их в одной строке.
+    <FieldLayoutProvider value={labels === "side" ? "side" : "stack"}>
+      <div
+        ref={ref}
+        className={cn("grid gap-4", columns === 2 && "sm:grid-cols-2", className)}
+        // Свой проп сильнее чужого `style`: он именованный и явный, а
+        // переменная в `style` — способ обойти отсутствие пропа.
+        style={
+          labelWidth != null ? ({ ...style, "--form-label-w": labelWidth } as CSSProperties) : style
+        }
+        {...rest}
+      />
+    </FieldLayoutProvider>
+  );
+});
+
+export type FieldRowProps = ComponentPropsWithoutRef<"div">;
+
+/**
+ * Поле во всю ширину раскладки: адрес, длинное описание, блок кнопок.
+ *
+ * `col-span-full`, а не `col-span-2`: строка обязана занимать столько колонок,
+ * сколько их есть. Фиксированные две в одноколоночной раскладке создали бы
+ * неявную вторую колонку — форма разъехалась бы там, где ничего не меняли.
+ */
+export const FieldRow = forwardRef<HTMLDivElement, FieldRowProps>(function FieldRow(
+  { className, ...rest },
+  ref
+) {
+  return <div ref={ref} className={cn("col-span-full", className)} {...rest} />;
+});

package/src/components/inputs/InlineEdit.tsx

@@ -0,0 +1,205 @@
+"use client";
+
+import {
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ComponentPropsWithoutRef,
+  type KeyboardEvent,
+} from "react";
+import { cn } from "../../lib/cn.js";
+import { useMessages } from "../../i18n/useMessages.js";
+import { TextControl } from "./TextControl.js";
+
+export interface InlineEditProps extends Omit<
+  ComponentPropsWithoutRef<"div">,
+  "onChange" | "children" | "defaultValue"
+> {
+  /** Подтверждённое значение. Компонент его не хранит. */
+  value: string;
+  /** Подтверждение правки. Вызывается, только когда значение изменилось. */
+  onChange: (value: string) => void;
+  /**
+   * Доступное имя поля. Обязательно и проверяется компилятором: без него
+   * правка по месту даёт поле без имени ровно в момент ввода. Имя кнопки
+   * строится из значения и слова «изменить» из каталога сообщений.
+   */
+  label: string;
+  /** Режим правки. Без пропа компонент ведёт его сам. */
+  editing?: boolean;
+  /** Вызывается при входе в режим правки и выходе из него и получает новое состояние. */
+  onEditingChange?: (editing: boolean) => void;
+  /** Что показать на кнопке, когда значение пустое. */
+  placeholder?: string;
+  /** Выключает правку: кнопка-значение не открывает поле. */
+  disabled?: boolean;
+}
+
+/**
+ * Правка значения по месту: кнопка-значение → поле → подтверждение.
+ *
+ * ПОДТВЕРЖДЁННОЕ ЗНАЧЕНИЕ НЕ ХРАНИТСЯ. Внутри живёт только черновик правки — то,
+ * что набирают прямо сейчас; подтверждение уходит наружу, и следующим кадром
+ * значение приходит пропом. Компонент, хранящий подтверждённое, показывал бы
+ * своё после отказа сервера сохранить.
+ *
+ * ОТМЕНА ПО ESCAPE — ТРЕБОВАНИЕ, А НЕ УДОБСТВО. Без неё пользователь, начавший
+ * править по ошибке, не может выйти, не сохранив: щелчок мимо подтверждает,
+ * Enter подтверждает, и выхода без записи не остаётся.
+ *
+ * ФОКУС — ГЛАВНОЕ, ЧТО ЗДЕСЬ ЕСТЬ, и потому проверяется в живом браузере:
+ *
+ * - открытие ставит курсор в поле, а не оставляет его на кнопке — иначе
+ *   пользователь клавиатуры открыл поле и печатает в никуда;
+ * - Escape возвращает и значение, и фокус на кнопку;
+ * - Enter подтверждает и тоже возвращает фокус на кнопку: поле исчезает, и без
+ *   возврата фокус уезжает на `<body>`;
+ * - щелчок мимо подтверждает и фокус НЕ забирает: пользователь ушёл туда,
+ *   куда хотел.
+ *
+ * Режим правки можно вести снаружи (`editing` + `onEditingChange`) — так же,
+ * как сворачивание у `SideNav`. Без пропа компонент ведёт его сам: три строки
+ * состояния, повторённые каждым потребителем, — это не «состояние у
+ * потребителя», а переписанный компонент.
+ */
+export function InlineEdit({
+  value,
+  onChange,
+  label,
+  editing,
+  onEditingChange,
+  placeholder,
+  disabled,
+  className,
+  ...rest
+}: InlineEditProps) {
+  const messages = useMessages();
+  const [uncontrolled, setUncontrolled] = useState(false);
+  const isControlled = editing !== undefined;
+  const open = isControlled ? editing : uncontrolled;
+
+  const [draft, setDraft] = useState(value);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const fieldRef = useRef<HTMLInputElement>(null);
+  // Возврат фокуса нужен НЕ всегда: после щелчка мимо забирать фокус обратно
+  // значит уводить его оттуда, куда пользователь только что ушёл.
+  const returnFocus = useRef(false);
+  // Escape снимает режим сам, и вслед за ним не должно сработать подтверждение
+  // по потере фокуса.
+  const cancelling = useRef(false);
+
+  const setOpen = (next: boolean) => {
+    if (!isControlled) setUncontrolled(next);
+    onEditingChange?.(next);
+  };
+
+  useLayoutEffect(() => {
+    if (open) {
+      /*
+        Черновик берётся из значения на КАЖДОМ открытии, а не только в `start()`.
+
+        `start()` — обработчик кнопки, и открытие снаружи (`editing` пропом —
+        документированный сценарий: правка из меню строки) до него не доходило.
+        В поле оставался черновик с монтирования: пришедшее с сервера значение
+        не подхватывалось, а blur подтверждал устаревший текст поверх нового —
+        тихий откат. Отменённый Escape'ом текст возвращался тем же путём.
+      */
+      setDraft(value);
+      cancelling.current = false;
+      /*
+        Значение кладётся в DOM СИНХРОННО, до `select()`.
+
+        `setDraft` — это запрос на рендер, а не запись: к моменту `select()` в
+        поле ещё старый текст, и React дофлашивает новый сразу после эффекта,
+        схлопывая выделение в конец. Видно это ровно в том сценарии, ради
+        которого синхронизация и заводилась: открытие снаружи, когда значение
+        успело смениться. В обычном пути (щелчок по кнопке) `setDraft` —
+        no-op, рендера нет, и выделение случайно уцелевало.
+      */
+      if (fieldRef.current) fieldRef.current.value = value;
+      fieldRef.current?.focus();
+      fieldRef.current?.select();
+      return;
+    }
+    if (returnFocus.current) {
+      returnFocus.current = false;
+      buttonRef.current?.focus();
+    }
+    // Зависимость ТОЛЬКО `open`, и это намеренно: правка значения снаружи при
+    // уже открытой форме не должна затирать то, что пользователь набрал.
+    // Эффект стреляет на переходе режима, а не на смене значения.
+  }, [open]);
+
+  const start = () => setOpen(true);
+
+  const confirm = (withFocus: boolean) => {
+    returnFocus.current = withFocus;
+    setOpen(false);
+    if (draft !== value) onChange(draft);
+  };
+
+  const cancel = () => {
+    cancelling.current = true;
+    returnFocus.current = true;
+    setOpen(false);
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key === "Enter") {
+      event.preventDefault();
+      confirm(true);
+    }
+    if (event.key === "Escape") {
+      event.preventDefault();
+      cancel();
+    }
+  };
+
+  return (
+    <div className={cn("min-w-0", className)} {...rest}>
+      {open ? (
+        <TextControl
+          ref={fieldRef}
+          aria-label={label}
+          value={draft}
+          disabled={disabled}
+          onChange={(event) => setDraft(event.target.value)}
+          onKeyDown={handleKeyDown}
+          onBlur={() => {
+            if (cancelling.current) {
+              cancelling.current = false;
+              return;
+            }
+            confirm(false);
+          }}
+          shellClassName="w-full"
+        />
+      ) : (
+        <button
+          ref={buttonRef}
+          type="button"
+          disabled={disabled}
+          onClick={start}
+          className={
+            "text-fg-0 rounded-control hover:bg-bg-2 flex w-full cursor-pointer items-center " +
+            "px-2 py-[10px] text-left text-[13px] leading-5 transition-colors " +
+            "focus-visible:outline-accent-strong focus-visible:outline-2 focus-visible:outline-offset-2 " +
+            "disabled:cursor-not-allowed disabled:opacity-50"
+          }
+        >
+          {value === "" ? (
+            <span className="text-fg-3">{placeholder ?? messages.inlineEdit.empty}</span>
+          ) : (
+            value
+          )}
+          {/*
+            Имя кнопки строится из содержимого: значение обязано быть в имени.
+            `aria-label` вытеснил бы его, и скринридер объявлял бы «изменить
+            название», не читая того, что там написано.
+          */}
+          <span className="sr-only">, {messages.inlineEdit.edit}</span>
+        </button>
+      )}
+    </div>
+  );
+}