italia / italia/publiccode-editor
First-run onboarding wizard
- Dominant language
- TypeScript
- Stars
- 32
- Forks
- 33
- Avg merge
- 3d 15h
- Merged PRs (30d)
- 16
Description
## Context
Derived from requirement **RF-PCE-005**
## Scope
A first-time visitor lands on a long form with no explanation of what `publiccode.yml`
is for, how the left panel relates to the YAML on the right, or where to start. Add an
onboarding tutorial that runs on first launch and walks the user through using the form.
Shown once, on first launch — not on every visit.
Two things the requirement does not say, but that the feature needs to be usable:
- **A way to dismiss it.** Someone who already knows the tool should be able to leave
the tutorial immediately, at any step.
- **A way to bring it back.** Once "first launch" has passed it never returns, so a user
who dismissed it by reflex has no path back. It should be reachable again from the UI
— the settings panel is the natural place.
Worth being explicit about what "first launch" can mean here: the editor is a static SPA
with no accounts, so the only place to record it is browser storage. The tutorial will
reappear in a private window, on another device, or after the user clears site data.
That is acceptable, but it should be a deliberate choice rather than a surprise.
## Affected areas
- `src/app/App.tsx` — the root component, where the tutorial would mount over the
two-panel layout.
- `src/app/lib/store.ts` — a new persisted flag, following the existing pattern of
`useITCountrySpecific` (Zustand `persist` with `partialize`, its own storage name).
- `src/app/components/Editor.tsx` and the `Editor*.tsx` field components — whatever the
tutorial points at needs stable anchors.
- `src/app/components/SettingsPanel.tsx` — entry point for replaying the tutorial.
- `src/app/lib/utils.ts` — `useIsMobile`, since the mobile layout stacks the panels and
the tour has to make sense there too.
- `src/i18n/locales/*.json` — tutorial copy.
## Non-functional constraints
- **RNF-PCE-004 — Standards and compliance**: an overlay tour is a well-known
accessibility trap. It must be operable by keyboard alone, trap and restore focus
correctly, be dismissible with Escape, and announce step changes to assistive
technology. This has to hold jointly with #646 — a tutorial that breaks keyboard
navigation would undo that work.
- **RNF-PCE-006 — Long-term sustainability**: tutorial content describes a form that
will change, in particular through #653 and the redesign of field grouping. It needs
to be maintainable — copy in the locale files, anchors that fail loudly when the
element they point at is gone, rather than a tour that silently drifts out of date.
## Acceptance criteria
- [ ] On first launch the tutorial is shown, explaining how to fill in the form and how
the YAML preview relates to it
- [ ] It is not shown again on subsequent visits
- [ ] It can be dismissed at any step
- [ ] It can be replayed from the UI after being dismissed or completed
- [ ] Fully operable by keyboard: focus is trapped while open, restored on close, Escape
dismisses
- [ ] Step changes are announced to screen readers
- [ ] Works in the mobile stacked layout, not only on desktop
- [ ] All copy lives in the locale files and is translated in every supported language
- [ ] An anchor pointing at an element that no longer exists fails visibly rather than
silently skipping
## Related
- #646 — accessibility conformance; the tutorial must not regress it
- #647 — new locales; the tutorial copy needs to land there too
- #451 — UX of the always-visible YAML panel, which the tutorial has to explain
Contributor guide
Research direction
Start by reading src/app/App.tsx, src/app/lib/store.ts, SettingsPanel.tsx, the Editor field components, and useIsMobile in src/app/lib/utils.ts. Trace the existing persisted-flag pattern and locale files, then review the accessibility expectations in #646. Done means all acceptance criteria pass across first launch, replay, keyboard and screen-reader use, mobile layout, anchors, and every supported language.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- accessibility, frontend, internationalization, web-dev
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100