Context itu cukup.
Redux itu terlalu berat.
Zustand itu lebih simple.

State apa yang sedang kita kelola?
Siapa pemiliknya?
Siapa yang boleh mengubahnya?
Berapa luas radius pembacaannya?
Seberapa sering berubah?
Apakah perlu action log?
Apakah perlu selector granularity?
Apakah state ini server-owned, client-owned, workflow-owned, atau capability-owned?
Apa failure mode jika tool yang dipilih salah?

Context       = dependency/capability passing untuk subtree.
Zustand       = lightweight external store dengan selector ergonomics.
Redux Toolkit = governed state architecture dengan reducer/action/middleware convention.

Di mana state hidup, dan siapa yang mengontrol perubahan state itu?

State hidup di component instance.

State hidup di closest owner yang mengoordinasi beberapa children.

Value disediakan oleh provider untuk subtree.

State hidup di external store yang dapat dibaca component melalui selector.

State hidup di centralized governed store, berubah lewat action/reducer/middleware convention.

Jangan mulai dari library.
Mulai dari ownership.

- theme
- locale
- direction
- form field context
- modal service capability
- permission snapshot untuk subtree
- feature flag reader
- analytics capability
- dependency injection untuk testing

- UI workspace state
- selection state besar
- editor state client-owned
- command palette state
- modal/overlay registry
- client-side graph/layout state
- persisted user preference
- micro store per feature

- large shared client state
- normalized client entity cache non-server-authoritative
- audit-relevant UI transitions
- cross-feature workflow state
- team-wide action/reducer convention
- debugging via action timeline
- deterministic state transition tests

Context untuk membaca dependency.
Zustand untuk shared client state yang butuh granular subscription tanpa governance besar.
Redux Toolkit untuk shared client state yang butuh convention, traceability, dan team governance.

shared state yang dibaca banyak component

Provider -> Consumer dependency propagation

Store -> Action -> Reducer -> Middleware -> Selector -> Subscriber

Saya tidak mau prop drilling theme/locale/session/capability.

Saya butuh action vocabulary, transition log, middleware, normalized entity state, dan multi-team convention.

- selector-level subscription native,
- middleware pipeline matang,
- DevTools action timeline sekuat Redux,
- ecosystem entity adapter,
- standard async lifecycle convention,
- team-wide state governance.

- Dibutuhkan oleh banyak descendant dalam subtree.
- Value adalah dependency/capability, bukan volatile data utama.
- Update frequency rendah atau provider scope kecil.
- Provider hierarchy punya arti arsitektural.
- Consumer memang bergantung pada environment tersebut.

const PermissionContext = createContext<PermissionReader | null>(null);

export function PermissionProvider({
  permissions,
  children,
}: {
  permissions: PermissionSnapshot;
  children: React.ReactNode;
}) {
  const reader = useMemo(() => createPermissionReader(permissions), [permissions]);

  return (
    <PermissionContext.Provider value={reader}>
      {children}
    </PermissionContext.Provider>
  );
}

export function usePermission() {
  const reader = useContext(PermissionContext);
  if (!reader) {
    throw new Error('usePermission must be used inside PermissionProvider');
  }
  return reader;
}

Permission reader adalah capability.
Consumer tidak perlu tahu dari mana permission berasal.
Provider scope dapat berbeda per page/tenant/session.

type AppContextValue = {
  user: User | null;
  theme: Theme;
  selectedRows: string[];
  currentSearchText: string;
  notifications: Notification[];
  draftInvoice: InvoiceDraft;
  setSelectedRows: Dispatch<SetStateAction<string[]>>;
  setCurrentSearchText: Dispatch<SetStateAction<string>>;
  setDraftInvoice: Dispatch<SetStateAction<InvoiceDraft>>;
};

- domain tidak terkait masuk satu value,
- update kecil dapat memengaruhi banyak consumer,
- setter mentah bocor,
- ownership tidak jelas,
- testing butuh mock raksasa,
- refactor jadi mahal.

ThemeContext
FieldContext
DialogContext
PermissionContext
AnalyticsContext
FormSectionContext

