hallo-kit 0.3.0

package/src/ui/toast/toast.tsx

@@ -0,0 +1,159 @@
+'use client'
+
+import * as React from 'react'
+
+import * as ToastPrimitive from '@radix-ui/react-toast'
+import { create } from 'zustand'
+
+import { Icon } from '../Icon'
+import { cn } from '../../lib/utils'
+import {
+	type NotifyOptions,
+	type NotifyVariant,
+	registerNotifyHandler,
+} from '../../utils/notify'
+
+type IconType = React.ComponentProps<typeof Icon>['type']
+
+// Вид по варианту: soft-фон карточки + рамка в полном цвете статуса + иконка из
+// нашего набора и её цвет. Ширину рамки задаёт общий `border` на Root.
+const TOAST_VARIANT: Record<
+	NotifyVariant,
+	{ wrap: string; icon: IconType; tone: string }
+> = {
+	error: {
+		wrap: 'bg-error-soft border-error',
+		icon: 'alert',
+		tone: 'text-error',
+	},
+	success: {
+		wrap: 'bg-success-soft border-success',
+		icon: 'check_circle',
+		tone: 'text-success',
+	},
+	warning: {
+		wrap: 'bg-warning-soft border-warning',
+		icon: 'warning',
+		tone: 'text-warning',
+	},
+	info: { wrap: 'bg-secondary border-primary', icon: 'info', tone: 'text-primary' },
+}
+
+const DEFAULT_DURATION = 5000
+// Сколько держать запись после закрытия, чтобы проиграть exit-анимацию, перед тем
+// как выкинуть её из очереди.
+const REMOVE_DELAY = 200
+
+interface ToastItem {
+	id: string
+	open: boolean
+	title: string
+	description?: string
+	variant: NotifyVariant
+	duration: number
+}
+
+let idCounter = 0
+const nextId = () => `toast-${++idCounter}`
+
+// Очередь тостов на zustand. Radix управляет таймером/свайпом каждой карточки и
+// дёргает onOpenChange(false); по нему гасим open (запускает exit-анимацию) и через
+// REMOVE_DELAY убираем из очереди.
+interface ToastStore {
+	toasts: ToastItem[]
+	push: (t: Omit<ToastItem, 'id' | 'open'>) => void
+	setOpen: (id: string, open: boolean) => void
+}
+
+const useToastStore = create<ToastStore>(set => ({
+	toasts: [],
+	push: t =>
+		set(s => ({ toasts: [...s.toasts, { ...t, id: nextId(), open: true }] })),
+	setOpen: (id, open) => {
+		set(s => ({
+			toasts: s.toasts.map(x => (x.id === id ? { ...x, open } : x)),
+		}))
+		if (!open) {
+			setTimeout(() => {
+				set(s => ({ toasts: s.toasts.filter(x => x.id !== id) }))
+			}, REMOVE_DELAY)
+		}
+	},
+}))
+
+// Адаптер: notify(...) из инфраструктуры → запись в очередь.
+function showToast({
+	title,
+	description,
+	variant = 'info',
+	timeout,
+}: NotifyOptions) {
+	useToastStore.getState().push({
+		title,
+		description,
+		variant,
+		duration: timeout ?? DEFAULT_DURATION,
+	})
+}
+
+// Анимации входа/выхода и свайпа — через data-state/data-swipe (Radix) + tw-animate-css.
+const TOAST_MOTION =
+	'data-[state=open]:animate-in data-[state=open]:fade-in data-[state=open]:slide-in-from-right-full ' +
+	'data-[state=closed]:animate-out data-[state=closed]:fade-out data-[state=closed]:slide-out-to-right-full ' +
+	'data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)] data-[swipe=move]:transition-none ' +
+	'data-[swipe=cancel]:translate-x-0 data-[swipe=cancel]:transition-transform ' +
+	'data-[swipe=end]:animate-out data-[swipe=end]:slide-out-to-right-full'
+
+// Рендерит область тостов и подключает наш notify-порт. Монтируется один раз в
+// провайдерах. Radix даёт таймер автозакрытия, свайп, паузу при наведении и aria-live.
+export function Toaster() {
+	const toasts = useToastStore(s => s.toasts)
+	const setOpen = useToastStore(s => s.setOpen)
+
+	React.useEffect(() => registerNotifyHandler(showToast), [])
+
+	return (
+		<ToastPrimitive.Provider swipeDirection='right' label='Уведомление'>
+			{toasts.map(t => {
+				const v = TOAST_VARIANT[t.variant]
+				return (
+					<ToastPrimitive.Root
+						key={t.id}
+						open={t.open}
+						onOpenChange={open => setOpen(t.id, open)}
+						duration={t.duration}
+						className={cn(
+							'pointer-events-auto flex items-center gap-fl-10/12 rounded-lg border p-fl-12/16',
+							v.wrap,
+							TOAST_MOTION,
+						)}
+					>
+						{/* фикс. квадратный слот: иконки разных пропорций (warning 20×18)
+						    центрируются и не сбивают отступ текста */}
+						<span
+							className={cn(
+								'flex size-6 shrink-0 items-center justify-center',
+								v.tone,
+							)}
+						>
+							<Icon type={v.icon} isCurrentColor size={20} />
+						</span>
+						<div className='flex min-w-0 flex-col gap-0.5 text-left'>
+							<ToastPrimitive.Title className='text-body-m text-foreground'>
+								{t.title}
+							</ToastPrimitive.Title>
+							{t.description ? (
+								<ToastPrimitive.Description className='text-body-s text-muted-foreground'>
+									{t.description}
+								</ToastPrimitive.Description>
+							) : null}
+						</div>
+					</ToastPrimitive.Root>
+				)
+			})}
+			{/* fluid-ширина с потолком: плавно растёт от ширины экрана (минус поля 16px)
+			    и упирается в 25rem (400px). Без скачка на брейкпоинте; всегда у правого края. */}
+			<ToastPrimitive.Viewport className='fixed top-4 right-4 z-100 flex max-h-screen w-[min(calc(100vw_-_2rem),25rem)] flex-col gap-2 outline-none' />
+		</ToastPrimitive.Provider>
+	)
+}

