pejay-ui 1.4.2 → 1.5.0

package/templates/notes/under-dev/overlay-close.ts

@@ -0,0 +1,50 @@
+import { notify } from "@/components/base/notify";
+import {
+  getActiveFormOverlay,
+  getActiveOverlayClose,
+  isUnsavedConfirmOpen,
+  setUnsavedConfirmOpen,
+} from "./form-overlay-registry";
+import { UNSAVED_CHANGES_NOTIFY } from "./unsaved-changes-notify";
+
+export { UNSAVED_CHANGES_NOTIFY } from "./unsaved-changes-notify";
+
+export function showUnsavedChangesNotify(onDiscard: () => void) {
+  setUnsavedConfirmOpen(true);
+
+  notify.default({
+    title: UNSAVED_CHANGES_NOTIFY.title,
+    description: UNSAVED_CHANGES_NOTIFY.description,
+    onDismiss: () => setUnsavedConfirmOpen(false),
+    defaultButton: {
+      ...UNSAVED_CHANGES_NOTIFY.defaultButton,
+      onClick: onDiscard,
+    },
+  });
+}
+
+export function requestOverlayCloseWithConfirm() {
+  if (isUnsavedConfirmOpen()) {
+    notify.dismiss();
+    return;
+  }
+
+  const form = getActiveFormOverlay();
+  if (form?.isCloseBlocked?.()) {
+    return;
+  }
+
+  const requestClose = getActiveOverlayClose();
+  const dirty = form?.isDirty?.() ?? false;
+
+  if (dirty && requestClose) {
+    showUnsavedChangesNotify(requestClose);
+    return;
+  }
+
+  requestClose?.();
+}
+
+export function dismissActiveNotify() {
+  notify.dismiss();
+}

package/templates/notes/under-dev/page-shortcut-registry.ts

@@ -0,0 +1,9 @@
+let newRecordHandler: (() => void) | null = null;
+
+export function setPageNewRecordHandler(handler: (() => void) | null) {
+  newRecordHandler = handler;
+}
+
+export function getPageNewRecordHandler() {
+  return newRecordHandler;
+}

package/templates/notes/under-dev/unsaved-changes-notify.ts

@@ -0,0 +1,11 @@
+/** Edit copy and default button options here for the dirty-form close prompt. */
+export const UNSAVED_CHANGES_NOTIFY = {
+  title: "You have unsaved changes",
+  description:
+    "Press Esc to keep editing, or discard changes to close without saving.",
+  defaultButton: {
+    label: "Discard changes",
+    autoFocus: true,
+    dismiss: true,
+  },
+};

package/templates/notes/under-dev/use-keyboard-shortcuts.tsx

@@ -0,0 +1,110 @@
+import { useCallback, useEffect, useRef } from "react";
+import { KeyboardShortcutsHelp } from "@/components/global/keyboard-shortcuts-help";
+import {
+  dismissActiveNotify,
+  requestOverlayCloseWithConfirm,
+} from "@/hooks/overlay-close";
+import {
+  getActiveFormOverlay,
+  isUnsavedConfirmOpen,
+} from "@/hooks/form-overlay-registry";
+import { getPageNewRecordHandler } from "@/hooks/page-shortcut-registry";
+import { isModKey, isTypingTarget } from "@/hooks/keyboard-utils";
+import type { Provider as Props } from "@/types";
+
+type OverlayContent = Props.OverlayContent;
+
+function navigateFormTab(direction: "prev" | "next") {
+  const tabs = getActiveFormOverlay()?.tabs;
+  if (!tabs || tabs.order.length === 0) return;
+
+  const currentIndex = tabs.order.indexOf(tabs.active);
+  if (currentIndex === -1) return;
+
+  const nextIndex =
+    direction === "next"
+      ? (currentIndex + 1) % tabs.order.length
+      : (currentIndex - 1 + tabs.order.length) % tabs.order.length;
+
+  tabs.setActive(tabs.order[nextIndex]!);
+}
+
+export function useKeyboardShortcuts(
+  isOverlayOpen: boolean,
+  openModal: (content: OverlayContent) => void,
+) {
+  const isOverlayOpenRef = useRef(isOverlayOpen);
+  isOverlayOpenRef.current = isOverlayOpen;
+
+  const openHelp = useCallback(() => {
+    openModal(({ close }) => <KeyboardShortcutsHelp close={close} />);
+  }, [openModal]);
+
+  const openHelpRef = useRef(openHelp);
+  openHelpRef.current = openHelp;
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const typing = isTypingTarget(event.target);
+      const mod = isModKey(event);
+
+      if (
+        event.key === "?" &&
+        event.shiftKey &&
+        !event.ctrlKey &&
+        !event.metaKey &&
+        !event.altKey
+      ) {
+        if (typing) return;
+        event.preventDefault();
+        openHelpRef.current();
+        return;
+      }
+
+      if (isOverlayOpenRef.current) {
+        if (event.key === "Escape") {
+          event.preventDefault();
+
+          if (isUnsavedConfirmOpen()) {
+            dismissActiveNotify();
+            return;
+          }
+
+          requestOverlayCloseWithConfirm();
+          return;
+        }
+
+        if (mod && event.key === "Enter") {
+          event.preventDefault();
+          getActiveFormOverlay()?.onSubmit?.();
+          return;
+        }
+
+        if (event.altKey && event.key === "ArrowLeft") {
+          if (typing) return;
+          event.preventDefault();
+          navigateFormTab("prev");
+          return;
+        }
+
+        if (event.altKey && event.key === "ArrowRight") {
+          if (typing) return;
+          event.preventDefault();
+          navigateFormTab("next");
+          return;
+        }
+
+        return;
+      }
+
+      if (mod && event.altKey && event.key.toLowerCase() === "n") {
+        if (typing) return;
+        event.preventDefault();
+        getPageNewRecordHandler()?.();
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, []);
+}

