airqo-platform / airqo-platform/AirQo-frontend

[Vertex: New Feature] Add a "Learning Center" slide-in panel to Vertex (v1: static onboarding walkthroughs)

未关闭
#3,728 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
feature-request ui/ux vertex
主要语言
TypeScript
星标
23
派生
48
平均合并
15 小时 24 分钟
30 天内合并 PR
57

描述

## Is your feature request related to a problem? Please describe.
New Vertex users currently have no in-app path to guidance — the only way to learn how to use the product is to already know that `platform.airqo.net/docs/vertex` exists and go find it themselves. Tools like Docker Desktop and Google Cloud Console solve this with a persistent "Learning center" / "Learn" panel, launched from the topbar, that surfaces a short curated list of task-oriented walkthroughs without leaving the app (see attached screenshots for both references).

We already have real documentation content for Vertex under `src/docs-website/docs/vertex/` (published at `platform.airqo.net/docs/vertex/...`), so this is purely an in-app discovery/surfacing problem, not a content-authoring problem.

## Describe the solution you'd like
Add a slide-in "Learning Center" panel, triggered by a new icon button in the Vertex topbar, containing a curated, static (non-personalized-by-route) list of 6 walkthrough cards. Each card is a title (phrased as a user question, e.g. "How do I add my first device?"), a one-line subtext, a time estimate, and a link that opens the relevant docs-website page in a new tab. A footer link ("View all documentation") points to the docs site root.

### v1 card list (title / subtext / time / target doc path)
1. **What is Vertex?** — "A quick overview of what Vertex does and who it's for." — 3 min — `/intro`
2. **How do I get started as an individual?** *or* **How do I get started with my organization?** (pick one based on `userContext`, see below) — "Set up your workspace and get ready to add your first device." — 5 min — `/getting-started/for-individuals` or `/getting-started/for-organizations`
3. **How do I add my first device?** — "Register a device so it starts sending data to Vertex." — 5 min — `/device-deployment/add-airqo-device`
4. **How do I deploy a device to a site?** — "Assign a registered device to a physical location to start collecting site data." — 4 min — `/device-deployment/deploy-to-site`
5. **What does my device's data status mean?** — "Understand the difference between online, offline, and due-for-maintenance states." — 3 min — `/data-visibility/device-data-status`
6. **Who can see my data?** — "Control whether your devices and readings are public or private." — 4 min — `/data-visibility/public-visibility`

Card 2 should not show both variants at once — read `userContext` (`'personal' | 'external-org'`) from `state.user` (defined in [core/redux/slices/userSlice.ts] `src/vertex/core/redux/slices/userSlice.ts`) via `useAppSelector` and show the organization-flavored card when `userContext === 'external-org'`, otherwise the individual-flavored card.

## In scope
- One new topbar-triggered slide-in panel, static list, same content for every user/role (no per-route content, no completion tracking — explicitly deferred, see Out of scope).
- The 6 cards listed above, in that order.
- Reusing existing primitives: the currently-unused `Sheet` component ([components/ui/sheet.tsx] `src/vertex/components/ui/sheet.tsx`) for the slide-in panel shell, and the currently-unused `vertexConfig.links.docsUrl` config field ([vertex.config.ts:46] `src/vertex/vertex.config.ts#L46`) as the base URL for every card link (append the relative doc path per card to this base).
- Fixing `links.docsUrl` in [vertex.config.ts] `src/vertex/vertex.config.ts` from the current (wrong/unused) `"https://docs.airqo.net"` to `"https://platform.airqo.net/docs/vertex"` as part of this change — it has no other consumers today, so correcting it here is safe and this feature becomes its first real usage. Also update the matching field in [vertex.config.example.ts] `src/vertex/vertex.config.example.ts` for consistency.
- A trigger icon button in the topbar, placed next to the existing "Help & Feedback" button.
- Following the existing global-event trigger pattern used by the feedback dialog (`FEEDBACK_DIALOG_OPEN_EVENT` in [feedback-dialog.ts] `src/vertex/components/features/feedback/feedback-dialog.ts` + the `useEffect` listener in [feedback-launcher.tsx:390-394] `src/vertex/components/features/feedback/feedback-launcher.tsx#L390-L394`) so the panel can, in principle, be opened from anywhere in the app later, not just the topbar.
- Basic keyboard/a11y behavior inherited from the `Sheet` primitive (focus trap, `Escape` to close) — no custom a11y work beyond wiring standard props.
- Manual verification only (see Acceptance criteria) — automated tests are optional, not required to close this issue.