package/src/utils/api/stringFormat.ts

@@ -0,0 +1,5 @@
+export const stringFormat = (template: string, ...values: string[]) =>
+	template.replace(/{(\d+)}/g, (match, index) => values[index] || '')
+
+export const stringFormatNamed = (template: string, values: Record<string, string | number>) =>
+	template.replace(/{(\w+)}/g, (_, key) => (values[key] !== undefined ? String(values[key]) : ''))

package/src/utils/clearAllCookies.ts

@@ -0,0 +1,7 @@
+export const clearAllCookies = () => {
+	document.cookie.split(';').forEach(function (c) {
+		document.cookie = c
+			.replace(/^ +/, '')
+			.replace(/=.*/, '=;expires=' + new Date().toUTCString() + ';path=/')
+	})
+}

package/src/utils/clsx.ts

@@ -0,0 +1,18 @@
+import cl, { ClassValue } from 'clsx'
+
+// Расширенный tailwind-merge (знает наши кастомные text-*-токены типографики),
+// чтобы он не путал text-button-*/text-h* с text-{color}. Источник — @/lib/utils.
+import { twMerge } from '../lib/utils'
+
+function expandTuples(inputs: ClassValue[]): ClassValue[] {
+	return inputs.map((input) => {
+		if (Array.isArray(input) && input.length === 2 && typeof input[0] === 'string') {
+			return input[1] ? input[0] : undefined
+		}
+		return input
+	})
+}
+
+export const clsx = (...inputs: ClassValue[]) => {
+	return twMerge(cl(expandTuples(inputs)))
+}

package/src/utils/confirm.ts

