@proyecto-viviana/solidaria-components 0.4.0 → 0.5.0

package/src/ListBox.tsx

@@ -11,6 +11,7 @@ import {
   createEffect,
   createMemo,
   createSignal,
+  on,
   onCleanup,
   splitProps,
   useContext,
@@ -22,17 +23,29 @@ import {
   createOption,
   createFocusRing,
   createScrollIntoViewOnFocus,
+  createStringFormatter,
+  createDragSession,
+  getGlobalDraggingCollectionRef,
+  getGlobalDraggingKeys,
+  registerDropItem,
+  dndIntlStrings,
   mergeProps,
+  moveVirtualFocus,
   useLocale,
+  FOCUS_EVENT,
+  CLEAR_FOCUS_EVENT,
   type AriaListBoxProps,
   type AriaOptionProps,
 } from "@proyecto-viviana/solidaria";
 import {
   createListState,
+  createFilteredListState,
   type ListState,
+  type ListFilterFn,
   type Key,
   type DropTarget,
 } from "@proyecto-viviana/solid-stately";
+import { useAutocompleteCollection } from "./Autocomplete";
 import {
   type RenderChildren,
   type ClassNameOrFunction,
@@ -53,7 +66,10 @@ import {
   mergePersistedKeysIntoVirtualRange,
   useDndPersistedKeys,
   useRenderDropIndicator,
+  DropIndicatorContext,
+  type DropIndicatorProps,
 } from "./DragAndDrop";
+import type { ItemDropTarget } from "@proyecto-viviana/solid-stately";
 import {
   CollectionRendererContext,
   Section,
@@ -124,7 +140,7 @@ export interface ListBoxProps<T> extends Omit<AriaListBoxProps, "children">, Slo
   /** Called when the load more sentinel becomes visible. */
   onLoadMore?: () => void | Promise<void>;
   /** Ref for the listbox element. */
-  ref?: RefLike<HTMLUListElement>;
+  ref?: RefLike<HTMLDivElement>;
   /** Drag and drop hooks from `useDragAndDrop`. */
   dragAndDropHooks?: DragAndDropHooks<T>;
   /** Layout hint for styling parity. */
@@ -165,7 +181,7 @@ export interface ListBoxOptionProps<T>
   /** The text value of the option (for typeahead). */
   textValue?: string;
   /** Ref for the option element. */
-  ref?: RefLike<HTMLLIElement>;
+  ref?: RefLike<HTMLDivElement>;
 }
 
 export interface ListBoxLoadMoreItemProps extends SlotProps {
@@ -245,7 +261,7 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
 
   const hasSections = createMemo(() => stateProps.items.some((item) => isCollectionSection(item)));
 
-  const state = createListState<T>({
+  const baseState = createListState<T>({
     get items() {
       return flatItems();
     },
@@ -281,6 +297,21 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
     },
   });
 
+  // When this ListBox is the collection of an Autocomplete, the input and the
+  // collection are separate components bridged by context. The collection's
+  // state is filtered by the input's predicate (mirrors RAC's
+  // UNSTABLE_useFilteredListState), and virtual focus is driven across the
+  // component boundary by synthetic DOM events (see the bridge effects below).
+  // ComboBox/Picker never provide this context, so their createListBox path is
+  // untouched.
+  const autocompleteCtx = useAutocompleteCollection();
+  const state = autocompleteCtx
+    ? createFilteredListState<T>(
+        baseState,
+        () => autocompleteCtx.filter as ListFilterFn<T> | undefined,
+      )
+    : baseState;
+
   const resolveDisabled = (): boolean => {
     const disabled = ariaProps.isDisabled;
     if (typeof disabled === "function") {
@@ -290,9 +321,33 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
   };
 
   const locale = useLocale();
+  // A parent Virtualizer publishes `isVirtualized` through the collection
+  // renderer context; the base ListBox forwards it into createListBox so each
+  // option emits aria-posinset/aria-setsize for the windowed (incomplete) DOM.
+  const parentCollectionRenderer = useCollectionRenderer<unknown>();
   const listBoxAria = createListBox(
     {
       ...ariaProps,
+      get isVirtualized() {
+        return parentCollectionRenderer?.isVirtualized ?? ariaProps.isVirtualized;
+      },
+      // Under Autocomplete, the input owns the collection's id (its
+      // aria-controls target), accessible name, and virtual-focus/type-ahead
+      // config; prefer the bridged values over any locally-passed props.
+      get id() {
+        return autocompleteCtx?.collectionProps.id ?? (ariaProps as { id?: string }).id;
+      },
+      get "aria-label"() {
+        return autocompleteCtx?.collectionProps["aria-label"] ?? ariaProps["aria-label"];
+      },
+      get shouldUseVirtualFocus() {
+        return (
+          autocompleteCtx?.collectionProps.shouldUseVirtualFocus ?? ariaProps.shouldUseVirtualFocus
+        );
+      },
+      get disallowTypeAhead() {
+        return autocompleteCtx?.collectionProps.disallowTypeAhead ?? ariaProps.disallowTypeAhead;
+      },
       get isDisabled() {
         return resolveDisabled();
       },
@@ -353,8 +408,81 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
     ref: () => listRef(),
   });
 
+  // Autocomplete bridge. createListBox reimplements navigation inline (it does
+  // not route through createSelectableCollection), so the virtual-focus event
+  // wiring the Autocomplete input relies on lives here, gated on the bridge
+  // context. This mirrors createSelectableCollection's FOCUS_EVENT/CLEAR_FOCUS_EVENT
+  // handlers and useSelectableItem's per-item moveVirtualFocus, at the component
+  // layer, without touching the shared hooks (protecting ComboBox/Picker).
+  if (autocompleteCtx) {
+    // Forward path: the input dispatches FOCUS_EVENT/CLEAR_FOCUS_EVENT onto the
+    // collection element. FOCUS_EVENT marks the collection focused (and, when the
+    // user types forward, requests the first item); the actual arrow navigation
+    // arrives as a re-dispatched KeyboardEvent handled by createListBox's onKeyDown.
+    let shouldVirtualFocusFirst = false;
+    createEffect(() => {
+      const list = listRef();
+      if (!list) return;
+      const onFocusEvent = (e: Event) => {
+        const detail = (e as CustomEvent).detail;
+        e.stopPropagation();
+        state.setFocused(true);
+        if (detail?.focusStrategy === "first") {
+          shouldVirtualFocusFirst = true;
+        }
+      };
+      const onClearFocusEvent = (e: Event) => {
+        e.stopPropagation();
+        state.setFocused(false);
+        if ((e as CustomEvent).detail?.clearFocusKey) {
+          state.setFocusedKey(null);
+        }
+      };
+      list.addEventListener(FOCUS_EVENT, onFocusEvent);
+      list.addEventListener(CLEAR_FOCUS_EVENT, onClearFocusEvent);
+      onCleanup(() => {
+        list.removeEventListener(FOCUS_EVENT, onFocusEvent);
+        list.removeEventListener(CLEAR_FOCUS_EVENT, onClearFocusEvent);
+      });
+    });
+
+    // Focus the first item once the (filtered) collection settles after the user
+    // types forward. If nothing survives the filter, clear the input's active
+    // descendant by moving virtual focus onto the collection itself (its focusin
+    // reaches the input's clear branch). Mirrors useSelectableCollection.
+    createEffect(
+      on(
+        () => [state.collection().getFirstKey?.() ?? null, state.collection().size] as const,
+        ([firstKey, size]) => {
+          if (!shouldVirtualFocusFirst) return;
+          if (firstKey == null) {
+            const list = listRef();
+            if (list) moveVirtualFocus(list);
+            if (size > 0) shouldVirtualFocusFirst = false;
+          } else {
+            state.setFocusedKey(firstKey);
+            shouldVirtualFocusFirst = false;
+          }
+        },
+        { defer: true },
+      ),
+    );
+
+    // Reverse path: mirror the focused key onto the option's DOM element via a
+    // synthetic, bubbling focusin (moveVirtualFocus). The input's focusin listener
+    // reads target.id into its aria-activedescendant. Option ids are String(key)
+    // in this path (createOption). Real DOM focus stays on the input.
+    createEffect(() => {
+      const key = state.focusedKey();
+      const list = listRef();
+      if (!list || !state.isFocused()) return;
+      if (key == null) return;
+      const el = list.ownerDocument.getElementById(String(key));
+      if (el) moveVirtualFocus(el);
+    });
+  }
+
   const isEmpty = () => stateProps.items.length === 0;
-  const parentCollectionRenderer = useCollectionRenderer<unknown>();
   const getItemNodes = createMemo(() =>
     Array.from(state.collection()).filter((node) => node.type === "item"),
   );
@@ -432,6 +560,14 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
           getKeyPageBelow: (key) => state.collection().getKeyAfter(key),
           getKeyPageAbove: (key) => state.collection().getKeyBefore(key),
         },
+        // The real collection drives keyboard drop-target navigation
+        // (`navigate()` walks getKeyAfter/getKeyBefore) and post-drop focus
+        // restoration. Reading it here re-registers the drop target when the
+        // collection changes (mirrors upstream keying its effect on the state).
+        collection: state.collection(),
+        selectedKeys: state.selectionManager.selectedKeys,
+        setSelectedKeys: (keys) => state.selectionManager.setSelectedKeys(keys),
+        setFocusedKey: (key) => state.setFocusedKey(key),
       },
       activeDropState,
       () => listRef(),
@@ -448,6 +584,165 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
     if (!target || target.type !== "item") return undefined;
     return dndRenderDropIndicator()?.(target);
   };
+
+  // ── Drop indicator (Fix B: labeled, self-focusing) ─────────────────────────
+  // The port of react-aria-components' ListBoxDropIndicatorWrapper +
+  // useDropIndicator. The droppable-collection state layer diverged to a minimal
+  // reactive target-holder with no collection reference, so the label (which
+  // needs the collection's text values) and the self-focus (which needs the live
+  // drag session) are computed here in the host layer, where both are available.
+  const dndFormatter = createStringFormatter(dndIntlStrings);
+  const dragSession = createDragSession();
+  const dropIndicatorTargetsEqual = (
+    a: DropTarget | null | undefined,
+    b: ItemDropTarget,
+  ): boolean =>
+    !!a && a.type === "item" && a.key === b.key && a.dropPosition === b.dropPosition;
+  // Faithful port of useDropIndicator's label logic: "Drop on X" for an on-item
+  // target, else "Insert between X and Y" / "Insert before X" / "Insert after X"
+  // resolved from the target's neighbours in the collection.
+  const dropIndicatorLabel = (target: ItemDropTarget): string => {
+    const collection = state.collection();
+    const getText = (key: Key | null): string => {
+      if (key == null) return "";
+      return collection.getTextValue(key) ?? collection.getItem(key)?.textValue ?? "";
+    };
+    if (target.dropPosition === "on") {
+      return dndFormatter().format("dropOnItem", { itemText: getText(target.key) });
+    }
+    let before: Key | null;
+    let after: Key | null;
+    if (target.dropPosition === "before") {
+      const prevKey = collection.getKeyBefore(target.key);
+      const prevNode = prevKey != null ? collection.getItem(prevKey) : null;
+      before = prevNode?.type === "item" ? prevNode.key : null;
+    } else {
+      before = target.key;
+    }
+    if (target.dropPosition === "after") {
+      const nextKey = collection.getKeyAfter(target.key);
+      const nextNode = nextKey != null ? collection.getItem(nextKey) : null;
+      after = nextNode?.type === "item" ? nextNode.key : null;
+    } else {
+      after = target.key;
+    }
+    if (before != null && after != null) {
+      return dndFormatter().format("insertBetween", {
+        beforeItemText: getText(before),
+        afterItemText: getText(after),
+      });
+    }
+    if (before != null) {
+      return dndFormatter().format("insertAfter", { itemText: getText(before) });
+    }
+    if (after != null) {
+      return dndFormatter().format("insertBefore", { itemText: getText(after) });
+    }
+    return "";
+  };
+  // Wrap the raw Set<string> the DragManager hands drop items into the DragTypes
+  // delegate the port state expects (mirrors createDroppableCollection.wrapTypes).
+  const wrapDropTypes = (types: Set<string>) => ({
+    has: (type: string | string[]) => {
+      if (typeof type === "string") return types.has(type);
+      if (Array.isArray(type)) return type.some((t) => typeof t === "string" && types.has(t));
+      return false;
+    },
+  });
+  const ListBoxDropIndicator = (props: { target: ItemDropTarget }): JSX.Element => {
+    const [indicatorRef, setIndicatorRef] = createSignal<HTMLDivElement | null>(null);
+    const isDropTarget = createMemo(() =>
+      dropIndicatorTargetsEqual(dropState()?.target, props.target),
+    );
+    // aria-hidden mirrors useDropIndicator: outside a drag session, or on a
+    // non-active target, the indicator is hidden from AT ('true'); the active
+    // target during a session is exposed (undefined). isHidden then tells us
+    // whether to omit the element entirely (RAC returns null when hidden).
+    const ariaHidden = createMemo(() =>
+      !dragSession() ? "true" : isDropTarget() ? undefined : "true",
+    );
+    const isHidden = createMemo(() => !isDropTarget() && !!ariaHidden());
+    // Faithful port of useDroppableItem. Registration (of the indicator element as
+    // a DragManager droppable item) and the self-focus must happen in one effect,
+    // registration first: the DragManager's onFocus keys off the dropItems map, so
+    // if the element self-focused before it was registered, onFocus would treat it
+    // as an unknown target and redirect focus back to the collection (a pickup
+    // bounce). React's two useDroppableItem effects run in guaranteed order after
+    // the ref is attached; Solid's independent effects race, so we fuse them. The
+    // dropItems map keys off live elements — the ref nulls itself on Show cleanup
+    // (below), so a hidden indicator unregisters instead of lingering as a stale
+    // detached entry.
+    createEffect(() => {
+      const el = indicatorRef();
+      if (!el) return;
+      const unregister = registerDropItem({
+        element: el,
+        target: props.target,
+        getDropOperation: (types, allowedOperations) => {
+          const st = dropState();
+          if (!st) return "cancel";
+          // Thread the same drag identity the collection uses (see
+          // createDroppableCollection.isInternalDropOperation): an internal
+          // keyboard reorder must report `isInternal` so the state's feature
+          // detection keeps before/after indicators valid (and rejects "on" for a
+          // reorder-only host). Without it every indicator would return "cancel"
+          // and drop out of the DragManager's ariaHideOutside keep-set.
+          const isInternal = getGlobalDraggingCollectionRef() === listRef();
+          return st.getDropOperation(
+            props.target,
+            wrapDropTypes(types) as Parameters<typeof st.getDropOperation>[1],
+            allowedOperations,
+            isInternal,
+            getGlobalDraggingKeys(),
+          );
+        },
+      });
+      onCleanup(unregister);
+      // While a drag session is active, the current drop target moves real DOM
+      // focus onto itself, so keyboard drop navigation lands on the labeled
+      // insertion point rather than the collection element. The self-focus is
+      // deferred to an animation frame to mirror upstream's timing: in
+      // useDroppableItem the focus is a *passive* useEffect, so it commits only
+      // after the browser's microtask checkpoint. That ordering matters because
+      // the DragManager keeps the active drop indicator visible via
+      // ariaHideOutside, whose keep-set is `[dragSource, ...registered drop
+      // items]` (the collection is dropped from the set once it owns items). A
+      // freshly-mounted indicator is momentarily `inert` — it only leaves the
+      // keep-set's blind spot once the DragManager's MutationObserver re-runs
+      // updateValidDropTargets on a later microtask. Focusing synchronously (or
+      // on a microtask) would call .focus() while the element is still inert and
+      // silently no-op; the animation frame runs after that refresh, exactly as
+      // React's passive effect does.
+      if (dragSession() && isDropTarget()) {
+        requestAnimationFrame(() => {
+          if (dragSession() && isDropTarget() && indicatorRef() === el) {
+            el.focus();
+          }
+        });
+      }
+    });
+    return (
+      <Show when={!isHidden()}>
+        <div
+          ref={(el) => {
+            setIndicatorRef(el);
+            onCleanup(() => setIndicatorRef(null));
+          }}
+          role="option"
+          class="solidaria-DropIndicator"
+          aria-roledescription={dndFormatter().format("dropIndicator")}
+          aria-label={dropIndicatorLabel(props.target)}
+          aria-hidden={ariaHidden()}
+          tabindex={-1}
+          data-drop-target={isDropTarget() || undefined}
+        />
+      </Show>
+    );
+  };
+  const dropIndicatorContextValue = {
+    render: (p: DropIndicatorProps) => <ListBoxDropIndicator target={p.target} />,
+  };
+
   const virtualizer = useVirtualizerContext();
   const persistedKeys = useDndPersistedKeys(
     { focusedKey: state.focusedKey },
@@ -565,11 +860,12 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
     >
       <ListBoxStateContext.Provider value={state}>
         <CollectionRendererContext.Provider value={collectionRenderer()}>
+         <DropIndicatorContext.Provider value={dropIndicatorContextValue}>
           <>
             <Show when={ariaProps.label}>
               <span {...cleanLabelProps()}>{ariaProps.label as JSX.Element}</span>
             </Show>
-            <ul
+            <div
               {...mergeProps(
                 domProps(),
                 cleanListBoxProps(),
@@ -580,6 +876,7 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
               ref={(el) => {
                 setListRef(el);
                 assignRef(local.ref, el);
+                autocompleteCtx?.collectionRef(el);
               }}
               class={renderProps.class()}
               style={renderProps.style()}
@@ -594,14 +891,14 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
             >
               <SharedElementTransition>
                 {isEmpty() && local.renderEmptyState ? (
-                  <li role="option" style={{ display: "contents" }} data-empty-state>
+                  <div role="option" style={{ display: "contents" }} data-empty-state>
                     {local.renderEmptyState()}
-                  </li>
+                  </div>
                 ) : hasSections() ? (
                   <For each={sectionedRenderEntries()}>
                     {(entry) =>
                       entry.type === "section" ? (
-                        <li role="presentation" data-section-wrapper>
+                        <div role="presentation" data-section-wrapper>
                           <Section class="solidaria-ListBox-section">
                             {entry.section.title != null && (
                               <Header class="solidaria-ListBox-sectionHeader">
@@ -609,7 +906,7 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
                               </Header>
                             )}
                             <Group class="solidaria-ListBox-sectionGroup">
-                              <ul role="group" aria-label={entry.section["aria-label"]}>
+                              <div role="group" aria-label={entry.section["aria-label"]}>
                                 <For each={entry.items}>
                                   {(indexedItem) => (
                                     <>
@@ -629,10 +926,10 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
                                     </>
                                   )}
                                 </For>
-                              </ul>
+                              </div>
                             </Group>
                           </Section>
-                        </li>
+                        </div>
                       ) : (
                         <>
                           {collectionRenderer().renderDropIndicator?.(entry.item.index, "before")}
@@ -646,7 +943,7 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
                 ) : (
                   <>
                     {virtualRange()?.offsetTop ? (
-                      <li
+                      <div
                         role="presentation"
                         aria-hidden="true"
                         style={virtualSpacerStyle(virtualRange()!.offsetTop)}
@@ -673,7 +970,7 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
                       }}
                     </For>
                     {virtualRange()?.offsetBottom ? (
-                      <li
+                      <div
                         role="presentation"
                         aria-hidden="true"
                         style={virtualSpacerStyle(virtualRange()!.offsetBottom)}
@@ -686,8 +983,9 @@ export function ListBox<T>(props: ListBoxProps<T>): JSX.Element {
               {local.hasMore && local.onLoadMore && (
                 <ListBoxLoadMoreItem onLoadMore={local.onLoadMore} isLoading={local.isLoading} />
               )}
-            </ul>
+            </div>
           </>
+         </DropIndicatorContext.Provider>
         </CollectionRendererContext.Provider>
       </ListBoxStateContext.Provider>
     </ListBoxContext.Provider>
@@ -714,7 +1012,7 @@ export function ListBoxOption<T>(props: ListBoxOptionProps<T>): JSX.Element {
   }
   const state = context as ListState<T>;
   const listContext = useContext(ListBoxContext) as ListBoxContextValue<T> | null;
-  const [ref, setRef] = createSignal<HTMLLIElement | null>(null);
+  const [ref, setRef] = createSignal<HTMLDivElement | null>(null);
 
   const optionAria = createOption<T>(
     {
@@ -742,6 +1040,7 @@ export function ListBoxOption<T>(props: ListBoxOptionProps<T>): JSX.Element {
       },
     },
     state,
+    ref,
   );
 
   const renderValues = createMemo<ListBoxOptionRenderProps>(() => ({
@@ -777,6 +1076,9 @@ export function ListBoxOption<T>(props: ListBoxOptionProps<T>): JSX.Element {
     return listContext.dragAndDropHooks.useDraggableItem(
       {
         key: local.id as string | number,
+        // Surfaces the drag-affordance description (aria-describedby) only for
+        // selectable collections, mirroring upstream useDraggableItem.
+        selectionMode: state.selectionManager.selectionMode,
       },
       listContext.dragState as Parameters<NonNullable<DragAndDropHooks<T>["useDraggableItem"]>>[1],
     );
@@ -808,7 +1110,7 @@ export function ListBoxOption<T>(props: ListBoxOptionProps<T>): JSX.Element {
 
   return (
     <SelectionIndicatorContext.Provider value={selectionIndicatorContext()}>
-      <li
+      <div
         ref={(el) => {
           setRef(el);
           assignRef(local.ref, el);
@@ -836,7 +1138,7 @@ export function ListBoxOption<T>(props: ListBoxOptionProps<T>): JSX.Element {
         ) : (
           renderProps.renderChildren()
         )}
-      </li>
+      </div>
     </SelectionIndicatorContext.Provider>
   );
 }
@@ -892,10 +1194,10 @@ export function ListBoxLoadMoreItem(props: ListBoxLoadMoreItemProps): JSX.Elemen
 
   return (
     <>
-      <li style={{ position: "relative", width: 0, height: 0, overflow: "hidden" }} inert>
+      <div style={{ position: "relative", width: 0, height: 0, overflow: "hidden" }} inert>
         <div ref={sentinelRef} style={{ position: "absolute", height: "1px", width: "1px" }} />
-      </li>
-      <li
+      </div>
+      <div
         role="option"
         aria-disabled={true}
         tabIndex={0}
@@ -907,7 +1209,7 @@ export function ListBoxLoadMoreItem(props: ListBoxLoadMoreItemProps): JSX.Elemen
         data-loading={isLoading() || undefined}
       >
         {renderProps.renderChildren()}
-      </li>
+      </div>
     </>
   );
 }

package/src/Modal.tsx

@@ -264,9 +264,14 @@ export function ModalOverlay(props: ModalOverlayProps): JSX.Element {
       }
     };
 
-    document.addEventListener("keydown", handleKeyDown, true);
+    // Bubble phase, mirroring react-aria's `useOverlay` (its `onKeyDown` is an
+    // overlay-element prop, handled on bubble). Capture would preempt inner
+    // widgets that dismiss on Escape (a combobox/menu inside the dialog must
+    // consume Escape first) and would also fire before the event is recorded by
+    // capture-phase listeners, inverting the keydown/onOpenChange order.
+    document.addEventListener("keydown", handleKeyDown, false);
     onCleanup(() => {
-      document.removeEventListener("keydown", handleKeyDown, true);
+      document.removeEventListener("keydown", handleKeyDown, false);
     });
   });
 
@@ -487,9 +492,11 @@ function ModalContent(props: ModalProps): JSX.Element {
       }
     };
 
-    document.addEventListener("keydown", handleKeyDown, true);
+    // Bubble phase — see the ModalOverlay handler above for why (react-aria
+    // `useOverlay` parity; inner-widget Escape precedence; event-order fidelity).
+    document.addEventListener("keydown", handleKeyDown, false);
     onCleanup(() => {
-      document.removeEventListener("keydown", handleKeyDown, true);
+      document.removeEventListener("keydown", handleKeyDown, false);
     });
   });
 
@@ -548,7 +555,16 @@ function ModalContent(props: ModalProps): JSX.Element {
     // No autoFocus: react-aria's Overlay renders FocusScope with restoreFocus +
     // contain only — initial focus is useDialog's job (it focuses the dialog
     // element itself when nothing inside holds focus).
-    <FocusScope contain restoreFocus>
+    //
+    // `contain` is gated on `!isExiting`, mirroring react-aria's Overlay
+    // (react-aria/src/overlays/Overlay.tsx: `contain={... && !isExiting}`). The
+    // overlay stays mounted through its exit transition (isOpen || isExiting), so
+    // without this gate containment would remain active during the exit and yank
+    // focus back into the dialog as restoreFocus moves it to the trigger —
+    // producing a focus bounce (focusout→focusin→focusout) that React never
+    // shows. Releasing containment the instant the exit begins lets focus settle
+    // on the trigger in a single move, matching upstream's event sequence.
+    <FocusScope contain={!isModalExiting()} restoreFocus>
       <div
         {...domProps()}
         ref={registerModalRef}

package/src/Popover.tsx

@@ -22,6 +22,7 @@ import {
   createOverlayTrigger,
   createPopover,
   FocusScope,
+  useLocale,
   useUNSAFE_PortalContext,
   visuallyHiddenStyles,
   type AriaLabelingProps,
@@ -280,12 +281,29 @@ export function Popover(props: PopoverProps): JSX.Element {
     "isExiting",
   ]);
 
-  let popoverRef!: HTMLDivElement;
+  // A reactive ref (not a plain `let`) so the overlay-position effect in
+  // createOverlayPosition — which tracks `overlayRef()` as a dependency —
+  // re-runs once the portal node actually mounts. React gets this timing for
+  // free from useLayoutEffect (the ref is populated before the position effect
+  // fires); in Solid the portal node is created lazily on open, AFTER the
+  // position effect first ran with a null ref, so a non-reactive ref left the
+  // popover stranded at the createOverlayPosition fallback (position:fixed;
+  // top:0; left:0) whenever no other dependency happened to re-fire the effect
+  // after mount. Mirrors the sibling groupRef signal below.
+  const [popoverRef, setPopoverRef] = createSignal<HTMLDivElement | null>(null);
   const [groupRef, setGroupRef] = createSignal<HTMLDivElement | null>(null);
   // False on the server and during hydration; true after onMount. Gates the Portal
   // so overlay content only ever renders client-side, post-hydration.
   const isHydrated = useIsHydrated();
 
+  // Mirrors upstream S2 Popover (Popover.mjs: `el.lang = locale; el.dir =
+  // direction`): the overlay portals out of the app root, so it must carry both
+  // the locale `lang` AND writing `direction` — otherwise the portaled
+  // listbox/dialog stays LTR and keeps the Latin font under an RTL Provider (the
+  // `:lang(ar)` font swap needs a `lang` ancestor the portal would otherwise
+  // escape). RAC's own Popover only threads `dir`; S2 adds `lang` on top.
+  const locale = useLocale();
+
   const triggerContext = useContext(PopoverTriggerContext);
   const dialogTriggerContext = useContext(DialogTriggerContext);
   const popoverGroupContext = useContext(PopoverGroupContext);
@@ -333,7 +351,7 @@ export function Popover(props: PopoverProps): JSX.Element {
   const popoverAria = createPopover(
     {
       triggerRef: getTriggerRef,
-      popoverRef: () => popoverRef ?? null,
+      popoverRef: () => popoverRef(),
       groupRef: () => (isSubPopover() ? (popoverGroupContext?.() ?? null) : groupRef()),
       get placement() {
         return local.placement;
@@ -514,7 +532,7 @@ export function Popover(props: PopoverProps): JSX.Element {
   createEffect(() => {
     if (!isOpen() || !shouldBeDialog()) return;
     if ((local.autoFocus ?? true) === false) return;
-    if (!popoverRef) return;
+    if (!popoverRef()) return;
     if (resolvedTrigger() === "SubmenuTrigger") return;
 
     let timeout: number | undefined;
@@ -522,11 +540,12 @@ export function Popover(props: PopoverProps): JSX.Element {
 
     const focusIfNeeded = () => {
       if (!isOpen() || !shouldBeDialog()) return;
-      if (!popoverRef || resolvedTrigger() === "SubmenuTrigger") return;
-      if (document.activeElement === popoverRef || popoverRef.contains(document.activeElement)) {
+      const node = popoverRef();
+      if (!node || resolvedTrigger() === "SubmenuTrigger") return;
+      if (document.activeElement === node || node.contains(document.activeElement)) {
         return;
       }
-      popoverRef.focus();
+      node.focus();
     };
 
     const scheduleFocus = () => {
@@ -572,12 +591,14 @@ export function Popover(props: PopoverProps): JSX.Element {
         <div
           {...domProps()}
           {...cleanPopoverProps()}
-          ref={popoverRef}
+          ref={setPopoverRef}
           id={overlayId()}
           role={shouldBeDialog() ? "dialog" : undefined}
           tabIndex={shouldBeDialog() ? -1 : undefined}
           class={renderProps.class()}
           style={mergedStyle()}
+          lang={locale().locale}
+          dir={locale().direction}
           data-trigger={resolvedTrigger()}
           data-placement={popoverAria.placement()}
           data-entering={dataAttr(local.isEntering)}