@olenbetong/appframe-ds 1.8.0 → 1.9.0

package/src/cutoff/context.tsx

@@ -1,194 +1,194 @@
-import type React from "react";
-import { createContext, useContext, useEffect, useReducer } from "react";
-import { useSearchParams } from "react-router";
-
-import { type CutOffDatesRecord, dsCutOffDates } from "./dsCutOffDates.js";
-import {
-	defaultCutOffType,
-	defaultPeriod,
-	defaultPeriods,
-	getCutOffFromSearchParams,
-	getHistoryRangeStart,
-	getPeriodLabel,
-	type PeriodType,
-	type PeriodTypeValueMap,
-} from "./utils.js";
-
-export type PeriodState = {
-	/** The selected period of every type, so switching type and back keeps the choice. */
-	periods: PeriodTypeValueMap;
-	/** The selected period as Appframe stores it (weeks without the W). */
-	period: string;
-	/** The selected period in ISO form (weeks as `2026-W38`). */
-	isoPeriod: string;
-	cutOffType: PeriodType;
-	/** Start of a history range ending at the period; see `getHistoryRangeStart`. */
-	historyStart: string;
-	label: string;
-	/** The period's dates from the database, once fetched (`CutOffProvider fetchPeriod`). */
-	data?: CutOffDatesRecord;
-};
-
-export type PeriodActions = {
-	setPeriod: (type: PeriodType, period: string) => void;
-	setCutOffType: (type: PeriodType) => void;
-};
-
-export const CutOffContext = createContext<PeriodState & PeriodActions>({
-	historyStart: getHistoryRangeStart(defaultCutOffType, defaultPeriod),
-	label: getPeriodLabel(defaultCutOffType, defaultPeriod),
-	periods: defaultPeriods,
-	period: defaultPeriod,
-	isoPeriod: defaultPeriod,
-	cutOffType: defaultCutOffType,
-	setPeriod: () => null,
-	setCutOffType: () => null,
-});
-
-type CutOffAction =
-	| { type: "setCutOffType"; payload: PeriodType }
-	| { type: "setPeriod"; payload: { type: PeriodType; period: string } }
-	| { type: "cutOffLoaded"; payload: CutOffDatesRecord };
-
-const periodCache = new Map<string, CutOffDatesRecord>();
-
-function cutOffReducer(state: PeriodState, action: CutOffAction): PeriodState {
-	switch (action.type) {
-		case "setPeriod": {
-			let { period, type } = action.payload;
-			let isActivePeriod = type === state.cutOffType;
-			let key = `${type}-${period}`;
-
-			return {
-				...state,
-				data: periodCache.get(key),
-				period: (isActivePeriod ? action.payload.period : state.period).replace("W", ""),
-				isoPeriod: isActivePeriod ? action.payload.period : state.period,
-				periods: {
-					...state.periods,
-					[state.cutOffType]: action.payload.period,
-				},
-				historyStart: isActivePeriod ? getHistoryRangeStart(type, period) : state.historyStart,
-				label: isActivePeriod ? getPeriodLabel(type, period) : state.label,
-			};
-		}
-		case "setCutOffType": {
-			let { payload: coType } = action;
-			let key = `${coType}-${state.periods[coType]}`;
-
-			return {
-				...state,
-				data: periodCache.get(key),
-				period: state.periods[coType].replace("W", ""),
-				isoPeriod: state.periods[coType],
-				historyStart: getHistoryRangeStart(coType, state.periods[coType]),
-				label: getPeriodLabel(coType, state.periods[coType]),
-				cutOffType: coType,
-			};
-		}
-		case "cutOffLoaded":
-			return { ...state, data: action.payload };
-		default:
-			return state;
-	}
-}
-
-function initialState(): PeriodState {
-	let { coType, period } = getCutOffFromSearchParams(new URLSearchParams(globalThis.location?.search ?? ""));
-
-	return {
-		periods: { ...defaultPeriods, [coType]: period },
-		historyStart: getHistoryRangeStart(coType, period),
-		label: getPeriodLabel(coType, period),
-		period,
-		isoPeriod: period,
-		cutOffType: coType,
-	};
-}
-
-async function getCutOffPeriod(cutOffType: PeriodType, period: string): Promise<CutOffDatesRecord | undefined> {
-	let key = `${cutOffType}-${period}`;
-	let cached = periodCache.get(key);
-	if (cached) return cached;
-	if (!dsCutOffDates) return undefined;
-
-	let result = await dsCutOffDates.retrieve({
-		maxRecords: 1,
-		filterString: `[COType] = '${cutOffType}' AND [Period] = '${period}'`,
-	});
-
-	if (result.length > 0) {
-		periodCache.set(key, result[0]);
-	}
-
-	return result[0];
-}
-
-export type CutOffProviderProps = React.PropsWithChildren<{
-	/**
-	 * Fetch the period's dates from the database when it changes. Without it `data` stays
-	 * undefined.
-	 */
-	fetchPeriod?: boolean;
-}>;
-
-/**
- * Holds the selected cut-off period for the app, initialised from the `co` and `period`
- * search parameters. Read and change it with {@link useCutOff}; let the user pick it with
- * `CutOffPicker`.
- */
-export function CutOffProvider({ children, fetchPeriod }: CutOffProviderProps) {
-	let [state, dispatch] = useReducer(cutOffReducer, undefined, initialState);
-
-	useEffect(() => {
-		if (fetchPeriod && !state.data) {
-			getCutOffPeriod(state.cutOffType, state.period)
-				.then((payload) => {
-					if (payload) dispatch({ type: "cutOffLoaded", payload });
-				})
-				.catch((error) => console.warn(String(error)));
-		}
-	}, [fetchPeriod, state.cutOffType, state.period, state.data]);
-
-	return (
-		<CutOffContext.Provider
-			value={{
-				...state,
-				setPeriod: (type, period) => dispatch({ type: "setPeriod", payload: { type, period } }),
-				setCutOffType: (type) => dispatch({ type: "setCutOffType", payload: type }),
-			}}
-		>
-			{children}
-		</CutOffContext.Provider>
-	);
-}
-
-/**
- * The selected cut-off period and the actions that change it. Keeps the `co` and `period`
- * search parameters in step with the selection unless `disableSearchParams` is set (a form
- * that submits the period itself, say).
- */
-export function useCutOff({ disableSearchParams = false }: { disableSearchParams?: boolean } = {}) {
-	let cutOff = useContext(CutOffContext);
-	let [, setSearchParams] = useSearchParams();
-
-	useEffect(() => {
-		if (!disableSearchParams) {
-			let searchParams = new URLSearchParams(window.location.search);
-			if (cutOff.period === defaultPeriods[cutOff.cutOffType]) {
-				searchParams.delete("period");
-			} else {
-				searchParams.set("period", cutOff.period);
-			}
-			if (cutOff.cutOffType === "MLD") {
-				searchParams.delete("co");
-			} else {
-				searchParams.set("co", cutOff.cutOffType);
-			}
-
-			setSearchParams(searchParams, { replace: true });
-		}
-	}, [disableSearchParams, cutOff.period, cutOff.cutOffType, setSearchParams]);
-
-	return cutOff;
-}
+import type React from "react";
+import { createContext, useContext, useEffect, useReducer } from "react";
+import { useSearchParams } from "react-router";
+
+import { type CutOffDatesRecord, dsCutOffDates } from "./dsCutOffDates.js";
+import {
+	defaultCutOffType,
+	defaultPeriod,
+	defaultPeriods,
+	getCutOffFromSearchParams,
+	getHistoryRangeStart,
+	getPeriodLabel,
+	type PeriodType,
+	type PeriodTypeValueMap,
+} from "./utils.js";
+
+export type PeriodState = {
+	/** The selected period of every type, so switching type and back keeps the choice. */
+	periods: PeriodTypeValueMap;
+	/** The selected period as Appframe stores it (weeks without the W). */
+	period: string;
+	/** The selected period in ISO form (weeks as `2026-W38`). */
+	isoPeriod: string;
+	cutOffType: PeriodType;
+	/** Start of a history range ending at the period; see `getHistoryRangeStart`. */
+	historyStart: string;
+	label: string;
+	/** The period's dates from the database, once fetched (`CutOffProvider fetchPeriod`). */
+	data?: CutOffDatesRecord;
+};
+
+export type PeriodActions = {
+	setPeriod: (type: PeriodType, period: string) => void;
+	setCutOffType: (type: PeriodType) => void;
+};
+
+export const CutOffContext = createContext<PeriodState & PeriodActions>({
+	historyStart: getHistoryRangeStart(defaultCutOffType, defaultPeriod),
+	label: getPeriodLabel(defaultCutOffType, defaultPeriod),
+	periods: defaultPeriods,
+	period: defaultPeriod,
+	isoPeriod: defaultPeriod,
+	cutOffType: defaultCutOffType,
+	setPeriod: () => null,
+	setCutOffType: () => null,
+});
+
+type CutOffAction =
+	| { type: "setCutOffType"; payload: PeriodType }
+	| { type: "setPeriod"; payload: { type: PeriodType; period: string } }
+	| { type: "cutOffLoaded"; payload: CutOffDatesRecord };
+
+const periodCache = new Map<string, CutOffDatesRecord>();
+
+function cutOffReducer(state: PeriodState, action: CutOffAction): PeriodState {
+	switch (action.type) {
+		case "setPeriod": {
+			let { period, type } = action.payload;
+			let isActivePeriod = type === state.cutOffType;
+			let key = `${type}-${period}`;
+
+			return {
+				...state,
+				data: periodCache.get(key),
+				period: (isActivePeriod ? action.payload.period : state.period).replace("W", ""),
+				isoPeriod: isActivePeriod ? action.payload.period : state.period,
+				periods: {
+					...state.periods,
+					[state.cutOffType]: action.payload.period,
+				},
+				historyStart: isActivePeriod ? getHistoryRangeStart(type, period) : state.historyStart,
+				label: isActivePeriod ? getPeriodLabel(type, period) : state.label,
+			};
+		}
+		case "setCutOffType": {
+			let { payload: coType } = action;
+			let key = `${coType}-${state.periods[coType]}`;
+
+			return {
+				...state,
+				data: periodCache.get(key),
+				period: state.periods[coType].replace("W", ""),
+				isoPeriod: state.periods[coType],
+				historyStart: getHistoryRangeStart(coType, state.periods[coType]),
+				label: getPeriodLabel(coType, state.periods[coType]),
+				cutOffType: coType,
+			};
+		}
+		case "cutOffLoaded":
+			return { ...state, data: action.payload };
+		default:
+			return state;
+	}
+}
+
+function initialState(): PeriodState {
+	let { coType, period } = getCutOffFromSearchParams(new URLSearchParams(globalThis.location?.search ?? ""));
+
+	return {
+		periods: { ...defaultPeriods, [coType]: period },
+		historyStart: getHistoryRangeStart(coType, period),
+		label: getPeriodLabel(coType, period),
+		period,
+		isoPeriod: period,
+		cutOffType: coType,
+	};
+}
+
+async function getCutOffPeriod(cutOffType: PeriodType, period: string): Promise<CutOffDatesRecord | undefined> {
+	let key = `${cutOffType}-${period}`;
+	let cached = periodCache.get(key);
+	if (cached) return cached;
+	if (!dsCutOffDates) return undefined;
+
+	let result = await dsCutOffDates.retrieve({
+		maxRecords: 1,
+		filterString: `[COType] = '${cutOffType}' AND [Period] = '${period}'`,
+	});
+
+	if (result.length > 0) {
+		periodCache.set(key, result[0]);
+	}
+
+	return result[0];
+}
+
+export type CutOffProviderProps = React.PropsWithChildren<{
+	/**
+	 * Fetch the period's dates from the database when it changes. Without it `data` stays
+	 * undefined.
+	 */
+	fetchPeriod?: boolean;
+}>;
+
+/**
+ * Holds the selected cut-off period for the app, initialised from the `co` and `period`
+ * search parameters. Read and change it with {@link useCutOff}; let the user pick it with
+ * `CutOffPicker`.
+ */
+export function CutOffProvider({ children, fetchPeriod }: CutOffProviderProps) {
+	let [state, dispatch] = useReducer(cutOffReducer, undefined, initialState);
+
+	useEffect(() => {
+		if (fetchPeriod && !state.data) {
+			getCutOffPeriod(state.cutOffType, state.period)
+				.then((payload) => {
+					if (payload) dispatch({ type: "cutOffLoaded", payload });
+				})
+				.catch((error) => console.warn(String(error)));
+		}
+	}, [fetchPeriod, state.cutOffType, state.period, state.data]);
+
+	return (
+		<CutOffContext.Provider
+			value={{
+				...state,
+				setPeriod: (type, period) => dispatch({ type: "setPeriod", payload: { type, period } }),
+				setCutOffType: (type) => dispatch({ type: "setCutOffType", payload: type }),
+			}}
+		>
+			{children}
+		</CutOffContext.Provider>
+	);
+}
+
+/**
+ * The selected cut-off period and the actions that change it. Keeps the `co` and `period`
+ * search parameters in step with the selection unless `disableSearchParams` is set (a form
+ * that submits the period itself, say).
+ */
+export function useCutOff({ disableSearchParams = false }: { disableSearchParams?: boolean } = {}) {
+	let cutOff = useContext(CutOffContext);
+	let [, setSearchParams] = useSearchParams();
+
+	useEffect(() => {
+		if (!disableSearchParams) {
+			let searchParams = new URLSearchParams(window.location.search);
+			if (cutOff.period === defaultPeriods[cutOff.cutOffType]) {
+				searchParams.delete("period");
+			} else {
+				searchParams.set("period", cutOff.period);
+			}
+			if (cutOff.cutOffType === "MLD") {
+				searchParams.delete("co");
+			} else {
+				searchParams.set("co", cutOff.cutOffType);
+			}
+
+			setSearchParams(searchParams, { replace: true });
+		}
+	}, [disableSearchParams, cutOff.period, cutOff.cutOffType, setSearchParams]);
+
+	return cutOff;
+}

