split-component

What this skill does

# Split React Component

You receive a single React component file to analyze and split into smaller, focused pieces. The goal is to separate concerns: business logic goes into custom hooks, repetitive or large UI blocks become presentation components.

## Step 1: Analyze the component

Read the file at `$ARGUMENTS`, then run an LSP-driven analysis pipeline. LSP provides semantic understanding -- it does not guess, it knows. Use it as the primary source of truth.

### 1.1 Symbol map

Run `documentSymbol` on the target file to get every symbol: functions, variables, types, interfaces. This is the skeleton of the component -- the full list of what exists and where.

### 1.2 Type and signature inspection

For each symbol returned in 1.1, run `hover` to get its type signature. This reveals:

- Which variables are state (`useState` returns `[T, Dispatch<SetStateAction<T>>]`)
- Which are memoized values (`useMemo` return types)
- Which are callbacks (`useCallback` signatures)
- Prop types and their shape
- Return types of custom hooks and helper functions

### 1.3 Internal dependency graph

For each function, handler, and hook call identified in 1.1-1.2:

- Run `outgoingCalls` to map what each function calls internally. This reveals which helpers, hooks, and API calls are tightly coupled.
- Run `findReferences` on state variables and handlers to identify which JSX sections consume them. This determines what moves together during extraction.

### 1.4 External dependency check

For imported symbols (API clients, utilities, types from other modules):

- Run `goToDefinition` to confirm where they live.
- Run `findReferences` scoped to the target file to see how many places use each import. Imports used in only one extracted piece can move with it cleanly.

### 1.5 Synthesis

With the LSP data collected, build a split plan identifying:

- **Hook candidates**: clusters of state + effects + handlers that `outgoingCalls` and `findReferences` show are cohesive (they reference each other but not the rest).
- **Component candidates**: JSX blocks inside loops, conditional sections, or large standalone sections where `findReferences` shows they depend on a narrow set of props/state.
- **Shared dependencies**: symbols referenced by multiple extraction candidates -- these stay in the parent or get lifted.

Present findings to the user as a short summary with the proposed split plan. Use `AskUserQuestion` to confirm before making changes.

## Step 2: Determine extraction strategy

The file's location determines how to organize the new files.

### Domain context (component lives inside a module)

When the component is inside a domain directory (e.g., `src/modules/orders/components/OrderDetail.tsx`), add new files as siblings within that domain:

```
modules/orders/
  components/
    OrderDetail.tsx            <- refactored, now lean
    OrderSummaryCard.tsx       <- extracted presentation component
  hooks/
    useOrderCalculations.ts    <- extracted logic
```

Create `hooks/` or `stores/` directories inside the domain if they don't exist yet.

### Isolated context (component lives outside a domain)

When the component is standalone (e.g., `src/components/Dashboard.tsx`), convert it into a self-contained directory with an `index.tsx` that preserves the original import path:

```
components/
  Dashboard/
    index.tsx                  <- re-exports, preserves import path
    DashboardFilters.tsx       <- extracted presentation component
    hooks/
      useDashboardData.ts      <- extracted logic
```

Use `git mv` to move the original file into the new directory as `index.tsx`, then extract from there.

## Step 3: Extract custom hooks

Business logic, state management, data fetching, and complex computations belong in custom hooks. Each hook should have a single, clear responsibility.

Guidelines for extraction:

- A hook manages one cohesive concern (e.g., form validation, data fetching for a specific resource, pagination state).
- The hook returns only what the component needs to render -- no internal implementation details leak out.
- Consolidate into `useReducer` when either condition applies: (a) 5+ `useState` variables, or (b) multiple `setState` calls scattered across different handlers that represent a single state transition -- these become one `dispatch` call with a descriptive action type instead of several `set*` calls spread across the codebase.
- Name the hook after what it does, not where it came from. `useOrderFilters` over `useOrderDetailFilters`.

## Step 4: Extract presentation components

UI blocks that are large, repeated, or self-contained become their own components. These are pure: they receive props and render JSX, nothing more.

What qualifies for extraction:

- JSX blocks inside `.map()` or `.forEach()` loops -- almost always worth extracting.
- Conditionally rendered sections with their own visual identity (a modal, a sidebar panel, an empty state).
- Repeated layout patterns, even if not identical -- parameterize with props.

Presentation components receive data and callbacks as props. They do not call hooks for data fetching or global state. If a presentation component needs local UI state (like a toggle or hover), that's fine -- keep it inside the component.

## Step 5: State management decisions

Apply this decision tree for each piece of state:

1. **Used only in one component?** Keep it local with `useState`. Escalate to `useReducer` when: (a) 5+ state variables, or (b) multiple `set*` calls in different handlers that logically represent a single state transition and can collapse into one `dispatch`.
2. **Shared across siblings or cousins?** Lift to the nearest common parent and pass as props if the prop chain is shallow (2 levels max).
3. **Shared across distant components or prop drilling becomes painful?** Use a zustand store scoped to that feature.

### Stores and reducers organization

When creating a zustand store or reducer, place it in a `stores/` or `reducers/` directory within the domain or component directory. Naming rules:

- Name after the concern, not the component: `cart-items.ts`, not `shopping-cart-store.ts`.
- Never append "store" or "reducer" to the filename -- the directory already communicates that.
- Always use kebab-case for filenames.

## Step 6: Wire everything together

After extraction:

1. Update the original component to import and use the new hooks and components.
2. Verify that the original import path still works (barrel file / index.tsx).
3. Check that no circular dependencies were introduced.
4. Run a build (`npm run build`, `npx tsc --noEmit`, or the project's equivalent) to confirm there are no type errors or broken imports.

## File naming

Name files after their purpose, not after the parent component. Each file type follows its own convention:

- **Components** (PascalCase): `Pagination.tsx` over `DataTablePagination.tsx`
- **Hooks** (camelCase): `usePagination.ts` over `useTablePaginationHook.ts`
- **Stores/reducers** (kebab-case): `cart-items.ts` over `shopping-cart-store.ts`