Component Refactoring

Component Refactoring Skill

Refactor high-complexity React components with the patterns and workflow below.

Core Refactoring Patterns

Pattern 1: Extract Custom Hooks

When: Component has complex state management, multiple useState/useEffect, or business logic mixed with UI.

Dify Convention: Place hooks in a hooks/ subdirectory or alongside the component as use-<feature>.ts.

// ❌ Before: Complex state logic in component
const Configuration: FC = () => {
  const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
  const [datasetConfigs, setDatasetConfigs] = useState<DatasetConfigs>(...)
  const [completionParams, setCompletionParams] = useState<FormValue>({})

  // 50+ lines of state management logic...

  return <div>...</div>
}

// ✅ After: Extract to custom hook
// hooks/use-model-config.ts
export const useModelConfig = (appId: string) => {
  const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
  const [completionParams, setCompletionParams] = useState<FormValue>({})

  // Related state management logic here

  return { modelConfig, setModelConfig, completionParams, setCompletionParams }
}

// Component becomes cleaner
const Configuration: FC = () => {
  const { modelConfig, setModelConfig } = useModelConfig(appId)
  return <div>...</div>
}

Pattern 2: Extract Sub-Components

When: Single component has multiple UI sections, conditional rendering blocks, or repeated patterns.

// ❌ Before: Monolithic JSX with multiple sections
const AppInfo = () => {
  return (
    <div>
      {/* 100 lines of header UI */}
      {/* 100 lines of operations UI */}
      {/* 100 lines of modals */}
    </div>
  )
}

// ✅ After: Split into focused components
// app-info/
//   ├── index.tsx           (orchestration only)
//   ├── app-header.tsx      (header UI)
//   ├── app-operations.tsx  (operations UI)
//   └── app-modals.tsx      (modal management)

const AppInfo = () => {
  const { showModal, setShowModal } = useAppInfoModals()

  return (
    <div>
      <AppHeader appDetail={appDetail} />
      <AppOperations onAction={handleAction} />
      <AppModals show={showModal} onClose={() => setShowModal(null)} />
    </div>
  )
}

Pattern 3: Simplify Conditional Logic

When: Deep nesting (> 3 levels), complex ternaries, or multiple if/else chains.

// ❌ Before: Deeply nested conditionals
const Template = useMemo(() => {
  if (appDetail?.mode === AppModeEnum.CHAT) {
    switch (locale) {
      case LanguagesSupported[1]:
        return <TemplateChatZh />
      case LanguagesSupported[7]:
        return <TemplateChatJa />
      default:
        return <TemplateChatEn />
    }
  }
  if (appDetail?.mode === AppModeEnum.ADVANCED_CHAT) {
    // Another 15 lines...
  }
  // More conditions...
}, [appDetail, locale])

// ✅ After: Use lookup tables + early returns
const TEMPLATE_MAP = {
  [AppModeEnum.CHAT]: {
    [LanguagesSupported[1]]: TemplateChatZh,
    [LanguagesSupported[7]]: TemplateChatJa,
    default: TemplateChatEn,
  },
  [AppModeEnum.ADVANCED_CHAT]: {
    [LanguagesSupported[1]]: TemplateAdvancedChatZh,
    // ...
  },
}

const Template = useMemo(() => {
  const modeTemplates = TEMPLATE_MAP[appDetail?.mode]
  if (!modeTemplates) return null

  const TemplateComponent = modeTemplates[locale] || modeTemplates.default
  return <TemplateComponent appDetail={appDetail} />
}, [appDetail, locale])

Pattern 4: Extract API/Data Logic

When: Component directly handles API calls, data transformation, or complex async operations.

// ❌ Before: API logic in component
const MCPServiceCard = () => {
  const [basicAppConfig, setBasicAppConfig] = useState({})

  useEffect(() => {
    if (isBasicApp && appId) {
      (async () => {
        const res = await fetchAppDetail({ url: '/apps', id: appId })
        setBasicAppConfig(res?.model_config || {})
      })()
    }
  }, [appId, isBasicApp])

  // More API-related logic...
}

// ✅ After: Extract to data hook using React Query
// use-app-config.ts
import { useQuery } from '@tanstack/react-query'
import { get } from '@/service/base'

const NAME_SPACE = 'appConfig'

export const useAppConfig = (appId: string, isBasicApp: boolean) => {
  return useQuery({
    enabled: isBasicApp && !!appId,
    queryKey: [NAME_SPACE, 'detail', appId],
    queryFn: () => get<AppDetailResponse>(`/apps/${appId}`),
    select: data => data?.model_config || {},
  })
}

