const [open, setOpen] = useState(false);

confirmation dialog
nested modal
drawer
popover
toast
command palette
route modal
unsaved-changes prompt
permission dialog
async confirm
loading modal
error recovery dialog
modal opened from table row
modal opened from portal child
mobile bottom sheet
focus trap
scroll lock
Escape handling
outside click policy
z-index conflict

1. visual container
2. lifecycle ownership
3. interaction contract

Tooltip memakai modal semantics → keyboard experience buruk.
Dialog tanpa modal semantics → screen reader dan focus leakage.
Toast masuk overlay stack modal → notifikasi memblokir UX.
Popover diperlakukan seperti global modal → state ownership melebar tanpa perlu.

import { createPortal } from "react-dom";

function ModalPortal({ children }: { children: React.ReactNode }) {
  const root = document.getElementById("overlay-root");

  if (!root) return null;

  return createPortal(children, root);
}

DOM tree berbeda.
React tree tetap sama.
Context tetap bekerja.
Event bubbling mengikuti React tree.

function Row() {
  return (
    <div onClick={() => console.log("row clicked")}>
      <button>Open modal</button>
      <ModalPortal>
        <div onClick={(event) => event.stopPropagation()}>
          Modal content
        </div>
      </ModalPortal>
    </div>
  );
}

Siapa pemilik lifecycle overlay ini?

function UserAvatarMenu() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Menu</button>
      {open && <AvatarMenu onClose={() => setOpen(false)} />}
    </>
  );
}

overlay tidak perlu dibuka dari tempat lain
tidak butuh promise/result global
tidak perlu stack coordination kompleks
tidak memengaruhi route
tidak harus survive parent re-render/remount

function InvoicePage() {
  const [editingInvoiceId, setEditingInvoiceId] = useState<string | null>(null);

  return (
    <>
      <InvoiceTable onEdit={(id) => setEditingInvoiceId(id)} />
      {editingInvoiceId && (
        <EditInvoiceDialog
          invoiceId={editingInvoiceId}
          onClose={() => setEditingInvoiceId(null)}
        />
      )}
    </>
  );
}

Page owns selection.
Dialog owns local draft.
Server cache owns loaded invoice.

confirm delete
show alert
open command palette
open global search
show toast
show permission dialog

backdrop click
Escape
close button
confirm
cancel
route change
parent unmount
permission changed
server success
server failure
timeout

type OverlayCloseReason =
  | "escape"
  | "backdrop"
  | "close-button"
  | "cancel"
  | "confirm"
  | "route-change"
  | "parent-unmount"
  | "programmatic";

type OverlayCloseEvent = {
  reason: OverlayCloseReason;
  source?: string;
};

type ConfirmDialogProps = {
  title: string;
  message: string;
  onClose: (event: OverlayCloseEvent) => void;
  onConfirm: () => void | Promise<void>;
};

Apakah backdrop click boleh close?
Apakah Escape boleh close?
Apakah close bisa dicegah ketika pending?
Apakah close berarti cancel atau abandon?
Apakah close mengembalikan result?
Apakah unsaved changes butuh confirmation nested?

const confirmed = await confirm({
  title: "Delete invoice?",
  message: "This action cannot be undone.",
});

if (confirmed) {
  await deleteInvoice(invoiceId);
}

promise harus resolve tepat sekali
promise tidak boleh menggantung saat provider unmount
cancel harus resolve false atau reject dengan alasan eksplisit
nested confirm harus punya stack ordering
route change harus cleanup

type OverlayId = string;

type OverlayKind = "confirm" | "custom";

type OverlayDescriptor = {
  id: OverlayId;
  kind: OverlayKind;
  props: unknown;
  modal: boolean;
  createdAt: number;
};

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

type OverlayEvent =
  | { type: "OPEN"; overlay: OverlayDescriptor }
  | { type: "CLOSE"; id: OverlayId }
  | { type: "CLOSE_TOP" }
  | { type: "CLEAR" };