package/templates/notes/under-dev/useFormDirty.ts

@@ -0,0 +1,6 @@
+import { useRef } from "react";
+
+export function useFormDirty<T>(values: T): boolean {
+  const initialRef = useRef(values);
+  return JSON.stringify(values) !== JSON.stringify(initialRef.current);
+}

package/templates/notes/under-dev/useFormOverlayRegistration.ts

@@ -0,0 +1,47 @@
+import { useEffect } from "react";
+import {
+  registerActiveFormOverlay,
+  type FormOverlayRegistration,
+  type FormTabsConfig,
+} from "./form-overlay-registry";
+
+type UseFormOverlayRegistrationArgs = {
+  enabled?: boolean;
+  onSubmit?: () => void;
+  isDirty?: boolean;
+  closeDisabled?: boolean;
+  formTabs?: FormTabsConfig;
+};
+
+export function useFormOverlayRegistration({
+  enabled = true,
+  onSubmit,
+  isDirty = false,
+  closeDisabled = false,
+  formTabs,
+}: UseFormOverlayRegistrationArgs) {
+  useEffect(() => {
+    if (!enabled) {
+      registerActiveFormOverlay(null);
+      return;
+    }
+
+    const registration: FormOverlayRegistration = {
+      onSubmit,
+      isDirty: () => isDirty,
+      isCloseBlocked: () => closeDisabled,
+      tabs: formTabs,
+    };
+
+    registerActiveFormOverlay(registration);
+    return () => registerActiveFormOverlay(null);
+  }, [
+    enabled,
+    onSubmit,
+    isDirty,
+    closeDisabled,
+    formTabs?.active,
+    formTabs?.order.join(","),
+    formTabs?.setActive,
+  ]);
+}

package/templates/notes/under-dev/useFormPanel.tsx

@@ -0,0 +1,18 @@
+import { useCallback, type ComponentType } from "react";
+import { useOverlay } from "./useOverlay";
+
+export function useFormPanel() {
+  const { openSidePanel } = useOverlay();
+
+  return useCallback(
+    <P extends { close: () => void }>(
+      Component: ComponentType<P>,
+      props: Omit<P, "close">,
+    ) => {
+      openSidePanel(({ close }) => (
+        <Component {...({ ...props, close } as P)} />
+      ));
+    },
+    [openSidePanel],
+  );
+}

package/templates/notes/under-dev/useFormTabHandler.ts

