@pzerelles/headlessui-svelte 2.1.2-next.3 → 2.1.2-next.4

package/dist/focus-trap/FocusTrap.svelte

@@ -1,314 +1,460 @@
-<script lang="ts" module>import { getOwnerDocument } from "../utils/owner.js";
-import { history } from "../utils/active-element-history.js";
-import { useWatch } from "../hooks/use-watch.svelte.js";
-import { microTask } from "../utils/microTask.js";
-import { Focus, focusElement, focusIn, FocusResult } from "../utils/focus-management.js";
-import { useIsTopLayer } from "../hooks/use-is-top-layer.svelte.js";
-import { useIsMounted } from "../hooks/use-is-mounted.svelte.js";
-import { useEventListener } from "../hooks/use-event-listener.svelte.js";
-import { useTabDirection, Direction as TabDirection } from "../hooks/use-tab-direction.svelte.js";
-import { match } from "../utils/match.js";
-import { useDisposables } from "../utils/disposables.js";
-import Hidden, { HiddenFeatures } from "../internal/Hidden.svelte";
-import ElementOrComponent from "../utils/ElementOrComponent.svelte";
-function resolveContainers(containers) {
-  if (!containers) return /* @__PURE__ */ new Set();
-  if (typeof containers === "function") return new Set(containers());
-  let all = /* @__PURE__ */ new Set();
-  for (let container of containers) {
-    if (container instanceof HTMLElement) {
-      all.add(container);
-    }
-  }
-  return all;
-}
-let DEFAULT_FOCUS_TRAP_TAG = "div";
-export var FocusTrapFeatures = /* @__PURE__ */ ((FocusTrapFeatures2) => {
-  FocusTrapFeatures2[FocusTrapFeatures2["None"] = 0] = "None";
-  FocusTrapFeatures2[FocusTrapFeatures2["InitialFocus"] = 1] = "InitialFocus";
-  FocusTrapFeatures2[FocusTrapFeatures2["TabLock"] = 2] = "TabLock";
-  FocusTrapFeatures2[FocusTrapFeatures2["FocusLock"] = 4] = "FocusLock";
-  FocusTrapFeatures2[FocusTrapFeatures2["RestoreFocus"] = 8] = "RestoreFocus";
-  FocusTrapFeatures2[FocusTrapFeatures2["AutoFocus"] = 16] = "AutoFocus";
-  return FocusTrapFeatures2;
-})(FocusTrapFeatures || {});
-function useRestoreElement(options) {
-  const { enabled } = $derived(options ?? { enabled: true });
-  let localHistory = $state(history.slice());
-  useWatch({
-    action: ([newEnabled], [oldEnabled]) => {
-      if (oldEnabled === true && newEnabled === false) {
-        microTask(() => {
-          localHistory.splice(0);
-        });
-      }
-      if (oldEnabled === false && newEnabled === true) {
-        localHistory = history.slice();
+<script lang="ts" module>
+  import { getOwnerDocument } from "../utils/owner.js"
+  import type { ElementType, Props } from "../utils/types.js"
+  import { history } from "../utils/active-element-history.js"
+  import { useWatch } from "../hooks/use-watch.svelte.js"
+  import { microTask } from "../utils/microTask.js"
+  import { Focus, focusElement, focusIn, FocusResult } from "../utils/focus-management.js"
+  import { useIsTopLayer } from "../hooks/use-is-top-layer.svelte.js"
+  import { useIsMounted } from "../hooks/use-is-mounted.svelte.js"
+  import { useEventListener } from "../hooks/use-event-listener.svelte.js"
+  import { useTabDirection, Direction as TabDirection } from "../hooks/use-tab-direction.svelte.js"
+  import { match } from "../utils/match.js"
+  import { useDisposables } from "../utils/disposables.js"
+  import Hidden, { HiddenFeatures } from "../internal/Hidden.svelte"
+  import ElementOrComponent from "../utils/ElementOrComponent.svelte"
+
+  type Containers =
+    // Lazy resolved containers
+    | (() => Iterable<HTMLElement>)
+
+    // List of containers
+    | Iterable<HTMLElement>
+
+  function resolveContainers(containers?: Containers): Set<HTMLElement> {
+    if (!containers) return new Set<HTMLElement>()
+    if (typeof containers === "function") return new Set(containers())
+
+    let all = new Set<HTMLElement>()
+    for (let container of containers) {
+      if (container instanceof HTMLElement) {
+        all.add(container)
       }
-    },
-    get dependencies() {
-      return [enabled, history, localHistory];
     }
-  });
-  return {
-    get lastElement() {
-      return localHistory.find((x) => x != null && x.isConnected) ?? null;
-    }
-  };
-}
-function useRestoreFocus(options) {
-  const { features, ownerDocument } = $derived(options);
-  const enabled = $derived(Boolean(features & 8 /* RestoreFocus */));
-  const restoreElement = useRestoreElement({
-    get enabled() {
-      return enabled;
+    return all
+  }
+
+  let DEFAULT_FOCUS_TRAP_TAG = "div" as const
+
+  export enum FocusTrapFeatures {
+    /** No features enabled for the focus trap. */
+    None = 0,
+
+    /** Ensure that we move focus initially into the container. */
+    InitialFocus = 1 << 0,
+
+    /** Ensure that pressing `Tab` and `Shift+Tab` is trapped within the container. */
+    TabLock = 1 << 1,
+
+    /** Ensure that programmatically moving focus outside of the container is disallowed. */
+    FocusLock = 1 << 2,
+
+    /** Ensure that we restore the focus when unmounting the focus trap. */
+    RestoreFocus = 1 << 3,
+
+    /** Initial focus should look for the `data-autofocus` */
+    AutoFocus = 1 << 4,
+  }
+
+  type FocusTrapRenderPropArg = {}
+  type FocusTrapPropsWeControl = never
+
+  export type FocusTrapProps<TTag extends ElementType = typeof DEFAULT_FOCUS_TRAP_TAG> = Props<
+    TTag,
+    FocusTrapRenderPropArg,
+    FocusTrapPropsWeControl,
+    {
+      initialFocus?: HTMLElement
+      // A fallback element to focus, but this element will be skipped when tabbing around. This is
+      // only done for focusing a fallback parent container (e.g.: A `Dialog`, but you want to tab
+      // *inside* the dialog excluding the dialog itself).
+      initialFocusFallback?: HTMLElement
+      features?: FocusTrapFeatures
+      containers?: Containers
     }
-  });
-  useWatch({
-    action: () => {
-      if (enabled) return;
-      if (ownerDocument?.activeElement === ownerDocument?.body) {
-        focusElement(restoreElement.lastElement);
-      }
-    },
-    get dependencies() {
-      return [enabled];
+  >
+
+  function useRestoreElement(options?: { enabled: boolean }) {
+    const { enabled } = $derived(options ?? { enabled: true })
+    let localHistory = $state<HTMLElement[]>(history.slice())
+
+    useWatch({
+      action: ([newEnabled], [oldEnabled]) => {
+        // We are disabling the restore element, so we need to clear it.
+        if (oldEnabled === true && newEnabled === false) {
+          // However, let's schedule it in a microTask, so that we can still read the value in the
+          // places where we are restoring the focus.
+          microTask(() => {
+            localHistory.splice(0)
+          })
+        }
+
+        // We are enabling the restore element, so we need to set it to the last "focused" element.
+        if (oldEnabled === false && newEnabled === true) {
+          localHistory = history.slice()
+        }
+      },
+      get dependencies() {
+        return [enabled, history, localHistory]
+      },
+    })
+
+    // We want to return the last element that is still connected to the DOM, so we can restore the
+    // focus to it.
+    return {
+      get lastElement() {
+        return localHistory.find((x) => x != null && x.isConnected) ?? null
+      },
     }
-  });
-  $effect(() => {
-    if (!enabled) return;
-    return () => focusElement(restoreElement.lastElement);
-  });
-}
-function useInitialFocus(options) {
-  const { features, ownerDocument, container, initialFocus, initialFocusFallback } = $derived(options);
-  let previousActiveElement = $state(null);
-  let enabled = useIsTopLayer({
-    get enabled() {
-      return Boolean(features & 1 /* InitialFocus */);
-    },
-    scope: "focus-trap#initial-focus"
-  });
-  let mounted = useIsMounted();
-  useWatch({
-    action: () => {
-      if (features === 0 /* None */) {
-        return;
-      }
-      if (!enabled) {
-        if (initialFocusFallback) {
-          focusElement(initialFocusFallback);
+  }
+
+  function useRestoreFocus(options: { features: FocusTrapFeatures; ownerDocument: Document | null }) {
+    const { features, ownerDocument } = $derived(options)
+    const enabled = $derived(Boolean(features & FocusTrapFeatures.RestoreFocus))
+
+    const restoreElement = useRestoreElement({
+      get enabled() {
+        return enabled
+      },
+    })
+
+    // Restore the focus to the previous element when `enabled` becomes false again
+    useWatch({
+      action: () => {
+        if (enabled) return
+
+        if (ownerDocument?.activeElement === ownerDocument?.body) {
+          focusElement(restoreElement.lastElement)
         }
-        return;
-      }
-      let containerElement = container;
-      if (!containerElement) return;
-      microTask(() => {
-        if (!mounted.current) {
-          return;
+      },
+      get dependencies() {
+        return [enabled]
+      },
+    })
+
+    // Restore the focus to the previous element when the component is unmounted
+    $effect(() => {
+      if (!enabled) return
+
+      return () => focusElement(restoreElement.lastElement)
+    })
+  }
+
+  function useInitialFocus(options: {
+    features: FocusTrapFeatures
+    ownerDocument: Document | null
+    container: HTMLElement | null
+    initialFocus?: HTMLElement | null
+    initialFocusFallback?: HTMLElement | null
+  }) {
+    const { features, ownerDocument, container, initialFocus, initialFocusFallback } = $derived(options)
+    let previousActiveElement = $state<HTMLElement | null>(null)
+    let enabled = useIsTopLayer({
+      get enabled() {
+        return Boolean(features & FocusTrapFeatures.InitialFocus)
+      },
+      scope: "focus-trap#initial-focus",
+    })
+
+    let mounted = useIsMounted()
+
+    // Handle initial focus
+    useWatch({
+      action: () => {
+        // No focus management needed
+        if (features === FocusTrapFeatures.None) {
+          return
         }
-        let activeElement = ownerDocument?.activeElement;
-        if (initialFocus) {
-          if (initialFocus === activeElement) {
-            previousActiveElement = activeElement;
-            return;
+
+        if (!enabled) {
+          // If we are disabling the initialFocus, then we should focus the fallback element if one is
+          // provided. This is needed to ensure _something_ is focused. Typically a wrapping element
+          // (e.g.: `Dialog` component).
+          //
+          // Note: we _don't_ want to move focus to the `initialFocus` ref, because the `InitialFocus`
+          // feature is disabled.
+          if (initialFocusFallback) {
+            focusElement(initialFocusFallback)
           }
-        } else if (containerElement.contains(activeElement)) {
-          previousActiveElement = activeElement;
-          return;
+
+          return
         }
-        if (initialFocus) {
-          focusElement(initialFocus);
-        } else {
-          if (features & 16 /* AutoFocus */) {
-            if (focusIn(containerElement, Focus.First | Focus.AutoFocus) !== FocusResult.Error) {
-              return;
+        let containerElement = container
+        if (!containerElement) return
+
+        // Delaying the focus to the next microtask ensures that a few conditions are true:
+        // - The container is rendered
+        // - Transitions could be started
+        // If we don't do this, then focusing an element will immediately cancel any transitions. This
+        // is not ideal because transitions will look broken.
+        // There is an additional issue with doing this immediately. The FocusTrap is used inside a
+        // Dialog, the Dialog is rendered inside of a Portal and the Portal is rendered at the end of
+        // the `document.body`. This means that the moment we call focus, the browser immediately
+        // tries to focus the element, which will still be at the bottom resulting in the page to
+        // scroll down. Delaying this will prevent the page to scroll down entirely.
+        microTask(() => {
+          if (!mounted.current) {
+            return
+          }
+
+          let activeElement = ownerDocument?.activeElement as HTMLElement
+
+          if (initialFocus) {
+            if (initialFocus === activeElement) {
+              previousActiveElement = activeElement
+              return // Initial focus ref is already the active element
             }
-          } else if (focusIn(containerElement, Focus.First) !== FocusResult.Error) {
-            return;
+          } else if (containerElement!.contains(activeElement)) {
+            previousActiveElement = activeElement
+            return // Already focused within Dialog
           }
-          if (initialFocusFallback) {
-            focusElement(initialFocusFallback);
-            if (ownerDocument?.activeElement === initialFocusFallback) {
-              return;
+
+          // Try to focus the initialFocus ref
+          if (initialFocus) {
+            focusElement(initialFocus)
+          } else {
+            if (features & FocusTrapFeatures.AutoFocus) {
+              // Try to focus the first focusable element with `Focus.AutoFocus` feature enabled
+              if (focusIn(containerElement!, Focus.First | Focus.AutoFocus) !== FocusResult.Error) {
+                return // Worked, bail
+              }
+            }
+
+            // Try to focus the first focusable element.
+            else if (focusIn(containerElement!, Focus.First) !== FocusResult.Error) {
+              return // Worked, bail
+            }
+
+            // Try the fallback
+            if (initialFocusFallback) {
+              focusElement(initialFocusFallback)
+              if (ownerDocument?.activeElement === initialFocusFallback) {
+                return // Worked, bail
+              }
             }
+
+            // Nothing worked
+            console.warn("There are no focusable elements inside the <FocusTrap />")
           }
-          console.warn("There are no focusable elements inside the <FocusTrap />");
-        }
-        previousActiveElement = ownerDocument?.activeElement;
-      });
-    },
-    get dependencies() {
-      return [initialFocusFallback, enabled, features];
-    }
-  });
-  return {
-    get value() {
-      return previousActiveElement;
-    },
-    set value(element) {
-      previousActiveElement = element;
+
+          previousActiveElement = ownerDocument?.activeElement as HTMLElement
+        })
+      },
+      get dependencies() {
+        return [initialFocusFallback, enabled, features]
+      },
+    })
+
+    return {
+      get value() {
+        return previousActiveElement
+      },
+      set value(element) {
+        previousActiveElement = element
+      },
     }
-  };
-}
-function useFocusLock(options) {
-  let { features, ownerDocument, container, containers, previousActiveElement } = $derived(options);
-  const mounted = useIsMounted();
-  const enabled = $derived(Boolean(features & 4 /* FocusLock */));
-  useEventListener({
-    get element() {
-      return ownerDocument?.defaultView;
-    },
-    type: "focus",
-    listener: (event) => {
-      if (!enabled) return;
-      if (!mounted.current) return;
-      let allContainers = resolveContainers(containers);
-      if (container instanceof HTMLElement) allContainers.add(container);
-      let previous = previousActiveElement;
-      if (!previous) return;
-      let toElement = event.target;
-      if (toElement && toElement instanceof HTMLElement) {
-        if (!contains(allContainers, toElement)) {
-          event.preventDefault();
-          event.stopPropagation();
-          focusElement(previous);
+  }
+
+  function useFocusLock(options: {
+    features: FocusTrapFeatures
+    ownerDocument: Document | null
+    container: HTMLElement | null
+    containers?: Containers
+    previousActiveElement: HTMLElement | null
+  }) {
+    let { features, ownerDocument, container, containers, previousActiveElement } = $derived(options)
+    const mounted = useIsMounted()
+    const enabled = $derived(Boolean(features & FocusTrapFeatures.FocusLock))
+
+    // Prevent programmatically escaping the container
+    useEventListener({
+      get element() {
+        return ownerDocument?.defaultView
+      },
+      type: "focus",
+      listener: (event) => {
+        if (!enabled) return
+        if (!mounted.current) return
+
+        let allContainers = resolveContainers(containers)
+        if (container instanceof HTMLElement) allContainers.add(container)
+
+        let previous = previousActiveElement
+        if (!previous) return
+
+        let toElement = event.target as HTMLElement | null
+
+        if (toElement && toElement instanceof HTMLElement) {
+          if (!contains(allContainers, toElement)) {
+            event.preventDefault()
+            event.stopPropagation()
+            focusElement(previous)
+          } else {
+            options.previousActiveElement = toElement
+            focusElement(toElement)
+          }
         } else {
-          options.previousActiveElement = toElement;
-          focusElement(toElement);
+          focusElement(previousActiveElement)
         }
-      } else {
-        focusElement(previousActiveElement);
-      }
-    },
-    options: true
-  });
-}
-function contains(containers, element) {
-  for (let container of containers) {
-    if (container.contains(element)) return true;
+      },
+      options: true,
+    })
   }
-  return false;
-}
-</script>
 
-<script lang="ts" generics="TTag extends ElementType = typeof DEFAULT_FOCUS_TRAP_TAG">let container = $state(null);
-let {
-  ref = $bindable(),
-  initialFocus,
-  initialFocusFallback,
-  containers,
-  features = FocusTrapFeatures.InitialFocus | FocusTrapFeatures.TabLock | FocusTrapFeatures.FocusLock | FocusTrapFeatures.RestoreFocus,
-  ...theirProps
-} = $props();
-const ownerDocument = $derived(getOwnerDocument(ref));
-useRestoreFocus({
-  get features() {
-    return features;
-  },
-  get ownerDocument() {
-    return ownerDocument;
-  }
-});
-let previousActiveElement = useInitialFocus({
-  get features() {
-    return features;
-  },
-  get ownerDocument() {
-    return ownerDocument;
-  },
-  get container() {
-    return container;
-  },
-  get initialFocus() {
-    return initialFocus;
-  },
-  get initialFocusFallback() {
-    return initialFocusFallback;
+  function contains(containers: Set<HTMLElement>, element: HTMLElement) {
+    for (let container of containers) {
+      if (container.contains(element)) return true
+    }
+
+    return false
   }
-});
-useFocusLock({
-  get features() {
-    return features;
-  },
-  get ownerDocument() {
-    return ownerDocument;
-  },
-  get container() {
-    return container;
-  },
-  get containers() {
-    return containers;
-  },
-  get previousActiveElement() {
-    return previousActiveElement.value;
-  },
-  set previousActiveElement(element) {
-    previousActiveElement.value = element;
+</script>
+
+<script lang="ts" generics="TTag extends ElementType = typeof DEFAULT_FOCUS_TRAP_TAG">
+  let container = $state<HTMLElement | null>(null)
+  let {
+    ref = $bindable(),
+    initialFocus,
+    initialFocusFallback,
+    containers,
+    features = FocusTrapFeatures.InitialFocus |
+      FocusTrapFeatures.TabLock |
+      FocusTrapFeatures.FocusLock |
+      FocusTrapFeatures.RestoreFocus,
+    ...theirProps
+  }: { as?: TTag } & FocusTrapProps<TTag> = $props()
+
+  /*if (!useServerHandoffComplete()) {
+    features = FocusTrapFeatures.None
+  }*/
+
+  const ownerDocument = $derived(getOwnerDocument(ref))
+
+  useRestoreFocus({
+    get features() {
+      return features
+    },
+    get ownerDocument() {
+      return ownerDocument
+    },
+  })
+  let previousActiveElement = useInitialFocus({
+    get features() {
+      return features
+    },
+    get ownerDocument() {
+      return ownerDocument
+    },
+    get container() {
+      return container
+    },
+    get initialFocus() {
+      return initialFocus
+    },
+    get initialFocusFallback() {
+      return initialFocusFallback
+    },
+  })
+
+  useFocusLock({
+    get features() {
+      return features
+    },
+    get ownerDocument() {
+      return ownerDocument
+    },
+    get container() {
+      return container
+    },
+    get containers() {
+      return containers
+    },
+    get previousActiveElement() {
+      return previousActiveElement.value
+    },
+    set previousActiveElement(element) {
+      previousActiveElement.value = element
+    },
+  })
+
+  const direction = useTabDirection()
+  const handleFocus = (e: FocusEvent) => {
+    let el = container as HTMLElement
+    if (!el) return
+
+    // TODO: Cleanup once we are using real browser tests
+    let wrapper = process.env.NODE_ENV === "test" ? microTask : (cb: Function) => cb()
+    wrapper(() => {
+      match(direction.current, {
+        [TabDirection.Forwards]: () => {
+          focusIn(el, Focus.First, {
+            skipElements: [e.relatedTarget, initialFocusFallback] as HTMLElement[],
+          })
+        },
+        [TabDirection.Backwards]: () => {
+          focusIn(el, Focus.Last, {
+            skipElements: [e.relatedTarget, initialFocusFallback] as HTMLElement[],
+          })
+        },
+      })
+    })
   }
-});
-const direction = useTabDirection();
-const handleFocus = (e) => {
-  let el = container;
-  if (!el) return;
-  let wrapper = process.env.NODE_ENV === "test" ? microTask : (cb) => cb();
-  wrapper(() => {
-    match(direction.current, {
-      [TabDirection.Forwards]: () => {
-        focusIn(el, Focus.First, {
-          skipElements: [e.relatedTarget, initialFocusFallback]
-        });
-      },
-      [TabDirection.Backwards]: () => {
-        focusIn(el, Focus.Last, {
-          skipElements: [e.relatedTarget, initialFocusFallback]
-        });
+
+  let tabLockEnabled = useIsTopLayer({
+    get enabled() {
+      return Boolean(features & FocusTrapFeatures.TabLock)
+    },
+    scope: "focus-trap#tab-lock",
+  })
+
+  const d = useDisposables()
+  let recentlyUsedTabKey = $state(false)
+  const ourProps = $derived({
+    onkeydown(e: KeyboardEvent) {
+      if (e.key == "Tab") {
+        recentlyUsedTabKey = true
+        d.requestAnimationFrame(() => {
+          recentlyUsedTabKey = false
+        })
       }
-    });
-  });
-};
-let tabLockEnabled = useIsTopLayer({
-  get enabled() {
-    return Boolean(features & FocusTrapFeatures.TabLock);
-  },
-  scope: "focus-trap#tab-lock"
-});
-const d = useDisposables();
-let recentlyUsedTabKey = $state(false);
-const ourProps = $derived({
-  onkeydown(e) {
-    if (e.key == "Tab") {
-      recentlyUsedTabKey = true;
-      d.requestAnimationFrame(() => {
-        recentlyUsedTabKey = false;
-      });
-    }
-  },
-  onblur(e) {
-    if (!(features & FocusTrapFeatures.FocusLock)) return;
-    let allContainers = resolveContainers(containers);
-    if (container instanceof HTMLElement) allContainers.add(container);
-    let relatedTarget = e.relatedTarget;
-    if (!(relatedTarget instanceof HTMLElement)) return;
-    if (relatedTarget.dataset.headlessuiFocusGuard === "true") {
-      return;
-    }
-    if (!contains(allContainers, relatedTarget)) {
-      if (recentlyUsedTabKey) {
-        focusIn(
-          container,
-          match(direction.current, {
-            [TabDirection.Forwards]: () => Focus.Next,
-            [TabDirection.Backwards]: () => Focus.Previous
-          }) | Focus.WrapAround,
-          { relativeTo: e.target }
-        );
-      } else if (e.target instanceof HTMLElement) {
-        focusElement(e.target);
+    },
+    onblur(e: FocusEvent) {
+      if (!(features & FocusTrapFeatures.FocusLock)) return
+
+      let allContainers = resolveContainers(containers)
+      if (container instanceof HTMLElement) allContainers.add(container)
+
+      let relatedTarget = e.relatedTarget
+      if (!(relatedTarget instanceof HTMLElement)) return
+
+      // Known guards, leave them alone!
+      if (relatedTarget.dataset.headlessuiFocusGuard === "true") {
+        return
       }
-    }
-  }
-});
+
+      // Blur is triggered due to focus on relatedTarget, and the relatedTarget is not inside any
+      // of the dialog containers. In other words, let's move focus back in!
+      if (!contains(allContainers, relatedTarget)) {
+        // Was the blur invoked via the keyboard? Redirect to the next in line.
+        if (recentlyUsedTabKey) {
+          focusIn(
+            container as HTMLElement,
+            match(direction.current, {
+              [TabDirection.Forwards]: () => Focus.Next,
+              [TabDirection.Backwards]: () => Focus.Previous,
+            }) | Focus.WrapAround,
+            { relativeTo: e.target as HTMLElement }
+          )
+        }
+
+        // It was invoked via something else (e.g.: click, programmatically, ...). Redirect to the
+        // previous active item in the FocusTrap
+        else if (e.target instanceof HTMLElement) {
+          focusElement(e.target)
+        }
+      }
+    },
+  })
 </script>
 
 {#if tabLockEnabled}