@redseed/redseed-ui-vue3 8.58.0 → 8.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@redseed/redseed-ui-vue3",
-    "version": "8.58.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
+}