@@ -0,0 +1,22 @@
+import { useCallback, type Dispatch, type SetStateAction } from "react";
+import type { FormTabsConfig } from "./form-overlay-registry";
+
+export function useFormTabHandler<T extends string>(
+  setActive: Dispatch<SetStateAction<T>>,
+) {
+  return useCallback((tab: T) => {
+    setActive(tab);
+  }, [setActive]);
+}
+
+export function toFormTabsConfig<T extends string>(
+  active: T,
+  handleTabChange: (tab: T) => void,
+  order: T[],
+): FormTabsConfig {
+  return {
+    active,
+    setActive: (id) => handleTabChange(id as T),
+    order,
+  };
+}

package/templates/notes/under-dev/useHorizontalWheelScroll.ts

@@ -0,0 +1,27 @@
+import { useEffect, useRef } from "react";
+
+export function useHorizontalWheelScroll<T extends HTMLElement>() {
+  const ref = useRef<T>(null);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+
+    const onWheel = (event: WheelEvent) => {
+      const maxScrollLeft = element.scrollWidth - element.clientWidth;
+      if (maxScrollLeft <= 0) return;
+
+      // Preserve native horizontal trackpad / shift+wheel gestures.
+      if (Math.abs(event.deltaX) > Math.abs(event.deltaY)) return;
+
+      event.preventDefault();
+      event.stopPropagation();
+      element.scrollLeft += event.deltaY;
+    };
+
+    element.addEventListener("wheel", onWheel, { passive: false, capture: true });
+    return () => element.removeEventListener("wheel", onWheel, { capture: true });
+  }, []);
+
+  return ref;
+};

package/templates/notes/under-dev/useOverlay.ts

@@ -0,0 +1,41 @@
+import { useCallback } from "react";
+import { useAppProvider } from "@/provider/app-context";
+import { APP_PROVIDER_TYPE } from "@/utils";
+import type { Provider } from "@/types";
+
+type OverlayContent = Provider.OverlayContent;
+type OverlayOptions = Provider.OverlayOptions;
+
+export function useOverlay() {
+  const { open, isOverlayOpen, stackDepth } = useAppProvider();
+
+  const openSidePanel = useCallback(
+    (content: OverlayContent, options?: OverlayOptions) => {
+      open(APP_PROVIDER_TYPE.SIDE_PANEL, content, {
+        onSide: "right",
+        ...options,
+      });
+    },
+    [open],
+  );
+
+  const openModal = useCallback(
+    (content: OverlayContent, options?: OverlayOptions) => {
+      open(APP_PROVIDER_TYPE.MODAL, content, options);
+    },
+    [open],
+  );
+
+  return { openSidePanel, openModal, isOverlayOpen, stackDepth };
+}
+
+/** @deprecated Prefer `useOverlay` */
+export function useSidePanel() {
+  return useOverlay();
+}
+
+/** @deprecated Prefer `useOverlay` */
+export function useModal() {
+  const { openModal, isOverlayOpen, stackDepth } = useOverlay();
+  return { openModal, isOverlayOpen, stackDepth };
+}

package/templates/overlays/index.ts

@@ -1 +1,2 @@
-export * from "./portal";
+export * from "./portal/portal";
+export * from "./tooltip/tooltip";

package/templates/overlays/portal/portal.tsx

@@ -0,0 +1,26 @@
+import { createPortal } from "react-dom";
+import { useEffect, useState, type ReactNode } from "react";
+
+interface PortalProps {
+  children: ReactNode;
+}
+export function Portal({ children }: PortalProps) {
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    const div = document.createElement("div");
+    div.id = "dynamic-portal";
+    document.body.appendChild(div);
+    setContainer(div);
+
+    return () => {
+      if (div.parentNode) {
+        document.body.removeChild(div);
+      }
+    };
+  }, []);
+
+  if (!container) return null;
+
+  return createPortal(children, container);
+}

package/templates/overlays/tooltip/readme.tooltip.md