// Component becomes cleaner
const MCPServiceCard = () => {
  const { data: config, isLoading } = useAppConfig(appId, isBasicApp)
  // UI only
}

React Query Best Practices:

• Define NAME_SPACE for query key organization
• Use enabled option for conditional fetching
• Use select for data transformation
• Export invalidation hooks: useInvalidXxx

Pattern 5: Extract Modal/Dialog Management

When: Component manages multiple modals with complex open/close states.

// ❌ Before: Multiple modal states in component
const AppInfo = () => {
  const [showEditModal, setShowEditModal] = useState(false)
  const [showDuplicateModal, setShowDuplicateModal] = useState(false)
  const [showConfirmDelete, setShowConfirmDelete] = useState(false)
  const [showSwitchModal, setShowSwitchModal] = useState(false)
  const [showImportDSLModal, setShowImportDSLModal] = useState(false)
  // 5+ more modal states...
}

// ✅ After: Extract to modal management hook
type ModalType = 'edit' | 'duplicate' | 'delete' | 'switch' | 'import' | null

const useAppInfoModals = () => {
  const [activeModal, setActiveModal] = useState<ModalType>(null)

  const openModal = useCallback((type: ModalType) => setActiveModal(type), [])
  const closeModal = useCallback(() => setActiveModal(null), [])

  return {
    activeModal,
    openModal,
    closeModal,
    isOpen: (type: ModalType) => activeModal === type,
  }
}

Common Mistakes to Avoid

❌ Over-Engineering

// ❌ Too many tiny hooks
const useButtonText = () => useState('Click')
const useButtonDisabled = () => useState(false)
const useButtonLoading = () => useState(false)

// ✅ Cohesive hook with related state
const useButtonState = () => {
  const [text, setText] = useState('Click')
  const [disabled, setDisabled] = useState(false)
  const [loading, setLoading] = useState(false)
  return { text, setText, disabled, setDisabled, loading, setLoading }
}

❌ Breaking Existing Patterns

• Follow existing directory structures
• Maintain naming conventions
• Preserve export patterns for compatibility

❌ Premature Abstraction

• Only extract when there's clear complexity benefit
• Don't create abstractions for single-use code
• Keep refactored code in the same domain area

References

Related Skills

• frontend-testing - For testing refactored components

Complexity Reduction Patterns

This document provides patterns for reducing cognitive complexity in React components.

Understanding Complexity

What Increases Complexity

Pattern 1: Replace Conditionals with Lookup Tables

Before (complexity: ~15):

const Template = useMemo(() => {
  if (appDetail?.mode === AppModeEnum.CHAT) {
    switch (locale) {
      case LanguagesSupported[1]:
        return <TemplateChatZh appDetail={appDetail} />
      case LanguagesSupported[7]:
        return <TemplateChatJa appDetail={appDetail} />
      default:
        return <TemplateChatEn appDetail={appDetail} />
    }
  }
  if (appDetail?.mode === AppModeEnum.ADVANCED_CHAT) {
    switch (locale) {
      case LanguagesSupported[1]:
        return <TemplateAdvancedChatZh appDetail={appDetail} />
      case LanguagesSupported[7]:
        return <TemplateAdvancedChatJa appDetail={appDetail} />
      default:
        return <TemplateAdvancedChatEn appDetail={appDetail} />
    }
  }
  if (appDetail?.mode === AppModeEnum.WORKFLOW) {
    // Similar pattern...
  }
  return null
}, [appDetail, locale])

After (complexity: ~3):

// Define lookup table outside component
const TEMPLATE_MAP: Record<AppModeEnum, Record<string, FC<TemplateProps>>> = {
  [AppModeEnum.CHAT]: {
    [LanguagesSupported[1]]: TemplateChatZh,
    [LanguagesSupported[7]]: TemplateChatJa,
    default: TemplateChatEn,
  },
  [AppModeEnum.ADVANCED_CHAT]: {
    [LanguagesSupported[1]]: TemplateAdvancedChatZh,
    [LanguagesSupported[7]]: TemplateAdvancedChatJa,
    default: TemplateAdvancedChatEn,
  },
  [AppModeEnum.WORKFLOW]: {
    [LanguagesSupported[1]]: TemplateWorkflowZh,
    [LanguagesSupported[7]]: TemplateWorkflowJa,
    default: TemplateWorkflowEn,
  },
  // ...
}

