isLoading = true
error = "Network failed"
data = {...}
selectedId = "case-123"
entities["case-123"] = undefined
step = "review"
validation.status = "idle"
modal.open = false
modal.payload = {...}

How do I update this state?

What states are legal?
What states are impossible?
Which transitions may move between them?
Which component owns those transitions?
Which tests prove those invariants?

A selected item id must exist in the entity map.
A closed modal must not keep stale payload.
A submitting form cannot be edited unless editing is explicitly allowed.
A successful request must have data and no error.
An optimistic entity must have a client temp id until confirmed.
A wizard cannot enter review step before required fields are valid.
Only one accordion item can be open in single-select mode.
A dialog stack top item is the only item that receives Escape key close.

state shape
component identity
props contract
context value
external store snapshot
server cache data
URL parameters
pending async work

const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
const [data, setData] = useState<CaseDetail | null>(null);

isLoading=true, error!=null, data!=null
isLoading=false, error=null, data=null
isLoading=true, error!=null, data=null

type CaseDetailState =
  | { tag: 'idle' }
  | { tag: 'loading' }
  | { tag: 'success'; data: CaseDetail }
  | { tag: 'failure'; error: ErrorInfo };

success requires data
failure requires error
loading cannot also have stale error unless explicitly modeled
idle cannot accidentally contain payload

isDialogOpen
isSubmitting
isConfirming
isDirty
isValid
errorMessage
selectedId

type DeleteCaseFlow =
  | { tag: 'idle' }
  | { tag: 'confirming'; caseId: CaseId }
  | { tag: 'submitting'; caseId: CaseId; requestId: string }
  | { tag: 'failed'; caseId: CaseId; error: ErrorInfo }
  | { tag: 'completed'; caseId: CaseId };

confirming -> dialog is open
submitting -> confirm button disabled
failed -> dialog stays open with error
completed -> dialog closes and cache invalidates

The dropdown renders selectedId correctly.
But selectedId points to an entity removed by another store transition.

make illegal states unrepresentable
then guard illegal transitions
then assert impossible edge cases

State owner:
  AssignmentPanel

State:
  selectedAssigneeId
  eligibleAssignees
  currentAssigneeId
  submitStatus

Invariants:
  selectedAssigneeId must be null or exist in eligibleAssignees
  selectedAssigneeId may equal currentAssigneeId only when no change is pending
  submit button is enabled only when selectedAssigneeId differs from currentAssigneeId
  submitting state captures the assignee id being submitted
  response for old request cannot overwrite newer request
  currentAssigneeId updates only after confirmed success or optimistic commit

type ModalState = {
  isOpen: boolean;
  isConfirming: boolean;
  isSubmitting: boolean;
  isError: boolean;
  caseId?: string;
  error?: string;
};

isOpen=false and caseId exists
isSubmitting=true and caseId missing
isConfirming=true and isSubmitting=true
isError=true and error missing
isOpen=false and error visible in memory

type DeleteModalState =
  | { tag: 'closed' }
  | { tag: 'confirming'; caseId: string }
  | { tag: 'submitting'; caseId: string; requestId: string }
  | { tag: 'failed'; caseId: string; error: string };

function DeleteCaseDialog({ state, onCancel, onConfirm }: Props) {
  if (state.tag === 'closed') return null;

  return (
    <Dialog open onOpenChange={(open) => !open && onCancel()}>
      <Dialog.Title>Delete case?</Dialog.Title>

      {state.tag === 'failed' && <ErrorText>{state.error}</ErrorText>}

      <Button
        disabled={state.tag === 'submitting'}
        onClick={() => onConfirm(state.caseId)}
      >
        {state.tag === 'submitting' ? 'Deleting...' : 'Delete'}
      </Button>
    </Dialog>
  );
}

no boolean combinations
no optional payload checks scattered everywhere
no stale payload after close
no ambiguous loading+error state

type FormState = {
  step: 'details' | 'review' | 'submit';
  details?: Details;
  validationErrors?: Record<string, string>;
  submittedId?: string;
};

step=review with no details
step=submit with validationErrors
submittedId exists while step=details

type FormState =
  | { tag: 'editingDetails'; draft: DetailsDraft; errors: FieldErrors }
  | { tag: 'reviewing'; details: ValidDetails }
  | { tag: 'submitting'; details: ValidDetails; requestId: string }
  | { tag: 'submitted'; submissionId: string };

editingDetails has draft and errors
reviewing has valid details
submitting has valid details and request identity
submitted has server submission id

const [items, setItems] = useState<Item[]>([]);
const [selectedId, setSelectedId] = useState<string | null>(null);
const [selectedItem, setSelectedItem] = useState<Item | null>(null);

