@kahitsan/ksui 0.40.1 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.40.1",
+  "version": "0.41.0",
   "description": "ksui is a standalone set of SolidJS UI components for KahitSan/Hilinga and any SolidJS app. Published to the public npm registry and consumed as a normal dependency. Ships source under a `solid` export condition so the consumer's vite-plugin-solid compiles it with only solid-js externalized; it depends on nothing but solid-js + lucide-solid and injects its own CSS.",
   "type": "module",
   "main": "./src/index.ts",

package/src/components/base/MonthCalendar.test.tsx

@@ -0,0 +1,107 @@
+import { createSignal } from "solid-js";
+import { fireEvent, render, screen, within } from "@solidjs/testing-library";
+import { describe, expect, it, vi } from "vitest";
+import MonthCalendar from "./MonthCalendar";
+
+function renderCalendar(overrides: Partial<Parameters<typeof MonthCalendar>[0]> = {}) {
+  const onMonthChange = vi.fn();
+  render(() => (
+    <MonthCalendar
+      month="2026-09-19"
+      today="2026-09-12"
+      onMonthChange={onMonthChange}
+      renderDay={({ date }) => <button type="button">Open {date}</button>}
+      {...overrides}
+    />
+  ));
+  return { onMonthChange };
+}
+
+describe("MonthCalendar", () => {
+  it("renders labelled grid semantics and six seven-day rows", () => {
+    renderCalendar();
+    const section = screen.getByRole("region", { name: "September 2026" });
+    const grid = within(section).getByRole("grid", { name: "September 2026" });
+    expect(within(grid).getAllByRole("columnheader").map((node) => node.textContent)).toEqual([
+      "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat",
+    ]);
+    expect(within(grid).getAllByRole("row")).toHaveLength(7);
+    expect(within(grid).getAllByRole("gridcell")).toHaveLength(42);
+  });
+
+  it("normalizes previous, next, and today changes to month starts", async () => {
+    const { onMonthChange } = renderCalendar();
+    await fireEvent.click(screen.getByRole("button", { name: "Previous month" }));
+    await fireEvent.click(screen.getByRole("button", { name: "Next month" }));
+    await fireEvent.click(screen.getByRole("button", { name: "Today" }));
+    expect(onMonthChange.mock.calls).toEqual([
+      ["2026-08-01"],
+      ["2026-10-01"],
+      ["2026-09-01"],
+    ]);
+  });
+
+  it("marks today and labels day cells with full dates", () => {
+    renderCalendar();
+    const today = screen.getByRole("gridcell", { name: "Saturday, September 12, 2026" });
+    expect(today.getAttribute("aria-current")).toBe("date");
+    expect(within(today).getByText("Open 2026-09-12")).toBeTruthy();
+  });
+
+  it("hides outside cells and skips their render slots", () => {
+    const renderDay = vi.fn(({ date }: { date: string }) => <span>{date}</span>);
+    renderCalendar({ showOutsideDays: false, renderDay });
+    expect(renderDay).toHaveBeenCalledTimes(30);
+    expect(screen.queryByText("2026-08-30")).toBeNull();
+    const hiddenCells = screen.getAllByRole("gridcell", { hidden: true }).filter((cell) => cell.getAttribute("aria-hidden") === "true");
+    expect(hiddenCells).toHaveLength(12);
+  });
+
+  it("supports Monday-first localized headers and custom labels", () => {
+    renderCalendar({
+      weekStartsOn: 1,
+      locale: "fr-FR",
+      labels: { previousMonth: "Mois précédent", nextMonth: "Mois suivant", today: "Aujourd’hui" },
+    });
+    expect(screen.getAllByRole("columnheader").map((node) => node.textContent)).toEqual([
+      "lun.", "mar.", "mer.", "jeu.", "ven.", "sam.", "dim.",
+    ]);
+    expect(screen.getByRole("button", { name: "Mois précédent" })).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Aujourd’hui" })).toBeTruthy();
+  });
+
+  it("supports controlled month updates", async () => {
+    const [month, setMonth] = createSignal("2026-09-30");
+    render(() => (
+      <MonthCalendar
+        month={month()}
+        today="2026-09-12"
+        onMonthChange={setMonth}
+        renderDay={({ date }) => <span>{date}</span>}
+      />
+    ));
+    await fireEvent.click(screen.getByRole("button", { name: "Next month" }));
+    expect(screen.getByRole("heading", { name: "October 2026" })).toBeTruthy();
+  });
+
+  it("passes week metadata and stable child rendering through renderWeek", () => {
+    const weeks: string[] = [];
+    renderCalendar({
+      renderWeek: ({ weekIndex, days, children }) => {
+        weeks.push(`${weekIndex}:${days[0].date}`);
+        return <>{children()}</>;
+      },
+    });
+    expect(weeks).toEqual([
+      "0:2026-08-30", "1:2026-09-06", "2:2026-09-13",
+      "3:2026-09-20", "4:2026-09-27", "5:2026-10-04",
+    ]);
+  });
+
+  it("allows class overrides and hiding today button", () => {
+    renderCalendar({ classes: { root: "custom-root", cell: "custom-cell" }, showTodayButton: false });
+    expect(screen.getByRole("region").classList.contains("custom-root")).toBe(true);
+    expect(screen.getAllByRole("gridcell")[0].classList.contains("custom-cell")).toBe(true);
+    expect(screen.queryByRole("button", { name: "Today" })).toBeNull();
+  });
+});

