@olddevs/ui 0.0.0-stage → 4.0.0

package/src/lib/responsive.ts

@@ -0,0 +1,71 @@
+/**
+ * Значение по брейкпойнтам кита → классы Tailwind.
+ *
+ * Общий механизм для пропов вида «одно значение или своё на каждой ширине
+ * экрана»: `columns` у `Grid`, `slidesPerView` у `Carousel`. Модуль знает только
+ * брейкпойнты и правило разбора; КЛАССЫ ПРИНОСИТ КОМПОНЕНТ своим словарём.
+ *
+ * Почему словарь, а не сборка строки (`` `${bp}:grid-cols-${n}` ``): Tailwind
+ * сканирует исходники как текст и не исполняет код. Класс, склеенный в
+ * рантайме, не попадёт в CSS, и сборка при этом пройдёт без предупреждения —
+ * компонент просто окажется без раскладки. Поэтому каждый класс со своим
+ * префиксом написан в словаре компонента целиком, а здесь только выбирается.
+ *
+ * Брейкпойнты — штатные Tailwind 4, и ровно те, на которых схлопывается кит:
+ * `sm` (640) у `FormLayout`, `md` (768) у `AppShell`, `lg` (1024) у раскладок
+ * страниц. Своих значений в `styles.css` кит не задаёт, поэтому префикс здесь
+ * и медиазапрос у потребителя совпадают по построению. `base` — без префикса,
+ * то есть с нуля: отсчёт mobile-first, как у самого Tailwind.
+ *
+ * Медиазапрос, а не `matchMedia`: раскладка, зависящая от JS, до гидратации
+ * показывает неверную (ADR-0018), а класс работает с первого кадра и на сервере.
+ */
+
+/** Брейкпойнты по возрастанию ширины. Порядок важен: старший перекрывает младший. */
+export const BREAKPOINTS = ["base", "sm", "md", "lg", "xl"] as const;
+
+export type Breakpoint = (typeof BREAKPOINTS)[number];
+
+/**
+ * Одно значение на всех ширинах или своё с каждого брейкпойнта.
+ *
+ * Объект читается как в Tailwind: значение действует с указанной ширины и
+ * выше, пока его не перекроет следующий ключ. Пропущенный ключ наследует
+ * младший; пропущенный `base` значит «без класса» — что это даёт, решает
+ * компонент (у сетки — одна колонка, как у любого `display: grid`).
+ */
+export type Responsive<T extends PropertyKey> = T | Partial<Record<Breakpoint, T>>;
+
+/**
+ * Словарь компонента: для каждого брейкпойнта — класс на каждое значение.
+ *
+ * Тип требует ВСЕ брейкпойнты и ВСЕ значения: пропущенная клетка была бы
+ * значением, которое тип пропускает, а CSS не знает. Значения у `base` без
+ * префикса, у остальных — с префиксом брейкпойнта (`md:grid-cols-3`).
+ */
+export type ResponsiveClassMap<T extends PropertyKey> = Record<Breakpoint, Record<T, string>>;
+
+/**
+ * Разворачивает значение в классы по словарю.
+ *
+ * Скаляр — это `base`: без префикса класс действует на любой ширине. Пустое
+ * значение (`undefined`) даёт пустую строку, и компонент сам решает, что
+ * считать умолчанием.
+ */
+export function responsiveClasses<T extends PropertyKey>(
+  value: Responsive<T> | undefined,
+  map: ResponsiveClassMap<T>
+): string {
+  if (value == null) return "";
+  // `T` — число или строка, поэтому объект здесь однозначно «по брейкпойнтам».
+  const byBreakpoint: Partial<Record<Breakpoint, T>> =
+    typeof value === "object" ? value : { base: value };
+
+  // Значение вне словаря (потребитель на JS, без проверки типов) не даёт
+  // класса вовсе, а не строку `undefined` в разметке.
+  return BREAKPOINTS.flatMap((breakpoint) => {
+    const at = byBreakpoint[breakpoint];
+    const cls = at == null ? undefined : (map[breakpoint][at] as string | undefined);
+    return cls ? [cls] : [];
+  }).join(" ");
+}