// Clean component logic
const Template = useMemo(() => {
  if (!appDetail?.mode) return null

  const templates = TEMPLATE_MAP[appDetail.mode]
  if (!templates) return null

  const TemplateComponent = templates[locale] ?? templates.default
  return <TemplateComponent appDetail={appDetail} />
}, [appDetail, locale])

Pattern 2: Use Early Returns

Before (complexity: ~10):

const handleSubmit = () => {
  if (isValid) {
    if (hasChanges) {
      if (isConnected) {
        submitData()
      } else {
        showConnectionError()
      }
    } else {
      showNoChangesMessage()
    }
  } else {
    showValidationError()
  }
}

After (complexity: ~4):

const handleSubmit = () => {
  if (!isValid) {
    showValidationError()
    return
  }

  if (!hasChanges) {
    showNoChangesMessage()
    return
  }

  if (!isConnected) {
    showConnectionError()
    return
  }

  submitData()
}

Pattern 3: Extract Complex Conditions

Before (complexity: high):

const canPublish = (() => {
  if (mode !== AppModeEnum.COMPLETION) {
    if (!isAdvancedMode)
      return true

    if (modelModeType === ModelModeType.completion) {
      if (!hasSetBlockStatus.history || !hasSetBlockStatus.query)
        return false
      return true
    }
    return true
  }
  return !promptEmpty
})()

After (complexity: lower):

// Extract to named functions
const canPublishInCompletionMode = () => !promptEmpty

const canPublishInChatMode = () => {
  if (!isAdvancedMode) return true
  if (modelModeType !== ModelModeType.completion) return true
  return hasSetBlockStatus.history && hasSetBlockStatus.query
}

// Clean main logic
const canPublish = mode === AppModeEnum.COMPLETION
  ? canPublishInCompletionMode()
  : canPublishInChatMode()

Pattern 4: Replace Chained Ternaries

Before (complexity: ~5):

const statusText = serverActivated
  ? t('status.running')
  : serverPublished
    ? t('status.inactive')
    : appUnpublished
      ? t('status.unpublished')
      : t('status.notConfigured')

After (complexity: ~2):

const getStatusText = () => {
  if (serverActivated) return t('status.running')
  if (serverPublished) return t('status.inactive')
  if (appUnpublished) return t('status.unpublished')
  return t('status.notConfigured')
}

const statusText = getStatusText()

Or use lookup:

const STATUS_TEXT_MAP = {
  running: 'status.running',
  inactive: 'status.inactive',
  unpublished: 'status.unpublished',
  notConfigured: 'status.notConfigured',
} as const

const getStatusKey = (): keyof typeof STATUS_TEXT_MAP => {
  if (serverActivated) return 'running'
  if (serverPublished) return 'inactive'
  if (appUnpublished) return 'unpublished'
  return 'notConfigured'
}

const statusText = t(STATUS_TEXT_MAP[getStatusKey()])

Pattern 5: Flatten Nested Loops

Before (complexity: high):

const processData = (items: Item[]) => {
  const results: ProcessedItem[] = []

  for (const item of items) {
    if (item.isValid) {
      for (const child of item.children) {
        if (child.isActive) {
          for (const prop of child.properties) {
            if (prop.value !== null) {
              results.push({
                itemId: item.id,
                childId: child.id,
                propValue: prop.value,
              })
            }
          }
        }
      }
    }
  }

  return results
}

After (complexity: lower):

// Use functional approach
const processData = (items: Item[]) => {
  return items
    .filter(item => item.isValid)
    .flatMap(item =>
      item.children
        .filter(child => child.isActive)
        .flatMap(child =>
          child.properties
            .filter(prop => prop.value !== null)
            .map(prop => ({
              itemId: item.id,
              childId: child.id,
              propValue: prop.value,
            }))
        )
    )
}

Pattern 6: Extract Event Handler Logic

Before (complexity: high in component):

const Component = () => {
  const handleSelect = (data: DataSet[]) => {
    if (isEqual(data.map(item => item.id), dataSets.map(item => item.id))) {
      hideSelectDataSet()
      return
    }

    formattingChangedDispatcher()
    let newDatasets = data
    if (data.find(item => !item.name)) {
      const newSelected = produce(data, (draft) => {
        data.forEach((item, index) => {
          if (!item.name) {
            const newItem = dataSets.find(i => i.id === item.id)
            if (newItem)
              draft[index] = newItem
          }
        })
      })
      setDataSets(newSelected)
      newDatasets = newSelected
    }
    else {
      setDataSets(data)
    }
    hideSelectDataSet()

    // 40 more lines of logic...
  }

  return <div>...</div>
}

After (complexity: lower):

