@zentauri-ui/zentauri-components 1.7.1 → 1.7.3

package/src/ui/popover/popover-base.tsx

@@ -0,0 +1,261 @@
+"use client";
+
+import {
+  Children,
+  cloneElement,
+  createContext,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type RefObject,
+  type KeyboardEventHandler,
+  type MouseEventHandler,
+  type ReactElement,
+  type Ref,
+  useMemo,
+} from "react";
+
+import { cn } from "../../lib/utils";
+
+import type {
+  PopoverAlign,
+  PopoverContentProps,
+  PopoverContextType,
+  PopoverProps,
+  PopoverSide,
+  PopoverTriggerProps,
+} from "./types";
+import { popoverContentVariants } from "./variants";
+
+export const PopoverContext = createContext<PopoverContextType | null>(null);
+
+export const usePopover = () => {
+  const context = useContext(PopoverContext);
+  if (!context) {
+    throw new Error("Popover components must be used within Popover");
+  }
+  return context;
+};
+
+function mergeRefs<T>(...refs: Array<Ref<T> | undefined>) {
+  return (node: T) => {
+    for (const ref of refs) {
+      if (typeof ref === "function") {
+        ref(node);
+      } else if (ref) {
+        (ref as RefObject<T | null>).current = node;
+      }
+    }
+  };
+}
+
+export function sideAlignClass(side: PopoverSide, align: PopoverAlign) {
+  const sideClasses = {
+    top: "bottom-full mb-2",
+    bottom: "top-full mt-2",
+    left: "right-full mr-2",
+    right: "left-full ml-2",
+  } satisfies Record<PopoverSide, string>;
+
+  const verticalAlign = {
+    start: "left-0",
+    center: "left-1/2 -translate-x-1/2",
+    end: "right-0",
+  } satisfies Record<PopoverAlign, string>;
+
+  const horizontalAlign = {
+    start: "top-0",
+    center: "top-1/2 -translate-y-1/2",
+    end: "bottom-0",
+  } satisfies Record<PopoverAlign, string>;
+
+  return cn(
+    sideClasses[side],
+    side === "top" || side === "bottom"
+      ? verticalAlign[align]
+      : horizontalAlign[align],
+  );
+}
+
+export const Popover = ({
+  children,
+  defaultOpen = false,
+  open: controlledOpen,
+  onOpenChange,
+  closeOnEscape = true,
+  closeOnOutsideClick = true,
+}: PopoverProps) => {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const contentId = `${useId()}-popover`;
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const contentRef = useRef<HTMLDivElement | null>(null);
+
+  const isControlled = controlledOpen !== undefined;
+  const open = isControlled ? controlledOpen : uncontrolledOpen;
+
+  const setOpen = useCallback(
+    (value: boolean) => {
+      if (!isControlled) {
+        setUncontrolledOpen(value);
+      }
+      onOpenChange?.(value);
+    },
+    [isControlled, onOpenChange],
+  );
+
+  const toggleOpen = useCallback(() => setOpen(!open), [open, setOpen]);
+
+  useEffect(() => {
+    if (!open) {
+      return undefined;
+    }
+
+    const onPointerDown = (event: PointerEvent) => {
+      if (!closeOnOutsideClick) {
+        return;
+      }
+      const target = event.target as Node;
+      if (
+        contentRef.current?.contains(target) ||
+        triggerRef.current?.contains(target)
+      ) {
+        return;
+      }
+      setOpen(false);
+    };
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape" && closeOnEscape) {
+        setOpen(false);
+        triggerRef.current?.focus();
+      }
+    };
+
+    document.addEventListener("pointerdown", onPointerDown);
+    document.addEventListener("keydown", onKeyDown);
+
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown);
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [closeOnEscape, closeOnOutsideClick, open, setOpen]);
+
+  const contextValue = useMemo(
+    () => ({
+      open,
+      setOpen,
+      toggleOpen,
+      contentId,
+      triggerRef,
+      contentRef,
+    }),
+    [open, setOpen, toggleOpen, contentId],
+  );
+
+  return (
+    <PopoverContext.Provider
+      value={contextValue}
+    >
+      <div className="relative inline-block">{children}</div>
+    </PopoverContext.Provider>
+  );
+};
+
+export const PopoverTrigger = ({
+  children,
+  className,
+}: PopoverTriggerProps) => {
+  const { open, toggleOpen, contentId, triggerRef } = usePopover();
+  const childList = Children.toArray(children).filter(
+    (node) => node !== null && node !== undefined && typeof node !== "boolean",
+  );
+
+  const soleCandidate =
+    childList.length === 1 && isValidElement(childList[0])
+      ? (childList[0] as ReactElement<{
+          className?: string;
+          ref?: Ref<HTMLElement>;
+          onClick?: MouseEventHandler;
+          onKeyDown?: KeyboardEventHandler;
+          "aria-expanded"?: boolean;
+          "aria-haspopup"?: string;
+          "aria-controls"?: string;
+        }>)
+      : undefined;
+
+  if (soleCandidate) {
+    return cloneElement(soleCandidate, {
+      ref: mergeRefs(triggerRef, soleCandidate.props.ref),
+      onClick: (event) => {
+        soleCandidate.props.onClick?.(event);
+        if (!event.defaultPrevented) {
+          toggleOpen();
+        }
+      },
+      onKeyDown: (event) => {
+        soleCandidate.props.onKeyDown?.(event);
+        if (event.key === "Escape") {
+          event.preventDefault();
+        }
+      },
+      className: cn(className, soleCandidate.props.className),
+      "aria-expanded": open,
+      "aria-haspopup": "dialog",
+      "aria-controls": open ? contentId : undefined,
+    });
+  }
+
+  return (
+    <button
+      ref={triggerRef as Ref<HTMLButtonElement>}
+      type="button"
+      className={className}
+      aria-expanded={open}
+      aria-haspopup="dialog"
+      aria-controls={open ? contentId : undefined}
+      onClick={toggleOpen}
+    >
+      {children}
+    </button>
+  );
+};
+
+export const PopoverContent = ({
+  children,
+  className,
+  variant,
+  size,
+  width,
+  side = "bottom",
+  align = "center",
+  role = "dialog",
+  ...props
+}: PopoverContentProps) => {
+  const { open, contentId, contentRef } = usePopover();
+
+  if (!open) {
+    return null;
+  }
+
+  return (
+    <div
+      ref={contentRef}
+      id={contentId}
+      data-open={open}
+      role={role}
+      tabIndex={-1}
+      className={cn(
+        popoverContentVariants({ variant, size, width }),
+        sideAlignClass(side, align),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+};

package/src/ui/popover/popover.test.tsx

@@ -0,0 +1,84 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { Popover, PopoverContent, PopoverTrigger } from "./popover";
+
+describe("Popover", () => {
+  it("should open and close popover content from the trigger", async () => {
+    const user = userEvent.setup();
+    render(
+      <Popover>
+        <PopoverTrigger>
+          <button type="button">Open panel</button>
+        </PopoverTrigger>
+        <PopoverContent>Interactive panel</PopoverContent>
+      </Popover>,
+    );
+
+    const trigger = screen.getByRole("button", { name: "Open panel" });
+    await user.click(trigger);
+    expect(screen.getByRole("dialog")).toHaveTextContent("Interactive panel");
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+
+    await user.click(trigger);
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+  });
+
+  it("should close when clicking outside the popover", async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <Popover defaultOpen>
+          <PopoverTrigger>
+            <button type="button">Open panel</button>
+          </PopoverTrigger>
+          <PopoverContent>Panel body</PopoverContent>
+        </Popover>
+        <button type="button">Outside</button>
+      </>,
+    );
+
+    expect(screen.getByRole("dialog")).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Outside" }));
+    await waitFor(() => {
+      expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+    });
+  });
+
+  it("should close on Escape and return focus to the trigger", async () => {
+    const user = userEvent.setup();
+    render(
+      <Popover defaultOpen>
+        <PopoverTrigger>
+          <button type="button">Focus trigger</button>
+        </PopoverTrigger>
+        <PopoverContent>Escape closes me</PopoverContent>
+      </Popover>,
+    );
+
+    await user.keyboard("{Escape}");
+    await waitFor(() => {
+      expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+    });
+    expect(screen.getByRole("button", { name: "Focus trigger" })).toHaveFocus();
+  });
+
+  it("should support controlled open state", async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+
+    render(
+      <Popover open={false} onOpenChange={onOpenChange}>
+        <PopoverTrigger>
+          <button type="button">Controlled</button>
+        </PopoverTrigger>
+        <PopoverContent>Controlled body</PopoverContent>
+      </Popover>,
+    );
+
+    await user.click(screen.getByRole("button", { name: "Controlled" }));
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+  });
+});

