pejay-ui 1.4.3 → 1.5.0

package/templates/panels/core/PanelProvider.tsx

@@ -0,0 +1,145 @@
+import { useCallback, useMemo, useState, type ReactNode } from "react";
+import {
+  PanelOverlayStateContext,
+  PanelOverlayActionsContext,
+} from "./panel-context";
+import { APP_PROVIDER_TYPE } from "./constants";
+import { useHotkey } from "@/pejay-ui/hotkeys";
+import { requestOverlayCloseWithConfirm } from "./overlay-close";
+import type { OverlayStackItem, OverlayContent, OverlayOptions } from "./types";
+import { Modal } from "../components/modal/modal";
+import {
+  SidePanel,
+  SidePanelContent,
+} from "../components/side-panel/side-panel";
+import { ModalRaw } from "../components/modal/modal-raw";
+import { SidePanelRaw } from "../components/side-panel/side-panel-raw";
+
+export interface PanelProviderProps {
+  children: ReactNode;
+}
+
+export const PanelProvider = ({ children }: PanelProviderProps) => {
+  const [stack, setStack] = useState<OverlayStackItem[]>([]);
+
+  const open = useCallback(
+    (type: string, content?: OverlayContent, options?: OverlayOptions) => {
+      const id = crypto.randomUUID();
+      setStack((prev) => [...prev, { id, type, content, options }]);
+    },
+    [],
+  );
+
+  const close = useCallback((id: string) => {
+    setStack((prev) => prev.filter((item) => item.id !== id));
+  }, []);
+
+  const isOverlayOpen = stack.length > 0;
+  const stackDepth = stack.length;
+
+  useHotkey(
+    "escape",
+    () => {
+      requestOverlayCloseWithConfirm();
+    },
+    {
+      category: "Overlays",
+      description: "Close topmost active modal or side panel",
+      disabled: !isOverlayOpen,
+      enabledInInputs: true,
+    },
+  );
+
+  const stateValue = useMemo(
+    () => ({ stack, isOverlayOpen, stackDepth }),
+    [stack, isOverlayOpen, stackDepth],
+  );
+
+  const actionsValue = useMemo(
+    () => ({ open, close }),
+    [open, close],
+  );
+
+  const topOverlayId = stack.at(-1)?.id;
+
+  return (
+    <PanelOverlayStateContext.Provider value={stateValue}>
+      <PanelOverlayActionsContext.Provider value={actionsValue}>
+        {children}
+
+        {stack.map((item, index) => {
+          const isActive = item.id === topOverlayId;
+          const layer = index + 1;
+          const onClose = () => close(item.id);
+          const closeId = () => close(item.id);
+
+          /* ── Form Side Panel ── */
+          if (item.type === APP_PROVIDER_TYPE.SIDE_PANEL) {
+            return (
+              <SidePanel
+                key={item.id}
+                options={item.options || {}}
+                isActive={isActive}
+                layer={layer}
+                onClose={onClose}
+              >
+                <SidePanelContent content={item.content} />
+              </SidePanel>
+            );
+          }
+
+          /* ── Form Modal ── */
+          if (item.type === APP_PROVIDER_TYPE.MODAL) {
+            return (
+              <Modal
+                key={item.id}
+                options={item.options || {}}
+                isActive={isActive}
+                layer={layer}
+                onClose={onClose}
+              >
+                {item.content?.({ close: closeId })}
+              </Modal>
+            );
+          }
+
+          /* ── Raw Side Panel (no chrome) ── */
+          if (item.type === APP_PROVIDER_TYPE.SIDE_PANEL_RAW) {
+            return (
+              <SidePanel
+                key={item.id}
+                options={item.options || {}}
+                isActive={isActive}
+                layer={layer}
+                onClose={onClose}
+              >
+                <SidePanelRaw>
+                  {item.content?.({ close: closeId })}
+                </SidePanelRaw>
+              </SidePanel>
+            );
+          }
+
+          /* ── Raw Modal (no chrome) ── */
+          if (item.type === APP_PROVIDER_TYPE.MODAL_RAW) {
+            return (
+              <Modal
+                key={item.id}
+                options={item.options || {}}
+                isActive={isActive}
+                layer={layer}
+                onClose={onClose}
+              >
+                <ModalRaw>
+                  {item.content?.({ close: closeId })}
+                </ModalRaw>
+              </Modal>
+            );
+          }
+
+          return null;
+        })}
+      </PanelOverlayActionsContext.Provider>
+    </PanelOverlayStateContext.Provider>
+  );
+};

