@redseed/redseed-ui-vue3 8.59.0 → 8.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@redseed/redseed-ui-vue3",
-    "version": "8.59.0",
+    "version": "8.60.0",
     "description": "RedSeed UI Vue 3 components",
     "main": "index.js",
     "repository": "https://github.com/redseedtraining/redseed-ui",

package/src/components/FormField/DateRangeInternal/DateRangeMonth.vue

@@ -0,0 +1,168 @@
+<script setup>
+import { computed } from 'vue'
+import { buildMonthGrid, formatIsoDate, formatMonthCaption } from './dateRange.js'
+
+const props = defineProps({
+    year: {
+        type: Number,
+        required: true,
+    },
+    monthIndex: {
+        type: Number,
+        required: true,
+    },
+    locale: {
+        type: String,
+        default: undefined,
+    },
+    weekdays: {
+        type: Array,
+        default: () => [],
+    },
+    // The bounds to paint. While a range is half-picked the parent passes the
+    // preview (picked bound + hovered day) rather than the committed value, so
+    // this component never needs to know a selection is in progress.
+    start: {
+        type: String,
+        default: null,
+    },
+    end: {
+        type: String,
+        default: null,
+    },
+    focusedDate: {
+        type: String,
+        default: null,
+    },
+    minDate: {
+        type: String,
+        required: true,
+    },
+    maxDate: {
+        type: String,
+        required: true,
+    },
+    referenceDate: {
+        type: String,
+        default: null,
+    },
+})
+
+const emit = defineEmits(['select', 'hover'])
+
+const weeks = computed(() => buildMonthGrid(props.year, props.monthIndex))
+
+const caption = computed(() => formatMonthCaption(props.year, props.monthIndex, props.locale))
+
+// A plain `>`/`<` is exact for Y-m-d — fixed-width and zero-padded, so they
+// sort lexicographically in date order.
+function isUnavailable(iso) {
+    return iso < props.minDate || iso > props.maxDate
+}
+
+function isRangeStart(iso) {
+    return props.start !== null && iso === props.start
+}
+
+function isRangeEnd(iso) {
+    return props.end !== null && iso === props.end
+}
+
+function isInRange(iso) {
+    if (! props.start || ! props.end) {
+        return false
+    }
+
+    return iso > props.start && iso < props.end
+}
+
+/**
+ * Only the two ends of the window are `aria-selected`.
+ *
+ * Marking the interior too makes a 90-day range announce ninety selected
+ * cells, which tells a screen-reader user nothing about where the window
+ * begins or ends. The interior is carried by styling, as the APG date-picker
+ * pattern does.
+ */
+function isEndpoint(iso) {
+    return isRangeStart(iso) || isRangeEnd(iso)
+}
+
+function dayClass(iso) {
+    return [
+        'rsui-form-field-date-range__day',
+        {
+            'rsui-form-field-date-range__day--range-start': isRangeStart(iso),
+            'rsui-form-field-date-range__day--range-end': isRangeEnd(iso),
+            'rsui-form-field-date-range__day--in-range': isInRange(iso),
+            'rsui-form-field-date-range__day--reference': iso === props.referenceDate,
+            'rsui-form-field-date-range__day--unavailable': isUnavailable(iso),
+        },
+    ]
+}
+
+// Out-of-bounds days stay focusable and keep their place in the grid — a day
+// you can arrow onto and be told is unavailable beats one that silently is not
+// there — so they carry aria-disabled and refuse the click here instead.
+function select(iso) {
+    if (isUnavailable(iso)) {
+        return
+    }
+
+    emit('select', iso)
+}
+</script>
+<template>
+<div class="rsui-form-field-date-range__month">
+    <div class="rsui-form-field-date-range__caption" aria-hidden="true">
+        {{ caption }}
+    </div>
+
+    <table
+        class="rsui-form-field-date-range__table"
+        role="grid"
+        :aria-label="caption"
+        @mouseleave="emit('hover', null)"
+    >
+        <thead>
+            <tr>
+                <th v-for="weekday in weekdays"
+                    :key="weekday.long"
+                    class="rsui-form-field-date-range__weekday"
+                    scope="col"
+                >
+                    <span aria-hidden="true">{{ weekday.short }}</span>
+                    <span class="rsui-form-field-date-range__sr-only">{{ weekday.long }}</span>
+                </th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr v-for="(week, weekIndex) in weeks"
+                :key="weekIndex"
+                class="rsui-form-field-date-range__week"
+            >
+                <td v-for="(cell, cellIndex) in week"
+                    :key="cellIndex"
+                    class="rsui-form-field-date-range__cell"
+                    role="gridcell"
+                    :aria-selected="cell ? String(isEndpoint(cell.iso)) : undefined"
+                >
+                    <button v-if="cell"
+                        type="button"
+                        :class="dayClass(cell.iso)"
+                        :data-date="cell.iso"
+                        :tabindex="cell.iso === focusedDate ? 0 : -1"
+                        :aria-disabled="isUnavailable(cell.iso) ? 'true' : undefined"
+                        :aria-current="cell.iso === referenceDate ? 'date' : undefined"
+                        :aria-label="formatIsoDate(cell.iso, locale, { dateStyle: 'long' })"
+                        @click="select(cell.iso)"
+                        @mouseenter="emit('hover', cell.iso)"
+                    >
+                        {{ cell.day }}
+                    </button>
+                </td>
+            </tr>
+        </tbody>
+    </table>
+</div>
+</template>

package/src/components/FormField/DateRangeInternal/DateRangePresetRail.vue