@@ -0,0 +1,26 @@
+# Tooltip Overlay Component
+
+A standalone utility wrapper to show visual popover info bubbles when hovering over any child element.
+
+---
+
+## Usage
+
+```tsx
+import { Tooltip } from "@/pejay-ui/components/overlays/tooltip";
+
+<Tooltip content="Upload CSV data file" placement="bottom">
+  <button className="p-2 border rounded">Upload</button>
+</Tooltip>
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `children` | `ReactNode` | — | The target element that triggers the tooltip on hover. |
+| `content` | `string` | — | Text inside the tooltip bubble. |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Tooltip popover alignment relative to the trigger. |
+| `className` | `string` | — | Additional CSS classes for custom visual overrides. |

package/templates/{button → overlays/tooltip}/tooltip.tsx

@@ -13,7 +13,7 @@ import {
   FloatingPortal,
   type Placement,
 } from "@floating-ui/react";
-import { cn } from "@/utils/cn";
+import { cn } from "@/pejay-ui/utils/cn";
 
 interface TooltipProps {
   children: React.ReactNode | string;

package/templates/panels/COMPONENTS.md

@@ -0,0 +1,103 @@
+# Panel Component Cards Reference
+
+There are **4 card types** available depending on how much control you need over the overlay's layout.
+
+---
+
+## Form Cards (Recommended for most use cases)
+
+These cards include a built-in title row, X button, footer slot, and full keyboard shortcut support (`Ctrl+Enter` to submit, `Escape` to close with dirty guard, tab navigation via `Alt+Arrow`).
+
+### `SidePanelCard`
+A full-height side panel that slides in from the right (or left). Use for **create / edit forms**.
+
+```tsx
+import { SidePanelCard } from "@/pejay-ui/panels";
+
+<SidePanelCard
+  title="Add Vendor"
+  close={close}
+  onSubmit={handleSave}
+  isDirty={isDirty}
+  size="md"           // "sm" | "md" | "lg" | "xl"
+  footer={<SaveCancelButtons />}
+  headerSlot={<TabsRow />}
+>
+  {/* your form fields */}
+</SidePanelCard>
+```
+
+### `ModalCard`
+A centered modal dialog. Same feature set as `SidePanelCard`. Use for **confirmations, quick edits, or view dialogs**.
+
+```tsx
+import { ModalCard } from "@/pejay-ui/panels";
+
+<ModalCard
+  title="Edit Vendor"
+  description="Update the vendor's details."
+  close={close}
+  onSubmit={handleSave}
+  isDirty={isDirty}
+  size="md"           // "sm" | "md" | "lg" | "xl"
+  footer={<SaveCancelButtons />}
+>
+  {/* your form fields */}
+</ModalCard>
+```
+
+| Prop | Type | Description |
+|:---|:---|:---|
+| `title` | `string` | Heading shown at the top |
+| `description` | `string` | Subtitle below the title |
+| `close` | `() => void` | Injected by the hook — always pass through |
+| `onSubmit` | `() => void` | Enables `Ctrl+Enter` shortcut |
+| `isDirty` | `boolean` | When `true`, blocks close with unsaved-changes guard |
+| `closeDisabled` | `boolean` | Disables X and Escape (use during async saves) |
+| `footer` | `ReactNode` | Bottom bar — typically Cancel + Save buttons |
+| `headerSlot` | `ReactNode` | Renders below title (e.g. tab switcher row) |
+| `size` | `"sm"\|"md"\|"lg"\|"xl"` | Controls width preset |
+| `formTabs` | `FormTabsConfig` | Enables `Alt+Arrow` tab switching |
+
+---
+
+## Raw Wrappers (For fully custom layouts)
+
+These wrappers render **only** a container with `p-2` padding. No title, no X button, no footer. Your content receives a `{ close }` callback and is fully responsible for triggering its own close action.
+
+Use raw wrappers when you need to build a completely custom overlay layout that doesn't fit the standard form card structure.
+
+### `SidePanelRaw`
+Opened via `openRawSidePanel` from `useOverlay`.
+
+```tsx
+import { useOverlay } from "@/pejay-ui/panels";
+
+const { openRawSidePanel } = useOverlay();
+
+openRawSidePanel(({ close }) => (
+  <div>
+    <p>Fully custom side panel content.</p>
+    <button onClick={close}>Dismiss</button>
+  </div>
+));
+```
+
+### `ModalRaw`
+Opened via `openRawModal` from `useOverlay`.
+
+```tsx
+import { useOverlay } from "@/pejay-ui/panels";
+
+const { openRawModal } = useOverlay();
+
+openRawModal(({ close }) => (
+  <div>
+    <p>Fully custom modal content.</p>
+    <button onClick={close}>Dismiss</button>
+  </div>
+));
+```
+
+> [!TIP]
+> Raw wrappers still benefit from the global `PanelProvider` stack — they support overlay stacking and the `Escape` key still closes them.