package/templates/panels/core/constants.ts

@@ -0,0 +1,9 @@
+export const APP_PROVIDER_TYPE = {
+  MODAL: "modal",
+  SIDE_PANEL: "side-panel",
+  MODAL_RAW: "modal-raw",
+  SIDE_PANEL_RAW: "side-panel-raw",
+} as const;
+
+export const getOverlayBackdropZ = (layer: number) => 1000 + layer * 10;
+export const getOverlayContentZ = (layer: number) => 1000 + layer * 10 + 1;

package/templates/panels/core/form-overlay-registry.ts

@@ -0,0 +1,35 @@
+import type { FormOverlayRegistration } from "./types";
+
+let closeStack: (() => void)[] = [];
+let formStack: FormOverlayRegistration[] = [];
+
+export function registerActiveOverlayClose(handler: () => void) {
+  closeStack.push(handler);
+}
+
+export function unregisterActiveOverlayClose(handler: (() => void) | null) {
+  if (!handler) return;
+  closeStack = closeStack.filter((h) => h !== handler);
+}
+
+export function getActiveOverlayClose() {
+  return closeStack[closeStack.length - 1] || null;
+}
+
+export function registerActiveFormOverlay(
+  registration: FormOverlayRegistration | null,
+) {
+  if (!registration) return;
+  formStack.push(registration);
+}
+
+export function unregisterActiveFormOverlay(
+  registration: FormOverlayRegistration | null,
+) {
+  if (!registration) return;
+  formStack = formStack.filter((item) => item !== registration);
+}
+
+export function getActiveFormOverlay() {
+  return formStack[formStack.length - 1] || null;
+}

package/templates/panels/core/index.ts

@@ -0,0 +1,6 @@
+export * from "./PanelProvider";
+export * from "./panel-context";
+export * from "./types";
+export * from "./constants";
+export * from "./form-overlay-registry";
+export * from "./overlay-close";

package/templates/panels/core/overlay-close.ts

@@ -0,0 +1,11 @@
+import { getActiveFormOverlay, getActiveOverlayClose } from "./form-overlay-registry";
+
+export function requestOverlayCloseWithConfirm() {
+  const form = getActiveFormOverlay();
+  if (form?.isCloseBlocked?.()) {
+    return;
+  }
+
+  const requestClose = getActiveOverlayClose();
+  requestClose?.();
+}

package/templates/panels/core/panel-context.ts

@@ -0,0 +1,41 @@
+import { createContext, useContext } from "react";
+import type { OverlayStackItem, OverlayContent, OverlayOptions } from "./types";
+
+export interface PanelOverlayStateProps {
+  stack: OverlayStackItem[];
+  isOverlayOpen: boolean;
+  stackDepth: number;
+}
+
+export interface PanelOverlayActionsProps {
+  open: (
+    type: string,
+    content?: OverlayContent,
+    options?: OverlayOptions,
+  ) => void;
+  close: (id: string) => void;
+}
+
+export const PanelOverlayStateContext = createContext<
+  PanelOverlayStateProps | undefined
+>(undefined);
+
+export const PanelOverlayActionsContext = createContext<
+  PanelOverlayActionsProps | undefined
+>(undefined);
+
+export function usePanelOverlayState() {
+  const context = useContext(PanelOverlayStateContext);
+  if (context === undefined) {
+    throw new Error("usePanelOverlayState must be used within PanelProvider");
+  }
+  return context;
+}
+
+export function usePanelOverlayActions() {
+  const context = useContext(PanelOverlayActionsContext);
+  if (context === undefined) {
+    throw new Error("usePanelOverlayActions must be used within PanelProvider");
+  }
+  return context;
+}

package/templates/panels/core/types.ts

@@ -0,0 +1,41 @@
+import type { ReactNode } from "react";
+
+export type OverlayContent = (helpers: { close: () => void }) => ReactNode;
+
+export interface OverlayOptions {
+  onSide?: "left" | "right";
+  width?: string;
+  [key: string]: any;
+}
+
+export interface OverlayStackItem {
+  id: string;
+  type: string;
+  content?: OverlayContent;
+  options?: OverlayOptions;
+}
+
+export interface AppContextProps {
+  open: (type: string, content?: OverlayContent, options?: OverlayOptions) => void;
+  close: (id: string) => void;
+  stack: OverlayStackItem[];
+  isOverlayOpen: boolean;
+  stackDepth: number;
+}
+
+export interface ProviderProps {
+  children: ReactNode;
+}
+
+export type FormTabsConfig = {
+  active: string;
+  setActive: (id: string) => void;
+  order: string[];
+};
+
+export type FormOverlayRegistration = {
+  onSubmit?: () => void;
+  isDirty?: () => boolean;
+  isCloseBlocked?: () => boolean;
+  tabs?: FormTabsConfig;
+};

