italia / italia/publiccode-editor

First-run onboarding wizard

Open
#654 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.