@@ -0,0 +1,105 @@
+<script setup>
+import { computed } from 'vue'
+import { dateRangeValidationReason, isIsoDate, resolveDateRangePreset } from './dateRange.js'
+
+const props = defineProps({
+    // `{ name, label }` for a window RSUI owns the arithmetic for, or
+    // `{ label, resolve: (referenceDate) => ({ start, end }) }` as an escape
+    // hatch for a genuinely bespoke one. The escape hatch is the exception:
+    // anything named here is resolved by RSUI so that every consumer gets the
+    // same window — and the same clamp fix — without writing the maths again.
+    presets: {
+        type: Array,
+        default: () => [],
+    },
+    referenceDate: {
+        type: String,
+        default: null,
+    },
+    // The committed range, so the rail can mark the preset it represents.
+    range: {
+        type: Object,
+        default: () => ({ start: null, end: null }),
+    },
+    minDate: {
+        type: String,
+        required: true,
+    },
+    maxDate: {
+        type: String,
+        required: true,
+    },
+})
+
+const emit = defineEmits(['select'])
+
+/**
+ * Run a consumer's `resolve()` and check what it handed back.
+ *
+ * The escape hatch takes arbitrary consumer code, so a wrong return shape — a
+ * string, a `Date` pair, an object missing a bound — otherwise surfaces only as
+ * a button that is disabled forever, with nothing said about why. That is the
+ * hardest kind of bug to place, because the rail looks like it is working.
+ */
+function resolveEscapeHatch(preset) {
+    const resolved = preset.resolve(props.referenceDate)
+    const isUsable = Boolean(resolved)
+        && isIsoDate(resolved.start)
+        && isIsoDate(resolved.end)
+
+    if (! isUsable) {
+        console.warn(
+            `[FormFieldDateRange] the resolve() for preset "${preset.label}" returned `
+            + `${JSON.stringify(resolved)}, which is not { start, end } of Y-m-d strings. `
+            + 'Its button stays disabled. Note the bounds must be Y-m-d strings, not Date objects.'
+        )
+
+        return null
+    }
+
+    return resolved
+}
+
+// Resolve, validate and match each preset in one pass — the rail needs all
+// three for every entry, and resolving once keeps them in agreement.
+const items = computed(() => props.presets.map((preset, index) => {
+    const range = typeof preset.resolve === 'function'
+        ? resolveEscapeHatch(preset)
+        : resolveDateRangePreset(preset.name, props.referenceDate)
+
+    // A preset whose window falls outside the bounds is disabled rather than
+    // clamped: a shortened window under an unchanged label would claim to cover
+    // rows it never asked for.
+    const isDisabled = ! range
+        || dateRangeValidationReason(range, props.minDate, props.maxDate) !== null
+
+    return {
+        key: preset.name ?? `preset-${index}`,
+        label: preset.label,
+        range,
+        isDisabled,
+        // No `custom` sentinel: a window no preset describes simply selects
+        // nothing, because picking dates directly IS custom.
+        isSelected: Boolean(range)
+            && range.start === props.range?.start
+            && range.end === props.range?.end,
+    }
+}))
+</script>
+<template>
+<div class="rsui-form-field-date-range__presets" role="group">
+    <button v-for="item in items"
+        :key="item.key"
+        type="button"
+        :class="[
+            'rsui-form-field-date-range__preset',
+            { 'rsui-form-field-date-range__preset--selected': item.isSelected },
+        ]"
+        :aria-pressed="item.isSelected ? 'true' : 'false'"
+        :disabled="item.isDisabled"
+        @click="emit('select', item.range)"
+    >
+        {{ item.label }}
+    </button>
+</div>
+</template>

package/src/components/FormField/DateRangeInternal/dateRange.js

