pejay-ui 1.4.3 → 1.5.0

package/templates/notes/under-dev/card/base-card.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+import { Flex } from "../layout";
+import { cn } from "@/utils";
+
+interface BaseCardProps {
+  children?: ReactNode;
+  /** Override padding. Defaults to "p-2.5" */
+  padding?: string;
+  /** Override border radius. Defaults to "rounded-md" */
+  rounded?: string;
+  /** CSS height value e.g. "200px" | "50vh". min-h-0 is always applied. */
+  height?: string;
+  /** Override width. Defaults to "w-full" */
+  width?: string;
+  className?: string;
+}
+
+export function BaseCard({
+  children,
+  padding = "p-2.5",
+  rounded = "rounded-md",
+  height,
+  width = "w-full",
+  className,
+}: BaseCardProps) {
+  return (
+    <Flex
+      direction="row"
+      className={cn("min-h-0", rounded, width, padding, className)}
+      style={height ? { height } : undefined}
+    >
+      {children}
+    </Flex>
+  );
+}

package/templates/notes/under-dev/card/index.ts

@@ -0,0 +1,4 @@
+export * from "./base-card";
+export * from "./base-card";
+export * from "./modal-card";
+export * from "./side-panel-card";

package/templates/notes/under-dev/card/modal-card.tsx

