Arnike/duty-teller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity
Files
172d145f0e871fe0161668bb08caf9fe07f01dbb
duty-teller/docs/webapp-next-refactor-audit.md
Nikolay Tatarinov fa22976e75 feat: enhance Mini App design guidelines and refactor layout components 
- Updated Mini App design guidelines to include detailed instructions on UI changes, accessibility rules, and verification processes.
- Refactored multiple components to utilize `MiniAppScreen` and `MiniAppScreenContent` for consistent layout structure across the application.
- Improved error handling in `GlobalError` and `NotFound` components by integrating new layout components for better user experience.
- Introduced new hooks for admin functionality, streamlining access checks and data loading processes.
- Enhanced documentation to reflect changes in design policies and component usage, ensuring clarity for future development.
2026-03-06 17:51:33 +03:00

4.7 KiB
Raw Blame History

Webapp-next Refactor Baseline Audit

This note captures the baseline before the phased refactor. It defines current risks, duplication hotspots, and expected behavior that must not regress.

1) Screens and boundaries

  • Home route orchestration: webapp-next/src/app/page.tsx
    • Chooses among AccessDeniedScreen, CurrentDutyView, CalendarPage.
    • Controls app visibility via appContentReady.
  • Admin route orchestration: webapp-next/src/app/admin/page.tsx
    • Thin route, but still owns shell duplication and content-ready signaling.
  • Calendar composition root: webapp-next/src/components/CalendarPage.tsx
    • Combines sticky layout, swipe, month loading, auto-refresh, settings button.
  • Current duty feature root: webapp-next/src/components/current-duty/CurrentDutyView.tsx
    • Combines data loading, error/access states, back button, and close action.
  • Admin feature state root: webapp-next/src/components/admin/useAdminPage.ts
    • Combines SDK button handling, admin access, users/duties loading, sheet state, mutation and infinite scroll concerns.

2) Telegram integration touchpoints

  • SDK/provider bootstrap:
    • webapp-next/src/components/providers/TelegramProvider.tsx
    • webapp-next/src/components/ReadyGate.tsx
    • webapp-next/src/lib/telegram-ready.ts
  • Direct control usage in feature code:
    • backButton in CurrentDutyView and useAdminPage
    • settingsButton in CalendarPage
    • closeMiniApp in CurrentDutyView
  • Haptics in feature-level handlers:
    • webapp-next/src/lib/telegram-haptic.ts

Risk: platform behavior is spread across feature components instead of a narrow platform boundary.

3) Layout and shell duplication

Repeated outer wrappers appear across route and state screens:

  • content-safe min-h-[var(--tg-viewport-stable-height,100vh)] bg-background
  • mx-auto flex w-full max-w-[var(--max-width-app)] flex-col

Known locations:

  • webapp-next/src/app/page.tsx
  • webapp-next/src/app/admin/page.tsx
  • webapp-next/src/components/CalendarPage.tsx
  • webapp-next/src/components/states/FullScreenStateShell.tsx
  • webapp-next/src/app/not-found.tsx
  • webapp-next/src/app/global-error.tsx

Risk: future safe-area or viewport fixes require multi-file edits.

4) Readiness and lifecycle coupling

appContentReady is set by multiple screens/routes:

  • page.tsx
  • admin/page.tsx
  • CalendarPage.tsx
  • CurrentDutyView.tsx

ReadyGate is route-agnostic, but signaling is currently ad hoc. Risk: race conditions or deadlock-like "hidden app" scenarios when screen states change in future refactors.

5) Async/data-loading duplication

Repeated manual patterns (abort, retries, state machine):

  • webapp-next/src/hooks/use-month-data.ts
  • webapp-next/src/components/current-duty/CurrentDutyView.tsx
  • webapp-next/src/components/admin/useAdminPage.ts

Risk: inconsistent retry/access-denied behavior and difficult maintenance.

6) Store mixing concerns

webapp-next/src/store/app-store.ts currently mixes:

  • session/platform concerns (lang, appContentReady, isAdmin)
  • calendar/domain concerns (currentMonth, pendingMonth, duties/events)
  • view concerns (currentView, selectedDay, error, accessDenied)

Risk: high coupling and larger blast radius for otherwise local changes.

7) i18n/a11y gaps to close

  • Hardcoded grid label in CalendarGrid: aria-label="Calendar".
  • Hardcoded sr-only close text in shared Sheet: "Close".
  • Mixed language access strategy (useTranslation() vs getLang()/translate()), valid for bootstrap/error boundary, but not explicitly codified in one place.

8) Telegram Mini Apps compliance checklist (baseline)

Already implemented well:

  • Dynamic theme + runtime sync.
  • Safe-area/content-safe-area usage via CSS vars and layout classes.
  • ready() gate and Telegram loader handoff.
  • Android low-performance class handling.

Needs explicit policy/consistency:

  • Vertical swipes policy for gesture-heavy screens.
  • Closing confirmation policy for stateful admin flows.
  • Main/Secondary button usage policy for primary actions.
  • Terminology alignment with current official docs: safeAreaInset, contentSafeAreaInset, fullscreen events.

9) Expected behavior (non-regression)

  • /:
    • Shows access denied screen if not allowed.
    • Opens current-duty view for startParam=duty.
    • Otherwise opens calendar.
  • /admin:
    • Denies non-admin users.
    • Loads users and duties for selected admin month.
    • Allows reassignment with visible feedback.
  • Error/fallback states:
    • not-found and global error remain full-screen and theme-safe.
  • Telegram UX:
    • Back/settings controls remain functional in Telegram context.
    • Ready handoff happens when first useful screen is visible.