package/src/lib/state.ts

@@ -0,0 +1,39 @@
+import type { Size } from "./variants.js";
+
+/**
+ * Раскладка «состояния экрана»: пусто и отказ.
+ *
+ * Вынесено из `EmptyState` в момент появления `ErrorState`. Геометрия у них
+ * одна и та же — вертикальная центровка, иконка, заголовок, пояснение, слот
+ * действия, — а различаются они тоном и ролью в дереве доступности. Копипаст
+ * этой таблицы разошёлся бы: у пакета уже есть такая история с полями поиска
+ * во фронте, ради которой и заведён `SearchControl`.
+ *
+ * Строки литеральные и целиком — Tailwind сканирует исходники как текст.
+ */
+export type StateSize = Extract<Size, "sm" | "md">;
+
+export const STATE_ROOT = "flex flex-col items-center justify-center text-center";
+export const STATE_ICON = "flex";
+export const STATE_TITLE = "font-semibold";
+export const STATE_DESCRIPTION = "max-w-[360px]";
+
+export const STATE_LAYOUT: Record<
+  StateSize,
+  { root: string; icon: string; title: string; description: string; action: string }
+> = {
+  sm: {
+    root: "gap-1 px-3 py-4",
+    icon: "mb-0.5",
+    title: "text-[13px]",
+    description: "text-xs",
+    action: "mt-1.5",
+  },
+  md: {
+    root: "gap-1.5 px-4 py-10",
+    icon: "mb-1",
+    title: "text-md",
+    description: "text-[13px]",
+    action: "mt-3",
+  },
+};

package/src/lib/table-state.ts