AppContext
GlobalContext
SharedContext
CommonContext
StoreContext

- shared client state,
- selector subscription,
- API kecil,
- store/action dekat dengan feature,
- tidak butuh action log governance berat,
- mudah membuat scoped store jika perlu,
- persistence middleware sederhana,
- subscription dari non-React code.

import { create } from 'zustand';

interface SelectionStore {
  selectedIds: Set<string>;
  isSelected(id: string): boolean;
  select(id: string): void;
  deselect(id: string): void;
  toggle(id: string): void;
  clear(): void;
}

export const useSelectionStore = create<SelectionStore>((set, get) => ({
  selectedIds: new Set<string>(),

  isSelected: (id) => get().selectedIds.has(id),

  select: (id) =>
    set((state) => {
      const next = new Set(state.selectedIds);
      next.add(id);
      return { selectedIds: next };
    }),

  deselect: (id) =>
    set((state) => {
      const next = new Set(state.selectedIds);
      next.delete(id);
      return { selectedIds: next };
    }),

  toggle: (id) =>
    set((state) => {
      const next = new Set(state.selectedIds);
      if (next.has(id)) next.delete(id);
      else next.add(id);
      return { selectedIds: next };
    }),

  clear: () => set({ selectedIds: new Set() }),
}));

function Row({ id }: { id: string }) {
  const selected = useSelectionStore((state) => state.selectedIds.has(id));
  const toggle = useSelectionStore((state) => state.toggle);

  return (
    <button aria-pressed={selected} onClick={() => toggle(id)}>
      {selected ? 'Selected' : 'Select'}
    </button>
  );
}

Banyak row membaca bagian kecil dari state.
Perubahan selection satu row tidak seharusnya membuat semua consumer context membaca root value yang sama.
Selector subscription lebih natural.

Jika state ini feature-local, action log tidak audit-critical, dan tim tidak butuh convention Redux-level, Zustand cukup.

- semua feature membuat singleton store global tanpa boundary,
- action naming tidak konsisten,
- state server cache masuk store manual,
- persistence dipakai tanpa versioning/migration,
- selector mengembalikan object/array baru setiap render,
- store menjadi implicit dependency dari semua component.

- transisi state harus punya nama,
- event/action vocabulary harus konsisten,
- debugging butuh timeline,
- side effects butuh middleware boundary,
- reducer transition perlu dites,
- entity state perlu normalisasi,
- banyak team bergantung pada state yang sama,
- refactor perlu dilakukan dengan contract jelas.

import { createSlice, PayloadAction } from '@reduxjs/toolkit';

type BulkActionState =
  | { status: 'idle'; selectedIds: string[] }
  | { status: 'confirming'; selectedIds: string[]; operation: 'archive' | 'delete' }
  | { status: 'submitting'; selectedIds: string[]; operation: 'archive' | 'delete'; requestId: string }
  | { status: 'failed'; selectedIds: string[]; operation: 'archive' | 'delete'; message: string };

const initialState: BulkActionState = {
  status: 'idle',
  selectedIds: [],
};

const bulkActionSlice = createSlice({
  name: 'bulkAction',
  initialState,
  reducers: {
    selectionChanged(state, action: PayloadAction<string[]>) {
      if (state.status === 'submitting') return;
      return { status: 'idle', selectedIds: action.payload };
    },

    confirmationRequested(
      state,
      action: PayloadAction<{ operation: 'archive' | 'delete' }>,
    ) {
      if (state.status !== 'idle') return;
      if (state.selectedIds.length === 0) return;
      return {
        status: 'confirming',
        selectedIds: state.selectedIds,
        operation: action.payload.operation,
      };
    },

    submissionStarted(state, action: PayloadAction<{ requestId: string }>) {
      if (state.status !== 'confirming') return;
      return {
        status: 'submitting',
        selectedIds: state.selectedIds,
        operation: state.operation,
        requestId: action.payload.requestId,
      };
    },

    submissionFailed(state, action: PayloadAction<{ message: string }>) {
      if (state.status !== 'submitting') return;
      return {
        status: 'failed',
        selectedIds: state.selectedIds,
        operation: state.operation,
        message: action.payload.message,
      };
    },

    dismissed() {
      return initialState;
    },
  },
});