function overlayReducer(state: OverlayState, event: OverlayEvent): OverlayState {
  switch (event.type) {
    case "OPEN":
      return {
        ...state,
        stack: [...state.stack, event.overlay],
      };

    case "CLOSE":
      return {
        ...state,
        stack: state.stack.filter((overlay) => overlay.id !== event.id),
      };

    case "CLOSE_TOP":
      return {
        ...state,
        stack: state.stack.slice(0, -1),
      };

    case "CLEAR":
      return { stack: [] };

    default:
      return state;
  }
}

type OverlayApi = {
  confirm(input: ConfirmInput): Promise<boolean>;
  close(id: OverlayId): void;
};

const OverlayContext = createContext<OverlayApi | null>(null);

export function useOverlay() {
  const value = useContext(OverlayContext);

  if (!value) {
    throw new Error("useOverlay must be used inside OverlayProvider");
  }

  return value;
}

type Resolver = {
  resolve(value: boolean): void;
  reject(error: unknown): void;
};

function OverlayProvider({ children }: { children: React.ReactNode }) {
  const [state, dispatch] = useReducer(overlayReducer, { stack: [] });
  const resolversRef = useRef(new Map<OverlayId, Resolver>());

  const close = useCallback((id: OverlayId) => {
    const resolver = resolversRef.current.get(id);
    resolver?.resolve(false);
    resolversRef.current.delete(id);
    dispatch({ type: "CLOSE", id });
  }, []);

  const confirm = useCallback((input: ConfirmInput) => {
    const id = crypto.randomUUID();

    const promise = new Promise<boolean>((resolve, reject) => {
      resolversRef.current.set(id, { resolve, reject });
    });

    dispatch({
      type: "OPEN",
      overlay: {
        id,
        kind: "confirm",
        modal: true,
        props: input,
        createdAt: Date.now(),
      },
    });

    return promise;
  }, []);

  useEffect(() => {
    return () => {
      for (const resolver of resolversRef.current.values()) {
        resolver.resolve(false);
      }

      resolversRef.current.clear();
    };
  }, []);

  const api = useMemo(() => ({ confirm, close }), [confirm, close]);

  return (
    <OverlayContext.Provider value={api}>
      {children}
      <OverlayHost
        stack={state.stack}
        close={close}
        resolversRef={resolversRef}
      />
    </OverlayContext.Provider>
  );
}

type OverlayHostProps = {
  stack: OverlayDescriptor[];
  close(id: OverlayId): void;
  resolversRef: React.MutableRefObject<Map<OverlayId, Resolver>>;
};

function OverlayHost({ stack, close, resolversRef }: OverlayHostProps) {
  const root = document.getElementById("overlay-root");

  if (!root) return null;

  return createPortal(
    <>
      {stack.map((overlay, index) => {
        const isTop = index === stack.length - 1;

        if (overlay.kind === "confirm") {
          return (
            <ConfirmLayer
              key={overlay.id}
              overlay={overlay}
              isTop={isTop}
              onCancel={() => close(overlay.id)}
              onConfirm={() => {
                resolversRef.current.get(overlay.id)?.resolve(true);
                resolversRef.current.delete(overlay.id);
                close(overlay.id);
              }}
            />
          );
        }

        return null;
      })}
    </>,
    root,
  );
}

[]
[ConfirmDelete]
[EditDrawer, UnsavedChangesDialog]
[CommandPalette, NestedHelpDialog]

Top overlay menerima Escape.
Top modal menentukan background inert.
Focus berada di top modal.
Backdrop milik layer yang tepat.
Z-index berasal dari stack index, bukan angka magic tersebar.
Route change cleanup sesuai policy.

function selectTopOverlay(state: OverlayState) {
  return state.stack[state.stack.length - 1] ?? null;
}

function selectHasModal(state: OverlayState) {
  return state.stack.some((overlay) => overlay.modal);
}

function useEscapeToCloseTop({
  enabled,
  onCloseTop,
}: {
  enabled: boolean;
  onCloseTop: () => void;
}) {
  useEffect(() => {
    if (!enabled) return;

    function onKeyDown(event: KeyboardEvent) {
      if (event.key !== "Escape") return;

      event.preventDefault();
      onCloseTop();
    }

    document.addEventListener("keydown", onKeyDown);

    return () => {
      document.removeEventListener("keydown", onKeyDown);
    };
  }, [enabled, onCloseTop]);
}