@@ -0,0 +1,264 @@
+import type { Key, SortDescriptor } from "react-aria-components";
+import type { Density } from "./variants.js";
+
+/**
+ * Контракт состояния таблицы и его перенос в адрес.
+ *
+ * Модуль намеренно БЕЗ `"use client"`: разбор адреса нужен и на сервере — в
+ * Next.js состояние восстанавливается из `searchParams` до отрисовки. Хук
+ * `useTableState` — React-обвязка поверх этих же типов.
+ */
+
+/**
+ * Применённый фильтр.
+ *
+ * У токена СВОЙ идентификатор, а не пара «поле + значение», и это не
+ * педантизм: два фильтра по одному полю дают одинаковые на вид токены, и снять
+ * нужный станет нечем. Подпись источником правды тоже не является — она
+ * локализуется и обрезается, а снимать по обрезанной подписи нельзя.
+ *
+ * Операторов здесь нет намеренно (ADR-0023, ADR-0063): без `to` токен означает
+ * равенство, с `to` — диапазон `value…to`. `gte` и `lte` — тот же диапазон с
+ * пустой границей, поэтому отдельной оси не заводится. `contains` и `in`
+ * по-прежнему ждут своего заказчика, а не догадки.
+ */
+export interface TableFilter {
+  id: string;
+  /** Поле данных. Как оно называется на сервере, решает потребитель. */
+  field: string;
+  /**
+   * Значение — или нижняя граница диапазона, если задано `to`. Для диапазона
+   * пустая строка значит «снизу не ограничено».
+   */
+  value: string;
+  /**
+   * Верхняя граница диапазона. **Не задано — токен равенства; пустая строка —
+   * диапазон без верха** («от 50»). Различие несёт сам факт наличия ключа,
+   * поэтому проверять его надо через `!== undefined`, а не по истинности.
+   * Числа и даты ходят строками: ISO-даты `ГГГГ-ММ-ДД`, как везде в ките.
+   */
+  to?: string;
+  /** Что показать в токене. Нет — потребитель покажет `field: value`. */
+  label?: string;
+}
+
+export interface TableState {
+  /** Не задана — таблица не отсортирована; ось сортировки не включается. */
+  sort?: SortDescriptor;
+  /** Нумерация с единицы: так же считает `Pagination`. */
+  page: number;
+  pageSize: number;
+  selectedKeys: Set<Key>;
+  expandedKeys: Set<Key>;
+  filters: TableFilter[];
+  /** Порядок колонок идентификаторами. Пустой — порядок объявления. */
+  columnOrder: string[];
+  hiddenColumns: Set<string>;
+  density: Density;
+}
+
+/** Умолчания состояния, кроме плотности: её даёт провайдер. */
+export const DEFAULT_TABLE_STATE: Omit<TableState, "density"> = {
+  page: 1,
+  pageSize: 25,
+  selectedKeys: new Set(),
+  expandedKeys: new Set(),
+  filters: [],
+  columnOrder: [],
+  hiddenColumns: new Set(),
+};
+
+const PARAM = {
+  sort: "sort",
+  page: "page",
+  size: "size",
+  filter: "f",
+  hidden: "hide",
+  order: "cols",
+  density: "density",
+} as const;
+
+/**
+ * Части фильтра кодируются по отдельности: `:` внутри значения не помешает.
+ *
+ * Подпись едет ЧЕТВЁРТОЙ частью. Раньше кодировались только три, и `label`
+ * терялся: `FilterBarAdd` всегда проставляет его («Раздел: Договоры»), а
+ * пользователь, скопировавший ссылку и открывший её заново, видел
+ * «section: contracts» — сырые идентификаторы бэкенда вместо человеческой
+ * подписи. Round-trip-тест этого не ловил, потому что брал фильтры без `label`.
+ *
+ * Верхняя граница диапазона едет ПЯТОЙ частью (ADR-0063). Её присутствие и
+ * есть признак диапазона, поэтому пустая пятая часть пишется, а не
+ * опускается: «от 50» иначе стало бы равенством «= 50». У равенства пятой
+ * части нет, и его адрес остался прежним.
+ */
+const encodeFilter = (f: TableFilter) => {
+  const parts = [f.id, f.field, f.value, f.label ?? ""];
+  if (f.to !== undefined) parts.push(f.to);
+  return parts.map(encodeURIComponent).join(":");
+};
+
+/**
+ * `decodeURIComponent`, не бросающий на битой escape-последовательности.
+ *
+ * `URLSearchParams` уже раскодировал параметр один раз, поэтому `%25zz`
+ * приходит сюда как `%zz` — незавершённая последовательность, на которой
+ * штатный `decodeURIComponent` бросает `URIError`. Раньше он бросал его прямо
+ * в `tableStateFromParams`, а модуль намеренно без `"use client"` и зовётся на
+ * сервере из `searchParams`: один символ `%` в ссылке давал 500 на маршруте.
+ */
+function decodeOrNull(part: string): string | null {
+  try {
+    return decodeURIComponent(part);
+  } catch {
+    return null;
+  }
+}
+
+function decodeFilter(raw: string): TableFilter | null {
+  const parts = raw.split(":");
+  // Три части — ссылка, сохранённая до волны 26: подписи там нет, и это не
+  // повод отбросить фильтр. Пять — диапазон (ADR-0063); четыре и три читаются
+  // как раньше.
+  if (parts.length < 3 || parts.length > 5) return null;
+  const decoded = parts.map(decodeOrNull);
+  // Битая часть отбраковывает фильтр целиком — так же, как это уже делает
+  // неверное число частей. Отбрасывается один токен, не весь разбор.
+  if (decoded.some((part) => part == null)) return null;
+  const [id, field, value, label, to] = decoded as [
+    string,
+    string,
+    string,
+    string | undefined,
+    string | undefined,
+  ];
+  if (!id || !field) return null;
+  const filter: TableFilter = { id, field, value };
+  if (label) filter.label = label;
+  if (to !== undefined) filter.to = to;
+  return filter;
+}
+
+/**
+ * Состояние → параметры адреса.
+ *
+ * **Умолчания не пишутся.** Иначе ссылка на первую страницу без фильтров
+ * обрастает шестью параметрами, и скопировать её человеку неудобно.
+ *
+ * **Выделение и раскрытие в адрес не идут**, хотя спека называла выделение
+ * среди состояния. Причины две: список ключей ничем не ограничен по длине, и
+ * ссылка с выделением, открытая назавтра, отмечает записи, которых уже нет.
+ * Выделение — состояние сеанса, а не адреса.
+ */
+export function tableStateToParams(state: Partial<TableState>): URLSearchParams {
+  const params = new URLSearchParams();
+
+  if (state.sort)
+    params.set(
+      PARAM.sort,
+      `${String(state.sort.column)}:${state.sort.direction === "descending" ? "desc" : "asc"}`
+    );
+
+  if (state.page != null && state.page !== DEFAULT_TABLE_STATE.page)
+    params.set(PARAM.page, String(state.page));
+
+  if (state.pageSize != null && state.pageSize !== DEFAULT_TABLE_STATE.pageSize)
+    params.set(PARAM.size, String(state.pageSize));
+
+  for (const filter of state.filters ?? []) params.append(PARAM.filter, encodeFilter(filter));
+
+  if (state.hiddenColumns?.size) params.set(PARAM.hidden, [...state.hiddenColumns].join(","));
+  if (state.columnOrder?.length) params.set(PARAM.order, state.columnOrder.join(","));
+  if (state.density && state.density !== "comfortable") params.set(PARAM.density, state.density);
+
+  return params;
+}
+
+/**
+ * Параметры адреса → состояние.
+ *
+ * Возвращает ЧАСТЬ состояния: адрес несёт не всё, и недостающее берётся из
+ * умолчаний вызывающего. Мусор не роняет разбор и не даёт сломанного
+ * состояния — адрес приходит от пользователя, а он правит его руками.
+ */
+export function tableStateFromParams(params: URLSearchParams): Partial<TableState> {
+  const state: Partial<TableState> = {};
+
+  const sort = params.get(PARAM.sort);
+  if (sort) {
+    const at = sort.lastIndexOf(":");
+    const column = at === -1 ? sort : sort.slice(0, at);
+    const direction = at === -1 ? "asc" : sort.slice(at + 1);
+    if (column)
+      state.sort = {
+        column,
+        direction: direction === "desc" ? "descending" : "ascending",
+      };
+  }
+
+  // `Number` на мусоре даёт `NaN`, а на «-3» — отрицательную страницу: обе
+  // ведут к пустому экрану, который пользователь прочтёт как «ничего нет».
+  const page = Number(params.get(PARAM.page));
+  if (Number.isInteger(page) && page > 0) state.page = page;
+
+  const size = Number(params.get(PARAM.size));
+  if (Number.isInteger(size) && size > 0) state.pageSize = size;
+
+  const filters = params
+    .getAll(PARAM.filter)
+    .map(decodeFilter)
+    .filter((f): f is TableFilter => f != null);
+  if (filters.length) state.filters = filters;
+
+  const hidden = params.get(PARAM.hidden);
+  if (hidden) state.hiddenColumns = new Set(hidden.split(",").filter(Boolean));
+
+  const order = params.get(PARAM.order);
+  if (order) state.columnOrder = order.split(",").filter(Boolean);
+
+  const density = params.get(PARAM.density);
+  if (density === "compact" || density === "comfortable") state.density = density;
+
+  return state;
+}
+
+/**
+ * Упорядочить колонки по списку идентификаторов.
+ *
+ * Список — **префикс, а не полный перечень**. Не названные в нём колонки
+ * встают следом в порядке объявления, а неизвестные идентификаторы
+ * пропускаются.
+ *
+ * Иначе порядок, пришедший из адреса, молча выбрасывал бы колонки: ссылка,
+ * сохранённая до появления новой колонки, показывала бы урезанную таблицу — и
+ * выглядело бы это как рабочая таблица, а не как ошибка. Ровно это ловится
+ * тестом; поведение общее для `DataTable` и `TablePreferences`, поэтому живёт
+ * здесь, а не двумя копиями.
+ */
+export function orderColumns<T extends { id: string }>(columns: T[], order: string[]): T[] {
+  if (order.length === 0) return columns;
+
+  const byId = new Map(columns.map((c) => [c.id, c]));
+  const listed = order.flatMap((id) => {
+    const column = byId.get(id);
+    if (!column) return [];
+    byId.delete(id);
+    return [column];
+  });
+
+  // Остаток — в порядке объявления: он и есть умолчание.
+  return [...listed, ...columns.filter((c) => byId.has(c.id))];
+}
+
+/**
+ * Отсеять скрытые колонки, не доводя таблицу до нуля.
+ *
+ * Панель настроек снять последнюю видимую не даёт, но состояние приходит и из
+ * адреса, где такой охраны нет: `?hide=` со всеми колонками давал таблицу без
+ * единого заголовка. Пустая таблица — не состояние интерфейса, а поломка,
+ * поэтому скрытие целиком игнорируется.
+ */
+export function visibleColumns<T extends { id: string }>(columns: T[], hidden: Set<string>): T[] {
+  const visible = columns.filter((c) => !hidden.has(c.id));
+  return visible.length > 0 ? visible : columns;
+}