package/src/components/base/MonthCalendar.tsx

@@ -0,0 +1,399 @@
+import { For, createMemo, createUniqueId, type JSX } from "solid-js";
+import ChevronLeft from "lucide-solid/icons/chevron-left";
+import ChevronRight from "lucide-solid/icons/chevron-right";
+import { injectCSS } from "../../utils/inject-css";
+import {
+  addCivilMonths,
+  buildMonthCalendarDays,
+  formatCivilDate,
+  requireCivilDate,
+  todayInTimeZone,
+  type MonthCalendarDay,
+} from "../../utils/month-calendar-date";
+
+const STYLE_ID = "ksui-month-calendar-style";
+const MONTH_CALENDAR_CSS = `
+.ksui-month-calendar{color:var(--ksui-month-calendar-fg,var(--ks-fg,#ffffff));font-family:var(--ksui-month-calendar-font,var(--ks-font-body,"Inter", system-ui, sans-serif));}
+.ksui-month-calendar__nav{display:flex;align-items:center;justify-content:space-between;gap:.75rem;margin-bottom:.75rem;}
+.ksui-month-calendar__nav-group{display:flex;align-items:center;gap:.25rem;min-width:0;}
+.ksui-month-calendar__heading{margin:0 .25rem;font-size:.875rem;line-height:1.25rem;font-weight:600;white-space:nowrap;}
+.ksui-month-calendar__button{display:inline-flex;align-items:center;justify-content:center;border:0;border-radius:.375rem;background:transparent;color:var(--ksui-month-calendar-muted,var(--ks-fg-muted,#a1a1aa));cursor:pointer;transition:background-color .15s ease,color .15s ease;}
+.ksui-month-calendar__button:hover{background:var(--ksui-month-calendar-hover,var(--ks-surface-raised,#1a1a1a));color:var(--ksui-month-calendar-fg,var(--ks-fg,#ffffff));}
+.ksui-month-calendar__button:focus-visible{outline:2px solid var(--ksui-month-calendar-focus,var(--ks-focus-ring,#c9a961));outline-offset:2px;}
+.ksui-month-calendar__nav-button{width:2rem;height:2rem;padding:0;}
+.ksui-month-calendar__today-button{padding:.375rem .625rem;font-size:.75rem;line-height:1rem;font-weight:500;}
+.ksui-month-calendar__grid{overflow:hidden;border:1px solid var(--ksui-month-calendar-border,var(--ks-border,rgba(39,39,42,0.5)));border-radius:.5rem;background:var(--ksui-month-calendar-gap,var(--ks-border,rgba(39,39,42,0.5)));}
+.ksui-month-calendar__header,.ksui-month-calendar__week{display:grid;grid-template-columns:repeat(7,minmax(0,1fr));gap:1px;}
+.ksui-month-calendar__columnheader{padding:.5rem .25rem;background:var(--ksui-month-calendar-surface,var(--ks-surface,#0f0f0f));color:var(--ksui-month-calendar-subtle,var(--ks-fg-subtle,#71717a));font-size:.6875rem;line-height:1rem;font-weight:600;text-align:center;text-transform:uppercase;letter-spacing:.05em;}
+.ksui-month-calendar__cell{min-width:0;min-height:5rem;background:var(--ksui-month-calendar-surface,var(--ks-surface,#0f0f0f));}
+.ksui-month-calendar__cell--outside{color:var(--ksui-month-calendar-subtle,var(--ks-fg-subtle,#71717a));}
+.ksui-month-calendar__cell--hidden{visibility:hidden;}
+.ksui-month-calendar__day-label{display:inline-flex;align-items:center;justify-content:center;min-width:1.5rem;height:1.5rem;margin:.25rem;padding:0 .25rem;border-radius:9999px;color:var(--ksui-month-calendar-muted,var(--ks-fg-muted,#a1a1aa));font-size:.75rem;line-height:1rem;font-variant-numeric:tabular-nums;}
+.ksui-month-calendar__cell[aria-current="date"] .ksui-month-calendar__day-label{background:var(--ksui-month-calendar-today-bg,color-mix(in srgb,var(--ks-primary,#c9a961) 20%,transparent));color:var(--ksui-month-calendar-today-fg,var(--ks-accent,#fbbf24));font-weight:600;}
+`;
+
+export interface MonthCalendarDayRenderProps extends MonthCalendarDay {
+  dayLabelId: string;
+}
+
+export interface MonthCalendarWeekRenderProps {
+  weekIndex: number;
+  days: readonly MonthCalendarDayRenderProps[];
+  children: () => JSX.Element;
+}
+
+export interface MonthCalendarLabels {
+  previousMonth?: string;
+  nextMonth?: string;
+  today?: string;
+}
+
+export interface MonthCalendarClasses {
+  root?: string;
+  nav?: string;
+  heading?: string;
+  grid?: string;
+  header?: string;
+  columnHeader?: string;
+  week?: string;
+  cell?: string;
+  dayLabel?: string;
+  previousButton?: string;
+  nextButton?: string;
+  todayButton?: string;
+}
+
+export interface MonthCalendarProps {
+  month: string;
+  onMonthChange: (month: string) => void;
+  renderDay: (props: MonthCalendarDayRenderProps) => JSX.Element;
+  renderWeek?: (props: MonthCalendarWeekRenderProps) => JSX.Element;
+  today?: string;
+  timeZone?: string;
+  locale?: string;
+  weekStartsOn?: number;
+  showOutsideDays?: boolean;
+  showTodayButton?: boolean;
+  labels?: MonthCalendarLabels;
+  classes?: MonthCalendarClasses;
+}
+
+interface ResolvedLabels {
+  previousMonth: string;
+  nextMonth: string;
+  today: string;
+}
+
+function resolveLabels(labels?: MonthCalendarLabels): ResolvedLabels {
+  return {
+    previousMonth: labels?.previousMonth ?? "Previous month",
+    nextMonth: labels?.nextMonth ?? "Next month",
+    today: labels?.today ?? "Today",
+  };
+}
+
+function resolveClasses(classes?: MonthCalendarClasses): MonthCalendarClasses {
+  return classes ?? {};
+}
+
+function joinClasses(...values: Array<string | undefined>): string {
+  return values.filter(Boolean).join(" ");
+}
+
+
+function displayDate(day: MonthCalendarDay, locale: string): string {
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: "full",
+    timeZone: "UTC",
+  }).format(new Date(Date.UTC(day.year, day.month - 1, day.day)));
+}
+
+interface DayCellProps {
+  day: MonthCalendarDayRenderProps;
+  locale: string;
+  showOutsideDays: boolean;
+  cellClass?: string;
+  dayLabelClass?: string;
+  renderDay: MonthCalendarProps["renderDay"];
+}
+
+function DayCell(props: DayCellProps) {
+  const hidden = () => !props.day.inMonth && !props.showOutsideDays;
+  return (
+    <div
+      role="gridcell"
+      aria-current={props.day.isToday ? "date" : undefined}
+      aria-labelledby={hidden() ? undefined : props.day.dayLabelId}
+      aria-hidden={hidden() ? "true" : undefined}
+      class={joinClasses(
+        "ksui-month-calendar__cell",
+        !props.day.inMonth ? "ksui-month-calendar__cell--outside" : undefined,
+        hidden() ? "ksui-month-calendar__cell--hidden" : undefined,
+        props.cellClass,
+      )}
+    >
+      {!hidden() && (
+        <>
+          <span
+            id={props.day.dayLabelId}
+            class={joinClasses("ksui-month-calendar__day-label", props.dayLabelClass)}
+            aria-label={displayDate(props.day, props.locale)}
+          >
+            {props.day.day}
+          </span>
+          {props.renderDay(props.day)}
+        </>
+      )}
+    </div>
+  );
+}
+
+interface CalendarGridProps {
+  headingId: string;
+  weekdayLabels: readonly string[];
+  weeks: readonly (readonly MonthCalendarDayRenderProps[])[];
+  locale: string;
+  showOutsideDays: boolean;
+  classes?: MonthCalendarClasses;
+  renderDay: MonthCalendarProps["renderDay"];
+  renderWeek?: MonthCalendarProps["renderWeek"];
+}
+
+interface CalendarNavigationProps {
+  heading: string;
+  headingId: string;
+  showTodayButton: boolean;
+  previousLabel: string;
+  nextLabel: string;
+  todayLabel: string;
+  navClass?: string;
+  headingClass?: string;
+  previousButtonClass?: string;
+  nextButtonClass?: string;
+  todayButtonClass?: string;
+  onPreviousMonth: () => void;
+  onNextMonth: () => void;
+  onToday: () => void;
+}
+
+interface NavigationIconButtonProps {
+  label: string;
+  class?: string;
+  direction: "previous" | "next";
+  onClick: () => void;
+}
+
+function NavigationIconButton(props: NavigationIconButtonProps) {
+  return (
+    <button
+      type="button"
+      aria-label={props.label}
+      class={joinClasses("ksui-month-calendar__button ksui-month-calendar__nav-button", props.class)}
+      onClick={props.onClick}
+    >
+      {props.direction === "previous"
+        ? <ChevronLeft size={16} aria-hidden="true" />
+        : <ChevronRight size={16} aria-hidden="true" />}
+    </button>
+  );
+}
+
+interface TodayButtonProps {
+  visible: boolean;
+  label: string;
+  class?: string;
+  onClick: () => void;
+}
+
+function TodayButton(props: TodayButtonProps) {
+  return props.visible ? (
+    <button
+      type="button"
+      class={joinClasses("ksui-month-calendar__button ksui-month-calendar__today-button", props.class)}
+      onClick={props.onClick}
+    >
+      {props.label}
+    </button>
+  ) : null;
+}
+
+function CalendarNavigation(props: CalendarNavigationProps) {
+  return (
+    <nav aria-label={props.heading} class={joinClasses("ksui-month-calendar__nav", props.navClass)}>
+      <div class="ksui-month-calendar__nav-group">
+        <NavigationIconButton
+          label={props.previousLabel}
+          class={props.previousButtonClass}
+          direction="previous"
+          onClick={props.onPreviousMonth}
+        />
+        <h2 id={props.headingId} class={joinClasses("ksui-month-calendar__heading", props.headingClass)}>
+          {props.heading}
+        </h2>
+        <NavigationIconButton
+          label={props.nextLabel}
+          class={props.nextButtonClass}
+          direction="next"
+          onClick={props.onNextMonth}
+        />
+      </div>
+      <TodayButton
+        visible={props.showTodayButton}
+        label={props.todayLabel}
+        class={props.todayButtonClass}
+        onClick={props.onToday}
+      />
+    </nav>
+  );
+}
+
+interface MonthCalendarModel {
+  headingId: string;
+  heading: () => string;
+  locale: () => string;
+  showOutsideDays: () => boolean;
+  showTodayButton: () => boolean;
+  weekdayLabels: () => string[];
+  weeks: () => MonthCalendarDayRenderProps[][];
+  previousMonth: () => void;
+  nextMonth: () => void;
+  goToToday: () => void;
+}
+
+function createMonthCalendarModel(props: MonthCalendarProps): MonthCalendarModel {
+  const id = createUniqueId();
+  const locale = () => props.locale ?? "en-US";
+  const timeZone = () => props.timeZone ?? "UTC";
+  const weekStartsOn = () => props.weekStartsOn ?? 0;
+  const showOutsideDays = () => props.showOutsideDays ?? true;
+  const showTodayButton = () => props.showTodayButton ?? true;
+  const today = createMemo(() => props.today ?? formatCivilDate(todayInTimeZone(timeZone())));
+  const month = createMemo(() => requireCivilDate(props.month, "month"));
+  const monthStart = createMemo(() => ({ ...month(), day: 1 }));
+  const headingId = `${id}-heading`;
+  const heading = createMemo(() =>
+    new Intl.DateTimeFormat(locale(), {
+      month: "long",
+      year: "numeric",
+      timeZone: "UTC",
+    }).format(new Date(Date.UTC(month().year, month().month - 1, 1))),
+  );
+  const weekdayLabels = createMemo(() => {
+    const formatter = new Intl.DateTimeFormat(locale(), { weekday: "short", timeZone: "UTC" });
+    return Array.from({ length: 7 }, (_, index) => {
+      const weekday = (weekStartsOn() + index) % 7;
+      return formatter.format(new Date(Date.UTC(2024, 0, 7 + weekday)));
+    });
+  });
+  const weeks = createMemo(() => {
+    const days = buildMonthCalendarDays(props.month, today(), weekStartsOn());
+    return Array.from({ length: 6 }, (_, weekIndex) =>
+      days.slice(weekIndex * 7, weekIndex * 7 + 7).map((day) => ({
+        ...day,
+        dayLabelId: `${id}-day-${day.date}`,
+      })),
+    );
+  });
+  const changeMonth = (offset: number) => {
+    props.onMonthChange(formatCivilDate(addCivilMonths(monthStart(), offset)));
+  };
+  const goToToday = () => {
+    const value = requireCivilDate(today(), "today");
+    props.onMonthChange(formatCivilDate({ ...value, day: 1 }));
+  };
+  return {
+    headingId,
+    heading,
+    locale,
+    showOutsideDays,
+    showTodayButton,
+    weekdayLabels,
+    weeks,
+    previousMonth: () => changeMonth(-1),
+    nextMonth: () => changeMonth(1),
+    goToToday,
+  };
+}
+
+function CalendarGrid(props: CalendarGridProps) {
+  const cells = (days: readonly MonthCalendarDayRenderProps[]) => (
+    <For each={days}>
+      {(day) => (
+        <DayCell
+          day={day}
+          locale={props.locale}
+          showOutsideDays={props.showOutsideDays}
+          cellClass={props.classes?.cell}
+          dayLabelClass={props.classes?.dayLabel}
+          renderDay={props.renderDay}
+        />
+      )}
+    </For>
+  );
+
+  return (
+    <div role="grid" aria-labelledby={props.headingId} class={joinClasses("ksui-month-calendar__grid", props.classes?.grid)}>
+      <div role="row" class={joinClasses("ksui-month-calendar__header", props.classes?.header)}>
+        <For each={props.weekdayLabels}>
+          {(label) => (
+            <div role="columnheader" class={joinClasses("ksui-month-calendar__columnheader", props.classes?.columnHeader)}>
+              {label}
+            </div>
+          )}
+        </For>
+      </div>
+      <For each={props.weeks}>
+        {(days, weekIndex) => {
+          const children = () => cells(days);
+          return (
+            <div role="row" class={joinClasses("ksui-month-calendar__week", props.classes?.week)}>
+              {props.renderWeek
+                ? props.renderWeek({ weekIndex: weekIndex(), days, children })
+                : children()}
+            </div>
+          );
+        }}
+      </For>
+    </div>
+  );
+}
+
+export default function MonthCalendar(props: MonthCalendarProps) {
+  injectCSS(STYLE_ID, MONTH_CALENDAR_CSS);
+  const model = createMonthCalendarModel(props);
+  const labels = () => resolveLabels(props.labels);
+  const classes = () => resolveClasses(props.classes);
+  return (
+    <section
+      aria-labelledby={model.headingId}
+      class={joinClasses("ksui-month-calendar", classes().root)}
+    >
+      <CalendarNavigation
+        heading={model.heading()}
+        headingId={model.headingId}
+        showTodayButton={model.showTodayButton()}
+        previousLabel={labels().previousMonth}
+        nextLabel={labels().nextMonth}
+        todayLabel={labels().today}
+        navClass={classes().nav}
+        headingClass={classes().heading}
+        previousButtonClass={classes().previousButton}
+        nextButtonClass={classes().nextButton}
+        todayButtonClass={classes().todayButton}
+        onPreviousMonth={model.previousMonth}
+        onNextMonth={model.nextMonth}
+        onToday={model.goToToday}
+      />
+      <CalendarGrid
+        headingId={model.headingId}
+        weekdayLabels={model.weekdayLabels()}
+        weeks={model.weeks()}
+        locale={model.locale()}
+        showOutsideDays={model.showOutsideDays()}
+        classes={classes()}
+        renderDay={props.renderDay}
+        renderWeek={props.renderWeek}
+      />
+    </section>
+  );
+}