@@ -0,0 +1,48 @@
+// UI-агностичный порт подтверждений — «window.confirm по-нашему», асинхронный.
+// Любой код зовёт `await confirmDialog({...})` и получает Promise<boolean>; UI-слой
+// один раз регистрирует обработчик (ConfirmDialogHost с кит-модалкой) — тот же
+// паттерн, что у тостов (см. utils/notify.ts). Пока обработчик не зарегистрирован —
+// фолбэк в нативный window.confirm, чтобы ничего не падало.
+
+// Только тип (стирается при компиляции) — рантайм-агностичность порта сохраняется:
+// передаём ИМЯ иконки, а сам <Icon> строит UI-слой (ConfirmDialogHost).
+import type { IconNameType } from '../ui/Icon'
+
+export interface ConfirmOptions {
+	title: string
+	description?: string
+	/** Подпись кнопки подтверждения. По умолчанию — ui.confirm.confirm из словаря. */
+	confirmLabel?: string
+	/** Подпись кнопки отмены. По умолчанию — ui.confirm.cancel из словаря. */
+	cancelLabel?: string
+	/** Опасное действие (удаление/отвязка): красная кнопка подтверждения. */
+	danger?: boolean
+	/**
+	 * Иконка справа в кнопке подтверждения. По умолчанию — стрелка вправо
+	 * (`arrow_right`). Передай своё имя иконки, либо `null`, чтобы убрать иконку.
+	 */
+	confirmIcon?: IconNameType | null
+}
+
+export type ConfirmHandler = (options: ConfirmOptions) => Promise<boolean>
+
+let handler: ConfirmHandler | null = null
+
+/**
+ * Подключить реальный показ модалки. Возвращает функцию-отписку — удобно звать
+ * из `useEffect` в хосте.
+ */
+export const registerConfirmHandler = (next: ConfirmHandler): (() => void) => {
+	handler = next
+	return () => {
+		if (handler === next) handler = null
+	}
+}
+
+export const confirmDialog = (options: ConfirmOptions): Promise<boolean> => {
+	if (handler) return handler(options)
+
+	// Фолбэк до подключения UI-обработчика (SSR → отказ без падения).
+	if (typeof window === 'undefined') return Promise.resolve(false)
+	return Promise.resolve(window.confirm(options.title))
+}

package/src/utils/copy-to-clipboard.ts

@@ -0,0 +1,12 @@
+/**
+ * Копирует текст без необработанного Promise rejection, если браузер запретил clipboard.
+ * Возвращаем результат, чтобы вызывающий UI при необходимости мог показать уведомление.
+ */
+export async function copyToClipboard(value: string): Promise<boolean> {
+	try {
+		await navigator.clipboard.writeText(value)
+		return true
+	} catch {
+		return false
+	}
+}

package/src/utils/date/convertTimestamp.ts

@@ -0,0 +1,44 @@
+import { format as formatDate } from 'date-fns'
+
+import { dateFnsLocales } from './locales'
+
+type FormatType =
+	| 'HH:mm'
+	| 'd MMMM, yyyy'
+	| 'd MMMM, yyyy HH:mm'
+	| 'd MMMM, yyyy HH:mm:ss'
+	| 'HH:mm dd.MM.yyyy'
+	| 'dd.MM.yyyy'
+	| 'HH:mm:ss'
+	| 'd MMMM yyyy'
+	| 'd MMMM'
+
+export const convertTimestamp = (
+	timestamp: string | number | Date,
+	lang: string,
+	format?: FormatType
+): string => {
+	if (!timestamp) return ''
+
+	let date: Date
+
+	// Если timestamp — число (UNIX)
+	if (typeof timestamp === 'number') {
+		date = new Date(timestamp * 1000)
+	}
+	// Если timestamp — строка (ISO)
+	else if (typeof timestamp === 'string') {
+		date = new Date(timestamp)
+	}
+	// Если уже объект Date
+	else if (timestamp instanceof Date) {
+		date = timestamp
+	} else {
+		return ''
+	}
+
+	const locale = dateFnsLocales.find((x) => x.key === lang)
+	if (!locale) return 'Unsupported language'
+
+	return formatDate(date, format || 'd MMMM, yyyy', { locale: locale.localeFns })
+}

