Library apa yang harus dipakai?

State ini milik siapa?
Siapa yang boleh mengubahnya?
Berapa lama state ini hidup?
Apakah state ini harus bisa di-share, di-refresh, di-cache, di-serialize, di-audit, atau di-reset?
Apa invariant yang tidak boleh dilanggar?

1. Is it purely visual and local?             → local state / ref
2. Is it derived from props/state/cache?      → compute, do not store
3. Is it shared by siblings?                  → closest owner / lift state
4. Is it shareable/bookmarkable?              → URL state
5. Is the server authoritative?               → server-state cache
6. Does it come from browser/external system? → useSyncExternalStore adapter
7. Does it encode workflow transitions?       → reducer / state machine
8. Is it high-frequency global UI state?      → external store with selectors

Input: a piece of state S
Output: recommended state boundary and tool

1. Can S be computed from existing data during render?
   - Yes: do not store it.
   - No: continue.

2. Is S only needed by one component instance?
   - Yes: local useState/useReducer/useRef.
   - No: continue.

3. Do all readers/writers share a close parent?
   - Yes: lift state to that parent and pass props/callbacks.
   - No: continue.

4. Should S be visible in browser URL or survive refresh/share link?
   - Yes: URL state.
   - No: continue.

5. Is S authoritative on the server or fetched remotely?
   - Yes: server-state cache.
   - No: continue.

6. Is S produced by an external mutable source outside React?
   - Yes: useSyncExternalStore or library built around it.
   - No: continue.

7. Does S represent a workflow with legal/illegal transitions?
   - Yes: reducer or state machine.
   - No: continue.

8. Does S need broad sharing with high-frequency updates?
   - Yes: external store with selector subscriptions.
   - No: scoped context or reducer + context.

const [isOpen, setOpen] = useState(false);
const [draftName, setDraftName] = useState('');
const [selectedTab, setSelectedTab] = useState('overview');

- updates are scattered across many handlers
- multiple fields must change atomically
- transition legality matters
- state must be read/written far away
- state mirrors server data

type State =
  | { status: 'idle' }
  | { status: 'editing'; draft: Draft }
  | { status: 'saving'; draft: Draft; requestId: string }
  | { status: 'failed'; draft: Draft; error: string };

type Event =
  | { type: 'editStarted'; draft: Draft }
  | { type: 'fieldChanged'; field: keyof Draft; value: string }
  | { type: 'saveRequested'; requestId: string }
  | { type: 'saveSucceeded'; requestId: string }
  | { type: 'saveFailed'; requestId: string; error: string };

- selected row controls details panel
- tab selection controls tab panel
- filter form controls result list inside one page
- selected item controls action toolbar

?status=open&sort=created_desc&page=2

?state=%7B%22internalTabIndex%22%3A2%2C%22modal%22%3Atrue%7D

- theme capability
- design-system density
- locale/direction
- form field ID linkage
- modal service capability
- permission capability
- analytics client
- route-level command dispatcher

sharing radius is subtree-scoped
update frequency is low or controlled
value represents capability/configuration
provider placement is intentional

- complex form section
- wizard screen
- selection + bulk action state
- modal orchestration inside one feature
- local feature workflow

- client-side app shell state shared widely
- high-frequency state with selector subscriptions
- cross-route UI state
- browser API adapter
- feature store with independent consumers
- microfrontend bridge state

const value = useSyncExternalStore(
  store.subscribe,
  store.getSnapshot,
  store.getServerSnapshot
);

- async
- stale by nature
- shared across screens
- needs cache key
- needs invalidation
- may be refreshed in background
- may need optimistic mutation
- authoritative source is not React

server record → user edits locally → user submits command → server accepts/rejects

server record → UI reads → mutation invalidates/refetches → UI observes fresh cache

idle → confirming → submitting → succeeded
idle → confirming → submitting → failed → retrying

const [isLoading, setLoading] = useState(false);
const [isSuccess, setSuccess] = useState(false);
const [isError, setError] = useState(false);
const [isConfirmOpen, setConfirmOpen] = useState(false);

isLoading=true, isSuccess=true, isError=true, isConfirmOpen=true

type State =
  | { status: 'idle' }
  | { status: 'confirming' }
  | { status: 'submitting'; requestId: string }
  | { status: 'succeeded' }
  | { status: 'failed'; error: string };

input draft     → local form state
committed query → URL state
results         → server-state cache keyed by URL params
selection       → local/lifted page state

One giant SearchContext containing draft, committed params, results, loading, selected rows, errors, and server data.

