hallo-kit 0.3.0

package/src/utils/index.ts

@@ -0,0 +1,28 @@
+// Утилиты кита: классы, буфер обмена, даты, платформа, валидация, порт уведомлений.
+
+export * from './api/stringFormat'
+export * from './clearAllCookies'
+export * from './clsx'
+export * from './confirm'
+export * from './copy-to-clipboard'
+export * from './date/convertTimestamp'
+export * from './date/formatCountdown'
+export * from './date/formatDayLabel'
+export * from './date/formatRelativeDateTime'
+export * from './date/locales'
+export * from './form/validationSchema'
+export * from './getByKeyString'
+export * from './getCssVar'
+export * from './getDeepType'
+export * from './getQueryParams'
+export * from './inAppBrowser'
+export * from './isRTL'
+export * from './notify'
+export * from './openExternal'
+export * from './system/getMillisecondsPeriod'
+export * from './validation/authValidators'
+export * from './validation/refCode'
+
+// cn() и определение платформы — из lib, но публикуются здесь: это тоже утилиты.
+export * from '../lib/utils'
+export * from '../lib/platform'

package/src/utils/isRTL.ts

@@ -0,0 +1,29 @@
+const rtlLocales = [
+	'ae' /* Avestan */,
+	'ar' /* 'العربية', Arabic */,
+	'arc' /* Aramaic */,
+	'bcc' /* 'بلوچی مکرانی', Southern Balochi */,
+	'bqi' /* 'بختياري', Bakthiari */,
+	'ckb' /* 'Soranî / کوردی', Sorani */,
+	'dv' /* Dhivehi */,
+	'fa' /* 'فارسی', Persian */,
+	'glk' /* 'گیلکی', Gilaki */,
+	'he' /* 'עברית', Hebrew */,
+	'ku' /* 'Kurdî / كوردی', Kurdish */,
+	'mzn' /* 'مازِرونی', Mazanderani */,
+	'nqo' /* N'Ko */,
+	'pnb' /* 'پنجابی', Western Punjabi */,
+	'ps' /* 'پښتو', Pashto, */,
+	'sd' /* 'سنڌي', Sindhi */,
+	'ug' /* 'Uyghurche / ئۇيغۇرچە', Uyghur */,
+	'ur' /* 'اردو', Urdu */,
+	'yi' /* 'ייִדיש', Yiddish */,
+]
+
+export const isRTL = (locale: string) => {
+	return rtlLocales.indexOf(locale.split('-')[0]) !== -1
+}
+
+export const getCurrentDir = (locale: string) => {
+	return isRTL(locale) ? 'rtl' : 'ltr'
+}

package/src/utils/notify.ts

@@ -0,0 +1,46 @@
+// UI-агностичная абстракция тостов/уведомлений.
+//
+// Инфраструктурный код (например, axios-interceptor в clientApi) дёргает `notify(...)`,
+// НЕ зная, какой UI-кит показывает тост. Слой UI один раз вызывает
+// `registerNotifyHandler(...)` (обычно в провайдере) и подключает реальный тост.
+// Пока обработчик не зарегистрирован — фолбэк в консоль, чтобы ничего не падало.
+
+export type NotifyVariant = 'error' | 'success' | 'info' | 'warning'
+
+export interface NotifyOptions {
+	title: string
+	description?: string
+	variant?: NotifyVariant
+	/** Время автозакрытия в мс. Интерпретация — на стороне UI-обработчика. */
+	timeout?: number
+}
+
+export type NotifyHandler = (options: NotifyOptions) => void
+
+let handler: NotifyHandler | null = null
+
+/**
+ * Подключить реальный показ тостов. Возвращает функцию-отписку — удобно звать
+ * из `useEffect` в провайдере.
+ */
+export const registerNotifyHandler = (next: NotifyHandler): (() => void) => {
+	handler = next
+	return () => {
+		if (handler === next) handler = null
+	}
+}
+
+export const notify = (options: NotifyOptions): void => {
+	if (handler) {
+		handler(options)
+		return
+	}
+
+	// Фолбэк до подключения UI-обработчика.
+	const tag = `[notify:${options.variant ?? 'info'}]`
+	if (options.variant === 'error') {
+		console.error(tag, options.title, options.description ?? '')
+	} else {
+		console.warn(tag, options.title, options.description ?? '')
+	}
+}

