ECHO-615 participant onboarding cards update #391

ussaama · 2025-12-09T09:35:48Z

Summary by CodeRabbit

New Features & Updates
- Updated participant onboarding tutorial option labels for clarity: "Basic" now emphasizes data privacy and mic checks; "No tutorial" simplified to mic check only.
- Removed Advanced tutorial option from available selections.
Refactor
- Streamlined participant onboarding initialization flow for improved performance.
Localization
- Updated translations across German, English, Spanish, French, and Dutch language packs.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

- ECHO-615 remove directus call from onboarding cards

linear · 2025-12-09T09:35:51Z

ECHO-615 Only show the following cards on Participant Portal and remove directus calling

coderabbitai · 2025-12-09T09:35:59Z

Walkthrough

This PR refactors the participant onboarding card system to derive tutorial content from project.default_conversation_tutorial_slug instead of Directus-loaded initialCards. The getSystemCards function now accepts a slug string rather than a boolean flag, and the ParticipantStart component's card loading logic is simplified accordingly. All locale files reflect updated UI labels for tutorial tiers.

Changes

Cohort / File(s)	Summary
Component signature refactor `echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx`, `echo/frontend/src/components/participant/hooks/useOnboardingCards.ts`, `echo/frontend/src/routes/participant/ParticipantStart.tsx`	Removed `initialCards` prop from `ParticipantOnboardingCards`; updated `getSystemCards` to accept `tutorialSlug` (string) instead of `hasDirectusCards` (boolean); eliminated tutorial card loading and transformation logic in `ParticipantStart`, simplifying to project-only dependency.
UI label updates `echo/frontend/src/components/project/ProjectPortalEditor.tsx`	Updated select option labels for tutorial tiers: "No tutorial" and "Basic" relabeled; "Advanced" option removed from data array.
Locale file translations `echo/frontend/src/locales/de-DE.po`, `en-US.po`, `es-ES.po`, `fr-FR.po`, `nl-NL.po`	Synchronized translation entries with new tutorial labels ("Basic (Data privacy + mic check)" and "No tutorial (only mic check)"); marked deprecated variants as obsolete; adjusted source file references across all five locale files.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Hook signature change: Verify all callsites of getSystemCards pass correct tutorialSlug values and handle the new normalization logic.
Component prop removal: Confirm ParticipantOnboardingCards receives project correctly and derive tutorialSlug as expected.
Simplification impact: Review ParticipantStart to ensure removal of tutorial card loading doesn't break loading states or error handling for edge cases.
Locale consistency: Sample check that translated labels align across languages and deprecated entries are properly marked.

Possibly related PRs

ECHO-581 Add functionality to enable adding system built cards directly in participant portal #379: Directly modifies the same getSystemCards signature and ParticipantOnboardingCards logic, changing how system cards are sourced.
refactor hooks, bump frontend dependencies and add conversation link #237: Modifies participant onboarding hooks and card transformation logic, affecting similar data flow paths.
Change basic settings language text #167: Updates ProjectPortalEditor UI text and associated localization entries in parallel.

Suggested labels

Feature, improvement

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title references ECHO-615 and describes the main change (participant onboarding cards update), aligning with the core objectives of restricting card display and removing Directus calls.
Linked Issues check	✅ Passed	The changes implement the ECHO-615 requirements: tutorialSlug replaces direct Directus card retrieval, system cards now conditionally display based on slug ('none' → mic check only, 'basic' → privacy + mic check), and initialCards prop is removed.
Out of Scope Changes check	✅ Passed	All modifications directly support ECHO-615 objectives—removing Directus dependency, updating card mapping logic, and refactoring component signatures. Translation updates align with new card labels ('Data privacy + mic check', 'only mic check').
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch testing

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (5)

echo/frontend/src/components/participant/hooks/useOnboardingCards.ts (1)

5-23: Slug-driven system card selection matches the new spec

The refactor to getSystemCards(lang, tutorialSlug) with a lowercase-normalized slug and an early-return on "none" cleanly encodes the new behavior:

"none" ⇒ no system cards here (so participants see only the mic check flow).

"basic" (and any other non-"none" slug) ⇒ privacy card + mic check from the consumer.