package/src/index.ts

@@ -87,6 +87,27 @@ export { default as Modal, type ModalProps, type ModalSize, type ModalTone } fro
 // DataTable's date filter renders this picker.
 export { default as DatePicker, type DatePickerProps, type DateRangeValue } from "./components/base/DatePicker";
 
+export {
+  default as MonthCalendar,
+  type MonthCalendarProps,
+  type MonthCalendarDayRenderProps,
+  type MonthCalendarWeekRenderProps,
+  type MonthCalendarLabels,
+  type MonthCalendarClasses,
+} from "./components/base/MonthCalendar";
+export {
+  addCivilDays,
+  addCivilMonths,
+  buildMonthCalendarDays,
+  civilWeekday,
+  formatCivilDate,
+  parseCivilDate,
+  requireCivilDate,
+  todayInTimeZone,
+  type CivilDate,
+  type MonthCalendarDay,
+} from "./utils/month-calendar-date";
+
 export {
   default as MultiPeriodPicker,
   type MultiPeriodPickerProps,

package/src/utils/formatShortDate.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { formatShortDate } from "./formatShortDate";
+
+describe("formatShortDate", () => {
+  it("preserves date-only values across runtime timezone defaults", () => {
+    expect(formatShortDate("2026-09-10")).toBe("Sep 10, 2026");
+  });
+
+  it("uses the date component from full ISO values", () => {
+    expect(formatShortDate("2026-09-10T00:00:00.000Z")).toBe("Sep 10, 2026");
+  });
+
+  it("returns a placeholder for missing or malformed values", () => {
+    expect(formatShortDate(null)).toBe("—");
+    expect(formatShortDate("not-a-date")).toBe("—");
+  });
+});

package/src/utils/formatShortDate.ts

@@ -1,17 +1,21 @@
 // Short-date formatter for plugin remotes.
 //
 // Renders a YYYY-MM-DD (or full ISO) date string as the en-PH short form
-// (e.g. "Jan 5, 2026"). Hilinga is an Asia/Manila product, so the date part is
-// anchored at local midnight ("T00:00:00") to avoid the UTC drift that
-// toISOString would introduce. Returns an em-dash placeholder for a missing
-// value. Pure helper, no DOM, no fetch.
-
+// (e.g. "Jan 5, 2026"). Date-only values are parsed as calendar components
+// so runtime timezone defaults cannot shift their displayed day. Hilinga is an
+// Asia/Manila product, so formatting uses the canonical Manila timezone.
+// Returns an em-dash placeholder for a missing value. Pure helper, no DOM, no fetch.
 export function formatShortDate(dateStr: string | null | undefined): string {
   if (!dateStr) return "—";
   const datePart = dateStr.includes("T") ? dateStr.split("T")[0] : dateStr;
-  return new Date(datePart + "T00:00:00").toLocaleDateString("en-PH", {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(datePart);
+  if (!match) return "—";
+  const [, year, month, day] = match;
+  const date = new Date(Number(year), Number(month) - 1, Number(day));
+  return new Intl.DateTimeFormat("en-PH", {
+    timeZone: "Asia/Manila",
     year: "numeric",
     month: "short",
     day: "numeric",
-  });
+  }).format(date);
 }

package/src/utils/month-calendar-date.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  addCivilDays,
+  addCivilMonths,
+  buildMonthCalendarDays,
+  civilWeekday,
+  formatCivilDate,
+  parseCivilDate,
+  requireCivilDate,
+  todayInTimeZone,
+} from "./month-calendar-date";
+
+describe("month calendar civil dates", () => {
+  it("parses valid dates and rejects rollover dates", () => {
+    expect(parseCivilDate("2024-02-29")).toEqual({ year: 2024, month: 2, day: 29 });
+    expect(parseCivilDate("2023-02-29")).toBeNull();
+    expect(parseCivilDate("2024-2-09")).toBeNull();
+    expect(() => requireCivilDate("2024-13-01")).toThrow(TypeError);
+  });
+
+  it("uses UTC arithmetic across leap days and years", () => {
+    expect(formatCivilDate(addCivilDays({ year: 2024, month: 2, day: 28 }, 1))).toBe("2024-02-29");
+    expect(formatCivilDate(addCivilDays({ year: 2024, month: 12, day: 31 }, 1))).toBe("2025-01-01");
+    expect(addCivilMonths({ year: 2025, month: 1, day: 31 }, -1)).toEqual({ year: 2024, month: 12, day: 1 });
+    expect(civilWeekday({ year: 2026, month: 9, day: 12 })).toBe(6);
+  });
+
+  it("builds a stable six-week grid for any week start", () => {
+    const sunday = buildMonthCalendarDays("2026-09-20", "2026-09-12", 0);
+    expect(sunday).toHaveLength(42);
+    expect(sunday[0].date).toBe("2026-08-30");
+    expect(sunday[41].date).toBe("2026-10-10");
+    expect(sunday.find((day) => day.isToday)?.date).toBe("2026-09-12");
+
+    const monday = buildMonthCalendarDays("2026-09-01", "2026-09-12", 1);
+    expect(monday[0].date).toBe("2026-08-31");
+    expect(monday[6].date).toBe("2026-09-06");
+  });
+
+  it("rejects invalid weekStartsOn values", () => {
+    expect(() => buildMonthCalendarDays("2026-09-01", "2026-09-12", 7)).toThrow(RangeError);
+  });
+
+  it("derives today in the requested time zone", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-09-12T00:30:00Z"));
+    expect(todayInTimeZone("America/Los_Angeles")).toEqual({ year: 2026, month: 9, day: 11 });
+    expect(todayInTimeZone("Asia/Manila")).toEqual({ year: 2026, month: 9, day: 12 });
+    vi.useRealTimers();
+  });
+});