package/src/lib/tag.ts

@@ -0,0 +1,31 @@
+/**
+ * Вид метки: одна капсула для `TagGroup` и для меток внутри `TagInput`.
+ *
+ * Вынесено в тот момент, когда метка появилась во втором месте. Пользователь
+ * должен узнавать «метку» как одно понятие, а две рукописные копии этих строк
+ * разошлись бы при первой же правке отступа — и разошлись бы молча.
+ *
+ * Строки без `` `${...}` ``: Tailwind сканирует исходники текстом, и каждый
+ * класс обязан стоять в файле целиком (`tests/class-coverage.test.ts`).
+ */
+
+/**
+ * Капсула метки.
+ *
+ * Правый отступ зависит от кнопки удаления: `data-allows-removing` ставит
+ * react-aria на метку, у которой кнопка есть. Без кнопки симметричный отступ
+ * `pr-2.5`; с кнопкой `pr-1` — иначе крестик отстоял бы от края вдвое дальше,
+ * чем подпись от левого.
+ *
+ * Кольцо фокуса акцентное и со смещением: метка стоит в потоке плотно, и кольцо
+ * вплотную съело бы соседние.
+ */
+export const TAG_CLASS =
+  "bg-bg-3 text-fg-1 flex items-center gap-1 rounded-full px-2.5 py-0.5 text-sm outline-none " +
+  "data-[allows-removing]:pr-1 " +
+  "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--accent-strong)]";
+
+/** Кнопка удаления внутри метки. */
+export const TAG_REMOVE_CLASS =
+  "text-fg-3 hover:text-fg-0 flex cursor-pointer items-center rounded-full p-0.5 outline-none " +
+  "focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[color:var(--accent-strong)]";