@@ -0,0 +1,394 @@
+/**
+ * Date arithmetic for FormFieldDateRange.
+ *
+ * Ported from the LMS Meeting Report's `meetingReportDateRange.js`, which is
+ * where this logic was written correctly the first time. It lives in RSUI now
+ * because every consumer that needs a named window was otherwise writing it
+ * again — and the second copy did not carry the clamp fix below.
+ *
+ * Two rules hold everywhere in this module:
+ *
+ *   1. Every bound resolves against a caller-supplied `referenceDate` (a `Y-m-d`
+ *      string), NEVER a browser clock. The app timezone is Pacific/Auckland, so
+ *      a viewer elsewhere resolving "this month" locally would get a different
+ *      window than the report they are reading. Nothing here calls `new Date()`
+ *      without arguments.
+ *
+ *   2. All arithmetic runs in UTC, and values move as `Y-m-d` strings rather
+ *      than `Date` objects. ISO dates are fixed-width and zero-padded, so they
+ *      compare with a plain `>` in date order — no parsing, and therefore no
+ *      timezone to get wrong.
+ */
+
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+export function toIsoDate(year, monthIndex, day) {
+    return new Date(Date.UTC(year, monthIndex, day)).toISOString().slice(0, 10)
+}
+
+/**
+ * A `Y-m-d` string that names a day that actually exists.
+ *
+ * The shape test alone is not enough: `2026-02-30` matches the pattern, and
+ * every consumer downstream then trusts it. `Date.UTC` ROLLS rather than
+ * rejects, so it would quietly become 2 March — a window silently shifted off
+ * the date the caller asked for, which is the same class of bug the preset
+ * clamp exists to prevent.
+ *
+ * Round-tripping through `toIsoDate` is the check: a real date formats back to
+ * itself, a rolled one does not. Years are held to 1000–9999 because `Date.UTC`
+ * maps 0–99 to 1900+n, so `0050-01-15` would round-trip as 1950 and pass.
+ */
+export function isIsoDate(value) {
+    if (typeof value !== 'string' || ! ISO_DATE_PATTERN.test(value)) {
+        return false
+    }
+
+    const [year, month, day] = value.split('-').map(Number)
+
+    if (year < 1000) {
+        return false
+    }
+
+    return toIsoDate(year, month - 1, day) === value
+}
+
+// Day 0 of the following month is the last day of the one being asked about.
+// A negative monthIndex rolls back into the previous year, which is what the
+// three-month and last-month windows need in January through March.
+export function lastDayOfMonth(year, monthIndex) {
+    return new Date(Date.UTC(year, monthIndex + 1, 0)).getUTCDate()
+}
+
+export function parseIsoDate(iso) {
+    if (! isIsoDate(iso)) {
+        return null
+    }
+
+    const [year, month, day] = iso.split('-').map(Number)
+
+    return { year, monthIndex: month - 1, day }
+}
+
+/**
+ * Shift a year/month pair by whole months, normalising the year.
+ * `Date.UTC` already rolls month indices in both directions, so read the
+ * normalised pair back off the resulting date rather than doing it by hand.
+ */
+export function addMonths(year, monthIndex, delta) {
+    const shifted = new Date(Date.UTC(year, monthIndex + delta, 1))
+
+    return { year: shifted.getUTCFullYear(), monthIndex: shifted.getUTCMonth() }
+}
+
+/**
+ * Shift a date by whole days. Rolling IS the wanted behaviour here — the day
+ * after 31 August is 1 September — which is exactly why the month arithmetic
+ * above has to clamp instead.
+ */
+export function addDays(iso, delta) {
+    const parsed = parseIsoDate(iso)
+
+    if (! parsed) {
+        return null
+    }
+
+    return toIsoDate(parsed.year, parsed.monthIndex, parsed.day + delta)
+}
+
+/**
+ * Shift a date by whole months, clamping the day to the target month rather
+ * than letting it roll into the next one — the same trap `last_3_months`
+ * carries a fix for, reached here by paging the calendar with PageUp/PageDown.
+ */
+export function shiftMonths(iso, delta) {
+    const parsed = parseIsoDate(iso)
+
+    if (! parsed) {
+        return null
+    }
+
+    const { year, monthIndex } = addMonths(parsed.year, parsed.monthIndex, delta)
+
+    return toIsoDate(year, monthIndex, Math.min(parsed.day, lastDayOfMonth(year, monthIndex)))
+}
+
+// Monday-first weekday index (Monday 0 ... Sunday 6). getUTCDay() is
+// Sunday-first, so shift it.
+export function weekdayIndex(year, monthIndex, day) {
+    return (new Date(Date.UTC(year, monthIndex, day)).getUTCDay() + 6) % 7
+}
+
+/**
+ * The preset vocabulary, in the order the names are offered.
+ *
+ * The prefix is the rule: `last_*` counts BACK from the reference date,
+ * `this_*` runs from the start of the current period TO it.
+ * Every window ends at the reference date, so none of them can breach the
+ * common `maxDate` of today.
+ *
+ * ⚠️ `last_month` is ROLLING — one month back from the reference date, so 14
+ * July to 14 August. That is a deliberate deviation from the common
+ * convention, recorded here so nobody "fixes" it back: GA4, Mixpanel and
+ * Amplitude all read "Last month" as the previous COMPLETE calendar month
+ * (1–31 July) and offer "Last 30 days" separately for the rolling case. It is
+ * rolling here so `last_*` means one thing rather than two — the alternative
+ * was a single calendar-aligned outlier whose name looked like its siblings and
+ * behaved differently. If the convention is wanted later, the clean shape is a
+ * calendar `last_month` alongside a rolling `last_30_days`, offering both.
+ *
+ * There is deliberately no `custom`: with an always-visible range control
+ * there is nothing for it to reveal, because picking dates directly IS custom.
+ */
+export const KNOWN_PRESET_NAMES = [
+    'today',
+    'last_7_days',
+    'last_month',
+    'last_3_months',
+    'this_year',
+]
+
+export function isKnownPresetName(name) {
+    return KNOWN_PRESET_NAMES.includes(name)
+}
+
+/**
+ * Resolve a named preset to its bounds, or null for a name this module does
+ * not own (and for a missing or malformed reference date, since a preset
+ * cannot be resolved without one).
+ */
+export function resolveDateRangePreset(name, referenceDate) {
+    const reference = parseIsoDate(referenceDate)
+
+    if (! reference) {
+        return null
+    }
+
+    // Only `this_year` needs a part — the rolling windows work on the string,
+    // because both helpers they use parse it themselves.
+    const { year } = reference
+
+    // A single day is still a range — both bounds are the reference date. Same
+    // shape as the others, so nothing downstream needs to special-case it.
+    if (name === 'today') {
+        return { start: referenceDate, end: referenceDate }
+    }
+
+    /*
+     * Every `last_*` window is the same rule: count back from the reference
+     * date, end at it. Only the unit and the amount differ, so they are one
+     * table rather than a branch each — a second implementation of the same
+     * arithmetic is how the two of them drifted apart in the first place.
+     *
+     * Day counts are `n - 1` because both bounds are inclusive: today plus the
+     * six days before it is seven days, and `-7` would quietly be eight.
+     *
+     * Month shifts go through `shiftMonths`, which clamps. That clamp is not
+     * optional — `Date.UTC` ROLLS an out-of-range day forward, so a naive
+     * "31 May minus 3 months" asks for February 31 and resolves to 3 March,
+     * silently starting the window days late while rendering as though it were
+     * intended.
+     */
+    const ROLLING_WINDOWS = {
+        last_7_days: (iso) => addDays(iso, -6),
+        last_month: (iso) => shiftMonths(iso, -1),
+        last_3_months: (iso) => shiftMonths(iso, -3),
+    }
+
+    if (Object.hasOwn(ROLLING_WINDOWS, name)) {
+        return {
+            start: ROLLING_WINDOWS[name](referenceDate),
+            end: referenceDate,
+        }
+    }
+
+    if (name === 'this_year') {
+        return {
+            start: toIsoDate(year, 0, 1),
+            end: referenceDate,
+        }
+    }
+
+    return null
+}
+
+/**
+ * Whether a pair of bounds describes a window that cannot exist.
+ *
+ * A half-filled range is not out of order — it is simply unfinished, which is
+ * the normal state between the two clicks that pick a range.
+ */
+export function isRangeOutOfOrder(start, end) {
+    if (! start || ! end) {
+        return false
+    }
+
+    return start > end
+}
+
+/**
+ * Whether a bound is present but not a `Y-m-d` string.
+ *
+ * A `Date` object is the specific thing worth catching: it is the shape this
+ * API exists to keep out, and it fails SILENTLY without this check. Relational
+ * `<` / `>` coerce a Date with hint `number`, so every comparison against an
+ * ISO bound string is `NaN` — which is false in both directions, so a Date
+ * passes every range check below and reports as valid.
+ */
+function isUnusableBound(value) {
+    return value !== null && value !== undefined && ! isIsoDate(value)
+}
+
+/**
+ * Why a range cannot be used, in precedence order, or null when it is fine.
+ *
+ * Reasons mirror MUI's `onError`: a consumer gating a Generate button only
+ * needs to know THAT the window is unusable, and which way it is unusable is
+ * enough to say so in its own words. The message itself stays with the
+ * consumer — RSUI cannot reach an app's language files.
+ *
+ * The reason vocabulary is a PUBLIC CONTRACT — consumers switch on it — so it
+ * is deliberately complete rather than minimal. `incomplete` in particular:
+ * without it, every consumer gating a Generate button has to re-derive
+ * emptiness itself, which is exactly the duplication this component exists to
+ * remove.
+ *
+ * Vocabulary: 'invalid-value' | 'incomplete' | 'invalid-range' | 'min-date' | 'max-date' | null
+ */
+export function dateRangeValidationReason(range, minDate, maxDate) {
+    const start = range?.start ?? null
+    const end = range?.end ?? null
+
+    // First, because a bound of the wrong TYPE makes every check below
+    // meaningless rather than merely false.
+    if (isUnusableBound(range?.start) || isUnusableBound(range?.end)) {
+        return 'invalid-value'
+    }
+
+    // Ahead of the bound checks: a window missing an end is not a window, and
+    // saying so is more use to a consumer than "the start is fine".
+    if (! start || ! end) {
+        return 'incomplete'
+    }
+
+    if (isRangeOutOfOrder(start, end)) {
+        return 'invalid-range'
+    }
+
+    if (start < minDate || end < minDate) {
+        return 'min-date'
+    }
+
+    if (start > maxDate || end > maxDate) {
+        return 'max-date'
+    }
+
+    return null
+}
+
+/**
+ * Format a `Y-m-d` string for display in the viewer's language.
+ *
+ * Formatting is pinned to UTC so the rendered day is the day that was stored:
+ * reading a fixed date through a local-timezone formatter is the same class of
+ * mistake as resolving a preset against a browser clock.
+ *
+ * The default is zero-padded numeric rather than `dateStyle: 'medium'`. Two
+ * reasons, and the second is the load-bearing one:
+ *
+ *   1. Every value is the same width, so a range does not reflow as the user
+ *      moves between months.
+ *   2. Separation comes from the slashes. "08/06/2026" already reads as one
+ *      unit, so the en dash between the two bounds does not need extra spacing
+ *      to stop the six parts running together — which is what a spelled month
+ *      ("8 Jun 2026 – 25 Jun 2026") does need.
+ *
+ * Part ORDER still follows the locale — en-NZ renders `08/06/2026` as
+ * day-first, en-US the same digits as month-first. That is correct per viewer
+ * and is why the order is left to `Intl` rather than hardcoded.
+ */
+/**
+ * Formatters are memoised on (locale, options).
+ *
+ * `Intl.DateTimeFormat` construction is the expensive part — it resolves the
+ * locale and builds the pattern — and the day cells call this inline for every
+ * `aria-label`. Two months is around 70 cells, rebuilt on every reactive change,
+ * which includes each mouseenter while dragging a range across the grid. The
+ * key set is tiny and bounded: one locale times the two options shapes this
+ * module uses.
+ */
+const formatterCache = new Map()
+
+function dateFormatter(locale, options) {
+    const key = `${locale ?? ''}|${JSON.stringify(options)}`
+
+    if (! formatterCache.has(key)) {
+        formatterCache.set(key, new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' }))
+    }
+
+    return formatterCache.get(key)
+}
+
+export function formatIsoDate(iso, locale, options = { day: '2-digit', month: '2-digit', year: 'numeric' }) {
+    const parsed = parseIsoDate(iso)
+
+    if (! parsed) {
+        return ''
+    }
+
+    const date = new Date(Date.UTC(parsed.year, parsed.monthIndex, parsed.day))
+
+    return dateFormatter(locale, options).format(date)
+}
+
+export function formatMonthCaption(year, monthIndex, locale) {
+    const date = new Date(Date.UTC(year, monthIndex, 1))
+
+    return new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric', timeZone: 'UTC' })
+        .format(date)
+}
+
+/**
+ * Monday-first weekday names in the viewer's language, short for the column
+ * heading and long for the screen reader. 1 January 2024 was a Monday — an
+ * arbitrary anchor, not a clock.
+ */
+export function weekdayLabels(locale) {
+    return Array.from({ length: 7 }, (unused, index) => {
+        const date = new Date(Date.UTC(2024, 0, 1 + index))
+
+        return {
+            short: new Intl.DateTimeFormat(locale, { weekday: 'short', timeZone: 'UTC' }).format(date),
+            long: new Intl.DateTimeFormat(locale, { weekday: 'long', timeZone: 'UTC' }).format(date),
+        }
+    })
+}
+
+/**
+ * Lay a month out as Monday-first weeks of seven cells, padding both ends with
+ * nulls. Only the month's own days are emitted: the popover shows two months
+ * side by side, so borrowing days from a neighbouring month would render the
+ * same date twice and give it two places to be focused and selected from.
+ */
+export function buildMonthGrid(year, monthIndex) {
+    const totalDays = lastDayOfMonth(year, monthIndex)
+    const firstWeekday = weekdayIndex(year, monthIndex, 1)
+
+    const cells = Array.from({ length: firstWeekday }, () => null)
+
+    for (let day = 1; day <= totalDays; day++) {
+        cells.push({ iso: toIsoDate(year, monthIndex, day), day })
+    }
+
+    while (cells.length % 7 !== 0) {
+        cells.push(null)
+    }
+
+    const weeks = []
+
+    for (let index = 0; index < cells.length; index += 7) {
+        weeks.push(cells.slice(index, index + 7))
+    }
+
+    return weeks
+}

package/src/components/FormField/FormFieldDateRange.vue

@@ -0,0 +1,679 @@
+<script setup>
+import { computed, nextTick, onMounted, ref, useAttrs, useId, useSlots, watch } from 'vue'
+import { onClickOutside } from '@vueuse/core'
+import { CalendarIcon, ChevronLeftIcon, ChevronRightIcon } from '@heroicons/vue/24/outline'
+import FormFieldSlot from './FormFieldSlot.vue'
+import DateRangeMonth from './DateRangeInternal/DateRangeMonth.vue'
+import DateRangePresetRail from './DateRangeInternal/DateRangePresetRail.vue'
+import { useDropdownPosition } from '../../composables/useDropdownPosition.js'
+import {
+    KNOWN_PRESET_NAMES,
+    addDays,
+    addMonths,
+    dateRangeValidationReason,
+    formatIsoDate,
+    formatMonthCaption,
+    isIsoDate,
+    isKnownPresetName,
+    parseIsoDate,
+    shiftMonths,
+    toIsoDate,
+    weekdayIndex,
+    weekdayLabels,
+} from './DateRangeInternal/dateRange.js'
+
+defineOptions({
+    inheritAttrs: false,
+})
+
+// `{ start, end }` of Y-m-d strings, never Date objects: ISO dates compare
+// correctly with a plain `>`, so the value carries no timezone to get wrong.
+const model = defineModel({
+    type: Object,
+    default: () => ({ start: null, end: null }),
+})
+
+const props = defineProps({
+    // Required whenever `presets` is set, and never the browser clock. The app
+    // timezone is Pacific/Auckland; a viewer elsewhere resolving "this month"
+    // locally would get a different window than the report they are reading.
+    referenceDate: {
+        type: String,
+        default: null,
+    },
+    presets: {
+        type: Array,
+        default: () => [],
+    },
+    minDate: {
+        type: String,
+        default: '1900-01-01',
+    },
+    maxDate: {
+        type: String,
+        default: '2099-12-31',
+    },
+    // NOTE: `disabled` is deliberately NOT a prop. It arrives as an attribute,
+    // matching FormFieldCombobox and FormFieldSelect — a divergence inside the
+    // FormField family would be permanent once this publishes, and consumers
+    // reasonably expect one control to behave like its siblings.
+    //
+    // Formatting only — month names, weekday headings and the value in the
+    // field. Left undefined it follows the browser, which is right far more
+    // often than hardcoded English.
+    locale: {
+        type: String,
+        default: undefined,
+    },
+})
+
+const emit = defineEmits(['error'])
+
+const attrs = useAttrs()
+const slots = useSlots()
+
+const isOpen = ref(false)
+const pendingStart = ref(null)
+const hoverDate = ref(null)
+const focusedDate = ref(null)
+// Anchored on mount and re-anchored on every open, so the (hidden) popover
+// never holds a month nobody asked for.
+const leftMonth = ref({ year: 1970, monthIndex: 0 })
+
+const fieldElement = ref(null)
+const triggerElement = ref(null)
+const popoverElement = ref(null)
+
+// The a11y wiring is computed here rather than injected from FormFieldSlot:
+// this component RENDERS the slot, so it is the slot's parent, and inject only
+// ever walks upwards. Passing our own id down means the label's `for`, the
+// help/error element ids and the control agree on one id either way.
+const fallbackId = useId()
+const effectiveId = computed(() => attrs.id || fallbackId)
+
+const ariaDescribedby = computed(() => {
+    const ids = []
+
+    if (slots.help) {
+        ids.push(`${effectiveId.value}-help`)
+    }
+
+    if (slots.error) {
+        ids.push(`${effectiveId.value}-error`)
+    }
+
+    return ids.length > 0 ? ids.join(' ') : undefined
+})
+
+const ariaInvalid = computed(() => slots.error ? 'true' : undefined)
+
+/**
+ * Whether a boolean ATTRIBUTE is present.
+ *
+ * `<FormFieldDateRange required>` arrives as the empty string, which is falsy —
+ * so a plain truthiness test reads the bare, most idiomatic form of the
+ * attribute as absent. Only an explicit `:required="false"` (or the literal
+ * string "false") means off.
+ */
+function hasBooleanAttr(value) {
+    return value !== undefined && value !== null && value !== false && value !== 'false'
+}
+
+const isDisabled = computed(() => hasBooleanAttr(attrs.disabled))
+
+const isRequired = computed(() => hasBooleanAttr(attrs.required))
+
+const popoverId = computed(() => `${effectiveId.value}-popover`)
+
+/**
+ * The trigger names itself as "<label>, <value>".
+ *
+ * A <button> takes its accessible name from its own subtree, so browsers
+ * announce the formatted range and drop the `<label for>` entirely — in a
+ * filter panel of four of these, every one is announced as a bare pair of
+ * dates. Listing the label first and the button's own id second composes both,
+ * in reading order. Only while a label exists: with no label the subtree name
+ * is already right, and pointing at a missing id would blank the name.
+ */
+const ariaLabelledby = computed(() =>
+    slots.label ? `${effectiveId.value}-label ${effectiveId.value}` : undefined
+)
+
+const range = computed(() => ({
+    start: model.value?.start ?? null,
+    end: model.value?.end ?? null,
+}))
+
+const weekdays = computed(() => weekdayLabels(props.locale))
+
+const rightMonth = computed(() => addMonths(leftMonth.value.year, leftMonth.value.monthIndex, 1))
+
+const monthCaptions = computed(() => [
+    formatMonthCaption(leftMonth.value.year, leftMonth.value.monthIndex, props.locale),
+    formatMonthCaption(rightMonth.value.year, rightMonth.value.monthIndex, props.locale),
+])
+
+// Names the popover after what it is showing, which is already in the viewer's
+// language — no English string to hardcode and no label to translate.
+const popoverLabel = computed(() => monthCaptions.value.join(' – '))
+
+// The paging buttons are named after the month they page TO, for the same
+// reason: a caption is already translated, "Previous month" would not be.
+const navCaptions = computed(() => {
+    const previous = addMonths(leftMonth.value.year, leftMonth.value.monthIndex, -1)
+    const next = addMonths(rightMonth.value.year, rightMonth.value.monthIndex, 1)
+
+    return {
+        previous: formatMonthCaption(previous.year, previous.monthIndex, props.locale),
+        next: formatMonthCaption(next.year, next.monthIndex, props.locale),
+    }
+})
+
+const displayValue = computed(() => {
+    const start = formatIsoDate(range.value.start, props.locale)
+    const end = formatIsoDate(range.value.end, props.locale)
+
+    // Nothing usable to render, so fall through to the placeholder. Joining two
+    // empty strings would produce a bare " – " — truthy, so it would win the
+    // v-if and show an en dash with no dates beside it, which is how a Date
+    // object or a "14/05/2026" string used to render as though it were fine.
+    if (! start && ! end) {
+        return ''
+    }
+
+    // The dash stays on the side that HAS a bound, so a half-filled value reads
+    // as the open-ended window it is: "01/08/2026 –" is a start with no end,
+    // "– 01/08/2026" an end with no start. Formatting both into one string
+    // would render those two states identically.
+    return `${start} – ${end}`.trim()
+})
+
+// Presets are opt-in, and they cannot resolve without a reference date, so a
+// rail that would have to guess one is not rendered at all.
+const canResolvePresets = computed(() =>
+    props.presets.length > 0
+    && isIsoDate(props.referenceDate)
+)
+
+// While a range is half-picked, paint the bound already chosen against the day
+// under the pointer so the window being drawn is visible before it is committed.
+const previewRange = computed(() => {
+    if (! pendingStart.value) {
+        return range.value
+    }
+
+    // Falls back to the FOCUSED day, not just the hovered one, so a keyboard
+    // user arrowing toward the second bound watches the window paint exactly as
+    // a mouse user does. Driving this off hover alone left the keyboard path
+    // with no feedback at all between the two selections.
+    return orderRange(
+        pendingStart.value,
+        hoverDate.value ?? focusedDate.value ?? pendingStart.value,
+    )
+})
+
+const validationReason = computed(() =>
+    dateRangeValidationReason(range.value, props.minDate, props.maxDate)
+)
+
+function orderRange(one, other) {
+    return one > other
+        ? { start: other, end: one }
+        : { start: one, end: other }
+}
+
+/**
+ * Which month the left calendar opens on. Anchoring on the range keeps the
+ * window the user already has in view; the reference date is the next best
+ * anchor. Only when there is neither does this read the browser's date, and
+ * only to decide what to LOOK at — no value is resolved from it, so it cannot
+ * produce the timezone-skewed window this component exists to prevent.
+ */
+function anchorMonth() {
+    const anchor = range.value.start
+        ?? range.value.end
+        ?? props.referenceDate
+        ?? new Date().toISOString().slice(0, 10)
+
+    const parsed = parseIsoDate(anchor) ?? parseIsoDate(new Date().toISOString().slice(0, 10))
+
+    // A range with only an end is shown on the RIGHT month, so the empty start
+    // side of it is the one with room to be picked.
+    if (! range.value.start && range.value.end) {
+        return addMonths(parsed.year, parsed.monthIndex, -1)
+    }
+
+    return { year: parsed.year, monthIndex: parsed.monthIndex }
+}
+
+function monthKey(year, monthIndex) {
+    return year * 12 + monthIndex
+}
+
+// Page the pair so the focused day is one of the two months on screen.
+function ensureFocusVisible() {
+    const focused = parseIsoDate(focusedDate.value)
+
+    if (! focused) {
+        return
+    }
+
+    const focusedKey = monthKey(focused.year, focused.monthIndex)
+    const leftKey = monthKey(leftMonth.value.year, leftMonth.value.monthIndex)
+    const rightKey = monthKey(rightMonth.value.year, rightMonth.value.monthIndex)
+
+    if (focusedKey < leftKey) {
+        leftMonth.value = { year: focused.year, monthIndex: focused.monthIndex }
+    }
+
+    if (focusedKey > rightKey) {
+        leftMonth.value = addMonths(focused.year, focused.monthIndex, -1)
+    }
+}
+
+async function focusFocusedDay() {
+    await nextTick()
+
+    popoverElement.value?.querySelector(`[data-date="${focusedDate.value}"]`)?.focus()
+}
+
+function open() {
+    if (isDisabled.value || isOpen.value) {
+        return
+    }
+
+    isOpen.value = true
+    leftMonth.value = anchorMonth()
+
+    // Each candidate has to be a real Y-m-d, not merely non-null. `??` only
+    // skips null and undefined, so a Date object or a "14/05/2026" string from
+    // an unvalidated v-model used to land in focusedDate — where no day cell
+    // matches it, leaving the grid with nothing tabbable and the arrow keys
+    // computing from a value that cannot be parsed.
+    focusedDate.value = [
+        range.value.start,
+        range.value.end,
+        props.referenceDate,
+    ].find(isIsoDate)
+        ?? toIsoDate(leftMonth.value.year, leftMonth.value.monthIndex, 1)
+
+    ensureFocusVisible()
+
+    nextTick(() => {
+        calculateDropdownPosition()
+        focusFocusedDay()
+    })
+}
+
+function close({ restoreFocus = false } = {}) {
+    isOpen.value = false
+    pendingStart.value = null
+    hoverDate.value = null
+
+    if (restoreFocus) {
+        triggerElement.value?.focus()
+    }
+}
+
+function toggle() {
+    if (isOpen.value) {
+        close()
+        return
+    }
+
+    open()
+}
+
+// Paging carries the focused day with it. Without that, `tabindex="0"` stays on
+// a day that is no longer rendered, so the grid has NO tabbable cell and cannot
+// be reached by keyboard at all — and the next arrow key would page straight
+// back, because `ensureFocusVisible()` would drag the months to the stale focus.
+function pageMonths(delta) {
+    leftMonth.value = addMonths(leftMonth.value.year, leftMonth.value.monthIndex, delta)
+    focusedDate.value = shiftMonths(focusedDate.value, delta) ?? focusedDate.value
+}
+
+function moveFocus(iso) {
+    if (! iso) {
+        return
+    }
+
+    focusedDate.value = iso
+    ensureFocusVisible()
+    focusFocusedDay()
+}
+
+const DAY_DELTAS = {
+    ArrowLeft: -1,
+    ArrowRight: 1,
+    ArrowUp: -7,
+    ArrowDown: 7,
+}
+
+function handleGridKeydown(event) {
+    if (Object.hasOwn(DAY_DELTAS, event.key)) {
+        event.preventDefault()
+        moveFocus(addDays(focusedDate.value, DAY_DELTAS[event.key]))
+        return
+    }
+
+    const focused = parseIsoDate(focusedDate.value)
+
+    if (! focused) {
+        return
+    }
+
+    if (event.key === 'Home') {
+        event.preventDefault()
+        moveFocus(addDays(focusedDate.value, -weekdayIndex(focused.year, focused.monthIndex, focused.day)))
+        return
+    }
+
+    if (event.key === 'End') {
+        event.preventDefault()
+        moveFocus(addDays(focusedDate.value, 6 - weekdayIndex(focused.year, focused.monthIndex, focused.day)))
+        return
+    }
+
+    if (event.key === 'PageUp') {
+        event.preventDefault()
+        moveFocus(shiftMonths(focusedDate.value, -1))
+        return
+    }
+
+    if (event.key === 'PageDown') {
+        event.preventDefault()
+        moveFocus(shiftMonths(focusedDate.value, 1))
+    }
+}
+
+function handlePopoverKeydown(event) {
+    if (event.key === 'Escape') {
+        event.preventDefault()
+        close({ restoreFocus: true })
+        return
+    }
+
+    if (event.key === 'Tab') {
+        containTab(event)
+    }
+}
+
+/**
+ * Keep Tab inside the open popover.
+ *
+ * Two wrong answers were tried before this one. Leaving Tab unhandled walks
+ * straight out of the document, because the popover is teleported to the end of
+ * <body> and the roving tabindex leaves every unfocused day at -1. Closing on
+ * Tab — which is what FormFieldSelect does — fixes that but makes the preset
+ * rail and the month chevrons unreachable by keyboard entirely, since focus
+ * opens on a day and Tab is the only way out of the grid. Presets are a
+ * required feature, so that trades a focus-order bug for a WCAG 2.1.1 Level A
+ * one.
+ *
+ * FormFieldSelect can close on Tab because its popover holds nothing but
+ * options reachable with the arrow keys. This one has three focusable regions,
+ * so it needs containment — which is also what its role="dialog" already
+ * implies. Escape remains the way out.
+ */
+function containTab(event) {
+    // `:not([tabindex="-1"])` skips the roving-tabindex days, leaving the one
+    // day that is currently tabbable plus the rail and nav buttons.
+    const focusable = [
+        ...popoverElement.value?.querySelectorAll(
+            'button:not([disabled]):not([tabindex="-1"])'
+        ) ?? [],
+    ]
+
+    if (focusable.length === 0) {
+        return
+    }
+
+    const first = focusable[0]
+    const last = focusable[focusable.length - 1]
+    const active = document.activeElement
+
+    // Anything not in the cycle (or a stale focus after a re-render) restarts at
+    // the appropriate end rather than falling through to the browser.
+    if (event.shiftKey && (active === first || ! focusable.includes(active))) {
+        event.preventDefault()
+        last.focus()
+        return
+    }
+
+    if (! event.shiftKey && (active === last || ! focusable.includes(active))) {
+        event.preventDefault()
+        first.focus()
+    }
+}
+
+function selectDay(iso) {
+    if (! pendingStart.value) {
+        pendingStart.value = iso
+        focusedDate.value = iso
+        return
+    }
+
+    // Ordered on commit, so a range picked backwards is a range picked, not an
+    // error the consumer has to catch.
+    model.value = orderRange(pendingStart.value, iso)
+    close({ restoreFocus: true })
+}
+
+function selectPreset(resolved) {
+    if (! resolved) {
+        return
+    }
+
+    model.value = { start: resolved.start, end: resolved.end }
+    close({ restoreFocus: true })
+}
+
+function handleHover(iso) {
+    hoverDate.value = iso
+}
+
+// Reuses the positioning FormFieldSelect/Combobox/SearchAsync share (#220), so
+// the popover clamps to the viewport instead of covering its own field. 'min'
+// lets the two-month panel be wider than the field it is anchored to.
+const { calculateDropdownPosition } = useDropdownPosition(
+    popoverElement,
+    fieldElement,
+    isOpen,
+    { widthMode: 'min' },
+)
+
+// Restore focus only when it was inside the popover: `v-show` sets
+// display:none, which drops the focused day out of the a11y tree and resets
+// focus to <body>, losing the user's place in the page. A click that lands
+// elsewhere has already moved focus on purpose, so leave it alone.
+onClickOutside(
+    fieldElement,
+    () => close({ restoreFocus: popoverElement.value?.contains(document.activeElement) ?? false }),
+    { ignore: [popoverElement] },
+)
+
+// Mirrors MUI's onError: the reason only, because the message belongs to the
+// consumer's language files. Emitted once on mount so a Generate button can be
+// gated before the user touches anything, then on every change of reason.
+watch(validationReason, (reason) => emit('error', reason, range.value))
+
+// Both are reactive props, so a mount-only check misses every consumer whose
+// labels arrive with its language files or whose reference date is fetched —
+// exactly the cases where the rail silently never appears.
+watch(
+    [() => props.presets, () => props.referenceDate],
+    ([presets, referenceDate]) => {
+        if (presets.length > 0 && ! isIsoDate(referenceDate)) {
+            console.warn(
+                '[FormFieldDateRange] `presets` needs a `referenceDate` (a Y-m-d string) to resolve against. '
+                + 'The preset rail is hidden: resolving against the browser clock would give a viewer outside '
+                + 'the app timezone a different window than the one they are reading.'
+            )
+        }
+
+        const unknown = presets
+            .map((preset) => preset?.name)
+            .filter((name) => name && ! isKnownPresetName(name))
+
+        // Without this an unknown name — a typo, or the `custom` sentinel a
+        // consumer migrating off a hand-rolled filter would carry over — just
+        // renders as a permanently disabled button with nothing in the console.
+        if (unknown.length > 0) {
+            console.warn(
+                `[FormFieldDateRange] unknown preset name(s): ${unknown.join(', ')}. `
+                + `Known names are ${KNOWN_PRESET_NAMES.join(', ')}. `
+                + 'An unknown name resolves to nothing, so its button stays disabled. '
+                + 'Note there is deliberately no `custom` preset: picking dates directly IS custom.'
+            )
+        }
+    },
+    { immediate: true, deep: true },
+)
+
+onMounted(() => {
+    leftMonth.value = anchorMonth()
+
+    emit('error', validationReason.value, range.value)
+})
+
+defineExpose({
+    focus() {
+        triggerElement.value?.focus()
+    },
+    open,
+    close,
+})
+</script>
+<template>
+<FormFieldSlot
+    :id="effectiveId"
+    :class="[$attrs.class, 'rsui-form-field-date-range']"
+    :required="$attrs.required"
+    :showAsterisk="$attrs.showAsterisk"
+    :compact="$attrs.compact"
+    :lg="$attrs.lg"
+>
+    <template #label v-if="$slots.label">
+        <slot name="label"></slot>
+    </template>
+
+    <div ref="fieldElement" class="rsui-form-field-date-range__group">
+        <button
+            ref="triggerElement"
+            type="button"
+            class="rsui-form-field-date-range__trigger"
+            :id="effectiveId"
+            :aria-labelledby="ariaLabelledby"
+            :aria-describedby="ariaDescribedby"
+            :aria-invalid="ariaInvalid"
+            :aria-required="isRequired || undefined"
+            :aria-expanded="isOpen ? 'true' : 'false'"
+            aria-haspopup="dialog"
+            :aria-controls="isOpen ? popoverId : undefined"
+            :disabled="isDisabled"
+            :name="$attrs.name"
+            @click="toggle"
+            @keydown.down.prevent="open"
+            @keydown.up.prevent="open"
+        >
+            <span v-if="displayValue" class="rsui-form-field-date-range__value">
+                {{ displayValue }}
+            </span>
+            <span v-if="! displayValue" class="rsui-form-field-date-range__placeholder">
+                <slot name="placeholder"></slot>
+            </span>
+        </button>
+
+        <div class="rsui-form-field-date-range__icon" aria-hidden="true">
+            <CalendarIcon></CalendarIcon>
+        </div>
+    </div>
+
+    <Teleport to="body">
+        <div
+            ref="popoverElement"
+            v-show="isOpen"
+            :id="popoverId"
+            role="dialog"
+            :aria-label="popoverLabel"
+            :class="[
+                'rsui-form-field-date-range__popover',
+                { 'rsui-form-field-date-range__popover--open': isOpen },
+            ]"
+            @keydown="handlePopoverKeydown"
+        >
+            <DateRangePresetRail
+                v-if="canResolvePresets"
+                :presets="presets"
+                :referenceDate="referenceDate"
+                :range="range"
+                :minDate="minDate"
+                :maxDate="maxDate"
+                @select="selectPreset"
+            ></DateRangePresetRail>
+
+            <div class="rsui-form-field-date-range__calendars">
+                <div class="rsui-form-field-date-range__nav">
+                    <button
+                        type="button"
+                        class="rsui-form-field-date-range__nav-button rsui-form-field-date-range__nav-button--previous"
+                        :aria-label="navCaptions.previous"
+                        @click="pageMonths(-1)"
+                    >
+                        <ChevronLeftIcon aria-hidden="true"></ChevronLeftIcon>
+                    </button>
+                    <button
+                        type="button"
+                        class="rsui-form-field-date-range__nav-button rsui-form-field-date-range__nav-button--next"
+                        :aria-label="navCaptions.next"
+                        @click="pageMonths(1)"
+                    >
+                        <ChevronRightIcon aria-hidden="true"></ChevronRightIcon>
+                    </button>
+                </div>
+
+                <div class="rsui-form-field-date-range__months" @keydown="handleGridKeydown">
+                    <DateRangeMonth
+                        :year="leftMonth.year"
+                        :monthIndex="leftMonth.monthIndex"
+                        :locale="locale"
+                        :weekdays="weekdays"
+                        :start="previewRange.start"
+                        :end="previewRange.end"
+                        :focusedDate="focusedDate"
+                        :minDate="minDate"
+                        :maxDate="maxDate"
+                        :referenceDate="referenceDate"
+                        @select="selectDay"
+                        @hover="handleHover"
+                    ></DateRangeMonth>
+
+                    <DateRangeMonth
+                        :year="rightMonth.year"
+                        :monthIndex="rightMonth.monthIndex"
+                        :locale="locale"
+                        :weekdays="weekdays"
+                        :start="previewRange.start"
+                        :end="previewRange.end"
+                        :focusedDate="focusedDate"
+                        :minDate="minDate"
+                        :maxDate="maxDate"
+                        :referenceDate="referenceDate"
+                        @select="selectDay"
+                        @hover="handleHover"
+                    ></DateRangeMonth>
+                </div>
+            </div>
+        </div>
+    </Teleport>
+
+    <template #help v-if="$slots.help">
+        <slot name="help"></slot>
+    </template>
+
+    <template #error v-if="$slots.error">
+        <slot name="error"></slot>
+    </template>
+</FormFieldSlot>
+</template>