Apakah Escape close semua overlay atau hanya top?
Apakah Escape disabled saat pending?
Apakah alert dialog destructive boleh Escape?
Apakah nested overlay menang atas parent?
Apakah Escape dalam text editor/search input tetap close?

Escape hanya menutup top dismissible layer.
Non-dismissible pending layer harus mengabaikan Escape atau menampilkan reason.
Nested overlay tidak boleh membuat parent ikut close.

mousedown inside, mouseup outside
mousedown outside, mouseup inside
drag selection
nested popover in modal
portal child outside DOM subtree
mobile touch events
scrollbar click

function Backdrop({ onInteractOutside }: { onInteractOutside: () => void }) {
  return (
    <div
      role="presentation"
      onMouseDown={(event) => {
        if (event.target !== event.currentTarget) return;
        onInteractOutside();
      }}
    />
  );
}

pointer down outside
focus outside
interact outside
nested layer exclusion
branch/portal awareness

Focus masuk ke dialog saat dibuka.
Tab dan Shift+Tab tetap di dalam dialog.
Escape menutup dialog jika dismissible.
Background tidak bisa diinteraksi.
Focus kembali ke trigger saat dialog ditutup.
Dialog punya accessible name.

function useFocusReturn(enabled: boolean) {
  const previousActiveElementRef = useRef<HTMLElement | null>(null);

  useLayoutEffect(() => {
    if (!enabled) return;

    previousActiveElementRef.current = document.activeElement as HTMLElement | null;

    return () => {
      previousActiveElementRef.current?.focus?.();
    };
  }, [enabled]);
}

function useInitialFocus(
  enabled: boolean,
  containerRef: React.RefObject<HTMLElement | null>,
) {
  useLayoutEffect(() => {
    if (!enabled) return;

    const container = containerRef.current;
    if (!container) return;

    const focusable = container.querySelector<HTMLElement>(
      "button, [href], input, select, textarea, [tabindex]:not([tabindex='-1'])",
    );

    focusable?.focus();
  }, [enabled, containerRef]);
}

useLayoutEffect dipakai agar focus terjadi sebelum browser paint berikutnya.
SSR harus guard document/window access.
Focus trap production lebih kompleks daripada querySelector sederhana.

document.body.style.overflow = "hidden";

multiple modals
scrollbar width shift
mobile Safari
body scroll position
nested lock
route transition cleanup

let lockCount = 0;
let previousOverflow = "";

export function lockBodyScroll() {
  if (lockCount === 0) {
    previousOverflow = document.body.style.overflow;
    document.body.style.overflow = "hidden";
  }

  lockCount += 1;

  return () => {
    lockCount -= 1;

    if (lockCount === 0) {
      document.body.style.overflow = previousOverflow;
    }
  };
}

function useBodyScrollLock(enabled: boolean) {
  useLayoutEffect(() => {
    if (!enabled) return;
    return lockBodyScroll();
  }, [enabled]);
}

native inert attribute
aria-hidden siblings
focus trap
pointer-events blocking backdrop

placement: left | right | bottom
dismissible: boolean
swipe-to-close: mobile only
snap points
resize behavior
focus initial target
route back behavior

URL/entity id → server-state cache → drawer draft state → mutation → invalidation → close

// Avoid
type DrawerState = {
  open: boolean;
  invoice: Invoice;
};

// Prefer
type DrawerState = {
  editingInvoiceId: string | null;
};

/invoices
/invoices?modal=create
/invoices?edit=inv_123
/invoices/inv_123?view=activity

function closeModal() {
  navigate({ search: removeModalParams(location.search) });
}

Modal open state di URL, tetapi local state juga punya open boolean.

