tg-miniapp

Telegram Mini App — Critical Patterns

🔴 CRITICAL: Safe Area в Fullscreen

safeAreaInset может вернуть 0 при инициализации — нельзя читать один раз. Значения обновляются асинхронно. iOS и Android дают разные safe areas.

Решение — реактивный хук (файл: src/hooks/useSafeAreaInset.ts):

import { useSafeAreaInset } from "@/hooks/useSafeAreaInset";

// В компоненте:
const safeArea = useSafeAreaInset();

// Полные поля:
safeArea.top         // комбинированная safe area (systemTop + contentTop, с fallback)
safeArea.bottom      // нижний отступ
safeArea.systemTop   // высота статус-бара устройства (0 вне fullscreen)
safeArea.contentTop  // высота TG-контролов — "Закрыть", "˅", "..." (0 вне fullscreen)
safeArea.isFullscreen // true если Mini App в fullscreen

// Простое использование — paddingTop = combined safe area:
<div style={{ paddingTop: safeArea.top }}>

Минимальные fallback для fullscreen:

• iOS: top = 100px (если сумма < 80)
• Android: top = 80px (если сумма < 80)

Архитектура safe area зон (fullscreen):

┌──────────────────────────────┐
│  22:54   📶  📶  🔋          │  ← systemTop (статус-бар / notch)
│ ✕ Закрыть          ˅  ...   │  ← contentTop (TG floating controls)
│  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─   │  ← safeArea.top = systemTop + contentTop
│       App content            │

• safeAreaInset.top и contentSafeAreaInset.top — аддитивны в fullscreen
• Вне fullscreen оба = 0 (нативный TG-хидер управляет сам)

Sticky header с safe area:

// WRONG — контент просвечивает сквозь gap
<div className="sticky top-0">Header</div>

// CORRECT
<div className="sticky top-0" style={{ paddingTop: safeArea.top, background: COLORS.bg }}>
  Header
</div>

🔴 CRITICAL: Брендинг в зоне TG-контролов (fullscreen header)

В fullscreen режиме можно разместить текст/логотип между системными кнопками TG ("Закрыть" слева, "˅ + ..." справа). Это заменяет кастомный хидер и экономит место.

Паттерн — branding в TG controls zone:

const safeArea = useSafeAreaInset();

{/* Прозрачный spacer = вся safe area */}
{safeArea.top > 0 && (
  <div className="shrink-0 relative" style={{ height: safeArea.top }}>
    {/* Текст позиционирован точно в зоне TG-контролов */}
    {safeArea.isFullscreen && safeArea.contentTop > 0 && (
      <div
        className="absolute left-0 right-0 flex items-center justify-center pointer-events-none"
        style={{
          top: safeArea.systemTop,
          height: safeArea.contentTop,
        }}
      >
        <span
          className="text-[15px] font-bold tracking-[0.08em] uppercase"
          style={{ color: "rgba(228,228,240,0.55)" }}
        >
          MyApp
        </span>
      </div>
    )}
  </div>
)}