Given the current allowed values are just "none" and "basic", this is exactly what we want for ECHO-615. If you ever introduce additional tutorial slugs, it may be worth tightening the comment (and possibly a switch on normalizedSlug) so future behavior is explicit rather than “anything non-none gets privacy”.

echo/frontend/src/routes/participant/ParticipantStart.tsx (1)

7-48: Add defensive check before rendering ParticipantOnboardingCards

While the route simplification is good, the code unsafely casts project as Project without verifying it's defined. Other components using useParticipantProjectById (ParticipantBody, RefineSelection, ParticipantPostConversation) all defensively check or use optional chaining on projectQuery.data.

Replace <ParticipantOnboardingCards project={project as Project} /> with either:

A defensive guard: {project && <ParticipantOnboardingCards project={project} />}

Or move the render into a conditional block that ensures project is truthy

This prevents potential undefined reference errors and maintains consistency with the rest of the codebase.

echo/frontend/src/locales/fr-FR.po (1)

2171-2183: Fix a couple of French grammar nits in portal editor copy

Overall the new portal/page content strings are solid, and the capitalization of “Portail” is correct for French UI per prior guidance. Two minor FR issues worth cleaning up:

Line 3419:

Current: Cette est une vue en direct du portail du participant.

Suggested: Ceci est une vue en direct du portail du participant. or Il s'agit d'une vue en direct du portail du participant.

Line 3451:

Current: Cette prompt guide comment l'IA répond aux participants.

Suggested: e.g. Cette consigne guide la façon dont l’IA répond aux participants. or Ce prompt guide la façon dont l’IA répond aux participants.

Everything else in this block (“Page Content”, “Page Title”, “Portal Content”, “Thank You Page Content”, “This page is shown …”) reads naturally and keeps “Portail” capitalized as desired.

Based on learnings, this keeps French capitalization rules while tightening grammar.

Also applies to: 2435-2438, 3293-3296, 3417-3419, 3439-3445, 3450-3451, 4665-4667
echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx (1)
272-371: Back button on first microphone slide is a no‑op

With the new slug mapping, when tutorialSlug === "none" the microphone slide becomes the very first card. In that case:

The “Back” button in the mic branch is enabled,

But prevSlide early‑returns at currentSlideIndex === 0, so clicking Back does nothing.

Not a blocker, but it’s a slightly janky UX compared to the non‑mic branch where Back is disabled on the first slide.

