@proyecto-viviana/solidaria-components 0.2.5 → 0.3.0

package/src/Calendar.tsx

@@ -7,6 +7,7 @@
 
 import {
   type JSX,
+  type Accessor,
   createContext,
   createMemo,
   createSignal,
@@ -15,22 +16,25 @@ import {
   For,
   Index,
   Show,
-} from 'solid-js';
+} from "solid-js";
 
 import {
   createCalendar,
   createCalendarGrid,
   createCalendarCell,
+  createHover,
   type AriaCalendarProps,
   type AriaCalendarGridProps,
-} from '@proyecto-viviana/solidaria';
+} from "@proyecto-viviana/solidaria";
 import {
   createCalendarState,
   type CalendarState,
   type CalendarStateProps,
   type CalendarDate,
   type DateValue,
-} from '@proyecto-viviana/solid-stately';
+  endOfMonth,
+  isSameMonth,
+} from "@proyecto-viviana/solid-stately";
 import {
   type RenderChildren,
   type ClassNameOrFunction,
@@ -39,22 +43,36 @@ import {
   useRenderProps,
   dataAttr,
   useIsHydrated,
-} from './utils';
+} from "./utils";
+import { VisuallyHidden } from "./VisuallyHidden";
 
-// ============================================
-// TYPES
-// ============================================
+type RefLike<T> = ((el: T) => void) | { current?: T | null } | undefined;
+
+function assignRef<T>(ref: RefLike<T>, el: T): void {
+  if (!ref) {
+    return;
+  }
+
+  if (typeof ref === "function") {
+    ref(el);
+  } else {
+    ref.current = el;
+  }
+}
 
 export interface CalendarRenderProps {
   /** Whether the calendar is disabled. */
   isDisabled: boolean;
   /** Whether the calendar is read-only. */
   isReadOnly: boolean;
+  /** Whether the current selection is invalid. */
+  isInvalid: boolean;
 }
 
 export interface CalendarProps<T extends DateValue = DateValue>
