@proyecto-viviana/solidaria 0.3.0 → 0.4.1

package/src/tabs/createTabs.ts

@@ -3,7 +3,7 @@
  * Based on @react-aria/tabs.
  */
 
-import { type Accessor, createEffect, createMemo } from "solid-js";
+import { type Accessor, batch, createEffect, createMemo } from "solid-js";
 import { createFocusRing } from "../interactions";
 import { createPress } from "../interactions";
 import { createHover } from "../interactions";
@@ -54,8 +54,10 @@ export interface TabListAria {
     "aria-labelledby"?: string;
     "aria-describedby"?: string;
     onKeyDown: (e: KeyboardEvent) => void;
-    onFocus: (e: FocusEvent) => void;
-    onBlur: (e: FocusEvent) => void;
+    // React's bubbling onFocus/onBlur map to focusin/focusout in Solid; the
+    // tab list must observe focus entering/leaving its child tabs.
+    onFocusIn: (e: FocusEvent) => void;
+    onFocusOut: (e: FocusEvent) => void;
   };
 }
 
@@ -80,12 +82,14 @@ export interface TabAria {
     "aria-controls": string | undefined;
     "aria-label"?: string;
     "aria-labelledby"?: string;
-    tabIndex: number;
+    tabIndex: number | undefined;
     onKeyDown: (e: KeyboardEvent) => void;
     onMouseDown: (e: MouseEvent) => void;
     onPointerDown: (e: PointerEvent) => void;
     onClick: (e: MouseEvent) => void;
     onFocus: (e: FocusEvent) => void;
+    onFocusIn: (e: FocusEvent) => void;
+    onBlur: (e: FocusEvent) => void;
   };
   /** Whether the tab is selected. */
   isSelected: Accessor<boolean>;
@@ -268,7 +272,25 @@ export function createTabList<T>(props: AriaTabListProps, state: TabListState<T>
 
     if (nextKey !== null) {
       e.preventDefault();
-      state.setFocusedKey(nextKey);
+      // Batch the focus + selection writes so their observable ordering matches
+      // React. `setFocusedKey` drives a reactive effect that moves DOM focus
+      // (firing native focusout/focusin); `setSelectedKey` calls
+      // `onSelectionChange` synchronously. Written bare, Solid flushes the focus
+      // effect the instant `setFocusedKey` runs — so focus moves *before* the
+      // selection callback, inverting React's order. React batches both state
+      // updates in the handler (callback fires synchronously) and defers the
+      // focus move to a layout effect. `batch()` is the Solid equivalent: it
+      // holds the focus effect until the batch closes, so the synchronous
+      // `onSelectionChange` fires first, then focus moves — matching upstream's
+      // `callback → focusout → focusin` sequence (D4 event-sequence oracle).
+      batch(() => {
+        state.setFocusedKey(nextKey);
+        // Selection follows focus only for keyboard navigation in automatic mode
+        // (mirrors useSelectableCollection's selectOnFocus in navigateToKey).
+        if (keyboardActivation() === "automatic") {
+          state.setSelectedKey(nextKey);
+        }
+      });
     }
   };
 
@@ -297,8 +319,8 @@ export function createTabList<T>(props: AriaTabListProps, state: TabListState<T>
       "aria-labelledby": props["aria-labelledby"],
       "aria-describedby": props["aria-describedby"],
       onKeyDown: handleKeyDown,
-      onFocus: handleFocus,
-      onBlur: handleBlur,
+      onFocusIn: handleFocus,
+      onFocusOut: handleBlur,
     },
   };
 }
@@ -319,24 +341,43 @@ export function createTab<T>(
     return state.isKeyDisabled(key());
   });
 
-  const isFocused = createMemo(() => state.focusedKey() === key());
+  // Whether this tab is the roving-focus target (state layer), used for the
+  // roving tabIndex and DOM focus alignment. The returned isFocused is the
+  // DOM-focus-based ring state, matching upstream's useFocusRing semantics.
+  const isKeyFocused = createMemo(() => state.focusedKey() === key());
 
   // Focus ring