const selectedItem = selectedId
  ? items.find((item) => item.id === selectedId) ?? null
  : null;

selectedItem is always derived from selectedId and items

type CaseState = {
  selectedCaseId: string | null;
  casesById: Record<string, CaseSummary>;
};

function assertCaseState(state: CaseState) {
  if (state.selectedCaseId && !state.casesById[state.selectedCaseId]) {
    throw new Error(`selectedCaseId does not exist: ${state.selectedCaseId}`);
  }
}

function reducer(state: CaseState, event: Event): CaseState {
  switch (event.type) {
    case 'caseSelected': {
      if (!state.casesById[event.caseId]) {
        return state; // or throw in development
      }

      return { ...state, selectedCaseId: event.caseId };
    }

    case 'caseRemoved': {
      const { [event.caseId]: removed, ...casesById } = state.casesById;

      return {
        casesById,
        selectedCaseId:
          state.selectedCaseId === event.caseId ? null : state.selectedCaseId,
      };
    }
  }
}

accept legal events
preserve invariants in the next state

type UploadState =
  | { tag: 'idle' }
  | { tag: 'selecting'; file: File }
  | { tag: 'uploading'; file: File; requestId: string; progress: number }
  | { tag: 'failed'; file: File; error: string }
  | { tag: 'uploaded'; fileId: string };

type UploadEvent =
  | { type: 'fileSelected'; file: File }
  | { type: 'uploadStarted'; requestId: string }
  | { type: 'progressChanged'; requestId: string; progress: number }
  | { type: 'uploadFailed'; requestId: string; error: string }
  | { type: 'uploadSucceeded'; requestId: string; fileId: string }
  | { type: 'cancelled' };

function uploadReducer(state: UploadState, event: UploadEvent): UploadState {
  switch (event.type) {
    case 'fileSelected':
      return { tag: 'selecting', file: event.file };

    case 'uploadStarted':
      if (state.tag !== 'selecting') return state;
      return {
        tag: 'uploading',
        file: state.file,
        requestId: event.requestId,
        progress: 0,
      };

    case 'progressChanged':
      if (state.tag !== 'uploading') return state;
      if (state.requestId !== event.requestId) return state;
      return {
        ...state,
        progress: Math.max(state.progress, event.progress),
      };

    case 'uploadFailed':
      if (state.tag !== 'uploading') return state;
      if (state.requestId !== event.requestId) return state;
      return { tag: 'failed', file: state.file, error: event.error };

    case 'uploadSucceeded':
      if (state.tag !== 'uploading') return state;
      if (state.requestId !== event.requestId) return state;
      return { tag: 'uploaded', fileId: event.fileId };

    case 'cancelled':
      return { tag: 'idle' };
  }
}

progress cannot arrive before uploadStarted
old request responses cannot overwrite current state
progress cannot go backwards
failed keeps file for retry
uploaded contains server file id, not local File object
cancel resets payload

function invariant(condition: boolean, message: string): asserts condition {
  if (!condition) {
    if (process.env.NODE_ENV !== 'production') {
      throw new Error(message);
    }

    console.error(message);
  }
}

async function handleSave() {
  setStatus('saving');
  await saveDraft(draft);
  setStatus('saved');
  setSavedDraft(draft);
}

async function handleSave() {
  const requestId = crypto.randomUUID();
  const submittedDraft = draft;

  dispatch({ type: 'saveStarted', requestId, draft: submittedDraft });

  try {
    const saved = await saveDraft(submittedDraft);
    dispatch({ type: 'saveSucceeded', requestId, saved });
  } catch (error) {
    dispatch({ type: 'saveFailed', requestId, error: toErrorInfo(error) });
  }
}

case 'saveSucceeded': {
  if (state.tag !== 'saving') return state;
  if (state.requestId !== event.requestId) return state;
  return { tag: 'saved', saved: event.saved };
}

Only the active request may complete the active save state.

Can the user edit while saving?
Can a save complete after draft changed?
Does success mark the current draft saved or the submitted draft saved?
Does retry use latest draft or failed request draft?

type SearchState =
  | { tag: 'idle'; query: string }
  | { tag: 'loading'; query: string; requestId: string }
  | { tag: 'success'; query: string; results: SearchResult[] }
  | { tag: 'failure'; query: string; error: ErrorInfo };

q=a      request r1
q=ab     request r2
q=abc    request r3
r1 returns after r3

case 'searchSucceeded': {
  if (state.tag !== 'loading') return state;
  if (state.requestId !== event.requestId) return state;
  return { tag: 'success', query: state.query, results: event.results };
}