package/src/utils/date/formatCountdown.ts

@@ -0,0 +1,9 @@
+// Обратный отсчёт «мм:сс» для таймеров (TTL ссылки бота, повторная отправка кода).
+// padMinutes — минуты с ведущим нулём («03:44»); без — как есть («0:43»).
+export function formatCountdown(ms: number, padMinutes = false): string {
+	const totalSeconds = Math.max(0, Math.ceil(ms / 1000))
+	const minutes = Math.floor(totalSeconds / 60)
+	const seconds = totalSeconds % 60
+	const mm = padMinutes ? String(minutes).padStart(2, '0') : String(minutes)
+	return `${mm}:${String(seconds).padStart(2, '0')}`
+}

package/src/utils/date/formatDayLabel.ts

@@ -0,0 +1,50 @@
+import { convertTimestamp } from './convertTimestamp'
+
+// Подпись «разреза» между днями в ленте сообщений: «Сегодня» / «Вчера» / «23 июня»
+// (текущий год) / «23 июня 2024» (прошлые годы). Локаль и тексты сегодня/вчера — снаружи
+// (i18n): утилка про формат, не про переводы. Даты через convertTimestamp (date-fns).
+export function formatDayLabel(
+	timestamp: string | number | Date,
+	lang: string,
+	labels: { today: string; yesterday: string },
+): string {
+	if (!timestamp) return ''
+
+	// number трактуем как UNIX-секунды — так же, как convertTimestamp (×1000).
+	const date =
+		typeof timestamp === 'number'
+			? new Date(timestamp * 1000)
+			: new Date(timestamp)
+
+	// Разница в КАЛЕНДАРНЫХ днях (по началу суток), а не в 24ч — «Вчера» по дате.
+	const startOfDay = (d: Date) =>
+		new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime()
+	const now = new Date()
+	const dayDiff = Math.round(
+		(startOfDay(now) - startOfDay(date)) / 86_400_000,
+	)
+
+	if (dayDiff === 0) return labels.today
+	if (dayDiff === 1) return labels.yesterday
+
+	// Тот же год — без года; прошлые годы — с годом.
+	const format = date.getFullYear() === now.getFullYear() ? 'd MMMM' : 'd MMMM yyyy'
+	return convertTimestamp(timestamp, lang, format)
+}
+
+// Одни ли календарные сутки у двух отметок времени (для решения «показать ли разрез»).
+export const isSameCalendarDay = (
+	a?: string | number | Date | null,
+	b?: string | number | Date | null,
+): boolean => {
+	if (!a || !b) return false
+	const toDate = (v: string | number | Date) =>
+		typeof v === 'number' ? new Date(v * 1000) : new Date(v)
+	const da = toDate(a)
+	const db = toDate(b)
+	return (
+		da.getFullYear() === db.getFullYear() &&
+		da.getMonth() === db.getMonth() &&
+		da.getDate() === db.getDate()
+	)
+}

package/src/utils/date/formatRelativeDateTime.ts

@@ -0,0 +1,34 @@
+import { convertTimestamp } from './convertTimestamp'
+
+// Относительная дата+время: «Сегодня/Вчера, ЧЧ:ММ» либо «11 июня, ЧЧ:ММ» (без года).
+// Локаль + относительные подписи приходят снаружи (i18n) — утилка про формат, не про
+// тексты. Само форматирование делегируем convertTimestamp (date-fns), здесь только
+// выбор «сегодня/вчера/дата».
+export function formatRelativeDateTime(
+	timestamp: string | number | Date,
+	lang: string,
+	labels: { today: string; yesterday: string },
+): string {
+	if (!timestamp) return ''
+
+	const time = convertTimestamp(timestamp, lang, 'HH:mm')
+
+	// number трактуем как UNIX-секунды — так же, как convertTimestamp (×1000).
+	const date =
+		typeof timestamp === 'number'
+			? new Date(timestamp * 1000)
+			: new Date(timestamp)
+
+	// Разница в КАЛЕНДАРНЫХ днях (по началу суток), а не в 24ч — чтобы «Вчера»
+	// считалось по дате, а не по «минус 24 часа».
+	const startOfDay = (d: Date) =>
+		new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime()
+	const dayDiff = Math.round(
+		(startOfDay(new Date()) - startOfDay(date)) / 86_400_000,
+	)
+
+	if (dayDiff === 0) return `${labels.today}, ${time}`
+	if (dayDiff === 1) return `${labels.yesterday}, ${time}`
+
+	return `${convertTimestamp(timestamp, lang, 'd MMMM')}, ${time}`
+}

