Học từ Facebook #18: Keep-alive tab trong SPA

import {
  createContext,
  useCallback,
  useContext,
  useEffect,
  useLayoutEffect,
  useMemo,
  useRef,
  useState,
  type ReactNode,
} from 'react';

/**
 * "Cây con đang bị ẩn" (ý tưởng từ HiddenSubtreeContextProvider của Facebook).
 *
 * Khi một màn hình vẫn được giữ mount nhưng không hiển thị (keep-alive tab, dialog bị che…),
 * mọi thứ bên trong cần biết để tự dừng: video, timer, animation, log impression.
 *
 * Có 2 context:
 * - Reactive: đổi giá trị -> component dùng nó re-render. Tiện, nhưng đắt nếu cây lớn.
 * - Passive: chỉ có getCurrentState() + subscribe(). Đổi trạng thái KHÔNG làm re-render;
 *   ai quan tâm thì tự subscribe (dừng timer, pause video…). Facebook dùng loại này cho
 *   hầu hết các hook hạ tầng.
 */

export interface HiddenState {
  /** bị ẩn hẳn (vd: tab không active) */
  hidden: boolean;
  /** vẫn thấy nhưng ở "nền" (vd: browser tab ẩn, bị dialog che) */
  backgrounded: boolean;
}

export interface HiddenSubtreeStore {
  getCurrentState(): HiddenState;
  /** chỉ được gọi khi trạng thái gộp THỰC SỰ đổi */
  subscribe(listener: (state: HiddenState) => void): () => void;
}

const VISIBLE: HiddenState = { hidden: false, backgrounded: false };

const HiddenSubtreeContext = createContext<HiddenState>(VISIBLE);
const HiddenSubtreePassiveContext = createContext<HiddenSubtreeStore>({
  getCurrentState: () => VISIBLE,
  subscribe: () => () => {},
});

// Con bị ẩn nếu chính nó HOẶC bất kỳ tổ tiên nào bị ẩn (phép OR).
const merge = (a: HiddenState, b: HiddenState): HiddenState => ({
  hidden: a.hidden || b.hidden,
  backgrounded: a.backgrounded || b.backgrounded,
});
const same = (a: HiddenState, b: HiddenState) =>
  a.hidden === b.hidden && a.backgrounded === b.backgrounded;

export function HiddenSubtreeProvider({
  hidden,
  backgrounded = false,
  ignoreParent = false,
  children,
}: {
  hidden: boolean;
  backgrounded?: boolean;
  /** không gộp với tổ tiên (vd: một layer nổi lên trên cùng luôn hiển thị) */
  ignoreParent?: boolean;
  children: ReactNode;
}) {
  const parent = useContext(HiddenSubtreeContext);
  const parentStore = useContext(HiddenSubtreePassiveContext);

  const ownRef = useRef<HiddenState>({ hidden, backgrounded });
  const lastNotifiedRef = useRef<HiddenState | null>(null);
  const listenersRef = useRef(new Set<(state: HiddenState) => void>());

  const getCurrentState = useCallback(
    () => (ignoreParent ? ownRef.current : merge(ownRef.current, parentStore.getCurrentState())),
    [ignoreParent, parentStore],
  );

  // Gọi khi props của mình đổi HOẶC khi cha báo đổi. Chỉ phát cho listener nếu trạng thái
  // gộp khác lần phát trước: cha đổi backgrounded mà mình đang hidden sẵn thì con không cần biết.
  const notifyIfChanged = useCallback(() => {
    const next = getCurrentState();
    if (lastNotifiedRef.current && same(next, lastNotifiedRef.current)) return;
    lastNotifiedRef.current = next;
    Array.from(listenersRef.current).forEach((listener) => listener(next));
  }, [getCurrentState]);

  // layout effect: listener (vd: pause video) chạy cùng commit với lúc màn hình bị ẩn,
  // trước khi trình duyệt vẽ frame tiếp theo.
  useLayoutEffect(() => {
    ownRef.current = { hidden, backgrounded };
    notifyIfChanged();
  }, [hidden, backgrounded, notifyIfChanged]);

  useEffect(() => {
    if (ignoreParent) return;
    return parentStore.subscribe(notifyIfChanged);
  }, [ignoreParent, parentStore, notifyIfChanged]);

  const store = useMemo<HiddenSubtreeStore>(
    () => ({
      getCurrentState,
      subscribe(listener) {
        listenersRef.current.add(listener);
        return () => {
          listenersRef.current.delete(listener);
        };
      },
    }),
    [getCurrentState],
  );

  const merged = ignoreParent ? { hidden, backgrounded } : merge({ hidden, backgrounded }, parent);
  // useMemo theo 2 boolean: giá trị context chỉ đổi tham chiếu khi thực sự đổi
  const value = useMemo(
    () => ({ hidden: merged.hidden, backgrounded: merged.backgrounded }),
    [merged.hidden, merged.backgrounded],
  );

  return (
    <HiddenSubtreeContext.Provider value={value}>
      <HiddenSubtreePassiveContext.Provider value={store}>{children}</HiddenSubtreePassiveContext.Provider>
    </HiddenSubtreeContext.Provider>
  );
}

