@proyecto-viviana/solidaria 0.2.8 → 0.4.0

package/src/calendar/createCalendarCell.ts

@@ -5,14 +5,18 @@
  * Based on @react-aria/calendar useCalendarCell
  */
 
-import { createSignal, createMemo, createEffect } from 'solid-js';
-import { access, type MaybeAccessor } from '../utils/reactivity';
-import type { CalendarState, CalendarDate, DateValue } from '@proyecto-viviana/solid-stately';
-import { isToday as isTodayUtil, DateFormatter, getLocalTimeZone } from '@internationalized/date';
-
-// ============================================
-// TYPES
-// ============================================
+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 { getCalendarHookData } from "./utils";
+import { formatCalendarLabel } from "./intl";
 
 export interface AriaCalendarCellProps {
   /** The date represented by the cell. */
@@ -32,10 +36,14 @@ export interface CalendarCellAria {
   isSelected: boolean;
   /** Whether the cell is focused. */
   isFocused: boolean;
+  /** Whether the cell should display a keyboard focus ring. */
+  isFocusVisible: boolean;
   /** Whether the cell is disabled. */
   isDisabled: boolean;
   /** Whether the cell is unavailable (e.g., booked date). */
   isUnavailable: boolean;
+  /** Whether the cell is part of an invalid selection. */
+  isInvalid: boolean;
   /** Whether the cell is outside the visible month. */
   isOutsideMonth: boolean;
   /** Whether the cell represents today. */
@@ -46,21 +54,22 @@ export interface CalendarCellAria {
   formattedDate: string;
 }
 
-// ============================================
-// IMPLEMENTATION
-// ============================================
-
 /**
  * Provides the behavior and accessibility implementation for a calendar cell.
  */
 export function createCalendarCell<T extends CalendarState>(
   props: MaybeAccessor<AriaCalendarCellProps>,
   state: T,
-  ref?: () => HTMLElement | null
+  ref?: () => HTMLElement | null,
 ): CalendarCellAria {
   const getProps = () => access(props);
   const [isPressed, setIsPressed] = createSignal(false);
+  const { focusProps, isFocusVisible: isRingFocusVisible } = createFocusRing();
   const timeZone = getLocalTimeZone();
+  const inheritedLocale = useLocale();
+  const stateWithLocale = state as T & { locale?: Accessor<string> };
+  const locale = () => stateWithLocale.locale?.() ?? inheritedLocale().locale;
+  let ignoreNextClick = false;
 
   // Get the date from props
   const date = createMemo(() => getProps().date as CalendarDate);
@@ -68,16 +77,32 @@ 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());
   });
   const isUnavailable = createMemo(() => state.isCellUnavailable(date()));
-  const isOutsideMonth = createMemo(() => getProps().isOutsideMonth ?? state.isOutsideVisibleRange(date()));
+  const isOutsideMonth = createMemo(
+    () => getProps().isOutsideMonth ?? state.isOutsideVisibleRange(date()),
+  );
   const isToday = createMemo(() => isTodayUtil(date(), timeZone));
+  const isCellFocusVisible = createMemo(
+    () => isFocused() && isRingFocusVisible() && getInteractionModality() !== null,
+  );
 
   // Format the date for display
   const formattedDate = createMemo(() => {
-    return date().day.toString();
+    const d = date();
+    const formatter = new DateFormatter(locale(), {
+      day: "numeric",
+      timeZone,
+      calendar: d.calendar.identifier,
+    } as Intl.DateTimeFormatOptions);
+
+    return (
+      formatter.formatToParts(d.toDate(timeZone)).find((part) => part.type === "day")?.value ??
+      d.day.toString()
+    );
   });
 
   // Handle pointer down - this is where selection happens
@@ -89,6 +114,7 @@ export function createCalendarCell<T extends CalendarState>(
       // Select the date on pointer down for immediate response
       // This matches React Aria's behavior of using onPressStart
       state.selectDate(date());
+      ignoreNextClick = true;
       // Prevent default to avoid double-triggering with onClick
       e.preventDefault();
     }