package/src/utils/openExternal.ts

@@ -0,0 +1,27 @@
+'use client'
+
+import { getTelegram, getTelegramWebApp } from '../hooks/useTelegram'
+
+// Открытие внешней ссылки с учётом платформы (паттерн nerp Setup.tsx):
+//  • Telegram MiniApp + http(s) — tg.openLink(): системный браузер поверх мини-аппа
+//    (window.open из WebView Telegram либо глушится, либо уводит юзера из аппа);
+//  • Telegram MiniApp + кастомная схема (happ://…) — location.href: openLink не умеет
+//    не-http схемы, а прямой переход отдаёт диплинк ОС;
+//  • обычный браузер — window.open в новой вкладке.
+// Использовать для ВСЕХ наружных переходов: ссылка оплаты, скачивание Happ, диплинки.
+export function openExternal(url?: string | null) {
+	if (!url) return
+
+	const isHttp = /^https?:\/\//i.test(url)
+	const webApp = getTelegramWebApp()
+
+	if (webApp?.openLink && isHttp) {
+		webApp.openLink(url)
+		return
+	}
+	if (getTelegram() && !isHttp) {
+		window.location.href = url
+		return
+	}
+	window.open(url, '_blank', 'noopener,noreferrer')
+}

package/src/utils/system/getMillisecondsPeriod.ts

@@ -0,0 +1,31 @@
+type PreProps = {
+	sec?: never
+	min?: never
+	hour?: never
+	day?: never
+}
+
+type SecProps = Omit<PreProps, 'sec'> & {
+	sec: number
+}
+
+type MinProps = Omit<PreProps, 'min'> & {
+	min: number
+}
+
+type HourProps = Omit<PreProps, 'hour'> & {
+	hour: number
+}
+
+type DayProps = Omit<PreProps, 'day'> & {
+	day: number
+}
+
+type Props = SecProps | MinProps | HourProps | DayProps
+
+export const getMillisecondsPeriod = ({ sec, min, hour, day }: Props) => {
+	if (sec) return 1000 * sec
+	if (min) return 1000 * 60 * min
+	if (hour) return 1000 * 60 * 60 * hour
+	if (day) return 1000 * 60 * 60 * 24 * day
+}

package/src/utils/validation/authValidators.ts

@@ -0,0 +1,23 @@
+import isEmail from 'validator/lib/isEmail'
+import isUUID from 'validator/lib/isUUID'
+
+/**
+ * Display-нормализация email: `Trim → NFC → toLowerCase`. Это форма «как ввёл
+ * пользователь», которая идёт в чек/письмо. Никакой gmail-специфики (точки,
+ * `+suffix`) — это ответственность бэка (`EmailCanonicalizer`). Фронт не должен
+ * схлопывать вариации сам: на других провайдерах (yandex и т.п.) точки в local-part
+ * — это РАЗНЫЕ ящики, и фронт не знает per-domain правил.
+ */
+export const normalizeAuthEmail = (value: string) =>
+	value.trim().normalize('NFC').toLowerCase()
+
+/** UUID-идентификатор: только trim. Регистр сохраняем (UUID-парсинг case-insensitive). */
+export const normalizeRemnaIdentifier = (value: string) => value.trim()
+
+export const isValidAuthEmail = (value: string) =>
+	isEmail(normalizeAuthEmail(value), {
+		allow_utf8_local_part: false,
+		require_tld: true,
+	})
+
+export const isValidRemnaIdentifier = (value: string) => isUUID(normalizeRemnaIdentifier(value))

package/src/utils/validation/refCode.ts

