Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

feat(studio): connectSection experiment — replace Getting Started with Connect section (#43629)

Pamela Chia578a73f9668c
diff --git a/apps/studio/components/interfaces/ConnectButton/ConnectButton.tsx b/apps/studio/components/interfaces/ConnectButton/ConnectButton.tsx
index 4e1cf5fbc16..1a4390c4ca2 100644
--- a/apps/studio/components/interfaces/ConnectButton/ConnectButton.tsx
+++ b/apps/studio/components/interfaces/ConnectButton/ConnectButton.tsx
@@ -6,6 +6,7 @@ import { ComponentProps } from 'react'
import { Button, cn } from 'ui'
import { PROJECT_STATUS } from '@/lib/constants'
+import { useAppStateSnapshot } from '@/state/app-state'
interface ConnectButtonProps {
buttonType?: ComponentProps<typeof Button>['type']
@@ -14,6 +15,7 @@ interface ConnectButtonProps {
export const ConnectButton = ({ buttonType = 'default', className }: ConnectButtonProps) => {
const { data: selectedProject } = useSelectedProjectQuery()
+ const { setConnectSheetSource } = useAppStateSnapshot()
const isActiveHealthy = selectedProject?.status === PROJECT_STATUS.ACTIVE_HEALTHY
const [, setShowConnect] = useQueryState('showConnect', parseAsBoolean.withDefault(false))
@@ -24,7 +26,10 @@ export const ConnectButton = ({ buttonType = 'default', className }: ConnectButt
disabled={!isActiveHealthy}
className={cn('rounded-full', className)}
icon={<Plug className="rotate-90" />}
- onClick={() => setShowConnect(true)}
+ onClick={() => {
+ setConnectSheetSource('header_button')
+ setShowConnect(true)
+ }}
tooltip={{
content: {
side: 'bottom',
diff --git a/apps/studio/components/interfaces/ConnectSheet/Connect.types.ts b/apps/studio/components/interfaces/ConnectSheet/Connect.types.ts
index b525e93d704..30fd027ab93 100644
--- a/apps/studio/components/interfaces/ConnectSheet/Connect.types.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/Connect.types.ts
@@ -51,7 +51,8 @@ export type ConditionalValue<T> =
// Schema Types - Modes
// ============================================================================
-export type ConnectMode = 'framework' | 'direct' | 'orm' | 'mcp'
+export const CONNECT_MODES = ['framework', 'direct', 'orm', 'mcp'] as const
+export type ConnectMode = (typeof CONNECT_MODES)[number]
export interface ModeDefinition {
id: ConnectMode
diff --git a/apps/studio/components/interfaces/ConnectSheet/ConnectSheet.tsx b/apps/studio/components/interfaces/ConnectSheet/ConnectSheet.tsx
index 02f605fc838..f110ec843c2 100644
--- a/apps/studio/components/interfaces/ConnectSheet/ConnectSheet.tsx
+++ b/apps/studio/components/interfaces/ConnectSheet/ConnectSheet.tsx
@@ -3,34 +3,61 @@ import { useParams } from 'common'
import { getKeys, useAPIKeysQuery } from 'data/api-keys/api-keys-query'
import { useAsyncCheckPermissions } from 'hooks/misc/useCheckPermissions'
import { parseAsBoolean, parseAsString, useQueryState } from 'nuqs'
-import { useMemo } from 'react'
+import { useEffect, useMemo, useRef } from 'react'
import { cn, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from 'ui'
-import type { ProjectKeys } from './Connect.types'
+import type { ConnectMode, ProjectKeys } from './Connect.types'
+import { CONNECT_MODES } from './Connect.types'
import { ConnectConfigSection, ModeSelector } from './ConnectConfigSection'
import { ConnectStepsSection } from './ConnectStepsSection'
import { useConnectState } from './useConnectState'
+import { useAvailableConnectModes } from './useAvailableConnectModes'
import { useProjectApiUrl } from '@/data/config/project-endpoint-query'
-import { useIsFeatureEnabled } from '@/hooks/misc/useIsFeatureEnabled'
+import { useAppStateSnapshot } from '@/state/app-state'
+import { useTrack } from 'lib/telemetry/track'
+
+function isConnectMode(value: string): value is ConnectMode {
+ return CONNECT_MODES.some((mode) => mode === value)
+}
export const ConnectSheet = () => {
const { ref: projectRef } = useParams()
- const {
- projectConnectionShowAppFrameworks: showAppFrameworks,
- projectConnectionShowMobileFrameworks: showMobileFrameworks,
- projectConnectionShowOrms: showOrms,
- } = useIsFeatureEnabled([
- 'project_connection:show_app_frameworks',
- 'project_connection:show_mobile_frameworks',
- 'project_connection:show_orms',
- ])
+ const availableModeIds = useAvailableConnectModes()
const [showConnect, setShowConnect] = useQueryState(
'showConnect',
parseAsBoolean.withDefault(false)
)
- const [, setConnectTab] = useQueryState('connectTab', parseAsString)
+ const [connectTab, setConnectTab] = useQueryState('connectTab', parseAsString)
+ const { connectSheetSource, setConnectSheetSource } = useAppStateSnapshot()
+ const track = useTrack()
+ const prevShowConnect = useRef(false)
+
+ const { state, activeFields, resolvedSteps, schema, getFieldOptions, setMode, updateField } =
+ useConnectState()
+
+ useEffect(() => {
+ const justOpened = showConnect && !prevShowConnect.current
+ prevShowConnect.current = showConnect
+
+ if (!justOpened) return
+
+ track('connect_sheet_opened', { source: connectSheetSource })
+ setConnectSheetSource('header_button')
+
+ if (connectTab && isConnectMode(connectTab) && availableModeIds.includes(connectTab)) {
+ setMode(connectTab)
+ }
+ }, [
+ showConnect,
+ connectSheetSource,
+ connectTab,
+ availableModeIds,
+ track,
+ setConnectSheetSource,
+ setMode,
+ ])
const handleOpenChange = (sheetOpen: boolean) => {
if (!sheetOpen) {
@@ -39,9 +66,6 @@ export const ConnectSheet = () => {
setShowConnect(sheetOpen)
}
- const { state, activeFields, resolvedSteps, schema, getFieldOptions, setMode, updateField } =
- useConnectState()
-
const { data: endpoint = '' } = useProjectApiUrl({ projectRef }, { enabled: showConnect })
const { can: canReadAPIKeys } = useAsyncCheckPermissions(
@@ -61,23 +85,16 @@ export const ConnectSheet = () => {
}
}, [endpoint, anonKey?.api_key, publishableKey?.api_key])
- const availableModeIds = useMemo(() => {
- const modes: string[] = []
- const showFrameworks = showAppFrameworks || showMobileFrameworks
-
- if (showFrameworks) modes.push('framework')
- modes.push('direct')
- if (showOrms) modes.push('orm')
- modes.push('mcp')
-
- return modes
- }, [showAppFrameworks, showMobileFrameworks, showOrms])
-
const availableModes = useMemo(
() => schema.modes.filter((m) => availableModeIds.includes(m.id)),
[schema.modes, availableModeIds]
)
+ const handleModeChange = (mode: ConnectMode) => {
+ setMode(mode)
+ setConnectTab(mode)
+ }
+
return (
<Sheet open={showConnect} onOpenChange={handleOpenChange}>
<SheetContent size="lg" className="flex flex-col gap-0 p-0 space-y-0" tabIndex={undefined}>
@@ -88,7 +105,11 @@ export const ConnectSheet = () => {
<div className="flex flex-1 flex-col overflow-y-auto divide-y">
<div className="p-8">
- <ModeSelector modes={availableModes} selected={state.mode} onChange={setMode} />
+ <ModeSelector
+ modes={availableModes}
+ selected={state.mode}
+ onChange={handleModeChange}
+ />
</div>
<div className="border-b p-8">
diff --git a/apps/studio/components/interfaces/ConnectSheet/connect.schema.test.ts b/apps/studio/components/interfaces/ConnectSheet/connect.schema.test.ts
index e7eb1d9fab8..a4b1fed820e 100644
--- a/apps/studio/components/interfaces/ConnectSheet/connect.schema.test.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/connect.schema.test.ts
@@ -114,7 +114,7 @@ describe('connect.schema:fields', () => {
const field = connectSchema.fields.mcpClient
expect(field.type).toBe('select')
expect(field.options).toEqual({ source: 'mcpClients' })
- expect(field.defaultValue).toBe('cursor')
+ expect(field.defaultValue).toBe('claude-code')
})
test('mcpFeatures field should have multi-select type', () => {
diff --git a/apps/studio/components/interfaces/ConnectSheet/connect.schema.ts b/apps/studio/components/interfaces/ConnectSheet/connect.schema.ts
index 76ecd8ecc1c..41723910b08 100644
--- a/apps/studio/components/interfaces/ConnectSheet/connect.schema.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/connect.schema.ts
@@ -265,7 +265,7 @@ export const connectSchema: ConnectSchema = {
label: 'Client',
description: 'Choose the MCP client you are using.',
options: { source: 'mcpClients' },
- defaultValue: 'cursor',
+ defaultValue: 'claude-code',
},
mcpReadonly: {
id: 'mcpReadonly',
diff --git a/apps/studio/components/interfaces/ConnectSheet/useAvailableConnectModes.ts b/apps/studio/components/interfaces/ConnectSheet/useAvailableConnectModes.ts
new file mode 100644
index 00000000000..0e241e87b57
--- /dev/null
+++ b/apps/studio/components/interfaces/ConnectSheet/useAvailableConnectModes.ts
@@ -0,0 +1,25 @@
+import { useIsFeatureEnabled } from '@/hooks/misc/useIsFeatureEnabled'
+import { useMemo } from 'react'
+import type { ConnectMode } from './Connect.types'
+
+export function useAvailableConnectModes(): ConnectMode[] {
+ const {
+ projectConnectionShowAppFrameworks: showAppFrameworks,
+ projectConnectionShowMobileFrameworks: showMobileFrameworks,
+ projectConnectionShowOrms: showOrms,
+ } = useIsFeatureEnabled([
+ 'project_connection:show_app_frameworks',
+ 'project_connection:show_mobile_frameworks',
+ 'project_connection:show_orms',
+ ])
+
+ return useMemo(() => {
+ const allModes: { id: ConnectMode; enabled: boolean }[] = [
+ { id: 'framework', enabled: showAppFrameworks || showMobileFrameworks },
+ { id: 'direct', enabled: true },
+ { id: 'orm', enabled: showOrms },
+ { id: 'mcp', enabled: true },
+ ]
+ return allModes.filter((m) => m.enabled).map((m) => m.id)
+ }, [showAppFrameworks, showMobileFrameworks, showOrms])
+}
diff --git a/apps/studio/components/interfaces/ConnectSheet/useConnectState.test.ts b/apps/studio/components/interfaces/ConnectSheet/useConnectState.test.ts
index d37f7cd731e..dbd40cd39a8 100644
--- a/apps/studio/components/interfaces/ConnectSheet/useConnectState.test.ts
+++ b/apps/studio/components/interfaces/ConnectSheet/useConnectState.test.ts
@@ -324,8 +324,8 @@ describe('useConnectState', () => {
const { result } = renderHook(() => useConnectState({ mode: 'mcp' }))
const stepIds = result.current.resolvedSteps.map((s) => s.id)
- // MCP mode should have configure step
- expect(stepIds.some((id) => id.includes('configure') || id.includes('mcp'))).toBe(true)
+ // MCP mode (defaults to claude-code) should have claude-add-server step
+ expect(stepIds.some((id) => id.includes('claude') || id.includes('mcp'))).toBe(true)
})
test('should resolve different steps for different mcp clients', () => {
diff --git a/apps/studio/components/interfaces/ProjectHome/ConnectSection.config.tsx b/apps/studio/components/interfaces/ProjectHome/ConnectSection.config.tsx
new file mode 100644
index 00000000000..6159be2284a
--- /dev/null
+++ b/apps/studio/components/interfaces/ProjectHome/ConnectSection.config.tsx
@@ -0,0 +1,40 @@
+import { Box, Cable, Database, Sparkles } from 'lucide-react'
+import type { ReactNode } from 'react'
+import type { ConnectMode } from '../ConnectSheet/Connect.types'
+
+// Temporary: experiment variants for the connectSection A/B test. Remove after the experiment.
+export type ConnectSectionVariant = 'connect' | 'getting-started'
+
+export type ConnectAction = {
+ mode: ConnectMode
+ heading: string
+ subheading: string
+ icon: ReactNode
+}
+
+export const CONNECT_ACTIONS: ConnectAction[] = [
+ {
+ mode: 'framework',
+ heading: 'Framework',
+ subheading: 'Use a client library',
+ icon: <Box size={16} strokeWidth={1.5} />,
+ },
+ {
+ mode: 'direct',
+ heading: 'Direct',
+ subheading: 'Connection string',
+ icon: <Database size={16} strokeWidth={1.5} />,
+ },
+ {
+ mode: 'orm',
+ heading: 'ORM',
+ subheading: 'Third-party library',
+ icon: <Cable size={16} strokeWidth={1.5} />,
+ },
+ {
+ mode: 'mcp',
+ heading: 'MCP',
+ subheading: 'Connect your agent',
+ icon: <Sparkles size={16} strokeWidth={1.5} />,
+ },
+]
diff --git a/apps/studio/components/interfaces/ProjectHome/ConnectSection.tsx b/apps/studio/components/interfaces/ProjectHome/ConnectSection.tsx
new file mode 100644
index 00000000000..299153046e9
--- /dev/null
+++ b/apps/studio/components/interfaces/ProjectHome/ConnectSection.tsx
@@ -0,0 +1,97 @@
+import { IS_PLATFORM } from 'common'
+import { useSelectedProjectQuery } from 'hooks/misc/useSelectedProject'
+import { BASE_PATH, PROJECT_STATUS } from 'lib/constants'
+import { useTrack } from 'lib/telemetry/track'
+import { parseAsBoolean, parseAsString, useQueryState } from 'nuqs'
+import { useEffect, useRef } from 'react'
+import { Card, CardContent, cn } from 'ui'
+
+import type { ConnectMode } from '../ConnectSheet/Connect.types'
+import { useAvailableConnectModes } from '../ConnectSheet/useAvailableConnectModes'
+import { useAppStateSnapshot } from '@/state/app-state'
+import { CONNECT_ACTIONS, type ConnectSectionVariant } from './ConnectSection.config'
+
+interface ConnectSectionProps {
+ variant: ConnectSectionVariant
+}
+
+export const ConnectSection = ({ variant }: ConnectSectionProps) => {
+ const { data: selectedProject } = useSelectedProjectQuery()
+ const { setConnectSheetSource } = useAppStateSnapshot()
+ const track = useTrack()
+ const [, setShowConnect] = useQueryState('showConnect', parseAsBoolean.withDefault(false))
+ const [, setConnectTab] = useQueryState('connectTab', parseAsString)
+
+ const isActiveHealthy = selectedProject?.status === PROJECT_STATUS.ACTIVE_HEALTHY
+
+ const availableModeIds = useAvailableConnectModes()
+ const availableActions = CONNECT_ACTIONS.filter((action) =>
+ availableModeIds.includes(action.mode)
+ )
+
+ const hasTrackedExposure = useRef(false)
+
+ useEffect(() => {
+ if (!IS_PLATFORM) return
+ if (hasTrackedExposure.current) return
+ hasTrackedExposure.current = true
+ track('home_connect_section_exposed', { variant })
+ }, [variant, track])
+
+ const handleConnectClick = (mode: ConnectMode) => {
+ track('home_connect_action_clicked', { mode })
+ setConnectTab(mode)
+ setConnectSheetSource('connect_section')
+ setShowConnect(true)
+ }
+
+ return (
+ <section className="w-full">
+ <div className="mb-6">
+ <h3 className="heading-section">Get connected</h3>
+ </div>
+
+ <Card className="bg-background/25 border-dashed relative overflow-hidden">
+ <div className="absolute -inset-16 z-0 opacity-50">
+ <img
+ src={`${BASE_PATH}/img/reports/bg-grafana-dark.svg`}
+ alt=""
+ className="w-full h-full object-cover object-right hidden dark:block"
+ />
+ <img
+ src={`${BASE_PATH}/img/reports/bg-grafana-light.svg`}
+ alt=""
+ className="w-full h-full object-cover object-right dark:hidden"
+ />
+ <div className="absolute inset-0 bg-gradient-to-r from-background-alternative to-transparent" />
+ </div>
+
+ <CardContent className="relative z-10 p-0">
+ <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-4 divide-y md:divide-y-0 md:divide-x border-muted">
+ {availableActions.map((action) => (
+ <button
+ key={action.mode}
+ type="button"
+ disabled={!isActiveHealthy}
+ onClick={() => handleConnectClick(action.mode)}
+ className={cn(
+ 'group flex flex-col items-center justify-center gap-3 p-6 text-center transition-colors min-h-32',
+ 'hover:bg-surface-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand',
+ !isActiveHealthy && 'cursor-not-allowed opacity-50'
+ )}
+ >
+ <span className="text-foreground-light group-hover:text-foreground">
+ {action.icon}
+ </span>
+ <div className="flex flex-col gap-1">
+ <p className="text-sm">{action.heading}</p>
+ <p className="text-sm text-foreground-lighter">{action.subheading}</p>
+ </div>
+ </button>
+ ))}
+ </div>
+ </CardContent>
+ </Card>
+ </section>
+ )
+}
diff --git a/apps/studio/components/interfaces/ProjectHome/Home.tsx b/apps/studio/components/interfaces/ProjectHome/Home.tsx
index ebe2082109f..3939521415b 100644
--- a/apps/studio/components/interfaces/ProjectHome/Home.tsx
+++ b/apps/studio/components/interfaces/ProjectHome/Home.tsx
@@ -8,6 +8,7 @@ import { ScaffoldContainer, ScaffoldSection } from 'components/layouts/Scaffold'
import dayjs from 'dayjs'
import { useLocalStorage } from 'hooks/misc/useLocalStorage'
import { useSelectedProjectQuery } from 'hooks/misc/useSelectedProject'
+import { usePHFlag } from 'hooks/ui/useFlag'
import { PROJECT_STATUS } from 'lib/constants'
import { useTrack } from 'lib/telemetry/track'
import { useEffect, useRef } from 'react'
@@ -15,9 +16,12 @@ import { useAppStateSnapshot } from 'state/app-state'
import { cn } from 'ui'
import { AdvisorSection } from './AdvisorSection'
+import { ConnectSection } from './ConnectSection'
+import type { ConnectSectionVariant } from './ConnectSection.config'
import { CustomReportSection } from './CustomReportSection'
import { type GettingStartedState } from './GettingStarted/GettingStarted.types'
import { GettingStartedSection } from './GettingStarted/GettingStartedSection'
+import { DEFAULT_SECTION_ORDER, mergeSectionOrder, getSectionVisibility } from './Home.utils'
import { ProjectUsageSection as ProjectUsageSectionV2 } from './ProjectUsageSection'
export const ProjectHome = () => {
@@ -27,6 +31,7 @@ export const ProjectHome = () => {
const track = useTrack()
const showHomepageUsageV2 = useFlag('newHomepageUsageV2')
+ const connectSectionVariant = usePHFlag<ConnectSectionVariant | false>('connectSection')
const isMatureProject = dayjs(project?.inserted_at).isBefore(dayjs().subtract(10, 'day'))
@@ -36,7 +41,7 @@ export const ProjectHome = () => {
const [sectionOrder, setSectionOrder] = useLocalStorage<string[]>(
`home-section-order-${project?.ref || 'default'}`,
- ['getting-started', 'usage', 'advisor', 'custom-report']
+ DEFAULT_SECTION_ORDER
)
const [gettingStartedState, setGettingStartedState] = useLocalStorage<GettingStartedState>(
@@ -73,6 +78,17 @@ export const ProjectHome = () => {
}
}, [enableBranching, snap])
+ useEffect(() => {
+ setSectionOrder(mergeSectionOrder)
+ }, [setSectionOrder])
+
+ const { showConnectSection, showGettingStarted } = getSectionVisibility({
+ connectSectionVariant,
+ isMatureProject,
+ hasProject: !!project,
+ gettingStartedState,
+ })
+
return (
<div className="w-full h-full">
<ScaffoldContainer size="large" className={cn(isPaused && 'h-full')}>
@@ -88,9 +104,11 @@ export const ProjectHome = () => {
<ScaffoldSection isFullWidth className="gap-16 pb-32">
<DndContext sensors={sensors} onDragEnd={handleDragEnd}>
<SortableContext
- items={sectionOrder.filter(
- (id) => id !== 'getting-started' || gettingStartedState !== 'hidden'
- )}
+ items={sectionOrder.filter((id) => {
+ if (id === 'connect') return showConnectSection
+ if (id === 'getting-started') return showGettingStarted
+ return true
+ })}
strategy={verticalListSortingStrategy}
>
{sectionOrder.map((id) => {
@@ -103,12 +121,14 @@ export const ProjectHome = () => {
</div>
)
}
- if (
- id === 'getting-started' &&
- !isMatureProject &&
- project &&
- gettingStartedState !== 'hidden'
- ) {
+ if (id === 'connect' && showConnectSection) {
+ return (
+ <SortableSection key={id} id={id}>
+ <ConnectSection variant={connectSectionVariant as ConnectSectionVariant} />
+ </SortableSection>
+ )
+ }
+ if (id === 'getting-started' && showGettingStarted) {
return (
<SortableSection key={id} id={id}>
<GettingStartedSection
diff --git a/apps/studio/components/interfaces/ProjectHome/Home.utils.test.ts b/apps/studio/components/interfaces/ProjectHome/Home.utils.test.ts
new file mode 100644
index 00000000000..f4f00e86a1e
--- /dev/null
+++ b/apps/studio/components/interfaces/ProjectHome/Home.utils.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest'
+
+import { mergeSectionOrder, getSectionVisibility } from './Home.utils'
+
+describe('mergeSectionOrder', () => {
+ it('returns stored order unchanged when it matches defaults', () => {
+ const stored = ['connect', 'getting-started', 'usage', 'advisor', 'custom-report']
+ expect(mergeSectionOrder(stored)).toBe(stored)
+ })
+
+ it('inserts missing sections at their default-relative position', () => {
+ expect(mergeSectionOrder(['usage', 'advisor', 'custom-report'])).toEqual([
+ 'connect',
+ 'getting-started',
+ 'usage',
+ 'advisor',
+ 'custom-report',
+ ])
+ })
+
+ it('preserves user reordering while inserting missing sections', () => {
+ expect(mergeSectionOrder(['getting-started', 'advisor', 'usage', 'custom-report'])).toEqual([
+ 'connect',
+ 'getting-started',
+ 'advisor',
+ 'usage',
+ 'custom-report',
+ ])
+ })
+
+ it('strips unknown sections from stored order', () => {
+ expect(mergeSectionOrder(['usage', 'deleted-section', 'advisor', 'custom-report'])).toEqual([
+ 'connect',
+ 'getting-started',
+ 'usage',
+ 'advisor',
+ 'custom-report',
+ ])
+ })
+})
+
+describe('getSectionVisibility', () => {
+ const base = {
+ connectSectionVariant: 'connect' as const,
+ isMatureProject: false,
+ hasProject: true,
+ gettingStartedState: 'empty' as const,
+ }
+
+ it('shows connect section for connect variant on new project', () => {
+ expect(getSectionVisibility(base)).toEqual({
+ showConnectSection: true,
+ showGettingStarted: false,
+ })
+ })
+
+ it('shows getting started for non-connect variant', () => {
+ expect(getSectionVisibility({ ...base, connectSectionVariant: 'getting-started' })).toEqual({
+ showConnectSection: false,
+ showGettingStarted: true,
+ })
+ })
+
+ it('shows neither when flag is unresolved', () => {
+ expect(getSectionVisibility({ ...base, connectSectionVariant: undefined })).toEqual({
+ showConnectSection: false,
+ showGettingStarted: false,
+ })
+ })
+
+ it('shows neither for mature projects', () => {
+ expect(getSectionVisibility({ ...base, isMatureProject: true })).toEqual({
+ showConnectSection: false,
+ showGettingStarted: false,
+ })
+ })
+
+ it('hides getting started when user dismissed it', () => {
+ expect(
+ getSectionVisibility({
+ ...base,
+ connectSectionVariant: 'getting-started',
+ gettingStartedState: 'hidden',
+ })
+ ).toEqual({
+ showConnectSection: false,
+ showGettingStarted: false,
+ })
+ })
+
+ it('shows getting started when flag resolved to false (control group)', () => {
+ expect(getSectionVisibility({ ...base, connectSectionVariant: false })).toEqual({
+ showConnectSection: false,
+ showGettingStarted: true,
+ })
+ })
+
+ it('shows neither when project is missing', () => {
+ expect(getSectionVisibility({ ...base, hasProject: false })).toEqual({
+ showConnectSection: false,
+ showGettingStarted: false,
+ })
+ })
+})
diff --git a/apps/studio/components/interfaces/ProjectHome/Home.utils.ts b/apps/studio/components/interfaces/ProjectHome/Home.utils.ts
new file mode 100644
index 00000000000..713ab06bcb0
--- /dev/null
+++ b/apps/studio/components/interfaces/ProjectHome/Home.utils.ts
@@ -0,0 +1,55 @@
+import type { GettingStartedState } from './GettingStarted/GettingStarted.types'
+import type { ConnectSectionVariant } from './ConnectSection.config'
+
+export const DEFAULT_SECTION_ORDER = [
+ 'connect',
+ 'getting-started',
+ 'usage',
+ 'advisor',
+ 'custom-report',
+]
+
+/**
+ * Reconciles a stored section order with the canonical list.
+ * Preserves user ordering for known sections, inserts missing
+ * sections at their default-relative position.
+ */
+export function mergeSectionOrder(stored: string[]): string[] {
+ const known = stored.filter((id) => DEFAULT_SECTION_ORDER.includes(id))
+ const missing = DEFAULT_SECTION_ORDER.filter((id) => !known.includes(id))
+
+ if (missing.length === 0 && known.length === stored.length) return stored
+
+ const merged = [...known]
+ for (const id of missing) {
+ const defaultIndex = DEFAULT_SECTION_ORDER.indexOf(id)
+ const nextKnown = DEFAULT_SECTION_ORDER.slice(defaultIndex + 1).find((c) => merged.includes(c))
+
+ if (!nextKnown) {
+ merged.push(id)
+ } else {
+ merged.splice(merged.indexOf(nextKnown), 0, id)
+ }
+ }
+ return merged
+}
+
+// Temporary: getSectionVisibility and related types support the connectSection
+// experiment (connect vs getting-started). Remove after the experiment concludes.
+interface SectionVisibilityInput {
+ connectSectionVariant: ConnectSectionVariant | false | undefined
+ isMatureProject: boolean
+ hasProject: boolean
+ gettingStartedState: GettingStartedState
+}
+
+export function getSectionVisibility(input: SectionVisibilityInput) {
+ const { connectSectionVariant, isMatureProject, hasProject, gettingStartedState } = input
+ const canShowEither = connectSectionVariant !== undefined && !isMatureProject && hasProject
+
+ return {
+ showConnectSection: canShowEither && connectSectionVariant === 'connect',
+ showGettingStarted:
+ canShowEither && connectSectionVariant !== 'connect' && gettingStartedState !== 'hidden',
+ }
+}
diff --git a/apps/studio/components/layouts/ProjectLayout/LayoutHeader/LayoutHeader.tsx b/apps/studio/components/layouts/ProjectLayout/LayoutHeader/LayoutHeader.tsx
index 08fcbf376d3..bb7a25432ee 100644
--- a/apps/studio/components/layouts/ProjectLayout/LayoutHeader/LayoutHeader.tsx
+++ b/apps/studio/components/layouts/ProjectLayout/LayoutHeader/LayoutHeader.tsx
@@ -33,6 +33,7 @@ import { MergeRequestButton } from './MergeRequestButton'
import { Connect } from '@/components/interfaces/Connect/Connect'
import { ConnectButton } from '@/components/interfaces/ConnectButton/ConnectButton'
import { ConnectSheet } from '@/components/interfaces/ConnectSheet/ConnectSheet'
+import type { ConnectSectionVariant } from '@/components/interfaces/ProjectHome/ConnectSection.config'
import { usePHFlag } from '@/hooks/ui/useFlag'
const LayoutHeaderDivider = ({ className, ...props }: React.HTMLProps<HTMLSpanElement>) => (
@@ -75,9 +76,9 @@ export const LayoutHeader = ({
const { data: selectedOrganization } = useSelectedOrganizationQuery()
const gitlessBranching = useIsBranching2Enabled()
- const connectSheetFlag = usePHFlag<string | boolean>('connectSheet')
- const isFlagResolved = connectSheetFlag !== undefined
- const isConnectSheetEnabled = connectSheetFlag === true || connectSheetFlag === 'variation'
+ const connectSectionVariant = usePHFlag<ConnectSectionVariant | false>('connectSection')
+ const isFlagResolved = connectSectionVariant !== undefined
+ const isConnectSheetEnabled = connectSectionVariant === 'connect'
const [commandMenuEnabled] = useLocalStorageQuery(LOCAL_STORAGE_KEYS.HOTKEY_COMMAND_MENU, true)
diff --git a/apps/studio/state/app-state.ts b/apps/studio/state/app-state.ts
index aed3c6826e8..984f5864703 100644
--- a/apps/studio/state/app-state.ts
+++ b/apps/studio/state/app-state.ts
@@ -71,6 +71,11 @@ export const appState = proxy({
appState.mobileMenuOpen = value
},
+ connectSheetSource: 'header_button' as 'header_button' | 'connect_section',
+ setConnectSheetSource: (value: 'header_button' | 'connect_section') => {
+ appState.connectSheetSource = value
+ },
+
lastRouteBeforeVisitingAccountPage: '',
setLastRouteBeforeVisitingAccountPage: (value: string) => {
appState.lastRouteBeforeVisitingAccountPage = value
diff --git a/packages/common/telemetry-constants.ts b/packages/common/telemetry-constants.ts
index 2c543cee321..9ff732856ea 100644
--- a/packages/common/telemetry-constants.ts
+++ b/packages/common/telemetry-constants.ts
@@ -1940,6 +1940,60 @@ export interface HomeNewExperimentExposedEvent {
groups: TelemetryGroups
}
+/**
+ * Connect section was shown to the user as part of the connectSection experiment.
+ *
+ * @group Events
+ * @source studio
+ * @page /project/{ref}
+ */
+export interface HomeConnectSectionExposedEvent {
+ action: 'home_connect_section_exposed'
+ properties: {
+ /**
+ * The experiment variant shown to the user
+ */
+ variant: 'connect' | 'getting-started'
+ }
+ groups: TelemetryGroups
+}
+
+/**
+ * User clicked a connect action tile in the Connect section on the project homepage.
+ *
+ * @group Events
+ * @source studio
+ * @page /project/{ref}
+ */
+export interface HomeConnectActionClickedEvent {
+ action: 'home_connect_action_clicked'
+ properties: {
+ /**
+ * The connect mode that was clicked
+ */
+ mode: 'framework' | 'direct' | 'orm' | 'mcp'
+ }
+ groups: TelemetryGroups
+}
+
+/**
+ * User opened the ConnectSheet panel.
+ *
+ * @group Events
+ * @source studio
+ * @page /project/{ref}
+ */
+export interface ConnectSheetOpenedEvent {
+ action: 'connect_sheet_opened'
+ properties: {
+ /**
+ * Where the sheet was opened from
+ */
+ source: 'header_button' | 'connect_section'
+ }
+ groups: TelemetryGroups
+}
+
/**
* User reordered sections in HomeV2 using drag and drop.
*
@@ -2987,6 +3041,9 @@ export type TelemetryEvent =
| HomeGettingStartedClosedEvent
| HomeGettingStartedSectionExposedEvent
| HomeNewExperimentExposedEvent
+ | HomeConnectSectionExposedEvent
+ | HomeConnectActionClickedEvent
+ | ConnectSheetOpenedEvent
| HomeSectionRowsMovedEvent
| HomeActivityStatClickedEvent
| HomeProjectUsageServiceClickedEvent