// Extract to hook or utility
const useDatasetSelection = (dataSets: DataSet[], setDataSets: SetState<DataSet[]>) => {
  const normalizeSelection = (data: DataSet[]) => {
    const hasUnloadedItem = data.some(item => !item.name)
    if (!hasUnloadedItem) return data

    return produce(data, (draft) => {
      data.forEach((item, index) => {
        if (!item.name) {
          const existing = dataSets.find(i => i.id === item.id)
          if (existing) draft[index] = existing
        }
      })
    })
  }

  const hasSelectionChanged = (newData: DataSet[]) => {
    return !isEqual(
      newData.map(item => item.id),
      dataSets.map(item => item.id)
    )
  }

  return { normalizeSelection, hasSelectionChanged }
}

// Component becomes cleaner
const Component = () => {
  const { normalizeSelection, hasSelectionChanged } = useDatasetSelection(dataSets, setDataSets)

  const handleSelect = (data: DataSet[]) => {
    if (!hasSelectionChanged(data)) {
      hideSelectDataSet()
      return
    }

    formattingChangedDispatcher()
    const normalized = normalizeSelection(data)
    setDataSets(normalized)
    hideSelectDataSet()
  }

  return <div>...</div>
}

Pattern 7: Reduce Boolean Logic Complexity

Before (complexity: ~8):

const toggleDisabled = hasInsufficientPermissions
  || appUnpublished
  || missingStartNode
  || triggerModeDisabled
  || (isAdvancedApp && !currentWorkflow?.graph)
  || (isBasicApp && !basicAppConfig.updated_at)

After (complexity: ~3):

// Extract meaningful boolean functions
const isAppReady = () => {
  if (isAdvancedApp) return !!currentWorkflow?.graph
  return !!basicAppConfig.updated_at
}

const hasRequiredPermissions = () => {
  return isCurrentWorkspaceEditor && !hasInsufficientPermissions
}

const canToggle = () => {
  if (!hasRequiredPermissions()) return false
  if (!isAppReady()) return false
  if (missingStartNode) return false
  if (triggerModeDisabled) return false
  return true
}

const toggleDisabled = !canToggle()

Pattern 8: Simplify useMemo/useCallback Dependencies

Before (complexity: multiple recalculations):

const payload = useMemo(() => {
  let parameters: Parameter[] = []
  let outputParameters: OutputParameter[] = []

  if (!published) {
    parameters = (inputs || []).map((item) => ({
      name: item.variable,
      description: '',
      form: 'llm',
      required: item.required,
      type: item.type,
    }))
    outputParameters = (outputs || []).map((item) => ({
      name: item.variable,
      description: '',
      type: item.value_type,
    }))
  }
  else if (detail && detail.tool) {
    parameters = (inputs || []).map((item) => ({
      // Complex transformation...
    }))
    outputParameters = (outputs || []).map((item) => ({
      // Complex transformation...
    }))
  }

  return {
    icon: detail?.icon || icon,
    label: detail?.label || name,
    // ...more fields
  }
}, [detail, published, workflowAppId, icon, name, description, inputs, outputs])

After (complexity: separated concerns):

// Separate transformations
const useParameterTransform = (inputs: InputVar[], detail?: ToolDetail, published?: boolean) => {
  return useMemo(() => {
    if (!published) {
      return inputs.map(item => ({
        name: item.variable,
        description: '',
        form: 'llm',
        required: item.required,
        type: item.type,
      }))
    }

    if (!detail?.tool) return []

    return inputs.map(item => ({
      name: item.variable,
      required: item.required,
      type: item.type === 'paragraph' ? 'string' : item.type,
      description: detail.tool.parameters.find(p => p.name === item.variable)?.llm_description || '',
      form: detail.tool.parameters.find(p => p.name === item.variable)?.form || 'llm',
    }))
  }, [inputs, detail, published])
}

// Component uses hook
const parameters = useParameterTransform(inputs, detail, published)
const outputParameters = useOutputTransform(outputs, detail, published)

const payload = useMemo(() => ({
  icon: detail?.icon || icon,
  label: detail?.label || name,
  parameters,
  outputParameters,
  // ...
}), [detail, icon, name, parameters, outputParameters])

Target Metrics After Refactoring

Component Splitting Patterns

This document provides detailed guidance on splitting large components into smaller, focused components.

When to Split Components

Split a component when you identify:

1. Multiple UI sections - Distinct visual areas with minimal coupling that can be composed independently 1. Conditional rendering blocks - Large {condition && <JSX />} blocks 1. Repeated patterns - Similar UI structures used multiple times 1. 300+ lines - Component exceeds manageable size 1. Modal clusters - Multiple modals rendered in one component