package/src/utils/date/locales.ts

@@ -0,0 +1,9 @@
+import { enUS, ru as ruDateFns } from 'date-fns/locale'
+
+// Локали date-fns, которые поддерживает кит. Ключи совпадают с KitLocale (i18n-порт).
+// Кабинет держит такой же список в @/locales/config — там он ещё несёт title для
+// переключателя языка; ките нужен только объект локали для форматирования дат.
+export const dateFnsLocales = [
+	{ key: 'ru', localeFns: ruDateFns },
+	{ key: 'en', localeFns: enUS },
+]

package/src/utils/form/validationSchema.ts

@@ -0,0 +1,46 @@
+import { FieldValues, Resolver } from 'react-hook-form'
+
+import { yupResolver } from '@hookform/resolvers/yup'
+import isEmail from 'validator/lib/isEmail'
+import isUUID from 'validator/lib/isUUID'
+import * as yup from 'yup'
+
+// Общая декларативная фабрика валидации форм (react-hook-form + yup).
+// Описываешь поля — получаешь resolver. Не плодим частные валидаторы под каждый кейс:
+//   resolver: validationSchema<FormValues>({
+//     fields: { email: { type: 'email', error: t('error.email'), required: true } },
+//   })
+// `error` — уже локализованное сообщение (одно на поле, как в trade-space).
+
+export type FieldType = 'text' | 'email' | 'uuid'
+
+export interface FieldSchema {
+	type?: FieldType
+	/** Локализованный текст ошибки поля. */
+	error: string
+	required?: boolean
+}
+
+export interface ValidationSchemaProps<T extends FieldValues> {
+	fields: Partial<Record<keyof T, FieldSchema>>
+}
+
+const buildField = ({ type = 'text', error, required }: FieldSchema): yup.StringSchema =>
+	yup
+		.string()
+		.transform((value) => (typeof value === 'string' ? value.trim() : value))
+		.test('required', error, (value) => (required ? !!value && value.length > 0 : true))
+		.test('email', error, (value) =>
+			type === 'email' && value ? isEmail(value, { require_tld: true }) : true
+		)
+		.test('uuid', error, (value) => (type === 'uuid' && value ? isUUID(value) : true))
+
+export function validationSchema<T extends FieldValues>({
+	fields,
+}: ValidationSchemaProps<T>): Resolver<T> {
+	const shape: Record<string, yup.StringSchema> = {}
+	for (const name of Object.keys(fields)) {
+		shape[name] = buildField(fields[name as keyof T] as FieldSchema)
+	}
+	return yupResolver(yup.object().shape(shape)) as unknown as Resolver<T>
+}

package/src/utils/getByKeyString.ts

@@ -0,0 +1,15 @@
+// Достаёт значение по «точечному» пути ('a.b.c') из объекта.
+export const getByKeyString = (obj: Record<string, unknown>, keyString: string) => {
+	if (!keyString) return null
+
+	const keys = keyString.split('.')
+	let result: unknown = obj
+	for (const key of keys) {
+		if (result && typeof result === 'object' && key in result) {
+			result = (result as Record<string, unknown>)[key]
+		} else {
+			return undefined
+		}
+	}
+	return result
+}

package/src/utils/getCssVar.ts

@@ -0,0 +1,2 @@
+export const getCssVar = (name: string) =>
+	getComputedStyle(document.documentElement).getPropertyValue(name).trim()

package/src/utils/getDeepType.ts