Only the latest active request may commit visible results.

field error belongs to current field value
form-level validity derives from current field states
submit uses validated snapshot, not mutable current draft
server error belongs to submitted payload version
reset clears dirty/touched/errors consistently
hidden conditional fields do not submit stale values unless explicitly retained

type FormState = {
  values: Values;
  errors: Errors;
  touched: Touched;
  isValid: boolean;
  isSubmitting: boolean;
  serverError?: string;
};

values      = user draft
errors      = validation result for a specific values version
touched     = interaction metadata
submit      = command with values snapshot
serverError = response for submitted snapshot

type FormState = {
  values: Values;
  version: number;
  validation: {
    version: number;
    errors: Errors;
  };
  submission:
    | { tag: 'idle' }
    | { tag: 'submitting'; requestId: string; version: number; values: Values }
    | { tag: 'failed'; version: number; errors: ServerErrors }
    | { tag: 'succeeded'; id: string };
};

const [open, setOpen] = useState(false);
const [caseId, setCaseId] = useState<string | null>(null);

type ModalState =
  | { tag: 'closed' }
  | { tag: 'open'; caseId: string };

closed modal has no payload
open modal always has payload

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

type OverlayState = {
  stack: Overlay[];
};

Escape closes only the top overlay
focus trap belongs to top modal
background is inert if stack length > 0
body scroll lock count equals modal stack depth

type SelectionState = {
  selectedId: string | null;
  visibleIds: string[];
};

selectedId is null or included in visibleIds
if filter removes selected item, either clear selection or preserve global selection explicitly
keyboard focus id may differ from selected id

type SelectionState = {
  selectedIds: Set<string>;
  allIds: string[];
  visibleIds: string[];
};

selectedIds is a subset of allIds
visible selection count derives from selectedIds ∩ visibleIds
select all visible is not the same as select all global
bulk action payload must define whether it targets visible, selected, or query-matched entities

type EntityState = {
  cases: Record<string, CaseEntity>;
  comments: Record<string, CommentEntity>;
};

every comment.caseId exists in cases
every case.commentIds item exists in comments
relationship order is stored exactly once
entity table does not contain temp and confirmed id for the same logical entity
partial response cannot erase fields unless explicitly marked as partial

case 'commentDeleted': {
  const comments = { ...state.comments };
  delete comments[event.commentId];

  return {
    ...state,
    comments,
    cases: {
      ...state.cases,
      [event.caseId]: {
        ...state.cases[event.caseId],
        commentIds: state.cases[event.caseId].commentIds.filter(
          (id) => id !== event.commentId,
        ),
      },
    },
  };
}

type SearchParamsState = {
  page: number;
  sort: 'createdAt' | 'priority';
  direction: 'asc' | 'desc';
  status: 'open' | 'closed' | 'all';
};

page >= 1
sort is one of allowed fields
direction is valid
status is valid
invalid params become canonical defaults
URL does not contain private tokens or sensitive filters
query key derives from canonical params, not raw search string

stored value has schema version
stored value passes validation before use
unknown version migrates or resets
logout clears identity-bound state
sensitive state is not persisted casually
hydrated value cannot contradict server session

type PersistedPreferencesV2 = {
  version: 2;
  density: 'compact' | 'comfortable';
  sidebarCollapsed: boolean;
};

function parsePreferences(raw: string | null): PersistedPreferencesV2 {
  if (!raw) return defaultPreferences;

  try {
    const value = JSON.parse(raw);

    if (value.version === 2 && isValidPreferences(value)) {
      return value;
    }

    return defaultPreferences;
  } catch {
    return defaultPreferences;
  }
}

consumer must be under provider unless optional fallback is intentional
provider value identity must be stable enough for its volatility
state context and command context may need separate providers
capability context should not expose mutable implementation details
permission context must not become security enforcement

function createStrictContext<T>(name: string) {
  const Context = createContext<T | null>(null);

  function useStrictContext() {
    const value = useContext(Context);

    if (value === null) {
      throw new Error(`${name} must be used within ${name}.Provider`);
    }

    return value;
  }

  return [Context.Provider, useStrictContext] as const;
}

Consumer never silently runs with fake default capability.

type ControllableProps<T> = {
  value?: T;
  defaultValue?: T;
  onValueChange?: (next: T) => void;
};

component is controlled if value is not undefined on first render
component should not switch controlledness after mount
controlled component does not mutate internal source of truth
uncontrolled component owns internal state
onValueChange emits intent, not guaranteed commit

