@remit/ui 0.0.113 → 0.0.114

package/src/lib/event-phrase.ts

@@ -0,0 +1,228 @@
+/**
+ * A deliberately small natural-language reader for the quick-entry field.
+ *
+ * It handles the phrasings a person actually types at a calendar — a title, a
+ * day, a time, a length, and who is coming — and it reports what it consumed
+ * for each one. The point is not coverage; it is that the machine's reading is
+ * on screen, attributed to the words it came from, before anything is
+ * committed. Whatever it could not settle comes back in `unresolved`, and
+ * whatever it filled in for you comes back in `assumptions`. Both are meant to
+ * be rendered, not swallowed.
+ */
+
+export interface PhraseParse {
+	/** What is left after the day, time, length and guests are taken out. */
+	title: string;
+	/** `YYYY-MM-DD`, empty when the phrase named no day. */
+	date: string;
+	/** The words the day was read from, e.g. "friday". */
+	dateText: string;
+	/** `HH:MM` on a 24-hour clock, empty when the phrase named no time. */
+	startTime: string;
+	startTimeText: string;
+	/** Minutes; 0 when the phrase named no length. */
+	durationMinutes: number;
+	durationText: string;
+	attendees: string[];
+	attendeesText: string;
+	/** Things the phrase never said, in the words the UI should show. */
+	unresolved: string[];
+	/** Defaults applied on the reader's own authority. */
+	assumptions: string[];
+}
+
+const WEEKDAYS: Record<string, number> = {
+	sun: 0,
+	sunday: 0,
+	mon: 1,
+	monday: 1,
+	tue: 2,
+	tues: 2,
+	tuesday: 2,
+	wed: 3,
+	weds: 3,
+	wednesday: 3,
+	thu: 4,
+	thur: 4,
+	thurs: 4,
+	thursday: 4,
+	fri: 5,
+	friday: 5,
+	sat: 6,
+	saturday: 6,
+};
+
+const WEEKDAY_ALTERNATION = Object.keys(WEEKDAYS)
+	.sort((a, b) => b.length - a.length)
+	.join("|");
+
+const DURATION_RE =
+	/\b(?:for\s+)?(\d+(?:[.,]\d+)?)\s*(hours|hour|hrs|hr|h|minutes|minute|mins|min|m)\b/i;
+const CLOCK_RE =
+	/\b(\d{1,2})(?:[:.](\d{2}))?\s*(am|pm)\b|\b(\d{1,2}):(\d{2})\b/i;
+const NOON_RE = /\b(noon|midday|midnight)\b/i;
+const RELATIVE_DAY_RE = /\b(today|tonight|tomorrow)\b/i;
+const NEXT_WEEKDAY_RE = new RegExp(
+	`\\bnext\\s+(${WEEKDAY_ALTERNATION})\\b`,
+	"i",
+);
+const WEEKDAY_RE = new RegExp(`\\b(?:on\\s+)?(${WEEKDAY_ALTERNATION})\\b`, "i");
+const WITH_RE = /\bwith\s+(.+)$/i;
+
+function pad(n: number): string {
+	return String(n).padStart(2, "0");
+}
+
+function isoDate(d: Date): string {
+	return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+function addDays(d: Date, days: number): Date {
+	const next = new Date(d);
+	next.setDate(next.getDate() + days);
+	return next;
+}
+
+/** The soonest day with this weekday, today included. */
+function comingWeekday(now: Date, weekday: number): Date {
+	return addDays(now, (weekday - now.getDay() + 7) % 7);
+}
+
+function minutesFrom(amount: number, unit: string): number {
+	const isHours = /^h/i.test(unit);
+	return Math.round(isHours ? amount * 60 : amount);
+}
+
+function cut(source: string, match: RegExpMatchArray): string {
+	const at = match.index ?? 0;
+	return `${source.slice(0, at)} ${source.slice(at + match[0].length)}`;
+}
+
+function tidy(text: string): string {
+	return text
+		.replace(/\s+/g, " ")
+		.replace(/^[\s,;–-]+|[\s,;–-]+$/g, "")
+		.replace(/\s+(on|at|with|for|from)$/i, "")
+		.trim();
+}
+
+function splitNames(clause: string): string[] {
+	return clause
+		.split(/\s*(?:,|\band\b|&)\s*/i)
+		.map((name) => tidy(name))
+		.filter((name) => name.length > 0);
+}
+
+function readClock(match: RegExpMatchArray): string {
+	if (match[3]) {
+		const meridiem = match[3].toLowerCase();
+		const hour12 = Number(match[1]) % 12;
+		const hour = meridiem === "pm" ? hour12 + 12 : hour12;
+		return `${pad(hour)}:${pad(Number(match[2] ?? 0))}`;
+	}
+	return `${pad(Number(match[4]))}:${pad(Number(match[5]))}`;
+}
+
+/**
+ * Reads `phrase` against `now`. `now` is a parameter rather than a call to the
+ * clock so the same phrase always gives the same answer in a story and a test.
+ */
+export function parseEventPhrase(phrase: string, now: Date): PhraseParse {
+	let rest = ` ${phrase} `;
+	const unresolved: string[] = [];
+	const assumptions: string[] = [];
+
+	let durationMinutes = 0;
+	let durationText = "";
+	const duration = rest.match(DURATION_RE);
+	if (duration) {
+		durationMinutes = minutesFrom(
+			Number(duration[1].replace(",", ".")),
+			duration[2],
+		);
+		durationText = duration[0].trim();
+		rest = cut(rest, duration);
+	}
+
+	let startTime = "";
+	let startTimeText = "";
+	const named = rest.match(NOON_RE);
+	const clock = rest.match(CLOCK_RE);
+	if (named) {
+		const word = named[1].toLowerCase();
+		startTime = word === "midnight" ? "00:00" : "12:00";
+		startTimeText = named[0].trim();
+		rest = cut(rest, named);
+	} else if (clock) {
+		startTime = readClock(clock);
+		startTimeText = clock[0].trim();
+		rest = cut(rest, clock);
+	}
+
+	let date = "";
+	let dateText = "";
+	const relative = rest.match(RELATIVE_DAY_RE);
+	const nextWeekday = rest.match(NEXT_WEEKDAY_RE);
+	const weekday = rest.match(WEEKDAY_RE);
+	if (relative) {
+		const word = relative[1].toLowerCase();
+		date = isoDate(word === "tomorrow" ? addDays(now, 1) : now);
+		dateText = relative[0].trim();
+		rest = cut(rest, relative);
+	} else if (nextWeekday) {
+		date = isoDate(
+			addDays(comingWeekday(now, WEEKDAYS[nextWeekday[1].toLowerCase()]), 7),
+		);
+		dateText = nextWeekday[0].trim();
+		rest = cut(rest, nextWeekday);
+	} else if (weekday) {
+		date = isoDate(comingWeekday(now, WEEKDAYS[weekday[1].toLowerCase()]));
+		dateText = weekday[0].trim();
+		rest = cut(rest, weekday);
+	}
+
+	let attendees: string[] = [];
+	let attendeesText = "";
+	const guests = tidy(rest).match(WITH_RE);
+	if (guests) {
+		attendees = splitNames(guests[1]);
+		attendeesText = guests[0].trim();
+		rest = tidy(rest).slice(0, guests.index ?? 0);
+	}
+
+	const title = tidy(rest);
+
+	if (title === "") unresolved.push("No title yet");
+	if (date === "") {
+		date = isoDate(now);
+		assumptions.push("No day given — using today");
+	}
+	if (startTime === "") {
+		unresolved.push("No time given");
+	} else if (durationMinutes === 0) {
+		durationMinutes = 60;
+		assumptions.push("No length given — using an hour");
+	}
+
+	return {
+		title,
+		date,
+		dateText,
+		startTime,
+		startTimeText,
+		durationMinutes,
+		durationText,
+		attendees,
+		attendeesText,
+		unresolved,
+		assumptions,
+	};
+}
+
+/** `13:00` + 90 → `14:30`. Empty in, empty out. */
+export function addMinutesToClock(clock: string, minutes: number): string {
+	if (clock === "") return "";
+	const [hours, mins] = clock.split(":").map(Number);
+	const total = (hours * 60 + mins + minutes) % 1440;
+	return `${pad(Math.floor(total / 60))}:${pad(total % 60)}`;
+}

package/src/lib/recurrence.test.ts

@@ -0,0 +1,141 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	type CustomRecurrence,
+	dayOfMonthLabel,
+	defaultCustomRecurrence,
+	defaultEndDate,
+	formatCustomRecurrence,
+	ordinalWeekdayLabel,
+	readCustomRecurrence,
+	repeatChoices,
+} from "./recurrence.js";
+
+/** Thursday 11 June 2026. */
+const DATE = "2026-06-11";
+
+const rule = (patch: Partial<CustomRecurrence> = {}): CustomRecurrence => ({
+	...defaultCustomRecurrence(DATE),
+	...patch,
+});
+
+describe("repeatChoices", () => {
+	it("derives the monthly choice from the date's own weekday", () => {
+		assert.ok(
+			repeatChoices(DATE, "").includes("Every month on the second Thursday"),
+		);
+	});
+
+	it("appends the hour when there is one", () => {
+		assert.ok(repeatChoices(DATE, "09:15").includes("Every day, 09:15"));
+	});
+
+	it("offers weekdays only when the date is one", () => {
+		assert.ok(!repeatChoices("2026-06-13", "").includes("Every weekday"));
+	});
+});
+
+describe("defaultCustomRecurrence", () => {
+	it("starts on the event's own weekday", () => {
+		assert.deepEqual(defaultCustomRecurrence(DATE).weekdays, [4]);
+	});
+
+	it("survives a date it cannot read", () => {
+		assert.deepEqual(defaultCustomRecurrence("").weekdays, []);
+	});
+});
+
+describe("formatCustomRecurrence", () => {
+	it("reads a rule in words, never as an RRULE", () => {
+		const text = formatCustomRecurrence(
+			rule({
+				interval: 2,
+				weekdays: [1, 4],
+				ends: { kind: "onDate", date: "2026-10-03" },
+			}),
+			DATE,
+			"",
+		);
+		assert.equal(text, "Every 2 weeks on Monday and Thursday, until 3 October");
+	});
+
+	it("drops the interval when it is one", () => {
+		assert.equal(
+			formatCustomRecurrence(rule({ weekdays: [4] }), DATE, ""),
+			"Every week on Thursday",
+		);
+	});
+
+	it("counts an ending that is counted", () => {
+		assert.equal(
+			formatCustomRecurrence(
+				rule({ unit: "day", ends: { kind: "afterCount", count: 13 } }),
+				DATE,
+				"",
+			),
+			"Every day, 13 times",
+		);
+	});
+
+	it("says which of the two monthly readings is meant", () => {
+		assert.equal(
+			formatCustomRecurrence(rule({ unit: "month" }), DATE, ""),
+			"Every month on day 11",
+		);
+		assert.equal(
+			formatCustomRecurrence(
+				rule({ unit: "month", monthlyMode: "weekdayOfMonth" }),
+				DATE,
+				"",
+			),
+			"Every month on the second Thursday",
+		);
+	});
+
+	it("carries the hour", () => {
+		assert.equal(
+			formatCustomRecurrence(rule({ unit: "year" }), DATE, "09:15"),
+			"Every year on 11 June, 09:15",
+		);
+	});
+});
+
+describe("readCustomRecurrence", () => {
+	for (const seed of [
+		rule({ interval: 2, weekdays: [1, 4] }),
+		rule({ interval: 3, unit: "day" }),
+		rule({ unit: "month", monthlyMode: "weekdayOfMonth" }),
+		rule({ unit: "year" }),
+		rule({ weekdays: [0, 2, 6], ends: { kind: "afterCount", count: 13 } }),
+		rule({ ends: { kind: "onDate", date: "2026-10-03" } }),
+	])
+		it(`reopens on "${formatCustomRecurrence(seed, DATE, "")}"`, () => {
+			const text = formatCustomRecurrence(seed, DATE, "09:15");
+			const read = readCustomRecurrence(text, DATE);
+			assert.ok(read);
+			assert.equal(formatCustomRecurrence(read, DATE, "09:15"), text);
+		});
+
+	it("declines a sentence it did not write", () => {
+		assert.equal(readCustomRecurrence("Every weekday, 09:15", DATE), undefined);
+		assert.equal(
+			readCustomRecurrence("whenever Jane is free", DATE),
+			undefined,
+		);
+		assert.equal(
+			readCustomRecurrence("Every week on Blursday", DATE),
+			undefined,
+		);
+	});
+});
+
+describe("labels", () => {
+	it("offers an end date a year out", () => {
+		assert.equal(defaultEndDate(DATE), "2027-06-11");
+	});
+
+	it("names the two readings of the same day", () => {
+		assert.equal(dayOfMonthLabel(DATE), "day 11");
+		assert.equal(ordinalWeekdayLabel(DATE), "the second Thursday");
+	});
+});