package/templates/panels/hooks/index.ts

@@ -0,0 +1,7 @@
+export * from "./useOverlay";
+export * from "./useFormPanel";
+export * from "./useModalForm";
+export * from "./useFormOverlayRegistration";
+export * from "./useFormDirty";
+export * from "./useFormTabHandler";
+export * from "./useHorizontalWheelScroll";

package/templates/panels/hooks/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/panels/hooks/useFormOverlayRegistration.ts

@@ -0,0 +1,92 @@
+import { useEffect } from "react";
+import { useHotkey } from "@/pejay-ui/hotkeys";
+import {
+  registerActiveFormOverlay,
+  unregisterActiveFormOverlay,
+} from "../core/form-overlay-registry";
+import type { FormOverlayRegistration, FormTabsConfig } from "../core/types";
+
+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) return;
+
+    const registration: FormOverlayRegistration = {
+      onSubmit,
+      isDirty: () => isDirty,
+      isCloseBlocked: () => closeDisabled,
+      tabs: formTabs,
+    };
+
+    registerActiveFormOverlay(registration);
+    return () => unregisterActiveFormOverlay(registration);
+  }, [
+    enabled,
+    onSubmit,
+    isDirty,
+    closeDisabled,
+    formTabs?.active,
+    formTabs?.order.join(","),
+    formTabs?.setActive,
+  ]);
+
+  // Dynamically register submitting key combo
+  useHotkey(
+    "ctrl+enter",
+    () => {
+      onSubmit?.();
+    },
+    {
+      category: "Form Actions",
+      description: "Submit and save current form",
+      disabled: !enabled || !onSubmit || closeDisabled,
+    },
+  );
+
+  const hasTabs = Boolean(formTabs && formTabs.order.length > 0);
+
+  // Dynamically register tab switching combos
+  useHotkey(
+    "alt+arrowleft",
+    () => {
+      if (!formTabs) return;
+      const currentIndex = formTabs.order.indexOf(formTabs.active);
+      const prevIndex =
+        (currentIndex - 1 + formTabs.order.length) % formTabs.order.length;
+      formTabs.setActive(formTabs.order[prevIndex]!);
+    },
+    {
+      category: "Form Navigation",
+      description: "Switch to previous form tab",
+      disabled: !enabled || !hasTabs || closeDisabled,
+    },
+  );
+
+  useHotkey(
+    "alt+arrowright",
+    () => {
+      if (!formTabs) return;
+      const currentIndex = formTabs.order.indexOf(formTabs.active);
+      const nextIndex = (currentIndex + 1) % formTabs.order.length;
+      formTabs.setActive(formTabs.order[nextIndex]!);
+    },
+    {
+      category: "Form Navigation",
+      description: "Switch to next form tab",
+      disabled: !enabled || !hasTabs || closeDisabled,
+    },
+  );
+}

package/templates/panels/hooks/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/panels/hooks/useFormTabHandler.ts

@@ -0,0 +1,25 @@
+import { useCallback, type Dispatch, type SetStateAction } from "react";
+import type { FormTabsConfig } from "../core/types";
+
+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/panels/hooks/useHorizontalWheelScroll.ts

@@ -0,0 +1,31 @@
+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/panels/hooks/useModalForm.tsx

@@ -0,0 +1,22 @@
+import { useCallback, type ComponentType } from "react";
+import { useOverlay } from "./useOverlay";
+
+/**
+ * Like `useFormPanel` but opens the component inside a centered MODAL
+ * instead of a side panel. Injects `close` automatically.
+ */
+export function useModalForm() {
+  const { openModal } = useOverlay();
+
+  return useCallback(
+    <P extends { close: () => void }>(
+      Component: ComponentType<P>,
+      props: Omit<P, "close">,
+    ) => {
+      openModal(({ close }) => (
+        <Component {...({ ...props, close } as P)} />
+      ));
+    },
+    [openModal],
+  );
+}

package/templates/panels/hooks/useOverlay.ts

