from child to parent
from parent to context
from context to external store
from effect-managed state to derived state
from duplicated client copy to server-state cache
from setter soup to reducer
from reducer to state machine
from local draft to URL state
from URL state to route-owned canonical state

a child state must be observed by sibling components
local state must survive navigation
state must become shareable through URL
state must synchronize with server cache
state transition logic becomes too complex for inline setters
context causes too many rerenders
state crosses feature boundaries
workflow has illegal transitions
modal/overlay state becomes global UI capability
server data is duplicated in client state

preserve observable behavior
improve internal structure

replace local state with Zustand
change component API
change server mutation flow
change loading behavior
change URL shape
change design system component

1. add characterization tests
2. introduce new state owner behind same public API
3. migrate transitions one by one
4. delete old state after parity
5. only then change public API if needed

opening and closing
default value behavior
controlled value behavior
dirty state
reset behavior
validation timing
submit lifecycle
loading/error display
selection preservation
URL synchronization
focus behavior

it('clears selected item when filter removes it', async () => {
  render(<CaseSearchPage />);

  await user.click(screen.getByRole('row', { name: /case 123/i }));
  await user.type(screen.getByRole('searchbox'), 'closed only');

  expect(screen.queryByText(/case 123/i)).not.toBeInTheDocument();
  expect(screen.getByText(/no case selected/i)).toBeVisible();
});

const [isOpen, setIsOpen] = useState(false);
const [mode, setMode] = useState<'create' | 'edit'>('create');
const [caseId, setCaseId] = useState<string | null>(null);

type EditorState =
  | { tag: 'closed' }
  | { tag: 'creating' }
  | { tag: 'editing'; caseId: string };

const [editor, setEditor] = useState<EditorState>({ tag: 'closed' });

function openCreate() {
  setEditor({ tag: 'creating' });
}

function openEdit(caseId: string) {
  setEditor({ tag: 'editing', caseId });
}

function closeEditor() {
  setEditor({ tag: 'closed' });
}

payload exists only when needed
close clears mode/payload atomically
rendering becomes exhaustive
future reducer migration is easier

function TaskList() {
  const [tasks, setTasks] = useState<Task[]>([]);
  const [selectedId, setSelectedId] = useState<string | null>(null);
  const [filter, setFilter] = useState('all');

  function deleteTask(id: string) {
    setTasks((tasks) => tasks.filter((task) => task.id !== id));
    if (selectedId === id) {
      setSelectedId(null);
    }
  }

  function completeTask(id: string) {
    setTasks((tasks) =>
      tasks.map((task) =>
        task.id === id ? { ...task, completed: true } : task,
      ),
    );
  }
}

selection invariant depends on delete handler remembering to clear selectedId
more transitions will scatter more invariant logic

type State = {
  tasks: Task[];
  selectedId: string | null;
  filter: Filter;
};

type Event =
  | { type: 'taskDeleted'; id: string }
  | { type: 'taskCompleted'; id: string }
  | { type: 'taskSelected'; id: string }
  | { type: 'filterChanged'; filter: Filter };

function reducer(state: State, event: Event): State {
  switch (event.type) {
    case 'taskDeleted':
      return {
        ...state,
        tasks: state.tasks.filter((task) => task.id !== event.id),
        selectedId: state.selectedId === event.id ? null : state.selectedId,
      };

    case 'taskCompleted':
      return {
        ...state,
        tasks: state.tasks.map((task) =>
          task.id === event.id ? { ...task, completed: true } : task,
        ),
      };

    case 'taskSelected':
      return state.tasks.some((task) => task.id === event.id)
        ? { ...state, selectedId: event.id }
        : state;

    case 'filterChanged':
      return { ...state, filter: event.filter };
  }
}

function SearchInput() {
  const [query, setQuery] = useState('');

  return <input value={query} onChange={(event) => setQuery(event.target.value)} />;
}

function CaseList() {
  return (
    <>
      <SearchInput />
      <Results />
    </>
  );
}

function SearchInput({ query, onQueryChange }: Props) {
  return (
    <input
      value={query}
      onChange={(event) => onQueryChange(event.target.value)}
    />
  );
}

