@redseed/redseed-ui-vue3 8.58.0 → 8.60.0

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>