case record       → server-state cache
current command   → reducer/state machine
permissions       → capability context
confirmation UI   → modal orchestrator
optimistic status → mutation/cache layer
local notes draft → local state

field drafts       → form state
current step       → reducer/state machine
server validation  → mutation result/cache
route step         → URL only if shareable/resumable
submission state   → action/mutation lifecycle

If the step cannot legally be visited before previous validation succeeds, encode that in transitions, not in scattered if-statements.

notification list          → server-state cache
unread count               → server-state cache or external push-backed store
open/closed panel          → local/app shell state
optimistic mark-as-read    → mutation + optimistic cache update
realtime subscription      → external event source → cache invalidation/update

theme tokens      → Context + CSS variables
persisted choice  → browser storage adapter
system preference → browser media query external source
component state   → local/compound context

# ADR: Search Filter State Placement

## Context
Search filters must survive refresh, support sharing links, and drive server result cache.

## Decision
Committed filters live in URL search params.
Draft filters live locally inside SearchFilterForm.
Results are loaded through server-state cache keyed by canonical URL params.

## Consequences
- Browser back/forward restores committed filters.
- Draft changes do not refetch until submit.
- Query key generation must canonicalize param ordering.
- PII fields must not be placed in URL.

- subscription granularity
- devtools/time travel
- event log
- middleware
- persistence
- cross-route sharing
- cache invalidation
- optimistic mutation
- workflow transitions

<AppContext.Provider value={{ user, theme, filters, results, modal, cart, permissions }}>
  <App />
</AppContext.Provider>

- unrelated consumers rerender together
- ownership disappears
- tests require giant provider setup
- reset semantics become unclear
- features couple through shared object shape

split by volatility, ownership, and domain boundary

const { data: invoice } = useInvoice(id);
const [localInvoice, setLocalInvoice] = useState(invoice);

- render directly from cache for read-only view
- create an explicit draft initialized when editing begins
- submit mutation and invalidate/update cache

?uiState={...large encoded blob...}

type Action =
  | { type: 'setAnyField'; key: string; value: unknown }
  | { type: 'setLoading'; value: boolean }
  | { type: 'setError'; value: string | null };

type Action =
  | { type: 'submitted'; requestId: string }
  | { type: 'succeeded'; requestId: string; result: Result }
  | { type: 'failed'; requestId: string; error: string };

1. Can this state be removed and derived?
2. Is there exactly one source of truth?
3. Is the owner the smallest correct owner?
4. Are update transitions named as domain/UI intents?
5. Does reset behavior follow component identity, URL navigation, cache invalidation, or explicit event?
6. Are async races guarded by request identity or cancellation?
7. Is server data managed as server state?
8. Is context carrying configuration/capability, or high-frequency mutable data?
9. Is persistence validated and versioned?
10. Are impossible states structurally impossible?

low sharing + low complexity             → local state
low sharing + high transition complexity → local reducer/state machine
medium sharing + low volatility          → lifted/context
high sharing + high volatility           → external store
server authority                         → server-state cache
serialization/shareability               → URL or persistence layer
workflow legality                        → reducer/state machine

case record             → server-state cache
edit notes draft        → local state
permission capability   → context
bulk selected documents → lifted/reducer state
current tab             → URL if shareable, local if not
modal stack             → overlay manager
approval workflow       → state machine
sidebar collapsed       → persistent preference
realtime lock status    → external subscription + cache update

1. Selected row in a table
2. Search filters on an admin page
3. Draft comment text
4. Current authenticated user
5. Permission check result
6. Sidebar collapsed preference
7. Infinite query result list
8. Multi-step onboarding progress
9. Toast queue
10. WebSocket connection status

Selected row is page-local shared state because table and toolbar need it.
If selection must survive refresh/share, move selectedId to URL.
If selection is high-volume across huge list virtualization, use a store/selector or table-local state depending on consumer radius.

const AppContext = createContext({
  user: null,
  theme: 'light',
  searchFilters: {},
  searchResults: [],
  selectedRows: [],
  modal: null,
  approvalStatus: 'idle',
});

- draft vs committed state
- URL serialization
- server cache key
- privacy limitation
- back button behavior

[ ] There is one source of truth.
[ ] Ownership is explicit.
[ ] Reset boundary is explicit.
[ ] Server-owned data is not copied unless intentionally forked as draft.
[ ] URL state is canonicalized and privacy-safe.
[ ] Persistence is validated, versioned, and cleared on auth boundary.
[ ] Context values are stable and scoped.
[ ] High-frequency shared state has selector-based subscription.
[ ] Reducer/state machine prevents impossible states.
[ ] Async transitions guard against stale responses.
[ ] Tests cover transition invariants and reset behavior.