@@ -0,0 +1,65 @@
+import { useCallback } from "react";
+import {
+  usePanelOverlayActions,
+  usePanelOverlayState,
+} from "../core/panel-context";
+import { APP_PROVIDER_TYPE } from "../core/constants";
+import type { OverlayContent, OverlayOptions } from "../core/types";
+
+export function useOverlay() {
+  const { open } = usePanelOverlayActions();
+  const { isOverlayOpen, stackDepth } = usePanelOverlayState();
+
+  /** Open a form side panel (with title, X, footer, keyboard shortcuts). */
+  const openSidePanel = useCallback(
+    (content: OverlayContent, options?: OverlayOptions) => {
+      open(APP_PROVIDER_TYPE.SIDE_PANEL, content, {
+        onSide: "right",
+        ...options,
+      });
+    },
+    [open],
+  );
+
+  /** Open a form modal (with title, X, footer, keyboard shortcuts). */
+  const openModal = useCallback(
+    (content: OverlayContent, options?: OverlayOptions) => {
+      open(APP_PROVIDER_TYPE.MODAL, content, options);
+    },
+    [open],
+  );
+
+  /**
+   * Open a raw side panel with no chrome (no title, X button, or footer).
+   * Your content receives `{ close }` and is responsible for its own close trigger.
+   */
+  const openRawSidePanel = useCallback(
+    (content: OverlayContent, options?: OverlayOptions) => {
+      open(APP_PROVIDER_TYPE.SIDE_PANEL_RAW, content, {
+        onSide: "right",
+        ...options,
+      });
+    },
+    [open],
+  );
+
+  /**
+   * Open a raw modal with no chrome (no title, X button, or footer).
+   * Your content receives `{ close }` and is responsible for its own close trigger.
+   */
+  const openRawModal = useCallback(
+    (content: OverlayContent, options?: OverlayOptions) => {
+      open(APP_PROVIDER_TYPE.MODAL_RAW, content, options);
+    },
+    [open],
+  );
+
+  return {
+    openSidePanel,
+    openModal,
+    openRawSidePanel,
+    openRawModal,
+    isOverlayOpen,
+    stackDepth,
+  };
+}

package/templates/panels/index.ts

@@ -0,0 +1,3 @@
+export * from "./core";
+export * from "./hooks";
+export * from "./components";

package/templates/panels/vendor-example/by-using-modal/VendorModalPage.tsx

@@ -0,0 +1,47 @@
+import { useVendorModalForm } from "./useVendorModalForm";
+import type { Vendor } from "./vendor-types";
+
+export default function VendorModalPage() {
+  const openVendorModal = useVendorModalForm();
+
+  const handleCreate = () => {
+    openVendorModal("create");
+  };
+
+  const handleEdit = (vendor: Vendor) => {
+    openVendorModal("update", vendor);
+  };
+
+  return (
+    <div className="p-6 max-w-xl mx-auto space-y-4">
+      <h1 className="text-xl font-bold text-slate-800">Vendors (Modal Demo)</h1>
+      <p className="text-sm text-slate-500">
+        Same Vendor form, same domain hook pattern — but opens in a centered modal instead of a side panel.
+      </p>
+
+      <div className="flex gap-4">
+        <button
+          onClick={handleCreate}
+          className="px-4 py-2 bg-violet-600 hover:bg-violet-700 text-white rounded text-sm transition-colors cursor-pointer"
+        >
+          Add Vendor (Modal)
+        </button>
+
+        <button
+          onClick={() =>
+            handleEdit({
+              id: "V-001",
+              name: "Acme Supplies",
+              email: "acme@mail.com",
+              phone: "555-0100",
+              status: "active",
+            })
+          }
+          className="px-4 py-2 border border-slate-200 rounded text-sm hover:bg-slate-50 transition-colors cursor-pointer"
+        >
+          Edit Acme (Modal)
+        </button>
+      </div>
+    </div>
+  );
+}

package/templates/panels/vendor-example/by-using-modal/useVendorModalForm.tsx

@@ -0,0 +1,19 @@
+import { useCallback } from "react";
+import { useModalForm } from "../../hooks/useModalForm";
+import { VendorModalForm, type VendorFormMode } from "./vendor-modal-form";
+import type { Vendor } from "./vendor-types";
+
+/**
+ * Domain hook for opening the Vendor form inside a centered MODAL.
+ * Uses useModalForm which automatically injects the `close` callback.
+ */
+export function useVendorModalForm() {
+  const openForm = useModalForm();
+
+  return useCallback(
+    (mode: VendorFormMode = "create", vendor?: Vendor) => {
+      openForm(VendorModalForm, { mode, vendor });
+    },
+    [openForm],
+  );
+}