@absolutejs/calendar 0.1.0

package/README.md

@@ -0,0 +1,13 @@
+# @absolutejs/calendar
+
+Framework-independent, date-only calendar mechanics for AbsoluteJS apps. Apps own event models, permissions, interactions and persistence.
+
+Exports: `isCalendarDate`, `addDays`, `addMonths` (clamps the day), `dateInZone`, `weekDates`, `monthDates` (42 cells), `formatCalendarDate`, and `groupByDate` (includes an undated bucket). Dates use `YYYY-MM-DD`; arithmetic and display avoid local-time/DST shifts. Week starts are configurable from Sunday (0) through Saturday (6). `dateInZone` is the explicit bridge from an instant to a calendar day.
+
+```ts
+import { monthDates, groupByDate } from '@absolutejs/calendar';
+const cells = monthDates('2026-09-24');
+const { days, undated } = groupByDate(tasks, task => task.due);
+```
+
+No provider calendars, timers, React or storage dependencies are required. Invalid date input throws for arithmetic and is retained in the undated bucket when grouping.

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/** Date-only arithmetic is UTC internally; it never treats a date as a local instant. */
+export declare function isCalendarDate(value: unknown): value is string;
+export declare function addDays(value: string, days: number): string;
+export declare function addMonths(value: string, months: number): string;
+export declare function dateInZone(now?: Date, timeZone?: string): string;
+export declare function weekDates(value: string, weekStartsOn?: number): string[];
+/** Six stable rows include adjacent-month days; default week starts Sunday. */
+export declare function monthDates(value: string, weekStartsOn?: number): string[];
+export declare function formatCalendarDate(value: string, options?: Intl.DateTimeFormatOptions, locale?: string): string;
+export declare function groupByDate<T>(items: readonly T[], getDate: (item: T) => string | null | undefined): {
+    days: Map<string, T[]>;
+    undated: T[];
+};

package/dist/index.js

@@ -0,0 +1,81 @@
+// src/index.ts
+function isCalendarDate(value) {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+    return false;
+  const d = new Date(value + "T12:00:00Z");
+  return Number.isFinite(d.getTime()) && d.toISOString().slice(0, 10) === value;
+}
+function parse(value) {
+  if (!isCalendarDate(value))
+    throw new RangeError("Invalid calendar date");
+  return new Date(value + "T12:00:00Z");
+}
+function format(date) {
+  const value = date.toISOString().slice(0, 10);
+  if (!isCalendarDate(value))
+    throw new RangeError("Calendar date out of range");
+  return value;
+}
+function addDays(value, days) {
+  if (!Number.isInteger(days))
+    throw new RangeError("Days must be an integer");
+  const d = parse(value);
+  d.setUTCDate(d.getUTCDate() + days);
+  return format(d);
+}
+function addMonths(value, months) {
+  if (!Number.isInteger(months))
+    throw new RangeError("Months must be an integer");
+  const d = parse(value), day = d.getUTCDate();
+  d.setUTCDate(1);
+  d.setUTCMonth(d.getUTCMonth() + months);
+  const last = new Date(d);
+  last.setUTCMonth(last.getUTCMonth() + 1);
+  last.setUTCDate(0);
+  d.setUTCDate(Math.min(day, last.getUTCDate()));
+  return format(d);
+}
+function dateInZone(now = new Date, timeZone = "UTC") {
+  const parts = new Intl.DateTimeFormat("en-US", { timeZone, year: "numeric", month: "2-digit", day: "2-digit" }).formatToParts(now);
+  const p = (type) => parts.find((p2) => p2.type === type).value;
+  return `${p("year")}-${p("month")}-${p("day")}`;
+}
+function weekDates(value, weekStartsOn = 0) {
+  if (!Number.isInteger(weekStartsOn) || weekStartsOn < 0 || weekStartsOn > 6)
+    throw new RangeError("Week start must be 0–6");
+  const day = parse(value).getUTCDay();
+  const first = addDays(value, -((day - weekStartsOn + 7) % 7));
+  return Array.from({ length: 7 }, (_, i) => addDays(first, i));
+}
+function monthDates(value, weekStartsOn = 0) {
+  parse(value);
+  const first = weekDates(value.slice(0, 7) + "-01", weekStartsOn)[0];
+  return Array.from({ length: 42 }, (_, i) => addDays(first, i));
+}
+function formatCalendarDate(value, options = {}, locale = "en-US") {
+  return new Intl.DateTimeFormat(locale, { ...options, timeZone: "UTC" }).format(parse(value));
+}
+function groupByDate(items, getDate) {
+  const days = new Map, undated = [];
+  for (const item of items) {
+    const date = getDate(item);
+    if (!isCalendarDate(date)) {
+      undated.push(item);
+      continue;
+    }
+    const bucket = days.get(date) ?? [];
+    bucket.push(item);
+    days.set(date, bucket);
+  }
+  return { days, undated };
+}
+export {
+  addDays,
+  addMonths,
+  dateInZone,
+  formatCalendarDate,
+  groupByDate,
+  isCalendarDate,
+  monthDates,
+  weekDates
+};

package/package.json

@@ -0,0 +1 @@
+{"name":"@absolutejs/calendar","version":"0.1.0","description":"Date-only calendar ranges and layouts for AbsoluteJS applications","type":"module","license":"MIT","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"files":["dist","README.md"],"scripts":{"build":"bun build src/index.ts --outdir dist --target browser && tsc --declaration --emitDeclarationOnly --target ES2022 --module ESNext --moduleResolution bundler --skipLibCheck --outDir dist src/index.ts","test":"bun test"},"devDependencies":{"typescript":"5.9.3","@types/bun":"^1.3.14"}}