Onboarding cards update by ussaama · Pull Request #392 · Dembrane/echo

ussaama · 2025-12-09T12:29:22Z

Summary by CodeRabbit

New Features
- Added tutorial configuration option to skip data privacy slide with host-managed consent
- Expanded tutorial modes: None, Basic, and Advanced
Improvements
- Clarified tutorial selection labels in project settings (e.g., "Tips and best practices")
- Normalized tutorial configuration options for consistency
Localization
- Updated translations for tutorial options across German, Spanish, French, and Dutch

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

…ponent - Removed initialCards prop and integrated tutorialSlug for system card retrieval - Updated useOnboardingCards hook to support tutorial slug normalization and added new tutorial card definitions - Adjusted ProjectPortalEditor to ensure consistent tutorial slug handling - translations

coderabbitai · 2025-12-09T12:29:37Z

Walkthrough

This PR refactors the participant onboarding tutorial system from initialCards-driven to tutorialSlug-driven architecture. Updates Directus sync operations, adds slug-based configuration (skip-consent, none, basic, advanced), removes initialCards component prop, and propagates corresponding UI label and translation updates across five locales.

Changes

Cohort / File(s)	Change Summary
Directus Sync & Configuration `echo/directus/sync/collections/operations.json`, `echo/directus/sync/snapshot/fields/project/default_conversation_tutorial_slug.json`	UUID identifiers swapped between operation nodes; tutorial slug field note changed from manual sync URL to null; added "Skip Consent" option and normalized "None" to "none".
Onboarding Component & Hook Refactoring `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 contract; introduced tutorialSlug derivation from project; replaced getSystemCards(lang, hasDirectusCards) → getSystemCards(lang, tutorialSlug?); added getBasicTutorialCards and getAdvancedTutorialCards helpers with slug-based control flow (skip-consent, none, basic, advanced); eliminated tutorial card fetch and simplified loading logic.
Project Portal Editor UI `echo/frontend/src/components/project/ProjectPortalEditor.tsx`	Normalized and validated default_conversation_tutorial_slug against allowed values; updated option labels ("No tutorial (only Privacy statements)" → "Skip data privacy slide (Host manages consent)", "Advanced (Tips and tricks)" → "Advanced (Tips and best practices)").
Localization Updates `echo/frontend/src/locales/de-DE.po`, `echo/frontend/src/locales/en-US.po`, `echo/frontend/src/locales/es-ES.po`, `echo/frontend/src/locales/fr-FR.po`, `echo/frontend/src/locales/nl-NL.po`	Added new translation entries for updated UI labels across all locales; deprecated obsolete "Advanced (Tips and tricks)" entries; reanchored reference line numbers reflecting source code repositioning.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

API contract changes: initialCards prop removal and tutorialSlug parameter introduction require verification across component tree and hook consumers
Logic density: Slug-based control flow in getSystemCards with four branches (skip-consent/none/basic/advanced) and new helper functions need careful trace-through
Locale file repetition: Five PO files follow consistent pattern of additions/deprecations—high redundancy mitigates review complexity despite file count
Cross-file dependencies: ParticipantStart → ParticipantOnboardingCards → useOnboardingCards chain needs end-to-end validation

Areas requiring extra attention:

Verify all call sites of getSystemCards() properly pass tutorialSlug (check ParticipantOnboardingCards language blocks)
Confirm fallback logic in getSystemCards (defaults to "none" for invalid/undefined values)
Validate slug normalization in ProjectPortalEditor matches allowed set ["skip-consent", "none", "basic", "advanced"]
Check that removed tutorial card fetch in ParticipantStart doesn't break error handling or edge cases

Possibly related PRs

ECHO-581 Add functionality to enable adding system built cards directly in participant portal #379 – Modifies participant onboarding system-card functionality and getSystemCards API; directly related to tutorialSlug refactor
fix syncids #220 – Updates same Directus sync operations.json UUIDs and flow identifiers
sp-nov-17-25 #366 – Overlapping edits to ProjectPortalEditor.tsx and tutorial-slug-driven onboarding logic chain

Suggested labels

improvement

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Onboarding cards update' directly aligns with the main changeset focus: refactoring onboarding card logic by removing initialCards prop, introducing tutorialSlug-based control flow, and updating related components and translations.
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 onboarding-cards-update

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: 4

Caution

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

⚠️ Outside diff range comments (2)

echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx (2)
2-2: Nuke this IDE artifact.

"Start of Selection" is classic IDE cruft - ship it clean.
-// Start of Selection
220-223: Fallback message isn't localized.

Edge case guard is good, but hardcoded English breaks i18n for the ~0.01% of users who hit this. Worth a quick <Trans> wrap.
 	// If there's no valid card, render a fallback
 	if (!currentCard) {
-		return <div>No card available for the current language and section.</div>;
+		return (
+			<div className="flex h-full items-center justify-center p-4">
+				<Trans>No card available for the current language and section.</Trans>
+			</div>
+		);
 	}

📜 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 10f0caa.

📒 Files selected for processing (11)

echo/directus/sync/collections/operations.json (12 hunks)
echo/directus/sync/snapshot/fields/project/default_conversation_tutorial_slug.json (1 hunks)
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 (3 hunks)
echo/frontend/src/locales/de-DE.po (42 hunks)
echo/frontend/src/locales/en-US.po (43 hunks)
echo/frontend/src/locales/es-ES.po (42 hunks)
echo/frontend/src/locales/fr-FR.po (42 hunks)
echo/frontend/src/locales/nl-NL.po (43 hunks)
echo/frontend/src/routes/participant/ParticipantStart.tsx (3 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

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

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/routes/participant/ParticipantStart.tsx
echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx
echo/frontend/src/components/project/ProjectPortalEditor.tsx

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/routes/participant/ParticipantStart.tsx
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/{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/routes/participant/ParticipantStart.tsx
echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx
echo/frontend/src/components/project/ProjectPortalEditor.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/routes/participant/ParticipantStart.tsx
echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx
echo/frontend/src/components/project/ProjectPortalEditor.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/routes/participant/ParticipantStart.tsx
echo/frontend/src/components/participant/hooks/useOnboardingCards.ts
echo/frontend/src/components/participant/ParticipantOnboardingCards.tsx
echo/frontend/src/locales/en-US.po