ref(onboarding): Drive the project-details form from host state

The hook kept name, team, and alert config in internal useState seeded
once from the host's saved form, a relic of the step component it was
extracted from, which remounts on every onboarding navigation. The
single-view project-creation flow keeps the hook mounted, so the two
copies of the form drift: clearing the host form on a platform or repo
change never reached the live fields.

Make the form fully controlled: the host owns the state and absent
fields derive their defaults, so a cleared form re-derives (the name
follows the platform) by construction. The unchanged-return reuse check
compares against the form captured at mount, since the live prop can no
longer be its own baseline. The wizard holds the live form in its
in-memory state; the onboarding step holds it in local state seeded
from the context, keeping the context to submitted values only so a
remount cannot adopt unsubmitted edits as the reuse baseline.

Author: jaydgoss

static/app/views/onboarding/components/useScmProjectDetails.ts

@@ -1,4 +1,4 @@
-import {useCallback, useState} from 'react';
+import {useCallback, useRef} from 'react';
 import * as Sentry from '@sentry/react';
 
 import {addErrorMessage} from 'sentry/actionCreators/indicator';
@@ -69,6 +69,13 @@ interface UseScmProjectDetailsOptions {
    * both and advance in one place.
    */
   onComplete: (completion: ScmProjectDetailsCompletion) => void;
+  /**
+   * Live form state, owned by the host. Fields absent from the form derive
+   * their defaults (platform-based name, first admin team, default alert
+   * config), so the host clearing the form makes the fields re-derive.
+   */
+  onProjectDetailsFormChange: (form: ProjectDetailsFormState) => void;
+  projectDetailsForm: ProjectDetailsFormState | undefined;
   selectedPlatform: OnboardingSelectedSDK | undefined;
   selectedRepository: Repository | undefined;
   /**
@@ -79,7 +86,6 @@ interface UseScmProjectDetailsOptions {
   allowMemberWithoutTeam?: boolean;
   /** Slug of an already-created project, used for the back-nav reuse check. */
   createdProjectSlug?: string;
-  projectDetailsForm?: ProjectDetailsFormState;
 }
 
 interface ScmProjectDetailsForm {
@@ -108,19 +114,22 @@ interface ScmProjectDetailsForm {
 }
 
 /**
- * Owns the SCM project-details form state, the create-project + repo-link flow,
- * and the field/create analytics (routed by `analyticsFlow`). Returned to the
- * host so it can render the presentational `ScmProjectDetailsCore` form and
- * place its own Create button (onboarding's fixed footer, project creation's
- * page-level footer) independent of where the form fields render.
+ * Drives the SCM project-details form (state owned by the host via
+ * `projectDetailsForm`/`onProjectDetailsFormChange`), the create-project +
+ * repo-link flow, and the field/create analytics (routed by `analyticsFlow`).
+ * Returned to the host so it can render the presentational
+ * `ScmProjectDetailsCore` form and place its own Create button (onboarding's
+ * fixed footer, project creation's page-level footer) independent of where
+ * the form fields render.
  */
 export function useScmProjectDetails({
   analyticsFlow,
   onComplete,
+  onProjectDetailsFormChange,
+  projectDetailsForm,
   selectedPlatform,
   selectedRepository,
   createdProjectSlug,
-  projectDetailsForm,
   allowMemberWithoutTeam,
 }: UseScmProjectDetailsOptions): ScmProjectDetailsForm {
   const organization = useOrganization();
@@ -139,41 +148,48 @@ export function useScmProjectDetails({
     !organization.access.includes('project:admin');
   const defaultName = slugify(selectedPlatform?.key ?? '');
 
-  // State tracks user edits. When the host restores a persisted
-  // projectDetailsForm (e.g. back-navigation in onboarding) it seeds the inputs.
-  const [projectName, setProjectName] = useState(projectDetailsForm?.projectName ?? null);
-  const [teamSlug, setTeamSlug] = useState(projectDetailsForm?.teamSlug ?? null);
-  const [alertRuleConfig, setAlertRuleConfig] = useState(
-    projectDetailsForm?.alertRuleConfig ?? DEFAULT_ISSUE_ALERT_OPTIONS_VALUES
-  );
+  // Fields absent from the host-owned form fall back to derived defaults, so
+  // a host clearing the form (e.g. on a platform change) re-derives them.
+  const projectNameResolved = projectDetailsForm?.projectName ?? defaultName;
+  const teamSlugResolved = projectDetailsForm?.teamSlug ?? firstAdminTeam?.slug ?? '';
+  const alertRuleConfig =
+    projectDetailsForm?.alertRuleConfig ?? DEFAULT_ISSUE_ALERT_OPTIONS_VALUES;
 
-  const projectNameResolved = projectName ?? defaultName;
-  const teamSlugResolved = teamSlug ?? firstAdminTeam?.slug ?? '';
+  // Baseline for the unchanged-return (reuse) check below: the form as it was
+  // when this step mounted, i.e. a restored session's saved values. Live edits
+  // flow through the controlled form, so the prop can't be its own baseline.
+  const savedFormRef = useRef(projectDetailsForm);
 
-  const onProjectNameChange = useCallback((value: string) => {
-    setProjectName(slugify(value));
-  }, []);
+  const onProjectNameChange = useCallback(
+    (value: string) => {
+      onProjectDetailsFormChange({...projectDetailsForm, projectName: slugify(value)});
+    },
+    [onProjectDetailsFormChange, projectDetailsForm]
+  );
 
   const onProjectNameBlur = useCallback(() => {
-    if (projectName !== null) {
+    if (projectDetailsForm?.projectName !== undefined) {
       trackAnalytics(NAME_EDITED_EVENT[analyticsFlow], {
         organization,
-        custom: projectName !== defaultName,
+        custom: projectDetailsForm.projectName !== defaultName,
       });
     }
-  }, [projectName, defaultName, organization, analyticsFlow]);
+  }, [projectDetailsForm?.projectName, defaultName, organization, analyticsFlow]);
 
   const onTeamChange = useCallback(
     ({value}: {value: string}) => {
-      setTeamSlug(value);
+      onProjectDetailsFormChange({...projectDetailsForm, teamSlug: value});
       trackAnalytics(TEAM_SELECTED_EVENT[analyticsFlow], {organization, team: value});
     },
-    [organization, analyticsFlow]
+    [onProjectDetailsFormChange, projectDetailsForm, organization, analyticsFlow]
   );
 
   const onAlertChange = useCallback(
     <K extends keyof AlertRuleOptions>(key: K, value: AlertRuleOptions[K]) => {
-      setAlertRuleConfig(prev => ({...prev, [key]: value}));
+      onProjectDetailsFormChange({
+        ...projectDetailsForm,
+        alertRuleConfig: {...alertRuleConfig, [key]: value},
+      });
       if (key === 'alertSetting') {
         const optionMap: Record<number, string> = {
           [RuleAction.DEFAULT_ALERT]: 'high_priority',
@@ -186,7 +202,13 @@ export function useScmProjectDetails({
         });
       }
     },
-    [organization, analyticsFlow]
+    [
+      onProjectDetailsFormChange,
+      projectDetailsForm,
+      alertRuleConfig,
+      organization,
+      analyticsFlow,
+    ]
   );
 
   // Block submission until teams and the projects store have loaded so the
@@ -207,12 +229,13 @@ export function useScmProjectDetails({
   // snapshot because the Project model tracks it; alert fields are not on the
   // Project record so we compare those against the context snapshot.
   const samePlatform = existingProject?.platform === selectedPlatform?.key;
-  const savedAlert = projectDetailsForm?.alertRuleConfig;
+  const savedForm = savedFormRef.current;
+  const savedAlert = savedForm?.alertRuleConfig;
   const nothingChanged =
     samePlatform &&
-    !!projectDetailsForm &&
-    projectNameResolved === projectDetailsForm.projectName &&
-    teamSlugResolved === projectDetailsForm.teamSlug &&
+    !!savedForm &&
+    projectNameResolved === savedForm.projectName &&
+    teamSlugResolved === savedForm.teamSlug &&
     alertRuleConfig.alertSetting === savedAlert?.alertSetting &&
     alertRuleConfig.interval === savedAlert?.interval &&
     alertRuleConfig.metric === savedAlert?.metric &&

static/app/views/onboarding/scmProjectDetails.spec.tsx

@@ -3,7 +3,13 @@ import {ProjectFixture} from 'sentry-fixture/project';
 import {RepositoryFixture} from 'sentry-fixture/repository';
 import {TeamFixture} from 'sentry-fixture/team';
 
-import {render, screen, userEvent, waitFor} from 'sentry-test/reactTestingLibrary';
+import {
+  render,
+  renderHookWithProviders,
+  screen,
+  userEvent,
+  waitFor,
+} from 'sentry-test/reactTestingLibrary';
 
 import type {ProductSolution} from 'sentry/components/onboarding/gettingStartedDoc/types';
 import type {ProjectDetailsFormState} from 'sentry/components/onboarding/onboardingContext';
@@ -12,6 +18,7 @@ import {TeamStore} from 'sentry/stores/teamStore';
 import type {Repository} from 'sentry/types/integrations';
 import type {OnboardingSelectedSDK} from 'sentry/types/onboarding';
 import * as analytics from 'sentry/utils/analytics';
+import {useScmProjectDetails} from 'sentry/views/onboarding/components/useScmProjectDetails';
 import {MetricValues, RuleAction} from 'sentry/views/projectInstall/issueAlertOptions';
 
 import {ScmProjectDetails} from './scmProjectDetails';
@@ -112,6 +119,32 @@ describe('ScmProjectDetails', () => {
     expect(screen.getByText("I'll create my own alerts later")).toBeInTheDocument();
   });
 
+  it('re-derives the fields when the host clears the form', () => {
+    const hookProps: Parameters<typeof useScmProjectDetails>[0] = {
+      analyticsFlow: 'onboarding',
+      selectedPlatform: mockPlatform,
+      selectedRepository: undefined,
+      createdProjectSlug: undefined,
+      projectDetailsForm: {
+        projectName: 'restored-name',
+        teamSlug: teamWithAccess.slug,
+      },
+      onProjectDetailsFormChange: jest.fn(),
+      onComplete: jest.fn(),
+    };
+    const {result, rerender} = renderHookWithProviders(useScmProjectDetails, {
+      organization,
+      initialProps: hookProps,
+    });
+
+    expect(result.current.projectName).toBe('restored-name');
+
+    // The host clears the form (platform or repo change in the single-view
+    // flow); the name falls back to the platform default.
+    rerender({...hookProps, projectDetailsForm: undefined});
+    expect(result.current.projectName).toBe('javascript-nextjs');
+  });
+
   it('create project button is disabled without platform', async () => {
     render(<ScmProjectDetails {...defaultProps()} />, {organization});
 

static/app/views/onboarding/scmProjectDetails.tsx

@@ -1,3 +1,5 @@
+import {useState} from 'react';
+
 import {Button} from '@sentry/scraps/button';
 import {Flex} from '@sentry/scraps/layout';
 
@@ -41,20 +43,29 @@ export function ScmProjectDetails({
   selectedRepository,
   genBackButton,
 }: ScmProjectDetailsProps) {
+  // Live form for this step, seeded from the saved form in the onboarding
+  // context. The context only ever holds submitted values, which the hook's
+  // unchanged-return reuse check relies on as its baseline, so live edits stay
+  // here. This step remounts on every onboarding navigation, so each visit
+  // re-seeds and abandoned edits are discarded.
+  const [liveForm, setLiveForm] = useState(projectDetailsForm);
+
   const form = useScmProjectDetails({
     analyticsFlow: 'onboarding',
     selectedPlatform,
     selectedRepository,
     createdProjectSlug,
-    projectDetailsForm,
+    projectDetailsForm: liveForm,
+    onProjectDetailsFormChange: setLiveForm,
     onComplete: ({
       project,
       projectDetailsForm: submittedForm,
     }: ScmProjectDetailsCompletion) => {
       // Store the slug separately so onboarding.tsx can find the project via
       // useRecentCreatedProject without corrupting selectedPlatform.key (which
-      // the platform features step needs), and persist the form so navigating
-      // back from setup-docs restores it. Both land before the step advances.
+      // the platform features step needs), and persist the submitted form so
+      // navigating back from setup-docs restores it. Both land before the
+      // step advances.
       onProjectCreated(project.slug);
       onProjectDetailsFormChange(submittedForm);
       onComplete(undefined, selectedFeatures ? {product: selectedFeatures} : undefined);