@@ -96,6 +122,11 @@ export function createCalendarCell<T extends CalendarState>(
 
   // Handle click - kept for accessibility (keyboard Enter/Space)
   const handleClick = () => {
+    if (ignoreNextClick) {
+      ignoreNextClick = false;
+      return;
+    }
+
     // Only select on click if not already selected via pointerdown
     // This handles keyboard activation (Enter/Space)
     if (!isDisabled() && !isUnavailable()) {
@@ -108,50 +139,82 @@ export function createCalendarCell<T extends CalendarState>(
   };
 
   // Keep DOM focus synchronized with focused date updates.
+  // Use focusSafely (preventScroll) to match @react-aria/calendar — bare focus()
+  // causes the browser to auto-scroll the page when bringing the cell into view,
+  // which is wrong inside a popover. Scroll-into-view should be opt-in based on
+  // interaction modality (handled at a higher layer when needed).
   createEffect(() => {
     const element = ref?.();
     if (element && isFocused()) {
-      element.focus();
+      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) });
+      }
     }
   });
 
   // Cell props (for the td element)
   const cellProps = createMemo(() => ({
-    role: 'gridcell',
-    'aria-disabled': isDisabled() || undefined,
-    'aria-selected': isSelected() || undefined,
+    role: "gridcell",
+    "aria-disabled": isDisabled() || isUnavailable() || undefined,
+    "aria-selected": isSelected() || undefined,
+    "aria-invalid": isInvalid() || undefined,
   }));
 
   // Button props (for the interactive element inside)
   const buttonProps = createMemo(() => {
     const d = date();
-    const formatter = new DateFormatter('en-US', {
-      weekday: 'long',
-      year: 'numeric',
-      month: 'long',
-      day: 'numeric',
-    });
-
-    return {
-      role: 'button',
-      tabIndex: isFocused() ? 0 : -1,
-      'aria-label': formatter.format(d.toDate(timeZone)),
-      'aria-disabled': isDisabled() || undefined,
-      'aria-pressed': isPressed() || undefined,
-      disabled: isDisabled(),
-      onClick: handleClick,
-      onPointerDown: handlePointerDown,
-      onPointerUp: handlePointerUp,
-      onPointerLeave: handlePointerUp,
-      onFocus: () => {
-        // Only update if this cell isn't already the focused date
-        // This prevents infinite loops when focus is programmatically set
-        if (!state.isCellFocused(d)) {
-          state.setFocusedDate(d);
-        }
-        state.setFocused(true);
-      },
-    };
+    const formatter = new DateFormatter(locale(), {
+      weekday: "long",
+      year: "numeric",
+      month: "long",
+      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 (isToday()) {
+      label = formatCalendarLabel(locale(), isSelected() ? "todayDateSelected" : "todayDate", {
+        date: label,
+      });
+    } else if (isSelected()) {
+      label = formatCalendarLabel(locale(), "dateSelected", { date: label });
+    }
+    const errorMessageId = getCalendarHookData(state)?.errorMessageId;
+
+    return mergeProps(
+      focusProps as Record<string, unknown>,
+      {
+        role: "button",
+        tabIndex: isFocused() ? 0 : -1,
+        "aria-label": label,
+        "aria-disabled": isDisabled() || isUnavailable() || undefined,
+        "aria-invalid": isInvalid() || undefined,
+        "aria-describedby": isInvalid() ? errorMessageId : undefined,
+        "aria-pressed": isPressed() || undefined,
+        "data-focus-visible": isCellFocusVisible() || undefined,
+        disabled: isDisabled() || isUnavailable(),
+        onClick: handleClick,
+        onPointerDown: handlePointerDown,
+        onPointerUp: handlePointerUp,
+        onPointerLeave: handlePointerUp,
+        onFocus: () => {
+          // Only update if this cell isn't already the focused date.
+          // This prevents infinite loops when focus is programmatically set.
+          if (!state.isCellFocused(d)) {
+            state.setFocusedDate(d);
+          }
+          state.setFocused(true);
+        },
+      } as Record<string, unknown>,
+    );
   });
 
   return {
@@ -167,12 +230,18 @@ export function createCalendarCell<T extends CalendarState>(
     get isFocused() {
       return isFocused();
     },
+    get isFocusVisible() {
+      return isCellFocusVisible();
+    },
     get isDisabled() {
       return isDisabled();
     },
     get isUnavailable() {
       return isUnavailable();
     },
+    get isInvalid() {
+      return isInvalid();
+    },
     get isOutsideMonth() {
       return isOutsideMonth();
     },

package/src/calendar/createCalendarGrid.ts

@@ -5,13 +5,11 @@
  * Based on @react-aria/calendar useCalendarGrid
  */
 
-import { createMemo } from 'solid-js';
-import { type MaybeAccessor } from '../utils/reactivity';
-import type { CalendarState, CalendarDate } from '@proyecto-viviana/solid-stately';
-
-// ============================================
-// TYPES
-// ============================================
+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). */
@@ -19,7 +17,7 @@ export interface AriaCalendarGridProps {
   /** The end date of the grid (defaults to end of focused month). */
   endDate?: CalendarDate;
   /** The number of weeks to display. */
-  weekdayStyle?: 'narrow' | 'short' | 'long';
+  weekdayStyle?: "narrow" | "short" | "long";
 }
 
 export interface CalendarGridAria {
@@ -31,105 +29,163 @@ export interface CalendarGridAria {
   weekDays: string[];
 }
 
-// ============================================
-// IMPLEMENTATION
-// ============================================
-
 /**
  * Provides the behavior and accessibility implementation for a calendar grid.
  */
 export function createCalendarGrid<T extends CalendarState>(
-  _props: MaybeAccessor<AriaCalendarGridProps>,
+  props: MaybeAccessor<AriaCalendarGridProps>,
   state: T,
-  ref?: () => HTMLElement | null
+  ref?: () => HTMLElement | null,
 ): CalendarGridAria {
   // Week days for headers
-  const weekDays = createMemo(() => state.weekDays());
+  const weekDays = createMemo(() => {
+    const gridProps = access(props);
+    const formatter = new DateFormatter(state.locale(), {
+      weekday: gridProps.weekdayStyle ?? "narrow",
+      timeZone: state.timeZone,
+    });
+    const weekStart = startOfWeek(today(state.timeZone), state.locale(), state.firstDayOfWeek());
+
+    return Array.from({ length: 7 }, (_, index) =>
+      formatter.format(weekStart.add({ days: index }).toDate(state.timeZone)),
+    );
+  });
 
   // Handle keyboard navigation
   const isRTL = (): boolean => {
     const element = ref?.();
-    const scopedDirection = element?.closest('[dir]')?.getAttribute('dir');
-    const documentDirection = typeof document !== 'undefined' ? document.dir : '';
-    return (scopedDirection ?? documentDirection) === 'rtl';
+    const scopedDirection = element?.closest("[dir]")?.getAttribute("dir");
+    const documentDirection = typeof document !== "undefined" ? document.dir : "";
+    return (scopedDirection ?? documentDirection) === "rtl";
   };
 
   const handleKeyDown = (e: KeyboardEvent) => {
     if (state.isDisabled()) return;
 
     switch (e.key) {
-      case 'ArrowLeft':
+      case "ArrowLeft":
         e.preventDefault();
+        e.stopPropagation();
         if (isRTL()) {
           state.focusNextDay();
         } else {
           state.focusPreviousDay();
         }
         break;
-      case 'ArrowRight':
+      case "ArrowRight":
         e.preventDefault();
+        e.stopPropagation();
         if (isRTL()) {
           state.focusPreviousDay();
         } else {
           state.focusNextDay();
         }
         break;
-      case 'ArrowUp':
+      case "ArrowUp":
         e.preventDefault();
+        e.stopPropagation();
         state.focusPreviousWeek();
         break;
-      case 'ArrowDown':
+      case "ArrowDown":
         e.preventDefault();
+        e.stopPropagation();
         state.focusNextWeek();
         break;
-      case 'PageUp':
+      case "PageUp":
         e.preventDefault();
+        e.stopPropagation();
         if (e.shiftKey) {
           state.focusPreviousSection(); // Previous year
         } else {
-          state.focusPreviousPage(); // Previous month
+          state.setFocusedDate(state.focusedDate().subtract({ months: 1 }));
         }
         break;
-      case 'PageDown':
+      case "PageDown":
         e.preventDefault();
+        e.stopPropagation();
         if (e.shiftKey) {
           state.focusNextSection(); // Next year
         } else {
-          state.focusNextPage(); // Next month
+          state.setFocusedDate(state.focusedDate().add({ months: 1 }));
         }
         break;
-      case 'Home':
+      case "Home":
         e.preventDefault();
+        e.stopPropagation();
         state.focusPageStart();
         break;
-      case 'End':
+      case "End":
         e.preventDefault();
+        e.stopPropagation();
         state.focusPageEnd();
         break;
-      case 'Enter':
-      case ' ':
+      case "Enter":
+      case " ":
         e.preventDefault();
         state.selectFocusedDate();
         break;
-      case 'Escape':
-        if ('setAnchorDate' in state && typeof state.setAnchorDate === 'function') {
+      case "Escape":
+        if (
+          "anchorDate" in state &&
+          typeof state.anchorDate === "function" &&
+          state.anchorDate() &&
+          "setAnchorDate" in state &&
+          typeof state.setAnchorDate === "function"
+        ) {
           e.preventDefault();
+          e.stopPropagation();
           state.setAnchorDate(null);
+          if ("setDragging" in state && typeof state.setDragging === "function") {
+            state.setDragging(false);
+          }
         }
         break;
     }
   };
 
+  // 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,
+      tabIndex: state.isFocused() ? 0 : -1,
+      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.

package/src/calendar/createCalendarMonthPicker.ts

@@ -0,0 +1,105 @@
+/**
+ * createCalendarMonthPicker hook for Solidaria
+ *
+ * Provides the behavior and accessibility implementation for a month picker
+ * within a calendar — a listbox/select that jumps the focused date to a chosen
+ * month of the focused year.
+ * Based on @react-aria/calendar useCalendarMonthPicker.
+ */
+
+import { createMemo } from "solid-js";
+import { DateFormatter, type CalendarDate } from "@internationalized/date";
+import type { CalendarState, RangeCalendarState } from "@proyecto-viviana/solid-stately";
+import { access, type MaybeAccessor } from "../utils/reactivity";
+import { useLocale } from "../i18n";
+
+type Key = string | number;
+
+export interface CalendarMonthPickerProps {
+  /** The format of the month to display in the picker. @default 'short' */
+  format?: "numeric" | "2-digit" | "long" | "short" | "narrow";
+}
+
+export interface CalendarMonthPickerItem {
+  /** The 1-based month number, used as the item's key. */
+  id: number;
+  /** The first day of the month. */
+  date: CalendarDate;
+  /** The localized month name. */
+  formatted: string;
+}
+
+export interface CalendarMonthPickerAria {
+  /** An accessible label for the month picker. */
+  "aria-label": string;
+  /** The key of the currently focused month (its 1-based number). */
+  value: Key;
+  /** Handler that moves focus to the selected month. */
+  onChange: (key: Key | null) => void;
+  /** The list of selectable months in the focused year. */
+  items: CalendarMonthPickerItem[];
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a month picker
+ * within a calendar.
+ */
+export function createCalendarMonthPicker(
+  props: MaybeAccessor<CalendarMonthPickerProps>,
+  state: CalendarState | RangeCalendarState,
+): CalendarMonthPickerAria {
+  const getProps = () => access(props);
+  const locale = useLocale();
+
+  const formatter = createMemo(
+    () =>
+      new DateFormatter(locale().locale, {
+        month: getProps().format ?? "short",
+        calendar: state.focusedDate().calendar.identifier,
+        timeZone: state.timeZone,
+      }),
+  );
+
+  // Build the list of months in the focused year. The number of months can vary
+  // by year in some calendar systems (e.g. the Hebrew leap year), so derive it
+  // from the focused date rather than assuming twelve.
+  const items = createMemo<CalendarMonthPickerItem[]>(() => {
+    const focused = state.focusedDate();
+    const fmt = formatter();
+    const numMonths = focused.calendar.getMonthsInYear(focused);
+    const months: CalendarMonthPickerItem[] = [];
+    for (let i = 1; i <= numMonths; i++) {
+      const date = focused.set({ month: i });
+      // Calendars that offset their month numbering (e.g. fiscal calendars)
+      // expose getFormattableMonth to map back to the displayable month.
+      const displayDate = date.calendar.getFormattableMonth?.(date) ?? date;
+      months.push({
+        id: i,
+        date,
+        formatted: fmt.format(displayDate.toDate(state.timeZone)),
+      });
+    }
+    return months;
+  });
+
+  const ariaLabel = createMemo(
+    () => new Intl.DisplayNames(locale().locale, { type: "dateTimeField" }).of("month") ?? "month",
+  );
+
+  return {
+    get "aria-label"() {
+      return ariaLabel();
+    },
+    get value() {
+      return state.focusedDate().month;
+    },
+    onChange: (key) => {
+      if (key != null) {
+        state.setFocusedDate(items()[Number(key) - 1].date);
+      }
+    },
+    get items() {
+      return items();
+    },
+  };
+}