status bukan boolean terpisah.
State shape mencegah illegal combinations.
Action names adalah domain vocabulary UI.
Reducer menjadi transition table yang bisa dites.

Menggunakan Context ketika ownership sebenarnya external store.
Menggunakan Zustand ketika ownership sebenarnya server cache.
Menggunakan Redux ketika ownership sebenarnya local component.

Action apa yang mengubah state ini?
Urutannya apa?
Payload-nya apa?
Middleware apa yang berjalan?

State slice ini berubah kapan dan consumer mana yang rerender?

Provider mana yang memberi capability ini?

- banyak ownership boundary,
- banyak feature team,
- turnover,
- onboarding,
- consistency requirement,
- refactor koordinasi,
- code review governance.

- user bisa select/unselect row,
- toolbar butuh jumlah selected,
- row butuh tahu apakah dirinya selected,
- bulk action butuh selected IDs.

type SelectionContextValue = {
  selectedIds: ReadonlySet<string>;
  toggle(id: string): void;
  clear(): void;
};

const SelectionContext = createContext<SelectionContextValue | null>(null);

function SelectionProvider({ children }: { children: React.ReactNode }) {
  const [selectedIds, setSelectedIds] = useState(() => new Set<string>());

  const value = useMemo<SelectionContextValue>(() => ({
    selectedIds,
    toggle(id) {
      setSelectedIds((prev) => {
        const next = new Set(prev);
        if (next.has(id)) next.delete(id);
        else next.add(id);
        return next;
      });
    },
    clear() {
      setSelectedIds(new Set());
    },
  }), [selectedIds]);

  return <SelectionContext.Provider value={value}>{children}</SelectionContext.Provider>;
}

Simple, scoped, easy.
But every consumer of SelectionContext observes same context value change.

type SelectionState = {
  selected: Record<string, true>;
  toggle(id: string): void;
  clear(): void;
};

const useSelection = create<SelectionState>((set) => ({
  selected: {},
  toggle: (id) =>
    set((state) => {
      const selected = { ...state.selected };
      if (selected[id]) delete selected[id];
      else selected[id] = true;
      return { selected };
    }),
  clear: () => set({ selected: {} }),
}));

function Row({ id }: { id: string }) {
  const isSelected = useSelection((state) => Boolean(state.selected[id]));
  const toggle = useSelection((state) => state.toggle);
  return <button aria-pressed={isSelected} onClick={() => toggle(id)}>{id}</button>;
}

Granular and compact.
But global singleton needs discipline or scoped store provider.

const selectionSlice = createSlice({
  name: 'selection',
  initialState: { selected: {} as Record<string, true> },
  reducers: {
    rowToggled(state, action: PayloadAction<string>) {
      const id = action.payload;
      if (state.selected[id]) delete state.selected[id];
      else state.selected[id] = true;
    },
    selectionCleared(state) {
      state.selected = {};
    },
  },
});

const selectIsSelected = (id: string) => (state: RootState) =>
  Boolean(state.selection.selected[id]);

More structure.
Better action vocabulary, debugging, and shared convention.

Small table UI detail? Context/local.
Large interactive workspace? Zustand.
Audit-relevant workflow? Redux Toolkit.

Fetch server data, put it into Context/Zustand/Redux manually, then manually track loading/error/stale/invalidation.

- owned by server,
- can become stale without local action,
- has cache lifecycle,
- has refetch/invalidation semantics,
- has loading/error/retry state,
- has optimistic mutation conflict risk,
- can be shared by query key.

- Consumer rerenders when the context value it reads changes.
- Provider value identity matters.
- Splitting context can reduce blast radius.
- Context is fine for low-frequency dependencies.
- Context is not a fine-grained selector subscription system by default.

Value changes rarely or consumer count is controlled.

