@structuralists/scaffolding 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "main": "./index.ts",
   "types": "./index.ts",
   "exports": {

package/src/components/Content/Menu/index.tsx

@@ -9,6 +9,7 @@ import {
 import { createPortal } from 'react-dom';
 import type { MenuItem, MenuProps } from './types';
 import { cx } from '../../../utils';
+import { useClickOutside } from '../../../hooks/useClickOutside';
 import styles from './styles.module.css';
 
 const isBranch = (
@@ -205,26 +206,20 @@ export const Menu = (props: MenuProps) => {
     );
   }, [open]);
 
+  useClickOutside({
+    ref: panelRef,
+    extraRefs: [triggerRef],
+    onOutside: () => setOpen(false),
+    enabled: open,
+  });
+
   useEffect(() => {
     if (!open) return;
-
-    const handleMouseDown = (e: MouseEvent) => {
-      const target = e.target as Node;
-      if (triggerRef.current?.contains(target)) return;
-      if (panelRef.current?.contains(target)) return;
-      setOpen(false);
-    };
-
     const handleKey = (e: KeyboardEvent) => {
       if (e.key === 'Escape') setOpen(false);
     };
-
-    window.addEventListener('mousedown', handleMouseDown);
     window.addEventListener('keydown', handleKey);
-    return () => {
-      window.removeEventListener('mousedown', handleMouseDown);
-      window.removeEventListener('keydown', handleKey);
-    };
+    return () => window.removeEventListener('keydown', handleKey);
   }, [open]);
 
   return (

package/src/components/Overlays/Popover/Popover.test.tsx

@@ -0,0 +1,75 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { useRef } from 'react';
+import { render, fireEvent, cleanup } from '@testing-library/react';
+import { Popover } from './index';
+import { globalEscapeHatches } from '../../../globalEscapeHatches';
+
+const Harness = (props: { onClose: () => void; isOpen?: boolean }) => {
+  const { onClose, isOpen = true } = props;
+  const anchorRef = useRef<HTMLButtonElement>(null);
+  return (
+    <div>
+      <button ref={anchorRef} type="button">
+        anchor
+      </button>
+      <Popover anchorRef={anchorRef} isOpen={isOpen} onClose={onClose}>
+        <div>popover-body</div>
+      </Popover>
+      <div data-testid="outside">elsewhere</div>
+    </div>
+  );
+};
+
+describe('Popover outside-click integration', () => {
+  test('dismisses on a normal pointerdown outside', () => {
+    const onClose = mock(() => {});
+    const { getByTestId } = render(<Harness onClose={onClose} />);
+    fireEvent.pointerDown(getByTestId('outside'));
+    expect(onClose).toHaveBeenCalledTimes(1);
+    cleanup();
+  });
+
+  test('does not dismiss when clicking the anchor', () => {
+    const onClose = mock(() => {});
+    const { getByText } = render(<Harness onClose={onClose} />);
+    fireEvent.pointerDown(getByText('anchor'));
+    expect(onClose).not.toHaveBeenCalled();
+    cleanup();
+  });
+
+  test('does not dismiss when clicking inside the panel', () => {
+    const onClose = mock(() => {});
+    const { getByText } = render(<Harness onClose={onClose} />);
+    fireEvent.pointerDown(getByText('popover-body'));
+    expect(onClose).not.toHaveBeenCalled();
+    cleanup();
+  });
+
+  // The motivating case for globalEscapeHatches: a host (e.g. a canvas-based
+  // UI library) captures pointer events before they reach the document, so
+  // the normal pointerdown listener never fires. The escape hatch lets the
+  // host's "click on background" handler still dismiss the popover.
+  test('globalEscapeHatches.onTriggerOutsideClick dismisses an open popover', () => {
+    const onClose = mock(() => {});
+    render(<Harness onClose={onClose} />);
+    globalEscapeHatches.onTriggerOutsideClick();
+    expect(onClose).toHaveBeenCalledTimes(1);
+    cleanup();
+  });
+
+  test('escape hatch is a no-op when the popover is closed', () => {
+    const onClose = mock(() => {});
+    render(<Harness onClose={onClose} isOpen={false} />);
+    globalEscapeHatches.onTriggerOutsideClick();
+    expect(onClose).not.toHaveBeenCalled();
+    cleanup();
+  });
+
+  test('dismisses on Escape', () => {
+    const onClose = mock(() => {});
+    render(<Harness onClose={onClose} />);
+    fireEvent.keyDown(document.body, { key: 'Escape' });
+    expect(onClose).toHaveBeenCalledTimes(1);
+    cleanup();
+  });
+});

package/src/components/Overlays/Popover/index.tsx

@@ -9,6 +9,7 @@ import {
 import { createPortal } from 'react-dom';
 import type { PopoverPlacement, PopoverProps } from './types';
 import { cx } from '../../../utils';
+import { useClickOutside } from '../../../hooks/useClickOutside';
 import styles from './styles.module.css';
 
 const GAP = 6;
@@ -100,27 +101,21 @@ export const Popover = (props: PopoverProps) => {
     );
   }, [isOpen, anchorRef, placement, matchAnchorWidth]);
 
+  useClickOutside({
+    ref: panelRef,
+    extraRefs: [anchorRef],
+    onOutside: onClose,
+    enabled: isOpen,
+  });
+
   useEffect(() => {
     if (!isOpen) return;
-
-    const handleMouseDown = (e: MouseEvent) => {
-      const target = e.target as Node;
-      if (panelRef.current?.contains(target)) return;
-      if (anchorRef.current?.contains(target)) return;
-      onClose();
-    };
-
     const handleKey = (e: KeyboardEvent) => {
       if (e.key === 'Escape') onClose();
     };
-
-    window.addEventListener('mousedown', handleMouseDown);
     window.addEventListener('keydown', handleKey);
-    return () => {
-      window.removeEventListener('mousedown', handleMouseDown);
-      window.removeEventListener('keydown', handleKey);
-    };
-  }, [isOpen, anchorRef, onClose]);
+    return () => window.removeEventListener('keydown', handleKey);
+  }, [isOpen, onClose]);
 
   // Capture the anchor at open time so a rerender that swaps the element
   // still restores focus to whatever the user originally engaged.

