@olddevs/ui 0.0.0-stage → 4.0.0

package/src/components/app-shell/MobileTabBar.tsx

@@ -0,0 +1,305 @@
+"use client";
+
+import { Slot, Slottable } from "@radix-ui/react-slot";
+import {
+  forwardRef,
+  isValidElement,
+  useContext,
+  type ComponentPropsWithoutRef,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { useMessages } from "../../i18n/useMessages.js";
+import type { AccessibleName } from "../../lib/accessible-name.js";
+import { BottomBarSlotContext } from "../../lib/bottom-bar-slot.js";
+import { cn } from "../../lib/cn.js";
+import { devWarn } from "../../lib/dev-warn.js";
+import { Badge } from "../content/Badge.js";
+
+interface MobileTabBarBaseProps extends Omit<
+  ComponentPropsWithoutRef<"nav">,
+  "aria-label" | "aria-labelledby"
+> {
+  /** Пункты полосы — обычно `MobileTabBarItem`; делят ширину поровну. */
+  children: ReactNode;
+}
+
+/**
+ * Имя навигации: `aria-label` или `aria-labelledby`, но не оба (`AccessibleName`).
+ *
+ * Необязательное — `Partial`: не задано ни то ни другое, и имя берётся из
+ * каталога сообщений («Разделы»). Видимой подписи у полосы нет, поэтому и
+ * `label` нет: в ките он значит только видимую подпись.
+ */
+export type MobileTabBarProps = MobileTabBarBaseProps & Partial<AccessibleName>;
+
+/**
+ * Подложка полосы: в слоте `bottomBar` — с хвостом на высоту выреза, вне слота
+ * — ровно по полосе. Разница и есть контракт, которого jsdom иначе не увидит
+ * (`env()` он не считает), поэтому словарь, а не условие внутри строки: тест
+ * сверяет класс с ним (`docs/conventions.md`, «Что проверяют тесты»).
+ *
+ * @internal Экспорт для теста; из пакета не выходит.
+ */
+export const BACKDROP_CLASS = {
+  inSlot:
+    "bg-bg-1 absolute inset-x-0 top-0 bottom-[calc(-1*env(safe-area-inset-bottom,0px))] -z-10",
+  standalone: "bg-bg-1 absolute inset-0 -z-10",
+} as const;
+
+/**
+ * Нижняя полоса главных разделов для телефона: пункты в ряд, поровну.
+ *
+ * ЧЕГО ЗДЕСЬ НЕТ, И ЭТО РЕШЕНИЕ. Ни `fixed`, ни скрытия на `md` и шире, ни
+ * отступа под вырез экрана: всё это даёт слот `bottomBar` у `AppShell`, и
+ * полоса, повторившая любое из трёх, разошлась бы с каркасом молча — отступ
+ * под вырез, например, оказался бы двойным. Вне `AppShell` полоса — обычная
+ * строка в потоке: положить её можно куда угодно, но тогда прилипание и
+ * скрытие остаются на потребителе.
+ *
+ * ПОДЛОЖКА — токен поверхности кита, без размытия: `backdrop-filter` на
+ * каждом мобильном экране стоит перерисовки при прокрутке, а читаемость
+ * подписей ему не нужна. В слоте `bottomBar` подложка спускается ниже полосы на
+ * высоту выреза: отступ под него добавляет обёртка слота, и подложка,
+ * обрезанная по самой полосе, оставляла бы под ней прозрачную щель, сквозь
+ * которую виден уезжающий контент. Вне слота отступа нет, и подложка ровно по
+ * полосе — иначе на телефоне с вырезом она перекрыла бы то, что стоит под
+ * полосой в потоке. Где стоит полоса, говорит `BottomBarSlotContext`.
+ *
+ * Маршрутизации не знает вовсе, как и `NavItem`: адрес приходит элементом
+ * через `asChild`, текущий пункт — пропом `active` (ADR-0018).
+ */
+export const MobileTabBar = forwardRef<HTMLElement, MobileTabBarProps>(function MobileTabBar(
+  { "aria-label": ariaLabel, "aria-labelledby": labelledBy, children, className, ...rest },
+  ref
+) {
+  const messages = useMessages();
+  const inSlot = useContext(BottomBarSlotContext);
+
+  return (
+    <nav
+      ref={ref}
+      // Умолчание — только когда имени не дали никак: пустая строка не имя
+      // (`||`, а не `??`), а при `aria-labelledby` строка из каталога была бы
+      // вторым источником, который спецификация всё равно отбросит.
+      aria-label={labelledBy ? undefined : ariaLabel || messages.mobileTabBar.label}
+      aria-labelledby={labelledBy || undefined}
+      // `isolate` держит отрицательный слой подложки внутри полосы: без него
+      // подложка уходила бы под соседей по обёртке слота.
+      className={cn("relative isolate flex items-stretch justify-around", className)}
+      {...rest}
+    >
+      <div aria-hidden className={inSlot ? BACKDROP_CLASS.inSlot : BACKDROP_CLASS.standalone} />
+      {children}
+    </nav>
+  );
+});
+
+interface MobileTabBarItemBaseProps extends Omit<ComponentPropsWithoutRef<"a">, "children"> {
+  /**
+   * Подпись пункта — и его доступное имя, целиком, даже когда на экране она
+   * обрезана многоточием.
+   *
+   * Отдельным пропом, а не содержимым, по той же причине, что у `NavItem`:
+   * подпись компонент обязан завернуть сам, а содержимое при `asChild`
+   * принадлежит потомку.
+   */
+  label: ReactNode;
+  /** Иконка над подписью; скрыта от скринридера, к её углу крепится значок `badge`. */
+  icon?: ReactNode;
+  /**
+   * Текущий раздел: `aria-current="page"`.
+   *
+   * Проп, а не вычисление: кит не знает маршрутизатора и правил сравнения
+   * путей (хвостовой слэш, вложенные маршруты, локаль в префиксе). Ошибка тут
+   * выражается не падением, а тихо неподсвеченным пунктом — ADR-0018.
+   * Называется `active`, как у `NavItem`: одна и та же идея в двух пунктах
+   * навигации не должна иметь двух имён. Атрибут `aria-current` ставится от него.
+   */
+  active?: boolean;
+  /**
+   * Вывести пункт дочерним элементом: `next/link`, `<Link>` роутера. Иконка и
+   * подпись уезжают внутрь потомка через `Slottable`, поэтому потомок
+   * передаётся пустым: `<MobileTabBarItem label="…" asChild><Link href="/x" /></MobileTabBarItem>`.
+   */
+  asChild?: boolean;
+  /** Нужен только при `asChild`: там это пустой потомок-ссылка, в который уезжают иконка и подпись. */
+  children?: ReactNode;
+}
+
+/**
+ * Значок: штатный или свой.
+ *
+ * ШТАТНЫЙ — число, `true` или строка. Число показывает счётчик (больше 99 —
+ * «99+»), `true` — точку «есть новое», строка — короткую надпись в той же
+ * «таблетке» `Badge`. `0`, `false` и пустая строка — ничего: пункт без новостей
+ * не должен носить пустой кружок. Положение, предел и текст для скринридера
+ * здесь решает компонент: у вкладки значок лежит поверх иконки.
+ *
+ * СВОЙ — любой элемент (`<Badge tone="success">`, иконка), встаёт в угол
+ * иконки как есть. Тогда `badgeLabel` ОБЯЗАТЕЛЕН, и это сказано типом: значок
+ * спрятан от скринридера вместе с иконкой, и свой узел без текста звучал бы как
+ * отсутствие значка. Видимое содержимое чужого узла кит прочитать за
+ * потребителя не может — это может быть картинка.
+ */
+export type MobileTabBarItemProps = MobileTabBarItemBaseProps &
+  (
+    | {
+        /** Штатный значок: число — счётчик, `true` — точка, строка — короткая надпись; `0`, `false` и пустая строка — без значка. */
+        badge?: number | boolean | string | null;
+        /**
+         * Текст значка для скринридера вместо «Новых: 3» из каталога (или
+         * вместо самой строки), когда значку нужен смысл («3 непрочитанных
+         * сообщения»). Значок на экране остаётся тем же. Обязателен, если
+         * `badge` — свой элемент.
+         */
+        badgeLabel?: string;
+      }
+    | {
+        /** Свой значок — любой элемент; встаёт в угол иконки как есть, `badgeLabel` тогда обязателен. */
+        badge: ReactElement;
+        /**
+         * Текст значка для скринридера вместо «Новых: 3» из каталога (или
+         * вместо самой строки), когда значку нужен смысл («3 непрочитанных
+         * сообщения»). Значок на экране остаётся тем же. Обязателен, если
+         * `badge` — свой элемент.
+         */
+        badgeLabel: string;
+      }
+  );
+
+const BASE =
+  "focus-visible:outline-accent-strong text-caption relative flex min-w-0 flex-1 flex-col " +
+  "items-center gap-0.5 px-1 py-2 font-medium no-underline transition-colors " +
+  "focus-visible:outline-2";
+
+// Текущий пункт отличается не одним цветом: полоска сверху — признак, который
+// переживает и ахроматическое зрение, и принудительные цвета.
+const STATE = {
+  active:
+    "text-accent-strong before:bg-accent-strong before:absolute before:inset-x-3 " +
+    "before:top-0 before:h-0.5 before:rounded-full",
+  idle: "text-fg-2 hover:text-fg-0",
+} as const;
+
+/**
+ * Пункт нижней полосы: иконка над подписью, поверх иконки — счётчик.
+ *
+ * ПОДПИСЬ — СТУПЕНЬ `text-caption` (11px) И ОБРЕЗАЕТСЯ МНОГОТОЧИЕМ. Это
+ * измеренный компромисс, а не недосмотр: потребитель замерил, что на 360px
+ * колонка вкладки при пяти пунктах даёт 50px под подпись, а «Библиотека» и
+ * «Расписание» на 11px занимают 64–65px против 58–59px на 10px, — то есть
+ * две подписи из пяти обрезаются, и он держит у себя 10px мимо шкалы. Кит идёт
+ * по шкале; нужна ли полосе своя ступень, решит первое внедрение.
+ * Обрезка вредит глазу, но не слуху: полная подпись остаётся доступным именем.
+ */
+export const MobileTabBarItem = forwardRef<HTMLAnchorElement, MobileTabBarItemProps>(
+  function MobileTabBarItem(
+    {
+      label,
+      icon,
+      active = false,
+      badge,
+      badgeLabel,
+      asChild = false,
+      children,
+      className,
+      ...rest
+    },
+    ref
+  ) {
+    const messages = useMessages();
+    // `asChild` без элемента внутри (потребитель на JS забыл ссылку) уронил бы
+    // `Slot` и всё дерево страницы. Пункт тогда остаётся своей ссылкой: видно
+    // подпись, а не белый экран.
+    const slotted = asChild && isValidElement(children);
+    const Comp = slotted ? Slot : "a";
+
+    // `true` — точка; число больше нуля — счётчик; непустая строка — надпись в
+    // «таблетке»; элемент — свой значок; всё прочее — значка нет.
+    const dot = badge === true;
+    const count = typeof badge === "number" && badge > 0 ? badge : null;
+    const text = typeof badge === "string" && badge !== "" ? badge : null;
+    const custom = isValidElement(badge) ? badge : null;
+    const shown = dot || count != null || text != null || custom != null;
+    // Свой элемент без `badgeLabel` не пропускает тип; потребитель на JS получит
+    // значок без текста, а не падение, — и предупреждение в разработке: значок
+    // виден, но не слышен, и сам он этого не заметит.
+    if (custom && !badgeLabel) {
+      devWarn(
+        "MobileTabBarItem: a custom element was passed as `badge` without `badgeLabel`. " +
+          "The badge is hidden from screen readers together with the icon, so it is shown " +
+          "but never announced. Pass `badgeLabel` with what the badge means, e.g. " +
+          '"Needs attention".'
+      );
+    }
+    // `||`, а не `??`: пустой `badgeLabel` не текст — тогда говорит умолчание.
+    const spoken =
+      badgeLabel ||
+      (count != null
+        ? messages.mobileTabBar.newCount({ count })
+        : dot
+          ? messages.mobileTabBar.new
+          : text);
+
+    return (
+      <Comp
+        ref={ref}
+        // `page`, а не `true`: пункт ведёт на страницу, для этого случая
+        // значение и существует.
+        aria-current={active ? "page" : undefined}
+        className={cn(BASE, active ? STATE.active : STATE.idle, className)}
+        {...rest}
+      >
+        {icon ? (
+          // Иконка вместе со значком скрыта от скринридера целиком: имя даёт
+          // подпись, а значок говорит через `sr-only` ниже. Видимое число,
+          // озвученное ещё и как есть, прозвучало бы дважды.
+          <span
+            aria-hidden
+            className={cn("relative flex shrink-0", active ? "text-accent-strong" : "text-fg-2")}
+          >
+            {icon}
+            {custom ? (
+              <span className="absolute top-[-2px] -right-1.5 flex">{custom}</span>
+            ) : shown ? (
+              <Badge overlay dot={dot} className="top-[-2px] -right-1.5">
+                {count ?? text}
+              </Badge>
+            ) : null}
+          </span>
+        ) : null}
+        {/*
+          БЕЗ ИКОНКИ значку не за что зацепиться: угол пустого узла — это точка
+          над серединой подписи. Тогда значок встаёт в строку подписи, после неё,
+          и подпись обрезается раньше значка, а не наоборот.
+        */}
+        <span className="flex w-full min-w-0 items-center justify-center gap-1">
+          <span className="min-w-0 truncate text-center">{label}</span>
+          {!icon && shown ? (
+            <span aria-hidden className="flex shrink-0">
+              {custom ?? <Badge dot={dot}>{count ?? text}</Badge>}
+            </span>
+          ) : null}
+        </span>
+        {/*
+          Пробел между подписью и текстом значка — не опечатка: это соседние
+          строчные узлы, и без него вычисленное имя склеилось бы в «Входящие3».
+          В раскладке пробел между элементами флекса не виден, в имени — нужен.
+        */}
+        {shown && spoken ? (
+          <>
+            {" "}
+            <span className="sr-only">{spoken}</span>
+          </>
+        ) : null}
+        {/*
+          `Slottable` — единственный способ сохранить иконку и подпись при
+          `asChild`: Slot сливает пропы с ЕДИНСТВЕННЫМ потомком, и пара «иконка
+          + ссылка» уронила бы его в рантайме. Тот же приём — в `NavItem`.
+        */}
+        {slotted ? <Slottable>{children}</Slottable> : asChild ? null : children}
+      </Comp>
+    );
+  }
+);

package/src/components/app-shell/NavItem.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+import { Slot, Slottable } from "@radix-ui/react-slot";
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  type ComponentPropsWithoutRef,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn.js";
+import { Tooltip } from "../overlays/Tooltip.js";
+
+/**
+ * Схлопнутость навигации: её задаёт `SideNav`, а читает каждый пункт.
+ *
+ * Контекст, а не проп на пункте, потому что иначе потребитель протаскивал бы
+ * одно и то же значение в каждый из десяти пунктов руками — и однажды забыл бы
+ * в одном. Вне `SideNav` пункт считается развёрнутым: это состояние по
+ * умолчанию, а не признак ошибки.
+ */
+/** @internal Читают `NavItem` и `NavGroup`; частью публичного API не является. */
+export const NavCollapsedContext = createContext(false);
+
+/** @internal Провайдер для `SideNav`; частью публичного API не является. */
+export const NavCollapsedProvider = NavCollapsedContext.Provider;
+
+export interface NavItemProps extends Omit<ComponentPropsWithoutRef<"a">, "children"> {
+  /**
+   * Подпись пункта — и его доступное имя.
+   *
+   * Отдельным пропом, а не содержимым, и причина в схлопнутом режиме: там
+   * подпись прячется от глаз, но обязана остаться для скринридера, то есть
+   * компонент должен её ЗАВЕРНУТЬ. Содержимое при `asChild` принадлежит
+   * потомку, и завернуть его нельзя — у `Button` ровно поэтому подпись при
+   * `asChild` и не оборачивается.
+   */
+  label: ReactNode;
+  /** Иконка слева от подписи; скрыта от скринридера, цвет следует за состоянием `active`. */
+  icon?: ReactNode;
+  /**
+   * Пункт ведёт на текущую страницу: подсвечен и получает `aria-current="page"`.
+   *
+   * Проп, а не вычисление: кит не знает ни маршрутизатора, ни правил сравнения
+   * путей (хвостовой слэш, query, вложенные маршруты, локаль в префиксе). У
+   * каждого маршрутизатора они свои, а ошибка выражается не падением, а тихо
+   * неподсвеченным пунктом. Решение — ADR-0018.
+   */
+  active?: boolean;
+  /** Счётчик или отметка справа от подписи: `Badge`, число, точка. */
+  badge?: ReactNode;
+  /**
+   * Слот горячей клавиши — обычно `Kbd`. Прячется вместе с подписью: в
+   * иконочном режиме показывать сочетание некуда, а озвучивать его в имени
+   * пункта значит удлинять имя ради того, чего на экране нет.
+   */
+  shortcut?: ReactNode;
+  /**
+   * Вывести пункт дочерним элементом: `next/link`, `<Link>` роутера, что угодно
+   * ещё. Иконка и подпись уезжают внутрь потомка через `Slottable`, поэтому
+   * потомок передаётся пустым: `<NavItem label="…" asChild><Link href="/x" /></NavItem>`.
+   */
+  asChild?: boolean;
+  /** Нужен только при `asChild`: там это пустой потомок-ссылка, в который уезжают иконка и подпись. */
+  children?: ReactNode;
+}
+
+const BASE =
+  "focus-visible:outline-accent-strong flex items-center gap-3 rounded-control border " +
+  "px-3 py-[9px] text-[13px] leading-5 no-underline transition-colors " +
+  "focus-visible:outline-2 focus-visible:outline-offset-2";
+
+const STATE = {
+  active: "border-line bg-bg-3 text-fg-0 font-semibold",
+  idle: "text-fg-1 hover:bg-bg-2 hover:text-fg-0 border-transparent font-medium",
+} as const;
+
+/**
+ * Пункт навигации: иконка, подпись, счётчик и слот горячей клавиши.
+ *
+ * Маршрутизации не знает вовсе — ни адреса, ни того, какой пункт сейчас
+ * открыт. И то и другое приходит снаружи: адрес элементом через `asChild` или
+ * `href`, текущий пункт — пропом `active`.
+ *
+ * В схлопнутом режиме подпись уходит из виду, но остаётся доступным именем, а
+ * рядом появляется подсказка. Прятать её `title`-атрибутом было бы дешевле и
+ * неверно: `title` не показывается при фокусе с клавиатуры и не читается
+ * частью скринридеров.
+ *
+ * ТРЕБОВАНИЕ К ПОТРЕБИТЕЛЮ: схлопнутая навигация обязана стоять внутри
+ * `TooltipProvider` — иначе Radix бросает на первом же пункте. Провайдер здесь
+ * не разворачивается сам по той же причине, по которой его не разворачивает
+ * `Segmented`: он задаёт группировку подсказок на всё приложение, и вложенный
+ * её ломает. В развёрнутом режиме подсказки нет, и требования тоже нет.
+ */
+export const NavItem = forwardRef<HTMLAnchorElement, NavItemProps>(function NavItem(
+  { label, icon, active = false, badge, shortcut, asChild = false, children, className, ...rest },
+  ref
+) {
+  const collapsed = useContext(NavCollapsedContext);
+  const Comp = asChild ? Slot : "a";
+
+  const item = (
+    <Comp
+      ref={ref}
+      // `page`, а не `true`: пункт ведёт на страницу, и это ровно тот случай,
+      // для которого значение существует.
+      aria-current={active ? "page" : undefined}
+      className={cn(
+        BASE,
+        active ? STATE.active : STATE.idle,
+        collapsed && "justify-center px-0",
+        className
+      )}
+      {...rest}
+    >
+      {icon ? (
+        <span
+          aria-hidden
+          className={cn("flex shrink-0", active ? "text-accent-strong" : "text-fg-2")}
+        >
+          {icon}
+        </span>
+      ) : null}
+      {/*
+        В схлопнутом режиме подпись прячется классом `sr-only`, а не
+        выбрасывается из разметки: выброшенная оставила бы пункт без имени, и
+        вся навигация превратилась бы в набор безымянных иконок — тот же
+        дефект, что аудит ловит у кнопок с одной иконкой.
+      */}
+      <span className={cn(collapsed ? "sr-only" : "truncate")}>{label}</span>
+      {!collapsed && badge != null ? <span className="ml-auto flex shrink-0">{badge}</span> : null}
+      {!collapsed && shortcut != null ? (
+        <span className={cn("shrink-0", badge == null && "ml-auto")}>{shortcut}</span>
+      ) : null}
+      {/*
+        `Slottable` — единственный способ сохранить иконку и подпись при
+        `asChild`: Slot сливает пропы с ЕДИНСТВЕННЫМ потомком, и пара «иконка +
+        ссылка» уронила бы его в рантайме. С `Slottable` мишенью становится
+        она, а соседи уезжают внутрь ссылки. Тот же приём — в `Button`.
+      */}
+      {asChild ? <Slottable>{children}</Slottable> : children}
+    </Comp>
+  );
+
+  // Подсказка вешается ТОЛЬКО в схлопнутом режиме: в развёрнутом подпись видна,
+  // и подсказка повторяла бы её — шум, а не помощь.
+  return collapsed ? <Tooltip content={label}>{item}</Tooltip> : item;
+});