function DeleteInvoiceButton({ invoiceId }: { invoiceId: string }) {
  const overlay = useOverlay();
  const deleteInvoice = useDeleteInvoiceMutation();

  async function onClick() {
    const confirmed = await overlay.confirm({
      title: "Delete invoice?",
      message: "This cannot be undone.",
      confirmLabel: "Delete",
      tone: "danger",
    });

    if (!confirmed) return;

    await deleteInvoice.mutateAsync({ invoiceId });
  }

  return <button onClick={onClick}>Delete</button>;
}

1. confirm closes, mutation pending appears on page row
2. confirm stays open with pending confirm button

<button disabled={pending} onClick={onConfirm}>
  {pending ? "Deleting..." : "Delete"}
</button>

function Toolbar() {
  const { confirm } = useOverlay();

  async function clearAll() {
    if (!(await confirm({ title: "Clear all filters?" }))) return;
    // command
  }

  return <button onClick={clearAll}>Clear</button>;
}

caller tidak tahu implementasi dialog
copywriting bisa distandardisasi
accessibility centralized
stack/focus/scroll policy centralized
testing bisa mock confirm result

semua flow memakai global confirm sehingga domain-specific UX hilang
manager menjadi dumping ground
overlay result melewati state ownership yang benar

it("closes only top overlay", () => {
  const state = {
    stack: [makeOverlay("a"), makeOverlay("b")],
  };

  expect(overlayReducer(state, { type: "CLOSE_TOP" }).stack.map((x) => x.id))
    .toEqual(["a"]);
});

open dialog
focus moves into dialog
Tab stays inside dialog
Escape closes if dismissible
focus returns to trigger
background not interactable

confirm resolves true on confirm
confirm resolves false on cancel
provider unmount resolves/rejects pending promise
nested confirm resolves correct promise

click delete
confirmation appears
confirm mutation runs once
row shows pending/delete state
cache invalidates
modal closes
focus returns

overlay.opened
overlay.closed
overlay.confirmed
overlay.cancelled
overlay.blocked_close
modal.focus_return_failed
modal.duplicate_confirm_prevented

type OverlayTelemetry = {
  overlayKind: string;
  overlayId: string;
  reason?: OverlayCloseReason;
  stackDepth: number;
  route: string;
  pending?: boolean;
};

const [showDelete, setShowDelete] = useState(false);
const [showEdit, setShowEdit] = useState(false);
const [showHistory, setShowHistory] = useState(false);
const [showUnsaved, setShowUnsaved] = useState(false);

type ModalState =
  | { type: "closed" }
  | { type: "delete"; invoiceId: string }
  | { type: "edit"; invoiceId: string }
  | { type: "history"; invoiceId: string };

User clicks backdrop.
App treats it like explicit cancel.
Unsaved draft disappears.

Model close reason.
Guard destructive close.
Ask nested confirmation if needed.

Click inside modal triggers parent row click.

Understand React tree bubbling.
Move portal higher or stop propagation inside overlay layer.

Keyboard user tabs into background while modal is open.

Focus trap + inert background + accessible dialog semantics.

confirm() promise never resolves after route change.

Provider cleanup resolves/rejects all pending overlay promises.

Dropdown appears behind modal.
Toast appears above destructive alert.

Centralize layer tokens and stack calculation.
Do not hardcode z-index in random components.

Business workflow state is hidden inside modal service.

Keep overlay manager generic.
Keep domain workflow in page hook, reducer, machine, or actor.

What type of overlay is this?
Who owns its lifecycle?
Is open state local, page-level, route-level, or app-level?
Does it return a result?
Can it be dismissed by Escape?
Can it be dismissed by backdrop?
What happens while async command is pending?
Where does focus go when opened?
Where does focus return when closed?
Does it need scroll lock?
Does background need inert?
Can overlays be nested?
What is the stack policy?
What is the route-change cleanup policy?
What should be tested?

ownership model
stack model
close contract
result contract
focus management
keyboard policy
scroll lock
inert background
route policy
async behavior
testing and observability

Use local overlay state until lifecycle coordination becomes cross-cutting.
Use page-owned overlay state when it belongs to a route/screen.
Use app-level overlay capability only for generic overlay services.
Never let the overlay manager become the hidden workflow engine.