Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

12.2 KB
Raw Blame
import { ROUTER_BASE } from '@app/constants/routerBase';
import { CommandState } from '@app/features/command';
import { useAnalytics } from '@app/lib/analytics/analytics-context';
import { useSplitPanel } from '@components/app/split-layout/layoutUtils';
import { useTutorialCompleted } from '@core/context/user';
import { registerHotkey, useHotkeyDOMScope } from '@core/hotkey/hotkeys';
import { isTouchDevice } from '@core/mobile/isTouchDevice';
import { useCompleteTutorialMutation } from '@queries/auth/tutorial';
import {
  batch,
  createEffect,
  createMemo,
  createSignal,
  type JSX,
  on,
  onCleanup,
  onMount,
} from 'solid-js';
import { createOnboardingState } from './create-onboarding-state';
import { LESSONS } from './lessons';
import { commandKOpen, setCommandKOpen } from './lessons/command-k';
import { OnboardingProvider } from './onboarding-context';
import { resetSandbox } from './sandbox/sandbox-store';

interface InteractiveOnboardingProps {
  onDismiss?: () => void;
  ignoreTutorialCompleted?: boolean;
  isFirstTimeOnboarding?: boolean;
  children: JSX.Element;
}

export default function InteractiveOnboarding(
  props: InteractiveOnboardingProps
) {
  return (
    <InteractiveOnboardingInner
      onDismiss={props.onDismiss}
      ignoreTutorialCompleted={props.ignoreTutorialCompleted}
      isFirstTimeOnboarding={props.isFirstTimeOnboarding}
    >
      {props.children}
    </InteractiveOnboardingInner>
  );
}

