@proyecto-viviana/solidaria 0.3.0 → 0.4.1

package/src/autocomplete/createAutocomplete.ts

@@ -9,7 +9,10 @@
 
 import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
 import { createId, getOwnerDocument } from "../ssr";
-import { type AutocompleteState } from "@proyecto-viviana/solid-stately";
+import { type AutocompleteState, type CollectionNode } from "@proyecto-viviana/solid-stately";
+import { FOCUS_EVENT, CLEAR_FOCUS_EVENT } from "../selection/constants";
+import { getActiveElement, getEventTarget } from "../utils/dom";
+import { getPointerType } from "../interactions";
 
 export interface CollectionOptions {
   /** The id of the collection element. */
@@ -20,6 +23,8 @@ export interface CollectionOptions {
   shouldUseVirtualFocus: boolean;
   /** Whether typeahead is disabled. */
   disallowTypeAhead: boolean;
+  /** Whether and where to focus an item when the collection mounts. */
+  autoFocus?: boolean | "first" | "last";
 }
 
 export interface AutocompleteInputProps {
@@ -49,7 +54,7 @@ export interface AutocompleteInputProps {
   autoComplete: "off";
 }
 
-export interface AriaAutocompleteOptions<_T = unknown> {
+export interface AriaAutocompleteOptions<T = unknown> {
   /** Ref accessor for the input element. */
   inputRef: Accessor<HTMLInputElement | undefined>;
   /** Ref accessor for the collection element. */
@@ -62,8 +67,9 @@ export interface AriaAutocompleteOptions<_T = unknown> {
    * An optional filter function used to determine if an option should be included.
    * @param textValue - The text value of the item
    * @param inputValue - The current input value
+   * @param node - The collection node being filtered
    */
-  filter?: (textValue: string, inputValue: string) => boolean;
+  filter?: (textValue: string, inputValue: string, node: CollectionNode<T>) => boolean;
   /**
    * Whether to focus the first item after filtering.
    * @default false
@@ -76,13 +82,13 @@ export interface AriaAutocompleteOptions<_T = unknown> {
   disableVirtualFocus?: boolean;
 }
 
-export interface AutocompleteAria<_T = unknown> {
+export interface AutocompleteAria<T = unknown> {
   /** Props for the autocomplete input element. */
   inputProps: AutocompleteInputProps;
   /** Props for the collection (ListBox/Menu). */
   collectionProps: CollectionOptions;
   /** A filter function that returns if the item should be shown. */
-  filter?: (textValue: string) => boolean;
+  filter?: (nodeTextValue: string, node: CollectionNode<T>) => boolean;
 }
 
 function toKeyboardEventInit(e: KeyboardEvent): KeyboardEventInit {
@@ -101,9 +107,14 @@ function toKeyboardEventInit(e: KeyboardEvent): KeyboardEventInit {
   };
 }
 
-// Custom event names for collection communication
-export const AUTOCOMPLETE_FOCUS_EVENT = "autocomplete:focus";
-export const AUTOCOMPLETE_CLEAR_FOCUS_EVENT = "autocomplete:clearfocus";
+// Custom event names for collection communication.
+// These are the shared @react-aria/selection constants the collection's
+// createSelectableCollection listens for (FOCUS_EVENT / CLEAR_FOCUS_EVENT);
+// the aliases below are retained for backwards-compatible re-exports.
+/** @deprecated Use {@link FOCUS_EVENT} from the selection layer. */
+export const AUTOCOMPLETE_FOCUS_EVENT = FOCUS_EVENT;
+/** @deprecated Use {@link CLEAR_FOCUS_EVENT} from the selection layer. */
+export const AUTOCOMPLETE_CLEAR_FOCUS_EVENT = CLEAR_FOCUS_EVENT;
 
 /**
  * Provides the behavior and accessibility implementation for an autocomplete component.
@@ -150,46 +161,84 @@ export function createAutocomplete<T = unknown>(
 
   const collectionId = collectionIdProp ?? createId();
   const [shouldUseVirtualFocus] = createSignal(!disableVirtualFocus);
+  // When the first item should be focused but the collection hasn't mounted yet,
+  // defer it by threading autoFocus through collectionProps so the collection
+  // focuses on mount (mirrors upstream's autoFocusOnMount state).
+  const [autoFocusOnMount, setAutoFocusOnMount] = createSignal(false);
   let lastInputType = "";
 
-  // Track the input type for determining focus behavior
-  const handleInput = (e: Event) => {
+  // Reverse-focus (collection → input aria-activedescendant) bookkeeping, mirroring
+  // useAutocomplete's queuedActiveDescendant / delayNextActiveDescendant / timeout
+  // refs. `queuedActiveDescendant` is the id of the option the collection has
+  // virtually focused — tracked synchronously on every collection `focusin`, even
+  // while the visible aria-activedescendant reflection is deferred, so key
+  // navigation always dispatches to the right item. When typing forward,
+  // `delayNextActiveDescendant` defers the next reflection behind a 500ms timeout so
+  // a screen reader finishes announcing the just-typed letter before naming the
+  // active option; every new focusin (and teardown) clears the pending timeout.
+  let queuedActiveDescendant: string | null = null;
+  let delayNextActiveDescendant = false;
+  let activeDescendantTimeout: ReturnType<typeof setTimeout> | undefined;
+  const ACTIVE_DESCENDANT_DELAY = 500;
+
+  // Track the input type for determining focus behavior. We listen to
+  // `beforeinput` (not `input`) so `lastInputType` is set before the input's
+  // `onChange` runs, mirroring @react-aria/autocomplete.
+  const handleBeforeInput = (e: Event) => {
     const inputEvent = e as InputEvent;
     lastInputType = inputEvent.inputType || "";
   };
 
-  // Set up input event listener
+  // Set up beforeinput event listener
   createEffect(() => {
     const input = inputRef();
     if (input) {
-      input.addEventListener("input", handleInput);
+      input.addEventListener("beforeinput", handleBeforeInput);
       onCleanup(() => {
-        input.removeEventListener("input", handleInput);
+        input.removeEventListener("beforeinput", handleBeforeInput);
       });
     }
   });
 
   // Focus first item in collection
   const focusFirstItem = () => {
+    // Typing forward focuses the first filtered row, but the resulting
+    // aria-activedescendant reflection must wait so the SR announces the typed
+    // letter first (see updateActiveDescendant). Mirrors useAutocomplete
+    // setting delayNextActiveDescendant.current = true before the focus event.
+    delayNextActiveDescendant = true;
     const collection = collectionRef();
-    if (collection) {
-      collection.dispatchEvent(
-        new CustomEvent(AUTOCOMPLETE_FOCUS_EVENT, {
-          cancelable: true,
-          bubbles: true,
-          detail: { focusStrategy: "first" },
-        }),
-      );
+    if (!collection) {
+      // Collection isn't mounted yet — defer focusing the first item to mount
+      // time via collectionProps.autoFocus instead of firing a focus event into
+      // a not-yet-rendered collection.
+      setAutoFocusOnMount(true);
+      return;
     }
+    collection.dispatchEvent(
+      new CustomEvent(FOCUS_EVENT, {
+        cancelable: true,
+        bubbles: true,
+        detail: { focusStrategy: "first" },
+      }),
+    );
   };
 
   // Clear virtual focus
   const clearVirtualFocus = (clearFocusKey = false) => {
+    setAutoFocusOnMount(false);
+    // Drop any pending delayed reflection and the tracked item alongside the
+    // active descendant so a subsequent focusin can't resurrect a stale id
+    // (mirrors useAutocomplete clearing queuedActiveDescendant / the timeout /
+    // delayNextActiveDescendant in clearVirtualFocus).
+    clearTimeout(activeDescendantTimeout);
+    queuedActiveDescendant = null;
+    delayNextActiveDescendant = false;
     state.setFocusedNodeId(null);
     const collection = collectionRef();
     if (collection) {
       collection.dispatchEvent(
-        new CustomEvent(AUTOCOMPLETE_CLEAR_FOCUS_EVENT, {
+        new CustomEvent(CLEAR_FOCUS_EVENT, {
           cancelable: true,
           bubbles: true,
           detail: { clearFocusKey },
@@ -200,8 +249,16 @@ export function createAutocomplete<T = unknown>(
 
   // Handle input value changes
   const onChange = (value: string) => {
-    // Focus first item when typing forward, clear when backspacing/pasting
-    if (lastInputType === "insertText" && !disableAutoFocusFirst) {
+    // Focus first item when typing forward, clear when backspacing/pasting.
+    // IME composition (e.g. CJK input) reports 'insertCompositionText'/
+    // 'insertFromComposition' instead of 'insertText'; treat those as forward
+    // typing so the first item still gets virtual focus.
+    if (
+      (lastInputType === "insertText" ||
+        lastInputType === "insertCompositionText" ||
+        lastInputType === "insertFromComposition") &&
+      !disableAutoFocusFirst
+    ) {
       focusFirstItem();
     } else if (
       lastInputType &&
@@ -221,7 +278,13 @@ export function createAutocomplete<T = unknown>(
       return;
     }
 
-    const focusedNodeId = state.focusedNodeId();
+    // Navigate against the id the collection has virtually focused, tracked
+    // synchronously on every focusin, NOT the (possibly still-delayed)
+    // aria-activedescendant reflection in state — mirrors useAutocomplete
+    // reading queuedActiveDescendant.current here. Reading state.focusedNodeId()
+    // would be null during the post-type reflection delay, so arrows would
+    // re-focus the first row instead of advancing.
+    const focusedNodeId = queuedActiveDescendant;
     const collection = collectionRef();
     const ownerDocument = getOwnerDocument(inputRef() ?? collection);
 
@@ -253,7 +316,7 @@ export function createAutocomplete<T = unknown>(
         // Dispatch focus event to collection
         if (collection) {
           collection.dispatchEvent(
-            new CustomEvent(AUTOCOMPLETE_FOCUS_EVENT, {
+            new CustomEvent(FOCUS_EVENT, {
               cancelable: true,
               bubbles: true,
             }),
@@ -264,9 +327,15 @@ export function createAutocomplete<T = unknown>(
 
       case "ArrowLeft":
       case "ArrowRight":
-        // Clear activedescendant so screen reader announces cursor movement
-        clearVirtualFocus();
-        return;
+        // With no virtual focus, just let the arrow move the text cursor; stop
+        // propagation so it doesn't leak into the collection. With virtual focus,
+        // fall through to dispatch the key to the focused item below, then clear
+        // the active descendant only after the item has seen it.
+        if (!focusedNodeId) {
+          e.stopPropagation();
+          return;
+        }
+        break;
 
       case "Enter":
         // Trigger click on focused item
@@ -280,17 +349,36 @@ export function createAutocomplete<T = unknown>(
         return;
     }
 
-    // Forward keyboard events to collection/focused item
-    if (!e.defaultPrevented && collection) {
+    // Forward keyboard events to the focused item (or the collection when there
+    // is no virtual focus) so the collection can act on them, e.g. onAction.
+    // Gated only on the collection existing — NOT on e.defaultPrevented: arrows
+    // call preventDefault above to stop the input's text cursor moving, but the
+    // key must still be re-dispatched to the row so navigation advances (mirrors
+    // useAutocomplete forwarding whenever collectionRef.current !== null).
+    if (collection) {
       e.stopPropagation();
 
+      let shouldPerformDefaultAction = true;
       if (focusedNodeId) {
         const item = ownerDocument?.getElementById(focusedNodeId);
         if (item) {
-          item.dispatchEvent(new KeyboardEvent(e.type, toKeyboardEventInit(e)));
+          shouldPerformDefaultAction = item.dispatchEvent(
+            new KeyboardEvent(e.type, toKeyboardEventInit(e)),
+          );
         }
       } else {
-        collection.dispatchEvent(new KeyboardEvent(e.type, toKeyboardEventInit(e)));
+        shouldPerformDefaultAction = collection.dispatchEvent(
+          new KeyboardEvent(e.type, toKeyboardEventInit(e)),
+        );
+      }
+
+      // After the focused item has seen ArrowLeft/ArrowRight, clear the active
+      // descendant so SR announcements aren't interrupted, but retain the
+      // collection's focused key so navigation restarts where it left off. If
+      // the item consumed the key (e.g. an expandable row collapsing), it
+      // cancels the event and we keep virtual focus.
+      if (shouldPerformDefaultAction && (e.key === "ArrowLeft" || e.key === "ArrowRight")) {
+        clearVirtualFocus();
       }
     }
   };
@@ -314,9 +402,85 @@ export function createAutocomplete<T = unknown>(
     // Virtual focus blur handling would go here
   };
 
-  // Create filter function
+  // Reverse path: mirror the collection's virtually-focused option into the
+  // input's aria-activedescendant. The collection dispatches a synthetic,
+  // bubbling `focusin` (via moveVirtualFocus) on its focused option; we read the
+  // target id, track it in `queuedActiveDescendant` synchronously (so key nav
+  // always dispatches to the right item), and reflect it into AutocompleteState
+  // — immediately, or, when `delayNextActiveDescendant` was set by forward
+  // typing, behind a 500ms timeout so the SR finishes announcing the typed
+  // letter before naming the active option. Faithful port of useAutocomplete's
+  // updateActiveDescendantEvent.
+  const updateActiveDescendant = (e: Event) => {
+    const input = inputRef();
+    // If the user clicks/taps an option directly (non-touch), pull real focus
+    // back to the input so typing keeps working.
+    if (
+      !e.isTrusted &&
+      shouldUseVirtualFocus() &&
+      input &&
+      getActiveElement(getOwnerDocument(input)) !== input &&
+      getPointerType() !== "touch"
+    ) {
+      input.focus();
+    }
+
+    const target = getEventTarget<Element>(e);
+    if (e.isTrusted || !target || queuedActiveDescendant === target.id) {
+      return;
+    }
+
+    const collection = collectionRef();
+    // A new focusin supersedes any pending delayed reflection.
+    clearTimeout(activeDescendantTimeout);
+    if (target !== collection) {
+      const targetId = target.id;
+      if (delayNextActiveDescendant) {
+        // Forward typing just focused the first row: track it now, but defer the
+        // aria-activedescendant reflection so the just-typed letter is announced
+        // before the active option.
+        queuedActiveDescendant = targetId;
+        activeDescendantTimeout = setTimeout(() => {
+          state.setFocusedNodeId(targetId);
+        }, ACTIVE_DESCENDANT_DELAY);
+      } else {
+        queuedActiveDescendant = targetId;
+        state.setFocusedNodeId(targetId);
+      }
+    } else if (
+      queuedActiveDescendant &&
+      !getOwnerDocument(collection)?.getElementById(queuedActiveDescendant)
+    ) {
+      // Refocus of the collection itself while the previously focused node no
+      // longer exists (filtered away, or the input was refocused): clear the
+      // tracked item and the active descendant.
+      queuedActiveDescendant = null;
+      state.setFocusedNodeId(null);
+    }
+    // Reflection delay is a one-shot; the next focusin reflects immediately
+    // unless forward typing sets the flag again.
+    delayNextActiveDescendant = false;
+  };
+
+  createEffect(() => {
+    if (!shouldUseVirtualFocus()) return;
+    const collection = collectionRef();
+    if (collection) {
+      collection.addEventListener("focusin", updateActiveDescendant);
+      onCleanup(() => {
+        collection.removeEventListener("focusin", updateActiveDescendant);
+        clearTimeout(activeDescendantTimeout);
+      });
+    }
+  });
+
+  // Create filter function. The user's 3-arg predicate (textValue, inputValue,
+  // node) is closed over the current input value and exposed to the collection
+  // as the 2-arg (nodeTextValue, node) shape that UNSTABLE_useFilteredListState
+  // (createFilteredListState) expects.
   const filterFn = filter
-    ? (textValue: string) => filter(textValue, state.inputValue())
+    ? (nodeTextValue: string, node: CollectionNode<T>) =>
+        filter(nodeTextValue, state.inputValue(), node)
     : undefined;
 
   return {
@@ -341,6 +505,9 @@ export function createAutocomplete<T = unknown>(
       "aria-label": collectionAriaLabel,
       shouldUseVirtualFocus: shouldUseVirtualFocus(),
       disallowTypeAhead: shouldUseVirtualFocus(),
+      get autoFocus() {
+        return autoFocusOnMount() ? "first" : false;
+      },
     },
     filter: filterFn,
   };

package/src/breadcrumbs/createBreadcrumbs.ts

@@ -84,8 +84,14 @@ export function createBreadcrumbItem(
   const elementType = () => getProps().elementType ?? "a";
 
   // Use createLink for base link behavior
-  // Current items are treated as disabled (can't navigate to current page)
-  const { linkProps, isPressed } = createLink({
+  // Current items are treated as disabled (can't navigate to current page).
+  // Keep the whole return value (do NOT destructure linkProps): `linkProps` is a
+  // reactive getter, and destructuring it here would snapshot getLinkProps() once
+  // at mount — freezing role/tabIndex to whatever elementType was during the
+  // transient first render (e.g. before isCurrent settles). Reading
+  // linkAria.linkProps fresh inside getItemProps keeps it live, mirroring React
+  // re-running useLink every render.
+  const linkAria = createLink({
     get isDisabled() {
       return isDisabled() || isCurrent();
     },
@@ -148,6 +154,8 @@ export function createBreadcrumbItem(
   const getItemProps = (): Record<string, unknown> => {
     const p = getProps();
     const current = isCurrent();
+    // Read fresh each call so elementType-driven role/tabIndex stay reactive.
+    const linkProps = linkAria.linkProps;
 
     // Start with link props, forwarding id if provided
     let baseProps: Record<string, unknown> = p.id ? mergeProps(linkProps, { id: p.id }) : linkProps;
@@ -175,8 +183,8 @@ export function createBreadcrumbItem(
       return getItemProps();
     },
     get linkProps() {
-      return linkProps;
+      return linkAria.linkProps;
     },
-    isPressed,
+    isPressed: linkAria.isPressed,
   };
 }

package/src/button/createToggleButtonGroup.ts

@@ -1,4 +1,5 @@
 import type { JSX } from "solid-js";
+import { splitProps } from "solid-js";
 import type { Key, ToggleGroupProps, ToggleGroupState } from "@proyecto-viviana/solid-stately";
 import { createToolbar, type Orientation } from "../toolbar";
 import { mergeProps } from "../utils";
@@ -75,21 +76,25 @@ export function createToggleButtonGroupItem(
   props: AriaToggleButtonGroupItemProps,
   state: ToggleGroupState,
 ): ToggleButtonAria {
-  const { id: _id, ...toggleProps } = props;
+  // splitProps keeps `toggleProps` a reactive proxy; an object-rest destructure
+  // (`{ id, ...toggleProps }`) eagerly reads and freezes every key. `id` is
+  // dropped here and re-read live via props.id below. guard:idiomatic-solid.
+  const [, toggleProps] = splitProps(props, ["id"]);
 
-  const toggleButton = createToggleButton({
-    ...toggleProps,
-    get isSelected() {
-      return state.selectedKeys.has(props.id);
-    },
-    onChange(isSelected) {
-      state.setSelected(props.id, isSelected);
-      props.onChange?.(isSelected);
-    },
-    get isDisabled() {
-      return isDisabledValue(props.isDisabled) || state.isDisabled;
-    },
-  });
+  const toggleButton = createToggleButton(
+    mergeProps(toggleProps, {
+      get isSelected() {
+        return state.selectedKeys.has(props.id);
+      },
+      onChange(isSelected: boolean) {
+        state.setSelected(props.id, isSelected);
+        props.onChange?.(isSelected);
+      },
+      get isDisabled() {
+        return isDisabledValue(props.isDisabled) || state.isDisabled;
+      },
+    }) as AriaToggleButtonProps,
+  );
 
   const baseButtonProps = toggleButton.buttonProps as Record<string, unknown>;
   const buttonProps: Record<string, unknown> = {

package/src/calendar/createCalendar.ts

@@ -11,6 +11,7 @@ import { access, type MaybeAccessor } from "../utils/reactivity";
 import { mergeProps } from "../utils/mergeProps";
 import type { CalendarState } from "@proyecto-viviana/solid-stately";
 import { formatVisibleRangeDescription, setCalendarHookData } from "./utils";
+import { formatCalendarLabel } from "./intl";
 
 export interface AriaCalendarProps {
   /** An ID for the calendar. */
@@ -88,6 +89,8 @@ export function createCalendar<T extends CalendarState>(
     setCalendarHookData(state, {
       errorMessageId:
         initialProps.errorMessage || initialProps.errorMessageId ? errorMessageId : undefined,
+      ariaLabel: initialProps["aria-label"],
+      ariaLabelledBy: initialProps["aria-labelledby"],
     });
   }
 
@@ -97,14 +100,13 @@ export function createCalendar<T extends CalendarState>(
     const isDisabled = p.isDisabled || state.isDisabled();
 
     return {
-      "aria-label": "Previous month",
+      "aria-label": formatCalendarLabel(state.locale(), "previous"),
       onClick: () => {
         if (!isDisabled) {
           state.focusPreviousPage();
         }
       },
       disabled: isDisabled,
-      tabIndex: -1,
     };
   });
 
@@ -114,14 +116,13 @@ export function createCalendar<T extends CalendarState>(
     const isDisabled = p.isDisabled || state.isDisabled();
 
     return {
-      "aria-label": "Next month",
+      "aria-label": formatCalendarLabel(state.locale(), "next"),
       onClick: () => {
         if (!isDisabled) {
           state.focusNextPage();
         }
       },
       disabled: isDisabled,
-      tabIndex: -1,
     };
   });
 

package/src/calendar/createCalendarCell.ts

@@ -8,13 +8,20 @@
 import { createSignal, createMemo, createEffect, type Accessor } from "solid-js";
 import { access, type MaybeAccessor } from "../utils/reactivity";
 import { focusSafely } from "../utils/focus";
+import { scrollIntoViewport, getScrollParent } from "../utils";
 import { createFocusRing } from "../interactions/createFocusRing";
 import { getInteractionModality } from "../interactions/createInteractionModality";
 import { useLocale } from "../i18n";
 import { mergeProps } from "../utils/mergeProps";
 import type { CalendarState, CalendarDate, DateValue } from "@proyecto-viviana/solid-stately";
-import { isToday as isTodayUtil, DateFormatter, getLocalTimeZone } from "@internationalized/date";
+import {
+  isToday as isTodayUtil,
+  DateFormatter,
+  getLocalTimeZone,
+  isSameDay,
+} from "@internationalized/date";
 import { getCalendarHookData } from "./utils";
+import { formatCalendarLabel } from "./intl";
 
 export interface AriaCalendarCellProps {
   /** The date represented by the cell. */
@@ -74,7 +81,6 @@ export function createCalendarCell<T extends CalendarState>(
 
   // Check states
   const isSelected = createMemo(() => state.isSelected(date()));
-  const isFocused = createMemo(() => state.isCellFocused(date()));
   const isInvalid = createMemo(() => state.isValueInvalid() && isSelected());
   const isDisabled = createMemo(() => {
     return getProps().isDisabled || state.isCellDisabled(date());
@@ -83,6 +89,11 @@ export function createCalendarCell<T extends CalendarState>(
   const isOutsideMonth = createMemo(
     () => getProps().isOutsideMonth ?? state.isOutsideVisibleRange(date()),
   );
+  // Mirror @react-aria/calendar useCalendarCell: `isCellFocused(date) &&
+  // !isOutsideMonth`. isCellFocused is gated on the calendar-level focus flag,
+  // so this drives the focusSafely effect (never on mount) — NOT the roving
+  // tabIndex, which tracks focusedDate directly below.
+  const isFocused = createMemo(() => state.isCellFocused(date()) && !isOutsideMonth());
   const isToday = createMemo(() => isTodayUtil(date(), timeZone));
   const isCellFocusVisible = createMemo(
     () => isFocused() && isRingFocusVisible() && getInteractionModality() !== null,
@@ -145,6 +156,14 @@ export function createCalendarCell<T extends CalendarState>(
     const element = ref?.();
     if (element && isFocused()) {
       focusSafely(element);
+
+      // Scroll into view if navigating with a keyboard, otherwise try not to
+      // shift the view under the user's mouse/finger. If in an overlay,
+      // scrollIntoViewport only scrolls up to the overlay scroll body. Only
+      // scroll if the cell actually got focused.
+      if (getInteractionModality() !== "pointer" && document.activeElement === element) {
+        scrollIntoViewport(element, { containingElement: getScrollParent(element) });
+      }
     }
   });
 
@@ -166,9 +185,16 @@ export function createCalendarCell<T extends CalendarState>(
       day: "numeric",
       calendar: d.calendar.identifier,
     } as Intl.DateTimeFormatOptions);
+    // Mirror @react-aria/calendar useCalendarCell: route the selected/today
+    // suffix through the localized string formatter instead of hardcoding
+    // " selected" (which dropped "Today" and never localized).
     let label = formatter.format(d.toDate(timeZone));
-    if (isSelected()) {
-      label += " selected";
+    if (isToday()) {
+      label = formatCalendarLabel(locale(), isSelected() ? "todayDateSelected" : "todayDate", {
+        date: label,
+      });
+    } else if (isSelected()) {
+      label = formatCalendarLabel(locale(), "dateSelected", { date: label });
     }
     const errorMessageId = getCalendarHookData(state)?.errorMessageId;
 
@@ -176,7 +202,12 @@ export function createCalendarCell<T extends CalendarState>(
       focusProps as Record<string, unknown>,
       {
         role: "button",
-        tabIndex: isFocused() ? 0 : -1,
+        // Roving tabbable cell = the focusedDate cell, ungated by calendar
+        // focus, mirroring @react-aria/calendar useCalendarCell
+        // (`tabIndex = isSameDay(date, state.focusedDate) ? 0 : -1`, undefined
+        // when disabled). Keeps one cell tabbable on mount without stealing
+        // focus, and prunes tabindex from disabled cells like upstream.
+        tabIndex: isDisabled() ? undefined : isSameDay(date(), state.focusedDate()) ? 0 : -1,
         "aria-label": label,
         "aria-disabled": isDisabled() || isUnavailable() || undefined,
         "aria-invalid": isInvalid() || undefined,

package/src/calendar/createCalendarGrid.ts

@@ -9,6 +9,7 @@ import { createMemo } from "solid-js";
 import { DateFormatter, startOfWeek, today } from "@internationalized/date";
 import { access, type MaybeAccessor } from "../utils/reactivity";
 import type { CalendarState, CalendarDate } from "@proyecto-viviana/solid-stately";
+import { formatVisibleRangeDescription, getCalendarHookData } from "./utils";
 
 export interface AriaCalendarGridProps {
   /** The start date of the grid (defaults to start of focused month). */
@@ -142,20 +143,54 @@ export function createCalendarGrid<T extends CalendarState>(
     }
   };
 
+  // Whether more than one date can be selected at once. Mirrors
+  // @react-aria/calendar useCalendarGrid: true for a RangeCalendar (highlightable
+  // range) or a Calendar in multiple-selection mode.
+  const isMultiSelectable = (): boolean => {
+    if ("highlightedRange" in state) {
+      return true;
+    }
+    return (
+      "selectionMode" in state &&
+      typeof state.selectionMode === "function" &&
+      state.selectionMode() === "multiple"
+    );
+  };
+
+  // The grid's accessible name combines the calendar's label with a description
+  // of this grid's visible month/range, mirroring @react-aria/calendar
+  // useCalendarGrid (useVisibleRangeDescription over the grid's own start/end so
+  // multi-month calendars name each grid by its own month).
+  const visibleRangeDescription = createMemo(() => {
+    const gridProps = access(props);
+    const start = gridProps.startDate ?? state.visibleRange().start;
+    const end = gridProps.endDate ?? state.visibleRange().end;
+    return formatVisibleRangeDescription(start, end, state.timeZone, state.locale());
+  });
+
   // Grid props
-  const gridProps = createMemo(() => ({
-    role: "grid",
-    "aria-readonly": state.isReadOnly() || undefined,
-    "aria-disabled": state.isDisabled() || undefined,
-    tabIndex: state.isFocused() ? 0 : -1,
-    onFocus: () => state.setFocused(true),
-    onBlur: () => state.setFocused(false),
-    onKeyDown: handleKeyDown,
-  }));
+  const gridProps = createMemo(() => {
+    const data = getCalendarHookData(state);
+    const gridLabel = [data?.ariaLabel, visibleRangeDescription()].filter(Boolean).join(", ");
+
+    return {
+      role: "grid",
+      "aria-label": gridLabel || undefined,
+      "aria-labelledby": data?.ariaLabelledBy,
+      "aria-readonly": state.isReadOnly() || undefined,
+      "aria-disabled": state.isDisabled() || undefined,
+      "aria-multiselectable": isMultiSelectable() || undefined,
+      onFocus: () => state.setFocused(true),
+      onBlur: () => state.setFocused(false),
+      onKeyDown: handleKeyDown,
+    };
+  });
 
-  // Header props are intentionally empty. Consumers render this on <thead>,
-  // which already has correct table semantics.
-  const headerProps = createMemo(() => ({}));
+  // Column headers are hidden to screen readers to make navigating with a touch
+  // screen reader easier — the day names are already included in each cell's
+  // label, so there's no need to announce them twice. Consumers render this on
+  // <thead>. Mirrors @react-aria/calendar useCalendarGrid headerProps.
+  const headerProps = createMemo(() => ({ "aria-hidden": true }));
 
   return {
     get gridProps() {