@mihcm/ui 0.14.1

package/src/Popover.tsx

@@ -0,0 +1,175 @@
+'use client';
+
+/**
+ * Popover (web variant — React DOM).
+ *
+ * Click-triggered floating panel anchored to a trigger element.
+ * Composes the shared Popper positioning primitive so floating-layer
+ * behavior stays consistent across Popover, Tooltip, Select, and menus.
+ *
+ *   <Popover open={open} onOpenChange={setOpen}>
+ *     <PopoverTrigger>
+ *       <Button>Open</Button>
+ *     </PopoverTrigger>
+ *     <PopoverContent>
+ *       <p>Popover body</p>
+ *     </PopoverContent>
+ *   </Popover>
+ *
+ * Wiki: docs/components/Popover.md
+ */
+import {
+  createContext,
+  forwardRef,
+  useContext,
+  useEffect,
+  useState,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from './internal/cn.js';
+import {
+  Popper,
+  PopperContent,
+  PopperTrigger,
+  type PopperPlacement,
+  type PopperStrategy,
+} from './Popper.js';
+
+/* ── Context ────────────────────────────────────────────────────────── */
+
+interface PopoverContextValue {
+  setSide: (side: PopoverSide) => void;
+  setAlign: (align: PopoverAlign) => void;
+}
+
+const PopoverContext = createContext<PopoverContextValue | null>(null);
+
+function usePopoverContext() {
+  const ctx = useContext(PopoverContext);
+  if (!ctx) throw new Error('Popover compound components must be used within <Popover>');
+  return ctx;
+}
+
+/* ── Root ───────────────────────────────────────────────────────────── */
+
+export interface PopoverProps {
+  open?: boolean | undefined;
+  defaultOpen?: boolean | undefined;
+  onOpenChange?: ((open: boolean) => void) | undefined;
+  children: ReactNode;
+  className?: string;
+  arrow?: boolean | undefined;
+  offset?: [number, number] | undefined;
+  strategy?: PopperStrategy | undefined;
+  portalled?: boolean | undefined;
+  align?: PopoverAlign | undefined;
+  matchReferenceWidth?: boolean | undefined;
+}
+
+type PopoverSide = 'top' | 'bottom' | 'left' | 'right';
+type PopoverAlign = 'start' | 'center' | 'end';
+
+export function Popover({
+  open,
+  defaultOpen,
+  onOpenChange,
+  children,
+  className,
+  arrow = false,
+  offset = [0, 8],
+  strategy,
+  portalled,
+  align: defaultAlign = 'center',
+  matchReferenceWidth = false,
+}: PopoverProps) {
+  const [side, setSide] = useState<PopoverSide>('bottom');
+  const [align, setAlign] = useState<PopoverAlign>(defaultAlign);
+  const placement = sideToPlacement(side, align);
+
+  return (
+    <Popper
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      placement={placement}
+      arrow={arrow}
+      offset={offset}
+      {...(strategy ? { strategy } : {})}
+      {...(portalled !== undefined ? { portalled } : {})}
+      matchReferenceWidth={matchReferenceWidth}
+    >
+      <PopoverContext.Provider value={{ setSide, setAlign }}>
+        <div className={cn('inline-flex', className)}>{children}</div>
+      </PopoverContext.Provider>
+    </Popper>
+  );
+}
+
+/* ── Trigger ────────────────────────────────────────────────────────── */
+
+export interface PopoverTriggerProps {
+  children: ReactElement;
+}
+
+/**
+ * Delegates to PopperTrigger, which clones its single child and merges
+ * trigger props onto it. This avoids nesting a `<button>` inside a
+ * `<button>` when the child is already a Button.
+ */
+export function PopoverTrigger({ children }: PopoverTriggerProps) {
+  return <PopperTrigger>{children}</PopperTrigger>;
+}
+
+/* ── Content ────────────────────────────────────────────────────────── */
+
+export const popoverContentVariants = cva(
+  'rounded-xl border border-border bg-card p-4 shadow-lg animate-dropdown-in',
+  {
+    variants: {
+      size: {
+        sm: 'w-56',
+        md: 'w-72',
+        lg: 'w-96',
+        auto: 'w-auto',
+      },
+    },
+    defaultVariants: { size: 'md' },
+  },
+);
+
+export interface PopoverContentProps
+  extends HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof popoverContentVariants> {
+  side?: PopoverSide | undefined;
+  align?: PopoverAlign | undefined;
+  arrowClassName?: string | undefined;
+}
+
+export const PopoverContent = forwardRef<HTMLDivElement, PopoverContentProps>(
+  function PopoverContent({ className, side = 'bottom', align = 'center', size, arrowClassName, ...props }, ref) {
+    const ctx = usePopoverContext();
+
+    useEffect(() => {
+      ctx.setSide(side);
+      ctx.setAlign(align);
+    }, [align, ctx, side]);
+
+    return (
+      <PopperContent
+        ref={ref}
+        size={size}
+        arrowClassName={arrowClassName}
+        className={cn(popoverContentVariants({ size }), className)}
+        {...props}
+      />
+    );
+  },
+);
+
+function sideToPlacement(side: PopoverSide, align: PopoverAlign): PopperPlacement {
+  if (align === 'center') return side;
+  return `${side}-${align}` as PopperPlacement;
+}

package/src/Popper.tsx

@@ -0,0 +1,399 @@
+'use client';
+
+/**
+ * Popper (web variant — React DOM).
+ *
+ * Low-level positioning primitive powered by `react-popper` and
+ * `@popperjs/core`. Use it when Tooltip, Popover, DropdownMenu, or Select do
+ * not expose enough positioning control.
+ *
+ * Wiki: docs/components/Popper.md
+ */
+import {
+  cloneElement,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type MouseEvent,
+  type Ref,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { createPortal } from 'react-dom';
+import { usePopper, type Modifier as ReactPopperModifier } from 'react-popper';
+import type { Placement, PositioningStrategy, State, VirtualElement } from '@popperjs/core';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from './internal/cn.js';
+
+export type PopperPlacement = Placement;
+export type PopperStrategy = PositioningStrategy;
+export type PopperVirtualElement = VirtualElement;
+export type PopperModifier<
+  Name extends string = string,
+  Options extends object = Record<string, unknown>,
+> = ReactPopperModifier<Name, Options>;
+
+type PopperContextValue = {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  referenceElement: Element | VirtualElement | null;
+  setReferenceElement: (element: Element | null) => void;
+  triggerElement: HTMLElement | null;
+  setTriggerElement: (element: HTMLElement | null) => void;
+  contentElement: HTMLElement | null;
+  setContentElement: (element: HTMLElement | null) => void;
+  arrowElement: HTMLElement | null;
+  setArrowElement: (element: HTMLElement | null) => void;
+  placement: Placement;
+  strategy: PositioningStrategy;
+  offset: [number, number];
+  flip: boolean;
+  preventOverflow: boolean;
+  arrow: boolean;
+  matchReferenceWidth: boolean;
+  modifiers: ReadonlyArray<PopperModifier> | undefined;
+  onFirstUpdate: ((state: Partial<State>) => void) | undefined;
+  closeOnOutsidePointerDown: boolean;
+  closeOnEscape: boolean;
+  portalled: boolean;
+};
+
+const PopperContext = createContext<PopperContextValue | null>(null);
+
+function usePopperContext() {
+  const ctx = useContext(PopperContext);
+  if (!ctx) throw new Error('Popper compound components must be used within <Popper>.');
+  return ctx;
+}
+
+export interface PopperProps {
+  children: ReactNode;
+  open?: boolean | undefined;
+  defaultOpen?: boolean | undefined;
+  onOpenChange?: ((open: boolean) => void) | undefined;
+  placement?: Placement | undefined;
+  strategy?: PositioningStrategy | undefined;
+  offset?: [number, number] | undefined;
+  flip?: boolean | undefined;
+  preventOverflow?: boolean | undefined;
+  arrow?: boolean | undefined;
+  matchReferenceWidth?: boolean | undefined;
+  modifiers?: ReadonlyArray<PopperModifier> | undefined;
+  referenceElement?: Element | VirtualElement | null | undefined;
+  onFirstUpdate?: ((state: Partial<State>) => void) | undefined;
+  closeOnOutsidePointerDown?: boolean | undefined;
+  closeOnEscape?: boolean | undefined;
+  portalled?: boolean | undefined;
+}
+
+export function Popper({
+  children,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  placement = 'bottom-start',
+  strategy = 'absolute',
+  offset = [0, 8],
+  flip = true,
+  preventOverflow = true,
+  arrow = false,
+  matchReferenceWidth = false,
+  modifiers,
+  referenceElement: externalReferenceElement,
+  onFirstUpdate,
+  closeOnOutsidePointerDown = true,
+  closeOnEscape = true,
+  portalled = true,
+}: PopperProps) {
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const [triggerElement, setTriggerElement] = useState<HTMLElement | null>(null);
+  const [contentElement, setContentElement] = useState<HTMLElement | null>(null);
+  const [arrowElement, setArrowElement] = useState<HTMLElement | null>(null);
+  const [localReferenceElement, setLocalReferenceElement] = useState<Element | null>(null);
+
+  const currentOpen = open ?? internalOpen;
+  const setOpen = useCallback(
+    (nextOpen: boolean) => {
+      onOpenChange?.(nextOpen);
+      if (open === undefined) setInternalOpen(nextOpen);
+    },
+    [onOpenChange, open],
+  );
+
+  return (
+    <PopperContext.Provider
+      value={{
+        open: currentOpen,
+        setOpen,
+        referenceElement: externalReferenceElement ?? localReferenceElement,
+        setReferenceElement: setLocalReferenceElement,
+        triggerElement,
+        setTriggerElement,
+        contentElement,
+        setContentElement,
+        arrowElement,
+        setArrowElement,
+        placement,
+        strategy,
+        offset,
+        flip,
+        preventOverflow,
+        arrow,
+        matchReferenceWidth,
+        modifiers,
+        onFirstUpdate,
+        closeOnOutsidePointerDown,
+        closeOnEscape,
+        portalled,
+      }}
+    >
+      {children}
+    </PopperContext.Provider>
+  );
+}
+
+export interface PopperTriggerProps {
+  children: ReactElement;
+}
+
+export function PopperTrigger({ children }: PopperTriggerProps) {
+  const ctx = usePopperContext();
+
+  if (!isValidElement(children)) {
+    throw new Error('PopperTrigger requires a single React element child.');
+  }
+
+  return cloneElement(children as ReactElement<Record<string, unknown>>, {
+    ref: (node: HTMLElement | null) => {
+      ctx.setTriggerElement(node);
+      ctx.setReferenceElement(node);
+      setRef((children as ReactElement<{ ref?: Ref<HTMLElement> }>).props.ref, node);
+    },
+    'aria-expanded': ctx.open,
+    'aria-haspopup': 'dialog' as const,
+    onClick: (event: MouseEvent) => {
+      const childOnClick = (children.props as Record<string, unknown>).onClick;
+      if (typeof childOnClick === 'function') childOnClick(event);
+      if (event.defaultPrevented) return;
+      ctx.setOpen(!ctx.open);
+    },
+  });
+}
+
+export const popperContentVariants = cva(
+  'z-50 rounded-lg border border-border bg-popover p-3 text-popover-foreground shadow-md outline-none animate-dropdown-in',
+  {
+    variants: {
+      size: {
+        sm: 'w-56',
+        md: 'w-72',
+        lg: 'w-96',
+        auto: 'w-auto',
+      },
+    },
+    defaultVariants: { size: 'md' },
+  },
+);
+
+export interface PopperContentProps
+  extends HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof popperContentVariants> {
+  hideWhenReferenceHidden?: boolean | undefined;
+  arrowClassName?: string | undefined;
+}
+
+export const PopperContent = forwardRef<HTMLDivElement, PopperContentProps>(
+  function PopperContent(
+    { className, size, hideWhenReferenceHidden = true, arrowClassName, children, style, ...props },
+    ref,
+  ) {
+    const ctx = usePopperContext();
+    const contentRef = useRef<HTMLDivElement | null>(null);
+    const modifiers = useMemo(
+      () => createModifiers(ctx, hideWhenReferenceHidden),
+      [ctx, hideWhenReferenceHidden],
+    );
+    const popperOptions = useMemo(
+      () => ({
+        placement: ctx.placement,
+        strategy: ctx.strategy,
+        modifiers,
+        ...(ctx.onFirstUpdate ? { onFirstUpdate: ctx.onFirstUpdate } : {}),
+      }),
+      [ctx.placement, ctx.strategy, modifiers, ctx.onFirstUpdate],
+    );
+    const { styles, attributes, state, update } = usePopper(
+      ctx.referenceElement,
+      ctx.contentElement,
+      popperOptions,
+    );
+
+    useEffect(() => {
+      if (!ctx.open || !ctx.closeOnOutsidePointerDown) return;
+      const handlePointerDown = (event: PointerEvent) => {
+        const target = event.target as Node;
+        if (ctx.triggerElement?.contains(target)) return;
+        if (contentRef.current?.contains(target)) return;
+        ctx.setOpen(false);
+      };
+      document.addEventListener('pointerdown', handlePointerDown);
+      return () => document.removeEventListener('pointerdown', handlePointerDown);
+    }, [ctx]);
+
+    useEffect(() => {
+      if (!ctx.open || !ctx.closeOnEscape) return;
+      const handleKeyDown = (event: KeyboardEvent) => {
+        if (event.key === 'Escape') {
+          ctx.setOpen(false);
+          ctx.triggerElement?.focus();
+        }
+      };
+      document.addEventListener('keydown', handleKeyDown);
+      return () => document.removeEventListener('keydown', handleKeyDown);
+    }, [ctx]);
+
+    useEffect(() => {
+      if (!ctx.open) return;
+      void update?.();
+    }, [ctx.open, update]);
+
+    if (!ctx.open) return null;
+
+    const isReferenceHidden = state?.modifiersData.hide?.isReferenceHidden === true;
+    const content = (
+      <div
+        ref={(node) => {
+          contentRef.current = node;
+          ctx.setContentElement(node);
+          if (typeof ref === 'function') ref(node);
+          else if (ref) ref.current = node;
+        }}
+        role="dialog"
+        data-popper-placement={state?.placement ?? ctx.placement}
+        data-reference-hidden={isReferenceHidden ? 'true' : undefined}
+        className={cn(
+          popperContentVariants({ size }),
+          hideWhenReferenceHidden && isReferenceHidden && 'invisible pointer-events-none',
+          className,
+        )}
+        style={{ ...styles.popper, ...style }}
+        {...attributes.popper}
+        {...props}
+      >
+        {children}
+        {ctx.arrow ? (
+          <PopperArrow
+            placement={state?.placement ?? ctx.placement}
+            className={arrowClassName}
+            style={styles.arrow}
+          />
+        ) : null}
+      </div>
+    );
+
+    if (!ctx.portalled || typeof document === 'undefined') return content;
+    return createPortal(content, document.body);
+  },
+);
+
+export interface PopperArrowProps extends HTMLAttributes<HTMLDivElement> {
+  placement?: Placement | undefined;
+}
+
+export const PopperArrow = forwardRef<HTMLDivElement, PopperArrowProps>(
+  function PopperArrow({ className, placement = 'bottom', style, ...props }, ref) {
+    const ctx = usePopperContext();
+    const side = placement.split('-')[0] as 'top' | 'bottom' | 'left' | 'right';
+
+    return (
+      <div
+        ref={(node) => {
+          ctx.setArrowElement(node);
+          if (typeof ref === 'function') ref(node);
+          else if (ref) ref.current = node;
+        }}
+        aria-hidden="true"
+        data-side={side}
+        className={cn(
+          'pointer-events-none absolute z-[-1] size-2 rotate-45 border border-border bg-popover',
+          side === 'top' && '-bottom-1',
+          side === 'bottom' && '-top-1',
+          side === 'left' && '-right-1',
+          side === 'right' && '-left-1',
+          className,
+        )}
+        style={style}
+        {...props}
+      />
+    );
+  },
+);
+
+function setRef<T>(ref: Ref<T> | undefined, value: T | null) {
+  if (typeof ref === 'function') ref(value);
+  else if (ref) ref.current = value;
+}
+
+function createModifiers(
+  ctx: PopperContextValue,
+  hideWhenReferenceHidden: boolean,
+): ReadonlyArray<PopperModifier> {
+  const builtIn: PopperModifier[] = [
+    {
+      name: 'offset',
+      options: { offset: ctx.offset },
+    } as PopperModifier<'offset'>,
+    {
+      name: 'flip',
+      enabled: ctx.flip,
+      options: { fallbackPlacements: ['top', 'right', 'bottom', 'left'] },
+    } as PopperModifier<'flip'>,
+    {
+      name: 'preventOverflow',
+      enabled: ctx.preventOverflow,
+      options: { padding: 8, altAxis: true, tether: true },
+    } as PopperModifier<'preventOverflow'>,
+    {
+      name: 'arrow',
+      enabled: ctx.arrow,
+      options: { element: ctx.arrowElement, padding: 8 },
+    } as PopperModifier<'arrow'>,
+    {
+      name: 'hide',
+      enabled: hideWhenReferenceHidden,
+    } as PopperModifier<'hide'>,
+  ];
+
+  if (ctx.matchReferenceWidth) {
+    builtIn.push(matchReferenceWidthModifier);
+  }
+
+  return [...builtIn, ...(ctx.modifiers ?? [])];
+}
+
+const matchReferenceWidthModifier = {
+  name: 'matchReferenceWidth',
+  enabled: true,
+  phase: 'beforeWrite',
+  requires: ['computeStyles'],
+  fn({ state }: { state: State }) {
+    state.styles.popper = {
+      ...state.styles.popper,
+      width: `${state.rects.reference.width}px`,
+    };
+  },
+  effect({ state }: { state: State }) {
+    const reference = state.elements.reference;
+    if ('getBoundingClientRect' in reference) {
+      state.elements.popper.style.width = `${reference.getBoundingClientRect().width}px`;
+    }
+    return undefined;
+  },
+} satisfies PopperModifier<'matchReferenceWidth'>;