package/src/lib/recurrence.ts

@@ -0,0 +1,266 @@
+/**
+ * Repeat rules in the words a person would say them.
+ *
+ * A rule is carried and shown as that sentence — "Every weekday, 09:15" — and
+ * never as an RRULE the reader has to decode. The picker offers the handful of
+ * rules a date can plausibly repeat by, worked out from the date itself, so
+ * "every month" means the second Wednesday when that is the Wednesday you
+ * clicked rather than a number nobody chose.
+ */
+
+const WEEKDAY_NAMES = [
+	"Sunday",
+	"Monday",
+	"Tuesday",
+	"Wednesday",
+	"Thursday",
+	"Friday",
+	"Saturday",
+];
+
+const MONTH_NAMES = [
+	"January",
+	"February",
+	"March",
+	"April",
+	"May",
+	"June",
+	"July",
+	"August",
+	"September",
+	"October",
+	"November",
+	"December",
+];
+
+const ORDINALS = ["first", "second", "third", "fourth", "last"];
+
+/** No repeat at all — the value a one-off carries. */
+export const NO_REPEAT = "";
+
+/**
+ * The rules on offer for a date, widest interval last. `startTime` is appended
+ * when there is one, because "every weekday" without an hour is only half a
+ * rule.
+ */
+export function repeatChoices(date: string, startTime: string): string[] {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return [];
+	const [year, month, dayOfMonth] = date.split("-").map(Number);
+	const when = new Date(Date.UTC(year, month - 1, dayOfMonth));
+	const weekday = WEEKDAY_NAMES[when.getUTCDay()];
+	const ordinal = ORDINALS[Math.min(Math.floor((dayOfMonth - 1) / 7), 4)];
+	const clock = startTime === "" ? "" : `, ${startTime}`;
+	const onWeekdays = when.getUTCDay() >= 1 && when.getUTCDay() <= 5;
+
+	return [
+		`Every day${clock}`,
+		...(onWeekdays ? [`Every weekday${clock}`] : []),
+		`Every week on ${weekday}${clock}`,
+		`Every month on the ${ordinal} ${weekday}${clock}`,
+		`Every year on ${dayOfMonth} ${MONTH_NAMES[month - 1]}${clock}`,
+	];
+}
+
+/* ------------------------------------------------------------------ */
+/* A rule the offered ones do not cover                                */
+/* ------------------------------------------------------------------ */
+
+export type RecurrenceUnit = "day" | "week" | "month" | "year";
+
+/**
+ * A monthly rule can mean two different things about the same date, and which
+ * one is meant is never derivable — the 14th and the second Tuesday coincide
+ * this month and diverge the next.
+ */
+export type MonthlyMode = "dayOfMonth" | "weekdayOfMonth";
+
+export type RecurrenceEnd =
+	| { kind: "never" }
+	| { kind: "onDate"; date: string }
+	| { kind: "afterCount"; count: number };
+
+export interface CustomRecurrence {
+	/** How many units between occurrences. One means every one. */
+	interval: number;
+	unit: RecurrenceUnit;
+	/** Weekday indexes, Sunday first. Read only when the unit is a week. */
+	weekdays: number[];
+	/** Read only when the unit is a month. */
+	monthlyMode: MonthlyMode;
+	ends: RecurrenceEnd;
+}
+
+/** Single-letter weekday labels, Sunday first, for a row of toggles. */
+export const WEEKDAY_INITIALS = ["S", "M", "T", "W", "T", "F", "S"];
+
+export const weekdayName = (index: number): string => WEEKDAY_NAMES[index];
+
+function parseDate(date: string): Date | undefined {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return undefined;
+	const [year, month, day] = date.split("-").map(Number);
+	return new Date(Date.UTC(year, month - 1, day));
+}
+
+/** The event's own day is what a custom rule starts from. */
+export function defaultCustomRecurrence(date: string): CustomRecurrence {
+	const when = parseDate(date);
+	return {
+		interval: 1,
+		unit: "week",
+		weekdays: when ? [when.getUTCDay()] : [],
+		monthlyMode: "dayOfMonth",
+		ends: { kind: "never" },
+	};
+}
+
+/**
+ * What the "on" ending offers before anyone picks a day: a year out, so the
+ * field reads as a date rather than as an empty box.
+ */
+export function defaultEndDate(date: string): string {
+	const when = parseDate(date);
+	if (!when) return date;
+	when.setUTCFullYear(when.getUTCFullYear() + 1);
+	return when.toISOString().slice(0, 10);
+}
+
+/** "the second Tuesday", derived from the date the event sits on. */
+export function ordinalWeekdayLabel(date: string): string {
+	const when = parseDate(date);
+	if (!when) return "";
+	const dayOfMonth = when.getUTCDate();
+	return `the ${ORDINALS[Math.min(Math.floor((dayOfMonth - 1) / 7), 4)]} ${
+		WEEKDAY_NAMES[when.getUTCDay()]
+	}`;
+}
+
+/** "day 14", the other reading of the same date. */
+export function dayOfMonthLabel(date: string): string {
+	const when = parseDate(date);
+	return when ? `day ${when.getUTCDate()}` : "";
+}
+
+/** "3 October" — an end date read the way the rule reads it back. */
+export function endDateLabel(date: string): string {
+	const when = parseDate(date);
+	return when
+		? `${when.getUTCDate()} ${MONTH_NAMES[when.getUTCMonth()]}`
+		: date;
+}
+
+function joinWords(parts: string[]): string {
+	if (parts.length <= 1) return parts.join("");
+	return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+
+/**
+ * The rule as a sentence. Everything the editor can express reads back in
+ * words — an RRULE is never shown, and never typed.
+ */
+export function formatCustomRecurrence(
+	rule: CustomRecurrence,
+	date: string,
+	startTime: string,
+): string {
+	const every =
+		rule.interval <= 1
+			? `Every ${rule.unit}`
+			: `Every ${rule.interval} ${rule.unit}s`;
+
+	let on = "";
+	if (rule.unit === "week" && rule.weekdays.length > 0)
+		on = ` on ${joinWords(
+			[...rule.weekdays].sort((a, b) => a - b).map(weekdayName),
+		)}`;
+	if (rule.unit === "month")
+		on = ` on ${
+			rule.monthlyMode === "dayOfMonth"
+				? dayOfMonthLabel(date)
+				: ordinalWeekdayLabel(date)
+		}`;
+	if (rule.unit === "year") {
+		const when = parseDate(date);
+		if (when)
+			on = ` on ${when.getUTCDate()} ${MONTH_NAMES[when.getUTCMonth()]}`;
+	}
+
+	const clock = startTime === "" ? "" : `, ${startTime}`;
+	const ends =
+		rule.ends.kind === "onDate"
+			? `, until ${endDateLabel(rule.ends.date)}`
+			: rule.ends.kind === "afterCount"
+				? `, ${rule.ends.count} times`
+				: "";
+
+	return `${every}${on}${clock}${ends}`;
+}
+
+/**
+ * The inverse of `formatCustomRecurrence`, so reopening the editor shows the
+ * rule the event already carries. A sentence it did not write — one of the
+ * offered choices, or a rule read out of a mail — returns nothing, and the
+ * editor starts from the event's own day instead.
+ */
+export function readCustomRecurrence(
+	text: string,
+	date: string,
+): CustomRecurrence | undefined {
+	let rest = text.trim();
+	let ends: RecurrenceEnd = { kind: "never" };
+
+	const times = rest.match(/,\s*(\d+) times$/);
+	if (times) {
+		ends = { kind: "afterCount", count: Number(times[1]) };
+		rest = rest.slice(0, times.index);
+	}
+
+	const until = rest.match(/,\s*until (\d{1,2}) ([A-Z][a-z]+)$/);
+	if (until) {
+		const endDate = isoForDayMonth(Number(until[1]), until[2], date);
+		if (endDate === "") return undefined;
+		ends = { kind: "onDate", date: endDate };
+		rest = rest.slice(0, until.index);
+	}
+
+	rest = rest.replace(/,\s*\d{2}:\d{2}$/, "");
+
+	const head = rest.match(
+		/^Every (?:(\d+) )?(day|week|month|year)s?(?: on (.+))?$/,
+	);
+	if (!head) return undefined;
+
+	const interval = head[1] === undefined ? 1 : Number(head[1]);
+	const unit = head[2] as RecurrenceUnit;
+	const on = head[3] ?? "";
+	const base = { ...defaultCustomRecurrence(date), interval, unit, ends };
+
+	if (unit === "week") {
+		if (on === "") return base;
+		const names = on.split(/,\s*|\s+and\s+/);
+		const weekdays = names.map((name) => WEEKDAY_NAMES.indexOf(name));
+		if (weekdays.some((index) => index === -1)) return undefined;
+		return { ...base, weekdays };
+	}
+
+	if (unit === "month") {
+		if (/^day \d{1,2}$/.test(on)) return { ...base, monthlyMode: "dayOfMonth" };
+		if (/^the \w+ [A-Z][a-z]+$/.test(on))
+			return { ...base, monthlyMode: "weekdayOfMonth" };
+		return on === "" ? base : undefined;
+	}
+
+	return base;
+}
+
+/** "3 October" against the event's own year, rolling forward if it has passed. */
+function isoForDayMonth(day: number, month: string, from: string): string {
+	const index = MONTH_NAMES.indexOf(month);
+	const start = parseDate(from);
+	if (index === -1 || !start) return "";
+	const sameYear = new Date(Date.UTC(start.getUTCFullYear(), index, day));
+	const when =
+		sameYear < start
+			? new Date(Date.UTC(start.getUTCFullYear() + 1, index, day))
+			: sameYear;
+	return when.toISOString().slice(0, 10);
+}