@hearthlog/runtime 0.0.0-stage → 0.1.0

package/src/ai/decisions.ts

@@ -0,0 +1,89 @@
+import { AccessSessionExpiredError, fetchAccessProtected } from '../access/session.js';
+import { requireActiveContext } from '../db/index.js';
+import { isAiCapabilityEnabled } from '@hearthlog/contracts/tenant/config';
+import { withTimeout } from '../utils/async.js';
+import {
+    MAX_DECISION_ITEMS,
+    type AiCapability,
+    type Decision,
+    type DecisionResponse,
+} from '@hearthlog/contracts/ai/capabilities';
+
+/**
+ * Client for the same-origin decision route. It never throws: offline, a site
+ * without the capability, a 503, a timeout or an unusable answer all return no
+ * decisions (a partial batch keeps what was answered), so callers show no
+ * suggestion and the manual path is unchanged.
+ */
+
+const TIMEOUT_MS = 30_000;
+
+/** What the client got back. `answered` is false when the model could not be asked or failed. */
+export interface DecisionResult extends DecisionResponse {
+    answered: boolean;
+}
+
+const NONE: DecisionResult = { model: '', decisions: [], answered: false };
+
+export async function requestDecisions(
+    capability: AiCapability,
+    items: ReadonlyArray<{ id: string }>,
+): Promise<DecisionResult> {
+    if (items.length === 0 || !isAiCapabilityEnabled(capability)) return NONE;
+    if (typeof navigator !== 'undefined' && navigator.onLine === false) return NONE;
+    let logId: string;
+    try {
+        logId = (await requireActiveContext()).logId;
+    } catch {
+        return NONE;
+    }
+
+    let model = '';
+    let answered = false;
+    const decisions: Decision[] = [];
+    for (let start = 0; start < items.length; start += MAX_DECISION_ITEMS) {
+        const chunk = items.slice(start, start + MAX_DECISION_ITEMS);
+        const reply = await requestChunk(logId, capability, chunk);
+        // A failed chunk ends the batch: later ones would most likely fail too.
+        if (!reply) break;
+        model = reply.model;
+        decisions.push(...reply.decisions);
+        answered = true;
+    }
+    return { model, decisions, answered };
+}
+
+async function requestChunk(logId: string, capability: AiCapability, items: unknown[]): Promise<DecisionResponse | null> {
+    try {
+        const response = await withTimeout(
+            fetchAccessProtected(`/api/ai/v1/logs/${logId}/decisions/${capability}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ items }),
+            }),
+            TIMEOUT_MS,
+            'AI decision request timed out',
+        );
+        if (!response.ok) return null;
+        return parseResponse(await response.json(), items.length);
+    } catch (error) {
+        if (!(error instanceof AccessSessionExpiredError)) console.warn('[AI] Decision request failed');
+        return null;
+    }
+}
+
+function parseResponse(payload: unknown, expected: number): DecisionResponse | null {
+    const record = payload as Partial<DecisionResponse> | null;
+    if (!record || !Array.isArray(record.decisions) || record.decisions.length !== expected) return null;
+    const decisions: Decision[] = [];
+    for (const entry of record.decisions) {
+        if (
+            !entry || typeof entry.id !== 'string' || typeof entry.option !== 'string' ||
+            typeof entry.probability !== 'number' || !Number.isFinite(entry.probability)
+        ) {
+            return null;
+        }
+        decisions.push({ id: entry.id, option: entry.option, probability: entry.probability });
+    }
+    return { model: typeof record.model === 'string' ? record.model : '', decisions };
+}

package/src/calendar/draft.ts

@@ -0,0 +1,84 @@
+/**
+ * Draft helpers for the dynamic entity editor's calendar section.
+ *
+ * The editor edits one calendar date per dynamic entity (the stored config is
+ * still an array, so hand-written events may declare several). These helpers
+ * convert between the stored sources and the flat form state, and validate
+ * against the entity's field list.
+ */
+
+import {
+    validateCalendarConfig,
+    type CalendarFieldLike,
+    type EntityCalendarSource,
+} from '@hearthlog/contracts/calendar/config';
+
+export interface CalendarSourceDraft {
+    enabled: boolean;
+    dateField: string;
+    endDateField: string;
+    timeField: string;
+    titleField: string;
+    label: string;
+}
+
+export function emptyCalendarDraft(): CalendarSourceDraft {
+    return {
+        enabled: false,
+        dateField: '',
+        endDateField: '',
+        timeField: '',
+        titleField: '',
+        label: '',
+    };
+}
+
+export function draftFromCalendar(
+    calendar: readonly EntityCalendarSource[] | null | undefined,
+): CalendarSourceDraft {
+    const source = calendar?.[0];
+    if (!source) return emptyCalendarDraft();
+    return {
+        enabled: true,
+        dateField: source.dateField,
+        endDateField: source.endDateField ?? '',
+        timeField: source.timeField ?? '',
+        titleField: source.titleField ?? '',
+        label: source.label,
+    };
+}
+
+export function calendarFromDraft(
+    draft: CalendarSourceDraft,
+): EntityCalendarSource[] {
+    if (!draft.enabled || !draft.dateField) return [];
+    return [
+        {
+            dateField: draft.dateField,
+            label: draft.label.trim() || 'Event',
+            ...(draft.endDateField ? { endDateField: draft.endDateField } : {}),
+            ...(draft.timeField ? { timeField: draft.timeField } : {}),
+            ...(draft.titleField ? { titleField: draft.titleField } : {}),
+        },
+    ];
+}
+
+/**
+ * First validation error for the draft, or null when it is valid. Disabled or
+ * empty drafts are always valid (the entity simply has no calendar date).
+ */
+export function calendarDraftError(
+    draft: CalendarSourceDraft,
+    fields: readonly CalendarFieldLike[],
+): string | null {
+    if (!draft.enabled) return null;
+    if (!draft.dateField) return 'Choose a date field';
+    if (!draft.label.trim()) return 'Add a calendar label';
+    const errors = validateCalendarConfig(
+        'draft',
+        calendarFromDraft(draft),
+        fields,
+        { parentTables: new Set<string>() },
+    );
+    return errors[0] ?? null;
+}

package/src/calendar/feeds.ts

@@ -0,0 +1,91 @@
+/**
+ * Client for the Worker calendar-feed registry.
+ *
+ * Every call is same-origin and Access-authenticated. The feed token is only
+ * ever returned by `createCalendarFeed`; the listing never includes it.
+ */
+
+export interface CalendarFeedWindow {
+    pastDays: number;
+    futureDays: number;
+}
+
+export interface CalendarFeedSummary {
+    feedId: string;
+    appId: string;
+    logId: string;
+    label: string;
+    /** Source keys, or null for "all sources". */
+    sources: string[] | null;
+    windowDays: CalendarFeedWindow;
+    createdBy: string;
+    createdAt: string;
+    lastAccessedAt: string | null;
+    expiresAt: string | null;
+}
+
+export interface CreatedCalendarFeed {
+    feed: CalendarFeedSummary;
+    token: string;
+    url: string;
+}
+
+export interface CalendarFeedDraft {
+    label: string;
+    sources: string[] | null;
+    windowDays: CalendarFeedWindow;
+}
+
+const ENDPOINT = '/api/calendar-feeds/v1';
+
+export function createCalendarFeed(
+    logId: string,
+    draft: CalendarFeedDraft,
+): Promise<CreatedCalendarFeed> {
+    return request<CreatedCalendarFeed>(ENDPOINT, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ logId, ...draft }),
+    });
+}
+
+export async function listCalendarFeeds(logId: string): Promise<CalendarFeedSummary[]> {
+    const body = await request<{ feeds: CalendarFeedSummary[] }>(
+        `${ENDPOINT}?logId=${encodeURIComponent(logId)}`,
+    );
+    return body.feeds;
+}
+
+export function revokeCalendarFeed(logId: string, feedId: string): Promise<void> {
+    return request<void>(
+        `${ENDPOINT}/${encodeURIComponent(feedId)}?logId=${encodeURIComponent(logId)}`,
+        { method: 'DELETE' },
+    );
+}
+
+/** Convert the https feed URL into a `webcal://` URL for one-click subscribe. */
+export function webcalUrl(url: string): string {
+    return url.replace(/^https?:/, 'webcal:');
+}
+
+async function request<T>(path: string, init: RequestInit = {}): Promise<T> {
+    const response = await fetch(path, { credentials: 'same-origin', ...init });
+    if (!response.ok) {
+        let message = `Calendar feed request failed (${response.status})`;
+        try {
+            const body: unknown = await response.json();
+            if (
+                body &&
+                typeof body === 'object' &&
+                typeof (body as { error?: unknown }).error === 'string'
+            ) {
+                message = (body as { error: string }).error;
+            }
+        } catch {
+            // Keep the status-based message.
+        }
+        throw new Error(message);
+    }
+    if (response.status === 204) return undefined as T;
+    return (await response.json()) as T;
+}

package/src/calendar/groups.ts

@@ -0,0 +1,198 @@
+/**
+ * Calendar source groups for the page filter and the feed picker.
+ *
+ * Dates that static definitions group share a menu row. A source that is not in a built-in group
+ * (a runtime-defined entity, or a future static date) is its own row.
+ * Preferences remember what the user turned off, so a new source stays visible.
+ */
+
+import { ENTITY_DEFINITIONS } from '@hearthlog/contracts/event/entity-definitions';
+import { calendarSourceKey, normalizeCalendarSources } from '@hearthlog/contracts/calendar/config';
+
+export interface CalendarSourceRef {
+    key: string;
+    label: string;
+    dynamic: boolean;
+}
+
+/** What the user turned off. Absence, or both lists empty, means show everything. */
+export interface CalendarSourcePreference {
+    hiddenGroups: string[];
+    hiddenSources: string[];
+}
+
+const EMPTY_CALENDAR_SOURCE_PREFERENCE: CalendarSourcePreference = {
+    hiddenGroups: [],
+    hiddenSources: [],
+};
+
+export interface CalendarMenuEntry {
+    id: string;
+    label: string;
+    kind: 'group' | 'source';
+    /** Source keys this row controls. Only keys present in the current log. */
+    sourceKeys: string[];
+    icon: string;
+}
+
+/**
+ * The menu rows static definitions declare (`group` on a calendar source), in
+ * the order of their first source's rank (Events, Transactions, Invoices).
+ */
+const GROUPS: ReadonlyArray<{
+    id: string;
+    label: string;
+    keys: readonly string[];
+    icon: string;
+}> = (() => {
+    const groups = new Map<string, { id: string; label: string; keys: string[]; icon: string; rank: number }>();
+    for (const definition of ENTITY_DEFINITIONS) {
+        for (const source of normalizeCalendarSources(definition.calendar)) {
+            if (!source.group) continue;
+            const entry = groups.get(source.group.id) ?? { ...source.group, keys: [], rank: Infinity };
+            entry.keys.push(calendarSourceKey(definition.name, source));
+            entry.rank = Math.min(entry.rank, source.presentation?.rank ?? Infinity);
+            groups.set(source.group.id, entry);
+        }
+    }
+    return [...groups.values()].sort((a, b) => a.rank - b.rank);
+})();
+
+const GROUP_BY_KEY = new Map<string, (typeof GROUPS)[number]>();
+for (const group of GROUPS) {
+    for (const key of group.keys) GROUP_BY_KEY.set(key, group);
+}
+
+export function sanitizeCalendarSourcePreference(value: unknown): CalendarSourcePreference {
+    if (!value || typeof value !== 'object') return EMPTY_CALENDAR_SOURCE_PREFERENCE;
+    const record = value as Record<string, unknown>;
+    return {
+        hiddenGroups: stringList(record.hiddenGroups),
+        hiddenSources: stringList(record.hiddenSources),
+    };
+}
+
+function stringList(value: unknown): string[] {
+    if (!Array.isArray(value)) return [];
+    const seen = new Set<string>();
+    for (const item of value) {
+        if (typeof item === 'string' && item.length > 0) seen.add(item);
+    }
+    return [...seen];
+}
+
+export function calendarMenuEntries(
+    sources: readonly CalendarSourceRef[],
+): CalendarMenuEntry[] {
+    const present = new Set(sources.map((source) => source.key));
+    const entries: CalendarMenuEntry[] = [];
+    for (const group of GROUPS) {
+        const sourceKeys = group.keys.filter((key) => present.has(key));
+        if (sourceKeys.length === 0) continue;
+        entries.push({
+            id: group.id,
+            label: group.label,
+            kind: 'group',
+            sourceKeys,
+            icon: group.icon,
+        });
+    }
+    for (const source of sources) {
+        if (GROUP_BY_KEY.has(source.key)) continue;
+        entries.push({
+            id: source.key,
+            label: source.label,
+            kind: 'source',
+            sourceKeys: [source.key],
+            icon: 'calendar-blank-outline',
+        });
+    }
+    return entries;
+}
+
+function isEntryHidden(
+    entry: CalendarMenuEntry,
+    preference: CalendarSourcePreference,
+): boolean {
+    return entry.kind === 'group'
+        ? preference.hiddenGroups.includes(entry.id)
+        : preference.hiddenSources.includes(entry.id);
+}
+
+export function isCalendarMenuEntryVisible(
+    entry: CalendarMenuEntry,
+    preference: CalendarSourcePreference,
+): boolean {
+    return !isEntryHidden(entry, preference);
+}
+
+/**
+ * Preference the menu and the query should agree on. A saved filter that hides
+ * every source currently available is treated as "show all" so the month is
+ * never blank because a feature was turned off.
+ */
+export function effectiveCalendarSourcePreference(
+    sources: readonly CalendarSourceRef[],
+    preference: CalendarSourcePreference | null,
+): CalendarSourcePreference {
+    const stored = sanitizeCalendarSourcePreference(preference);
+    const entries = calendarMenuEntries(sources);
+    if (entries.length === 0) return EMPTY_CALENDAR_SOURCE_PREFERENCE;
+    const visible = entries.filter((entry) => !isEntryHidden(entry, stored));
+    if (visible.length === 0) return EMPTY_CALENDAR_SOURCE_PREFERENCE;
+    return stored;
+}
+
+/**
+ * Source keys to query. `null` means every source — the repository then omits
+ * the filter instead of enumerating keys.
+ */
+export function visibleCalendarSourceKeys(
+    sources: readonly CalendarSourceRef[],
+    preference: CalendarSourcePreference | null,
+): Set<string> | null {
+    const effective = effectiveCalendarSourcePreference(sources, preference);
+    if (effective.hiddenGroups.length === 0 && effective.hiddenSources.length === 0) {
+        return null;
+    }
+    const keys = new Set<string>();
+    for (const entry of calendarMenuEntries(sources)) {
+        if (isEntryHidden(entry, effective)) continue;
+        for (const key of entry.sourceKeys) keys.add(key);
+    }
+    if (keys.size === 0 || keys.size === sources.length) return null;
+    return keys;
+}
+
+/**
+ * Toggle one menu row. Returns null when the click would hide the last visible
+ * row or the id is unknown. Operates on the preference the menu is showing.
+ */
+export function toggleCalendarMenuEntry(
+    sources: readonly CalendarSourceRef[],
+    preference: CalendarSourcePreference | null,
+    entryId: string,
+): CalendarSourcePreference | null {
+    const current = effectiveCalendarSourcePreference(sources, preference);
+    const entries = calendarMenuEntries(sources);
+    const entry = entries.find((item) => item.id === entryId);
+    if (!entry) return null;
+    const visibleCount = entries.filter((item) => !isEntryHidden(item, current)).length;
+    const hidden = isEntryHidden(entry, current);
+    if (!hidden && visibleCount <= 1) return null;
+
+    if (entry.kind === 'group') {
+        return {
+            hiddenGroups: hidden
+                ? current.hiddenGroups.filter((id) => id !== entry.id)
+                : [...new Set([...current.hiddenGroups, entry.id])],
+            hiddenSources: [...current.hiddenSources],
+        };
+    }
+    return {
+        hiddenGroups: [...current.hiddenGroups],
+        hiddenSources: hidden
+            ? current.hiddenSources.filter((id) => id !== entry.id)
+            : [...new Set([...current.hiddenSources, entry.id])],
+    };
+}

package/src/calendar/logic.ts

@@ -0,0 +1,141 @@
+import { differenceInCalendarDays } from "date-fns";
+
+export interface CalendarEventDraft {
+    title: string;
+    eventDate: string;
+    startTime: string;
+    notes: string;
+    pinned: boolean;
+}
+
+export interface CalendarMonth {
+    year: number;
+    monthIndex: number;
+    key: string;
+}
+
+const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const MONTH_PATTERN = /^(\d{4})-(\d{2})$/;
+const TIME_PATTERN = /^(\d{2}):(\d{2})$/;
+
+function pad(value: number): string {
+    return String(value).padStart(2, "0");
+}
+
+export function toLocalDateString(date = new Date()): string {
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+export function isValidLocalDate(value: string): boolean {
+    const match = value.match(DATE_PATTERN);
+    if (!match) return false;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const parsed = new Date(year, month - 1, day, 12);
+    return parsed.getFullYear() === year &&
+        parsed.getMonth() === month - 1 &&
+        parsed.getDate() === day;
+}
+
+export function isValidStartTime(value: string): boolean {
+    if (value === "") return true;
+    const match = value.match(TIME_PATTERN);
+    return Boolean(match && Number(match[1]) <= 23 && Number(match[2]) <= 59);
+}
+
+export function validateCalendarEventDraft(
+    draft: CalendarEventDraft,
+): Record<string, string> {
+    const errors: Record<string, string> = {};
+    if (!draft.title.trim()) errors.title = "Enter an event title.";
+    if (!isValidLocalDate(draft.eventDate)) {
+        errors.eventDate = "Choose a valid event date.";
+    }
+    if (!isValidStartTime(draft.startTime)) {
+        errors.startTime = "Enter a valid time.";
+    }
+    return errors;
+}
+
+export function parseCalendarMonth(
+    value: string | null | undefined,
+    fallback = new Date(),
+): CalendarMonth {
+    const match = value?.match(MONTH_PATTERN);
+    const year = match ? Number(match[1]) : fallback.getFullYear();
+    const month = match ? Number(match[2]) : fallback.getMonth() + 1;
+    const valid = Boolean(match && year >= 1 && month >= 1 && month <= 12);
+    const resolvedYear = valid ? year : fallback.getFullYear();
+    const resolvedMonth = valid ? month : fallback.getMonth() + 1;
+    return {
+        year: resolvedYear,
+        monthIndex: resolvedMonth - 1,
+        key: `${pad(resolvedYear)}-${pad(resolvedMonth)}`,
+    };
+}
+
+export function calendarMonthBounds(month: CalendarMonth): {
+    startDate: string;
+    endDateExclusive: string;
+} {
+    const next = month.monthIndex === 11
+        ? { year: month.year + 1, month: 1 }
+        : { year: month.year, month: month.monthIndex + 2 };
+    return {
+        startDate: `${pad(month.year)}-${pad(month.monthIndex + 1)}-01`,
+        endDateExclusive: `${pad(next.year)}-${pad(next.month)}-01`,
+    };
+}
+
+/**
+ * Bounds of the visible month grid, Monday-aligned and padded to whole weeks.
+ * The calendar renders leading and trailing days, so items must be fetched for
+ * the grid span rather than the month.
+ */
+export function calendarGridBounds(month: CalendarMonth): {
+    startDate: string;
+    endDateExclusive: string;
+} {
+    const firstDay = new Date(month.year, month.monthIndex, 1, 12);
+    const offset = (firstDay.getDay() + 6) % 7;
+    const daysInMonth = new Date(month.year, month.monthIndex + 1, 0).getDate();
+    const weeks = Math.ceil((offset + daysInMonth) / 7);
+    const start = new Date(month.year, month.monthIndex, 1 - offset, 12);
+    const end = new Date(
+        start.getFullYear(),
+        start.getMonth(),
+        start.getDate() + weeks * 7,
+        12,
+    );
+    return {
+        startDate: toLocalDateString(start),
+        endDateExclusive: toLocalDateString(end),
+    };
+}
+
+function parseLocalDate(value: string): Date {
+    const [year, month, day] = value.split("-").map(Number);
+    return new Date(year, month - 1, day, 12);
+}
+
+export function daysUntilCalendarEvent(
+    eventDate: string,
+    today = new Date(),
+): number {
+    const localToday = new Date(
+        today.getFullYear(),
+        today.getMonth(),
+        today.getDate(),
+        12,
+    );
+    return differenceInCalendarDays(parseLocalDate(eventDate), localToday);
+}
+
+export function describeEventCountdown(daysUntil: number): string {
+    if (daysUntil === 0) return "Today";
+    if (daysUntil === 1) return "Tomorrow";
+    if (daysUntil > 1) return `${daysUntil} days left`;
+    if (daysUntil === -1) return "1 day ago";
+    return `${Math.abs(daysUntil)} days ago`;
+}

package/src/calendar/preferences.ts

@@ -0,0 +1,40 @@
+/**
+ * Per-log calendar source filter, stored in the existing IndexedDB key-value
+ * store. This is a view preference, not log data, so it is not an event and
+ * does not sync.
+ */
+
+import { del, get, set } from '../db/kv.js';
+import { tenant } from '@hearthlog/contracts/tenant/config';
+import {
+    sanitizeCalendarSourcePreference,
+    type CalendarSourcePreference,
+} from './groups.js';
+
+export function calendarSourcePreferenceKey(tenantId: string, logId: string): string {
+    return `calendar-sources:${tenantId}:${logId}`;
+}
+
+export async function getCalendarSourcePreference(
+    logId: string,
+): Promise<CalendarSourcePreference | null> {
+    if (!logId) return null;
+    const stored = await get<unknown>(calendarSourcePreferenceKey(tenant.id, logId));
+    if (stored == null) return null;
+    return sanitizeCalendarSourcePreference(stored);
+}
+
+export async function setCalendarSourcePreference(
+    logId: string,
+    preference: CalendarSourcePreference,
+): Promise<void> {
+    const key = calendarSourcePreferenceKey(tenant.id, logId);
+    if (preference.hiddenGroups.length === 0 && preference.hiddenSources.length === 0) {
+        await del(key);
+        return;
+    }
+    await set(key, {
+        hiddenGroups: preference.hiddenGroups,
+        hiddenSources: preference.hiddenSources,
+    } satisfies CalendarSourcePreference);
+}

package/src/calendar/weeks.ts

@@ -0,0 +1,56 @@
+import { monthKeyOf, shiftDay, shiftWeek, weekOffset, weekStartOf } from '@hearthlog/ui/utils/endless-axis.js';
+
+/** Weeks read together, so scrolling reads a block at a time instead of a week. */
+export const CHUNK_WEEKS = 6;
+
+/** Weeks listed either side of today's week; a hundred years each way feels endless. */
+export const WEEK_SPAN = 5218;
+
+/** A Monday that chunks count from, so every visit reads the same blocks. */
+const CHUNK_EPOCH = '2000-01-03';
+
+/** The given weeks widened to whole chunks, sorted. */
+export function weekChunks(weekStarts: readonly string[]): string[] {
+    const weeks = new Set<string>();
+    for (const week of weekStarts) {
+        const first = shiftWeek(CHUNK_EPOCH, Math.floor(weekOffset(week, CHUNK_EPOCH) / CHUNK_WEEKS) * CHUNK_WEEKS);
+        for (let index = 0; index < CHUNK_WEEKS; index += 1) weeks.add(shiftWeek(first, index));
+    }
+    return [...weeks].sort();
+}
+
+/** The month with the most days in the given weeks; the earlier month wins a tie. */
+export function monthInView(weekStarts: readonly string[]): string {
+    const days = new Map<string, number>();
+    for (const week of weekStarts) {
+        for (let offset = 0; offset < 7; offset += 1) {
+            const month = monthKeyOf(shiftDay(week, offset));
+            days.set(month, (days.get(month) ?? 0) + 1);
+        }
+    }
+    let best = '';
+    let most = 0;
+    for (const [month, count] of days) {
+        if (count > most) {
+            best = month;
+            most = count;
+        }
+    }
+    return best;
+}
+
+/**
+ * Where a month boundary runs along a day's cell: above each of a month's
+ * first seven days, whose cell above belongs to the month before, and
+ * before its first day unless that is a Monday. Together they draw one
+ * stepped line between months.
+ */
+export function monthEdges(day: string): { top: boolean; start: boolean } {
+    const date = Number(day.slice(8, 10));
+    return { top: date <= 7, start: date === 1 && dayColumn(day) > 0 };
+}
+
+/** A day's column in its week, 0 for Monday. */
+export function dayColumn(day: string): number {
+    return Math.round((Date.parse(day) - Date.parse(weekStartOf(day))) / 86_400_000);
+}