Фіскальний календар України

Вебкалендар із номерами ISO-тижнів, фіскальними періодами GfK, вибраними святами України, українською й англійською мовами та світлою/темною темою.

Стек: Next.js 16, React 19, TypeScript, Tailwind CSS 4, Radix UI, Zustand. Потрібен Node.js 24 LTS. Версії залежностей зафіксовані в package-lock.json. Бази даних і бізнесового API немає.

Запуск

Використайте Node 24 з .nvmrc, виконайте npm ci, потім npm run dev. Розробка без NEXT_PUBLIC_SITE_URL використовує http://localhost:3000.

Для production скопіюйте .env.example у .env.local і встановіть NEXT_PUBLIC_SITE_URL. Це HTTP(S) origin без шляху, query чи облікових даних. Відсутній або некоректний URL зупиняє production build. NEXT_PUBLIC_GA_ID необовязковий; порожнє значення вимикає Analytics.

Команди:

• npm run lint - ESLint для TypeScript/JavaScript і React hooks.
• npm run typecheck - TypeScript.
• npm test - весь unit-набір у UTC, Europe/Kyiv, America/Los_Angeles, Pacific/Kiritimati та Australia/Sydney.
• npm run test:unit - unit-набір у поточному часовому поясі.
• npm run build - іконки та production standalone-збірка.
• npx playwright install chromium firefox webkit - браузери для тестів.
• npm run test:e2e - браузерні сценарії проти standalone-збірки на 127.0.0.1:19118.
• npm start - запуск standalone із локальними static/public файлами.
• npm audit --audit-level=high - перевірка залежностей.

Для повного E2E-набору збирайте з NEXT_PUBLIC_SITE_URL=http://127.0.0.1:19118 і NEXT_PUBLIC_GA_ID=G-CALENDARTEST. Це дозволяє перевірити як підключення, так і відключення аналітики; тести блокують мережеві запити до Google. Для перевірки вже запущеного локального контейнера на цьому ж порту встановіть CALENDAR_E2E_EXTERNAL=1: тести не запускатимуть другий сервер. У CI весь браузерний набір перевіряє Docker-образ під ресурсними обмеженнями з шаблону розгортання.

Скрипт dev:clean ніколи не завершує Node-процеси. Він відмовляється працювати, якщо сервер цього проекту активний або власника next-server неможливо визначити. Видалення залишкового .next/dev/lock потребує прапорця --remove-stale-lock після зупинки старого сервера. Звичайний npm run dev залишається основним способом запуску.

Правила календаря

Домен використовує CalendarDate у форматі YYYY-MM-DD. Це цивільна дата григоріанського календаря, не timestamp. Обчислення та форматування не залежать від часового поясу пристрою. Поточний день після гідрації визначається за локальним часовим поясом браузера; сервер передає узгоджений початковий знімок.

Підтримуваний діапазон інтерфейсу: 1900-2100. ISO-тиждень починається в понеділок; перший тиждень містить 4 січня.

Правило GfK цього проекту, погоджене 18.10.2026: базовий розподіл 5-4-4, 4-5-4, 4-4-5, 5-4-4; рік починається разом з ISO week-year. Якщо між початками двох років 53 тижні, додатковий тиждень належить останньому періоду. Це зафіксована домовленість проекту, а не твердження про універсальний стандарт усіх наборів GfK/NIQ.

Свята - вибраний сучасний набір дат і розрахункові релігійні події. Він не є повним історичним календарем, переліком законодавчих вихідних чи розрахунком робочих норм. Великдень розраховується за юліанською пасхалією з поправкою на століття; Великий піст містить 48 дат.

Архітектура

• lib/date-only.ts - дата, арифметика, форматери та межа між календарем і годинником.
• lib/calendar.ts, lib/gfk-calendar.ts - чисті функції календарних періодів.
• lib/holidays.ts - свята й обмежений індекс пошуку за датою.
• lib/upcoming-holidays.ts - відлік і окремі групи періодів.
• components/calendar-clock.tsx - єдиний поточний день; перевірка кожні 15 секунд, при focus і visibilitychange.
• lib/stores, lib/storage.ts - перевірені налаштування та fallback при недоступному сховищі.
• components/calendar - відображення, сітка з клавіатурною навігацією, підказки.
• proxy.ts - CSP з окремим nonce на відповідь; next.config.ts - додаткові захисні заголовки.
• app/opengraph-image.tsx - статичний PNG з локальним ліцензованим шрифтом.
• tests/unit, tests/e2e - доменні, негативні, UI та маршрутні перевірки.

HTML формується на запит: поточний день і CSP nonce не можна кешувати на 30 днів. Початковий знімок дати однаковий у SSR та першому клієнтському render; після гідрації годинник переходить на дату браузера. Явно обраний рік не змінюється о півночі; кнопка "Сьогодні" повертає автоматичний поточний рік.

LocalStorage: fiscal-calendar-mode, fiscal-calendar-lang, fiscal-calendar-theme, holidays-panel-state, holidays-panel-hint-shown. Невідомі значення і недоступне сховище не повинні ламати сторінку. Тіло сторінки не приховується в очікуванні JS.

Доступність і дані

Кожен місяць має один Tab-вхід. Стрілки змінюють день, Home/End переходять у межах рядка, Enter/Space відкривають свято, Escape закриває підказку. Мобільна панель має назву й повернення фокуса. Приховані контролі виключені з навігації.

Google Analytics запускається лише в production за наявності ID і без Do Not Track/Global Privacy Control. Юридичні сторінки залишаються українськими та мають власний lang і canonical. Непідтверджених aggregateRating у HTML немає.

Manifest та іконки доступні для браузерів, що підтримують встановлення. Service worker і офлайн-режим не реалізовані.

Доставка

Production працює в Komodo на Contabo: стек calendar, /opt/stacks/calendar, контейнер calendar-app. Докладний процес, ресурсні межі та відкат: docs/DEPLOYMENT.md.

NEXT_PUBLIC_* вбудовуються під час build. Передача нового значення лише через docker run -e не змінює вже зібраний браузерний код. Dockerfile приймає build arguments; реліз має мати незмінний тег або digest.

GitHub workflow перевіряє код і контейнер в ізольованому hosted runner; не має production-секретів і не виконує деплой. Сам факт наявності workflow не означає, що перевірка в GitHub уже пройшла.