Splitting Strategies

Strategy 1: Section-Based Splitting

Identify visual sections and extract each as a component.

// ❌ Before: Monolithic component (500+ lines)
const ConfigurationPage = () => {
  return (
    <div>
      {/* Header Section - 50 lines */}
      <div className="header">
        <h1>{t('configuration.title')}</h1>
        <div className="actions">
          {isAdvancedMode && <Badge>Advanced</Badge>}
          <ModelParameterModal ... />
          <AppPublisher ... />
        </div>
      </div>

      {/* Config Section - 200 lines */}
      <div className="config">
        <Config />
      </div>

      {/* Debug Section - 150 lines */}
      <div className="debug">
        <Debug ... />
      </div>

      {/* Modals Section - 100 lines */}
      {showSelectDataSet && <SelectDataSet ... />}
      {showHistoryModal && <EditHistoryModal ... />}
      {showUseGPT4Confirm && <Confirm ... />}
    </div>
  )
}

// ✅ After: Split into focused components
// configuration/
//   ├── index.tsx              (orchestration)
//   ├── configuration-header.tsx
//   ├── configuration-content.tsx
//   ├── configuration-debug.tsx
//   └── configuration-modals.tsx

// configuration-header.tsx
interface ConfigurationHeaderProps {
  isAdvancedMode: boolean
  onPublish: () => void
}

const ConfigurationHeader: FC<ConfigurationHeaderProps> = ({
  isAdvancedMode,
  onPublish,
}) => {
  const { t } = useTranslation()

  return (
    <div className="header">
      <h1>{t('configuration.title')}</h1>
      <div className="actions">
        {isAdvancedMode && <Badge>Advanced</Badge>}
        <ModelParameterModal ... />
        <AppPublisher onPublish={onPublish} />
      </div>
    </div>
  )
}

// index.tsx (orchestration only)
const ConfigurationPage = () => {
  const { modelConfig, setModelConfig } = useModelConfig()
  const { activeModal, openModal, closeModal } = useModalState()

  return (
    <div>
      <ConfigurationHeader
        isAdvancedMode={isAdvancedMode}
        onPublish={handlePublish}
      />
      <ConfigurationContent
        modelConfig={modelConfig}
        onConfigChange={setModelConfig}
      />
      {!isMobile && (
        <ConfigurationDebug
          inputs={inputs}
          onSetting={handleSetting}
        />
      )}
      <ConfigurationModals
        activeModal={activeModal}
        onClose={closeModal}
      />
    </div>
  )
}

Strategy 2: Conditional Block Extraction

Extract large conditional rendering blocks.

// ❌ Before: Large conditional blocks
const AppInfo = () => {
  return (
    <div>
      {expand ? (
        <div className="expanded">
          {/* 100 lines of expanded view */}
        </div>
      ) : (
        <div className="collapsed">
          {/* 50 lines of collapsed view */}
        </div>
      )}
    </div>
  )
}

// ✅ After: Separate view components
const AppInfoExpanded: FC<AppInfoViewProps> = ({ appDetail, onAction }) => {
  return (
    <div className="expanded">
      {/* Clean, focused expanded view */}
    </div>
  )
}

const AppInfoCollapsed: FC<AppInfoViewProps> = ({ appDetail, onAction }) => {
  return (
    <div className="collapsed">
      {/* Clean, focused collapsed view */}
    </div>
  )
}

const AppInfo = () => {
  return (
    <div>
      {expand
        ? <AppInfoExpanded appDetail={appDetail} onAction={handleAction} />
        : <AppInfoCollapsed appDetail={appDetail} onAction={handleAction} />
      }
    </div>
  )
}

Strategy 3: Modal Extraction

Extract modals with their trigger logic.

// ❌ Before: Multiple modals in one component
const AppInfo = () => {
  const [showEdit, setShowEdit] = useState(false)
  const [showDuplicate, setShowDuplicate] = useState(false)
  const [showDelete, setShowDelete] = useState(false)
  const [showSwitch, setShowSwitch] = useState(false)

  const onEdit = async (data) => { /* 20 lines */ }
  const onDuplicate = async (data) => { /* 20 lines */ }
  const onDelete = async () => { /* 15 lines */ }

  return (
    <div>
      {/* Main content */}

      {showEdit && <EditModal onConfirm={onEdit} onClose={() => setShowEdit(false)} />}
      {showDuplicate && <DuplicateModal onConfirm={onDuplicate} onClose={() => setShowDuplicate(false)} />}
      {showDelete && <DeleteConfirm onConfirm={onDelete} onClose={() => setShowDelete(false)} />}
      {showSwitch && <SwitchModal ... />}
    </div>
  )
}