@@ -0,0 +1,30 @@
+// Реф-код из ссылки (?ref=). Правила обязаны совпадать с серверными — иначе фронт
+// отправит код, который сервер молча отбросит. Лимит длины взят из схемы хранения.
+const MAX_LENGTH = 25
+const ALLOWED_PATTERN = /^[A-Za-z0-9_-]+$/
+
+// Служебные deep-link команды бота (?start=): рефом не являются, бот обрабатывает их сам.
+const BOT_COMMAND_PREFIXES = ['link_', 'pay_stars_', 'support_']
+const BOT_COMMANDS = ['pay', 'support']
+
+const isBotStartCommand = (value: string) =>
+	BOT_COMMAND_PREFIXES.some(prefix => value.startsWith(prefix)) ||
+	BOT_COMMANDS.includes(value)
+
+/** Нормализует `?ref=` → код или `null`, если бэк такое значение всё равно не примет. */
+export const normalizeRefCode = (value: string | null | undefined): string | null => {
+	if (!value) {
+		return null
+	}
+
+	const trimmed = value.trim()
+	if (!trimmed || trimmed.length > MAX_LENGTH) {
+		return null
+	}
+
+	if (!ALLOWED_PATTERN.test(trimmed) || isBotStartCommand(trimmed)) {
+		return null
+	}
+
+	return trimmed
+}

package/styles/base.css

@@ -0,0 +1,97 @@
+/* Базовые стили: голые теги выглядят опрятно без классов.
+   Источник: hallo/client — src/app/globals.css. Файл раздаётся пакетом @hallo/kit;
+   правки вносить ЗДЕСЬ, кабинет и сайты получают их обновлением пакета. */
+
+/* ============================================================
+   Базовые стили: голые теги выглядят опрятно без классов.
+   Это лишь дефолты — в разметке можно переопределять утилитами.
+   ============================================================ */
+@layer base {
+	/* Кольцо фокуса на кнопках, табах, радио-карточках и селектах не показываем: по решению
+	   владельца продукта оно мешало — особенно на модалках, где Radix переводил фокус на
+	   первый элемент при открытии и подсвечивал таб «5 устройств» до действий пользователя.
+
+	   Селектор намеренно ТОЛЬКО :focus-visible. Текстовые поля показывают активность тем же
+	   кольцом, но вешают его иначе: Input — на обёртку через focus-within, OTP-ячейки — через
+	   обычный focus. Их это правило не задевает, иначе логин и ввод кода печатались бы вслепую.
+
+	   Гасим ring-переменные Tailwind, а не box-shadow целиком: собственные тени карточек и
+	   модалок лежат в --tw-shadow и обязаны пережить фокус.
+
+	   !important обязателен: сами кольца приходят утилитами Tailwind из слоя utilities, а он
+	   идёт ПОСЛЕ base и без important перебил бы это правило. Для important-объявлений порядок
+	   слоёв инвертирован, поэтому base с !important выигрывает (тот же приём, что ниже у
+	   компенсации скроллбара).
+
+	   Цена решения: при ходьбе по странице с клавиатуры не видно, где сейчас фокус. Сама
+	   фокусируемость и порядок обхода не тронуты — вернуть подсветку = удалить это правило. */
+	*:focus-visible {
+		outline: none !important;
+		--tw-ring-shadow: 0 0 #0000 !important;
+		--tw-ring-offset-shadow: 0 0 #0000 !important;
+	}
+
+	body {
+		background-color: var(--color-background);
+		color: var(--color-foreground);
+		font-family: var(--font-sans), Arial, Helvetica, sans-serif;
+		/* дефолтный текст — Body M */
+		@apply text-body-m;
+	}
+
+	/* Резерв места под вертикальный скроллбар — ТОЛЬКО на не-сенсорных (мышь/трекпад:
+	   классический скроллбар «съедает» ширину) и от md-ширины (≥ 48rem = 768px). Так контент
+	   не дёргается по горизонтали при появлении/исчезновении скролла. Ниже 768 (мобила, где
+	   указатель грубый или скроллбар-оверлей) резерв не нужен. Действует и в Telegram
+	   MiniApp (десктопный клиент): без резерва контент прыгает при смене страниц
+	   со скроллом/без. */
+	@media (pointer: fine) and (min-width: 48rem) {
+		html {
+			scrollbar-gutter: stable;
+		}
+
+		/* Модалки (Radix Dialog → react-remove-scroll) при открытии компенсируют
+		   «исчезнувший» скроллбар инжект-стилем body[data-scroll-locked]
+		   { margin-right: <gap>px !important }. При активном scrollbar-gutter жёлоб УЖЕ
+		   зарезервирован — компенсация лишняя и сдвигает весь контент вправо на ширину
+		   скроллбара. Глушим её: удвоенный атрибут — специфичность выше инжекта, а
+		   !important в @layer побеждает unlayered !important (порядок слоёв для
+		   important-правил инвертирован). Вне gutter-условий (мобила) компенсация
+		   нужна — там не трогаем. */
+		body[data-scroll-locked][data-scroll-locked] {
+			margin-right: 0 !important;
+			padding-right: 0 !important;
+		}
+	}
+
+	/* Сплэш первой загрузки: разметка И стили целиком живут в <AppSplashScreen/>
+	   (components/app-splash-screen.tsx) — инлайн-<style> рядом с разметкой, чтобы
+	   не зависеть от загрузки этого файла, cascade layers и HMR. */
+
+	h1,
+	h2,
+	h3,
+	h4,
+	h5,
+	h6 {
+		font-family: var(--font-display), var(--font-sans), sans-serif;
+		text-wrap: balance;
+	}
+
+	/* размер/вес/интервалы заголовков — из токенов типографики */
+	h1 {
+		@apply text-h1;
+	}
+	h2 {
+		@apply text-h2;
+	}
+	h3 {
+		@apply text-h3;
+	}
+	h4 {
+		@apply text-h4;
+	}
+	h5 {
+		@apply text-h5;
+	}
+}

