User instructions modal (issue #2885 item 3)#2891
Draft
Conversation
Addresses item 3 of issue #2885: a "how to use the site" overview for first-time users and an exercise-screen contextual help that explains the three playback steps. ## What this adds - `<InstructionsModal>` — a four-step overview ("pick a topic → open a task → run Listen/Interact/Solve → see the results") triggered from the global header on every authenticated route. Icon + label ("Как заниматься" / "How to practise") visible at every breakpoint (no icon-only mobile variant — users include seniors and 7-year-olds). - `<ExercisePlaybackHelp>` — a contextual mini-help in the fullscreen exercise overlay that only covers the three playback buttons, since the user is already past the "pick a topic" stage. Placed next to the existing close-X, mirror-positioned. - `<UiInstructionsDialog>` — shared shell built on the native <dialog> element (modeled on `ui/confirm-dialog`), which gives focus trap, ESC-to-close, and backdrop-click-to-close for free. Both modals above are thin content wrappers around this shell. - `UiExerciseButton` tooltip: replaced the old "Exercise 3" level-only title with the two new strings (`exercise_button.tooltip_available` for unlocked tasks, `exercise_button.tooltip_locked` for locked tasks) — also requested in the same issue. ## Copy decisions (domain review) - Dropped the author's "75%" threshold claim. `app/schemas/exercise.ts` `isCompleted` is binary (all tasks or nothing). Wording softened to "когда правильных ответов наберётся достаточно" so the copy survives any future backend threshold changes. - Dropped the "green check with exclamation mark" state — it does not exist in the current UI. - Confirmed Listen→Interact auto-advances and Interact→Solve is manual (matches PR #2889 behavior). ## Accessibility - `<dialog>` native element → inherent `role="dialog"`, ESC closes, backdrop visible. - `aria-modal="true"`, `aria-labelledby` pointing at an <h2> inside. - Trigger carries `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, `aria-label`. - Focus is restored to the trigger when the dialog closes. - All interactive elements meet 44×44 touch-target minimum. ## Out of scope - Auto-open on first visit — needs a server-persisted `hasSeenInstructions` flag. Devices are shared at rehab centres, so localStorage would be wrong. - Drawer/bottom-sheet mobile variant — centered modal for v1, visual follow-up possible. - Per-step icons and screenshots (asset work). - Red-exclamation icon for <75% completion (backend flag doesn't exist). - Analytics for "instructions opened". ## Tests - `instructions-modal/component-test.gjs` — trigger renders, dialog opens with the four steps, ESC/X/OK close, aria metadata correct, Russian locale renders Russian title. - `exercise-playback-help/component-test.gjs` — trigger renders, dialog opens with the playback-specific title, close dismisses it. - `ui/exercise-button-test.gjs` — tooltip switches between `exercise_button.tooltip_available` and `tooltip_locked` based on `@isAvailable`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`setupIntl` in the rendering-test env returns the `t:<key>` placeholder instead of loading real translations (same pattern documented on `doctor-feedback/component-test.gjs` and used across the existing suite). Asserting full English strings fails in CI. Switch all tooltip and title assertions to the `t:KEY` placeholder form. Drop the redundant ru-ru locale module — placeholders do not change with locale, so the test was duplicative of the en-us case. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Frontend test coverage: 72.56% (+0.16% compared to 72.4% on base) |
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the "how to use the site" feature from issue #2885 item 3:
Components
app/components/ui/instructions-dialog/index.gts<dialog>element (modeled onui/confirm-dialog). Focus trap, ESC-to-close, backdrop-click-to-close come for free.app/components/instructions-modal/index.gts<Header>between<GlobalTimer>and<XpBadge>.app/components/exercise-playback-help/index.gtstemplates/group/series/subgroup/exercise.gtsnext to the close-X.app/components/ui/exercise-button/index.gtsexercise_button.tooltip_available/tooltip_locked) based on@isAvailable.Copy accuracy
A domain reviewer walked the author's original Russian spec against the current code:
app/schemas/exercise.tsisCompletedis binary. Wording softened to "когда правильных ответов наберётся достаточно" / "when you finish a task successfully".Accessibility
<dialog>element (inherentrole="dialog", ESC closes).aria-modal,aria-labelledby→<h2>inside.aria-haspopup="dialog",aria-expanded,aria-controls,aria-label.Out of scope (follow-ups)
hasSeenInstructionsflag; shared-device rehab contexts mean localStorage is wrong).Notes
frontend/patches/exists locally with pnpm-format patch files left over from an earlier exploration. Not touched in this PR. Either keep or revert in a follow-up — current master haspatch-packageas its postinstall, so the untracked files do not affect CI.pnpm test:embercurrently fails on pristine master withCould not find module 'calculate-cache-key-for-tree'— reproducible onmasterwithout this PR's changes. CI will show whether this is a local-only issue.Test plan
🤖 Generated with Claude Code