package/src/lib/themes.ts

@@ -0,0 +1,144 @@
+/**
+ * Реестр тем кита: какие оси существуют, как привести значение к допустимому и
+ * как применить его к документу.
+ *
+ * Зачем это в ките, а не у потребителя. Оси объявлены в `styles.css`, но наружу
+ * до 2.1.0 не отдавались — и каждый потребитель переписывал списки константами
+ * у себя. В продукте-потребителе это `["light","dark","dim"]` в одном месте
+ * и `value === "violet" ? "violet" : "blue"` в другом; второй проект написал бы
+ * их третий раз, и разошлись бы они молча. Решение — ADR-0020.
+ *
+ * Компонента переключателя здесь нет и не будет: `Segmented` уже даёт нужную
+ * форму, а кнопка завязана на хранилище и раскладку конкретного приложения.
+ * Готовый рецепт — `docs/recipes/theme-switcher.md`.
+ */
+
+/**
+ * Темы. Порядок значим ровно в одном месте — первая считается умолчанием,
+ * потому что именно она живёт в `:root` без своего атрибута.
+ */
+export const UI_THEMES = ["dark", "light", "dim"] as const;
+
+/** Акценты. `blue` — база `:root`, `violet` — оверлей `[data-accent]`. */
+export const UI_ACCENTS = ["blue", "violet"] as const;
+
+/** Бренды. `base` — отсутствие оверлея, а не оверлей с таким именем. */
+export const UI_BRANDS = ["base", "teal"] as const;
+
+export type UiTheme = (typeof UI_THEMES)[number];
+export type UiAccent = (typeof UI_ACCENTS)[number];
+export type UiBrand = (typeof UI_BRANDS)[number];
+
+export interface UiThemePrefs {
+  theme?: UiTheme;
+  accent?: UiAccent;
+  brand?: UiBrand;
+}
+
+/** Умолчания каждой оси — то состояние, в котором ни один оверлей не задан. */
+export const DEFAULT_THEME_PREFS: Required<UiThemePrefs> = {
+  theme: "dark",
+  accent: "blue",
+  brand: "base",
+};
+
+/**
+ * Приведение значения к допустимому.
+ *
+ * Аргумент типизирован как `unknown` намеренно: единственный интересный вызов —
+ * из хранилища, а `localStorage` возвращает что угодно, включая строку от
+ * прошлой версии приложения. Функция, принимающая `UiTheme`, защищала бы ровно
+ * тот случай, где защита не нужна.
+ */
+function normalize<T extends string>(list: readonly T[], value: unknown, fallback: T): T {
+  return list.includes(value as T) ? (value as T) : fallback;
+}
+
+export const normalizeTheme = (value: unknown): UiTheme =>
+  normalize(UI_THEMES, value, DEFAULT_THEME_PREFS.theme);
+
+export const normalizeAccent = (value: unknown): UiAccent =>
+  normalize(UI_ACCENTS, value, DEFAULT_THEME_PREFS.accent);
+
+export const normalizeBrand = (value: unknown): UiBrand =>
+  normalize(UI_BRANDS, value, DEFAULT_THEME_PREFS.brand);
+
+/**
+ * Выставить оси на элементе — обычно `document.documentElement`.
+ *
+ * Применяются ВСЕ ТРИ оси, а недоданные берутся из умолчаний: функция задаёт
+ * состояние целиком, а не правит одну ось поверх неизвестного текущего.
+ * Частичное применение выглядело бы удобнее ровно до первого случая, когда
+ * бренд остался от прошлого экрана, и никто не понял почему.
+ *
+ * `base` СНИМАЕТ `data-brand`, а не пишет `data-brand="base"`: блока с таким
+ * именем в CSS нет, и оставленный атрибут выглядел бы работающим оверлеем.
+ * Тот же выбор сделан в декораторе витрины — иначе снимки и приложение
+ * расходились бы на пустом месте.
+ */
+export function applyTheme(root: HTMLElement, prefs: UiThemePrefs = {}): void {
+  root.setAttribute("data-theme", normalizeTheme(prefs.theme));
+  root.setAttribute("data-accent", normalizeAccent(prefs.accent));
+
+  const brand = normalizeBrand(prefs.brand);
+  if (brand === "base") root.removeAttribute("data-brand");
+  else root.setAttribute("data-brand", brand);
+}
+
+/**
+ * Строка скрипта, применяющего сохранённую тему ДО первой отрисовки.
+ *
+ * Возвращается строка, а не выполняется код: куда её вставить, знает фреймворк
+ * потребителя, а не кит. В Next это `<Script strategy="beforeInteractive">`, в
+ * обычном приложении — `<script>` в шаблоне. Кит остаётся
+ * фреймворк-нейтральным и при этом закрывает место, где ошибаются: без раннего
+ * применения пользователь видит вспышку чужой темы между отрисовкой и
+ * гидратацией.
+ *
+ * Кит здесь начинает отдавать исполняемый JavaScript, и это осознанное
+ * расширение его границы — разбор и цена в ADR-0020.
+ *
+ * Формат хранения: JSON-объект `{ theme, accent, brand }` по ключу
+ * `storageKey`. Пишет его потребитель, читает этот скрипт; любое поле может
+ * отсутствовать или врать — normalize отработает.
+ *
+ * Списки осей подставляются из констант выше, а не пишутся в шаблоне руками:
+ * иначе скрипт разошёлся бы с реестром — тем самым дефектом, ради которого
+ * реестр и заведён.
+ */
+/**
+ * Литерал для вставки в ТЕЛО `<script>`.
+ *
+ * `JSON.stringify` закрывает кавычки, но не `<`, а этого мало: значение
+ * попадает внутрь тега, и последовательность `</script>` закрывает его на
+ * месте — остаток кода вываливается в разметку как текст. Живого XSS здесь
+ * нет, ключ задаёт разработчик; но кит генерирует код под
+ * `dangerouslySetInnerHTML`, и защита в один символ здесь ставится по
+ * умолчанию, а не по факту нападения.
+ */
+const scriptLiteral = (value: string) => JSON.stringify(value).replace(/</g, "\\u003c");
+
+export function themeInitScript({ storageKey }: { storageKey: string }): string {
+  const t = JSON.stringify(UI_THEMES);
+  const a = JSON.stringify(UI_ACCENTS);
+  const b = JSON.stringify(UI_BRANDS);
+  const d = DEFAULT_THEME_PREFS;
+
+  //
+  // `try` обнимает ТОЛЬКО чтение и разбор — то единственное, что здесь умеет
+  // бросить: `localStorage` недоступен в приватном режиме, а в ключе может
+  // лежать что угодно от прошлой версии приложения. Общий `try` вокруг всего
+  // тела выглядел бы осторожнее, но при битом JSON не выставлял бы НИ ОДНОГО
+  // атрибута, и документ оставался бы без осей вовсе — тест поймал ровно это.
+  return (
+    `(function(){` +
+    `var r=document.documentElement,p={};` +
+    `try{p=JSON.parse(localStorage.getItem(${scriptLiteral(storageKey)})||"{}")||{}}catch(e){}` +
+    `var n=function(l,v,f){return l.indexOf(v)===-1?f:v};` +
+    `r.setAttribute("data-theme",n(${t},p.theme,${JSON.stringify(d.theme)}));` +
+    `r.setAttribute("data-accent",n(${a},p.accent,${JSON.stringify(d.accent)}));` +
+    `var b=n(${b},p.brand,${JSON.stringify(d.brand)});` +
+    `if(b==="base"){r.removeAttribute("data-brand")}else{r.setAttribute("data-brand",b)}` +
+    `})();`
+  );
+}