function InteractiveOnboardingInner(props: InteractiveOnboardingProps) {
  const analytics = useAnalytics();

  const splitPanel = useSplitPanel();
  const completeTutorial = useCompleteTutorialMutation();
  const tutorialCompleted = useTutorialCompleted();

  const isTouch = isTouchDevice();

  const lessons = createMemo(() => LESSONS);

  const search = typeof window === 'undefined' ? '' : window.location.search;
  const params = new URLSearchParams(search);

  const testMode = params.has('test');
  const slideParam = params.get('slide');
  const slideIndex =
    slideParam !== null ? Math.max(0, parseInt(slideParam, 10) - 1) : null;

  const sortedLessons = createMemo(() =>
    [...lessons()].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
  );
  const debugCompleted =
    slideIndex !== null
      ? new Set(
          sortedLessons()
            .slice(0, slideIndex)
            .map((l) => l.id)
        )
      : undefined;

  // Detect a return-from-external-flow param synchronously so we can pre-populate
  // completed lessons before the first render, avoiding a flash of the first slide.
  // Search the unfiltered LESSONS list so return params can still complete
  // lessons even if the visible lesson list changes.
  const state = createOnboardingState({
    definitions: lessons,
    initialCompleted: debugCompleted ?? new Set(),
  });

  const [readyToContinue, setReadyToContinue] = createSignal(false);
  const [continueLabel, setContinueLabel] = createSignal<string | undefined>(
    undefined
  );

  const navigateAway = () => {
    if (props.onDismiss) {
      props.onDismiss();
    } else if (splitPanel) {
      splitPanel.handle.replace({
        next: { type: 'component', id: 'unified-list' },
      });
    } else {
      window.location.replace(ROUTER_BASE);
    }
  };

  // Redirect away if the backend already marks the tutorial as complete.
  // Skip the redirect when returning from external flow — we just marked it
  // complete ourselves and still have remaining lessons to show.
  createEffect(() => {
    if (tutorialCompleted() && !props.ignoreTutorialCompleted && !testMode) {
      navigateAway();
    }
  });

  let continueButtonRef: HTMLButtonElement | undefined;

  const handleLessonComplete = (
    buttonLabel?: string,
    options?: { skipFocus?: boolean }
  ) => {
    setContinueLabel(buttonLabel);
    setReadyToContinue(true);
    // Skip auto-focus on touch — Safari scrolls to the focused element,
    // which jumps the view to the bottom on longer lessons.
    if (!isTouch && !options?.skipFocus) {
      requestAnimationFrame(() => continueButtonRef?.focus());
    }
  };

  const handleLessonUnready = () => {
    setReadyToContinue(false);
  };

  // Programmatic advance for lessons that progress on their own interaction
  // rather than the Continue button.
  const advanceLesson = () => {
    const current = state.currentLesson();
    if (!current) return;
    analytics.track('tutorial_step', {
      id: current.definition.id,
      index: current.index,
      state: 'completed',
    });
    state.completeLesson(current.definition.id);
    setReadyToContinue(false);
    setContinueLabel(undefined);
  };

  const handleSkipLesson = () => {
    const current = state.currentLesson();
    if (!current) return;

    analytics.track('tutorial_step', {
      id: current.definition.id,
      index: current.index,
      state: 'skipped',
    });

    state.skipLesson(current.definition.id);
    setReadyToContinue(false);
    setContinueLabel(undefined);
  };

  const handleContinue = () => {
    const current = state.currentLesson();
    if (!current || !readyToContinue()) return;

    analytics.track('tutorial_step', {
      id: current.definition.id,
      index: current.index,
      state: 'completed',
    });

    state.completeLesson(current.definition.id);
    setReadyToContinue(false);
    setContinueLabel(undefined);
  };

  const getBackContext = () => ({
    isLessonSkipped: (id: string) =>
      state.lessons().find((l) => l.definition.id === id)?.skipped ?? false,
    hasPaidAccess: false,
  });

  const getPreviousLesson = () => {
    const current = state.currentLesson();
    if (!current) return undefined;
    const prev = current.definition.previousLesson;
    if (!prev) return undefined;
    if (typeof prev === 'function') {
      return prev(getBackContext());
    }
    return prev;
  };

  const handleBack = (targetLesson: string) => {
    const current = state.currentLesson();
    if (!current) return;
    const onBack = current.definition.onBack;
    if (onBack) {
      onBack(getBackContext());
    }
    state.goToLessonById(targetLesson);
  };

  const resetTutorial = () => {
    batch(() => {
      state.reset();
      resetSandbox();
      setReadyToContinue(false);
      setContinueLabel(undefined);
    });
  };

  // cmd+enter hotkey to continue
  let shellRef: HTMLDivElement | undefined;
  // Detached so onboarding hotkeys do not bubble up to app/global hotkeys.
  // Any lesson hotkeys registered with this scope still work while this shell
  // is focused, but unhandled keys stop at this scope instead of falling back
  // to the app-level handlers.
  const [attachHotkeys, scopeId] = useHotkeyDOMScope('onboarding-shell', true);

  onMount(() => {
    if (shellRef) {
      attachHotkeys(shellRef);
      shellRef.focus();

      // Keep raw bubbling keyboard events inside onboarding without blocking
      // target-level handlers like Lexical's editor input/mentions handling.
      // App-level hotkeys are handled separately by the detached hotkey scope.
      const stopKeyboardPropagation = (event: KeyboardEvent) => {
        event.stopPropagation();
      };
      shellRef.addEventListener('keydown', stopKeyboardPropagation);
      shellRef.addEventListener('keyup', stopKeyboardPropagation);

      // Reclaim focus when it's dropped to <body> (null relatedTarget) so the
      // scope stays active, but not while detaching — that's the close restore.
      const reclaimLostFocus = (event: FocusEvent) => {
        if (event.relatedTarget || commandKOpen() || !shellRef?.isConnected) {
          return;
        }
        shellRef.focus();
      };
      shellRef.addEventListener('focusout', reclaimLostFocus);

      onCleanup(() => {
        shellRef?.removeEventListener('keydown', stopKeyboardPropagation);
        shellRef?.removeEventListener('keyup', stopKeyboardPropagation);
        shellRef?.removeEventListener('focusout', reclaimLostFocus);
      });
    }
  });

  const reg = registerHotkey({
    scopeId,
    hotkey: 'cmd+enter',
    description: 'Continue',
    runWithInputFocused: true,
    keyDownHandler: () => {
      if (readyToContinue()) {
        handleContinue();
        return true;
      }
      return false;
    },
  });

  // Block global cmd+k during the entire tutorial.
  // On the command-k lesson slide this opens/closes the sandbox command menu.
  const cmdkReg = registerHotkey({
    scopeId,
    hotkey: 'cmd+k',
    description: 'Command menu (onboarding)',
    runWithInputFocused: true,
    keyDownHandler: () => {
      setCommandKOpen((v) => !v);
      return true; // swallow — prevents global handler
    },
  });

  // Patch CommandState so the global cmd+k handler (which calls toggle/open)
  // cannot open the real command menu while we're in the tutorial. Instead
  // it drives our sandbox dialog. Also patch close() so escape inside
  // CommandMenuInner closes the sandbox dialog.
  const origToggle = CommandState.toggle.bind(CommandState);
  const origOpen = CommandState.open.bind(CommandState);
  const origClose = CommandState.close.bind(CommandState);

  CommandState.toggle = () => {
    setCommandKOpen((v) => !v);
  };
  CommandState.open = () => {
    setCommandKOpen(true);
  };
  CommandState.close = () => {
    origClose();
    setCommandKOpen(false);
  };

  onCleanup(() => {
    CommandState.toggle = origToggle;
    CommandState.open = origOpen;
    CommandState.close = origClose;
  });
  onCleanup(() => reg.dispose());
  onCleanup(() => cmdkReg.dispose());
  onCleanup(() => resetSandbox());

  // When the sandbox command menu dialog closes, return focus to the
  // onboarding shell so DOM-scoped hotkeys (including cmd+k) keep working.
  createEffect(
    on(commandKOpen, (open) => {
      if (!open) {
        shellRef?.focus();
      }
    })
  );

  createEffect(
    on(
      () => state.isFinished(),
      (finished) => {
        if (finished && !testMode) {
          analytics.track('tutorial_completed', {
            isFirstTime: props.isFirstTimeOnboarding === true,
          });
          if (props.isFirstTimeOnboarding) {
            completeTutorial.mutate(undefined);
          }
        }
      }
    )
  );

  onMount(() => {
    if (state.currentIndex() > 0) return;

    analytics.track('tutorial_started', {
      isFirstTime: props.isFirstTimeOnboarding === true,
    });
  });

  createEffect(
    on(
      () => state.currentLesson(),
      (lesson) => {
        if (!lesson) return;

        analytics.track('tutorial_step', {
          id: lesson.definition.id,
          index: lesson.index,
          state: 'viewed',
        });
      }
    )
  );

  createEffect(
    on(
      () => state.dismissed(),
      (dismissed) => {
        if (dismissed) navigateAway();
      }
    )
  );

  const setContinueButtonRef = (el: HTMLButtonElement) => {
    continueButtonRef = el;
  };

  const contextValue = {
    state,
    scopeId,
    testMode,
    readyToContinue,
    continueLabel,
    setContinueButtonRef,
    handleLessonComplete,
    handleLessonUnready,
    advanceLesson,
    handleSkipLesson,
    handleContinue,
    resetTutorial,
    getPreviousLesson,
    handleBack,
  };

  return (
    <OnboardingProvider value={contextValue}>
      <div
        ref={shellRef}
        class="flex items-center justify-center size-full p-3 sm:p-4 overflow-hidden relative"
        tabIndex={-1}
      >
        <style>{
          /*css*/ `
          @keyframes onboarding-fade-up {
            from { opacity: 0; transform: translateY(8px); }
            to   { opacity: 1; transform: translateY(0); }
          }
          @keyframes onboarding-scale-in {
            from { opacity: 0; transform: scale(0.92); }
            to   { opacity: 1; transform: scale(1); }
          }
          .onboarding-stagger > * {
            animation: onboarding-fade-up 300ms ease-out both;
          }
          .onboarding-stagger > *:nth-child(1) { animation-delay: 50ms; }
          .onboarding-stagger > *:nth-child(2) { animation-delay: 120ms; }
          .onboarding-stagger > *:nth-child(3) { animation-delay: 190ms; }
          .onboarding-stagger > *:nth-child(4) { animation-delay: 260ms; }
          .onboarding-stagger > *:nth-child(5) { animation-delay: 330ms; }
        `
        }</style>

        <div class="size-full max-w-400 max-h-225 flex">{props.children}</div>
      </div>
    </OnboardingProvider>
  );
}