Hundreds of rows consume high-frequency changing state.

- Component subscribes to selected slice.
- Selector/equality controls rerender.
- Store update can be granular if selectors are stable.
- Bad selectors returning new objects cause rerenders.
- Global store can create hidden dependencies.

Many consumers need different small slices.

Team lacks store conventions and state becomes opaque global mutable architecture.

- React-Redux uses subscription and selector model.
- Selectors can memoize derived data.
- Normalized state helps update locality.
- Action dispatch is explicit and observable.
- Boilerplate/convention overhead exists.

State transition trace and team convention matter as much as render performance.

The state is component-local or purely server-owned.

+ stronger conventions
+ better traceability
+ clearer transition vocabulary
+ easier team-wide policy
- more ceremony
- more upfront design
- more abstraction surface

- context value changes frequently,
- many consumers read small parts,
- splitting providers becomes awkward,
- rerender fan-out is visible in profiler.

1. Identify context value shape.
2. Separate read state from commands.
3. Move state and commands to external store.
4. Replace context consumer with selector hook.
5. Keep provider only if store must be scoped per subtree.
6. Add tests for state transitions.
7. Profile before/after.

const { selectedIds, toggle } = useSelectionContext();
const selected = selectedIds.includes(id);

const selected = useSelectionStore((s) => Boolean(s.selected[id]));
const toggle = useSelectionStore((s) => s.toggle);

No component should subscribe to more state than it renders.

- action vocabulary becomes important,
- many teams change the same store,
- debugging needs timeline,
- side effects need consistent middleware,
- normalized entity state grows,
- store conventions are drifting.

1. Extract event names from Zustand actions.
2. Define slice state and reducers.
3. Move derived reads into selectors.
4. Move async orchestration to thunk/listener/RTK Query boundary.
5. Add action-level tests.
6. Deprecate old store action by action.

- slice is only used by one feature,
- action log provides no value,
- state is UI-only and small,
- reducer ceremony hides simple behavior,
- team wants feature-local ownership.

1. Audit slice consumers.
2. If only one route/page owns it, move state to page reducer or Zustand scoped store.
3. Replace global selectors with feature hook.
4. Keep action names as command names.
5. Delete reducer/middleware only after tests pass.

- state is server-owned,
- local update is mostly cache update,
- code manually tracks loading/error/refetch,
- invalidation bugs appear,
- multiple pages fetch same entity.

1. Identify server authority.
2. Define query keys.
3. Replace manual fetch effect/store state with query hook.
4. Move mutation lifecycle to mutation API.
5. Replace manual entity sync with invalidation or optimistic cache update.
6. Keep only client-owned UI state in store.

Context:
  - theme
  - permission reader
  - analytics

Query cache:
  - users
  - reports
  - metrics

Zustand:
  - dashboard layout
  - open panels
  - local workspace filters not shareable in URL

URL:
  - active tab
  - committed filters
  - pagination

Redux Toolkit:
  - only if dashboard workflows need shared action governance

Context:
  - case permission reader
  - audit logger capability
  - command bus capability for page-level actions

Query cache:
  - case details
  - documents
  - related parties
  - timeline

Zustand:
  - local workbench panel layout
  - selected document IDs
  - open drawers

Redux Toolkit:
  - cross-feature enforcement workflow state
  - bulk action state
  - normalized client-only review graph

State machine:
  - escalation lifecycle
  - multi-step approval with legal states

Context:
  - theme tokens
  - density
  - direction
  - form field linkage
  - compound component coordination

Local state:
  - open state for primitive when uncontrolled
  - focus index
  - transient interaction state

External store:
  - usually avoid inside primitive design-system components

Local reducer:
  - small editor sections

Zustand/scoped external store:
  - large editor document state
  - selection/cursor/sidebar state
  - history/undo stack if client-owned

Query cache:
  - server document loading/saving

Redux Toolkit:
  - if editor state shared across many product modules with action governance

State machine:
  - save lifecycle, conflict resolution, publish workflow

# ADR: State ownership for <feature>

