@react-x11/components 0.1.0 → 0.2.0

package/src/calendar/DatePicker.ts

@@ -0,0 +1,368 @@
+// <DatePicker> — a <Calendar> on a <popup>, hung off a field that shows the
+// current date. Ported from react-x11's `src/components/DatePicker.js`.
+import React, { useRef, useState } from 'react';
+import type { ReactElement } from 'react';
+import { createStyles } from 'react-x11/style';
+import type { Style, StyleProperties } from 'react-x11/style';
+import { useAnchor, useAnchorTracking, useTheme } from 'react-x11';
+import type {
+  AnchorOptions,
+  AnchorRect,
+  DrawnNode,
+  KeyboardEvent,
+} from 'react-x11';
+import { XK_DOWN, XK_ESCAPE, XK_RETURN, XK_UP } from 'react-x11/keysyms';
+
+import { hx } from '../internal/hx.js';
+import { useDismissOnWindowBlur } from '../internal/widget.js';
+import type { WidgetChangeEvent } from '../internal/widget.js';
+import { CALENDAR_HEIGHT, CALENDAR_WIDTH, Calendar } from './Calendar.js';
+import type {
+  CalendarHandle,
+  CalendarProps,
+  DateRange,
+  DateRangeInput,
+} from './Calendar.js';
+import { formatDay, formatDayRange, toDay } from './dates.js';
+import type { DayInput } from './dates.js';
+
+// A hairline round the sheet, as the menus and `Select` use: this border is
+// where the popup meets the desktop, not a control's outline, so a theme that
+// draws 2px borders on its buttons does not get a 2px frame here.
+const SHEET_BORDER = 1;
+
+/**
+ * `'@supports transparency'` is a real style block — react-x11 answers it from
+ * whether the display gave the window an ARGB visual — but its `Style` type
+ * models only the `@width`/`@height` size queries and the `:state` blocks. So
+ * the block is spelled out here rather than by augmenting `StyleBlocks`
+ * globally: this package should not quietly widen what type-checks in an app
+ * that merely installs it.
+ */
+type SupportsStyle = Style & {
+  '@supports transparency'?: StyleProperties;
+};
+
+const s = createStyles({
+  trigger: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 8,
+    padding: 8,
+    paddingLeft: 10,
+    paddingRight: 10,
+    cursor: 'pointer',
+  },
+  label: { flexGrow: 1 },
+  icon: { width: 14, height: 14, flexShrink: 0 },
+  sheet: { flexGrow: 1, flexShrink: 1, borderWidth: SHEET_BORDER },
+});
+
+/** A wall calendar, 14×14: the page, its two hangers and the ruled week. */
+function CalendarGlyph({ color }: { color: string }): ReactElement {
+  return hx('canvas', {
+    style: s.icon,
+    onDraw: (ctx, { width, height }) => {
+      ctx.strokeStyle = color;
+      ctx.lineWidth = 1;
+      ctx.strokeRect(0.5, 2.5, width - 1, height - 3);
+      ctx.beginPath();
+      ctx.moveTo(0.5, 6.5);
+      ctx.lineTo(width - 0.5, 6.5);
+      ctx.moveTo(4.5, 0.5);
+      ctx.lineTo(4.5, 3.5);
+      ctx.moveTo(width - 4.5, 0.5);
+      ctx.lineTo(width - 4.5, 3.5);
+      ctx.stroke();
+    },
+  });
+}
+
+/** What the trigger says, when the app has not said it itself. */
+function defaultFormat(
+  mode: string,
+  value: unknown,
+  locale: string | undefined,
+): string | null {
+  if (mode === 'range') {
+    const range = (value ?? {}) as DateRangeInput;
+    const start = toDay(range.start);
+    const end = toDay(range.end);
+    if (!start) return null;
+    if (!end) return `${formatDay(start, locale)} → …`;
+    return formatDayRange(start, end, locale);
+  }
+  const day = toDay(value as DayInput);
+  return day ? formatDay(day, locale) : null;
+}
+
+type PickerOwnProps = {
+  /** What the trigger shows. Defaults to the locale's medium date, and
+   *  `Intl`'s own range format when there are two of them. */
+  format?: (value: unknown) => string | null;
+  /** Shown when nothing is picked yet. */
+  placeholder?: string;
+  disabled?: boolean;
+  style?: Style | Style[];
+};
+
+/**
+ * `Omit` over a union collapses it into one member, which would cost the
+ * picker the thing that makes it pleasant to use: `mode` discriminating
+ * single from range, and with it the type of the `onChange` parameter. So the
+ * omit is distributed across the union instead, and `<DatePicker mode="range"
+ * onChange={(ev) => …}>` still knows `ev.value` is a `DateRange`.
+ */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown
+  ? Omit<T, K>
+  : never;
+
+export type DatePickerProps = DistributiveOmit<
+  CalendarProps,
+  'focusable' | 'focusVisible' | 'ref' | 'style'
+> &
+  PickerOwnProps;
+
+/**
+ * <DatePicker value onChange …boxProps> — a `<Calendar>` on a `<popup>`, hung
+ * off a field that shows the current date.
+ *
+ *   <DatePicker value={day} onChange={(ev) => setDay(ev.value)} />
+ *   <DatePicker mode="range" value={span} onChange={…} max="2026-12-31" />
+ *
+ * Every calendar prop passes straight through — `mode`, `min`/`max`,
+ * `isDateBlocked`, `spanBlocked`, `dayContent`, `locale`, `weekStartsOn` — and
+ * the value has the same shape here as there: a `'YYYY-MM-DD'` day, or
+ * `{ start, end }` in range mode.
+ *
+ * The calendar opens on the **press**, not the release, for the reason
+ * `Select`'s menu does: a control whose whole purpose is to be looked at has
+ * nothing to gain from waiting out the length of the click. It closes when the
+ * value is complete — the day in single mode, the second end of a range — on
+ * Escape, on a second press of the trigger, and when the window loses focus.
+ *
+ * The popup is override-redirect and never takes focus, so the **trigger keeps
+ * the keyboard** and hands the calendar its keys: Down/Up/Enter/Space open it,
+ * and once it is open everything the grid understands (arrows, Home/End,
+ * PageUp/PageDown, Enter, Space) goes there. Escape and Tab stay here, which
+ * is why `handleKey` reports whether it took the key.
+ *
+ * `format(value)` is the seam for the label: the default is the locale's
+ * medium date, and `Intl`'s own range format when there are two of them, which
+ * collapses the parts the ends share ("7 – 12 Aug 2026").
+ */
+export function DatePicker(props: DatePickerProps): ReactElement {
+  const {
+    mode = 'single',
+    value,
+    defaultValue,
+    onChange,
+    name,
+    month,
+    defaultMonth,
+    onMonthChange,
+    min,
+    max,
+    isDateBlocked,
+    spanBlocked,
+    dayContent,
+    locale,
+    weekStartsOn,
+    format,
+    placeholder,
+    disabled = false,
+    style,
+    ...boxProps
+  } = props as DatePickerProps & {
+    mode?: string;
+    value?: unknown;
+    defaultValue?: unknown;
+    onChange?: (ev: WidgetChangeEvent<unknown>) => void;
+  };
+
+  const theme = useTheme();
+  const [open, setOpen] = useState(false);
+  // `AnchorRect` rather than `Rect`: `useAnchorTracking` reports the side the
+  // sheet actually landed on (react-x11#280), and its `setRect` is typed to
+  // hand that back. Nothing here reads `placement` — the sheet has no arrow
+  // to aim — but the state has to be able to hold it.
+  const [anchor, setAnchor] = useState<AnchorRect | null>(null);
+  const [focused, setFocused] = useState(false);
+  const [ownValue, setOwnValue] = useState<unknown>(defaultValue ?? null);
+  const triggerRef = useRef<DrawnNode | null>(null);
+  const calendarRef = useRef<CalendarHandle | null>(null);
+
+  const measureAnchor = useAnchor(triggerRef);
+  const current = value === undefined ? ownValue : value;
+
+  const width = CALENDAR_WIDTH + SHEET_BORDER * 2;
+  const height = CALENDAR_HEIGHT + SHEET_BORDER * 2;
+  const anchorOptions = (): AnchorOptions => ({
+    placement: 'bottom',
+    width,
+    height,
+  });
+
+  const close = (): void => setOpen(false);
+  const openCalendar = (): void => {
+    const rect = measureAnchor(anchorOptions());
+    if (!rect) return;
+    setAnchor(rect);
+    setOpen(true);
+  };
+  const toggle = (): void => (open ? close() : openCalendar());
+
+  // the same two the other popups take: keep the sheet under the trigger while
+  // anything moves it, and shut it when the window itself loses focus (the
+  // trigger keeps its focus, so its own onBlur never hears about that)
+  useAnchorTracking(triggerRef, open, anchorOptions, setAnchor, close);
+  useDismissOnWindowBlur(triggerRef, open, close);
+
+  const handleChange = (ev: WidgetChangeEvent<unknown>): void => {
+    if (value === undefined) setOwnValue(ev.value);
+    onChange?.(ev);
+    // a half-picked range is the one selection that is not finished, and the
+    // calendar has to stay up for the other end of it
+    if (mode !== 'range' || (ev.value as DateRange | null)?.end) close();
+  };
+
+  const onKeyDown = (ev: KeyboardEvent): void => {
+    if (ev.keysym === XK_ESCAPE) {
+      if (open) close();
+      return;
+    }
+    if (open && calendarRef.current?.handleKey(ev)) return;
+    if (
+      ev.keysym === XK_DOWN ||
+      ev.keysym === XK_UP ||
+      ev.keysym === XK_RETURN ||
+      ev.codepoint === 32
+    ) {
+      if (!open) openCalendar();
+    }
+  };
+
+  const label = format ? format(current) : defaultFormat(mode, current, locale);
+  const empty = label == null || label === '';
+  const text = empty
+    ? (placeholder ?? (mode === 'range' ? 'Pick dates…' : 'Pick a date…'))
+    : label;
+
+  return hx(
+    'box',
+    {
+      theme,
+      role: 'combobox',
+      'aria-expanded': Boolean(open),
+      'aria-haspopup': 'dialog',
+      disabled: disabled || undefined,
+      ref: triggerRef,
+      focusable: !disabled,
+      onMouseDown: disabled ? undefined : toggle,
+      onFocus: () => setFocused(true),
+      onBlur: () => {
+        setFocused(false);
+        close();
+      },
+      onKeyDown: disabled ? undefined : onKeyDown,
+      ...boxProps,
+      style: [
+        s.trigger,
+        {
+          cursor: disabled ? 'default' : 'pointer',
+          borderWidth: theme.borderWidth,
+          borderRadius: theme.radius,
+          borderColor: focused || open ? theme.borderFocus : theme.border,
+          backgroundColor: disabled ? theme.surfaceHover : theme.background,
+        },
+        // hover and press say "this opens", so they belong to the trigger
+        // while it is shut and are simply not declared once the calendar is
+        // down — a state block always outranks the base style, so the only
+        // way for the open look to win is for nothing to be competing
+        !disabled &&
+          !open && {
+            ':hover': { backgroundColor: theme.surfaceHover },
+            ':active': { backgroundColor: theme.surfaceActive },
+          },
+        style,
+      ],
+    },
+    hx(
+      'text',
+      {
+        style: [
+          s.label,
+          { color: disabled || empty ? theme.textMuted : theme.text },
+        ],
+      },
+      text,
+    ),
+    React.createElement(CalendarGlyph, {
+      color: disabled ? theme.border : theme.textMuted,
+    }),
+    open &&
+      anchor &&
+      hx(
+        'popup',
+        {
+          theme,
+          x: anchor.x,
+          y: anchor.y,
+          width,
+          height,
+          grab: true,
+          onDismiss: close,
+          // ARGB where the display has it, so the corners the sheet gives up
+          // are the desktop rather than a colour. The window paints nothing
+          // itself when it can be seen through — the box below is the whole
+          // of the sheet, and a square fill under it would put the corners
+          // straight back.
+          transparent: true,
+          style: {
+            backgroundColor: theme.background,
+            '@supports transparency': { backgroundColor: 'transparent' },
+          } as SupportsStyle,
+        },
+        hx(
+          'box',
+          {
+            style: [
+              s.sheet,
+              {
+                borderColor: theme.border,
+                backgroundColor: theme.background,
+                '@supports transparency': { borderRadius: theme.radiusPopup },
+              } as SupportsStyle,
+            ],
+          },
+          React.createElement(Calendar, {
+            ref: calendarRef,
+            mode,
+            value: current,
+            onChange: handleChange,
+            name,
+            month,
+            defaultMonth,
+            onMonthChange,
+            min,
+            max,
+            isDateBlocked,
+            spanBlocked,
+            dayContent,
+            locale,
+            weekStartsOn,
+            // The trigger owns the keyboard: the popup is override-redirect
+            // and never takes focus, so a focusable grid inside it would take
+            // focus on the press instead — blurring the trigger, whose onBlur
+            // closes the sheet, unmounting the day under the pointer before
+            // the release could turn into a click.
+            focusable: false,
+            // …and because it does not hold the focus, it would not draw the
+            // day cursor either, leaving the arrow keys moving something
+            // invisible.
+            focusVisible: true,
+          } as CalendarProps),
+        ),
+      ),
+  );
+}