@@ -0,0 +1,3 @@
+export type DeepType = {
+	[key in string]: string | number | DeepType | DeepType[] | (<T extends string>(id: T) => string)
+}

package/src/utils/getQueryParams.ts

@@ -0,0 +1,21 @@
+export type QueryParamsProps = {
+	pageNumber?: number
+	query?: string
+}
+
+export const getQueryKeysArray = (query?: Record<string, unknown> | null) => {
+	if (!query) return []
+
+	return Object.entries(query)
+		.filter(([key, value]) => {
+			if (
+				typeof value === 'undefined' ||
+				(typeof value === 'string' && !value.length) ||
+				(key === 'sortType' && value === 0)
+			)
+				return false
+
+			return true
+		})
+		.map(([key, value]) => `${key}_${value}`)
+}

package/src/utils/inAppBrowser.ts

@@ -0,0 +1,151 @@
+import { getTelegram, getTelegramWebApp } from '../hooks/useTelegram'
+
+export type MobileOS = 'ios' | 'android' | 'other'
+
+export function getMobileOS(): MobileOS {
+	if (typeof navigator === 'undefined') return 'other'
+	const ua = navigator.userAgent || ''
+	if (/iPhone|iPad|iPod/i.test(ua)) return 'ios'
+	// iPadOS 13+ маскируется под Macintosh — отличаем по тач-поинтам.
+	if (/Macintosh/.test(ua) && (navigator.maxTouchPoints ?? 0) > 1) return 'ios'
+	if (/Android/i.test(ua)) return 'android'
+	return 'other'
+}
+
+// Встроенные браузеры приложений (webview), где ломаются вход через Google,
+// всплывающие окна оплаты, cookies и т.п. Ключ — для логов/аналитики.
+const IN_APP_PATTERNS: ReadonlyArray<readonly [string, RegExp]> = [
+	['instagram', /Instagram/i],
+	['facebook', /FBAN|FBAV|FB_IAB/i],
+	['line', /\bLine\//i],
+	['whatsapp', /WhatsApp/i],
+	['snapchat', /Snapchat/i],
+	['tiktok', /musical_ly|BytedanceWebview|TikTok/i],
+	['twitter', /Twitter/i],
+	['vk', /VKAndroidApp|VKClient/i],
+	['pinterest', /Pinterest/i],
+	['google-app', /\bGSA\//i], // приложение Google на iOS
+]
+
+export interface InAppDetection {
+	inApp: boolean
+	/** Идентификатор приложения-обёртки (для логов), либо null. */
+	app: string | null
+	os: MobileOS
+}
+
+function isStandalonePwa(): boolean {
+	if (typeof window === 'undefined') return false
+	return (
+		window.matchMedia?.('(display-mode: standalone)').matches ||
+		(window.navigator as unknown as { standalone?: boolean }).standalone === true
+	)
+}
+
+/** tgWebApp*-параметры в URL — присутствуют только при запуске как Mini App. */
+function hasTgWebAppParams(): boolean {
+	if (typeof window === 'undefined') return false
+	return /[?#&]tgWebApp(Data|Version|Platform)=/i.test(window.location.href)
+}
+
+/**
+ * Telegram Mini App — штатное окружение кабинета, его НЕ редиректим.
+ *
+ * Различать Mini App и встроенный браузер Telegram можно ТОЛЬКО по:
+ *  - `initDataUnsafe.user` (getTelegram) — заполнен только в Mini App;
+ *  - `tgWebApp*` в URL — только при запуске как Mini App.
+ *
+ * `Telegram.WebApp` и `TelegramWebviewProxy` присутствуют в ОБОИХ окружениях
+ * (в инапп-браузере SDK подгружается лоадером, а мост инжектит клиент), поэтому
+ * как признак Mini App они НЕ годятся.
+ */
+function isTelegramMiniApp(): boolean {
+	return getTelegram() !== null || hasTgWebAppParams()
+}
+
+/**
+ * Признак Telegram-окружения вообще (Mini App ИЛИ встроенный браузер Telegram):
+ * присутствует мост/SDK Telegram или «Telegram» в UA. На iOS UA встроенного
+ * браузера неотличим от Safari, поэтому ловим именно по мосту/SDK.
+ */
+function hasTelegramEnv(): boolean {
+	if (typeof window === 'undefined') return false
+	const w = window as unknown as { Telegram?: { WebApp?: unknown }; TelegramWebviewProxy?: unknown }
+	if (typeof w.TelegramWebviewProxy !== 'undefined') return true
+	if (w.Telegram?.WebApp) return true
+	return /Telegram/i.test(navigator.userAgent || '')
+}
+
+export function detectInAppBrowser(): InAppDetection {
+	const os = getMobileOS()
+	if (typeof navigator === 'undefined') return { inApp: false, app: null, os }
+
+	// Установленную PWA и реальный Mini App не трогаем — это поддерживаемые окружения.
+	if (isStandalonePwa() || isTelegramMiniApp()) return { inApp: false, app: null, os }
+
+	// Встроенный браузер Telegram: окружение Telegram есть, но это НЕ Mini App
+	// (исключён выше). Его UA на iOS равен Safari, поэтому ловим именно так.
+	if (hasTelegramEnv()) return { inApp: true, app: 'telegram', os }
+
+	const ua = navigator.userAgent || ''
+	for (const [app, re] of IN_APP_PATTERNS) {
+		if (re.test(ua)) return { inApp: true, app, os }
+	}
+
+	// Generic iOS WKWebView (встроенный в приложение): UA содержит `AppleWebKit`, но
+	// НЕ содержит `Safari`. У самого Safari и standalone Chrome/Firefox iOS токен
+	// `Safari` есть, поэтому они сюда не попадают.
+	if (os === 'ios' && /AppleWebKit/i.test(ua) && !/Safari/i.test(ua)) {
+		return { inApp: true, app: 'ios-webview', os }
+	}
+
+	// Generic Android WebView — UA содержит `; wv)`.
+	if (os === 'android' && /;\s*wv\)/.test(ua)) {
+		return { inApp: true, app: 'android-webview', os }
+	}
+
+	return { inApp: false, app: null, os }
+}
+
+/**
+ * Попытка открыть текущий URL в системном браузере.
+ * - Android Telegram: `WebApp.openLink` — клиент открывает системный браузер.
+ * - Android (прочее): `intent://` с дефолтным браузером (browser_fallback_url).
+ * - iOS: `x-safari-https://` — уводит в Safari из webview (в т.ч. инапп Telegram,
+ *   где `openLink` бесполезно открывает ещё один встроенный браузер).
+ * Возвращает true, если попытка инициирована (не гарантия успеха).
+ */
+export function tryOpenInExternalBrowser(): boolean {
+	if (typeof window === 'undefined') return false
+	const os = getMobileOS()
+	const { href, host, pathname, search, hash } = window.location
+
+	// На iOS Telegram `WebApp.openLink` открывает ссылку СНОВА во встроенном браузере —
+	// бесполезно. Внешний браузер на iOS уводит трюк `x-safari-https://` (ниже),
+	// поэтому openLink используем только на Android (там он открывает системный браузер).
+	const tgWebApp = getTelegramWebApp() as {
+		openLink?: (url: string, options?: { try_instant_view?: boolean }) => void
+	} | null
+	if (tgWebApp?.openLink && os !== 'ios') {
+		try {
+			tgWebApp.openLink(href, { try_instant_view: false })
+			return true
+		} catch {
+			// fallthrough на платформенные способы ниже.
+		}
+	}
+
+	if (os === 'android') {
+		const fallback = encodeURIComponent(href)
+		const intent = `intent://${host}${pathname}${search}${hash}#Intent;scheme=https;S.browser_fallback_url=${fallback};end`
+		window.location.href = intent
+		return true
+	}
+
+	if (os === 'ios') {
+		window.location.href = `x-safari-https://${host}${pathname}${search}${hash}`
+		return true
+	}
+
+	return false
+}