function useControllednessWarning(name: string, isControlled: boolean) {
  const initial = useRef(isControlled);

  if (process.env.NODE_ENV !== 'production') {
    if (initial.current !== isControlled) {
      console.error(
        `${name} changed from ${initial.current ? 'controlled' : 'uncontrolled'} ` +
          `to ${isControlled ? 'controlled' : 'uncontrolled'}.`,
      );
    }
  }
}

a dialog that is visually open must expose modal semantics
focus must move into modal and return after close
aria-expanded must match actual disclosure state
aria-controls must reference an existing controlled element
active descendant id must exist in the listbox options
selected tab must control the visible panel
error message id must be referenced by invalid field

State: idle
  event: started -> loading
  event: cancelled -> idle

State: loading
  event: succeeded(active request) -> success
  event: failed(active request) -> failure
  event: cancelled -> idle

State: success
  event: refreshed -> loading
  event: reset -> idle

State: failure
  event: retry -> loading
  event: reset -> idle

function reducer(state: State, event: Event): State {
  switch (state.tag) {
    case 'idle':
      return reduceIdle(state, event);
    case 'loading':
      return reduceLoading(state, event);
    case 'success':
      return reduceSuccess(state, event);
    case 'failure':
      return reduceFailure(state, event);
  }
}

function assertNever(value: never): never {
  throw new Error(`Unexpected value: ${JSON.stringify(value)}`);
}

function renderContent(state: CaseDetailState) {
  switch (state.tag) {
    case 'idle':
      return <EmptyState />;
    case 'loading':
      return <Spinner />;
    case 'success':
      return <CaseView data={state.data} />;
    case 'failure':
      return <ErrorView error={state.error} />;
    default:
      return assertNever(state);
  }
}

useEffect(() => {
  if (!open) {
    setPayload(null);
    setError(null);
  }
}, [open]);

type DialogState =
  | { tag: 'closed' }
  | { tag: 'open'; payload: Payload }
  | { tag: 'failed'; payload: Payload; error: string };

case 'closed':
  return { tag: 'closed' };

const selectedCase = useMemo(
  () => cases.find((item) => item.id === selectedId),
  [selectedId],
);

const selectedCase = useMemo(
  () => cases.find((item) => item.id === selectedId) ?? null,
  [cases, selectedId],
);

selectedCase is derived from the latest cases and selectedId snapshot

function CaseRow({ item }: Props) {
  selectedCaseRegistry.add(item.id); // mutation during render
  return <tr>{item.title}</tr>;
}

function CaseRow({ item, onVisible }: Props) {
  useEffect(() => {
    onVisible(item.id);
    return () => onVisible(null);
  }, [item.id, onVisible]);

  return <tr>{item.title}</tr>;
}

describe('case selection reducer', () => {
  it('clears selected id when selected case is removed', () => {
    const state = {
      selectedCaseId: 'c1',
      casesById: {
        c1: { id: 'c1', title: 'A' },
        c2: { id: 'c2', title: 'B' },
      },
    };

    const next = reducer(state, { type: 'caseRemoved', caseId: 'c1' });

    expect(next.selectedCaseId).toBeNull();
    expect(next.casesById.c1).toBeUndefined();
  });
});

it('ignores stale search result', () => {
  const loading = {
    tag: 'loading',
    query: 'abc',
    requestId: 'r3',
  } satisfies SearchState;

  const next = reducer(loading, {
    type: 'searchSucceeded',
    requestId: 'r1',
    results: [],
  });

  expect(next).toBe(loading);
});

function expectValidSelection(state: CaseState) {
  if (state.selectedCaseId !== null) {
    expect(state.casesById[state.selectedCaseId]).toBeDefined();
  }
}

What is the source of truth?
What states are legal?
What states are impossible?
Can illegal states be made unrepresentable?
Which transitions exist?
Which transitions are illegal?
What happens to dependent state when primary state changes?
Can async responses arrive out of order?
Can old closures commit stale data?
Can URL/persistence/server data violate assumptions?
Can component identity reset or preserve the wrong state?
Where are invariant tests?
What does the UI do if an invariant is breached in production?

If two booleans cannot both be true, use a union.
If a field is only valid in one mode, put it inside that mode.
If an id references an entity, handle deletion in the same transition.
If async work can overlap, attach request identity.
If data can be derived, derive it.
If state must reset on identity change, use key intentionally.
If a prop controls ownership, warn on controlledness switch.
If a value comes from URL/storage/network, parse and validate it.
If an effect repairs state, redesign the state.

State is not a bag of values.
State is a set of legal configurations.
Events are not random callbacks.
Events are transition requests.
Reducers are not just update utilities.
Reducers preserve invariants.
Types are not decoration.
Types can make illegal states unrepresentable.
Effects are not repair loops.
Effects synchronize external systems.