package/styles/brand.css

@@ -0,0 +1,36 @@
+/* ПАЛИТРА БРЕНДА (raw). Единственный слой, который сайт переопределяет под себя:
+   продублируй эти переменные в своём globals.css ПОСЛЕ импорта кита — семантика
+   и все компоненты подхватят новые цвета сами.
+   Источник: hallo/client — src/app/globals.css. Файл раздаётся пакетом @hallo/kit;
+   правки вносить ЗДЕСЬ, кабинет и сайты получают их обновлением пакета. */
+
+:root {
+	/* ============================================================
+     ПАЛИТРА БРЕНДА (raw) — фирменные цвета с исходными названиями.
+     Используется как источник для семантического слоя ниже.
+     ============================================================ */
+	--brand-blue: #1565ff; /* Brand Blue */
+	--blue-light: #4f8cff; /* вторая точка Blue Gradient */
+	--blue-pressed: #0f57e6; /* Blue Pressed — нажатое состояние Primary-кнопки */
+	--line-strong: #7f94bf; /* Line Strong — рамка вторичной кнопки (из ref-page) */
+	--deep-navy: #061b6a; /* Deep Navy */
+	--cloud-white: #fefefe; /* Cloud White */
+	--sky-mist: #eaf2ff; /* Sky Mist */
+	--ice-blue: #dce7ff; /* Ice Blue */
+	--connection-green: #22c55e; /* Connection Green */
+	--connection-green-dark: #15803d; /* контрастный success-текст на светлом soft-фоне */
+	--green-soft: #e8f8ee; /* Green Soft */
+	--error-red: #ef4444; /* Error Red */
+	--error-red-soft: #fef2f2; /* Error Red Soft */
+	--error-red-dark: #b91c1c; /* Error Red Dark */
+	--warning-gold: #f4b740; /* Warning Gold */
+	--warning-gold-dark: #8a5a00; /* контрастный warning-текст на светлом soft-фоне */
+	--gold-soft: #fff4d6; /* Gold Soft */
+	--disabled-blue: #8ea6d8; /* Disabled Blue */
+
+	--gradient-brand: linear-gradient(
+		90deg,
+		var(--brand-blue) 0%,
+		var(--blue-light) 100%
+	);
+}

package/styles/index.css