## Out of scope
- Route-aware / context-aware content (different cards depending on which Vertex page you're on) — explicitly deferred per prior discussion; v1 is one static list everywhere.
- Role-based content differences (org admin vs. member) — explicitly deferred; the only conditional logic in v1 is the individual-vs-organization pick for card 2, which is account-context, not role.
- Completion/progress tracking (e.g. Google Cloud's "step 3 of 6" state) — needs a persistence layer and is a good v2 candidate, not part of this issue.
- The 3 "phase 1.5" cards discussed (cohorts, third-party sensor import, device recall) — separate follow-up issue once v1 ships.
- Any change to the actual docs content under `src/docs-website/docs/vertex/` — this issue only links out to existing pages, it does not add/edit doc content.
- Any changes for other AirQo frontend products (Analytics/`platform`, mobile, website, calibrate) — Vertex only.
- Solving the case where a white-label deployment's `links.docsUrl` doesn't have equivalent AirQo doc paths (e.g. `/device-deployment/add-airqo-device` won't exist on a non-AirQo docs site) — flag this as a known limitation in the PR description rather than solving it here.

## Prerequisites
- Read the root [CONTRIBUTING.md](https://github.com/airqo-platform/AirQo-frontend/blob/staging/CONTRIBUTING.md) before starting: fork the repo, install Git LFS, and follow the branch/PR/issue-linking workflow described there.
- Read the [Vertex README](https://github.com/airqo-platform/AirQo-frontend/blob/staging/src/vertex/README.md) for local setup instructions (env vars, install, dev server).
- Review the existing docs-website Vertex structure at [src/docs-website/docs/vertex/] `src/docs-website/docs/vertex/` (or live at [platform.airqo.net/docs/vertex/intro](https://platform.airqo.net/docs/vertex/intro)) so the linked paths in this issue are still accurate at implementation time — doc paths may have moved since this issue was written.
- Read the `Sheet` component's existing API in [components/ui/sheet.tsx] `src/vertex/components/ui/sheet.tsx` — it currently has zero consumers in the app, so check the shadcn/radix docs for `Dialog`-family primitives (Sheet is built on `@radix-ui/react-dialog`) if the prop shape isn't self-explanatory.
- Read [feedback-dialog.ts] `src/vertex/components/features/feedback/feedback-dialog.ts` + the relevant section of [feedback-launcher.tsx] `src/vertex/components/features/feedback/feedback-launcher.tsx` (lines 357–412) as the reference pattern for a globally-triggerable, event-based panel mounted once at the layout level.
- Confirm current behavior locally: there is currently no "Learning Center" / "Learn" affordance anywhere in the Vertex topbar.

## Files expected to change
- **New** `src/vertex/components/features/learning-center/learning-center-launcher.ts` — exports `LEARNING_CENTER_OPEN_EVENT` and `openLearningCenter()`, mirroring [feedback-dialog.ts] `src/vertex/components/features/feedback/feedback-dialog.ts` exactly.
- **New** `src/vertex/components/features/learning-center/learning-center-panel.tsx` — the panel component: listens for `LEARNING_CENTER_OPEN_EVENT` (same `useEffect`/`window.addEventListener` pattern as [feedback-launcher.tsx:390-394] `src/vertex/components/features/feedback/feedback-launcher.tsx#L390-L394`), renders the `Sheet` with the card list, reads `userContext` via `useAppSelector` for card 2's variant, and builds each card's `href` as `` `${vertexConfig.links.docsUrl}${card.path}` ``.
- **New** `src/vertex/components/features/learning-center/walkthroughs.ts` — the static array of 6 card definitions (`title`, `subtitle`, `minutes`, `path`, and the two `path` variants for card 2).
- **Modify** [`src/vertex/components/layout/topbar.tsx`] `src/vertex/components/layout/topbar.tsx#L131-L139` — add a new `ReusableButton` (same shape as the existing "Help & Feedback" button at lines 131-139) immediately next to it, using an icon such as `AqGraduationHat01` from `@airqo/icons-react` (visually closest to the reference screenshots' graduation-cap icon — confirm with design if a different icon is preferred), `onClick={openLearningCenter}`, `title`/`aria-label="Learning Center"`.
- **Modify** [`src/vertex/components/layout/layout.tsx`] `src/vertex/components/layout/layout.tsx#L162` — mount `` next to the existing ``.
- **Modify** [`src/vertex/vertex.config.ts`] `src/vertex/vertex.config.ts#L46` — change `links.docsUrl` from `"https://docs.airqo.net"` to `"https://platform.airqo.net/docs/vertex"`.
- **Modify** [`src/vertex/vertex.config.example.ts`] `src/vertex/vertex.config.example.ts#L45` — same `docsUrl` correction, for consistency with the example config.

## Acceptance criteria
- [ ] A new icon button appears in the Vertex topbar next to "Help & Feedback", labeled/accessible as "Learning Center".
- [ ] Clicking it opens a slide-in panel (not a centered modal) containing the 6 cards listed above, in order.
- [ ] Card 2 shows the individual-flavored copy for personal-context users and the organization-flavored copy for external-org-context users (verify by switching context if your local test account supports it, or by inspecting `state.user.userContext`).
- [ ] Each card link opens the correct docs-website page in a new tab, built from `vertexConfig.links.docsUrl` + the card's relative path — verify the resulting URLs actually resolve (docs paths may have shifted since this issue was written).
- [ ] A "View all documentation" footer link opens `vertexConfig.links.docsUrl` (the docs root) in a new tab.
- [ ] Panel closes via close button, `Escape`, and clicking outside, and does not trap focus after closing.
- [ ] `links.docsUrl` correction doesn't break anything else — confirm via a repo-wide search that this field genuinely had no other consumers before this PR.
- [ ] Works on both desktop and mobile breakpoints.
- [ ] Dark mode support, consistent with the rest of the topbar (which already has a dark/light toggle).

## Additional context
Reference screenshots attached: Docker Desktop's "Learning center" panel (topbar icon → right-side panel with "Walkthroughs" cards showing title + time estimate, plus a "View all" link) and Google Cloud Console's "Learn" panel (similar right-side panel, contextual to the current product page, with tutorial cards showing title/time/description and a progress-through-steps view). These are UX/interaction references only — Vertex's v1 panel should use Vertex's own visual language (`Sheet`, `ReusableButton`, existing color/typography tokens), and should be static (non-contextual) per the v1 scope above, not context-aware like the Google Cloud example.

Image

Image

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。