feat(onboarding): add interactive guide for someday tasks (#891)

* feat(web): refactor onboarding components to use new layouts and remove boilerplate

* feat(web): enhance OnboardingTwoRowLayout with keyboard navigation support and refactor content structure

* feat(web): enhance SomedaySandbox with task management features and animated text

* refactor(web): rename taskColors to colors and update related functions in SomedaySandbox

* feat(web): update event creation API to accept multiple event formats

* feat(web): integrate SomedaySandbox into OnboardingDemo component

* feat(web): enhance SomedaySandbox with event creation and keyboard navigation improvements

* feat(web): add SomedaySandbox step to OnboardingDemo component

* feat(web): improve task input handling in SomedaySandbox with dynamic limits and keyboard navigation

* refactor(web): improve keyboard navigation handling in OnboardingTwoRowLayout and clean up SomedaySandbox event logic

* refactor(web): implement useOnboardingShortcuts hook for improved navigation control in OnboardingTwoRowLayout and SomedaySandbox

* refactor(web): update state management and variable naming in SomedaySandbox for clarity and consistency

* refactor(web): remove unused keyboard event handling in Onboarding component

* refactor(web): simplify navigation control and keyboard event handling in Onboarding components

* refactor(web): streamline task management and remove unused editing functionality in SomedaySandbox

* refactor(web): enhance OnboardingNextButton with pulsing animation and focus trapping

* refactor(web): enhance focus management in SomedaySandbox for improved task input navigation

* test(web): add unit tests for useOnboardingShortcuts hook to validate keyboard navigation behavior

* refactor(web): enhance conditional rendering in SomedaySandbox for improved user guidance

* test(web): add unit tests for SomedaySandbox component to validate task input functionality

* refactor(web): enhance onboarding navigation control and keyboard shortcuts for improved user experience

* refactor(web): improve onboarding step navigation control and state management for enhanced user experience

* fix(web): update ResultText styling in Welcome component for improved visual consistency

* fix(web): ensure next step triggers on key press after animation completion in Welcome component

* refactor(web): improve onboarding button functionality and user guidance

* docs(agents): add naming conventions for boolean variables

* refactor(web): simplify onboarding navigation logic and update tests for clarity

* feat(web): add keyboard event handling to onboarding steps for improved navigation

* refactor(web): remove SetSomedayEventsSuccess component from onboarding steps

* feat(web): implement disableLeftArrow functionality in onboarding steps for enhanced navigation control

* feat(web): enhance keyboard navigation in SomedaySandbox with task validation

* feat(web): implement submission prevention in SomedaySandbox to enhance user experience

* refactor(web): remove keyboard event handling from SomedaySandbox to streamline navigation

* refactor(web): add aria-labels to onboarding footer buttons for improved accessibility

* feat(web): introduce SomedaySandbox component with task management and keyboard shortcuts for enhanced onboarding experience

* chore(onboarding): fix typo

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore(onboarding): remove console.log

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: tyler-dane

AGENTS.md

@@ -187,6 +187,10 @@ TZ=Etc/UTC
 
 Always prioritize frontend development with `yarn dev:web` when backend services are unavailable.
 
+## Naming Conventions
+
+- Use `is` prefix for boolean variables. For example, `isLoading`, `isError`, `isSuccess`
+
 ## Branch Naming & Commit Message Conventions
 
 ### Semantic Branch Naming

packages/web/src/ducks/events/event.api.ts

@@ -8,7 +8,7 @@ import {
 import { CompassApi } from "@web/common/apis/compass.api";
 
 const EventApi = {
-  create: (event: Schema_Event) => {
+  create: (event: Schema_Event | Schema_Event[]) => {
     return CompassApi.post(`/event`, event);
   },
   delete: (_id: string) => {

packages/web/src/routers/index.tsx

@@ -25,10 +25,7 @@ const router = createBrowserRouter([
   },
   {
     path: ROOT_ROUTES.LOGIN,
-    element: (
-      // <LoginView />
-      <OnboardingDemo />
-    ),
+    element: <OnboardingDemo />,
   },
   { path: ROOT_ROUTES.LOGOUT, element: <LogoutView /> },
   { path: "*", element: <NotFoundView /> },

packages/web/src/views/Onboarding/OnboardingDemo.tsx

@@ -12,9 +12,7 @@ import {
   SetReminder,
   SetReminderSuccess,
   SetSomedayEventTwo,
-  SetSomedayEvents,
   SetSomedayEventsOne,
-  SetSomedayEventsSuccess,
   SignInWithGoogle,
   SignInWithGooglePrelude,
   WaitlistCheck,
@@ -23,6 +21,7 @@ import {
   WelcomeScreen,
   WelcomeStep,
 } from "./steps";
+import { SomedaySandbox } from "./steps/events/SomedaySandbox/SomedaySandbox";
 import { ReminderIntroOne } from "./steps/reminder/ReminderIntroOne";
 import { ReminderIntroTwo } from "./steps/reminder/ReminderIntroTwo";
 
@@ -55,6 +54,7 @@ const OnboardingDemo_: React.FC = () => {
       component: (props: OnboardingStepProps) => (
         <WelcomeScreen firstName="hello" {...props} />
       ),
+      disableLeftArrow: true,
     },
     {
       id: "welcome-note-one",
@@ -76,6 +76,8 @@ const OnboardingDemo_: React.FC = () => {
         <SignInWithGoogle {...props} />
       ),
       disableRightArrow: true,
+      preventNavigation: true,
+      handlesKeyboardEvents: true,
     },
     {
       id: "reminder-intro-one",
@@ -112,20 +114,15 @@ const OnboardingDemo_: React.FC = () => {
       ),
     },
     {
-      id: "set-someday-events",
-      component: (props: OnboardingStepProps) => (
-        <SetSomedayEvents {...props} />
-      ),
-    },
-    {
-      id: "set-someday-events-success",
-      component: (props: OnboardingStepProps) => (
-        <SetSomedayEventsSuccess {...props} />
-      ),
+      id: "someday-sandbox",
+      component: (props: OnboardingStepProps) => <SomedaySandbox {...props} />,
+      preventNavigation: true,
     },
+
     {
       id: "outro-two",
       component: (props: OnboardingStepProps) => <OutroTwo {...props} />,
+      disableLeftArrow: true,
     },
     {
       id: "outro-quote",
@@ -135,7 +132,7 @@ const OnboardingDemo_: React.FC = () => {
     },
   ];
 
-  // Initially hide the steps til the user logs in
+  // Initially hide the steps until the user logs in
   useEffect(() => {
     setHideSteps(true);
   }, [setHideSteps]);

packages/web/src/views/Onboarding/components/IconButtons.tsx

@@ -1,19 +1,65 @@
-import React from "react";
-import styled from "styled-components";
+import React, { useEffect, useRef } from "react";
+import styled, { css, keyframes } from "styled-components";
 import { OnboardingButton } from "./styled";
 
-const IconButton = styled(OnboardingButton)`
+// Keyframes for pulsing animation
+const pulse = keyframes`
+  0% {
+    transform: scale(1);
+    opacity: 1;
+  }
+  50% {
+    transform: scale(1.05);
+    opacity: 0.8;
+  }
+  100% {
+    transform: scale(1);
+    opacity: 1;
+  }
+`;
+
+const IconButton = styled(OnboardingButton)<{ $shouldPulse?: boolean }>`
   padding: 0;
   min-width: 0;
   width: 24px;
   height: 24px;
+  transition: all 0.2s ease-in-out;
+
+  ${({ $shouldPulse }) =>
+    $shouldPulse &&
+    css`
+      animation: ${pulse} 2s ease-in-out infinite;
+    `}
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
 `;
 
-export const OnboardingNextButton = (
-  props: React.ButtonHTMLAttributes<HTMLButtonElement>,
-) => {
+interface OnboardingNextButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  shouldTrapFocus?: boolean;
+  shouldPulse?: boolean;
+}
+
+export const OnboardingNextButton: React.FC<OnboardingNextButtonProps> = ({
+  shouldTrapFocus = false,
+  shouldPulse = false,
+  ...props
+}) => {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (shouldTrapFocus && buttonRef.current) {
+      // Focus the button when focus trapping is enabled
+      buttonRef.current.focus();
+    }
+  }, [shouldTrapFocus]);
+
   return (
-    <IconButton {...props}>
+    <IconButton ref={buttonRef} $shouldPulse={shouldPulse} {...props}>
       <svg
         width="10"
         height="9"
@@ -30,9 +76,9 @@ export const OnboardingNextButton = (
   );
 };
 
-export const OnboardingPreviousButton = (
-  props: React.ButtonHTMLAttributes<HTMLButtonElement>,
-) => {
+export const OnboardingPreviousButton: React.FC<
+  React.ButtonHTMLAttributes<HTMLButtonElement>
+> = (props) => {
   return (
     <IconButton {...props}>
       <svg

packages/web/src/views/Onboarding/components/Onboarding.tsx

@@ -1,6 +1,6 @@
-import React, { useEffect, useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import styled from "styled-components";
-import { Key } from "ts-key-enum";
+import { useOnboardingShortcuts } from "../hooks/useOnboardingShortcuts";
 
 export const OnboardingRoot = styled.div`
   // background: rgba(0, 0, 0, 0.8);
@@ -9,19 +9,25 @@ export const OnboardingRoot = styled.div`
   width: 100vw;
 `;
 
-export const OnboardingContainer = styled.div`
+interface OnboardingContainerProps {
+  fullWidth?: boolean;
+}
+
+export const OnboardingContainer = styled.div<OnboardingContainerProps>`
   background-color: #12151b;
   position: absolute;
-  width: 900px;
-  height: 800px;
-  border-radius: 44px;
-  top: 50%;
-  left: 50%;
-  transform: translate(-50%, -50%);
+  width: ${({ fullWidth }) => (fullWidth ? "100vw" : "900px")};
+  height: ${({ fullWidth }) => (fullWidth ? "100vh" : "800px")};
+  border-radius: ${({ fullWidth }) => (fullWidth ? "0" : "44px")};
+  top: ${({ fullWidth }) => (fullWidth ? "0" : "50%")};
+  left: ${({ fullWidth }) => (fullWidth ? "0" : "50%")};
+  transform: ${({ fullWidth }) =>
+    fullWidth ? "none" : "translate(-50%, -50%)"};
   display: flex;
   align-items: center;
   justify-content: center;
-  box-shadow: rgb(255 255 255 / 15%) 0px 9px 20px 1px;
+  box-shadow: ${({ fullWidth }) =>
+    fullWidth ? "none" : "rgb(255 255 255 / 15%) 0px 9px 20px 1px"};
 
   @keyframes flicker {
     0%,
@@ -60,7 +66,8 @@ export const OnboardingContainer = styled.div`
     }
   }
 
-  animation: flicker 0.5s infinite;
+  animation: ${({ fullWidth }) =>
+    fullWidth ? "none" : "flicker 0.5s infinite"};
 
   &::before {
     content: "";
@@ -73,7 +80,7 @@ export const OnboardingContainer = styled.div`
     background-size: 100% 4px;
     pointer-events: none;
     z-index: 1;
-    border-radius: 44px;
+    border-radius: ${({ fullWidth }) => (fullWidth ? "0" : "44px")};
   }
 `;
 
@@ -84,6 +91,12 @@ export interface OnboardingStepProps {
   onPrevious: () => void;
   onComplete: () => void;
   onSkip: () => void;
+  // New props for keyboard control
+  canNavigateNext?: boolean;
+  nextButtonDisabled?: boolean;
+  onNavigationControlChange?: (shouldPrevent: boolean) => void;
+  isNavPrevented?: boolean;
+  handlesKeyboardEvents?: boolean;
 }
 
 export interface OnboardingStep {
@@ -92,20 +105,21 @@ export interface OnboardingStep {
   onNext?: (data?: Record<string, unknown>) => void;
   disableLeftArrow?: boolean;
   disableRightArrow?: boolean;
+  // Navigation control properties
+  preventNavigation?: boolean;
+  nextButtonDisabled?: boolean;
+  canNavigateNext?: boolean;
+  handlesKeyboardEvents?: boolean;
 }
 
 interface Props {
   steps: OnboardingStep[];
   onComplete: (reason: "skip" | "complete") => void;
-  className?: string;
 }
 
-export const Onboarding: React.FC<Props> = ({
-  steps,
-  onComplete,
-  className,
-}) => {
+export const Onboarding: React.FC<Props> = ({ steps, onComplete }) => {
   const [currentStepIndex, setCurrentStepIndex] = useState(0);
+  const [isNavPrevented, setIsNavPrevented] = useState(false);
 
   const handleNext = (data?: Record<string, unknown>) => {
     // Call `onNext` if provided
@@ -119,6 +133,11 @@ export const Onboarding: React.FC<Props> = ({
   };
 
   const handlePrevious = () => {
+    // Check if the current step disables left arrow navigation
+    if (currentStep.disableLeftArrow) {
+      return;
+    }
+
     if (currentStepIndex > 0) {
       setCurrentStepIndex(currentStepIndex - 1);
     }
@@ -135,44 +154,48 @@ export const Onboarding: React.FC<Props> = ({
   const currentStep = steps[currentStepIndex];
   const StepComponent = currentStep?.component;
 
-  useEffect(() => {
-    const handleKeyDown = (event: KeyboardEvent) => {
-      const currentStep = steps[currentStepIndex];
-
-      if (
-        (event.key === Key.ArrowRight || event.key === Key.Enter) &&
-        !currentStep?.disableRightArrow
-      ) {
-        event.preventDefault();
-        handleNext();
-      } else if (event.key === "ArrowLeft" && !currentStep?.disableLeftArrow) {
-        event.preventDefault();
-        handlePrevious();
-      }
-    };
-
-    document.addEventListener("keydown", handleKeyDown);
-    return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [currentStepIndex, steps.length, handleNext, handlePrevious]);
-
   if (!StepComponent) {
     return null;
   }
 
+  // Get navigation control from step configuration
+  const preventNavigation = currentStep.preventNavigation || false;
+  const nextButtonDisabled = currentStep.nextButtonDisabled || false;
+  const canNavigateNext = currentStep.canNavigateNext !== false; // Default to true
+  const handlesKeyboardEvents = currentStep.handlesKeyboardEvents || false;
+
+  // Use the keyboard shortcuts hook
+  useOnboardingShortcuts({
+    onNext: handleNext,
+    onPrevious: handlePrevious,
+    canNavigateNext,
+    shouldPreventNavigation: preventNavigation ? isNavPrevented : false,
+    handlesKeyboardEvents,
+    disableLeftArrow: currentStep.disableLeftArrow || false,
+  });
+
+  // Handle navigation control changes from steps
+  const handleNavigationControlChange = (shouldPrevent: boolean) => {
+    setIsNavPrevented(shouldPrevent);
+  };
+
   const stepProps: OnboardingStepProps = {
     currentStep: currentStepIndex + 1,
     totalSteps: steps.length,
     onNext: handleNext,
     onPrevious: handlePrevious,
     onComplete: handleComplete,
     onSkip: handleSkip,
+    canNavigateNext,
+    nextButtonDisabled,
+    onNavigationControlChange: handleNavigationControlChange,
+    isNavPrevented: preventNavigation ? isNavPrevented : false,
+    handlesKeyboardEvents,
   };
 
   return (
     <OnboardingRoot>
-      <OnboardingContainer className={className} id="onboarding-container">
-        <StepComponent {...stepProps} />
-      </OnboardingContainer>
+      <StepComponent {...stepProps} />
     </OnboardingRoot>
   );
 };