// ✅ After: Modal manager component
// app-info-modals.tsx
type ModalType = 'edit' | 'duplicate' | 'delete' | 'switch' | null

interface AppInfoModalsProps {
  appDetail: AppDetail
  activeModal: ModalType
  onClose: () => void
  onSuccess: () => void
}

const AppInfoModals: FC<AppInfoModalsProps> = ({
  appDetail,
  activeModal,
  onClose,
  onSuccess,
}) => {
  const handleEdit = async (data) => { /* logic */ }
  const handleDuplicate = async (data) => { /* logic */ }
  const handleDelete = async () => { /* logic */ }

  return (
    <>
      {activeModal === 'edit' && (
        <EditModal
          appDetail={appDetail}
          onConfirm={handleEdit}
          onClose={onClose}
        />
      )}
      {activeModal === 'duplicate' && (
        <DuplicateModal
          appDetail={appDetail}
          onConfirm={handleDuplicate}
          onClose={onClose}
        />
      )}
      {activeModal === 'delete' && (
        <DeleteConfirm
          onConfirm={handleDelete}
          onClose={onClose}
        />
      )}
      {activeModal === 'switch' && (
        <SwitchModal
          appDetail={appDetail}
          onClose={onClose}
        />
      )}
    </>
  )
}

// Parent component
const AppInfo = () => {
  const { activeModal, openModal, closeModal } = useModalState()

  return (
    <div>
      {/* Main content with openModal triggers */}
      <Button onClick={() => openModal('edit')}>Edit</Button>

      <AppInfoModals
        appDetail={appDetail}
        activeModal={activeModal}
        onClose={closeModal}
        onSuccess={handleSuccess}
      />
    </div>
  )
}

Strategy 4: List Item Extraction

Extract repeated item rendering.

// ❌ Before: Inline item rendering
const OperationsList = () => {
  return (
    <div>
      {operations.map(op => (
        <div key={op.id} className="operation-item">
          <span className="icon">{op.icon}</span>
          <span className="title">{op.title}</span>
          <span className="description">{op.description}</span>
          <button onClick={() => op.onClick()}>
            {op.actionLabel}
          </button>
          {op.badge && <Badge>{op.badge}</Badge>}
          {/* More complex rendering... */}
        </div>
      ))}
    </div>
  )
}

// ✅ After: Extracted item component
interface OperationItemProps {
  operation: Operation
  onAction: (id: string) => void
}

const OperationItem: FC<OperationItemProps> = ({ operation, onAction }) => {
  return (
    <div className="operation-item">
      <span className="icon">{operation.icon}</span>
      <span className="title">{operation.title}</span>
      <span className="description">{operation.description}</span>
      <button onClick={() => onAction(operation.id)}>
        {operation.actionLabel}
      </button>
      {operation.badge && <Badge>{operation.badge}</Badge>}
    </div>
  )
}

const OperationsList = () => {
  const handleAction = useCallback((id: string) => {
    const op = operations.find(o => o.id === id)
    op?.onClick()
  }, [operations])

  return (
    <div>
      {operations.map(op => (
        <OperationItem
          key={op.id}
          operation={op}
          onAction={handleAction}
        />
      ))}
    </div>
  )
}

Directory Structure Patterns

Feature-Based Structure (Standard) is recommended. Group related components of a feature together and use a domain-driven approach for file naming and structure.

Props Design

Minimal Props Principle

Pass only what's needed:

// ❌ Bad: Passing entire objects when only some fields needed
<ConfigHeader appDetail={appDetail} modelConfig={modelConfig} />

// ✅ Good: Destructure to minimum required
<ConfigHeader
  appName={appDetail.name}
  isAdvancedMode={modelConfig.isAdvanced}
  onPublish={handlePublish}
/>

Callback Props Pattern

Use callbacks for child-to-parent communication:

// Parent
const Parent = () => {
  const [value, setValue] = useState('')

  return (
    <Child
      value={value}
      onChange={setValue}
      onSubmit={handleSubmit}
    />
  )
}

// Child
interface ChildProps {
  value: string
  onChange: (value: string) => void
  onSubmit: () => void
}

const Child: FC<ChildProps> = ({ value, onChange, onSubmit }) => {
  return (
    <div>
      <input value={value} onChange={e => onChange(e.target.value)} />
      <button onClick={onSubmit}>Submit</button>
    </div>
  )
}