package/src/components/FormField/FormFieldSlot.vue

@@ -65,7 +65,15 @@ const isRequired = computed(() =>
     <div v-if="$slots.label"
         :class="['rsui-form-field-slot__label', { 'rsui-form-field-slot__label--lg': lg }]"
     >
+        <!--
+            The id lets a control REFERENCE this label as well as be associated
+            with it. Native inputs only need `for`, but a control rendered as a
+            <button> takes its accessible name from its own subtree, so `for`
+            alone silently drops the label — such a control has to compose the
+            name itself with aria-labelledby, and cannot without an id to point at.
+        -->
         <label
+            :id="`${inputId}-label`"
             :for="inputId"
         >
             <slot name="label"></slot>

package/src/components/FormField/index.js

@@ -1,5 +1,6 @@
 import FormFieldCheckbox from './FormFieldCheckbox.vue'
 import FormFieldCombobox from './FormFieldCombobox.vue'
+import FormFieldDateRange from './FormFieldDateRange.vue'
 import FormFieldEmail from './FormFieldEmail.vue'
 import FormFieldHidden from './FormFieldHidden.vue'
 import FormFieldNumber from './FormFieldNumber.vue'
@@ -18,6 +19,7 @@ import FormFieldUploaderWrapper from './FormFieldUploaderWrapper.vue'
 export {
     FormFieldCheckbox,
     FormFieldCombobox,
+    FormFieldDateRange,
     FormFieldEmail,
     FormFieldHidden,
     FormFieldNumber,