@@ -0,0 +1,19 @@
+/* Стили дизайн-системы Hallo. Подключение в проекте:
+
+     @import 'tailwindcss';
+     @import '@hallo/kit/styles.css';
+     @source '../../node_modules/@hallo/kit/src';
+
+   Последняя строка обязательна: без неё Tailwind не сканирует классы внутри
+   пакета и половина стилей компонентов не попадёт в бандл.
+
+   Свой бренд: переопредели переменные из brand.css в своём css ПОСЛЕ этого импорта. */
+
+@import 'tw-animate-css';
+
+@import './brand.css';
+@import './semantic.css';
+@import './theme.css';
+@import './utilities.css';
+@import './base.css';
+@import './motion.css';

package/styles/motion.css

@@ -0,0 +1,207 @@
+/* Анимации: shimmer, reveal, float, signal-pulse, modal-blur + view transitions темы.
+   Уважают prefers-reduced-motion.
+   Источник: hallo/client — src/app/globals.css. Файл раздаётся пакетом @hallo/kit;
+   правки вносить ЗДЕСЬ, кабинет и сайты получают их обновлением пакета. */
+
+
+/* ── Skeleton shimmer ──────────────────────────────────────────────────────
+   Блик-полоса пробегает по заглушке слева-направо. Подключается утилитой
+   `animate-shimmer` на блике внутри Skeleton (см. components/ui/skeleton.tsx). */
+@theme {
+	--animate-shimmer: shimmer 1.6s ease-in-out infinite;
+}
+
+@keyframes shimmer {
+	0% {
+		transform: translateX(-100%);
+	}
+	100% {
+		transform: translateX(100%);
+	}
+}
+
+/* ── Появление контента ────────────────────────────────────────────────────
+   Мягкое «всплывание» блоков при монтировании: opacity + подъём на 10px.
+   GPU-friendly (только transform/opacity). Ease «out-back-lite» (0.22,1,0.36,1) —
+   быстрый старт, деликатное торможение без пружины. Всё гасится reduced-motion (ниже). */
+@keyframes reveal-up {
+	from {
+		opacity: 0;
+		transform: translateY(10px);
+	}
+	to {
+		opacity: 1;
+		transform: none;
+	}
+}
+
+/* Одиночное всплывание блока (напр. заголовок страницы). */
+@utility reveal {
+	animation: reveal-up 0.45s cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+
+/* Каскадное всплывание ПРЯМЫХ детей контейнера — каждый следующий чуть позже.
+   Вешать на grid/flex со списком карточек: сетка «собирается» лесенкой.
+   Задержка растёт до 8-го ребёнка, дальше — плато (чтобы длинные списки не тянулись). */
+@utility reveal-stagger {
+	& > * {
+		animation: reveal-up 0.5s cubic-bezier(0.22, 1, 0.36, 1) both;
+	}
+	& > *:nth-child(1) {
+		animation-delay: 0.04s;
+	}
+	& > *:nth-child(2) {
+		animation-delay: 0.1s;
+	}
+	& > *:nth-child(3) {
+		animation-delay: 0.16s;
+	}
+	& > *:nth-child(4) {
+		animation-delay: 0.22s;
+	}
+	& > *:nth-child(5) {
+		animation-delay: 0.28s;
+	}
+	& > *:nth-child(6) {
+		animation-delay: 0.34s;
+	}
+	& > *:nth-child(7) {
+		animation-delay: 0.4s;
+	}
+	& > *:nth-child(n + 8) {
+		animation-delay: 0.46s;
+	}
+}
+
+/* Медленное покачивание декоративной иллюстрации (маскот на карточках). */
+@keyframes float-slow {
+	0%,
+	100% {
+		transform: translateY(0);
+	}
+	50% {
+		transform: translateY(-6px);
+	}
+}
+@utility animate-float {
+	animation: float-slow 6s ease-in-out infinite;
+}
+
+/* Расходящаяся волна от центра («сигнал/коннект») — кольцо растёт и тает. Вешать на
+   абсолютные span'ы позади иконки (напр. галочка успеха оплаты); два span'а со сдвигом
+   animation-delay дают непрерывную пульсацию. */
+@keyframes signal-pulse {
+	0% {
+		transform: scale(0.85);
+		opacity: 0.55;
+	}
+	80%,
+	100% {
+		transform: scale(2);
+		opacity: 0;
+	}
+}
+@utility animate-signal-pulse {
+	animation: signal-pulse 1.9s cubic-bezier(0.22, 1, 0.36, 1) infinite;
+}
+
+/* Кружок-вердикт (галочка успеха/алерт): упругое появление + естественное «дыхание».
+   Две анимации в одном свойстве: pop конечный (both, с overshoot), breathe — мягкая
+   бесконечная пульсация, стартует с задержкой = длительности pop. Волны позади
+   (animate-signal-pulse) дышат в том же ритме визуально. */
+@keyframes verdict-pop {
+	from {
+		opacity: 0;
+		transform: scale(0.75);
+	}
+	to {
+		opacity: 1;
+		transform: scale(1);
+	}
+}
+@keyframes verdict-breathe {
+	0%,
+	100% {
+		transform: scale(1);
+	}
+	50% {
+		transform: scale(1.05);
+	}
+}
+@utility animate-verdict-pop {
+	animation:
+		verdict-pop 0.5s cubic-bezier(0.34, 1.56, 0.64, 1) both,
+		verdict-breathe 2.6s ease-in-out 0.5s infinite;
+}
+
+/* ── Modal blur-in ─────────────────────────────────────────────────────────
+   Появление модалки «из блюра» (blur + scale + fade) — контент проявляется, как при
+   наведении фокуса камеры. Центрирование делает флекс-обёртка (см. modal.tsx), поэтому
+   в keyframes только scale — НЕ трогаем translate, иначе анимация перебивала бы
+   центрирование и модалку уносило в угол. Выход — короче (0.2s) и с меньшим блюром,
+   чтобы текст не «мылился» дольше необходимого. */
+@keyframes modal-blur-in {
+	from {
+		opacity: 0;
+		filter: blur(12px);
+		transform: scale(0.96);
+	}
+	to {
+		opacity: 1;
+		filter: blur(0);
+		transform: scale(1);
+	}
+}
+@keyframes modal-blur-out {
+	from {
+		opacity: 1;
+		filter: blur(0);
+		transform: scale(1);
+	}
+	to {
+		opacity: 0;
+		filter: blur(8px);
+		transform: scale(0.97);
+	}
+}
+@utility modal-blur-in {
+	animation: modal-blur-in 0.35s cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+@utility modal-blur-out {
+	animation: modal-blur-out 0.2s ease-in both;
+}
+
+/* ── Reduced motion ────────────────────────────────────────────────────────
+   Уважаем системную «меньше движения»: срезаем ВСЕ анимации/переходы (tw-animate-css,
+   наши reveal/float, hover-lift) — контент сразу в финальном состоянии, без движения. */
+@media (prefers-reduced-motion: reduce) {
+	*,
+	*::before,
+	*::after {
+		animation-duration: 0.01ms !important;
+		animation-iteration-count: 1 !important;
+		transition-duration: 0.01ms !important;
+		scroll-behavior: auto !important;
+	}
+}
+
+/* Адаптивные size-классы (брейкпоинт-префиксы для responsiveSize) генерятся из
+   литералов в src/lib/responsive-sizes.keep.ts — Tailwind сканит его как обычный
+   исходник (умеет arbitrary `[…]` и варианты `data-[…]`, в отличие от @source inline). */
+
+/* ── View Transitions: смена темы ──────────────────────────────────────────
+   Тему переключаем круговым «раскрытием» из точки клика по тумблеру (см. theme-switch.tsx:
+   clip-path-анимация ::view-transition-new(root)). Дефолтный crossfade корня убираем — иначе
+   он наложится на clip-path и даст грязное подмигивание. Новый слой поверх старого (z-index),
+   старый статичен под растущим кругом нового. */
+::view-transition-old(root),
+::view-transition-new(root) {
+	animation: none;
+	mix-blend-mode: normal;
+}
+::view-transition-new(root) {
+	z-index: 1;
+}
+::view-transition-old(root) {
+	z-index: 0;
+}