Render Props for Flexibility

When sub-components need parent context:

interface ListProps<T> {
  items: T[]
  renderItem: (item: T, index: number) => React.ReactNode
  renderEmpty?: () => React.ReactNode
}

function List<T>({ items, renderItem, renderEmpty }: ListProps<T>) {
  if (items.length === 0 && renderEmpty) {
    return <>{renderEmpty()}</>
  }

  return (
    <div>
      {items.map((item, index) => renderItem(item, index))}
    </div>
  )
}

// Usage
<List
  items={operations}
  renderItem={(op, i) => <OperationItem key={i} operation={op} />}
  renderEmpty={() => <EmptyState message="No operations" />}
/>

Hook Extraction Patterns

This document provides detailed guidance on extracting custom hooks from complex components.

When to Extract Hooks

Extract a custom hook when you identify:

1. Coupled state groups - Multiple useState hooks that are always used together 1. Complex effects - useEffect with multiple dependencies or cleanup logic 1. Business logic - Data transformations, validations, or calculations 1. Reusable patterns - Logic that appears in multiple components

Extraction Process

Step 1: Identify State Groups

Look for state variables that are logically related:

// ❌ These belong together - extract to hook
const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
const [completionParams, setCompletionParams] = useState<FormValue>({})
const [modelModeType, setModelModeType] = useState<ModelModeType>(...)

// These are model-related state that should be in useModelConfig()

Step 2: Identify Related Effects

Find effects that modify the grouped state:

// ❌ These effects belong with the state above
useEffect(() => {
  if (hasFetchedDetail && !modelModeType) {
    const mode = currModel?.model_properties.mode
    if (mode) {
      const newModelConfig = produce(modelConfig, (draft) => {
        draft.mode = mode
      })
      setModelConfig(newModelConfig)
    }
  }
}, [textGenerationModelList, hasFetchedDetail, modelModeType, currModel])

Step 3: Create the Hook

// hooks/use-model-config.ts
import type { FormValue } from '@/app/components/header/account-setting/model-provider-page/declarations'
import type { ModelConfig } from '@/models/debug'
import { produce } from 'immer'
import { useEffect, useState } from 'react'
import { ModelModeType } from '@/types/app'

interface UseModelConfigParams {
  initialConfig?: Partial<ModelConfig>
  currModel?: { model_properties?: { mode?: ModelModeType } }
  hasFetchedDetail: boolean
}

interface UseModelConfigReturn {
  modelConfig: ModelConfig
  setModelConfig: (config: ModelConfig) => void
  completionParams: FormValue
  setCompletionParams: (params: FormValue) => void
  modelModeType: ModelModeType
}

export const useModelConfig = ({
  initialConfig,
  currModel,
  hasFetchedDetail,
}: UseModelConfigParams): UseModelConfigReturn => {
  const [modelConfig, setModelConfig] = useState<ModelConfig>({
    provider: 'langgenius/openai/openai',
    model_id: 'gpt-3.5-turbo',
    mode: ModelModeType.unset,
    // ... default values
    ...initialConfig,
  })

  const [completionParams, setCompletionParams] = useState<FormValue>({})

  const modelModeType = modelConfig.mode

  // Fill old app data missing model mode
  useEffect(() => {
    if (hasFetchedDetail && !modelModeType) {
      const mode = currModel?.model_properties?.mode
      if (mode) {
        setModelConfig(produce(modelConfig, (draft) => {
          draft.mode = mode
        }))
      }
    }
  }, [hasFetchedDetail, modelModeType, currModel])

  return {
    modelConfig,
    setModelConfig,
    completionParams,
    setCompletionParams,
    modelModeType,
  }
}

Step 4: Update Component

// Before: 50+ lines of state management
const Configuration: FC = () => {
  const [modelConfig, setModelConfig] = useState<ModelConfig>(...)
  // ... lots of related state and effects
}

// After: Clean component
const Configuration: FC = () => {
  const {
    modelConfig,
    setModelConfig,
    completionParams,
    setCompletionParams,
    modelModeType,
  } = useModelConfig({
    currModel,
    hasFetchedDetail,
  })

  // Component now focuses on UI
}

Naming Conventions

Hook Names

• Use use prefix: useModelConfig, useDatasetConfig
• Be specific: useAdvancedPromptConfig not usePrompt
• Include domain: useWorkflowVariables, useMCPServer

File Names

• Kebab-case: use-model-config.ts
• Place in hooks/ subdirectory when multiple hooks exist
• Place alongside component for single-use hooks