package/src/cutoff/dsCutOffDates.ts

@@ -1,21 +1,21 @@
-import type { AfData } from "@olenbetong/appframe-data";
-
-export type CutOffDatesRecord = {
-	COType: string;
-	PeriodStart: Date;
-	PeriodEnd: Date;
-	Period: string;
-};
-
-/** `aviw_System_CutOffDates`: the start and end dates the database assigns to a period. */
-export const dsCutOffDates = (
-	(globalThis as { af?: { data?: AfData } }).af?.data as AfData | undefined
-)?.generateApiDataHandler?.<CutOffDatesRecord>({
-	resource: "aviw_System_CutOffDates",
-	fields: [
-		{ name: "COType", type: "string", nullable: false },
-		{ name: "PeriodStart", type: "datetime", nullable: true },
-		{ name: "PeriodEnd", type: "datetime", nullable: true },
-		{ name: "Period", type: "string", nullable: true },
-	],
-});
+import type { AfData } from "@olenbetong/appframe-data";
+
+export type CutOffDatesRecord = {
+	COType: string;
+	PeriodStart: Date;
+	PeriodEnd: Date;
+	Period: string;
+};
+
+/** `aviw_System_CutOffDates`: the start and end dates the database assigns to a period. */
+export const dsCutOffDates = (
+	(globalThis as { af?: { data?: AfData } }).af?.data as AfData | undefined
+)?.generateApiDataHandler?.<CutOffDatesRecord>({
+	resource: "aviw_System_CutOffDates",
+	fields: [
+		{ name: "COType", type: "string", nullable: false },
+		{ name: "PeriodStart", type: "datetime", nullable: true },
+		{ name: "PeriodEnd", type: "datetime", nullable: true },
+		{ name: "Period", type: "string", nullable: true },
+	],
+});