package/src/globalEscapeHatches.ts

@@ -0,0 +1,33 @@
+/** Escape hatches for cases where the host environment swallows the events
+ *  our overlays normally listen for — e.g. a canvas-based UI library that
+ *  captures pointer events before they reach the document, so the
+ *  `pointerdown` listener that dismisses popovers/menus/slide-overlays
+ *  never fires.
+ *
+ *  Call these from your integration glue. They read clearly at the call
+ *  site — from the import alone it's obvious what's happening and why. */
+
+const outsideClickHandlers = new Set<() => void>();
+
+/** Register a handler that should run when something asks the library to
+ *  simulate an outside click. Returns an unregister function. Wired up
+ *  internally by `useClickOutside`; not part of the public API. */
+export const registerOutsideClickHandler = (handler: () => void) => {
+  outsideClickHandlers.add(handler);
+  return () => {
+    outsideClickHandlers.delete(handler);
+  };
+};
+
+export const globalEscapeHatches = {
+  /** Dismiss every currently open overlay whose dismissal is wired through
+   *  `useClickOutside` (popovers, menus, slide-in overlays, and anything
+   *  built on top of them). No-op when nothing is open. */
+  onTriggerOutsideClick: () => {
+    // Snapshot first — handlers deregister themselves as a side effect of
+    // closing, which would mutate the live set mid-iteration.
+    for (const handler of [...outsideClickHandlers]) {
+      handler();
+    }
+  },
+};

package/src/hooks/useClickOutside/index.ts