package/src/lib/time.ts

@@ -0,0 +1,107 @@
+/**
+ * Ручной ввод времени. Разделение на две функции не косметическое: маска
+ * работает на каждое нажатие, нормализация — только по уходу фокуса. Иначе
+ * «2» немедленно превращалось бы в «02:00» и мешало дописывать.
+ */
+
+/** Ставит двоеточие по мере ввода: `2130` → `21:30`. */
+export function maskTime(value: string): string {
+  const digits = String(value).replace(/\D/g, "").slice(0, 4);
+  if (digits.length <= 2) return digits;
+  return `${digits.slice(0, 2)}:${digits.slice(2)}`;
+}
+
+/** Доводит частичный ввод до валидного `ЧЧ:ММ`, обрезая по границам суток. */
+export function normalizeTime(value: string, fallback = "00:00"): string {
+  const digits = String(value).replace(/\D/g, "");
+  if (digits.length === 0) return fallback;
+  const h = Math.min(23, parseInt(digits.slice(0, 2), 10) || 0);
+  const m = Math.min(59, parseInt(digits.slice(2, 4) || "0", 10) || 0);
+  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}`;
+}
+
+/** Подписи периодов суток 12-часового формата. По умолчанию — латиница, как в большинстве локалей. */
+export interface TimePeriodLabels {
+  am: string;
+  pm: string;
+}
+
+const DEFAULT_PERIODS: TimePeriodLabels = { am: "AM", pm: "PM" };
+
+/** Печатает `ЧЧ:ММ` на 12-часовых часах: `14:30` → `2:30 PM`, полночь — `12:00 AM`. */
+export function formatTime12(time: string, labels: TimePeriodLabels = DEFAULT_PERIODS): string {
+  const [hh = "0", mm = "00"] = time.split(":");
+  const h = Math.min(23, parseInt(hh, 10) || 0);
+  const h12 = h % 12 === 0 ? 12 : h % 12;
+  return `${h12}:${mm.padStart(2, "0")} ${h < 12 ? labels.am : labels.pm}`;
+}
+
+/**
+ * Период в тексте после цифр: полная метка из каталога (`nachm.`) или последняя
+ * набранная буква `a`/`p` как сокращение. Метка проверяется первой, иначе буква `a` внутри
+ * чужой метки читалась бы как AM.
+ */
+function detectPeriod(text: string, labels: TimePeriodLabels): "am" | "pm" | undefined {
+  const tail = text.replace(/^.*\d/s, "").trim().toLowerCase();
+  if (tail === "") return undefined;
+  if (tail === labels.am.toLowerCase()) return "am";
+  if (tail === labels.pm.toLowerCase()) return "pm";
+  const letter = [...tail].reverse().find((c) => c === "a" || c === "p");
+  return letter === "a" ? "am" : letter === "p" ? "pm" : undefined;
+}
+
+/**
+ * Маска 12-часового ввода на каждое нажатие: `230p` → `2:30 PM`. Разряд часов
+ * определяется с конца (три цифры — `ч:мм`, четыре — `чч:мм`), поэтому набор
+ * идёт слева направо без пересчёта. Буква `a` или `p` достраивается до периода;
+ * без цифр период не ставится.
+ *
+ * `previous` — текст поля до этого нажатия. Если новый текст короче, идёт стирание: период
+ * тогда не достраивается из оставшейся буквы (иначе Backspace на `2:30 PM` возвращал бы
+ * `2:30 PM` и поле застревало), а сохраняется, только если полная метка осталась.
+ */
+export function maskTime12(
+  value: string,
+  labels: TimePeriodLabels = DEFAULT_PERIODS,
+  previous?: string
+): string {
+  const text = String(value);
+  const digits = text.replace(/\D/g, "").slice(0, 4);
+  if (digits.length === 0) return "";
+  const body = digits.length <= 2 ? digits : `${digits.slice(0, -2)}:${digits.slice(-2)}`;
+  const deleting = previous !== undefined && text.length < previous.length;
+  const tail = text.replace(/^.*\d/s, "").trim().toLowerCase();
+  const found = detectPeriod(text, labels);
+  if (deleting && tail !== labels.am.toLowerCase() && tail !== labels.pm.toLowerCase()) return body;
+  if (!found) return body;
+  return `${body} ${found === "am" ? labels.am : labels.pm}`;
+}
+
+/**
+ * Доводит 12-часовой ввод до `ЧЧ:ММ`. Если набрано 24-часовое время (часы больше
+ * двенадцати), период не учитывается. Без периода берётся период прежнего значения
+ * (`fallback`), а при его отсутствии — AM: «2:30» в поле, где стояло `15:00`, остаётся
+ * дневным.
+ */
+export function normalizeTime12(
+  value: string,
+  fallback = "00:00",
+  labels: TimePeriodLabels = DEFAULT_PERIODS
+): string {
+  const text = String(value);
+  const digits = text.replace(/\D/g, "");
+  if (digits.length === 0) return fallback;
+  const hourDigits = digits.length <= 2 ? digits : digits.slice(0, -2);
+  const rawHour = parseInt(hourDigits, 10) || 0;
+  const minutes = Math.min(59, digits.length <= 2 ? 0 : parseInt(digits.slice(-2), 10) || 0);
+  let hour: number;
+  if (rawHour > 12) {
+    hour = Math.min(23, rawHour);
+  } else {
+    const fallbackHour = parseInt(fallback.split(":")[0] ?? "0", 10) || 0;
+    const period = detectPeriod(text, labels);
+    const pm = period ? period === "pm" : fallbackHour >= 12;
+    hour = (rawHour % 12) + (pm ? 12 : 0);
+  }
+  return `${String(hour).padStart(2, "0")}:${String(minutes).padStart(2, "0")}`;
+}