/** Reactive: component re-render mỗi khi trạng thái đổi. */
export function useHiddenSubtree(): HiddenState {
  return useContext(HiddenSubtreeContext);
}

/** true nếu bị ẩn hoặc đang ở nền. */
export function useIsHidden(): boolean {
  const { hidden, backgrounded } = useContext(HiddenSubtreeContext);
  return hidden || backgrounded;
}

/** Passive: lấy store để tự subscribe, không gây re-render. */
export function useHiddenSubtreePassive(): HiddenSubtreeStore {
  return useContext(HiddenSubtreePassiveContext);
}

/**
 * setInterval tự dừng khi cây con bị ẩn/ở nền và chạy lại khi hiện ra.
 * Dùng store passive nên việc ẩn/hiện không làm component re-render.
 */
export function useVisibleInterval(callback: () => void, ms: number) {
  const store = useHiddenSubtreePassive();
  const callbackRef = useRef(callback);
  useLayoutEffect(() => {
    callbackRef.current = callback;
  });

  useEffect(() => {
    let timer: ReturnType<typeof setInterval> | undefined;
    const sync = (state: HiddenState) => {
      const shouldRun = !state.hidden && !state.backgrounded;
      if (shouldRun && timer === undefined) {
        timer = setInterval(() => callbackRef.current(), ms);
      } else if (!shouldRun && timer !== undefined) {
        clearInterval(timer);
        timer = undefined;
      }
    };
    sync(store.getCurrentState());
    const unsubscribe = store.subscribe(sync);
    return () => {
      unsubscribe();
      clearInterval(timer);
    };
  }, [store, ms]);
}

/** Tab trình duyệt có đang bị ẩn không (Page Visibility API). */
export function useDocumentHidden(): boolean {
  const [hiddenDoc, setHiddenDoc] = useState(
    () => typeof document !== 'undefined' && document.visibilityState === 'hidden',
  );
  useEffect(() => {
    const onChange = () => setHiddenDoc(document.visibilityState === 'hidden');
    document.addEventListener('visibilitychange', onChange);
    return () => document.removeEventListener('visibilitychange', onChange);
  }, []);
  return hiddenDoc;
}

import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from 'react';
import { HiddenSubtreeProvider } from './hiddenSubtree';

/**
 * Keep-alive cho các "tab" của SPA (ý tưởng từ CometRouter + MaintainedRouteConfig + CometMainRoutes).
 *
 * Khi rời một tab được cấu hình `maintained`, cây React của nó KHÔNG bị unmount mà được giữ lại
 * (ẩn đi) trong một thời gian `maintainForMs`. Quay lại trong thời gian đó: hiện ra tức thì,
 * nguyên state, nguyên vị trí cuộn. Hết hạn: unmount để trả lại bộ nhớ.
 * Mỗi tab được bọc HiddenSubtreeProvider để code bên trong biết mình đang bị ẩn mà tự dừng.
 */

export interface KeepAliveRouteConfig {
  maintained: boolean;
  /** giữ bao lâu sau khi rời tab; null/undefined = giữ mãi (như Messenger của Facebook) */
  maintainForMs?: number | null;
}

export interface MaintainedEntry {
  key: string;
  /** thời điểm (Date.now()) sẽ bị huỷ, null = không hết hạn */
  expiresAt: number | null;
}

export interface KeepAliveOutletProps {
  activeKey: string;
  render: (key: string) => ReactNode;
  config: Record<string, KeepAliveRouteConfig | undefined>;
  /** giữ tối đa bao nhiêu tab ẩn cùng lúc; vượt quá thì huỷ tab rời đi lâu nhất */
  maxMaintained?: number;
  /**
   * Cách ẩn tab không active:
   * - 'display': display:none (rẻ nhất, nhưng phần tử cuộn bên trong có thể mất scrollTop)
   * - 'content-visibility': content-visibility:hidden, trình duyệt bỏ qua render nhưng giữ
   *   nguyên trạng thái render (kể cả vị trí cuộn của phần tử con).
   */
  hideMode?: 'display' | 'content-visibility';
  onMaintainedChange?: (entries: MaintainedEntry[]) => void;
}

interface KeepAliveInfo {
  routeKey: string;
  active: boolean;
}

const KeepAliveContext = createContext<KeepAliveInfo | null>(null);

/** Cho component bên trong biết nó thuộc tab nào và tab đó có đang active không. */
export function useKeepAliveInfo() {
  return useContext(KeepAliveContext);
}

