Skip to content

AI media harness for planning, generating, and editing locally

TypeScript
3.6 KB
Raw Blame
/* Flyout — an anchored, light-dismiss popup on acrylic (WinUI Flyout).

   For small tools that open from a button: the work queue, a colour picker,
   a filter panel. It is non-modal: a press outside, Esc, a window resize or
   the window losing focus closes it; focus moves into it on open and back to
   the anchor on Esc.

     const button = useRef<HTMLButtonElement>(null);
     const [open, setOpen] = useState(false);
     <button ref={button} aria-expanded={open} onClick={() => setOpen(!open)}>Queue</button>
     <Flyout open={open} anchor={button} onClose={() => setOpen(false)} aria-label="Work queue">
       …
     </Flyout>
*/

import { useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode, type RefObject } from "react";
import { createPortal } from "react-dom";
import { LAYER_ATTR, cx, focusSafely, focusables, placeAnchored, useLightDismiss, type Placement, type RectLike } from "./internal";

export interface FlyoutProps {
  open: boolean;
  /** The element it hangs from (a ref or the element), or a rect. */
  anchor: RefObject<HTMLElement | null> | HTMLElement | RectLike | null;
  onClose: () => void;
  children?: ReactNode;
  placement?: Placement;
  "aria-label"?: string;
  "aria-labelledby"?: string;
  className?: string;
  /** Focus this on open; default the first focusable inside, else the flyout. */
  initialFocus?: RefObject<HTMLElement | null>;
  /** Width in px (default: content). */
  width?: number;
  /** Default "dialog". */
  role?: "dialog" | "region" | "group";
}

const resolveAnchor = (anchor: FlyoutProps["anchor"]): { element: HTMLElement | null; rect: RectLike | null } => {
  if (!anchor) return { element: null, rect: null };
  if (typeof HTMLElement !== "undefined" && anchor instanceof HTMLElement) return { element: anchor, rect: anchor.getBoundingClientRect() };
  if ("current" in anchor) return { element: anchor.current, rect: anchor.current?.getBoundingClientRect() ?? null };
  return { element: null, rect: anchor as RectLike };
};

export function Flyout({ open, anchor, onClose, children, placement = "bottom", className, initialFocus, width, role = "dialog", ...aria }: FlyoutProps) {
  const panel = useRef<HTMLDivElement>(null);
  /* The width is on the panel from the first frame, so what is measured below
     is the size it will have: measured at its content width, a wide flyout
     was placed as if it were narrow and ran off the right edge. */
  const [style, setStyle] = useState<CSSProperties>({ visibility: "hidden", width });
  const anchorElement = resolveAnchor(anchor).element;

  useLayoutEffect(() => {
    if (!open || !panel.current) return;
    const { rect } = resolveAnchor(anchor);
    const size = { width: width ?? panel.current.offsetWidth, height: panel.current.offsetHeight };
    const placed = rect ? placeAnchored(rect, size, placement, 4) : { left: 8, top: 8 };
    setStyle({ left: placed.left, top: placed.top, width });
    focusSafely(initialFocus?.current ?? focusables(panel.current)[0] ?? panel.current);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [open]);

  useLightDismiss(panel, open, (reason) => {
    if (reason === "escape") focusSafely(resolveAnchor(anchor).element);
    onClose();
  }, { ignore: [anchorElement] });

  if (!open) return null;
  return createPortal(
    <div
      ref={panel}
      role={role}
      tabIndex={-1}
      aria-label={aria["aria-label"]}
      aria-labelledby={aria["aria-labelledby"]}
      className={cx("ui-flyout", className)}
      style={style}
      {...{ [LAYER_ATTR]: "flyout" }}
    >
      {children}
    </div>,
    document.body,
  );
}