I’d suggest aligning behavior by disabling Back when there’s nothing to go back to:
{currentCard?.type === "microphone" ? (
  <>
    <Button
      onClick={prevSlide}
      variant="outline"
      color="gray"
      size="md"
-     className="basis-1/2"
+     className="basis-1/2"
+     disabled={currentSlideIndex === 0}
    >
      <Trans id="participant.button.back.microphone">Back</Trans>
    </Button>
This still lets people go back to Data Permission when present (basic tier), but avoids a dead button in the “none” path.
echo/frontend/src/locales/en-US.po (1)
4406-4409: Nit: tighten pronoun in “make them concrete” copy

Current string:
msgid "participant.concrete.instructions.receive.artefact"
msgstr "You'll soon get {objectLabel} to make them concrete."
The plural pronoun “them” doesn’t have a clear grammatical referent here and reads a bit off.

I’d tighten this to something like:
-msgstr "You'll soon get {objectLabel} to make them concrete."
+msgstr "You'll soon get {objectLabel} to make things concrete."
or, if you want to lean into the feature name more directly:
-msgstr "You'll soon get {objectLabel} to make them concrete."
+msgstr "You'll soon get {objectLabel} to make it concrete."
Pick whichever matches the intended UX copy system-wide.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 441a45d and d74e48a.

📒 Files selected for processing (9)

echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx (6 hunks)
echo/frontend/src/components/participant/hooks/useOnboardingCards.ts (1 hunks)
echo/frontend/src/components/project/ProjectPortalEditor.tsx (1 hunks)
echo/frontend/src/locales/de-DE.po (35 hunks)
echo/frontend/src/locales/en-US.po (36 hunks)
echo/frontend/src/locales/es-ES.po (35 hunks)
echo/frontend/src/locales/fr-FR.po (35 hunks)
echo/frontend/src/locales/nl-NL.po (36 hunks)
echo/frontend/src/routes/participant/ParticipantStart.tsx (3 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

echo/frontend/**/src/**/*.{css,tsx,ts}

📄 CodeRabbit inference engine (echo/frontend/AGENTS.md)

Use CSS variables var(--app-background) and var(--app-text) instead of hardcoded colors like #F6F4F1 or #2D2D2C to ensure theme changes propagate

Files:

echo/frontend/src/components/participant/hooks/useOnboardingCards.ts
echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx
echo/frontend/src/components/project/ProjectPortalEditor.tsx
echo/frontend/src/routes/participant/ParticipantStart.tsx

echo/frontend/**/src/{routes,components}/**/*.tsx

📄 CodeRabbit inference engine (echo/frontend/AGENTS.md)

echo/frontend/**/src/{routes,components}/**/*.tsx: Compose Mantine primitives (Stack, Group, ActionIcon, etc.) while layering Tailwind utility classes via className, alongside toast feedback via @/components/common/Toaster
For Tailwind classes that need dynamic values, replace with inline style props using CSS variables instead of hardcoded hex values

Files:

echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx
echo/frontend/src/components/project/ProjectPortalEditor.tsx
echo/frontend/src/routes/participant/ParticipantStart.tsx

echo/frontend/**/src/{theme.tsx,components,routes}/**/*.tsx

📄 CodeRabbit inference engine (echo/frontend/AGENTS.md)

When adding new Mantine components, reference the global Mantine theme in src/theme.tsx with custom primary color palette and component defaults, preferring CSS variables in styles over hardcoded hex values

Files:

echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx
echo/frontend/src/components/project/ProjectPortalEditor.tsx
echo/frontend/src/routes/participant/ParticipantStart.tsx

echo/frontend/**/src/{components,routes}/**/*.tsx

📄 CodeRabbit inference engine (echo/frontend/AGENTS.md)

UI mutations should surface inline feedback: pair toasts with contextual Mantine Alert components inside modals/forms for errors or warnings

Files:

echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx
echo/frontend/src/components/project/ProjectPortalEditor.tsx
echo/frontend/src/routes/participant/ParticipantStart.tsx

echo/frontend/**/src/routes/**/*.tsx

📄 CodeRabbit inference engine (echo/frontend/AGENTS.md)

Use Lingui macros t from @lingui/core/macro and Trans from @lingui/react/macro for localizing UI strings in routed screens

Files:

echo/frontend/src/routes/participant/ParticipantStart.tsx

🧠 Learnings (12)

📓 Common learnings

Learnt from: ussaama
Repo: Dembrane/echo PR: 205
File: echo/frontend/src/lib/query.ts:1444-1506
Timestamp: 2025-07-10T12:48:20.683Z
Learning: ussaama prefers string concatenation over template literals for simple cases where readability is clearer, even when linting tools suggest template literals. Human readability takes precedence over strict linting rules in straightforward concatenation scenarios.

📚 Learning: 2025-08-08T10:39:31.114Z

Learnt from: ussaama
Repo: Dembrane/echo PR: 259
File: echo/frontend/src/components/layout/ParticipantLayout.tsx:33-33
Timestamp: 2025-08-08T10:39:31.114Z
Learning: In echo/frontend/src/components/layout/ParticipantLayout.tsx, prefer using simple pathname.includes("start") and pathname.includes("finish") to control the settings button visibility. No need to switch to segment-based matching or add a useEffect to auto-close the modal for these routes, per ussaama’s preference in PR #259.

Applied to files:

echo/frontend/src/components/participant/hooks/useOnboardingCards.ts
echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx
echo/frontend/src/routes/participant/ParticipantStart.tsx
echo/frontend/src/locales/en-US.po

📚 Learning: 2025-05-30T15:38:44.413Z

Learnt from: ussaama
Repo: Dembrane/echo PR: 169
File: echo/frontend/src/components/project/ProjectPortalEditor.tsx:409-464
Timestamp: 2025-05-30T15:38:44.413Z
Learning: Badge-based selectors in ProjectPortalEditor.tsx: Keyboard navigation enhancements for accessibility are considered optional improvements rather than critical issues. The user acknowledges these suggestions but doesn't prioritize them as blockers.

Applied to files:

echo/frontend/src/components/project/ProjectPortalEditor.tsx
echo/frontend/src/locales/de-DE.po
echo/frontend/src/locales/en-US.po
echo/frontend/src/locales/fr-FR.po