feat(telegram): clear bottom and side safe-area insets
CI / changes (pull_request) Successful in 2s
CI / unit (pull_request) Has been skipped
CI / integration (pull_request) Has been skipped
CI / ui (pull_request) Successful in 55s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m17s

Only the device safe-area TOP inset was mirrored, so on phones with a home
indicator the rack / bottom bar sat under it, and in landscape the notch
clipped the screen edges.

Mirror the full device safe-area inset (bottom / left / right) into new
--tg-safe-bottom / --tg-safe-left / --tg-safe-right CSS vars (0 outside
Telegram) and pad the shared Screen wrapper by them, so every screen clears the
home indicator and the landscape notch; the top inset stays owned by the header.
Replace telegramSafeAreaTop with telegramSafeAreaInset (the full inset object),
with a unit test.
This commit is contained in:
Ilia Denisov
2026-06-24 10:24:56 +02:00
parent 0fb6004a8b
commit b84bd1297e
5 changed files with 43 additions and 14 deletions
+16 -8
View File
@@ -20,7 +20,7 @@ import {
telegramColorScheme,
telegramThemeParams,
telegramContentSafeAreaTop,
telegramSafeAreaTop,
telegramSafeAreaInset,
telegramDisableVerticalSwipes,
telegramHaptic,
telegramLaunch,
@@ -528,17 +528,25 @@ function syncTelegramChrome(): void {
}
/**
* syncTelegramSafeArea mirrors Telegram's content-safe-area top inset (the height its native
* nav overlays the viewport in fullscreen) into the --tg-content-top CSS var and toggles a
* `tg-fullscreen` class, so the header can drop below the nav and centre the title in its
* band. Called on launch and on Telegram's safe-area / fullscreen change events.
* syncTelegramSafeArea mirrors Telegram's safe-area insets into CSS vars: the content-safe-area top
* (the height Telegram's native nav overlays the viewport in fullscreen) into --tg-content-top
* (which also toggles the `tg-fullscreen` class so the header drops below the nav and centres the
* title in its band), and the device safe-area insets — notch / status bar (top), home indicator
* (bottom) and the landscape notch sides (left / right) — into --tg-safe-top / --tg-safe-bottom /
* --tg-safe-left / --tg-safe-right, so the header, rack and screen edges clear the device cut-outs.
* Called on launch and on Telegram's safe-area / fullscreen change events.
*/
function syncTelegramSafeArea(): void {
if (typeof document === 'undefined') return;
const root = document.documentElement;
const top = telegramContentSafeAreaTop();
document.documentElement.style.setProperty('--tg-content-top', `${top}px`);
document.documentElement.style.setProperty('--tg-safe-top', `${telegramSafeAreaTop()}px`);
document.documentElement.classList.toggle('tg-fullscreen', top > 0);
const safe = telegramSafeAreaInset();
root.style.setProperty('--tg-content-top', `${top}px`);
root.style.setProperty('--tg-safe-top', `${safe.top}px`);
root.style.setProperty('--tg-safe-bottom', `${safe.bottom}px`);
root.style.setProperty('--tg-safe-left', `${safe.left}px`);
root.style.setProperty('--tg-safe-right', `${safe.right}px`);
root.classList.toggle('tg-fullscreen', top > 0);
}
/**
+9
View File
@@ -8,6 +8,7 @@ import {
telegramLaunch,
telegramOpenExternalLink,
telegramThemeParams,
telegramSafeAreaInset,
} from './telegram';
function stubWebApp(initData: string, startParam?: string) {
@@ -51,6 +52,14 @@ describe('telegram launch detection', () => {
stubWebApp('query_id=abc');
expect(telegramThemeParams()?.bg_color).toBe('#101418');
});
it('telegramSafeAreaInset returns zeros outside Telegram and the SDK insets inside', () => {
expect(telegramSafeAreaInset()).toEqual({ top: 0, bottom: 0, left: 0, right: 0 });
vi.stubGlobal('window', {
Telegram: { WebApp: { initData: 'x', safeAreaInset: { top: 59, bottom: 34, left: 0, right: 0 } } },
});
expect(telegramSafeAreaInset()).toEqual({ top: 59, bottom: 34, left: 0, right: 0 });
});
});
describe('telegramOpenExternalLink', () => {
+8 -6
View File
@@ -274,13 +274,15 @@ export function telegramContentSafeAreaTop(): number {
}
/**
* telegramSafeAreaTop returns the device safe-area top inset (px) — the notch / status bar
* (Bot API 8.0). Telegram's own nav controls sit in the band between it and
* telegramContentSafeAreaTop, so aligning our header to that band lines it up with them. 0
* outside Telegram or on older clients.
* telegramSafeAreaInset returns the device safe-area insets (px) — the notch / status bar (top),
* the home indicator (bottom) and, in landscape, the notch sides (left / right) — from the SDK's
* safeAreaInset (Bot API 8.0). All 0 outside Telegram or on a client predating it, so callers can
* pad defensively. Telegram's own nav controls sit in the band between the top inset and
* telegramContentSafeAreaTop, so aligning our header to that band lines it up with them.
*/
export function telegramSafeAreaTop(): number {
return webApp()?.safeAreaInset?.top ?? 0;
export function telegramSafeAreaInset(): { top: number; bottom: number; left: number; right: number } {
const i = webApp()?.safeAreaInset;
return { top: i?.top ?? 0, bottom: i?.bottom ?? 0, left: i?.left ?? 0, right: i?.right ?? 0 };
}
/**