## Context
What state is being introduced?
Who reads it?
Who writes it?
How often does it change?

## State Category
- [ ] local
- [ ] derived
- [ ] lifted
- [ ] context capability
- [ ] shared client state
- [ ] server state
- [ ] URL state
- [ ] persistent client state
- [ ] workflow state

## Decision
We will use <Context/Zustand/Redux Toolkit/Query Cache/Local>.

## Why
Explain ownership, lifecycle, sharing radius, update frequency, and governance need.

## Alternatives Rejected
Why not local?
Why not Context?
Why not Zustand?
Why not Redux Toolkit?
Why not query cache?

## Invariants
What must always be true?

## Failure Modes
What can go wrong and how will we detect it?

## Migration Plan
How can this decision be reversed if scale changes?

Is this state server-owned?
If yes, why is it not in a query cache?

Is this state read by many unrelated branches?
If yes, why is the sharing radius so wide?

Is this Context value changing frequently?
If yes, how is rerender fan-out controlled?

Is this Zustand store a singleton?
If yes, should it be scoped per page/session/test?

Is this Redux slice local to one component?
If yes, why is it global?

Are raw setters exposed across boundaries?
If yes, what invariant prevents illegal transitions?

Are actions named after UI events or domain intents?
Is that intentional?

Is persistence versioned and cleared on logout/tenant switch?

Are selectors stable?
Do they allocate new objects every call?

Can this state be reset by key/route unmount instead of global mutation?

One AppContext contains user, permissions, theme, filters, drafts, notifications, and setters.

Split by capability/domain/lifecycle.
Move volatile shared state to external store.
Move server state to query cache.
Move local drafts down.

Every feature creates a global singleton store.
State ownership becomes invisible.

Require store owner per feature.
Prefer scoped store for route/workspace state.
Document persistence/version policy.
Add selectors and action naming convention.

Every input change dispatches global actions despite no shared/governed need.

Keep draft local.
Commit meaningful intent upward.
Use Redux only for workflow/domain transition, not every transient edit.

Store tracks data, loading, error, lastFetchedAt, retry, stale flags, invalidation maps.

Use TanStack Query or RTK Query.
Keep client-only coordination state in store.

Team rule says everything must use Redux, or everything must use Zustand, or Context only.

Classify state first.
Use multiple tools with explicit boundaries.
Create decision matrix.

1. Can it be derived during render?
   -> derive, do not store.

2. Is it owned by one component?
   -> local state.

3. Do several children need to coordinate?
   -> lift to closest common owner.

4. Is it shareable browser/navigation state?
   -> URL state.

5. Is it server-owned?
   -> query cache / RTK Query.

6. Is it a stable subtree dependency/capability?
   -> Context.

7. Is it shared client state needing fine-grained subscription and low ceremony?
   -> Zustand.

8. Is it shared client state needing governance, action trace, middleware, and team convention?
   -> Redux Toolkit.

9. Is it a legal-state workflow with guards/actions/invoked async behavior?
   -> reducer/state machine.

Local state:
  component-specific transient state

useReducer:
  local complex transition/invariant

Context:
  capability/configuration/subtree dependency

URL:
  shareable navigation/search state

Query cache:
  server-owned data

Zustand:
  shared client UI/workspace state needing selectors

Redux Toolkit:
  governed shared client state with action/middleware/team-scale needs

State machine:
  explicit workflow lifecycle with legal/illegal states

local / derived / lifted / context / URL / server / external store / workflow / persistent

Which state is currently too global?
Which state is currently too local?
Which state is duplicated?
Which state has unclear authority?

- capability context,
- query cache data,
- local page state,
- Zustand feature store,
- Redux governed slice if truly needed.

- Context,
- Zustand,
- Redux Toolkit.

bundle/API surface,
render fan-out,
testability,
action observability,
migration cost.

Context is not a global store replacement.
Zustand is not a license for ungoverned global state.
Redux Toolkit is not mandatory for every shared state.
Server state does not belong in random client stores.
The correct tool follows from authority, ownership, lifecycle, sharing radius, volatility, and governance.