package/src/utils/month-calendar-date.ts

@@ -0,0 +1,106 @@
+export interface CivilDate {
+  year: number;
+  month: number;
+  day: number;
+}
+
+export interface MonthCalendarDay extends CivilDate {
+  date: string;
+  inMonth: boolean;
+  isToday: boolean;
+}
+
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DAY_MS = 86_400_000;
+
+export function formatCivilDate(date: CivilDate): string {
+  return `${String(date.year).padStart(4, "0")}-${String(date.month).padStart(2, "0")}-${String(date.day).padStart(2, "0")}`;
+}
+
+export function parseCivilDate(value: string): CivilDate | null {
+  const match = DATE_RE.exec(value);
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const stamp = Date.UTC(year, month - 1, day);
+  const parsed = new Date(stamp);
+  if (
+    parsed.getUTCFullYear() !== year ||
+    parsed.getUTCMonth() !== month - 1 ||
+    parsed.getUTCDate() !== day
+  ) {
+    return null;
+  }
+  return { year, month, day };
+}
+
+export function requireCivilDate(value: string, name = "date"): CivilDate {
+  const parsed = parseCivilDate(value);
+  if (!parsed) throw new TypeError(`${name} must be a valid YYYY-MM-DD date`);
+  return parsed;
+}
+
+export function addCivilDays(date: CivilDate, days: number): CivilDate {
+  const result = new Date(Date.UTC(date.year, date.month - 1, date.day) + days * DAY_MS);
+  return {
+    year: result.getUTCFullYear(),
+    month: result.getUTCMonth() + 1,
+    day: result.getUTCDate(),
+  };
+}
+
+export function addCivilMonths(date: CivilDate, months: number): CivilDate {
+  const monthIndex = date.year * 12 + date.month - 1 + months;
+  return {
+    year: Math.floor(monthIndex / 12),
+    month: ((monthIndex % 12) + 12) % 12 + 1,
+    day: 1,
+  };
+}
+
+export function civilWeekday(date: CivilDate): number {
+  return new Date(Date.UTC(date.year, date.month - 1, date.day)).getUTCDay();
+}
+
+export function todayInTimeZone(timeZone: string): CivilDate {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date());
+  const values = new Map(parts.map((part) => [part.type, part.value]));
+  return {
+    year: Number(values.get("year")),
+    month: Number(values.get("month")),
+    day: Number(values.get("day")),
+  };
+}
+
+export function buildMonthCalendarDays(
+  monthAnchor: string,
+  today: string,
+  weekStartsOn = 0,
+): MonthCalendarDay[] {
+  if (!Number.isInteger(weekStartsOn) || weekStartsOn < 0 || weekStartsOn > 6) {
+    throw new RangeError("weekStartsOn must be an integer from 0 through 6");
+  }
+  const month = requireCivilDate(monthAnchor, "month");
+  const current = { year: month.year, month: month.month, day: 1 };
+  const todayDate = requireCivilDate(today, "today");
+  const todayKey = formatCivilDate(todayDate);
+  const leadingDays = (civilWeekday(current) - weekStartsOn + 7) % 7;
+  const first = addCivilDays(current, -leadingDays);
+
+  return Array.from({ length: 42 }, (_, index) => {
+    const date = addCivilDays(first, index);
+    const key = formatCivilDate(date);
+    return {
+      ...date,
+      date: key,
+      inMonth: date.year === current.year && date.month === current.month,
+      isToday: key === todayKey,
+    };
+  });
+}