@@ -0,0 +1,88 @@
+import { X } from "lucide-react";
+import type { ReactNode } from "react";
+import { cn } from "@/utils";
+
+interface ModalCardProps {
+  children: ReactNode;
+  className?: string;
+  title?: string;
+  description?: string;
+  footer?: ReactNode;
+  close?: () => void;
+  width?: string;
+  maxHeight?: string;
+  /** Renders below title row (e.g. tabs). */
+  headerSlot?: ReactNode;
+  bodyClassName?: string;
+}
+
+export function ModalCard({
+  children,
+  title,
+  description,
+  footer,
+  className,
+  close,
+  width = "min(560px, 92vw)",
+  maxHeight = "min(90vh, 720px)",
+  headerSlot,
+  bodyClassName,
+}: ModalCardProps) {
+  return (
+    <div
+      className={cn(
+        "flex flex-col overflow-hidden rounded-xl bg-white shadow-2xl",
+        className,
+      )}
+      style={{ width, maxHeight }}
+      onClick={(e) => e.stopPropagation()}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby={title ? "modal-title" : undefined}
+    >
+      <div className="shrink-0 border-b border-slate-200 px-6 pt-5 pb-0">
+        <div className="flex items-start justify-between gap-3 pb-4">
+          <div className="min-w-0">
+            {title && (
+              <h2
+                id="modal-title"
+                className="text-lg font-bold tracking-tight text-slate-900"
+              >
+                {title}
+              </h2>
+            )}
+            {description && (
+              <p className="mt-0.5 text-sm text-slate-500">{description}</p>
+            )}
+          </div>
+          {close && (
+            <button
+              type="button"
+              onClick={close}
+              className="shrink-0 rounded-full p-2 text-slate-400 transition-colors hover:bg-slate-100 hover:text-slate-600"
+              aria-label="Close"
+            >
+              <X className="h-4 w-4" strokeWidth={2} />
+            </button>
+          )}
+        </div>
+        {headerSlot}
+      </div>
+
+      <div
+        className={cn(
+          "min-h-0 flex-1 overflow-y-auto px-6 py-5",
+          bodyClassName,
+        )}
+      >
+        {children}
+      </div>
+
+      {footer && (
+        <div className="shrink-0 border-t border-slate-200 bg-white px-6 py-4">
+          {footer}
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/notes/under-dev/card/side-panel-card.tsx

@@ -0,0 +1,127 @@
+import { X } from "lucide-react";
+import type { ReactNode } from "react";
+import { Flex } from "../layout";
+import { cn } from "@/utils";
+import type { FormTabsConfig } from "@/hooks/form-overlay-registry";
+import { requestOverlayCloseWithConfirm } from "@/hooks/overlay-close";
+import { useFormOverlayRegistration } from "@/hooks/useFormOverlayRegistration";
+
+export type SidePanelSize = "sm" | "md" | "lg" | "xl";
+
+const PANEL_WIDTH: Record<SidePanelSize, string> = {
+  sm: "min(480px, 100vw)",
+  md: "min(560px, 100vw)",
+  lg: "min(720px, 92vw)",
+  xl: "min(840px, 95vw)",
+};
+
+interface SidePanelCardProps {
+  children: ReactNode;
+  title?: string;
+  description?: string;
+  className?: string;
+  close?: () => void;
+  footer?: ReactNode;
+  /** Preset widths — use `width` to override entirely. */
+  size?: SidePanelSize;
+  /** Custom CSS width; overrides `size`. */
+  width?: string;
+  /** Renders below title row (e.g. tabs). */
+  headerSlot?: ReactNode;
+  bodyClassName?: string;
+  onSubmit?: () => void;
+  isDirty?: boolean;
+  /** Blocks close via X, Escape, and backdrop while an async action is in progress. */
+  closeDisabled?: boolean;
+  formTabs?: FormTabsConfig;
+}
+
+export function SidePanelCard({
+  children,
+  title,
+  description,
+  className,
+  close,
+  footer,
+  size = "sm",
+  width,
+  headerSlot,
+  bodyClassName,
+  onSubmit,
+  isDirty = false,
+  closeDisabled = false,
+  formTabs,
+}: SidePanelCardProps) {
+  const panelWidth = width ?? PANEL_WIDTH[size];
+
+  useFormOverlayRegistration({
+    enabled: Boolean(close),
+    onSubmit,
+    isDirty,
+    closeDisabled,
+    formTabs,
+  });
+
+  const handleClose = () => {
+    if (closeDisabled) return;
+    requestOverlayCloseWithConfirm();
+  };
+
+  return (
+    <Flex
+      direction="column"
+      items="stretch"
+      noGap
+      className={cn(
+        "h-screen max-w-full overflow-hidden border-l border-slate-200 bg-white shadow-2xl",
+        className,
+      )}
+      style={{ width: panelWidth }}
+    >
+      <div className="w-full shrink-0 border-b border-slate-200 px-6 pt-4 pb-0">
+        <Flex direction="row" items="center" justify="between" className="pb-4">
+          <Flex direction="column" className="min-w-0 gap-0.5">
+            {title && (
+              <h2 className="text-lg font-bold tracking-tight text-slate-900">
+                {title}
+              </h2>
+            )}
+            {description && (
+              <p className="text-sm text-slate-500">{description}</p>
+            )}
+          </Flex>
+          <button
+            type="button"
+            onClick={handleClose}
+            disabled={closeDisabled}
+            className={cn(
+              "shrink-0 rounded-full p-2 text-slate-600 transition-colors",
+              closeDisabled
+                ? "cursor-not-allowed opacity-40"
+                : "cursor-pointer hover:bg-slate-100 hover:text-slate-600",
+            )}
+            aria-label="Close panel"
+          >
+            <X className="h-4 w-4" strokeWidth={2} />
+          </button>
+        </Flex>
+        {headerSlot}
+      </div>
+
+      <div
+        className={cn(
+          "min-h-0 w-full flex-1 overflow-y-auto px-6 py-5",
+          bodyClassName,
+        )}
+      >
+        {children}
+      </div>
+
+      {footer && (
+        <div className="w-full shrink-0 border-t border-slate-200 bg-white px-6 py-4">
+          {footer}
+        </div>
+      )}
+    </Flex>
+  );
+}

package/templates/notes/under-dev/form-overlay-registry.ts

@@ -0,0 +1,42 @@
+export type FormTabsConfig = {
+  active: string;
+  setActive: (id: string) => void;
+  order: string[];
+};
+
+export type FormOverlayRegistration = {
+  onSubmit?: () => void;
+  isDirty?: () => boolean;
+  isCloseBlocked?: () => boolean;
+  tabs?: FormTabsConfig;
+};
+
+let activeRequestClose: (() => void) | null = null;
+let activeFormRegistration: FormOverlayRegistration | null = null;
+let unsavedConfirmOpen = false;
+
+export function setActiveOverlayClose(handler: (() => void) | null) {
+  activeRequestClose = handler;
+}
+
+export function registerActiveFormOverlay(
+  registration: FormOverlayRegistration | null,
+) {
+  activeFormRegistration = registration;
+}
+
+export function setUnsavedConfirmOpen(open: boolean) {
+  unsavedConfirmOpen = open;
+}
+
+export function isUnsavedConfirmOpen() {
+  return unsavedConfirmOpen;
+}
+
+export function getActiveOverlayClose() {
+  return activeRequestClose;
+}
+
+export function getActiveFormOverlay() {
+  return activeFormRegistration;
+}

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

@@ -0,0 +1,79 @@
+import { useEffect, useState } from "react";
+import { Btn, ModalCard } from "@/components/base";
+import { formatModKey } from "@/hooks/keyboard-utils";
+
+const MOD = formatModKey();
+
+const SHORTCUT_GROUPS = [
+  {
+    title: "Form (side panel / modal)",
+    items: [
+      { keys: `${MOD} + Enter`, action: "Submit form" },
+      { keys: "Alt + ← / →", action: "Previous / next form tab" },
+      { keys: "Esc", action: "Close form (confirm if unsaved)" },
+    ],
+  },
+  {
+    title: "List pages",
+    items: [
+      { keys: `${MOD} + Alt + N`, action: "New record / open add form" },
+    ],
+  },
+  {
+    title: "Global",
+    items: [
+      { keys: "Shift + ?", action: "Show this shortcut guide" },
+      { keys: `${MOD} + K`, action: "Focus search" },
+    ],
+  },
+];
+
+type KeyboardShortcutsHelpProps = {
+  close: () => void;
+};
+
+export function KeyboardShortcutsHelp({ close }: KeyboardShortcutsHelpProps) {
+  return (
+    <ModalCard
+      close={close}
+      title="Keyboard shortcuts"
+      description="Shortcuts for forms, lists, and navigation."
+      width="min(36rem, 92vw)"
+      footer={
+        <div className="flex justify-end">
+          <Btn variant="primary" rounded="lg" onClick={close}>
+            Close
+          </Btn>
+        </div>
+      }
+    >
+      <div className="space-y-6">
+        {SHORTCUT_GROUPS.map((group) => (
+          <section key={group.title}>
+            <h3 className="mb-3 text-sm font-semibold text-slate-900">
+              {group.title}
+            </h3>
+            <ul className="space-y-2">
+              {group.items.map((item) => (
+                <li
+                  key={item.keys}
+                  className="flex items-center justify-between gap-4 rounded-lg border border-slate-200 bg-slate-50 px-3 py-2"
+                >
+                  <span className="text-sm text-slate-600">{item.action}</span>
+                  <kbd className="shrink-0 rounded-md border border-slate-200 bg-white px-2 py-1 font-mono text-xs text-slate-800">
+                    {item.keys}
+                  </kbd>
+                </li>
+              ))}
+            </ul>
+          </section>
+        ))}
+      </div>
+    </ModalCard>
+  );
+}
+
+export function useKeyboardShortcutsHelp() {
+  const [open, setOpen] = useState(false);
+  return { helpOpen: open, setHelpOpen: setOpen };
+}

package/templates/notes/under-dev/keyboard-utils.ts

@@ -0,0 +1,22 @@
+export function isMacPlatform() {
+  if (typeof navigator === "undefined") return false;
+  return /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+}
+
+export function isModKey(event: KeyboardEvent) {
+  return isMacPlatform() ? event.metaKey : event.ctrlKey;
+}
+
+export function isTypingTarget(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+
+  const tag = target.tagName;
+  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+
+  return Boolean(target.closest("[data-overlay-popover]"));
+}
+
+export function formatModKey() {
+  return isMacPlatform() ? "⌘" : "Ctrl";
+}

package/templates/notes/under-dev/overlay/backdrop.tsx

@@ -0,0 +1,95 @@
+import React, { useEffect } from "react";
+import { Flex } from "../layout/flex";
+import type { FlexProps } from "@/types";
+import { getOverlayBackdropZ } from "@/utils/constants/z-index";
+import { requestOverlayCloseWithConfirm } from "@/hooks/overlay-close";
+
+interface BackdropProps {
+  children?: React.ReactNode;
+  onClose?: () => void;
+  justify?: FlexProps["justify"];
+  items?: FlexProps["items"];
+  direction?: FlexProps["direction"];
+  visible?: boolean;
+  isActive?: boolean;
+  layer?: number;
+}
+
+export function Backdrop({
+  children,
+  onClose,
+  justify,
+  items,
+  direction,
+  visible = true,
+  isActive = true,
+  layer = 1,
+}: BackdropProps) {
+  useEffect(() => {
+    if (!isActive) return;
+
+    const originalOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+
+    return () => {
+      document.body.style.overflow = originalOverflow;
+    };
+  }, [isActive]);
+
+  if (!isActive) {
+    return (
+      <div className="pointer-events-none invisible fixed inset-0" aria-hidden>
+        {children}
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <style>{`
+        @keyframes backdropFadeIn {
+          from {
+            opacity: 0;
+            backdrop-filter: blur(0px);
+          }
+          to {
+            opacity: 1;
+            backdrop-filter: blur(4px);
+          }
+        }
+        @keyframes backdropFadeOut {
+          from {
+            opacity: 1;
+            backdrop-filter: blur(4px);
+          }
+          to {
+            opacity: 0;
+            backdrop-filter: blur(0px);
+          }
+        }
+        .animate-backdrop-fade {
+          animation: backdropFadeIn 0.28s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+        }
+        .animate-backdrop-fade-out {
+          animation: backdropFadeOut 0.28s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+        }
+      `}</style>
+
+      <Flex
+        direction={direction || "row"}
+        items={items || "center"}
+        justify={justify || "center"}
+        className="inset-0 fixed overflow-hidden"
+        style={{ zIndex: getOverlayBackdropZ(layer) }}
+      >
+        <div
+          onClick={() => requestOverlayCloseWithConfirm()}
+          className={`absolute inset-0 cursor-pointer bg-black/50 ${
+            visible ? "animate-backdrop-fade" : "animate-backdrop-fade-out"
+          }`}
+        />
+        <div className="relative z-10">{children}</div>
+      </Flex>
+    </>
+  );
+}

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

@@ -0,0 +1,4 @@
+export * from "./backdrop";
+export * from "./modal";
+export * from "./portal";
+export * from "./side-panel";

package/templates/notes/under-dev/overlay/modal.tsx

@@ -0,0 +1,43 @@
+import { useEffect, type ReactNode } from "react";
+import { type Provider as Props } from "@/types";
+import { setActiveOverlayClose } from "@/hooks/form-overlay-registry";
+import { Portal } from "./portal";
+import { Backdrop } from "./backdrop";
+import { getOverlayContentZ } from "@/utils/constants/z-index";
+
+interface ModalBaseProps {
+  children?: ReactNode;
+  onClose?: () => void;
+  options: Props.OverlayOptions;
+  isActive?: boolean;
+  layer?: number;
+}
+
+export const Modal = ({
+  children,
+  onClose,
+  options,
+  isActive = true,
+  layer = 1,
+}: ModalBaseProps) => {
+  useEffect(() => {
+    if (!isActive || !onClose) return;
+    setActiveOverlayClose(onClose);
+    return () => setActiveOverlayClose(null);
+  }, [isActive, onClose]);
+
+  return (
+    <Portal>
+      <Backdrop
+        {...options}
+        onClose={onClose}
+        isActive={isActive}
+        layer={layer}
+      >
+        <div className="relative" style={{ zIndex: getOverlayContentZ(layer) }}>
+          {children}
+        </div>
+      </Backdrop>
+    </Portal>
+  );
+};

package/templates/notes/under-dev/overlay/side-panel.tsx

@@ -0,0 +1,126 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
+import { motion, AnimatePresence } from "motion/react";
+import { type Provider as Props } from "@/types";
+import { Portal } from "./portal";
+import { getOverlayBackdropZ, getOverlayContentZ } from "@/utils/constants/z-index";
+import { setActiveOverlayClose } from "@/hooks/form-overlay-registry";
+import { requestOverlayCloseWithConfirm } from "@/hooks/overlay-close";
+
+const panelSpring = { type: "spring" as const, damping: 25, stiffness: 200 };
+
+const SidePanelCloseContext = createContext<(() => void) | null>(null);
+
+/** Animated close — use this instead of AppProvider's immediate close. */
+export function useAnimatedSidePanelClose() {
+  const close = useContext(SidePanelCloseContext);
+  if (!close) {
+    throw new Error("useAnimatedSidePanelClose must be used within SidePanel");
+  }
+  return close;
+}
+
+interface SidePanelBaseProps {
+  children?: ReactNode;
+  onClose?: () => void;
+  options: Props.OverlayOptions;
+  isActive?: boolean;
+  layer?: number;
+}
+
+export function SidePanel({
+  children,
+  onClose,
+  options,
+  isActive = true,
+  layer = 1,
+}: SidePanelBaseProps) {
+  const [isOpen, setIsOpen] = useState(true);
+  const isLeft = options?.onSide === "left";
+
+  const requestClose = useCallback(() => setIsOpen(false), []);
+
+  useEffect(() => {
+    if (!isActive) return;
+    setActiveOverlayClose(requestClose);
+    return () => setActiveOverlayClose(null);
+  }, [isActive, requestClose]);
+
+  useEffect(() => {
+    if (!isOpen || !isActive) return;
+
+    const originalOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = originalOverflow;
+    };
+  }, [isActive, isOpen]);
+
+  const offscreenX = isLeft ? "-100%" : "100%";
+  const panelPosition = isLeft ? "left-0" : "right-0";
+  const backdropZ = getOverlayBackdropZ(layer);
+  const panelZ = getOverlayContentZ(layer);
+
+  if (!isActive) {
+    return (
+      <Portal>
+        <div className="pointer-events-none invisible fixed inset-0" aria-hidden>
+          <SidePanelCloseContext.Provider value={requestClose}>
+            {children}
+          </SidePanelCloseContext.Provider>
+        </div>
+      </Portal>
+    );
+  }
+
+  return (
+    <Portal>
+      <SidePanelCloseContext.Provider value={requestClose}>
+        <AnimatePresence onExitComplete={() => onClose?.()}>
+          {isOpen && (
+            <>
+              <motion.div
+                key="side-panel-backdrop"
+                initial={{ opacity: 0 }}
+                animate={{ opacity: 1 }}
+                exit={{ opacity: 0 }}
+                transition={{ duration: 0.2 }}
+                className="fixed inset-0 bg-slate-900/20 backdrop-blur-sm"
+                style={{ zIndex: backdropZ }}
+                onClick={requestOverlayCloseWithConfirm}
+                aria-hidden
+              />
+              <motion.div
+                key="side-panel-panel"
+                initial={{ x: offscreenX }}
+                animate={{ x: 0 }}
+                exit={{ x: offscreenX }}
+                transition={panelSpring}
+                className={`fixed inset-y-0 flex h-full ${panelPosition}`}
+                style={{ zIndex: panelZ }}
+              >
+                {children}
+              </motion.div>
+            </>
+          )}
+        </AnimatePresence>
+      </SidePanelCloseContext.Provider>
+    </Portal>
+  );
+}
+
+type SidePanelContentProps = {
+  content?: Props.OverlayContent;
+};
+
+/** Renders provider content with animated `close` wired to the panel. */
+export function SidePanelContent({ content }: SidePanelContentProps) {
+  const requestClose = useAnimatedSidePanelClose();
+  return content?.({ close: requestClose }) ?? null;
+}