-  const { isFocusVisible, focusProps } = createFocusRing();
-
-  // Press handling
+  const { isFocused, isFocusVisible, focusProps } = createFocusRing();
+
+  // Press handling. Selection timing mirrors useSelectableItem's default
+  // (non-shouldSelectOnPressUp) path: mouse selects on press start and
+  // keyboard on key down, while touch, pen, and virtual pointers select on
+  // press up.
+  const selectTab = () => {
+    // Press handlers select only — they do NOT set the focused key. Upstream's
+    // useSelectableItem does the same: its press/onSelect path calls
+    // replaceSelection, while `focusedKey` is driven exclusively by the DOM
+    // `onFocus` handler (see handleFocus below). Setting the focused key here too
+    // flipped the roving tabIndex synchronously at pointer-up — *before* the
+    // browser's native focus reached the tab — so a touch tap logged the tapped
+    // tab with tabIndex 0 at its own `focusin`, where React (which updates
+    // tabIndex only on the post-event commit) still shows -1. Letting native
+    // focus alone advance `focusedKey` defers the tabIndex flip past the focus
+    // event, matching React's D4 event sequence.
+    state.setSelectedKey(key());
+  };
   const { isPressed, pressProps } = createPress({
     get isDisabled() {
       return isDisabled();
     },
-    onPress: () => {
-      const tabKey = key();
-      const wasSelected = state.selectedKey() === tabKey;
-
-      state.setFocusedKey(tabKey);
-
-      if (state.keyboardActivation() === "manual" || wasSelected) {
-        state.setSelectedKey(tabKey);
+    onPressStart: (e) => {
+      if (e.pointerType === "mouse" || e.pointerType === "keyboard") {
+        selectTab();
+      }
+    },
+    onPress: (e) => {
+      if (e.pointerType === "touch" || e.pointerType === "pen" || e.pointerType === "virtual") {
+        selectTab();
       }
     },
   });
@@ -363,12 +404,34 @@ export function createTab<T>(
     }
   };
 
-  // Focus management
+  // Focus management. The focus ring reacts to the native `focus` event, but the
+  // roving-tabindex commit is deliberately bound to `focusin` (see
+  // handleFocusIn) so its DOM reflection lands one event later — matching React,
+  // whose `onFocus` is a `focusin`-delegated listener at the app root.
   const handleFocus = (e: FocusEvent) => {
-    state.setFocusedKey(key());
     callHandler(focusProps.onFocus, e);
   };
 
+  // Roving-tabindex commit (D4 event-ordering). React's `onFocus` is delegated
+  // to a single `focusin` listener at the app root, so the roving tabIndex it
+  // drives reflects one event *after* the native `focus`. Binding the
+  // focusedKey write here (to `focusin`) mirrors that timing: the D4 oracle
+  // records event targets from a document-level capture-phase listener, which
+  // runs before this at-target handler, so a touch tap — whose selection lands
+  // on press-up, after focus — is still observed with tabIndex=-1 at `focusin`,
+  // exactly as React. A mouse press selects on press-start and syncs focusedKey
+  // before focus (createTabListState's selection→focus effect), so its tab
+  // already reads tabIndex=0 at `focusin`, again matching React. Setting it on
+  // the earlier `focus` event flipped the tab a whole event too soon, so touch
+  // taps diverged at `focusin`. See recertification.md D4 event-ordering.
+  const handleFocusIn = () => {
+    state.setFocusedKey(key());
+  };
+
+  const handleBlur = (e: FocusEvent) => {
+    callHandler(focusProps.onBlur, e);
+  };
+
   // Combine all handlers
   const handleKeyDown = (e: KeyboardEvent) => {
     callHandler(pressProps.onKeyDown, e);
@@ -386,10 +449,13 @@ export function createTab<T>(
     callHandler(pressProps.onClick, e);
   };
 
-  // Keep DOM focus aligned with focusedKey updates from keyboard delegate.
+  // Keep DOM focus aligned with focusedKey updates from keyboard navigation.
+  // Only while the tab list itself is focused (mirrors useSelectableItem's
+  // manager.isFocused guard), so programmatic selection changes don't steal
+  // focus from elsewhere in the document.
   createEffect(() => {
     const element = ref?.();
-    if (!isFocused() || !element) return;
+    if (!state.isFocused() || !isKeyFocused() || !element) return;
 
     const activeElement = element.ownerDocument?.activeElement;
     if (activeElement !== element) {
@@ -413,13 +479,18 @@ export function createTab<T>(
       "aria-label": props["aria-label"],
       "aria-labelledby": props["aria-labelledby"],
       get tabIndex() {
-        return isSelected() && !isDisabled() ? 0 : -1;
+        // Roving tabIndex follows the focused key (mirrors useSelectableItem);
+        // disabled tabs get no tabIndex at all (mirrors useTab).
+        if (isDisabled()) return undefined;
+        return isKeyFocused() ? 0 : -1;
       },
       onKeyDown: handleKeyDown,
       onMouseDown: handleMouseDown,
       onPointerDown: handlePointerDown,
       onClick: handleClick,
       onFocus: handleFocus,
+      onFocusIn: handleFocusIn,
+      onBlur: handleBlur,
     },
     isSelected,
     isDisabled,

package/src/tag/createTag.ts

@@ -20,6 +20,8 @@ import type { ListState, Key } from "@proyecto-viviana/solid-stately";
 export interface AriaTagProps {
   /** The unique key for this tag. */
   key: Key;
+  /** The role for the tag root. Components use row semantics inside a grid. */
+  role?: "option" | "row";
   /** Whether the tag is disabled. */
   isDisabled?: boolean;
   /** A text value for the tag used for accessibility. */
@@ -149,9 +151,9 @@ export function createTag<T>(
       return;
     }
 
-    const nextTag = Array.from(tagList.querySelectorAll<HTMLElement>('[role="row"]')).find(
-      (el) => el.getAttribute("data-key") === String(nextKey),
-    );
+    const nextTag = Array.from(
+      tagList.querySelectorAll<HTMLElement>('[role="option"], [role="row"]'),
+    ).find((el) => el.getAttribute("data-key") === String(nextKey));
 
     nextTag?.focus();
   };
@@ -182,13 +184,27 @@ export function createTag<T>(
   const handleKeyDown = (e: KeyboardEvent) => {
     if (isDisabled()) return;
 
+    // A TagGroup is inherently horizontal (useTagGroup passes
+    // `orientation: 'horizontal'` to the ListKeyboardDelegate), so the inline
+    // (Left/Right) axis is the navigation axis and flips under RTL, while the
+    // block (Up/Down) axis stays DOM-ordered. Mirror ListKeyboardDelegate:
+    // getKeyRightOf = rtl ? previous : next; getKeyLeftOf = rtl ? next : previous;
+    // getKeyBelow/Above are never direction-flipped.
+    const isRtl = getData()?.direction === "rtl";
+
     switch (e.key) {
       case "ArrowRight":
+        e.preventDefault();
+        focusKey(isRtl ? getPreviousFocusableKey(key()) : getNextFocusableKey(key()));
+        return;
+      case "ArrowLeft":
+        e.preventDefault();
+        focusKey(isRtl ? getNextFocusableKey(key()) : getPreviousFocusableKey(key()));
+        return;
       case "ArrowDown":
         e.preventDefault();
         focusKey(getNextFocusableKey(key()));
         return;
-      case "ArrowLeft":
       case "ArrowUp":
         e.preventDefault();
         focusKey(getPreviousFocusableKey(key()));
@@ -224,39 +240,14 @@ export function createTag<T>(
     }
   };
 
-  // Compute tabIndex
+  // Compute tabIndex. Mirror useTag (vendored @react-aria/tag/src/useTag.ts):
+  //   tabIndex = (!isDisabled && (isFocused || focusedKey == null)) ? 0 : -1
+  // Every non-disabled row is a tab stop when nothing is focused yet (so native
+  // Shift+Tab from a following element lands on the LAST row); once a key is
+  // focused, only that row keeps tabIndex 0 (roving single tab stop).
   const tabIndex = createMemo(() => {
     if (isDisabled()) return -1;
-
-    if (isFocused()) {
-      return 0;
-    }
-
-    if (state.focusedKey() !== null) {
-      return -1;
-    }
-
-    const collection = state.collection();
-    let defaultTabStop: Key | null = null;
-
-    if (state.selectionMode() !== "none") {
-      for (const item of collection) {
-        if (!state.isDisabled(item.key) && state.isSelected(item.key)) {
-          defaultTabStop = item.key;
-          break;
-        }
-      }
-    }
-
-    if (defaultTabStop == null) {
-      defaultTabStop = getFirstFocusableKey();
-    }
-
-    if (key() === defaultTabStop) {
-      return 0;
-    }
-
-    return -1;
+    return isFocused() || state.focusedKey() == null ? 0 : -1;
   });
 
   // Filter DOM props
@@ -268,6 +259,8 @@ export function createTag<T>(
     return !!data?.onRemove;
   });
 
+  const rootRole = createMemo(() => getProps().role ?? "option");
+
   return {
     get rowProps() {
       return mergeProps(
@@ -276,9 +269,10 @@ export function createTag<T>(
         pressProps as Record<string, unknown>,
         {
           id: rowId,
-          role: "row",
+          role: rootRole(),
           tabIndex: tabIndex(),
           "data-key": String(key()),
+          "aria-label": getProps().textValue,
           "aria-selected": isSelectable() ? isSelected() : undefined,
           "aria-disabled": isDisabled() || undefined,
           onKeyDown: handleKeyDown,

package/src/tag/createTagGroup.ts

@@ -35,6 +35,12 @@ export interface AriaTagGroupProps {
   errorMessage?: string;
   /** Handler that is called when a user removes a tag. */
   onRemove?: (keys: Set<Key>) => void;
+  /**
+   * The layout direction, threaded from `useLocale`. A TagGroup navigates on the
+   * inline axis, so ArrowLeft/ArrowRight flip under RTL (mirrors the direction
+   * the ListKeyboardDelegate receives from useTagGroup).
+   */
+  direction?: "ltr" | "rtl";
 }
 
 export interface TagGroupAria {
@@ -54,6 +60,7 @@ const tagGroupData = new WeakMap<object, TagGroupData>();
 interface TagGroupData {
   id: string;
   onRemove?: (keys: Set<Key>) => void;
+  direction: "ltr" | "rtl";
 }
 
 export function getTagGroupData(state: ListState): TagGroupData | undefined {
@@ -83,6 +90,9 @@ export function createTagGroup<T>(
     get onRemove() {
       return getProps().onRemove;
     },
+    get direction() {
+      return getProps().direction ?? "ltr";
+    },
   };
 
   // Filter DOM props
@@ -133,6 +143,82 @@ export function createTagGroup<T>(
     return ids.length > 0 ? ids.join(" ") : undefined;
   };
 
+  const getRef = () => _ref?.() ?? null;
+
+  // First/last navigable (non-disabled) row keys — the entry targets.
+  const getFirstNavigableKey = (): Key | null => {
+    const collection = state.collection();
+    let candidate = collection.getFirstKey();
+    while (candidate != null && state.isDisabled(candidate)) {
+      candidate = collection.getKeyAfter(candidate);
+    }
+    return candidate;
+  };
+
+  const getLastNavigableKey = (): Key | null => {
+    const collection = state.collection();
+    let candidate = collection.getLastKey();
+    while (candidate != null && state.isDisabled(candidate)) {
+      candidate = collection.getKeyBefore(candidate);
+    }
+    return candidate;
+  };
+
+  // Focus marshalling — the grid container is a trampoline. Its roving tabIndex
+  // is 0 only while `focusedKey == null` (see gridProps below), so a forward Tab
+  // that reaches the standalone container lands on the container itself; move the
+  // focused key onto the first/last row and the post-commit effect below pulls
+  // REAL DOM focus there while the container rolls to tabIndex -1. Mirrors
+  // useSelectableCollection's `onFocus` (via useTagGroup → useGridList). A
+  // Shift+Tab arriving directly on a row is handled by the row's own focusable
+  // onFocus, since every non-disabled row is a tab stop when nothing is focused.
+  const onFocus = (e: FocusEvent) => {
+    state.setFocused(true);
+
+    // `focus` is non-bubbling in Solid, so this fires only when the container
+    // itself receives focus; ignore anything that bubbled from a descendant.
+    const container = e.currentTarget as HTMLElement | null;
+    if (container && e.target && !container.contains(e.target as Node)) return;
+    if (state.focusedKey() != null || getProps().isDisabled) return;
+
+    const relatedTarget = e.relatedTarget as Element | null;
+    // Focus arriving from an element that FOLLOWS the group in document order
+    // means the user shift-tabbed backward into it → enter at the LAST row;
+    // otherwise (forward Tab, or programmatic) enter at the FIRST.
+    const enterKey =
+      relatedTarget &&
+      container &&
+      container.compareDocumentPosition(relatedTarget) & Node.DOCUMENT_POSITION_FOLLOWING
+        ? getLastNavigableKey()
+        : getFirstNavigableKey();
+    if (enterKey != null) {
+      state.setFocusedKey(enterKey);
+    }
+  };
+
+  const onBlur = () => {
+    state.setFocused(false);
+  };
+
+  // Once the roving tabindex for the focused key has committed to the DOM, move
+  // browser focus onto that row (looked up by its stable data-key), mirroring
+  // useSelectableCollection. Only manage focus while it already lives inside the
+  // container — i.e. the user is navigating via the trampoline — so a background
+  // focusedKey change never yanks focus from elsewhere on the page.
+  createEffect(() => {
+    const key = state.focusedKey();
+    const el = getRef();
+    if (!el || key == null) return;
+
+    const active = document.activeElement;
+    if (!active || (active !== el && !el.contains(active))) return;
+
+    const target = el.querySelector<HTMLElement>(`[data-key="${CSS.escape(String(key))}"]`);
+    if (target && target !== active) {
+      target.focus();
+    }
+  });
+
   return {
     get gridProps() {
       const p = getProps();
@@ -146,6 +232,12 @@ export function createTagGroup<T>(
         "aria-relevant": "additions",
         "aria-describedby": getAriaDescribedBy(),
         "aria-disabled": p.isDisabled || undefined,
+        // Roving container tabIndex mirrors useSelectableCollection: the container
+        // is tabbable (0) only while nothing is focused, then rolls to -1 once a
+        // row takes focus so Tab exits the group.
+        tabIndex: p.isDisabled ? undefined : state.focusedKey() != null ? -1 : 0,
+        onFocus,
+        onBlur,
       });
     },
     get labelProps() {

package/src/toast/createToast.ts

@@ -79,6 +79,7 @@ export function createToast<T>(props: AriaToastProps<T>): ToastAria {
     "aria-modal": "false",
     "aria-labelledby": hasTitle ? titleId : undefined,
     "aria-describedby": hasDescription ? descriptionId : undefined,
+    tabIndex: 0,
     "data-animation": props.toast.animation,
     "data-key": props.toast.key,
   }));

package/src/toggle/createToggle.ts

@@ -13,6 +13,7 @@ import { mergeProps } from "../utils/mergeProps";
 import { filterDOMProps } from "../utils/filterDOMProps";
 import { type MaybeAccessor, access } from "../utils/reactivity";
 import { isDevEnv } from "../utils/env";
+import { createSlotId } from "../ssr";
 import { type ToggleState } from "@proyecto-viviana/solid-stately";
 import { type PressEvent } from "../interactions/PressEvent";
 
@@ -84,6 +85,10 @@ export interface ToggleAria {
   labelProps: JSX.LabelHTMLAttributes<HTMLLabelElement>;
   /** Props to be spread on the input element. */
   inputProps: JSX.InputHTMLAttributes<HTMLInputElement>;
+  /** Props for the description element, if any. */
+  descriptionProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the error message element, if any. */
+  errorMessageProps: JSX.HTMLAttributes<HTMLElement>;
   /** Whether the toggle is selected. */
   isSelected: Accessor<boolean>;
   /** Whether the toggle is in a pressed state. */
@@ -233,6 +238,12 @@ export function createToggle(
   // Combined pressed state
   const combinedIsPressed: Accessor<boolean> = () => isPressed() || isLabelPressed();
 
+  // Mint ids for the description and error message slots. Copied from createField
+  // because we don't want the label behavior that provides — the id resolves only
+  // once an element with that id is actually rendered (e.g. via TextContext slots).
+  const descriptionId = createSlotId();
+  const errorMessageId = createSlotId();
+
   return {
     labelProps: mergeProps(labelPressProps, {
       onClick: (e: MouseEvent) => e.preventDefault(),
@@ -244,6 +255,9 @@ export function createToggle(
         "aria-errormessage": p["aria-errormessage"],
         "aria-controls": p["aria-controls"],
         "aria-readonly": isReadOnly() || undefined,
+        "aria-describedby":
+          [descriptionId(), errorMessageId(), p["aria-describedby"]].filter(Boolean).join(" ") ||
+          undefined,
         onChange,
         disabled: isDisabled(),
         ...(p.value == null ? {} : { value: p.value }),
@@ -256,6 +270,12 @@ export function createToggle(
         onClick: (e: MouseEvent) => e.stopPropagation(),
       }) as JSX.InputHTMLAttributes<HTMLInputElement>;
     },
+    get descriptionProps() {
+      return { id: descriptionId() };
+    },
+    get errorMessageProps() {
+      return { id: errorMessageId() };
+    },
     isSelected: state.isSelected,
     isPressed: combinedIsPressed,
     isDisabled: isDisabled(),