@proyecto-viviana/solidaria 0.3.0 → 0.4.1

package/src/listbox/createListBox.ts

@@ -42,6 +42,17 @@ export interface AriaListBoxProps {
   shouldSelectOnPressUp?: boolean;
   /** Whether to focus items on hover. */
   shouldFocusOnHover?: boolean;
+  /** Whether the listbox uses virtual scrolling. */
+  isVirtualized?: boolean;
+  /** Whether options should use virtual focus instead of receiving DOM focus. */
+  shouldUseVirtualFocus?: boolean;
+  /** The behavior of links in the collection. */
+  linkBehavior?: "action" | "selection" | "override" | "none";
+  /**
+   * Unstable upstream override that forces items with actions to prefer
+   * selection or action behavior.
+   */
+  UNSTABLE_itemBehavior?: "selection" | "action";
   /**
    * Whether keyboard focus movement should also update selection in single selection mode.
    * @default true
@@ -49,6 +60,28 @@ export interface AriaListBoxProps {
   shouldSelectOnFocus?: boolean;
   /** Whether type-to-select is disabled. @default false */
   disallowTypeAhead?: boolean;
+  /**
+   * The primary orientation of the items. In a horizontal listbox the Left/Right
+   * arrows navigate the list (the block-axis Up/Down arrows still work); in a
+   * vertical listbox Left/Right are no-ops, matching upstream's
+   * `ListKeyboardDelegate` for a `stack` layout.
+   * @default "vertical"
+   */
+  orientation?: "vertical" | "horizontal";
+  /**
+   * The text direction, used to resolve the horizontal navigation axis. In a
+   * horizontal listbox, RTL flips Left/Right (Right=previous, Left=next).
+   * @default "ltr"
+   */
+  direction?: "ltr" | "rtl";
+  /**
+   * Whether pressing the Escape key should clear selection in the listbox or not.
+   * Most experiences should not modify this option as it eliminates a keyboard
+   * user's ability to easily clear selection. Only use if the escape key is being
+   * handled externally or should not trigger selection clearing contextually.
+   * @default "clearSelection"
+   */
+  escapeKeyBehavior?: "clearSelection" | "none";
 }
 
 export interface ListBoxAria {
@@ -66,13 +99,28 @@ interface ListBoxData {
   onAction?: (key: Key) => void;
   shouldSelectOnPressUp?: boolean;
   shouldFocusOnHover?: boolean;
+  isVirtualized?: boolean;
+  shouldUseVirtualFocus?: boolean;
   isDisabled?: boolean;
+  linkBehavior?: "action" | "selection" | "override" | "none";
+  UNSTABLE_itemBehavior?: "selection" | "action";
 }
 
 export function getListBoxData(state: ListState): ListBoxData | undefined {
   return listBoxData.get(state);
 }
 
+/**
+ * Whether a key should be skipped during keyboard navigation. Disabled keys only
+ * block navigation under `disabledBehavior: "all"` (the default); under
+ * `"selection"` they stay focusable (selection is still blocked elsewhere).
+ * Mirrors `ListKeyboardDelegate.isDisabled` in React Aria, which gates the skip
+ * on the resolved `disabledBehavior` from the selection manager.
+ */
+function isNavigationDisabled<T>(state: ListState<T>, key: Key): boolean {
+  return state.isDisabled(key) && state.disabledBehavior() === "all";
+}
+
 function findNextEnabledKey<T>(
   state: ListState<T>,
   currentKey: Key | null,
@@ -88,13 +136,13 @@ function findNextEnabledKey<T>(
     direction === "next" ? () => collection.getFirstKey() : () => collection.getLastKey();
 
   let key = currentKey != null ? getAdjacentKey(currentKey) : getBoundaryKey();
-  while (key != null && state.isDisabled(key)) {
+  while (key != null && isNavigationDisabled(state, key)) {
     key = getAdjacentKey(key);
   }
 
   if (key == null && wrap) {
     key = getBoundaryKey();
-    while (key != null && state.isDisabled(key)) {
+    while (key != null && isNavigationDisabled(state, key)) {
       key = getAdjacentKey(key);
     }
   }
@@ -130,12 +178,22 @@ export function createListBox<T>(
 
   const updateSharedData = () => {
     const p = getProps();
+    const selectionBehavior = state.selectionBehavior();
+    let linkBehavior = p.linkBehavior ?? (selectionBehavior === "replace" ? "action" : "override");
+    if (selectionBehavior === "toggle" && linkBehavior === "action") {
+      linkBehavior = "override";
+    }
+
     listBoxData.set(state, {
       id,
       onAction: p.onAction,
       shouldSelectOnPressUp: p.shouldSelectOnPressUp,
       shouldFocusOnHover: p.shouldFocusOnHover,
+      isVirtualized: p.isVirtualized,
+      shouldUseVirtualFocus: p.shouldUseVirtualFocus,
       isDisabled: p.isDisabled,
+      linkBehavior,
+      UNSTABLE_itemBehavior: p.UNSTABLE_itemBehavior,
     });
   };
 
@@ -157,7 +215,10 @@ export function createListBox<T>(
     onBlurWithin: (e) => getProps().onBlur?.(e),
     onFocusWithinChange: (isFocused) => {
       getProps().onFocusChange?.(isFocused);
-      state.setFocused(isFocused);
+      // Collection focus lives on the selection manager (upstream tracks it in
+      // useSelectableCollection); the ListState-level setFocused may be a
+      // widget-level focus state (e.g. Select's trigger focus).
+      state.selectionManager.setFocused(isFocused);
     },
   });
 
@@ -189,6 +250,57 @@ export function createListBox<T>(
     },
   });
 
+  // Focus marshalling — the container is a trampoline. When a standalone
+  // listbox receives DOM focus with nothing focused yet (e.g. Tab lands on the
+  // container, whose roving tabIndex is 0 only while `focusedKey == null`), move
+  // the focused key to the first/last option; `createSelectableItem`'s focus
+  // effect then pulls REAL DOM focus onto that option and the container rolls to
+  // tabIndex -1. This mirrors `useSelectableCollection`'s `onFocus`
+  // (useSelectableCollection.ts:409-454) and is why upstream never needs
+  // `aria-activedescendant` on a standalone listbox — real focus IS the AT
+  // channel. Skipped under `shouldUseVirtualFocus` (ComboBox/Autocomplete keep
+  // DOM focus on the input and drive an activedescendant via the virtual-focus
+  // channel instead).
+  //
+  // NOTE on the guard: unlike upstream (whose selectable `onFocus` sets
+  // `manager.setFocused(true)` itself and guards on `manager.isFocused`), our
+  // `createFocusWithin` already flips `setFocused(true)` via `onFocusWithinChange`
+  // — and mergeProps chains it BEFORE this handler — so `manager.isFocused` is
+  // already true here. Guard on `focusedKey() == null` instead (only marshal when
+  // no option is focused yet). `onFocus` is non-bubbling in Solid, so this fires
+  // only when the container element itself receives focus, not on child focus.
+  const onListBoxFocus: JSX.EventHandler<HTMLElement, FocusEvent> = (e) => {
+    const p = getProps();
+    if (p.isDisabled || p.shouldUseVirtualFocus) return;
+    // Ignore focus events that bubbled through a portal.
+    if (!e.currentTarget.contains(e.target as Node)) return;
+    if (state.focusedKey() != null) return;
+
+    const manager = state.selectionManager;
+    const selectOnFocus = state.selectionBehavior() === "replace";
+    const navigateToKey = (key: Key | null | undefined) => {
+      if (key == null) return;
+      state.setFocusedKey(key);
+      if (selectOnFocus && !manager.isSelected(key)) {
+        state.replaceSelection(key);
+      }
+    };
+
+    const collection = state.collection();
+    const relatedTarget = e.relatedTarget as Element | null;
+    // Detect tab direction: if focus came from an element that FOLLOWS the
+    // listbox in the document, the user is shift-tabbing backward into it, so
+    // enter at the last item; otherwise enter at the first.
+    if (
+      relatedTarget &&
+      e.currentTarget.compareDocumentPosition(relatedTarget) & Node.DOCUMENT_POSITION_FOLLOWING
+    ) {
+      navigateToKey(manager.lastSelectedKey ?? collection.getLastKey());
+    } else {
+      navigateToKey(manager.firstSelectedKey ?? collection.getFirstKey());
+    }
+  };
+
   // Keyboard navigation
   const onKeyDown: JSX.EventHandler<HTMLElement, KeyboardEvent> = (e) => {
     const p = getProps();
@@ -200,9 +312,13 @@ export function createListBox<T>(
 
     switch (e.key) {
       case "ArrowDown": {
-        e.preventDefault();
+        // Only consume the key once a target exists. Mirrors
+        // useSelectableCollection (ArrowDown, 211-225): preventDefault is called
+        // inside `if (nextKey != null)`, so at the last item without wrap the
+        // arrow is left alone to bubble (e.g. to scroll an enclosing region).
         const nextKey = findNextEnabledKey(state, state.focusedKey(), "next", shouldWrap);
         if (nextKey != null) {
+          e.preventDefault();
           state.setFocusedKey(nextKey);
           if (shouldSelectOnFocus && !e.shiftKey && state.selectionMode() === "single") {
             state.replaceSelection(nextKey);
@@ -213,9 +329,9 @@ export function createListBox<T>(
         break;
       }
       case "ArrowUp": {
-        e.preventDefault();
         const prevKey = findNextEnabledKey(state, state.focusedKey(), "prev", shouldWrap);
         if (prevKey != null) {
+          e.preventDefault();
           state.setFocusedKey(prevKey);
           if (shouldSelectOnFocus && !e.shiftKey && state.selectionMode() === "single") {
             state.replaceSelection(prevKey);
@@ -225,7 +341,41 @@ export function createListBox<T>(
         }
         break;
       }
+      case "ArrowRight":
+      case "ArrowLeft": {
+        // Horizontal orientation promotes the inline axis to the primary
+        // navigation axis. Upstream's ListKeyboardDelegate strips
+        // getKeyLeftOf/getKeyRightOf for a vertical stack, so Left/Right stay
+        // no-ops there; in a horizontal stack they move prev/next, flipped
+        // under RTL (Right=next, Left=prev in LTR).
+        if (p.orientation !== "horizontal") break;
+        const isRtl = p.direction === "rtl";
+        const forward = e.key === "ArrowRight" ? !isRtl : isRtl;
+        const focusedKey = state.focusedKey();
+        // With nothing focused, both directions enter at the first item,
+        // mirroring upstream's getFirstKey() fallback for Left and Right.
+        const nextKey =
+          focusedKey != null
+            ? findNextEnabledKey(state, focusedKey, forward ? "next" : "prev", shouldWrap)
+            : findNextEnabledKey(state, null, "next", false);
+        // As with the block axis, only swallow the key when it moves focus
+        // (useSelectableCollection ArrowLeft/Right, 243-280).
+        if (nextKey != null) {
+          e.preventDefault();
+          state.setFocusedKey(nextKey);
+          if (shouldSelectOnFocus && !e.shiftKey && state.selectionMode() === "single") {
+            state.replaceSelection(nextKey);
+          } else if (e.shiftKey && state.selectionMode() === "multiple") {
+            state.extendSelection(nextKey, collection);
+          }
+        }
+        break;
+      }
       case "Home": {
+        // Mirror useSelectableCollection (Home, 283-285): with nothing focused,
+        // Shift+Home has no anchor to extend a selection from, so leave the
+        // event alone (no focus move, no preventDefault).
+        if (state.focusedKey() == null && e.shiftKey) break;
         e.preventDefault();
         const firstKey = findNextEnabledKey(state, null, "next", false);
         if (firstKey != null) {
@@ -240,6 +390,8 @@ export function createListBox<T>(
         break;
       }
       case "End": {
+        // Mirror useSelectableCollection (End, 300-302): same anchor guard as Home.
+        if (state.focusedKey() == null && e.shiftKey) break;
         e.preventDefault();
         const lastKey = findNextEnabledKey(state, null, "prev", false);
         if (lastKey != null) {
@@ -255,9 +407,18 @@ export function createListBox<T>(
       }
       case " ":
       case "Enter": {
+        if (e.target !== e.currentTarget) {
+          break;
+        }
+
         e.preventDefault();
         const focusedKey = state.focusedKey();
-        if (focusedKey != null && !state.isDisabled(focusedKey)) {
+        // Activation is gated on the navigation-disabled check, not the raw
+        // one: under disabledBehavior "selection" a focusable disabled option
+        // still fires onAction, mirroring useSelectableItem's allowsActions
+        // (manager.isDisabled is gated on "all"). Selection stays blocked —
+        // toggleSelection self-guards on the raw disabled check.
+        if (focusedKey != null && !isNavigationDisabled(state, focusedKey)) {
           if (state.selectionMode() !== "none") {
             state.toggleSelection(focusedKey);
           }
@@ -273,8 +434,19 @@ export function createListBox<T>(
         break;
       }
       case "Escape": {
-        e.preventDefault();
-        if (!state.disallowEmptySelection()) {
+        // Mirror useSelectableCollection (Escape, 352-362): only clear the
+        // selection — and swallow the event — when escapeKeyBehavior is
+        // 'clearSelection', there is actually a selection to clear, and empty
+        // selection is allowed. With escapeKeyBehavior 'none', or otherwise,
+        // leave Escape alone so an enclosing overlay (popover, dialog, combobox)
+        // can handle it.
+        if (
+          (p.escapeKeyBehavior ?? "clearSelection") === "clearSelection" &&
+          !state.disallowEmptySelection() &&
+          !state.isEmpty()
+        ) {
+          e.stopPropagation();
+          e.preventDefault();
           state.clearSelection();
         }
         break;
@@ -289,6 +461,26 @@ export function createListBox<T>(
     get listBoxProps() {
       const p = getProps();
       const selectionMode = state.selectionMode();
+      const virtualFocus = p.shouldUseVirtualFocus ?? false;
+      const focusedKey = state.focusedKey();
+
+      // Roving container tabIndex mirrors `useSelectableCollection`
+      // (useSelectableCollection.ts:581-582): with real option focus, the
+      // container is tabbable (0) only while nothing is focused, then rolls to
+      // -1 once focus lands on an option so Tab exits the widget. Under virtual
+      // focus (ComboBox/Autocomplete) the container is NOT a tab stop at all —
+      // upstream leaves `tabIndex` undefined, so the popover listbox never
+      // appears in the roving trail. `aria-activedescendant` is the
+      // virtual-focus AT channel and is emitted ONLY on that path — a standalone
+      // listbox announces the active option through real DOM focus, so upstream
+      // never sets it there.
+      const tabIndex = p.isDisabled
+        ? undefined
+        : virtualFocus
+          ? undefined
+          : focusedKey != null
+            ? -1
+            : 0;
 
       const baseProps = mergeProps(
         domProps(),
@@ -296,12 +488,13 @@ export function createListBox<T>(
         fieldProps as Record<string, unknown>,
         {
           role: "listbox",
-          tabIndex: p.isDisabled ? undefined : 0,
+          tabIndex,
           "aria-disabled": p.isDisabled || undefined,
           "aria-multiselectable": selectionMode === "multiple" ? true : undefined,
           "aria-activedescendant":
-            state.focusedKey() != null ? String(state.focusedKey()) : undefined,
+            virtualFocus && focusedKey != null ? String(focusedKey) : undefined,
           onKeyDown,
+          onFocus: onListBoxFocus,
         },
       );
 

package/src/listbox/createOption.ts

@@ -4,13 +4,13 @@
  */
 
 import { type JSX, type Accessor } from "solid-js";
-import { createPress } from "../interactions/createPress";
 import { createHover, type HoverEvents } from "../interactions/createHover";
 import { createFocusRing } from "../interactions/createFocusRing";
 import { mergeProps } from "../utils/mergeProps";
 import { access, type MaybeAccessor } from "../utils/reactivity";
 import { getListBoxData } from "./createListBox";
-import type { ListState, Key } from "@proyecto-viviana/solid-stately";
+import { getItemCount, type ListState, type Key } from "@proyecto-viviana/solid-stately";
+import { createSelectableItem, type SelectableItemState } from "../selection/createSelectableItem";
 
 export interface AriaOptionProps {
   /** The unique key for the option. */
@@ -27,6 +27,8 @@ export interface AriaOptionProps {
   shouldFocusOnHover?: boolean;
   /** Whether the option should use virtual focus instead of receiving DOM focus. */
   shouldUseVirtualFocus?: boolean;
+  /** Whether the option is contained in a virtual scrolling listbox. */
+  isVirtualized?: boolean;
   /** Whether press-up may occur without the press starting on this option. */
   allowsDifferentPressOrigin?: boolean;
   /** Handler called when hover starts. */
@@ -58,6 +60,10 @@ export interface OptionAria {
   isHovered: Accessor<boolean>;
   /** Whether the option is disabled. */
   isDisabled: Accessor<boolean>;
+  /** Whether the option may be selected. */
+  allowsSelection: Accessor<boolean>;
+  /** Whether the option has an action. */
+  hasAction: Accessor<boolean>;
 }
 
 /**
@@ -72,81 +78,70 @@ export function createOption<T>(
 
   const getData = () => getListBoxData(state);
 
-  const isDisabled: Accessor<boolean> = () => {
-    return Boolean(
-      getData()?.isDisabled || getProps().isDisabled || state.isDisabled(getProps().key),
-    );
+  const shouldSelectOnPressUp = () => {
+    return getProps().shouldSelectOnPressUp ?? getData()?.shouldSelectOnPressUp;
   };
 
-  const isSelected: Accessor<boolean> = () => {
-    return state.isSelected(getProps().key);
+  const shouldFocusOnHover = () => {
+    return getProps().shouldFocusOnHover ?? getData()?.shouldFocusOnHover ?? false;
   };
 
-  const isFocused: Accessor<boolean> = () => {
-    return state.focusedKey() === getProps().key;
+  const shouldUseVirtualFocus = () => {
+    return getProps().shouldUseVirtualFocus ?? getData()?.shouldUseVirtualFocus ?? false;
   };
 
-  const shouldSelectOnPressUp = () => {
-    return getProps().shouldSelectOnPressUp ?? getData()?.shouldSelectOnPressUp ?? true;
-  };
-
-  const shouldUseVirtualFocus = () => {
-    return getProps().shouldUseVirtualFocus ?? false;
+  const isVirtualized = () => {
+    return getProps().isVirtualized ?? getData()?.isVirtualized ?? false;
   };
 
   const allowsDifferentPressOrigin = () => {
-    return getProps().allowsDifferentPressOrigin ?? false;
+    return (
+      getProps().allowsDifferentPressOrigin ??
+      Boolean(shouldSelectOnPressUp() && shouldFocusOnHover())
+    );
   };
 
-  const selectAndAction = () => {
-    const key = getProps().key;
-    if (state.selectionMode() !== "none") {
-      state.select(key);
-    }
-    getProps().onAction?.();
-    getData()?.onAction?.(key);
+  const isDisabledProp = () => {
+    return Boolean(getData()?.isDisabled || getProps().isDisabled);
   };
 
-  const { pressProps, isPressed } = createPress({
-    get isDisabled() {
-      return isDisabled();
-    },
-    get preventFocusOnPress() {
-      return shouldUseVirtualFocus();
-    },
-    onPressStart(e) {
-      if (!shouldSelectOnPressUp() && e.pointerType !== "keyboard" && e.pointerType !== "virtual") {
-        selectAndAction();
-      }
-    },
-    onPressUp(e) {
-      if (shouldSelectOnPressUp() && allowsDifferentPressOrigin() && e.pointerType === "mouse") {
-        selectAndAction();
-      }
-    },
-    onPress(e) {
-      if (
-        (shouldSelectOnPressUp() && !allowsDifferentPressOrigin()) ||
-        (shouldSelectOnPressUp() &&
-          allowsDifferentPressOrigin() &&
-          e.pointerType !== "keyboard" &&
-          e.pointerType !== "mouse") ||
-        e.pointerType === "keyboard" ||
-        e.pointerType === "virtual"
-      ) {
-        selectAndAction();
-      }
+  const optionId = () => getProps().optionId ?? String(getProps().key);
+
+  const selectableItem = createSelectableItem<T>(
+    () => {
+      const key = getProps().key;
+      const hasAction = getProps().onAction != null || getData()?.onAction != null;
+
+      return {
+        key,
+        id: optionId(),
+        isDisabled: isDisabledProp(),
+        shouldSelectOnPressUp: shouldSelectOnPressUp(),
+        allowsDifferentPressOrigin: allowsDifferentPressOrigin(),
+        isVirtualized: isVirtualized(),
+        shouldUseVirtualFocus: shouldUseVirtualFocus(),
+        onAction: hasAction
+          ? () => {
+              getProps().onAction?.();
+              getData()?.onAction?.(key);
+            }
+          : undefined,
+        linkBehavior: getData()?.linkBehavior,
+        UNSTABLE_itemBehavior: getData()?.UNSTABLE_itemBehavior,
+      };
     },
-  });
+    state as SelectableItemState<T>,
+    () => _ref?.() ?? null,
+  );
 
   const { hoverProps, isHovered } = createHover({
     get isDisabled() {
-      return isDisabled();
+      return selectableItem.isDisabled();
     },
     onHoverStart(e) {
-      const shouldFocus = getProps().shouldFocusOnHover ?? getData()?.shouldFocusOnHover;
-      if (shouldFocus) {
-        state.setFocusedKey(getProps().key);
+      if (shouldFocusOnHover() && !isFocusVisible()) {
+        state.selectionManager.setFocused(true);
+        state.selectionManager.setFocusedKey(getProps().key);
       }
       getProps().onHoverStart?.(e);
     },
@@ -169,25 +164,38 @@ export function createOption<T>(
       const selectionMode = state.selectionMode();
       const ariaLabel = getProps()["aria-label"];
 
+      // When the listbox is virtualized the DOM only holds the windowed rows, so
+      // (mirroring @react-aria/listbox useOption) publish the item's absolute
+      // position in the full collection for assistive tech. Only under
+      // virtualization — an un-windowed listbox exposes every row and the browser
+      // derives posinset/setsize itself.
+      let ariaPosInSet: number | undefined;
+      let ariaSetSize: number | undefined;
+      if (isVirtualized()) {
+        const index = Number(state.collection().getItem(key)?.index);
+        ariaPosInSet = Number.isNaN(index) ? undefined : index + 1;
+        ariaSetSize = getItemCount(state.collection());
+      }
+
       return mergeProps(
-        pressProps as Record<string, unknown>,
+        selectableItem.itemProps as Record<string, unknown>,
         hoverProps as Record<string, unknown>,
         focusProps as Record<string, unknown>,
         {
           role: "option",
-          id: getProps().optionId ?? String(key),
-          "data-key": String(key),
-          "aria-selected": selectionMode !== "none" ? isSelected() : undefined,
-          "aria-disabled": isDisabled() || undefined,
+          id: optionId(),
+          "aria-selected": selectionMode !== "none" ? selectableItem.isSelected() : undefined,
+          "aria-disabled": selectableItem.isDisabled() || undefined,
           "aria-label": ariaLabel,
           "aria-labelledby": !ariaLabel ? labelId : undefined,
           "aria-describedby": descriptionId,
-          tabIndex: shouldUseVirtualFocus() ? undefined : isFocused() ? 0 : -1,
-          "data-selected": isSelected() || undefined,
-          "data-focused": isFocused() || undefined,
-          "data-focus-visible": isFocusVisible() || undefined,
-          "data-pressed": isPressed() || undefined,
-          "data-disabled": isDisabled() || undefined,
+          "aria-posinset": ariaPosInSet,
+          "aria-setsize": ariaSetSize,
+          "data-selected": selectableItem.isSelected() || undefined,
+          "data-focused": selectableItem.isFocused() || undefined,
+          "data-focus-visible": (selectableItem.isFocused() && isFocusVisible()) || undefined,
+          "data-pressed": selectableItem.isPressed() || undefined,
+          "data-disabled": selectableItem.isDisabled() || undefined,
           "data-hovered": isHovered() || undefined,
         } as Record<string, unknown>,
       ) as JSX.HTMLAttributes<HTMLElement>;
@@ -198,11 +206,13 @@ export function createOption<T>(
     descriptionProps: {
       id: descriptionId,
     },
-    isSelected,
-    isFocused,
-    isFocusVisible: () => isFocused() && isFocusVisible(),
-    isPressed,
+    isSelected: selectableItem.isSelected,
+    isFocused: selectableItem.isFocused,
+    isFocusVisible: () => selectableItem.isFocused() && isFocusVisible(),
+    isPressed: selectableItem.isPressed,
     isHovered,
-    isDisabled,
+    isDisabled: selectableItem.isDisabled,
+    allowsSelection: selectableItem.allowsSelection,
+    hasAction: selectableItem.hasAction,
   };
 }