@@ -1,10 +1,15 @@
 import { useEffect, useRef, type RefObject } from 'react';
 import { useStableCallback } from '../useStableCallback';
+import { registerOutsideClickHandler } from '../../globalEscapeHatches';
 
 type UseClickOutsideArgs<Element extends HTMLElement> = {
   /** Optional external ref. When omitted, the hook owns an internal ref —
    *  attach the returned `ref` to the element you want to guard. */
   ref?: RefObject<Element | null>;
+  /** Additional refs whose contents should also count as "inside" — e.g. an
+   *  anchoring trigger button that lives outside the guarded panel but
+   *  shouldn't dismiss it when clicked. */
+  extraRefs?: ReadonlyArray<RefObject<HTMLElement | null>>;
   /** Callback fired on a `pointerdown` outside the guarded element. When
    *  `undefined`, the listener is detached (lets callers gate via a prop
    *  without conditionally calling the hook). */
@@ -26,32 +31,56 @@ type UseClickOutsideReturn<Element extends HTMLElement> = {
  *  The callback is internally stabilized, so callers can pass an inline
  *  function without retriggering the listener attach/detach effect.
  *
+ *  Also auto-registers with `globalEscapeHatches.onTriggerOutsideClick`,
+ *  so hosts that swallow pointer events before they reach the document
+ *  (e.g. canvas-based UI libraries) can still trigger dismissal manually.
+ *
  *  Note: clicks inside portal'd descendants of the guarded element
  *  (popovers, tooltips, menus) count as outside since they are not
- *  DOM-contained. Compose with additional refs or a custom predicate
- *  if that is not desired. */
+ *  DOM-contained. Compose with `extraRefs` or a custom predicate if
+ *  that is not desired. */
 export const useClickOutside = <Element extends HTMLElement = HTMLElement>(
   args: UseClickOutsideArgs<Element>,
 ): UseClickOutsideReturn<Element> => {
-  const { ref: passedRef, onOutside, enabled = true } = args;
+  const { ref: passedRef, extraRefs, onOutside, enabled = true } = args;
 
   const innerRef = useRef<Element | null>(null);
   const ref = passedRef ?? innerRef;
 
+  // Held in a ref so a fresh array literal from the caller (e.g. inline
+  // `[anchorRef]`) doesn't churn the listener-attach effect every render.
+  const extraRefsRef = useRef(extraRefs);
+  useEffect(() => {
+    extraRefsRef.current = extraRefs;
+  }, [extraRefs]);
+
   const stableOnOutside = useStableCallback({ callback: onOutside });
   const isActive = enabled && onOutside != null;
 
   useEffect(() => {
     if (!isActive) return;
     const handler = (event: PointerEvent) => {
+      if (!(event.target instanceof Node)) return;
+      const target = event.target;
       const el = ref.current;
       if (el == null) return;
-      if (event.target instanceof Node && el.contains(event.target)) return;
+      if (el.contains(target)) return;
+      const extras = extraRefsRef.current;
+      if (extras) {
+        for (const r of extras) {
+          if (r.current?.contains(target)) return;
+        }
+      }
       stableOnOutside();
     };
     document.addEventListener('pointerdown', handler);
     return () => document.removeEventListener('pointerdown', handler);
   }, [ref, isActive, stableOnOutside]);
 
+  useEffect(() => {
+    if (!isActive) return;
+    return registerOutsideClickHandler(stableOnOutside);
+  }, [isActive, stableOnOutside]);
+
   return { ref };
 };

package/src/hooks/useClickOutside/useClickOutside.test.tsx

@@ -0,0 +1,104 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { useRef } from 'react';
+import { render, fireEvent, cleanup } from '@testing-library/react';
+import { useClickOutside } from './index';
+import { globalEscapeHatches } from '../../globalEscapeHatches';
+
+const Guarded = (props: {
+  onOutside: () => void;
+  enabled?: boolean;
+  withExtra?: boolean;
+}) => {
+  const { onOutside, enabled, withExtra } = props;
+  const panelRef = useRef<HTMLDivElement>(null);
+  const extraRef = useRef<HTMLButtonElement>(null);
+  useClickOutside({
+    ref: panelRef,
+    extraRefs: withExtra ? [extraRef] : undefined,
+    onOutside,
+    enabled,
+  });
+  return (
+    <div>
+      <button ref={extraRef} type="button">
+        trigger
+      </button>
+      <div ref={panelRef}>
+        <span>panel-child</span>
+      </div>
+      <div data-testid="outside">elsewhere</div>
+    </div>
+  );
+};
+
+describe('useClickOutside', () => {
+  test('fires onOutside for a pointerdown outside the guarded element', () => {
+    const onOutside = mock(() => {});
+    const { getByTestId } = render(<Guarded onOutside={onOutside} />);
+    fireEvent.pointerDown(getByTestId('outside'));
+    expect(onOutside).toHaveBeenCalledTimes(1);
+    cleanup();
+  });
+
+  test('does not fire for a pointerdown inside the guarded element', () => {
+    const onOutside = mock(() => {});
+    const { getByText } = render(<Guarded onOutside={onOutside} />);
+    fireEvent.pointerDown(getByText('panel-child'));
+    expect(onOutside).not.toHaveBeenCalled();
+    cleanup();
+  });
+
+  test('treats extraRefs as inside', () => {
+    const onOutside = mock(() => {});
+    const { getByText } = render(<Guarded onOutside={onOutside} withExtra />);
+    fireEvent.pointerDown(getByText('trigger'));
+    expect(onOutside).not.toHaveBeenCalled();
+    cleanup();
+  });
+
+  test('detaches when disabled', () => {
+    const onOutside = mock(() => {});
+    const { getByTestId } = render(
+      <Guarded onOutside={onOutside} enabled={false} />,
+    );
+    fireEvent.pointerDown(getByTestId('outside'));
+    expect(onOutside).not.toHaveBeenCalled();
+    cleanup();
+  });
+
+  test('globalEscapeHatches.onTriggerOutsideClick dismisses active consumers', () => {
+    const onOutside = mock(() => {});
+    render(<Guarded onOutside={onOutside} />);
+    globalEscapeHatches.onTriggerOutsideClick();
+    expect(onOutside).toHaveBeenCalledTimes(1);
+    cleanup();
+  });
+
+  test('disabled consumers are skipped by the escape hatch', () => {
+    const onOutside = mock(() => {});
+    render(<Guarded onOutside={onOutside} enabled={false} />);
+    globalEscapeHatches.onTriggerOutsideClick();
+    expect(onOutside).not.toHaveBeenCalled();
+    cleanup();
+  });
+
+  test('unmounted consumers deregister from the escape hatch', () => {
+    const onOutside = mock(() => {});
+    const { unmount } = render(<Guarded onOutside={onOutside} />);
+    unmount();
+    globalEscapeHatches.onTriggerOutsideClick();
+    expect(onOutside).not.toHaveBeenCalled();
+    cleanup();
+  });
+
+  test('fires all active consumers when multiple are mounted', () => {
+    const onOutsideA = mock(() => {});
+    const onOutsideB = mock(() => {});
+    render(<Guarded onOutside={onOutsideA} />);
+    render(<Guarded onOutside={onOutsideB} />);
+    globalEscapeHatches.onTriggerOutsideClick();
+    expect(onOutsideA).toHaveBeenCalledTimes(1);
+    expect(onOutsideB).toHaveBeenCalledTimes(1);
+    cleanup();
+  });
+});

package/src/index.ts

@@ -87,3 +87,4 @@ export { LongText, type LongTextProps } from './components/Primitives/LongText';
 export { type BackgroundToken } from './tokens';
 export { useStableCallback } from './hooks/useStableCallback';
 export { useClickOutside } from './hooks/useClickOutside';
+export { globalEscapeHatches } from './globalEscapeHatches';