-  extends Omit<AriaCalendarProps, 'id' | 'isDisabled' | 'isReadOnly'>,
-    Omit<CalendarStateProps<T>, 'locale'>,
+  extends
+    Omit<AriaCalendarProps, "id" | "isDisabled" | "isReadOnly">,
+    Omit<CalendarStateProps<T>, "locale">,
     SlotProps {
   /** The children of the component. */
   children?: JSX.Element;
@@ -64,6 +82,8 @@ export interface CalendarProps<T extends DateValue = DateValue>
   style?: StyleOrFunction<CalendarRenderProps>;
   /** The locale to use for formatting. */
   locale?: string;
+  /** Ref for the calendar root element. */
+  ref?: RefLike<HTMLDivElement>;
 }
 
 export interface CalendarGridRenderProps {
@@ -71,13 +91,16 @@ export interface CalendarGridRenderProps {
   isDisabled: boolean;
 }
 
-export interface CalendarGridProps extends Omit<AriaCalendarGridProps, 'startDate' | 'endDate'>, SlotProps {
+export interface CalendarGridProps
+  extends Omit<AriaCalendarGridProps, "startDate" | "endDate">, SlotProps {
   /** The children of the component (render function receiving weeks). */
   children?: (date: CalendarDate) => JSX.Element;
   /** The CSS className for the element. */
   class?: ClassNameOrFunction<CalendarGridRenderProps>;
   /** The inline style for the element. */
   style?: StyleOrFunction<CalendarGridRenderProps>;
+  /** Class name for weekday header cells. */
+  headerCellClass?: string;
   /** Number of weeks to offset from the start. */
   offset?: { months?: number };
 }
@@ -87,16 +110,30 @@ export interface CalendarCellRenderProps {
   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. */
   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. */
   isToday: boolean;
   /** Whether the cell is pressed. */
   isPressed: boolean;
+  /** Whether the cell is hovered. */
+  isHovered: boolean;
+  /** Whether the cell is the first day slot in its row. */
+  isFirstChild: boolean;
+  /** Whether the cell is the last day slot in its row. */
+  isLastChild: boolean;
+  /** Whether the cell is in the first rendered week row. */
+  isFirstWeek: boolean;
+  /** Whether the cell is in the last rendered week row. */
+  isLastWeek: boolean;
   /** The formatted date string. */
   formattedDate: string;
 }
@@ -110,6 +147,10 @@ export interface CalendarCellProps extends SlotProps {
   class?: ClassNameOrFunction<CalendarCellRenderProps>;
   /** The inline style for the element. */
   style?: StyleOrFunction<CalendarCellRenderProps>;
+  /** Class name for the table cell wrapper. */
+  cellClass?: ClassNameOrFunction<CalendarCellRenderProps>;
+  /** Inline style for the table cell wrapper. */
+  cellStyle?: StyleOrFunction<CalendarCellRenderProps>;
 }
 
 export interface CalendarHeaderCellProps extends SlotProps {
@@ -121,24 +162,34 @@ export interface CalendarHeaderCellProps extends SlotProps {
   style?: JSX.CSSProperties;
 }
 
-// ============================================
-// CONTEXT
-// ============================================
+export interface CalendarGridHeaderProps extends SlotProps {
+  children?: JSX.Element;
+  class?: string;
+  style?: JSX.CSSProperties;
+}
+
+export interface CalendarGridBodyProps extends SlotProps {
+  children?: JSX.Element;
+  class?: string;
+  style?: JSX.CSSProperties;
+}
 
 export const CalendarContext = createContext<CalendarState<DateValue> | null>(null);
+const CalendarGridMonthContext = createContext<Accessor<CalendarDate> | null>(null);
+const CalendarGridCellPositionContext = createContext<Accessor<{
+  weekIndex: number;
+  dayIndex: number;
+  lastWeekIndex: number;
+}> | null>(null);
 
 export function useCalendarContext(): CalendarState<DateValue> {
   const context = useContext(CalendarContext);
   if (!context) {
-    throw new Error('Calendar components must be used within a Calendar');
+    throw new Error("Calendar components must be used within a Calendar");
   }
   return context;
 }
 
-// ============================================
-// CALENDAR COMPONENT
-// ============================================
-
 /**
  * A calendar displays a grid of days in a month and allows users to select a single date.
  *
@@ -156,95 +207,181 @@ export function useCalendarContext(): CalendarState<DateValue> {
  * </Calendar>
  * ```
  */
-export function Calendar<T extends DateValue = CalendarDate>(
-  props: CalendarProps<T>
-): JSX.Element {
+export function Calendar<T extends DateValue = CalendarDate>(props: CalendarProps<T>): JSX.Element {
+  const inheritedState = useContext(CalendarContext);
+
   // Use hydration-safe pattern for client-only rendering
   const isHydrated = useIsHydrated();
 
   return (
     <Show
       when={isHydrated()}
-      fallback={<div class="solidaria-Calendar solidaria-Calendar--placeholder" aria-hidden="true" />}
+      fallback={
+        <div class="solidaria-Calendar solidaria-Calendar--placeholder" aria-hidden="true" />
+      }
     >
-      <CalendarInner {...props} />
+      <Show when={inheritedState} fallback={<CalendarInner {...props} />}>
+        <CalendarWithState state={inheritedState as CalendarState<DateValue>} {...props} />
+      </Show>
     </Show>
   );
 }
 
+function CalendarWithState<T extends DateValue = CalendarDate>(
+  props: CalendarProps<T> & { state: CalendarState<DateValue> },
+): JSX.Element {
+  const [local, stateProps, rest] = splitProps(
+    props,
+    ["children", "class", "style", "slot", "state", "ref"],
+    [
+      "value",
+      "defaultValue",
+      "onChange",
+      "minValue",
+      "maxValue",
+      "isDisabled",
+      "isReadOnly",
+      "autoFocus",
+      "focusedValue",
+      "defaultFocusedValue",
+      "onFocusChange",
+      "locale",
+      "createCalendar",
+      "isDateUnavailable",
+      "visibleMonths",
+      "pageBehavior",
+      "selectionAlignment",
+      "isDateDisabled",
+      "validationState",
+      "errorMessage",
+      "firstDayOfWeek",
+    ],
+  );
+
+  const state = () => props.state;
+  const calendarAria = createCalendar(
+    () => ({
+      ...rest,
+      errorMessage: stateProps.errorMessage,
+    }),
+    state(),
+  );
+
+  const renderValues = createMemo<CalendarRenderProps>(() => ({
+    isDisabled: state().isDisabled(),
+    isReadOnly: state().isReadOnly(),
+    isInvalid: state().isValueInvalid(),
+  }));
+
+  const renderProps = useRenderProps(
+    {
+      class: local.class,
+      style: local.style,
+      defaultClassName: "solidaria-Calendar",
+    },
+    renderValues,
+  );
+
+  return (
+    <div
+      {...calendarAria.calendarProps}
+      ref={(el) => assignRef(local.ref, el)}
+      class={renderProps.class()}
+      style={renderProps.style()}
+      data-disabled={dataAttr(state().isDisabled())}
+      data-readonly={dataAttr(state().isReadOnly())}
+      data-invalid={dataAttr(state().isValueInvalid())}
+    >
+      <VisuallyHidden>
+        <h2>{String(calendarAria.calendarProps["aria-label"] ?? "")}</h2>
+      </VisuallyHidden>
+      {props.children}
+    </div>
+  );
+}
+
 /**
  * Internal Calendar component that renders after client mount.
  */
-function CalendarInner<T extends DateValue = CalendarDate>(
-  props: CalendarProps<T>
-): JSX.Element {
+function CalendarInner<T extends DateValue = CalendarDate>(props: CalendarProps<T>): JSX.Element {
   const [local, stateProps, rest] = splitProps(
     props,
-    ['children', 'class', 'style', 'slot'],
+    ["children", "class", "style", "slot", "ref"],
     [
-      'value',
-      'defaultValue',
-      'onChange',
-      'minValue',
-      'maxValue',
-      'isDisabled',
-      'isReadOnly',
-      'autoFocus',
-      'focusedValue',
-      'defaultFocusedValue',
-      'onFocusChange',
-      'locale',
-      'isDateUnavailable',
-      'visibleMonths',
-      'isDateDisabled',
-      'validationState',
-      'errorMessage',
-      'firstDayOfWeek',
-    ]
+      "value",
+      "defaultValue",
+      "onChange",
+      "minValue",
+      "maxValue",
+      "isDisabled",
+      "isReadOnly",
+      "autoFocus",
+      "focusedValue",
+      "defaultFocusedValue",
+      "onFocusChange",
+      "locale",
+      "createCalendar",
+      "isDateUnavailable",
+      "visibleMonths",
+      "pageBehavior",
+      "selectionAlignment",
+      "isDateDisabled",
+      "validationState",
+      "errorMessage",
+      "firstDayOfWeek",
+    ],
   );
 
   // Create calendar state
   const state = createCalendarState(stateProps);
 
   // Create calendar ARIA props
-  const calendarAria = createCalendar(rest, state as unknown as CalendarState<DateValue>);
+  const calendarAria = createCalendar(
+    () => ({
+      ...rest,
+      errorMessage: stateProps.errorMessage,
+    }),
+    state as unknown as CalendarState<DateValue>,
+  );
 
-  // Render props values
   const renderValues = createMemo<CalendarRenderProps>(() => ({
     isDisabled: state.isDisabled(),
     isReadOnly: state.isReadOnly(),
+    isInvalid: state.isValueInvalid(),
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-Calendar',
+      defaultClassName: "solidaria-Calendar",
     },
-    renderValues
+    renderValues,
   );
 
   return (
     <CalendarContext.Provider value={state as unknown as CalendarState<DateValue>}>
       <div
         {...calendarAria.calendarProps}
+        ref={(el) => assignRef(local.ref, el)}
         class={renderProps.class()}
         style={renderProps.style()}
         data-disabled={dataAttr(state.isDisabled())}
         data-readonly={dataAttr(state.isReadOnly())}
+        data-invalid={dataAttr(state.isValueInvalid())}
       >
+        <VisuallyHidden>
+          <h2>{String(calendarAria.calendarProps["aria-label"] ?? "")}</h2>
+        </VisuallyHidden>
         {props.children}
       </div>
     </CalendarContext.Provider>
   );
 }
 
-// ============================================
-// CALENDAR HEADING COMPONENT
-// ============================================
-
 export interface CalendarHeadingProps extends SlotProps {
+  /** The children of the component. */
+  children?: RenderChildren<{ title: string }>;
   /** The CSS className for the element. */
   class?: string;
   /** The inline style for the element. */
@@ -256,25 +393,29 @@ export interface CalendarHeadingProps extends SlotProps {
  */
 export function CalendarHeading(props: CalendarHeadingProps): JSX.Element {
   const state = useCalendarContext();
+  const renderValues = createMemo(() => ({
+    title: state.title(),
+  }));
+  const renderProps = useRenderProps(
+    {
+      children: props.children,
+      class: props.class,
+      style: props.style,
+      defaultClassName: "solidaria-CalendarHeading",
+    },
+    renderValues,
+  );
 
   return (
-    <h2
-      class={props.class ?? 'solidaria-CalendarHeading'}
-      style={props.style}
-      aria-live="polite"
-    >
-      {state.title()}
+    <h2 class={renderProps.class()} style={renderProps.style()} aria-live="polite">
+      {typeof props.children === "function" ? renderProps.renderChildren() : state.title()}
     </h2>
   );
 }
 
-// ============================================
-// CALENDAR BUTTON COMPONENT
-// ============================================
-
 export interface CalendarButtonProps extends SlotProps {
   /** The slot for this button (previous or next). */
-  slot?: 'previous' | 'next';
+  slot?: "previous" | "next";
   /** The children of the component. */
   children?: JSX.Element;
   /** The CSS className for the element. */
@@ -293,7 +434,7 @@ export function CalendarButton(props: CalendarButtonProps): JSX.Element {
   const calendarAria = createCalendar({}, state);
 
   const buttonProps = createMemo(() => {
-    if (props.slot === 'previous') {
+    if (props.slot === "previous") {
       return calendarAria.prevButtonProps;
     }
     return calendarAria.nextButtonProps;
@@ -302,7 +443,7 @@ export function CalendarButton(props: CalendarButtonProps): JSX.Element {
   return (
     <button
       {...buttonProps()}
-      class={props.class ?? 'solidaria-CalendarButton'}
+      class={props.class ?? "solidaria-CalendarButton"}
       style={props.style}
       disabled={props.isDisabled || state.isDisabled()}
     >
@@ -311,161 +452,226 @@ export function CalendarButton(props: CalendarButtonProps): JSX.Element {
   );
 }
 
-// ============================================
-// CALENDAR GRID COMPONENT
-// ============================================
-
 /**
  * Displays a grid of calendar cells.
  */
 export function CalendarGrid(props: CalendarGridProps): JSX.Element {
   const state = useCalendarContext();
   const [gridRef, setGridRef] = createSignal<HTMLTableElement | null>(null);
+  const startDate = createMemo(() => {
+    const offsetMonths = props.offset?.months ?? 0;
+    const baseStart = state.visibleRange().start;
+    return offsetMonths ? baseStart.add({ months: offsetMonths }) : baseStart;
+  });
 
-  // Create grid ARIA props
   const gridAria = createCalendarGrid(
     {
+      startDate: startDate(),
+      endDate: endOfMonth(startDate()),
       weekdayStyle: props.weekdayStyle,
     },
     state,
-    gridRef
+    gridRef,
   );
 
-  // Render props values
   const renderValues = createMemo<CalendarGridRenderProps>(() => ({
     isDisabled: state.isDisabled(),
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
       class: props.class,
       style: props.style,
-      defaultClassName: 'solidaria-CalendarGrid',
+      defaultClassName: "solidaria-CalendarGrid",
     },
-    renderValues
+    renderValues,
   );
 
   // Memoize ALL dates for the grid at once to avoid reactive loops.
   // This breaks the cycle where accessing visibleRange() inside For loop
   // would cause infinite re-renders.
   const allDates = createMemo(() => {
-    const numWeeks = state.getWeeksInMonth();
+    const monthStart = startDate();
+    const numWeeks = state.getWeeksInMonth(monthStart);
     const weekDates: (CalendarDate | null)[][] = [];
 
     for (let weekIndex = 0; weekIndex < numWeeks; weekIndex++) {
-      weekDates.push(state.getDatesInWeek(weekIndex));
+      weekDates.push(state.getDatesInWeek(weekIndex, monthStart));
     }
 
     return weekDates;
   });
 
   return (
-    <table
-      ref={setGridRef}
-      {...gridAria.gridProps}
-      class={renderProps.class()}
-      style={renderProps.style()}
-    >
-      <thead {...gridAria.headerProps}>
-        <tr>
-          <For each={gridAria.weekDays}>
-            {(day) => (
-              <th scope="col" class="solidaria-CalendarHeaderCell">
-                {day}
-              </th>
+    <CalendarGridMonthContext.Provider value={startDate}>
+      <table
+        ref={setGridRef}
+        {...gridAria.gridProps}
+        class={renderProps.class()}
+        style={renderProps.style()}
+      >
+        <thead {...gridAria.headerProps}>
+          <tr>
+            <For each={gridAria.weekDays}>
+              {(day) => (
+                <th scope="col" class={props.headerCellClass ?? "solidaria-CalendarHeaderCell"}>
+                  {day}
+                </th>
+              )}
+            </For>
+          </tr>
+        </thead>
+        <tbody>
+          <Index each={allDates()}>
+            {(weekDates, weekIndex) => (
+              <tr>
+                <Index each={weekDates()}>
+                  {(date, dayIndex) => (
+                    <Show when={date()} fallback={<td />}>
+                      <CalendarGridCellPositionContext.Provider
+                        value={() => ({
+                          weekIndex,
+                          dayIndex,
+                          lastWeekIndex: allDates().length - 1,
+                        })}
+                      >
+                        {props.children?.(date()!)}
+                      </CalendarGridCellPositionContext.Provider>
+                    </Show>
+                  )}
+                </Index>
+              </tr>
             )}
-          </For>
-        </tr>
-      </thead>
-      <tbody>
-        <Index each={allDates()}>
-          {(weekDates) => (
-            <tr>
-              <Index each={weekDates()}>
-                {(date) => (
-                  <Show when={date()}>
-                    <td role="gridcell">
-                      {props.children?.(date()!)}
-                    </td>
-                  </Show>
-                )}
-              </Index>
-            </tr>
-          )}
-        </Index>
-      </tbody>
-    </table>
+          </Index>
+        </tbody>
+      </table>
+    </CalendarGridMonthContext.Provider>
   );
 }
 
-// ============================================
-// CALENDAR CELL COMPONENT
-// ============================================
+export function CalendarGridHeader(props: CalendarGridHeaderProps): JSX.Element {
+  return (
+    <thead class={props.class ?? "solidaria-CalendarGridHeader"} style={props.style}>
+      {props.children}
+    </thead>
+  );
+}
+
+export function CalendarGridBody(props: CalendarGridBodyProps): JSX.Element {
+  return (
+    <tbody class={props.class ?? "solidaria-CalendarGridBody"} style={props.style}>
+      {props.children}
+    </tbody>
+  );
+}
+
+export function CalendarHeaderCell(props: CalendarHeaderCellProps): JSX.Element {
+  return (
+    <th scope="col" class={props.class ?? "solidaria-CalendarHeaderCell"} style={props.style}>
+      {props.children}
+    </th>
+  );
+}
 
 /**
  * A cell in the calendar grid representing a single day.
  */
 export function CalendarCell(props: CalendarCellProps): JSX.Element {
   const state = useCalendarContext();
+  const currentMonthStart = useContext(CalendarGridMonthContext);
+  const cellPosition = useContext(CalendarGridCellPositionContext);
   const [cellRef, setCellRef] = createSignal<HTMLDivElement | null>(null);
+  const isOutsideMonth = createMemo(
+    () => currentMonthStart != null && !isSameMonth(currentMonthStart(), props.date),
+  );
+  const position = createMemo(
+    () =>
+      cellPosition?.() ?? {
+        weekIndex: 0,
+        dayIndex: 0,
+        lastWeekIndex: 0,
+      },
+  );
 
-  // Create cell ARIA props
   const cellAria = createCalendarCell(
-    { date: props.date },
+    () => ({
+      date: props.date,
+      isOutsideMonth: isOutsideMonth(),
+    }),
     state,
-    cellRef
+    cellRef,
   );
+  const { hoverProps, isHovered } = createHover(() => ({
+    isDisabled: cellAria.isDisabled || cellAria.isUnavailable,
+  }));
 
-  // Render props values
   const renderValues = createMemo<CalendarCellRenderProps>(() => ({
     isSelected: cellAria.isSelected,
     isFocused: cellAria.isFocused,
+    isFocusVisible: cellAria.isFocusVisible,
     isDisabled: cellAria.isDisabled,
     isUnavailable: cellAria.isUnavailable,
+    isInvalid: cellAria.isInvalid,
     isOutsideMonth: cellAria.isOutsideMonth,
     isToday: cellAria.isToday,
     isPressed: cellAria.isPressed,
+    isHovered: isHovered(),
+    isFirstChild: position().dayIndex === 0,
+    isLastChild: position().dayIndex === 6,
+    isFirstWeek: position().weekIndex === 0,
+    isLastWeek: position().weekIndex === position().lastWeekIndex,
     formattedDate: cellAria.formattedDate,
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
       children: props.children,
       class: props.class,
       style: props.style,
-      defaultClassName: 'solidaria-CalendarCell',
+      defaultClassName: "solidaria-CalendarCell",
+    },
+    renderValues,
+  );
+  const cellRenderProps = useRenderProps(
+    {
+      class: props.cellClass,
+      style: props.cellStyle,
+      defaultClassName: "solidaria-CalendarCellWrapper",
     },
-    renderValues
+    renderValues,
   );
 
   // Determine children content - avoid Show for SSR hydration compatibility
   const getChildren = () => {
-    if (typeof props.children === 'function') {
+    if (typeof props.children === "function") {
       return renderProps.renderChildren();
     }
     return cellAria.formattedDate;
   };
 
   return (
-    <div
-      ref={setCellRef}
-      {...cellAria.buttonProps}
-      class={renderProps.class()}
-      style={renderProps.style()}
-      data-selected={dataAttr(cellAria.isSelected)}
-      data-focused={dataAttr(cellAria.isFocused)}
-      data-disabled={dataAttr(cellAria.isDisabled)}
-      data-unavailable={dataAttr(cellAria.isUnavailable)}
-      data-outside-month={dataAttr(cellAria.isOutsideMonth)}
-      data-today={dataAttr(cellAria.isToday)}
-      data-pressed={dataAttr(cellAria.isPressed)}
-    >
-      {getChildren()}
-    </div>
+    <td {...cellAria.cellProps} class={cellRenderProps.class()} style={cellRenderProps.style()}>
+      <div
+        ref={setCellRef}
+        {...cellAria.buttonProps}
+        {...hoverProps}
+        class={renderProps.class()}
+        style={renderProps.style()}
+        data-selected={dataAttr(cellAria.isSelected)}
+        data-focused={dataAttr(cellAria.isFocused)}
+        data-focus-visible={dataAttr(cellAria.isFocusVisible)}
+        data-disabled={dataAttr(cellAria.isDisabled)}
+        data-unavailable={dataAttr(cellAria.isUnavailable)}
+        data-invalid={dataAttr(cellAria.isInvalid)}
+        data-outside-month={dataAttr(cellAria.isOutsideMonth)}
+        data-today={dataAttr(cellAria.isToday)}
+        data-pressed={dataAttr(cellAria.isPressed)}
+        data-hovered={dataAttr(isHovered())}
+      >
+        {getChildren()}
+      </div>
+    </td>
   );
 }
 
-// Re-export types
 export type { CalendarState, CalendarDate, DateValue };