@olenbetong/appframe-ds 1.2.0 → 1.3.0

package/src/cutoff/utils.ts

@@ -1,276 +1,276 @@
-/*
- * Cut-off periods: the period types Synergi reports on (day, ISO week, month, quarter, year,
- * with "last sunday" variants for month and quarter) and the string form each is stored in
- * (`2026-09-21`, `2026-W38`, `2026-09`, `2026-Q3`, `2026`). Ported from
- * @olenbetong/appframe-mui, with Temporal in place of date-fns for the ISO week arithmetic.
- */
-
-import { Temporal } from "temporal-polyfill";
-
-import { getLocalizedString } from "../i18n.js";
-
-export type PeriodType = "AllDates" | "WS" | "MLD" | "MLS" | "QLD" | "QLS" | "YLD";
-export type PeriodTypeValueMap = { [K in PeriodType]: string };
-
-/** ISO week string, `2026-W38`, of a date. */
-function toISOWeek(date: Temporal.PlainDate) {
-	return `${date.yearOfWeek}-W${String(date.weekOfYear).padStart(2, "0")}`;
-}
-
-/** The Monday of an ISO week given as `2026-W38` or `2026-38`. */
-function isoWeekToDate(week: string) {
-	let [year, weekNo] = week.replace("W", "").split("-");
-	let firstOfYear = Temporal.PlainDate.from(`${year}-01-01`);
-	let daysToAdd = (Number(weekNo) - 1) * 7;
-	let firstOfWeekOne: Temporal.PlainDate;
-	if (firstOfYear.dayOfWeek <= 4) {
-		firstOfWeekOne = firstOfYear.add({ days: -firstOfYear.dayOfWeek + 1 });
-	} else {
-		firstOfWeekOne = firstOfYear.add({ days: 8 - firstOfYear.dayOfWeek });
-	}
-
-	return firstOfWeekOne.add({ days: daysToAdd });
-}
-
-/** A date from the app's own Temporal copy or a string, as this module's `PlainDate`. */
-function toPlainDate(date: Temporal.PlainDate | string) {
-	return Temporal.PlainDate.from(typeof date === "string" ? date : date.toString());
-}
-
-const now = Temporal.Now.plainDateISO();
-const nowDate = now.toString();
-const nowWeek = toISOWeek(now);
-const nowMonth = Temporal.PlainYearMonth.from(now).toString();
-const nowQuarter = `${now.year}-Q${Math.ceil(now.month / 3)}`;
-const nowYear = String(now.year);
-
-export const defaultCutOffType: PeriodType = "MLD";
-export const defaultPeriod = nowMonth;
-
-export const defaultPeriods: PeriodTypeValueMap = {
-	AllDates: nowDate,
-	WS: nowWeek,
-	MLD: nowMonth,
-	MLS: nowMonth,
-	QLD: nowQuarter,
-	QLS: nowQuarter,
-	YLD: nowYear,
-};
-
-export function getYearRange(start: number, end: number) {
-	let years: string[] = [];
-	for (let i = Math.min(start, end); i < Math.max(start, end); i++) {
-		years.push(String(i));
-	}
-
-	return years;
-}
-
-export function subMonthString(month: string, amount: number) {
-	return Temporal.PlainYearMonth.from(month).subtract({ months: amount }).toString();
-}
-
-export function getMonthRange(start: string, end: string) {
-	let startDate = Temporal.PlainYearMonth.from(start);
-	let endDate = Temporal.PlainYearMonth.from(end);
-
-	if (Temporal.PlainYearMonth.compare(startDate, endDate) > 0) {
-		throw new Error("Start month must be lower than end month");
-	}
-
-	let months: string[] = [];
-
-	while (Temporal.PlainYearMonth.compare(startDate, endDate) <= 0) {
-		months.push(startDate.toString());
-		startDate = startDate.add({ months: 1 });
-	}
-
-	return months;
-}
-
-export function subWeekString(week: string, amount: number) {
-	return toISOWeek(isoWeekToDate(week).subtract({ weeks: amount }));
-}
-
-export function getWeekRange(start: string, end: string) {
-	let startDate = isoWeekToDate(start);
-	let endDate = isoWeekToDate(end);
-
-	if (Temporal.PlainDate.compare(startDate, endDate) > 0) {
-		throw new Error("Start week must be lower than end week");
-	}
-
-	let weeks: string[] = [];
-
-	while (Temporal.PlainDate.compare(startDate, endDate) <= 0) {
-		weeks.push(toISOWeek(startDate));
-		startDate = startDate.add({ weeks: 1 });
-	}
-
-	return weeks;
-}
-
-export function subDateString(date: string, amount: number) {
-	return Temporal.PlainDate.from(date).subtract({ days: amount }).toString();
-}
-
-export function getDateRange(start: string, end: string) {
-	let startDate = Temporal.PlainDate.from(start);
-	let endDate = Temporal.PlainDate.from(end);
-
-	if (Temporal.PlainDate.compare(startDate, endDate) > 0) {
-		throw new Error("Start date must be lower than end date");
-	}
-
-	let dates: string[] = [];
-
-	while (Temporal.PlainDate.compare(startDate, endDate) <= 0) {
-		dates.push(startDate.toString());
-		startDate = startDate.add({ days: 1 });
-	}
-
-	return dates;
-}
-
-/** The period of `periodType` a date falls in, in its stored string form. */
-export function plainDateToCutOff(date: Temporal.PlainDate | string, periodType: PeriodType) {
-	let plain = toPlainDate(date);
-
-	switch (periodType) {
-		case "AllDates":
-			return plain.toString();
-		case "YLD":
-			return String(plain.year);
-		case "QLD":
-		case "QLS":
-			return `${plain.year}-Q${String(Math.ceil(plain.month / 3))}`;
-		case "MLD":
-		case "MLS":
-			return Temporal.PlainYearMonth.from(plain).toString();
-		case "WS":
-			return toISOWeek(plain);
-		default:
-			return "";
-	}
-}
-
-/** The first day of a period. */
-export function cutOffToPlainDate(cutOffType: PeriodType, period: string) {
-	switch (cutOffType) {
-		case "YLD":
-			return Temporal.PlainDate.from({ year: Number(period), month: 1, day: 1 });
-		case "QLD":
-		case "QLS": {
-			let [year, quarter] = period.split("-");
-			quarter = quarter.replace("Q", "");
-			return Temporal.PlainDate.from({ year: Number(year), month: (Number(quarter) - 1) * 3 + 1, day: 1 });
-		}
-		case "MLD":
-		case "MLS":
-			return Temporal.PlainDate.from(`${period}-01`);
-		case "WS":
-			return isoWeekToDate(period);
-		case "AllDates":
-			return Temporal.PlainDate.from(period);
-		default:
-			return Temporal.Now.plainDateISO();
-	}
-}
-
-const culture = (globalThis as { af?: { userSession?: { culture?: string } } }).af?.userSession?.culture ?? "en-GB";
-
-/** A label for a period in the user's culture: "september 2026", "Week 38", "Q3 2026". */
-export function getPeriodLabel(periodType: PeriodType, period: string | null | undefined) {
-	if (!period) return "";
-
-	switch (periodType) {
-		case "YLD":
-			return String(period);
-		case "QLD":
-		case "QLS": {
-			let [year, quarter] = period.split("-");
-			return `${quarter} ${year}`;
-		}
-		case "MLD":
-		case "MLS": {
-			let month = Temporal.PlainDate.from(`${period}-01`);
-			return month.toLocaleString(culture, { month: "long", year: "numeric" });
-		}
-		case "WS": {
-			const [, week] = period.replace("-W", "-").split("-");
-			return `${getLocalizedString("Week")} ${Number(week)}`;
-		}
-		case "AllDates": {
-			let date = Temporal.PlainDate.from(period);
-			return date.toLocaleString(culture, { weekday: "long", day: "numeric", month: "short" });
-		}
-		default:
-			return "";
-	}
-}
-
-export function isPeriodValidForCoType(coType: PeriodType, period: string) {
-	switch (coType) {
-		case "AllDates":
-			return /^\d{4}-\d{2}-\d{2}$/.test(period);
-		case "WS":
-			return /^\d{4}-W\d{2}$/.test(period);
-		case "MLD":
-		case "MLS":
-			return /^\d{4}-\d{2}$/.test(period);
-		case "QLD":
-		case "QLS":
-			return /^\d{4}-Q[1234]$/.test(period);
-		case "YLD":
-			return /^\d{4}$/.test(period);
-		default:
-			return false;
-	}
-}
-
-/** Where a history range for a period starts: five years, two years, twelve months, 26 weeks or 31 days back. */
-export function getHistoryRangeStart(cutOffType: PeriodType, period: string) {
-	switch (cutOffType) {
-		case "YLD":
-			return String(Number(period) - 5);
-		case "QLD":
-		case "QLS": {
-			// Two years back, same quarter: "2026-Q3" -> "2024-Q3". (The appframe-mui original
-			// produced "2024-QQ3" here.)
-			let year = Number(period.substring(0, 4)) - 2;
-			return `${year}-${period.substring(5)}`;
-		}
-		case "MLD":
-		case "MLS":
-			return subMonthString(period, 12);
-		case "WS":
-			return subWeekString(period, 26);
-		case "AllDates":
-			return subDateString(period, 31);
-		default:
-			return "";
-	}
-}
-
-export function stringToCutOffType(coType: string | null): PeriodType {
-	if (!coType || !["AllDates", "WS", "MLS", "MLD", "QLS", "QLD", "YLD"].includes(coType)) {
-		return defaultCutOffType;
-	}
-
-	return coType as PeriodType;
-}
-
-/** The cut-off in the `co` and `period` search parameters, defaults for what is missing or invalid. */
-export function getCutOffFromSearchParams(searchParams: URLSearchParams) {
-	let coType = stringToCutOffType(searchParams.get("co"));
-	let period = searchParams.get("period") ?? defaultPeriods[coType];
-
-	if (!isPeriodValidForCoType(coType, period)) {
-		period = defaultPeriods[coType];
-	}
-
-	return {
-		coType,
-		period: period.replace("W", ""), // Appframe stores weeks without the W
-	};
-}
+/*
+ * Cut-off periods: the period types Synergi reports on (day, ISO week, month, quarter, year,
+ * with "last sunday" variants for month and quarter) and the string form each is stored in
+ * (`2026-09-21`, `2026-W38`, `2026-09`, `2026-Q3`, `2026`). Ported from
+ * @olenbetong/appframe-mui, with Temporal in place of date-fns for the ISO week arithmetic.
+ */
+
+import { Temporal } from "temporal-polyfill";
+
+import { getLocalizedString } from "../i18n.js";
+
+export type PeriodType = "AllDates" | "WS" | "MLD" | "MLS" | "QLD" | "QLS" | "YLD";
+export type PeriodTypeValueMap = { [K in PeriodType]: string };
+
+/** ISO week string, `2026-W38`, of a date. */
+function toISOWeek(date: Temporal.PlainDate) {
+	return `${date.yearOfWeek}-W${String(date.weekOfYear).padStart(2, "0")}`;
+}
+
+/** The Monday of an ISO week given as `2026-W38` or `2026-38`. */
+function isoWeekToDate(week: string) {
+	let [year, weekNo] = week.replace("W", "").split("-");
+	let firstOfYear = Temporal.PlainDate.from(`${year}-01-01`);
+	let daysToAdd = (Number(weekNo) - 1) * 7;
+	let firstOfWeekOne: Temporal.PlainDate;
+	if (firstOfYear.dayOfWeek <= 4) {
+		firstOfWeekOne = firstOfYear.add({ days: -firstOfYear.dayOfWeek + 1 });
+	} else {
+		firstOfWeekOne = firstOfYear.add({ days: 8 - firstOfYear.dayOfWeek });
+	}
+
+	return firstOfWeekOne.add({ days: daysToAdd });
+}
+
+/** A date from the app's own Temporal copy or a string, as this module's `PlainDate`. */
+function toPlainDate(date: Temporal.PlainDate | string) {
+	return Temporal.PlainDate.from(typeof date === "string" ? date : date.toString());
+}
+
+const now = Temporal.Now.plainDateISO();
+const nowDate = now.toString();
+const nowWeek = toISOWeek(now);
+const nowMonth = Temporal.PlainYearMonth.from(now).toString();
+const nowQuarter = `${now.year}-Q${Math.ceil(now.month / 3)}`;
+const nowYear = String(now.year);
+
+export const defaultCutOffType: PeriodType = "MLD";
+export const defaultPeriod = nowMonth;
+
+export const defaultPeriods: PeriodTypeValueMap = {
+	AllDates: nowDate,
+	WS: nowWeek,
+	MLD: nowMonth,
+	MLS: nowMonth,
+	QLD: nowQuarter,
+	QLS: nowQuarter,
+	YLD: nowYear,
+};
+
+export function getYearRange(start: number, end: number) {
+	let years: string[] = [];
+	for (let i = Math.min(start, end); i < Math.max(start, end); i++) {
+		years.push(String(i));
+	}
+
+	return years;
+}
+
+export function subMonthString(month: string, amount: number) {
+	return Temporal.PlainYearMonth.from(month).subtract({ months: amount }).toString();
+}
+
+export function getMonthRange(start: string, end: string) {
+	let startDate = Temporal.PlainYearMonth.from(start);
+	let endDate = Temporal.PlainYearMonth.from(end);
+
+	if (Temporal.PlainYearMonth.compare(startDate, endDate) > 0) {
+		throw new Error("Start month must be lower than end month");
+	}
+
+	let months: string[] = [];
+
+	while (Temporal.PlainYearMonth.compare(startDate, endDate) <= 0) {
+		months.push(startDate.toString());
+		startDate = startDate.add({ months: 1 });
+	}
+
+	return months;
+}
+
+export function subWeekString(week: string, amount: number) {
+	return toISOWeek(isoWeekToDate(week).subtract({ weeks: amount }));
+}
+
+export function getWeekRange(start: string, end: string) {
+	let startDate = isoWeekToDate(start);
+	let endDate = isoWeekToDate(end);
+
+	if (Temporal.PlainDate.compare(startDate, endDate) > 0) {
+		throw new Error("Start week must be lower than end week");
+	}
+
+	let weeks: string[] = [];
+
+	while (Temporal.PlainDate.compare(startDate, endDate) <= 0) {
+		weeks.push(toISOWeek(startDate));
+		startDate = startDate.add({ weeks: 1 });
+	}
+
+	return weeks;
+}
+
+export function subDateString(date: string, amount: number) {
+	return Temporal.PlainDate.from(date).subtract({ days: amount }).toString();
+}
+
+export function getDateRange(start: string, end: string) {
+	let startDate = Temporal.PlainDate.from(start);
+	let endDate = Temporal.PlainDate.from(end);
+
+	if (Temporal.PlainDate.compare(startDate, endDate) > 0) {
+		throw new Error("Start date must be lower than end date");
+	}
+
+	let dates: string[] = [];
+
+	while (Temporal.PlainDate.compare(startDate, endDate) <= 0) {
+		dates.push(startDate.toString());
+		startDate = startDate.add({ days: 1 });
+	}
+
+	return dates;
+}
+
+/** The period of `periodType` a date falls in, in its stored string form. */
+export function plainDateToCutOff(date: Temporal.PlainDate | string, periodType: PeriodType) {
+	let plain = toPlainDate(date);
+
+	switch (periodType) {
+		case "AllDates":
+			return plain.toString();
+		case "YLD":
+			return String(plain.year);
+		case "QLD":
+		case "QLS":
+			return `${plain.year}-Q${String(Math.ceil(plain.month / 3))}`;
+		case "MLD":
+		case "MLS":
+			return Temporal.PlainYearMonth.from(plain).toString();
+		case "WS":
+			return toISOWeek(plain);
+		default:
+			return "";
+	}
+}
+
+/** The first day of a period. */
+export function cutOffToPlainDate(cutOffType: PeriodType, period: string) {
+	switch (cutOffType) {
+		case "YLD":
+			return Temporal.PlainDate.from({ year: Number(period), month: 1, day: 1 });
+		case "QLD":
+		case "QLS": {
+			let [year, quarter] = period.split("-");
+			quarter = quarter.replace("Q", "");
+			return Temporal.PlainDate.from({ year: Number(year), month: (Number(quarter) - 1) * 3 + 1, day: 1 });
+		}
+		case "MLD":
+		case "MLS":
+			return Temporal.PlainDate.from(`${period}-01`);
+		case "WS":
+			return isoWeekToDate(period);
+		case "AllDates":
+			return Temporal.PlainDate.from(period);
+		default:
+			return Temporal.Now.plainDateISO();
+	}
+}
+
+const culture = (globalThis as { af?: { userSession?: { culture?: string } } }).af?.userSession?.culture ?? "en-GB";
+
+/** A label for a period in the user's culture: "september 2026", "Week 38", "Q3 2026". */
+export function getPeriodLabel(periodType: PeriodType, period: string | null | undefined) {
+	if (!period) return "";
+
+	switch (periodType) {
+		case "YLD":
+			return String(period);
+		case "QLD":
+		case "QLS": {
+			let [year, quarter] = period.split("-");
+			return `${quarter} ${year}`;
+		}
+		case "MLD":
+		case "MLS": {
+			let month = Temporal.PlainDate.from(`${period}-01`);
+			return month.toLocaleString(culture, { month: "long", year: "numeric" });
+		}
+		case "WS": {
+			const [, week] = period.replace("-W", "-").split("-");
+			return `${getLocalizedString("Week")} ${Number(week)}`;
+		}
+		case "AllDates": {
+			let date = Temporal.PlainDate.from(period);
+			return date.toLocaleString(culture, { weekday: "long", day: "numeric", month: "short" });
+		}
+		default:
+			return "";
+	}
+}
+
+export function isPeriodValidForCoType(coType: PeriodType, period: string) {
+	switch (coType) {
+		case "AllDates":
+			return /^\d{4}-\d{2}-\d{2}$/.test(period);
+		case "WS":
+			return /^\d{4}-W\d{2}$/.test(period);
+		case "MLD":
+		case "MLS":
+			return /^\d{4}-\d{2}$/.test(period);
+		case "QLD":
+		case "QLS":
+			return /^\d{4}-Q[1234]$/.test(period);
+		case "YLD":
+			return /^\d{4}$/.test(period);
+		default:
+			return false;
+	}
+}
+
+/** Where a history range for a period starts: five years, two years, twelve months, 26 weeks or 31 days back. */
+export function getHistoryRangeStart(cutOffType: PeriodType, period: string) {
+	switch (cutOffType) {
+		case "YLD":
+			return String(Number(period) - 5);
+		case "QLD":
+		case "QLS": {
+			// Two years back, same quarter: "2026-Q3" -> "2024-Q3". (The appframe-mui original
+			// produced "2024-QQ3" here.)
+			let year = Number(period.substring(0, 4)) - 2;
+			return `${year}-${period.substring(5)}`;
+		}
+		case "MLD":
+		case "MLS":
+			return subMonthString(period, 12);
+		case "WS":
+			return subWeekString(period, 26);
+		case "AllDates":
+			return subDateString(period, 31);
+		default:
+			return "";
+	}
+}
+
+export function stringToCutOffType(coType: string | null): PeriodType {
+	if (!coType || !["AllDates", "WS", "MLS", "MLD", "QLS", "QLD", "YLD"].includes(coType)) {
+		return defaultCutOffType;
+	}
+
+	return coType as PeriodType;
+}
+
+/** The cut-off in the `co` and `period` search parameters, defaults for what is missing or invalid. */
+export function getCutOffFromSearchParams(searchParams: URLSearchParams) {
+	let coType = stringToCutOffType(searchParams.get("co"));
+	let period = searchParams.get("period") ?? defaultPeriods[coType];
+
+	if (!isPeriodValidForCoType(coType, period)) {
+		period = defaultPeriods[coType];
+	}
+
+	return {
+		coType,
+		period: period.replace("W", ""), // Appframe stores weeks without the W
+	};
+}