@ttdk-design-system/library-react 0.0.0-stage → 1.0.0

package/src/web/popover/popover.tsx

@@ -0,0 +1,702 @@
+"use client";
+import * as React from "react";
+import { useState, useRef, useEffect } from "react";
+
+export interface PopoverContentOptions {
+  /**
+   * Sisi penempatan relatif terhadap elemen pemicu (trigger).
+   * @default 'bottom'
+   */
+  side?: "top" | "right" | "bottom" | "left";
+
+  /**
+   * Penjajaran di sepanjang sumbu sisi yang dipilih.
+   * @default 'center'
+   */
+  align?: "start" | "center" | "end";
+
+  /**
+   * Jarak offset dalam pixel dari elemen pemicu (trigger).
+   * @default 8
+   */
+  sideOffset?: number;
+
+  /**
+   * Offset dalam pixel di sepanjang sumbu penjajaran (alignment axis).
+   * @default 0
+   */
+  alignOffset?: number;
+
+  /**
+   * Mencegah popover terpotong keluar dari batas viewport layar dengan memanfaatkan middleware flip dan shift.
+   * @default true
+   */
+  avoidCollisions?: boolean;
+
+  /**
+   * Batas kontainer pendeteksi benturan viewport.
+   */
+  collisionBoundary?: any;
+
+  /**
+   * Jarak padding minimal dalam pixel dari tepi layar saat terjadi benturan.
+   * @default 8
+   */
+  collisionPadding?: number;
+
+  /**
+   * Jarak padding minimal dalam pixel untuk elemen panah (arrow) dari sudut popover.
+   * @default 8
+   */
+  arrowPadding?: number;
+
+  /**
+   * Perilaku popover saat elemen pemicu tergulung keluar layar ('partial' | 'always').
+   */
+  sticky?: "partial" | "always";
+
+  /**
+   * Sembunyikan popover ketika pemicu terpisah atau tidak terlihat di viewport.
+   * @default false
+   */
+  hideWhenDetached?: boolean;
+}
+export type PopoverUiProps = UiProps;
+export interface PopoverProps {
+  /**
+   * Status visibilitas popover (mode terkontrol / controlled state).
+   * Mendukung `v-model:open` pada Vue 3 dan controlled prop `open` pada React.
+   */
+  open?: boolean;
+
+  /**
+   * Status visibilitas awal saat pertama kali dirender (mode tidak terkontrol / uncontrolled initial state).
+   * @default false
+   */
+  defaultOpen?: boolean;
+
+  /**
+   * Menampilkan elemen panah (arrow) penunjuk arah yang menunjuk ke elemen pemicu.
+   * @default false
+   */
+  arrow?: boolean;
+
+  /**
+   * Mengizinkan popover ditutup saat pengguna mengeklik area di luar popover atau menekan tombol `Escape`.
+   * Jika bernilai `false`, popover tidak akan tertutup dan event `onClosePrevent` akan dipanggil.
+   * @default true
+   */
+  dismissible?: boolean;
+
+  /**
+   * Mengaktifkan mode modal dengan menampilkan lapisan latar belakang redup (backdrop overlay)
+   * serta memblokir interaksi di luar popover dan mengunci scroll latar belakang.
+   * @default false
+   */
+  modal?: boolean;
+
+  /**
+   * Mengunci pengguliran halaman web (body scroll lock) saat popover sedang terbuka,
+   * sehingga pengguna tidak dapat menggulir halaman di latar belakang.
+   * Otomatis aktif saat `modal={true}` kecuali dinyatakan `false`.
+   * @default false
+   */
+  preventScroll?: boolean;
+
+  /**
+   * Alias untuk `preventScroll`.
+   * @default false
+   */
+  lockScroll?: boolean;
+
+  /**
+   * Menonaktifkan pemicu sehingga popover tidak dapat dibuka.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Opsi konfigurasi penempatan dan benturan popover (side, align, sideOffset, dsb.)
+   * ATAU elemen konten popover secara langsung jika tidak menggunakan slot/children.
+   */
+  content?: PopoverContentOptions | any;
+
+  /**
+   * Konten kustom panel popover (alias untuk konten popover jika `content` dipakai untuk konfigurasi).
+   * Menerima ReactNode, VNode, string, atau render function `({ close }) => ReactNode`.
+   */
+  panel?: any;
+
+  /**
+   * Konten kustom panel popover (kompatibilitas selaras dengan Dropdown panelContent).
+   * Menerima ReactNode, VNode, string, atau render function `({ close }) => ReactNode`.
+   */
+  panelContent?: any;
+
+  /**
+   * Pintasan posisi penempatan panel popover Floating UI ('top', 'bottom', 'left', 'right', dsb.)
+   * Selaras dengan konfigurasi content.side dan content.align.
+   * @default 'bottom'
+   */
+  placement?:
+    | "top"
+    | "top-start"
+    | "top-end"
+    | "bottom"
+    | "bottom-start"
+    | "bottom-end"
+    | "left"
+    | "left-start"
+    | "left-end"
+    | "right"
+    | "right-start"
+    | "right-end";
+
+  /**
+   * Jarak offset dalam pixel dari elemen pemicu (shorthand untuk content.sideOffset).
+   * @default 8
+   */
+  offsetDistance?: number;
+
+  /**
+   * Menjadikan popover memenuhi lebar kontainer penuh (full width 100%).
+   * @default false
+   */
+  block?: boolean;
+
+  /**
+   * Kustomisasi visual granular wrapper utama (UiProps).
+   */
+  ui?: PopoverUiProps;
+
+  /**
+   * Style inline CSS native untuk wrapper luar.
+   */
+  style?: React.CSSProperties;
+
+  /**
+   * Class CSS kustom untuk wrapper luar.
+   */
+  className?: string;
+
+  /**
+   * Class CSS kustom untuk pemicu (trigger container).
+   */
+  triggerClass?: string;
+
+  /**
+   * Style kustom untuk pemicu (UiProps).
+   */
+  triggerStyle?: UiProps;
+
+  /**
+   * Class CSS kustom untuk panel popover konten.
+   */
+  contentClass?: string;
+
+  /**
+   * Style kustom untuk panel popover konten (UiProps).
+   */
+  contentStyle?: UiProps;
+
+  /**
+   * Class CSS kustom untuk elemen panah (arrow).
+   */
+  arrowClass?: string;
+
+  /**
+   * Style kustom untuk elemen panah (UiProps).
+   */
+  arrowStyle?: UiProps;
+
+  /**
+   * Class CSS kustom untuk lapisan latar belakang redup (modal overlay).
+   */
+  overlayClass?: string;
+
+  /**
+   * Style kustom untuk lapisan latar belakang redup (UiProps).
+   */
+  overlayStyle?: UiProps;
+
+  /**
+   * Callback event saat status terbuka/tertutup berubah (kompatibel dengan v-model:open pada Vue 3).
+   */
+  onUpdateOpen?: (open: boolean) => void;
+
+  /**
+   * Callback event saat status terbuka/tertutup berubah (alias standar React).
+   */
+  onOpenChange?: (open: boolean) => void;
+
+  /**
+   * Callback event saat popover terbuka.
+   */
+  onOpen?: () => void;
+
+  /**
+   * Callback event saat popover ditutup.
+   */
+  onClose?: () => void;
+
+  /**
+   * Callback event saat pengguna mencoba menutup popover tetapi dicegah karena dismissible={false}.
+   */
+  onClosePrevent?: () => void;
+
+  /**
+   * Elemen pemicu (trigger), tombol, atau komponen anak lainnya.
+   */
+  children?: any;
+}
+
+/**
+ * Komponen Popover TTDK Design System — Selaras dengan Spesifikasi Nuxt UI Popover (UPopover):
+ * - Mendukung mode 'click' dan mode 'hover' dengan configurable openDelay dan closeDelay
+ * - Floating UI otomatis (computePosition, autoUpdate, flip, shift, offset, arrow)
+ * - Posisi cerdas (top, bottom, left, right, start, end)
+ * - Elemen panah (arrow) penunjuk arah dinamis
+ * - Mode modal dengan backdrop overlay
+ * - Penanganan dismissible & closePrevent (Esc key, outside click)
+ * - Dukungan controlled state (v-model:open) dan uncontrolled defaultOpen
+ */
+
+import {
+  computePosition,
+  autoUpdate,
+  flip,
+  shift,
+  offset,
+  arrow as floatingArrow,
+} from "@floating-ui/dom";
+import { buildUiVars, UiProps } from "../../core/types";
+
+let lockCount = 0;
+let originalOverflow = "";
+let originalPaddingRight = "";
+
+function lockBodyScroll() {
+  if (typeof document === "undefined") return;
+  if (lockCount === 0) {
+    originalOverflow = document.body.style.overflow;
+    originalPaddingRight = document.body.style.paddingRight;
+    const scrollBarWidth = window.innerWidth - document.documentElement.clientWidth;
+    document.body.style.overflow = "hidden";
+    if (scrollBarWidth > 0) {
+      document.body.style.paddingRight = scrollBarWidth + "px";
+    }
+  }
+  lockCount++;
+}
+
+function unlockBodyScroll() {
+  if (typeof document === "undefined") return;
+  lockCount = Math.max(0, lockCount - 1);
+  if (lockCount === 0) {
+    document.body.style.overflow = originalOverflow;
+    document.body.style.paddingRight = originalPaddingRight;
+  }
+}
+
+function Popover(props: PopoverProps) {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLDivElement>(null);
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const arrowRef = useRef<HTMLDivElement>(null);
+  const [isOpen, setIsOpen] = useState(() =>
+    props.open !== undefined ? props.open : Boolean(props.defaultOpen)
+  );
+
+  const cleanupAutoUpdateRef = useRef<any>(null);
+
+  function isOptionsConfig(val: any) {
+    if (!val || typeof val !== "object") return false;
+    return (
+      "side" in val ||
+      "align" in val ||
+      "sideOffset" in val ||
+      "alignOffset" in val ||
+      "avoidCollisions" in val ||
+      "collisionPadding" in val ||
+      "arrowPadding" in val
+    );
+  }
+
+  function getResolvedPlacement() {
+    if (props.placement) {
+      return props.placement;
+    }
+    if (
+      props.content &&
+      typeof props.content === "object" &&
+      isOptionsConfig(props.content)
+    ) {
+      const side = props.content.side || "bottom";
+      const align = props.content.align || "center";
+      return align === "center" ? side : `${side}-${align}`;
+    }
+    return "bottom";
+  }
+
+  function getResolvedOffset() {
+    if (props.offsetDistance !== undefined && props.offsetDistance !== null) {
+      return props.offsetDistance;
+    }
+    if (
+      props.content &&
+      typeof props.content === "object" &&
+      isOptionsConfig(props.content)
+    ) {
+      if (props.content.sideOffset !== undefined) {
+        return props.content.sideOffset;
+      }
+    }
+    return 8;
+  }
+
+  function updatePosition() {
+    if (!triggerRef.current || !popoverRef.current) return;
+    const placement = getResolvedPlacement();
+    const offsetVal = getResolvedOffset();
+    const avoidCollisions =
+      props.content &&
+      typeof props.content === "object" &&
+      isOptionsConfig(props.content)
+        ? props.content.avoidCollisions !== false
+        : true;
+    const collisionPadding =
+      props.content &&
+      typeof props.content === "object" &&
+      isOptionsConfig(props.content)
+        ? props.content.collisionPadding ?? 8
+        : 8;
+    const arrowPadding =
+      props.content &&
+      typeof props.content === "object" &&
+      isOptionsConfig(props.content)
+        ? props.content.arrowPadding ?? 8
+        : 8;
+    const middlewares: any[] = [
+      offset(offsetVal),
+      ...(avoidCollisions
+        ? [
+            flip({
+              padding: collisionPadding,
+              fallbackPlacements: [
+                "top",
+                "bottom",
+                "left",
+                "right",
+                "top-start",
+                "top-end",
+                "bottom-start",
+                "bottom-end",
+              ],
+            }),
+            shift({
+              padding: collisionPadding,
+            }),
+          ]
+        : []),
+    ];
+    if (props.arrow && arrowRef.current) {
+      middlewares.push(
+        floatingArrow({
+          element: arrowRef.current,
+          padding: arrowPadding,
+        })
+      );
+    }
+    computePosition(triggerRef.current, popoverRef.current, {
+      placement,
+      strategy: "absolute",
+      middleware: middlewares,
+    }).then(({ x, y, placement: finalPlacement, middlewareData }: any) => {
+      if (!popoverRef.current) return;
+      popoverRef.current.style.position = "absolute";
+      popoverRef.current.style.left = `${x}px`;
+      popoverRef.current.style.top = `${y}px`;
+      const [resolvedSide, resolvedAlign] = finalPlacement.split("-");
+      popoverRef.current.setAttribute("data-side", resolvedSide);
+      popoverRef.current.setAttribute("data-align", resolvedAlign || "center");
+      popoverRef.current.setAttribute("data-placement", finalPlacement);
+      if (props.arrow && middlewareData.arrow && arrowRef.current) {
+        const { x: arrowX, y: arrowY } = middlewareData.arrow;
+        const staticSideMap: Record<string, string> = {
+          top: "bottom",
+          right: "left",
+          bottom: "top",
+          left: "right",
+        };
+        const staticSide = staticSideMap[resolvedSide] || "top";
+        Object.assign(arrowRef.current.style, {
+          left: arrowX != null ? `${arrowX}px` : "",
+          top: arrowY != null ? `${arrowY}px` : "",
+          right: "",
+          bottom: "",
+          [staticSide]: "-4px",
+        });
+      }
+    });
+  }
+
+  function startFloating() {
+    stopFloating();
+    if (triggerRef.current && popoverRef.current) {
+      cleanupAutoUpdateRef.current = autoUpdate(
+        triggerRef.current,
+        popoverRef.current,
+        () => {
+          updatePosition();
+        }
+      );
+    }
+  }
+
+  function stopFloating() {
+    if (typeof cleanupAutoUpdateRef.current === "function") {
+      cleanupAutoUpdateRef.current();
+      cleanupAutoUpdateRef.current = null;
+    }
+  }
+
+  function openPopover() {
+    if (props.disabled) return;
+    if (!isOpen) {
+      setIsOpen(true);
+      if (props.onOpen) props.onOpen();
+      if (props.onUpdateOpen) props.onUpdateOpen(true);
+      if (props.onOpenChange) props.onOpenChange(true);
+    }
+    setTimeout(() => {
+      startFloating();
+      updatePosition();
+    }, 0);
+  }
+
+  function closePopover(force?: boolean) {
+    if (props.dismissible === false && !force) {
+      if (props.onClosePrevent) {
+        props.onClosePrevent();
+      }
+      return;
+    }
+    stopFloating();
+    if (isOpen) {
+      setIsOpen(false);
+      if (props.onClose) props.onClose();
+      if (props.onUpdateOpen) props.onUpdateOpen(false);
+      if (props.onOpenChange) props.onOpenChange(false);
+    }
+  }
+
+  function togglePopover() {
+    if (props.disabled) return;
+    if (isOpen) {
+      closePopover();
+    } else {
+      openPopover();
+    }
+  }
+
+  function handleTriggerClick() {
+    if (props.disabled) return;
+    togglePopover();
+  }
+
+  function handlePointerDown(event: any) {
+    if (!isOpen) return;
+    const target = event.target;
+    if (
+      rootRef.current &&
+      !rootRef.current.contains(target) &&
+      popoverRef.current &&
+      !popoverRef.current.contains(target)
+    ) {
+      closePopover();
+    }
+  }
+
+  function handleKeyDown(event: any) {
+    if (!isOpen) return;
+    if (event.key === "Escape") {
+      closePopover();
+    }
+  }
+
+  function handleOverlayClick() {
+    closePopover();
+  }
+
+  function renderPanelContent() {
+    if (props.panel) {
+      return typeof props.panel === "function"
+        ? props.panel({
+            close: () => closePopover(true),
+          })
+        : props.panel;
+    }
+    if (props.panelContent) {
+      return typeof props.panelContent === "function"
+        ? props.panelContent({
+            close: () => closePopover(true),
+          })
+        : props.panelContent;
+    }
+    if (props.content && !isOptionsConfig(props.content)) {
+      return typeof props.content === "function"
+        ? props.content({
+            close: () => closePopover(true),
+          })
+        : props.content;
+    }
+    return null;
+  }
+
+  useEffect(() => {
+    if (props.open !== undefined) {
+      setIsOpen(props.open);
+    }
+  }, [props.open]);
+
+  useEffect(() => {
+    const shouldLockScroll = Boolean(
+      props.preventScroll ||
+      props.lockScroll ||
+      (props.modal && props.preventScroll !== false && props.lockScroll !== false)
+    );
+
+    if (isOpen) {
+      if (shouldLockScroll) {
+        lockBodyScroll();
+      }
+      startFloating();
+      updatePosition();
+
+      const handlePointerDown = (event: any) => {
+        const target = event.target;
+        if (
+          rootRef.current &&
+          !rootRef.current.contains(target) &&
+          popoverRef.current &&
+          !popoverRef.current.contains(target)
+        ) {
+          closePopover();
+        }
+      };
+
+      const handleKeyDown = (event: any) => {
+        if (event.key === "Escape") {
+          closePopover();
+        }
+      };
+
+      document.addEventListener("pointerdown", handlePointerDown, true);
+      document.addEventListener("keydown", handleKeyDown, true);
+
+      return () => {
+        if (shouldLockScroll) {
+          unlockBodyScroll();
+        }
+        stopFloating();
+        document.removeEventListener("pointerdown", handlePointerDown, true);
+        document.removeEventListener("keydown", handleKeyDown, true);
+      };
+    } else {
+      stopFloating();
+    }
+  }, [isOpen, props.dismissible, props.modal, props.preventScroll, props.lockScroll]);
+
+  useEffect(() => {
+    return () => {
+      stopFloating();
+      if (typeof document !== "undefined") {
+        document.removeEventListener(
+          "pointerdown",
+          (e: any) => handlePointerDown(e),
+          true
+        );
+        document.removeEventListener(
+          "keydown",
+          (e: any) => handleKeyDown(e),
+          true
+        );
+      }
+    };
+  }, []);
+
+  return (
+    <div
+      ref={rootRef}
+      className={`ttdk-popover-wrapper ${props.className || ""}`.trim()}
+      data-open={isOpen ? "true" : "false"}
+      data-disabled={props.disabled ? "true" : "false"}
+      data-block={props.block ? "true" : undefined}
+      style={{
+        ...buildUiVars(props.ui),
+        ...((props as any)["style"] || {}),
+              ...props.style,
+      }}
+    >
+      <div
+        role="button"
+        aria-haspopup="dialog"
+        ref={triggerRef}
+        className={`ttdk-popover-trigger ${props.triggerClass || ""}`.trim()}
+        tabIndex={props.disabled ? -1 : 0}
+        aria-expanded={isOpen}
+        aria-disabled={props.disabled}
+        data-open={isOpen ? "true" : "false"}
+        data-disabled={props.disabled ? "true" : "false"}
+        style={{
+          ...buildUiVars(props.triggerStyle),
+        }}
+        onClick={(event) => handleTriggerClick()}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            handleTriggerClick();
+          }
+        }}
+      >
+        {props.children ? <>{props.children}</> : null}
+      </div>
+      {isOpen && props.modal ? (
+        <div
+          className={`ttdk-popover-overlay ${props.overlayClass || ""}`.trim()}
+          style={{
+            ...buildUiVars(props.overlayStyle),
+          }}
+          onClick={(event) => handleOverlayClick()}
+        />
+      ) : null}
+      {isOpen ? (
+        <div
+          role="dialog"
+          ref={popoverRef}
+          className={`ttdk-popover-content ${props.contentClass || ""}`.trim()}
+          aria-modal={props.modal ? "true" : "false"}
+          tabIndex={-1}
+          style={{
+            ...buildUiVars(props.contentStyle),
+          }}
+        >
+          {props.arrow ? (
+            <div
+              ref={arrowRef}
+              className={`ttdk-popover-arrow ${props.arrowClass || ""}`.trim()}
+              style={{
+                ...buildUiVars(props.arrowStyle),
+              }}
+            />
+          ) : null}
+          {renderPanelContent()}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export default Popover;
+
+export { Popover };