package/src/calendar/dates.ts

@@ -0,0 +1,307 @@
+// Calendar days, and the arithmetic the date widgets do on them.
+//
+// Vendored from react-x11's `src/components/dates.js` when `<Calendar>` moved
+// out here. It is pure — no renderer, no ntk, no React — which is what made
+// the move cheap, and core is expected to drop its copy. Divergence is fine
+// and expected; this is the owner now.
+//
+// **A day here is a string, `'2026-08-07'`, not a `Date`.** A date picker
+// selects a square on a wall calendar, and that is not an instant: it has no
+// time, no zone, and no duration that survives a DST boundary. A `Date` is an
+// instant, so every comparison the widgets need — is this the selected day, is
+// it inside the range, is it blocked — would be a comparison of two timestamps
+// that are only equal if both were built the same way. `new Date(2026, 7, 7)`
+// and `new Date('2026-08-07')` are eleven hours apart in Sydney and neither is
+// wrong.
+//
+// A string has none of that: `a === b` is "the same day", `a < b` is "earlier"
+// (fixed-width fields, so lexical order *is* chronological order), it is a
+// `Map`/`Set` key without a codec, and it is what a calendar API hands back
+// over the wire in the first place — which is exactly the shape the desktop
+// event overlay in `../desktop-calendar/` produces.
+//
+// `Date` is still accepted everywhere a day is taken: `toDay()` converts one
+// using its **local** calendar day, because that is the day the user was
+// looking at when they built it.
+//
+// The arithmetic runs in UTC (`Date.UTC`, `getUTC*`) so that "add a day" is
+// always 86400 seconds and never 23 or 25 — the local-time trap that puts a
+// month grid an hour out on the last Sunday in October.
+
+/** A calendar day, `'YYYY-MM-DD'`. */
+export type CalendarDay = string;
+
+/** A calendar month, `'YYYY-MM'`. */
+export type CalendarMonth = string;
+
+/** What every day-shaped prop accepts. */
+export type DayInput = CalendarDay | Date | null | undefined;
+
+/** The parts of a day, so a caller does not have to parse the string. */
+export interface DayParts {
+  year: number;
+  /** 1-based, unlike `Date`'s. */
+  month: number;
+  day: number;
+  /** `0`-`6` from Sunday, as `Date#getDay()` counts. */
+  weekday: number;
+  date: Date;
+}
+
+const DAY_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const MONTH_RE = /^(\d{4})-(\d{2})$/;
+
+function pad(n: number, width: number): string {
+  return String(n).padStart(width, '0');
+}
+
+function key(year: number, month: number, day: number): CalendarDay {
+  return `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
+}
+
+/**
+ * A day key from a `'YYYY-MM-DD'` string, a `Date`, or `null`/`undefined`
+ * (which is "no day", and comes back as `null`).
+ *
+ * Throws on anything else, and on a string that is not a real date —
+ * `'2026-02-30'` is a typo, not a day, and silently sliding it to March 2nd
+ * the way `new Date()` does is how a booking ends up a day out. The message
+ * names what arrived, because the value in a props object is usually miles
+ * from the line that built it.
+ */
+export function toDay(value: DayInput): CalendarDay | null {
+  if (value == null) return null;
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new TypeError(
+        '@react-x11/components: an Invalid Date was passed where a calendar day was expected.',
+      );
+    }
+    // its *local* calendar day: `new Date(2026, 7, 7)` is local midnight, and
+    // the day the developer wrote down is the one they meant
+    return key(value.getFullYear(), value.getMonth() + 1, value.getDate());
+  }
+  if (typeof value === 'string') {
+    const m = DAY_RE.exec(value);
+    if (!m) {
+      throw new TypeError(
+        `@react-x11/components: expected a calendar day as 'YYYY-MM-DD' or a Date, got ${JSON.stringify(value)}.`,
+      );
+    }
+    const [, y, mo, d] = m;
+    // through a real Date and back: the fields on their own are well-formed
+    // for '2026-02-30' too, and only the calendar knows February ends earlier
+    const date = new Date(Date.UTC(Number(y), Number(mo) - 1, Number(d)));
+    const round = key(
+      date.getUTCFullYear(),
+      date.getUTCMonth() + 1,
+      date.getUTCDate(),
+    );
+    if (round !== value) {
+      throw new TypeError(
+        `@react-x11/components: ${JSON.stringify(value)} is not a real calendar date.`,
+      );
+    }
+    return value;
+  }
+  throw new TypeError(
+    `@react-x11/components: expected a calendar day as 'YYYY-MM-DD' or a Date, got ${typeof value}.`,
+  );
+}
+
+/** `'YYYY-MM'` from the same set of inputs, for the *visible month* props. */
+export function toMonth(value: DayInput): CalendarMonth | null {
+  if (value == null) return null;
+  if (typeof value === 'string' && MONTH_RE.test(value)) return value;
+  const day = toDay(value);
+  return day == null ? null : monthOf(day);
+}
+
+/** Today, on this machine, in local time — which is the day the user's wall
+ *  calendar is showing. */
+export function today(): CalendarDay {
+  const now = new Date();
+  return key(now.getFullYear(), now.getMonth() + 1, now.getDate());
+}
+
+/** The day as a UTC-midnight `Date`, for `Intl` and for arithmetic. */
+export function dayDate(day: CalendarDay): Date {
+  const [y, m, d] = day.split('-').map(Number);
+  return new Date(Date.UTC(y, m - 1, d));
+}
+
+/**
+ * `{ year, month, day, weekday, date }` — the parts a caller needs to decide
+ * something about a day without parsing the string itself. `weekday` is
+ * `0`-`6` from Sunday, as `Date#getDay()` counts, so blocking weekends is
+ * `weekday === 0 || weekday === 6`. `month` is 1-based, unlike `Date`'s.
+ */
+export function dayParts(day: CalendarDay): DayParts {
+  const date = dayDate(day);
+  return {
+    year: date.getUTCFullYear(),
+    month: date.getUTCMonth() + 1,
+    day: date.getUTCDate(),
+    weekday: date.getUTCDay(),
+    date,
+  };
+}
+
+export function addDays(day: CalendarDay, n: number): CalendarDay {
+  const date = dayDate(day);
+  date.setUTCDate(date.getUTCDate() + n);
+  return key(date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate());
+}
+
+/** `'2026-08'` — the month a day is in. */
+export function monthOf(day: CalendarDay): CalendarMonth {
+  return day.slice(0, 7);
+}
+
+/** The first day of a `'YYYY-MM'`. */
+export function firstOfMonth(month: CalendarMonth): CalendarDay {
+  return `${month}-01`;
+}
+
+/**
+ * `n` months on from a `'YYYY-MM'`. Months, unlike days, are not all the same
+ * length, so this deliberately works on the month key and never on a day: the
+ * "same date next month" question (Jan 31 → Feb 31?) has no good answer and
+ * nothing here asks it.
+ */
+export function addMonths(month: CalendarMonth, n: number): CalendarMonth {
+  const [y, m] = month.split('-').map(Number);
+  const total = y * 12 + (m - 1) + n;
+  return `${pad(Math.floor(total / 12), 4)}-${pad((total % 12) + 1, 2)}`;
+}
+
+/** `day` held inside `[min, max]`; either bound may be null. */
+export function clampDay(
+  day: CalendarDay,
+  min: CalendarDay | null,
+  max: CalendarDay | null,
+): CalendarDay {
+  if (min && day < min) return min;
+  if (max && day > max) return max;
+  return day;
+}
+
+/**
+ * The grid a month is drawn on: **six weeks of seven days**, always, starting
+ * on `weekStartsOn` and running through whatever days of the neighbouring
+ * months it takes to fill the corners.
+ *
+ * Six rows even when five would do (and a 28-day February starting on the
+ * first day of the week needs only four) because the alternative is a picker
+ * whose popup changes height as you page through it, moving the very buttons
+ * the pointer is aiming at.
+ */
+export function monthGrid(
+  month: CalendarMonth,
+  weekStartsOn = 1,
+): CalendarDay[][] {
+  const first = firstOfMonth(month);
+  const lead = (dayParts(first).weekday - weekStartsOn + 7) % 7;
+  const start = addDays(first, -lead);
+  const weeks: CalendarDay[][] = [];
+  for (let w = 0; w < 6; w++) {
+    const days: CalendarDay[] = [];
+    for (let d = 0; d < 7; d++) days.push(addDays(start, w * 7 + d));
+    weeks.push(days);
+  }
+  return weeks;
+}
+
+// Intl formatters are expensive to build and every cell in the grid wants the
+// same three, so they are made once per (locale, shape) and kept.
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+function formatter(
+  locale: string | undefined,
+  options: Intl.DateTimeFormatOptions,
+): Intl.DateTimeFormat {
+  const id = `${locale ?? ''}|${JSON.stringify(options)}`;
+  let f = formatters.get(id);
+  if (!f) {
+    // everything here is a UTC-midnight Date, so the formatter has to read it
+    // in UTC or a negative offset prints the day before
+    f = new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' });
+    formatters.set(id, f);
+  }
+  return f;
+}
+
+/**
+ * Which day the week starts on for a locale: `0` Sunday … `6` Saturday.
+ *
+ * The runtime knows this — CLDR carries it — but only through
+ * `Intl.Locale#getWeekInfo`, which is recent enough that a small-ICU build or
+ * an older V8 has neither it nor the `weekInfo` property it was proposed as.
+ * So it is feature-detected, and what is left when it is missing is **Monday**:
+ * ISO 8601's answer, and the one most of the world uses.
+ */
+export function localeWeekStart(locale?: string): number {
+  try {
+    const info = new Intl.Locale(locale ?? 'und');
+    // `getWeekInfo()` is the standardised spelling; `weekInfo` is what the
+    // proposal shipped as and what older V8 still has.
+    const withWeek = info as Intl.Locale & {
+      getWeekInfo?: () => { firstDay?: number };
+      weekInfo?: { firstDay?: number };
+    };
+    const week = withWeek.getWeekInfo?.() ?? withWeek.weekInfo;
+    // CLDR counts 1 Monday … 7 Sunday; JS counts 0 Sunday … 6 Saturday
+    if (week?.firstDay) return week.firstDay % 7;
+  } catch {
+    // an invalid locale tag: the caller's formatters will complain about it
+    // more usefully than a week-start fallback could
+  }
+  return 1;
+}
+
+/** `['Mon', 'Tue', …]` in the locale, rotated to start on `weekStartsOn`. */
+export function weekdayLabels(locale?: string, weekStartsOn = 1): string[] {
+  const f = formatter(locale, { weekday: 'short' });
+  // 2026-08-02 is a Sunday, so `+ weekday` lands on the day we want a name for
+  return Array.from({ length: 7 }, (_, i) =>
+    f.format(dayDate(addDays('2026-08-02', (weekStartsOn + i) % 7))),
+  );
+}
+
+/** `'August 2026'` in the locale. */
+export function formatMonth(month: CalendarMonth, locale?: string): string {
+  return formatter(locale, { month: 'long', year: 'numeric' }).format(
+    dayDate(firstOfMonth(month)),
+  );
+}
+
+/** `'7 Aug 2026'` in the locale — what a picker's trigger shows. */
+export function formatDay(
+  day: CalendarDay,
+  locale?: string,
+  options?: Intl.DateTimeFormatOptions,
+): string {
+  return formatter(locale, options ?? { dateStyle: 'medium' }).format(
+    dayDate(day),
+  );
+}
+
+/**
+ * `'7 – 12 Aug 2026'`: the locale's own way of writing a span, which collapses
+ * the parts the two ends share. `formatRange` is ES2021 and universal in the
+ * Node versions this package supports, but a small-ICU build can still throw,
+ * so a plain "a – b" is kept behind it.
+ */
+export function formatDayRange(
+  start: CalendarDay,
+  end: CalendarDay,
+  locale?: string,
+  options?: Intl.DateTimeFormatOptions,
+): string {
+  const f = formatter(locale, options ?? { dateStyle: 'medium' });
+  try {
+    return f.formatRange(dayDate(start), dayDate(end));
+  } catch {
+    return `${f.format(dayDate(start))} – ${f.format(dayDate(end))}`;
+  }
+}