@proyecto-viviana/solidaria 0.2.8 → 0.4.0

package/src/calendar/createCalendarYearPicker.ts

@@ -0,0 +1,144 @@
+/**
+ * createCalendarYearPicker hook for Solidaria
+ *
+ * Provides the behavior and accessibility implementation for a year picker
+ * within a calendar — a listbox/select that jumps the focused date to a chosen
+ * year within a sliding window centered on the focused year.
+ * Based on @react-aria/calendar useCalendarYearPicker.
+ */
+
+import { createMemo } from "solid-js";
+import {
+  DateFormatter,
+  isSameYear,
+  toCalendarDate,
+  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 CalendarYearPickerFormatOptions {
+  /** The format of the year. @default 'numeric' */
+  year?: "numeric" | "2-digit";
+  /** The format of the era. */
+  era?: "long" | "short" | "narrow";
+}
+
+export interface CalendarYearPickerProps {
+  /** The number of years to display in the picker. @default 20 */
+  visibleYears?: number;
+  /** The format of the year/era to display. */
+  format?: CalendarYearPickerFormatOptions;
+}
+
+export interface CalendarYearPickerItem {
+  /** The index of the year within the visible window, used as the item's key. */
+  id: number;
+  /** The first day of the year. */
+  date: CalendarDate;
+  /** The localized year name. */
+  formatted: string;
+}
+
+export interface CalendarYearPickerAria {
+  /** An accessible label for the year picker. */
+  "aria-label": string;
+  /** The key of the currently focused year (its index in the visible window). */
+  value: Key;
+  /** Handler that moves focus to the selected year. */
+  onChange: (key: Key | null) => void;
+  /** The list of selectable years in the visible window. */
+  items: CalendarYearPickerItem[];
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a year picker
+ * within a calendar.
+ */
+export function createCalendarYearPicker(
+  props: MaybeAccessor<CalendarYearPickerProps>,
+  state: CalendarState | RangeCalendarState,
+): CalendarYearPickerAria {
+  const getProps = () => access(props);
+  const locale = useLocale();
+
+  const formatter = createMemo(() => {
+    const focused = state.focusedDate();
+    const format = getProps().format;
+    return new DateFormatter(locale().locale, {
+      year: format?.year ?? "numeric",
+      era:
+        format?.era ??
+        (focused.calendar.identifier === "gregory" && focused.era === "BC" ? "short" : undefined),
+      calendar: focused.calendar.identifier,
+      timeZone: state.timeZone,
+    });
+  });
+
+  // Compute a window of years centered on the focused year, then clamp it to the
+  // calendar's min/max so the picker never offers an out-of-range year.
+  const data = createMemo(() => {
+    const focused = state.focusedDate();
+    const fmt = formatter();
+    // Falsy coercion (not `??`) mirrors upstream `props.visibleYears || 20`, so a
+    // `0`/`NaN` visibleYears falls back to the default 20 rather than producing an
+    // empty window.
+    const visibleYears = getProps().visibleYears || 20;
+    let minDate = focused.subtract({ years: Math.floor(visibleYears / 2) });
+    let maxDate = focused.add({ years: Math.ceil(visibleYears / 2) - 1 });
+
+    const stateMax = state.maxValue();
+    const stateMin = state.minValue();
+    if (stateMax && maxDate.compare(stateMax) > 0) {
+      maxDate = toCalendarDate(stateMax);
+      minDate = maxDate.subtract({ years: visibleYears - 1 });
+    }
+    if (stateMin && minDate.compare(stateMin) < 0) {
+      minDate = toCalendarDate(stateMin);
+      maxDate = minDate.add({ years: visibleYears - 1 });
+      if (stateMax && maxDate.compare(stateMax) > 0) {
+        maxDate = toCalendarDate(stateMax);
+      }
+    }
+
+    const years: CalendarYearPickerItem[] = [];
+    let value: number = 0;
+    let date = minDate;
+    while (date.compare(maxDate) <= 0) {
+      if (isSameYear(date, focused)) {
+        value = years.length;
+      }
+      years.push({
+        id: years.length,
+        date,
+        formatted: fmt.format(date.toDate(state.timeZone)),
+      });
+      date = date.add({ years: 1 });
+    }
+    return { items: years, value };
+  });
+
+  const ariaLabel = createMemo(
+    () => new Intl.DisplayNames(locale().locale, { type: "dateTimeField" }).of("year") ?? "year",
+  );
+
+  return {
+    get "aria-label"() {
+      return ariaLabel();
+    },
+    get value() {
+      return data().value;
+    },
+    onChange: (key) => {
+      if (key != null) {
+        state.setFocusedDate(data().items[Number(key)].date);
+      }
+    },
+    get items() {
+      return data().items;
+    },
+  };
+}

package/src/calendar/createRangeCalendar.ts

@@ -5,15 +5,17 @@
  * Based on @react-aria/calendar useRangeCalendar
  */
 
-import { createMemo } from 'solid-js';
-import { createId } from '../ssr';
-import { access, type MaybeAccessor } from '../utils/reactivity';
-import { mergeProps } from '../utils/mergeProps';
-import type { RangeCalendarState } from '@proyecto-viviana/solid-stately';
-
-// ============================================
-// TYPES
-// ============================================
+import { createMemo } from "solid-js";
+import { createId } from "../ssr";
+import { access, type MaybeAccessor } from "../utils/reactivity";
+import { mergeProps } from "../utils/mergeProps";
+import type { RangeCalendarState } from "@proyecto-viviana/solid-stately";
+import {
+  formatSelectedDateDescription,
+  formatVisibleRangeDescription,
+  getCalendarHookData,
+  setCalendarHookData,
+} from "./utils";
 
 export interface AriaRangeCalendarProps {
   /** An ID for the calendar. */
@@ -23,11 +25,19 @@ export interface AriaRangeCalendarProps {
   /** Whether the calendar is read-only. */
   isReadOnly?: boolean;
   /** An accessible label for the calendar. */
-  'aria-label'?: string;
+  "aria-label"?: string;
   /** The ID of an element that labels the calendar. */
-  'aria-labelledby'?: string;
+  "aria-labelledby"?: string;
   /** The ID of an element that describes the calendar. */
-  'aria-describedby'?: string;
+  "aria-describedby"?: string;
+  /** The ID of an element that provides additional details about the calendar. */
+  "aria-details"?: string;
+  /** Whether the current selection is invalid. */
+  isInvalid?: boolean;
+  /** Error message rendered for invalid selections. */
+  errorMessage?: string;
+  /** ID of the rendered error message element. */
+  errorMessageId?: string;
 }
 
 export interface RangeCalendarAria {
@@ -39,35 +49,57 @@ export interface RangeCalendarAria {
   nextButtonProps: Record<string, unknown>;
   /** Props for the title/heading element. */
   titleProps: Record<string, unknown>;
+  /** Props for the error message element, if any. */
+  errorMessageProps: Record<string, unknown>;
   /** An accessible label for the title. */
   title: string;
 }
 
-// ============================================
-// IMPLEMENTATION
-// ============================================
-
 /**
  * Provides the behavior and accessibility implementation for a range calendar component.
  */
 export function createRangeCalendar<T extends RangeCalendarState>(
   props: MaybeAccessor<AriaRangeCalendarProps>,
-  state: T
+  state: T,
 ): RangeCalendarAria {
   const getProps = () => access(props);
   const id = createId(getProps().id);
   const titleId = createId();
+  const errorMessageId = createId(getProps().errorMessageId);
 
   // Title (e.g., "December 2024")
   const title = createMemo(() => state.title());
+  const visibleRangeDescription = createMemo(() => {
+    const range = state.visibleRange();
+    return formatVisibleRangeDescription(range.start, range.end, state.timeZone, state.locale());
+  });
+  const calendarLabel = createMemo(() => {
+    const p = getProps();
+    return [p["aria-label"], visibleRangeDescription()].filter(Boolean).join(", ");
+  });
+  const selectedDateDescription = createMemo(() => formatSelectedDateDescription(state));
+
+  const initialProps = getProps();
+  const existingHookData = getCalendarHookData(state);
+  setCalendarHookData(state, {
+    errorMessageId:
+      initialProps.errorMessage || initialProps.errorMessageId
+        ? errorMessageId
+        : existingHookData?.errorMessageId,
+    ariaLabel: initialProps["aria-label"],
+    ariaLabelledBy: initialProps["aria-labelledby"],
+    get selectedDateDescription() {
+      return selectedDateDescription();
+    },
+  });
 
   // Previous button props
   const prevButtonProps = createMemo(() => {
     const p = getProps();
-    const isDisabled = p.isDisabled || state.isDisabled();
+    const isDisabled = p.isDisabled || state.isDisabled() || state.isPreviousVisibleRangeInvalid();
 
     return {
-      'aria-label': 'Previous month',
+      "aria-label": "Previous month",
       onClick: () => {
         if (!isDisabled) {
           state.focusPreviousPage();
@@ -81,10 +113,10 @@ export function createRangeCalendar<T extends RangeCalendarState>(
   // Next button props
   const nextButtonProps = createMemo(() => {
     const p = getProps();
-    const isDisabled = p.isDisabled || state.isDisabled();
+    const isDisabled = p.isDisabled || state.isDisabled() || state.isNextVisibleRangeInvalid();
 
     return {
-      'aria-label': 'Next month',
+      "aria-label": "Next month",
       onClick: () => {
         if (!isDisabled) {
           state.focusNextPage();
@@ -98,22 +130,24 @@ export function createRangeCalendar<T extends RangeCalendarState>(
   // Title props
   const titleProps = createMemo(() => ({
     id: titleId,
-    'aria-live': 'polite' as const,
+    "aria-live": "polite" as const,
+  }));
+  const errorMessageProps = createMemo(() => ({
+    id: errorMessageId,
   }));
 
   // Calendar container props
   const calendarProps = createMemo(() => {
     const p = getProps();
 
-    return mergeProps(
-      {
-        id,
-        role: 'group',
-        'aria-labelledby': p['aria-labelledby'] ?? titleId,
-        'aria-label': p['aria-label'],
-        'aria-describedby': p['aria-describedby'],
-      }
-    );
+    return mergeProps({
+      id,
+      role: "application",
+      "aria-labelledby": p["aria-labelledby"],
+      "aria-label": calendarLabel(),
+      "aria-describedby": p["aria-describedby"],
+      "aria-details": p["aria-details"],
+    });
   });
 
   return {
@@ -129,6 +163,9 @@ export function createRangeCalendar<T extends RangeCalendarState>(
     get titleProps() {
       return titleProps();
     },
+    get errorMessageProps() {
+      return errorMessageProps();
+    },
     get title() {
       return title();
     },

package/src/calendar/createRangeCalendarCell.ts

@@ -5,14 +5,14 @@
  * Based on @react-aria/calendar useCalendarCell (with range support)
  */
 
-import { createSignal, createMemo, createEffect } from 'solid-js';
-import { access, type MaybeAccessor } from '../utils/reactivity';
-import type { RangeCalendarState, CalendarDate, DateValue } from '@proyecto-viviana/solid-stately';
-import { isToday as isTodayUtil, DateFormatter, getLocalTimeZone } from '@internationalized/date';
-
-// ============================================
-// TYPES
-// ============================================
+import { createSignal, createMemo, createEffect } from "solid-js";
+import { access, type MaybeAccessor } from "../utils/reactivity";
+import { focusSafely } from "../utils/focus";
+import { createDescription } from "../utils/createDescription";
+import type { RangeCalendarState, CalendarDate, DateValue } from "@proyecto-viviana/solid-stately";
+import { isToday as isTodayUtil, DateFormatter, getLocalTimeZone } from "@internationalized/date";
+import { getCalendarHookData, getEraFormat } from "./utils";
+import { formatCalendarLabel, formatCalendarPrompt } from "./intl";
 
 export interface AriaRangeCalendarCellProps {
   /** The date represented by the cell. */
@@ -40,6 +40,8 @@ export interface RangeCalendarCellAria {
   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. */
@@ -50,17 +52,13 @@ export interface RangeCalendarCellAria {
   formattedDate: string;
 }
 
-// ============================================
-// IMPLEMENTATION
-// ============================================
-
 /**
  * Provides the behavior and accessibility implementation for a range calendar cell.
  */
 export function createRangeCalendarCell<T extends RangeCalendarState>(
   props: MaybeAccessor<AriaRangeCalendarCellProps>,
   state: T,
-  ref?: () => HTMLElement | null
+  ref?: () => HTMLElement | null,
 ): RangeCalendarCellAria {
   const getProps = () => access(props);
   const [isPressed, setIsPressed] = createSignal(false);
@@ -74,14 +72,37 @@ export function createRangeCalendarCell<T extends RangeCalendarState>(
   const isSelectionStart = createMemo(() => state.isSelectionStart(date()));
   const isSelectionEnd = createMemo(() => state.isSelectionEnd(date()));
   const isFocused = createMemo(() => state.isCellFocused(date()));
+  const isInvalid = createMemo(() => {
+    const range = state.highlightedRange();
+    const d = date();
+    return (
+      state.isValueInvalid() &&
+      !state.anchorDate() &&
+      !!range &&
+      d.compare(range.start) >= 0 &&
+      d.compare(range.end) <= 0
+    );
+  });
   const isDisabled = createMemo(() => {
     return getProps().isDisabled || state.isCellDisabled(date());
   });
   const isUnavailable = createMemo(() => state.isCellUnavailable(date()));
+  const isSelectable = createMemo(() => !isDisabled() && !isUnavailable());
   const isOutsideMonth = createMemo(() => {
     return getProps().isOutsideMonth ?? state.isOutsideVisibleRange(date());
   });
   const isToday = createMemo(() => isTodayUtil(date(), timeZone));
+  const rangeSelectionPrompt = createMemo(() => {
+    if (!isFocused() || state.isReadOnly() || !isSelectable()) {
+      return undefined;
+    }
+
+    return formatCalendarPrompt(
+      state.locale(),
+      state.anchorDate() ? "finishRangeSelectionPrompt" : "startRangeSelectionPrompt",
+    );
+  });
+  const descriptionProps = createDescription(rangeSelectionPrompt);
 
   // Format the date for display
   const formattedDate = createMemo(() => {
@@ -91,7 +112,7 @@ export function createRangeCalendarCell<T extends RangeCalendarState>(
   // Handle pointer down - selection on pointerdown avoids losing selection when
   // hover/focus updates re-render cells before click fires.
   const handlePointerDown = (e: PointerEvent) => {
-    if (!isDisabled() && !isUnavailable()) {
+    if (isSelectable()) {
       setIsPressed(true);
       state.selectDate(date());
       e.preventDefault();
@@ -100,7 +121,7 @@ export function createRangeCalendarCell<T extends RangeCalendarState>(
 
   // Handle click for keyboard activation (Enter/Space).
   const handleClick = () => {
-    if (!isDisabled() && !isUnavailable()) {
+    if (isSelectable()) {
       state.selectDate(date());
     }
   };
@@ -111,43 +132,80 @@ export function createRangeCalendarCell<T extends RangeCalendarState>(
 
   // Handle hover during range selection
   const handlePointerEnter = () => {
-    if (state.isDragging() && !isDisabled() && !isUnavailable()) {
+    if (state.isDragging() && isSelectable()) {
       state.setFocusedDate(date());
     }
   };
 
   // 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.
   createEffect(() => {
     const element = ref?.();
     if (element && isFocused()) {
-      element.focus();
+      focusSafely(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',
-    });
+    const formatter = new DateFormatter(state.locale(), {
+      weekday: "long",
+      year: "numeric",
+      month: "long",
+      day: "numeric",
+      era: getEraFormat(d),
+      calendar: d.calendar.identifier,
+      timeZone,
+    } as Intl.DateTimeFormatOptions);
+    const hookData = getCalendarHookData(state);
+    let label = "";
+
+    if (
+      hookData?.selectedDateDescription &&
+      !state.anchorDate() &&
+      state.value() &&
+      (state.isSelectionStart(d) || state.isSelectionEnd(d))
+    ) {
+      label = `${hookData.selectedDateDescription}, `;
+    }
+
+    label += formatter.format(d.toDate(timeZone));
+    if (isToday()) {
+      label = formatCalendarLabel(
+        state.locale(),
+        isSelected() ? "todayDateSelected" : "todayDate",
+        { date: label },
+      );
+    } else if (isSelected()) {
+      label = formatCalendarLabel(state.locale(), "dateSelected", { date: label });
+    }
+
+    const errorMessageId = hookData?.errorMessageId;
+    const describedByIds = [
+      isInvalid() ? errorMessageId : undefined,
+      descriptionProps["aria-describedby"],
+    ].filter(Boolean);
 
     return {
-      role: 'button',
+      role: "button",
       tabIndex: isFocused() ? 0 : -1,
-      'aria-label': formatter.format(d.toDate(timeZone)),
-      'aria-disabled': isDisabled() || undefined,
-      'aria-pressed': isPressed() || undefined,
-      disabled: isDisabled(),
+      "aria-label": label,
+      "aria-disabled": isDisabled() || isUnavailable() || undefined,
+      "aria-invalid": isInvalid() || undefined,
+      "aria-describedby": describedByIds.length ? describedByIds.join(" ") : undefined,
+      "aria-pressed": isPressed() || undefined,
+      disabled: isDisabled() || isUnavailable(),
       onClick: handleClick,
       onPointerDown: handlePointerDown,
       onPointerUp: handlePointerUp,
@@ -187,6 +245,9 @@ export function createRangeCalendarCell<T extends RangeCalendarState>(
     get isUnavailable() {
       return isUnavailable();
     },
+    get isInvalid() {
+      return isInvalid();
+    },
     get isOutsideMonth() {
       return isOutsideMonth();
     },

package/src/calendar/index.ts

@@ -1,34 +1,47 @@
 // Calendar
+export { createCalendar, type AriaCalendarProps, type CalendarAria } from "./createCalendar";
+
+// Calendar Month Picker
+export {
+  createCalendarMonthPicker,
+  type CalendarMonthPickerProps,
+  type CalendarMonthPickerItem,
+  type CalendarMonthPickerAria,
+} from "./createCalendarMonthPicker";
+
+// Calendar Year Picker
 export {
-  createCalendar,
-  type AriaCalendarProps,
-  type CalendarAria,
-} from './createCalendar';
+  createCalendarYearPicker,
+  type CalendarYearPickerProps,
+  type CalendarYearPickerFormatOptions,
+  type CalendarYearPickerItem,
+  type CalendarYearPickerAria,
+} from "./createCalendarYearPicker";
 
 // Calendar Grid
 export {
   createCalendarGrid,
   type AriaCalendarGridProps,
   type CalendarGridAria,
-} from './createCalendarGrid';
+} from "./createCalendarGrid";
 
 // Calendar Cell
 export {
   createCalendarCell,
   type AriaCalendarCellProps,
   type CalendarCellAria,
-} from './createCalendarCell';
+} from "./createCalendarCell";
 
 // Range Calendar
 export {
   createRangeCalendar,
   type AriaRangeCalendarProps,
   type RangeCalendarAria,
-} from './createRangeCalendar';
+} from "./createRangeCalendar";
 
 // Range Calendar Cell
 export {
   createRangeCalendarCell,
   type AriaRangeCalendarCellProps,
   type RangeCalendarCellAria,
-} from './createRangeCalendarCell';
+} from "./createRangeCalendarCell";