@astryxdesign/core 0.7.6 → 0.7.7-canary.0eb44a2

package/src/hooks/useAttachment.ts

@@ -4,16 +4,16 @@
 
 /**
  * @file useAttachment.ts
- * @input A node ref (an element's, or the document's), an attach function
+ * @input Node refs (an element's, or the document's), an attach function
  *   and a key
- * @output Exports useAttachment: keeps the attach function bound to the node
- *   the ref holds across commits
- * @position Internal React helper, not in hooks/index.ts: the one attach
- *   and release lifecycle of the gesture hooks (useGestureRecognizer,
- *   usePressTracker, useFingerScroll)
+ * @output Exports useAttachment and useAttachmentPair (two elements): they keep
+ *   the attach function bound to the nodes the refs hold across commits
+ * @position Internal React helper, not in hooks/index.ts: the one attach and
+ *   release lifecycle of the gesture hooks and the pager
  *
- * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx
- * and gestures/__tests__/useFingerScroll.test.tsx.
+ * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx,
+ * gestures/__tests__/useFingerScroll.test.tsx and
+ * __tests__/useAttachmentPair.test.tsx.
  */
 
 import {useRef, type RefObject} from 'react';
@@ -29,23 +29,65 @@ export function useAttachment<T extends Node = Element>(
   ref: RefObject<T | null>,
   attach: (element: T) => () => void,
   key: unknown,
+): void {
+  useAttachedNodes([ref], ([node]) => attach(node as T), key);
+}
+
+/**
+ * `useAttachment` for two elements. It keeps `attach` bound to the pair the
+ * refs hold after each commit, once both are there. Replacing either element
+ * releases the attachment and attaches the new pair. A changed `key`
+ * re-attaches, and the last attachment is released on unmount. A commit that
+ * changes neither does nothing.
+ */
+export function useAttachmentPair<A extends Element, B extends Element>(
+  firstRef: RefObject<A | null>,
+  secondRef: RefObject<B | null>,
+  attach: (first: A, second: B) => () => void,
+  key: unknown,
+): void {
+  useAttachedNodes(
+    [firstRef, secondRef],
+    ([first, second]) => attach(first as A, second as B),
+    key,
+  );
+}
+
+/**
+ * The lifecycle both share: one attachment of the nodes the refs hold. It is
+ * made once every node is there, and released when a node or `key` changes
+ * and at unmount.
+ */
+function useAttachedNodes(
+  refs: ReadonlyArray<RefObject<Node | null>>,
+  attach: (nodes: ReadonlyArray<Node>) => () => void,
+  key: unknown,
 ): void {
   const attachmentRef = useRef<{
-    element: T;
+    nodes: ReadonlyArray<Node>;
     key: unknown;
     release: () => void;
   } | null>(null);
 
-  // Syncs the attachment with the DOM node `ref` holds after this commit.
+  // Syncs the attachment with the DOM nodes the refs hold after this commit.
   useIsomorphicLayoutEffect(() => {
-    const element = ref.current;
+    const nodes = refs.map(ref => ref.current);
     const current = attachmentRef.current;
-    if (current?.element === element && current?.key === key) {
+    if (
+      current != null &&
+      current.key === key &&
+      nodes.every((node, index) => node === current.nodes[index])
+    ) {
       return;
     }
     current?.release();
-    attachmentRef.current =
-      element == null ? null : {element, key, release: attach(element)};
+    attachmentRef.current = nodes.every(node => node != null)
+      ? {
+          nodes: nodes,
+          key,
+          release: attach(nodes),
+        }
+      : null;
   });
 
   // Releases the attachment at unmount.

package/src/hooks/useFocusTrap.ts

@@ -228,7 +228,29 @@ export interface UseFocusTrapReturn<T extends HTMLElement = HTMLElement> {
 export function useFocusTrap<T extends HTMLElement = HTMLElement>(
   options: UseFocusTrapOptions,
 ): UseFocusTrapReturn<T> {
-  const {isActive, onEscape} = options;
+  return useFocusTrapInternal<T>(options);
+}
+
+/**
+ * Package-internal options. Not re-exported from the package entry point.
+ */
+interface InternalFocusTrapOptions extends UseFocusTrapOptions {
+  /**
+   * The element to restore focus to on deactivation, read at activation. For
+   * an overlay that may move focus inside before the trap activates (initial
+   * focus within the opening event), the element focused at activation is
+   * already inside, so the overlay names its opener instead. Returning `null`
+   * falls back to the element focused at activation.
+   */
+  getRestoreTarget?: () => HTMLElement | null;
+}
+
+export function useFocusTrapInternal<T extends HTMLElement = HTMLElement>(
+  options: InternalFocusTrapOptions,
+): UseFocusTrapReturn<T> {
+  const {isActive, onEscape, getRestoreTarget} = options;
+  const getRestoreTargetRef = useRef(getRestoreTarget);
+  getRestoreTargetRef.current = getRestoreTarget;
 
   const containerRef = useRef<T | null>(null);
   const lastFocusRef = useRef<Element | null>(null);
@@ -302,7 +324,9 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
     // Snapshot the container now; by cleanup it may be detached or unmounted.
     const container = containerRef.current;
     const doc = trapDocument(container);
-    const previouslyFocused = doc.activeElement as HTMLElement | null;
+    const previouslyFocused =
+      getRestoreTargetRef.current?.() ??
+      (doc.activeElement as HTMLElement | null);
 
     // Whether focus ever entered the trap container while it was active.
     // Initialized from the current active element in case focus was already