Return Type Names

• Suffix with Return: UseModelConfigReturn
• Suffix params with Params: UseModelConfigParams

Common Hook Patterns

1. Data Fetching Hook (React Query)

// Pattern: Use @tanstack/react-query for data fetching
import { useQuery, useQueryClient } from '@tanstack/react-query'
import { get } from '@/service/base'
import { useInvalid } from '@/service/use-base'

const NAME_SPACE = 'appConfig'

// Query keys for cache management
export const appConfigQueryKeys = {
  detail: (appId: string) => [NAME_SPACE, 'detail', appId] as const,
}

// Main data hook
export const useAppConfig = (appId: string) => {
  return useQuery({
    enabled: !!appId,
    queryKey: appConfigQueryKeys.detail(appId),
    queryFn: () => get<AppDetailResponse>(`/apps/${appId}`),
    select: data => data?.model_config || null,
  })
}

// Invalidation hook for refreshing data
export const useInvalidAppConfig = () => {
  return useInvalid([NAME_SPACE])
}

// Usage in component
const Component = () => {
  const { data: config, isLoading, error, refetch } = useAppConfig(appId)
  const invalidAppConfig = useInvalidAppConfig()

  const handleRefresh = () => {
    invalidAppConfig() // Invalidates cache and triggers refetch
  }

  return <div>...</div>
}

2. Form State Hook

// Pattern: Form state + validation + submission
export const useConfigForm = (initialValues: ConfigFormValues) => {
  const [values, setValues] = useState(initialValues)
  const [errors, setErrors] = useState<Record<string, string>>({})
  const [isSubmitting, setIsSubmitting] = useState(false)

  const validate = useCallback(() => {
    const newErrors: Record<string, string> = {}
    if (!values.name) newErrors.name = 'Name is required'
    setErrors(newErrors)
    return Object.keys(newErrors).length === 0
  }, [values])

  const handleChange = useCallback((field: string, value: any) => {
    setValues(prev => ({ ...prev, [field]: value }))
  }, [])

  const handleSubmit = useCallback(async (onSubmit: (values: ConfigFormValues) => Promise<void>) => {
    if (!validate()) return
    setIsSubmitting(true)
    try {
      await onSubmit(values)
    } finally {
      setIsSubmitting(false)
    }
  }, [values, validate])

  return { values, errors, isSubmitting, handleChange, handleSubmit }
}

3. Modal State Hook

// Pattern: Multiple modal management
type ModalType = 'edit' | 'delete' | 'duplicate' | null

export const useModalState = () => {
  const [activeModal, setActiveModal] = useState<ModalType>(null)
  const [modalData, setModalData] = useState<any>(null)

  const openModal = useCallback((type: ModalType, data?: any) => {
    setActiveModal(type)
    setModalData(data)
  }, [])

  const closeModal = useCallback(() => {
    setActiveModal(null)
    setModalData(null)
  }, [])

  return {
    activeModal,
    modalData,
    openModal,
    closeModal,
    isOpen: useCallback((type: ModalType) => activeModal === type, [activeModal]),
  }
}

4. Toggle/Boolean Hook

// Pattern: Boolean state with convenience methods
export const useToggle = (initialValue = false) => {
  const [value, setValue] = useState(initialValue)

  const toggle = useCallback(() => setValue(v => !v), [])
  const setTrue = useCallback(() => setValue(true), [])
  const setFalse = useCallback(() => setValue(false), [])

  return [value, { toggle, setTrue, setFalse, set: setValue }] as const
}

// Usage
const [isExpanded, { toggle, setTrue: expand, setFalse: collapse }] = useToggle()

Testing Extracted Hooks

After extraction, test hooks in isolation:

// use-model-config.spec.ts
import { renderHook, act } from '@testing-library/react'
import { useModelConfig } from './use-model-config'

describe('useModelConfig', () => {
  it('should initialize with default values', () => {
    const { result } = renderHook(() => useModelConfig({
      hasFetchedDetail: false,
    }))

    expect(result.current.modelConfig.provider).toBe('langgenius/openai/openai')
    expect(result.current.modelModeType).toBe(ModelModeType.unset)
  })

  it('should update model config', () => {
    const { result } = renderHook(() => useModelConfig({
      hasFetchedDetail: true,
    }))

    act(() => {
      result.current.setModelConfig({
        ...result.current.modelConfig,
        model_id: 'gpt-4',
      })
    })

    expect(result.current.modelConfig.model_id).toBe('gpt-4')
  })
})