package/src/cutoff/index.ts

@@ -1,4 +1,4 @@
-export * from "./context.js";
-export * from "./CutOffPicker.js";
-export * from "./dsCutOffDates.js";
-export * from "./utils.js";
+export * from "./context.js";
+export * from "./CutOffPicker.js";
+export * from "./dsCutOffDates.js";
+export * from "./utils.js";

package/src/cutoff/utils.test.ts

@@ -1,59 +1,59 @@
-import { describe, expect, test } from "vitest";
-
-import {
-	cutOffToPlainDate,
-	getCutOffFromSearchParams,
-	getHistoryRangeStart,
-	getWeekRange,
-	isPeriodValidForCoType,
-	plainDateToCutOff,
-	subWeekString,
-} from "./utils.js";
-
-describe("cut-off periods", () => {
-	test("a date maps to every period type", () => {
-		expect(plainDateToCutOff("2026-09-21", "AllDates")).toBe("2026-09-21");
-		expect(plainDateToCutOff("2026-09-21", "WS")).toBe("2026-W39");
-		expect(plainDateToCutOff("2026-09-21", "MLD")).toBe("2026-09");
-		expect(plainDateToCutOff("2026-09-21", "QLS")).toBe("2026-Q3");
-		expect(plainDateToCutOff("2026-09-21", "YLD")).toBe("2026");
-	});
-
-	test("ISO weeks follow the ISO year, not the calendar year", () => {
-		expect(plainDateToCutOff("2026-01-01", "WS")).toBe("2026-W01");
-		expect(plainDateToCutOff("2027-01-01", "WS")).toBe("2026-W53");
-		expect(plainDateToCutOff("2024-12-30", "WS")).toBe("2025-W01");
-	});
-
-	test("a period maps back to its first day", () => {
-		expect(cutOffToPlainDate("WS", "2026-W39").toString()).toBe("2026-09-21");
-		expect(cutOffToPlainDate("WS", "2026-39").toString()).toBe("2026-09-21");
-		expect(cutOffToPlainDate("QLD", "2026-Q3").toString()).toBe("2026-07-01");
-		expect(cutOffToPlainDate("MLS", "2026-09").toString()).toBe("2026-09-01");
-		expect(cutOffToPlainDate("YLD", "2026").toString()).toBe("2026-01-01");
-	});
-
-	test("week arithmetic", () => {
-		expect(subWeekString("2026-W02", 3)).toBe("2025-W51");
-		expect(getWeekRange("2025-W52", "2026-W02")).toEqual(["2025-W52", "2026-W01", "2026-W02"]);
-	});
-
-	test("history ranges", () => {
-		expect(getHistoryRangeStart("YLD", "2026")).toBe("2021");
-		expect(getHistoryRangeStart("QLD", "2026-Q3")).toBe("2024-Q3");
-		expect(getHistoryRangeStart("MLD", "2026-09")).toBe("2025-09");
-		expect(getHistoryRangeStart("WS", "2026-W39")).toBe("2026-W13");
-		expect(getHistoryRangeStart("AllDates", "2026-09-21")).toBe("2026-08-21");
-	});
-
-	test("search parameters: defaults for missing or invalid values, weeks without the W", () => {
-		expect(getCutOffFromSearchParams(new URLSearchParams("co=WS&period=2026-W39"))).toEqual({
-			coType: "WS",
-			period: "2026-39",
-		});
-		expect(getCutOffFromSearchParams(new URLSearchParams("co=QLD&period=2026-Q7")).period).toMatch(/^\d{4}-Q[1-4]$/);
-		expect(getCutOffFromSearchParams(new URLSearchParams("co=nope")).coType).toBe("MLD");
-		expect(isPeriodValidForCoType("MLS", "2026-09")).toBe(true);
-		expect(isPeriodValidForCoType("QLS", "2026-Q2")).toBe(true);
-	});
-});
+import { describe, expect, test } from "vitest";
+
+import {
+	cutOffToPlainDate,
+	getCutOffFromSearchParams,
+	getHistoryRangeStart,
+	getWeekRange,
+	isPeriodValidForCoType,
+	plainDateToCutOff,
+	subWeekString,
+} from "./utils.js";
+
+describe("cut-off periods", () => {
+	test("a date maps to every period type", () => {
+		expect(plainDateToCutOff("2026-09-21", "AllDates")).toBe("2026-09-21");
+		expect(plainDateToCutOff("2026-09-21", "WS")).toBe("2026-W39");
+		expect(plainDateToCutOff("2026-09-21", "MLD")).toBe("2026-09");
+		expect(plainDateToCutOff("2026-09-21", "QLS")).toBe("2026-Q3");
+		expect(plainDateToCutOff("2026-09-21", "YLD")).toBe("2026");
+	});
+
+	test("ISO weeks follow the ISO year, not the calendar year", () => {
+		expect(plainDateToCutOff("2026-01-01", "WS")).toBe("2026-W01");
+		expect(plainDateToCutOff("2027-01-01", "WS")).toBe("2026-W53");
+		expect(plainDateToCutOff("2024-12-30", "WS")).toBe("2025-W01");
+	});
+
+	test("a period maps back to its first day", () => {
+		expect(cutOffToPlainDate("WS", "2026-W39").toString()).toBe("2026-09-21");
+		expect(cutOffToPlainDate("WS", "2026-39").toString()).toBe("2026-09-21");
+		expect(cutOffToPlainDate("QLD", "2026-Q3").toString()).toBe("2026-07-01");
+		expect(cutOffToPlainDate("MLS", "2026-09").toString()).toBe("2026-09-01");
+		expect(cutOffToPlainDate("YLD", "2026").toString()).toBe("2026-01-01");
+	});
+
+	test("week arithmetic", () => {
+		expect(subWeekString("2026-W02", 3)).toBe("2025-W51");
+		expect(getWeekRange("2025-W52", "2026-W02")).toEqual(["2025-W52", "2026-W01", "2026-W02"]);
+	});
+
+	test("history ranges", () => {
+		expect(getHistoryRangeStart("YLD", "2026")).toBe("2021");
+		expect(getHistoryRangeStart("QLD", "2026-Q3")).toBe("2024-Q3");
+		expect(getHistoryRangeStart("MLD", "2026-09")).toBe("2025-09");
+		expect(getHistoryRangeStart("WS", "2026-W39")).toBe("2026-W13");
+		expect(getHistoryRangeStart("AllDates", "2026-09-21")).toBe("2026-08-21");
+	});
+
+	test("search parameters: defaults for missing or invalid values, weeks without the W", () => {
+		expect(getCutOffFromSearchParams(new URLSearchParams("co=WS&period=2026-W39"))).toEqual({
+			coType: "WS",
+			period: "2026-39",
+		});
+		expect(getCutOffFromSearchParams(new URLSearchParams("co=QLD&period=2026-Q7")).period).toMatch(/^\d{4}-Q[1-4]$/);
+		expect(getCutOffFromSearchParams(new URLSearchParams("co=nope")).coType).toBe("MLD");
+		expect(isPeriodValidForCoType("MLS", "2026-09")).toBe(true);
+		expect(isPeriodValidForCoType("QLS", "2026-Q2")).toBe(true);
+	});
+});