function nextMaintained(
  list: MaintainedEntry[],
  prevKey: string,
  activeKey: string,
  config: KeepAliveOutletProps['config'],
  maxMaintained: number,
): MaintainedEntry[] {
  // 1. Tab vừa được mở lại: bỏ khỏi danh sách giữ (FB: `withoutKey(A, tabKey)` + clearTimeout).
  let next = list.filter((entry) => entry.key !== activeKey);
  // 2. Tab vừa rời đi: nếu được cấu hình maintained thì giữ lại kèm hạn huỷ.
  const prevConfig = config[prevKey];
  if (prevConfig?.maintained && !next.some((entry) => entry.key === prevKey)) {
    const ttl = prevConfig.maintainForMs;
    next = [...next, { key: prevKey, expiresAt: ttl != null ? Date.now() + ttl : null }];
  }
  // 3. Giới hạn số tab giữ lại: huỷ tab rời đi lâu nhất.
  if (next.length > maxMaintained) next = next.slice(next.length - maxMaintained);
  return next;
}

export function KeepAliveOutlet({
  activeKey,
  render,
  config,
  maxMaintained = Infinity,
  hideMode = 'content-visibility',
  onMaintainedChange,
}: KeepAliveOutletProps) {
  const [state, setState] = useState<{ activeKey: string; maintained: MaintainedEntry[] }>({
    activeKey,
    maintained: [],
  });

  // Tính danh sách giữ lại NGAY TRONG LÚC RENDER khi tab đổi ("adjust state when a prop
  // changes"). Nếu đợi tới effect, commit đổi tab sẽ không còn tab cũ trong cây -> React
  // unmount nó -> mất hết state, đúng điều keep-alive muốn tránh.
  let maintained = state.maintained;
  if (state.activeKey !== activeKey) {
    maintained = nextMaintained(state.maintained, state.activeKey, activeKey, config, maxMaintained);
    setState({ activeKey, maintained });
  }

  // Cấu hình đổi (vd: tắt keep-alive) thì bỏ các tab không còn được phép giữ.
  const allowed = maintained.filter((entry) => config[entry.key]?.maintained);
  if (allowed.length !== maintained.length) {
    maintained = allowed;
    setState({ activeKey, maintained });
  }

  // Hẹn giờ huỷ: đồng bộ timer với danh sách hiện tại. Effect chỉ lo side effect,
  // danh sách là nguồn sự thật duy nhất.
  const timersRef = useRef(new Map<string, ReturnType<typeof setTimeout>>());
  useEffect(() => {
    const timers = timersRef.current;
    const live = new Set(maintained.map((entry) => entry.key));
    timers.forEach((timer, key) => {
      if (!live.has(key)) {
        clearTimeout(timer);
        timers.delete(key);
      }
    });
    maintained.forEach(({ key, expiresAt }) => {
      if (expiresAt == null || timers.has(key)) return;
      timers.set(
        key,
        setTimeout(
          () => {
            timers.delete(key);
            setState((current) => ({
              ...current,
              maintained: current.maintained.filter((entry) => entry.key !== key),
            }));
          },
          Math.max(0, expiresAt - Date.now()),
        ),
      );
    });
  }, [maintained]);

  useEffect(() => {
    const timers = timersRef.current;
    return () => {
      timers.forEach((timer) => clearTimeout(timer));
      timers.clear();
    };
  }, []);

  useEffect(() => {
    onMaintainedChange?.(maintained);
  }, [maintained, onMaintainedChange]);

  // Thứ tự render ổn định theo lần đầu xuất hiện: đổi tab không làm React di chuyển node DOM
  // (gỡ ra chèn lại node chứa <iframe> làm nó tải lại, <video> bị gỡ khỏi document thì dừng phát).
  const orderRef = useRef<string[]>([]);
  if (!orderRef.current.includes(activeKey)) orderRef.current = [...orderRef.current, activeKey];

  const liveKeys = new Set([activeKey, ...maintained.map((entry) => entry.key)]);
  const keys = orderRef.current.filter((key) => liveKeys.has(key));

  // Container position:relative: tab ẩn (content-visibility) được đặt absolute, cần một khung
  // để không đè lên phần khác của trang.
  return (
    <div data-keepalive-outlet style={{ position: 'relative' }}>
      {keys.map((key) => {
        const active = key === activeKey;
        return (
          <div
            key={key}
            data-keepalive-key={key}
            aria-hidden={!active || undefined}
            // inert: tab ẩn không nhận focus/click và trình đọc màn hình bỏ qua
            inert={!active}
            style={
              active
                ? undefined
                : hideMode === 'display'
                  ? { display: 'none' }
                  : { contentVisibility: 'hidden', position: 'absolute', inset: 0, overflow: 'hidden' }
            }
          >
            <HiddenSubtreeProvider hidden={!active} backgrounded={!active}>
              <KeepAliveContext.Provider value={{ routeKey: key, active }}>{render(key)}</KeepAliveContext.Provider>
            </HiddenSubtreeProvider>
          </div>
        );
      })}
    </div>
  );
}