Builder Guide - Improvement & Fix Plan

Status: TEMPORARILY DISABLED

Disabled in: Session 55 Location: apps/gograb-space/src/app/core/layout/main-shell/main-shell.component.html

What Is The Builder Guide?

The Builder Guide is an onboarding overlay component designed to help new users navigate the platform with step-by-step guidance. It appears as a floating card in the bottom-right corner of the screen.

Current Implementation Files

Why Was It Disabled?

1. Persistent State Issue: The guide uses autoFlashState (localStorage) to persist its state. This causes it to appear even when no active onboarding flow was intentionally started.

2. No Explicit Trigger: The guide shows whenever isActive() returns true, but there's no clear user action that starts an onboarding flow in the current UX.

3. Confusing UX: Users see a floating white box with no clear purpose, especially when they haven't explicitly requested help.

Current Architecture

OnboardingService (libs/libs-foundational/core-angular)

@Injectable({ providedIn: 'root' })
export class OnboardingService {
  // State persisted to localStorage
  private activeFlow = autoFlashState<OnboardingFlow | null>('onboarding-flow', null);
  
  // Computed selectors
  readonly flow = computed(() => this.activeFlow());
  readonly currentStep = computed(() => this.activeFlow()?.steps.find(s => !s.completed));
  readonly isActive = computed(() => !!this.activeFlow() && !this.activeFlow()?.isComplete);

  // Methods
  startFlow(templateId: string, universeId: string): void { ... }
  completeStep(stepId: string): void { ... }
  dismiss(): void { this.activeFlow.set(null); }
}

BuilderGuideComponent

@Component({
  selector: 'app-builder-guide',
  template: `
    @if (isActive()) {
      <div class="builder-guide-container" [@slideUp]>
        <!-- Header with title and dismiss/minimize buttons -->
        <!-- Progress bar -->
        <!-- Step content with action button -->
      </div>
    }
  `
})
export class BuilderGuideComponent {
  isActive = this.onboardingService.isActive;
  flow = this.onboardingService.flow;
  currentStep = this.onboardingService.currentStep;
}

Existing Flow Templates

The service has templates for:

• E-commerce: Products → Customize Homepage → Publish
• Blog: Write Post → Style Theme

Required Improvements

1. Explicit Flow Triggering

• Add "Start Tutorial" button in appropriate places (e.g., empty states, help menu)
• Only show guide when user explicitly requests it
• Consider showing on first-time universe creation only

2. Better State Management

• Clear stale localStorage data on app initialization if no valid flow
• Add expiration to flows (e.g., auto-dismiss after 7 days)
• Validate flow state on load (check if referenced routes/resources still exist)

3. Flow Improvements

• Add more flow templates for different use cases
• Make flows context-aware (show relevant steps based on current page)
• Add skip/snooze functionality
• Track completion analytics

4. UI/UX Enhancements

• Make the guide draggable/repositionable
• Add "Don't show again" option
• Improve visual design to match cosmic theme
• Add spotlight/highlight functionality to point at UI elements
• Support for video/image step content

5. Integration Points

• Trigger on universe template selection
• Trigger from help menu
• Trigger from empty states
• Context-sensitive help based on current tool/page

Implementation Steps

Phase 1: Fix Core Issues

1. Add initialization check to clear invalid/stale flow state
2. Add explicit startFlow() triggers (don't auto-show)
3. Re-enable component in main-shell.component.html

Phase 2: Improve UX

1. Add "Start Tutorial" button to appropriate locations
2. Add "Don't show again" preference
3. Improve dismiss behavior

Phase 3: Enhance Features

1. Add spotlight/highlight for UI elements
2. Add more flow templates
3. Add analytics tracking

Re-enabling The Guide

When ready to re-enable, update main-shell.component.html:

<!-- Change this: -->
<!-- <app-builder-guide></app-builder-guide> -->

<!-- To this: -->
<app-builder-guide></app-builder-guide>

And ensure proper flow triggering is in place before re-enabling.

Testing Checklist

• Guide only appears when explicitly triggered
• Dismiss button works and persists preference
• Progress is saved between sessions
• Completing all steps marks flow as complete
• Guide doesn't appear for returning users who completed/dismissed it
• Routes in flow steps are valid and navigate correctly
• Guide doesn't interfere with page-builder or other tools

Related Files

apps/gograb-space/src/app/
├── components/features/onboarding/
│   └── builder-guide/
│       └── builder-guide.component.ts    # Main component
├── core/layout/main-shell/
│   └── main-shell.component.html          # Where guide is rendered

libs/libs-foundational/core-angular/src/lib/
└── services/
    └── onboarding.service.ts              # State management

Notes for Implementing Agent

1. Don't just re-enable - Fix the triggering mechanism first
2. Test localStorage clearing - Users may have stale state from previous sessions
3. Consider the page-builder context - Guide shouldn't interfere with building
4. Cosmic theme - Current styles are light-themed, should match dark cosmic theme
5. Mobile responsive - Guide should work on smaller screens too