function CaseList() {
  const [query, setQuery] = useState('');

  return (
    <>
      <SearchInput query={query} onQueryChange={setQuery} />
      <Results query={query} />
    </>
  );
}

Search input and results read the same query source of truth.

function Page() {
  const [draft, setDraft] = useState(ProfileDraft>(initialDraft);

  return <ProfileEditor draft={draft} onDraftChange={setDraft} />;
}

function Page() {
  function handleSubmit(draft: ProfileDraft) {
    return saveProfile(draft);
  }

  return <ProfileEditor initialDraft={initialDraft} onSubmit={handleSubmit} />;
}

function ProfileEditor({ initialDraft, onSubmit }: Props) {
  const [draft, setDraft] = useState(initialDraft);

  return (
    <form onSubmit={(event) => {
      event.preventDefault();
      onSubmit(draft);
    }}>
      {/* fields */}
    </form>
  );
}

Parent owns committed profile.
Editor owns in-progress draft.

<Page currentUser={currentUser} permissions={permissions}>
  <Layout currentUser={currentUser} permissions={permissions}>
    <Toolbar currentUser={currentUser} permissions={permissions}>
      <ActionButton currentUser={currentUser} permissions={permissions} />
    </Toolbar>
  </Layout>
</Page>

const [PermissionProvider, usePermissions] = createStrictContext<PermissionApi>(
  'PermissionContext',
);

function CasePage() {
  const permissionApi = useMemo(
    () => createPermissionApi(currentUser, permissions),
    [currentUser, permissions],
  );

  return (
    <PermissionProvider value={permissionApi}>
      <CaseLayout />
    </PermissionProvider>
  );
}

function ActionButton() {
  const permissions = usePermissions();
  const canApprove = permissions.can('case.approve');

  return <Button disabled={!canApprove}>Approve</Button>;
}

value is subtree-scoped
many descendants need it
intermediate nodes do not
value is not high-frequency keystroke state

provider value changes often
too many consumers rerender
consumers need small slices
splitting providers becomes unwieldy
selectors would solve most rerenders
state must be read outside React boundary

const DashboardContext = createContext<DashboardState | null>(null);

type Store<T> = {
  getSnapshot: () => T;
  subscribe: (listener: () => void) => () => void;
  setState: (updater: (state: T) => T) => void;
};

function useDashboardSelector<T>(selector: (state: DashboardState) => T): T {
  return useSyncExternalStore(
    dashboardStore.subscribe,
    () => selector(dashboardStore.getSnapshot()),
    () => selector(dashboardStore.getSnapshot()),
  );
}

1. keep provider API stable
2. put store instance in provider
3. replace context value state with store object
4. migrate consumers from useContextState to useSelector
5. delete broad context reads

const [cases, setCases] = useState<CaseSummary[]>([]);

useEffect(() => {
  fetchCases().then(setCases);
}, []);

no cache key
no invalidation policy
duplicate fetches across screens
manual race handling
manual refetch
stale data after mutation

function CaseListPage() {
  const query = useCaseSearchParams();
  const casesQuery = useCasesQuery(query);

  if (casesQuery.isLoading) return <Spinner />;
  if (casesQuery.isError) return <ErrorView error={casesQuery.error} />;

  return <CaseTable rows={casesQuery.data.items} />;
}

server owns case data
query cache owns freshness and invalidation
component owns view state and local selection
URL owns search params
mutation owns submit lifecycle

const [fullName, setFullName] = useState('');

useEffect(() => {
  setFullName(`${firstName} ${lastName}`);
}, [firstName, lastName]);

const fullName = `${firstName} ${lastName}`;

const filteredRows = useMemo(
  () => filterRows(rows, filters),
  [rows, filters],
);

If state can be calculated from current props/state during render, remove stored copy.

search query
filters
sort
page
selected tab if it represents route-level view
expanded panel if deep-linking matters

password input
keystroke draft before submit
open tooltip
hover state
private sensitive filters
high-frequency drag position

const [page, setPage] = useState(1);
const [status, setStatus] = useState<'all' | 'open' | 'closed'>('all');

function useCaseListParams() {
  const [searchParams, setSearchParams] = useSearchParams();

  const params = parseCaseListParams(searchParams);

  function updateParams(patch: Partial<CaseListParams>) {
    setSearchParams(serializeCaseListParams({ ...params, ...patch }));
  }

  return [params, updateParams] as const;
}

Components use parsed canonical params, never raw search params.

every keystroke updates URL
every URL update triggers query
typing feels laggy
back button contains every character

input draft stays local
submitted query commits to URL
server query derives from URL

function SearchBox({ committedQuery, onCommit }: Props) {
  const [draft, setDraft] = useState(committedQuery);

  useEffect(() => {
    setDraft(committedQuery);
  }, [committedQuery]);

  return (
    <form onSubmit={(event) => {
      event.preventDefault();
      onCommit(draft);
    }}>
      <input value={draft} onChange={(event) => setDraft(event.target.value)} />
      <button>Search</button>
    </form>
  );
}

URL owns committed query.
Input owns editable draft.
Draft resets when committed query changes due to navigation.

many states and events
transition guards spread across branches
async invoked work depends on state
entry/exit behavior matters
parallel states exist
retry/cancel/undo behavior is subtle
team needs visual transition map

function reducer(state: State, event: Event): State {
  // many branches, many guards
}

const approvalMachine = createMachine({
  initial: 'draft',
  states: {
    draft: {
      on: { SUBMIT: 'submitting' },
    },
    submitting: {
      on: {
        SUCCESS: 'pendingApproval',
        FAILURE: 'failed',
      },
    },
    pendingApproval: {
      on: {
        APPROVE: 'approved',
        REJECT: 'rejected',
      },
    },
    failed: {
      on: { RETRY: 'submitting' },
    },
    approved: {},
    rejected: {},
  },
});

store contains modal open flags for one component
store contains local form drafts
store contains hover state
store contains temporary animation state
store contains state that never leaves one feature

const isTooltipOpen = useUiStore((state) => state.tooltips[id]?.open);
const openTooltip = useUiStore((state) => state.openTooltip);

function TooltipTrigger() {
  const [open, setOpen] = useState(false);
  return <Tooltip open={open} onOpenChange={setOpen} />;
}

less global coupling
less test setup
less accidental persistence
smaller store surface
clearer ownership

function useCaseSelectionOld() {
  const { selectedId, setSelectedId } = useContext(CaseContext);
  return { selectedId, setSelectedId };
}

function useCaseSelectionNew() {
  const selectedId = useCaseStore((state) => state.selectedId);
  const selectCase = useCaseStore((state) => state.selectCase);
  return { selectedId, selectCase };
}

function useCaseSelection() {
  const { selectedId, selectCase } = useCaseSelectionNew();

  return {
    selectedId,
    setSelectedId: selectCase,
  };
}

old: setSelectedId(id)
new: selectCase(id)

old state remains source of truth
new module mirrors a small slice
new module takes ownership of one transition
old transition is deleted
repeat

Week 1: add reducer for selection only
Week 2: move filter state to URL parser
Week 3: move data fetching to query cache
Week 4: move modal flow to local state machine
Week 5: delete legacy page reducer branches

query text draft       -> SearchBox local state
committed query        -> URL state
results data           -> server-state cache
selected case id       -> page local/lifted state or URL if deep-linkable
bulk selection         -> page reducer
modal workflow         -> local reducer/state machine
permissions            -> capability context
layout density         -> design system context/persistence

Should I use Redux or Zustand for this page?

none for draft
URL for filters
query cache for results
reducer for bulk selection
context for permissions
local reducer for modal

two values must always match
useEffect keeps them synchronized
bugs appear when one updates without the other

const [items, setItems] = useState<Item[]>([]);
const [activeItem, setActiveItem] = useState<Item | null>(null);

const [items, setItems] = useState<Item[]>([]);
const [activeItemId, setActiveItemId] = useState<string | null>(null);

const activeItem = activeItemId
  ? items.find((item) => item.id === activeItemId) ?? null
  : null;

1. introduce id state next to old object state
2. derive object from id and collection
3. replace reads of old object with derived value
4. replace writes with id transition
5. delete old object state
6. add invariant test for deleted active item

type AppContextValue = {
  currentUser: User;
  theme: Theme;
  permissions: Permission[];
  notifications: Notification[];
  selectedCaseId: string | null;
  setSelectedCaseId: (id: string | null) => void;
  openModal: (modal: ModalConfig) => void;
};

AuthContext          -> current authenticated principal
ThemeContext         -> design system tokens
PermissionContext    -> capability checks
NotificationStore    -> external/server state
CaseSelectionContext -> scoped page selection
OverlayProvider      -> modal capability

1. create new focused provider
2. populate from old context initially
3. migrate consumers to new hook
4. measure rerender impact
5. remove field from AppContext
6. repeat per responsibility

function CaseDetail({ caseId }: Props) {
  const [state, setState] = useState<State>({ tag: 'loading' });

  useEffect(() => {
    let ignore = false;

    setState({ tag: 'loading' });

    fetchCase(caseId)
      .then((data) => {
        if (!ignore) setState({ tag: 'success', data });
      })
      .catch((error) => {
        if (!ignore) setState({ tag: 'failure', error });
      });

    return () => {
      ignore = true;
    };
  }, [caseId]);

  // render
}

function useCaseDetail(caseId: string) {
  return useQuery({
    queryKey: ['case', caseId],
    queryFn: () => fetchCase(caseId),
  });
}

function CaseDetail({ caseId }: Props) {
  const caseQuery = useCaseDetail(caseId);

  if (caseQuery.isLoading) return <Spinner />;
  if (caseQuery.isError) return <ErrorView error={caseQuery.error} />;

  return <CaseView data={caseQuery.data} />;
}

cache key replaces ad hoc identity
query library handles observer lifecycle
mutation invalidation has a target
duplicate screens can share cached data

type UiStore = {
  deleteCaseModalOpen: boolean;
  deleteCaseId: string | null;
  assignCaseModalOpen: boolean;
  assignCaseId: string | null;
};

type OverlayRequest =
  | { kind: 'deleteCase'; caseId: string }
  | { kind: 'assignCase'; caseId: string }
  | { kind: 'previewDocument'; documentId: string };

type OverlayApi = {
  open: (request: OverlayRequest) => void;
  closeTop: (reason: CloseReason) => void;
};

1. introduce OverlayProvider
2. map old modal state to overlay stack internally
3. expose openDeleteCase(caseId) adapter
4. migrate call sites to overlay.open({kind, payload})
5. delete per-modal booleans
6. add focus/escape/backdrop tests

each open overlay has kind and payload
closed overlay has no stale payload
stack order defines focus and close behavior

type CaseStore = {
  cases: CaseSummary[];
  selectedCaseId: string | null;
  fetchCases: () => Promise<void>;
  updateCaseStatus: (id: string, status: Status) => Promise<void>;
};

cases data           -> query cache
case mutation        -> mutation hook
selectedCaseId       -> page state or URL state
bulk selection       -> reducer/external store if needed

function CasePage() {
  const params = useCaseListParams();
  const casesQuery = useCasesQuery(params);
  const [selectedCaseId, setSelectedCaseId] = useState<string | null>(null);

  return (
    <CaseTable
      rows={casesQuery.data?.items ?? []}
      selectedId={selectedCaseId}
      onSelectedIdChange={setSelectedCaseId}
    />
  );
}

function CasePage() {
  const flags = useFeatureFlags();

  return flags.enabled('casePage.newStateModel')
    ? <CasePageV2 />
    : <CasePageLegacy />;
}

screen is high-value
behavior is complex
QA needs side-by-side comparison
rollback must be quick
migration changes URL/cache/workflow semantics

duplicate code paths
divergent behavior
extra test matrix
flag cleanup risk

type CaseListModel = {
  rows: CaseRowModel[];
  selectedId: string | null;
  selectCase: (id: string) => void;
  refresh: () => void;
};

function useCaseListModel(): CaseListModel {
  // internals can migrate without changing component contract
}

function CaseListScreen() {
  const model = useCaseListModel();
  return <CaseListView {...model} />;
}

local fetch -> query cache
local selection -> URL
inline setters -> reducer
context -> external store

Many components update the same state from different places.
A child needs to notify distant siblings.
An effect exists only to copy prop into state.
A context value contains unrelated fields.
A global store contains state used by one component.
A server response is manually copied into multiple stores.
A URL param and local state represent the same filter.
A reducer has impossible state combinations.
A component reset bug is fixed by random key changes.

Move entire app state to one store.

unclear ownership
large blast radius
weak encapsulation
hard tests
unnecessary subscriptions
hard rollback

migrate one state dimension at a time
preserve public component contracts
keep old and new paths temporarily only where needed
measure rerenders after each migration
delete compatibility adapters quickly

function Page({ caseId }: Props) {
  return <CaseEditor caseId={caseId} />;
}

function Page({ caseId }: Props) {
  return <CaseEditor key={caseId} caseId={caseId} />;
}

Editor draft resets when case identity changes.

Should focus reset?
Should unsaved draft reset?
Should scroll reset?
Should child query observers remount?
Should animations restart?

const [selectedId, setSelectedId] = useState(props.selectedId);

useEffect(() => {
  setSelectedId(props.selectedId);
}, [props.selectedId]);

Is this component controlled?
Is selectedId a local draft initialized from prop?
Should prop changes reset draft?
Should local edits commit upward?

<Selector value={selectedId} onValueChange={setSelectedId} />

<Selector key={recordId} defaultValue={initialSelectedId} />

<Selector initialValue={selectedId} onCommit={setSelectedId} />

more ancestors and siblings may rerender
callbacks may change identity
memoized children may be invalidated
context provider value may change more often

lift only committed state, not keystroke draft
split read model and command callbacks
memoize expensive child boundaries only after profiling
use context only for low/medium volatility values
use external store for granular high-frequency shared state

transition tests
illegal event tests
invariant tests

provider harness tests
consumer tests under missing provider
override provider tests
rerender-sensitive tests if needed

parse invalid params
serialize canonical params
navigation/back button behavior
query key derivation

loading/error/success states
query key stability
mutation invalidation
optimistic rollback
stale data behavior

state transition table tests
async success/failure from each state
cancel/retry/undo semantics

What is the current owner?
Why is it wrong?
What is the new owner?
What behavior must remain unchanged?
What behavior intentionally changes?
Which invariants must hold?
Which tests capture current behavior?
What is the rollback strategy?
How will old state be deleted?

migrate one dimension at a time
keep public APIs stable where possible
use adapters for incremental rollout
avoid mixing behavior change with ownership change
measure render impact
write transition tests

delete compatibility code
delete old state fields
remove dead effects
update documentation/ADR
review provider/store boundaries
review invariants again

# ADR: Move Case Search Filters from Local State to URL State

## Context
Filters currently live in CaseSearchPage local state. Users cannot share filtered views, and browser back does not restore search state.

## Decision
Move committed filters to URL search params. Keep text input draft local until submit/debounce commit.

## State Ownership
- Draft query: SearchBox local state
- Committed filters: URL search params
- Results: query cache keyed by canonical filters
- Selected case: page local state

## Invariants
- Components read parsed canonical params, not raw URLSearchParams.
- Invalid params fall back to defaults and are canonicalized.
- Query cache key derives from canonical params.
- Sensitive filters are not stored in URL.

## Migration Plan
1. Add parse/serialize functions.
2. Add tests for invalid/canonical params.
3. Replace local committed filter state with URL hook.
4. Update query key.
5. Remove legacy local filter state.

## Rollback
Feature flag can switch page to legacy local state for one release.

State starts local.
Move it only when ownership pressure appears.
Preserve behavior before changing architecture.
Migrate one state dimension at a time.
Use adapters to avoid flag-day rewrites.
Use reducers for transition logic.
Use context for scoped dependencies.
Use external stores for granular shared client state.
Use server-state cache for server-owned data.
Use URL for shareable navigation state.
Use state machines for workflow correctness.
Move state back local when it was globalized unnecessarily.
Delete the old model after migration.