package/src/ui/popover/popover.tsx

@@ -0,0 +1,8 @@
+// popover.tsx — default static entry (no framer-motion)
+export {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverContext,
+  usePopover,
+} from "./popover-base";

package/src/ui/popover/types.ts

@@ -0,0 +1,38 @@
+import { VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+import { popoverContentVariants } from "./variants";
+
+export type PopoverSide = "top" | "left" | "bottom" | "right";
+export type PopoverAlign = "start" | "center" | "end";
+
+export type PopoverContextType = {
+  open: boolean;
+  setOpen: (value: boolean) => void;
+  toggleOpen: () => void;
+  contentId: string;
+  triggerRef: React.RefObject<HTMLElement | null>;
+  contentRef: React.RefObject<HTMLDivElement | null>;
+};
+
+export type PopoverProps = {
+  children: ReactNode;
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  closeOnEscape?: boolean;
+  closeOnOutsideClick?: boolean;
+};
+
+export type PopoverTriggerProps = {
+  children: ReactNode;
+  className?: string;
+};
+
+export type PopoverContentProps = ComponentPropsWithRef<"div"> & {
+  children: ReactNode;
+  variant?: VariantProps<typeof popoverContentVariants>["variant"]
+  size?: VariantProps<typeof popoverContentVariants>["size"];
+  width?: VariantProps<typeof popoverContentVariants>["width"];
+  side?: PopoverSide;
+  align?: PopoverAlign;
+};

package/src/ui/popover/variants.ts

@@ -0,0 +1,21 @@
+import { cva } from "class-variance-authority";
+
+import {
+  zuiPopoverContentBase,
+  zuiPopoverContentSizes,
+  zuiPopoverContentVariants,
+  zuiPopoverContentWidths,
+} from "../../design-system/popover";
+
+export const popoverContentVariants = cva(zuiPopoverContentBase, {
+  variants: {
+    variant: zuiPopoverContentVariants,
+    size: zuiPopoverContentSizes,
+    width: zuiPopoverContentWidths,
+  },
+  defaultVariants: {
+    variant: "default",
+    size: "md",
+    width: "xs",
+  },
+});