@redseed/redseed-ui-vue3 10.0.0 → 10.3.0

package/src/components/Toast/Toast.vue

@@ -0,0 +1,388 @@
+<script setup>
+import { computed, onBeforeUnmount, onUpdated, ref, useSlots, watch, watchEffect } from 'vue'
+import Icon from '../Icon/Icon.vue'
+import { XMarkIcon } from '@heroicons/vue/24/outline'
+import { rendersContent } from '../../helpers/slots'
+
+/**
+ * A brief confirmation that an action completed, bottom-left, past tense.
+ *
+ * Distinct from MessageBox, which describes the state of the thing on screen and stays
+ * until the page changes:
+ *
+ *              MessageBox                    Toast
+ *   placement  in the page flow              fixed, bottom-left
+ *   lifetime   until the page changes        auto-dismisses, UNLESS it carries an action
+ *   purpose    state of the thing on screen  an action completed
+ *
+ * Declarative rather than imperative. `v-model` is the whole API, which means the
+ * consumer owns when it shows — including from an Inertia flash prop, which is how the
+ * LMS already drives its banners. An imperative `useToast()` would be a thin layer over
+ * this component rather than a different one, so it can be added later without changing
+ * anything here.
+ *
+ * ONE AT A TIME. Every toast is `position: fixed` at the same bottom-left coordinates
+ * with the same z-index, so a second one renders exactly on top of the first — the second
+ * hides it completely, and a screen reader announces both while only one is visible.
+ * There is no stacking or queueing here, so the consumer must show one at a time. A
+ * dev-only warning below says so if two are ever open at once.
+ */
+const props = defineProps({
+    /**
+     * Whether the toast is showing. Use with v-model.
+     */
+    modelValue: {
+        type: Boolean,
+        default: false,
+    },
+    /**
+     * How long it stays, in milliseconds. 0 keeps it up until it is dismissed.
+     *
+     * The default follows Material's snackbar: long enough to read a short sentence,
+     * short enough not to sit over the page.
+     *
+     * IGNORED when the toast carries an action — see `visibleDuration`. A toast that
+     * offers Undo and then takes it away is the failure this component must not have.
+     */
+    duration: {
+        type: Number,
+        default: 5000,
+        // Negative, NaN and Infinity all pass `type: Number` and all make setTimeout fire
+        // immediately — a toast that paints and vanishes in the same frame, which reads
+        // as "it never showed". Rejected here and defended again in visibleDuration(),
+        // because validators only warn and are stripped from production builds.
+        validator: (value) => Number.isFinite(value) && value >= 0,
+    },
+    /**
+     * Errors are assertive; confirmations are not.
+     *
+     * A confirmation announces politely, after whatever the screen reader is currently
+     * saying. An error interrupts, because the reader needs to know their action did not
+     * take effect before they move on.
+     */
+    variant: {
+        type: String,
+        default: 'default',
+        // The list is written out here rather than referencing VARIANTS below, and that
+        // is forced rather than sloppy: defineProps() is hoisted outside setup(), so it
+        // cannot close over a local. A test asserts the two stay in step.
+        validator: (value) => ['default', 'success', 'error'].includes(value),
+    },
+    closeLabel: {
+        type: String,
+        default: 'Dismiss',
+    },
+})
+
+const emit = defineEmits(['update:modelValue', 'close'])
+
+const VARIANTS = ['default', 'success', 'error']
+
+const isKnownVariant = computed(() => VARIANTS.includes(props.variant))
+
+const safeVariant = computed(() => isKnownVariant.value ? props.variant : 'default')
+
+const slots = useSlots()
+
+/**
+ * Whether the action slot draws anything.
+ *
+ * A function, never a computed: useSlots() is not reactive, so a computed over it caches
+ * its first answer for the life of the component (#332).
+ *
+ * And it asks what the slot RENDERS, not whether it was passed — `<template #action>`
+ * around a falsy v-if is a slot that exists and draws nothing, which would otherwise
+ * strand an ordinary confirmation on screen forever, waiting to be dismissed by hand.
+ * The scope is forwarded because a consumer destructuring `{ close }` compiles to a
+ * function that throws when probed bare.
+ */
+function rendersAction() {
+    return rendersContent(slots.action, { close })
+}
+
+/**
+ * The probe's answer, as a tracked value.
+ *
+ * Avoiding the `computed` cache is necessary but NOT sufficient, which is the bug this
+ * ref exists to fix: a function that nothing re-invokes caches exactly as hard as a
+ * computed does. The timer watcher below only re-runs on modelValue, duration and
+ * isPaused — the action's rendered state is none of those — so a `v-if` inside the slot
+ * could flip with nothing re-deciding the lifetime:
+ *
+ *   - Undo appears at t=2s while a 5s timer is already armed, and the toast dismisses at
+ *     t=5s taking Undo with it. Exactly the WCAG 2.2.1 failure this component is built to
+ *     prevent, arriving through the back door.
+ *   - Undo disappears, and the ordinary confirmation left behind never dismisses.
+ *
+ * onUpdated is the hook that sees it: a stable slot's reactive reads are tracked by THIS
+ * component's render effect, so the Toast re-renders when the consumer's condition flips.
+ * Guarded on an actual change, because restarting on every update would let an unrelated
+ * parent re-render hold the countdown open indefinitely.
+ */
+const hasAction = ref(rendersAction())
+
+onUpdated(() => {
+    const rendersNow = rendersAction()
+
+    if (rendersNow === hasAction.value) return
+
+    hasAction.value = rendersNow
+})
+
+/**
+ * A toast carrying an action DOES NOT auto-dismiss. `duration` is ignored entirely.
+ *
+ * This started as a doubled duration, which is not a fix. A keyboard user cannot pause
+ * what they have not reached yet: pause-on-focus only helps once focus is already inside
+ * the toast, and arriving there is the whole race — Tab has to walk from wherever they
+ * are, and the toast is teleported to the end of the body. Doubling 5s to 10s just moves
+ * the line they have to beat.
+ *
+ * So an auto-dismissing toast carrying the only route to Undo is a time limit on that
+ * action (WCAG 2.2.1), and the honest resolutions are the two ends: no action, or no
+ * auto-dismiss. It takes the second. A toast with an action stays until it is dismissed —
+ * by the action, the close button, or Escape.
+ *
+ * The countdown still pauses on hover and focus for the no-action case, where it is a
+ * courtesy to a slow reader rather than the only thing standing between them and a
+ * control they cannot reach.
+ */
+function visibleDuration() {
+    if (hasAction.value) return 0
+
+    // Defended here as well as in the validator: validators only warn, and are stripped
+    // from production builds entirely.
+    if (!Number.isFinite(props.duration) || props.duration < 0) return 0
+
+    // setTimeout clamps anything past a signed 32-bit millisecond count to immediate,
+    // which would turn "a very long toast" into "no toast".
+    return Math.min(props.duration, 2_147_483_647)
+}
+
+/**
+ * WCAG 2.2.1: the countdown pauses while the pointer is over the toast or while focus is
+ * inside it. Someone reading it is not finished with it, and a toast that vanishes
+ * mid-sentence is the failure this guards against.
+ *
+ * Only reachable in the no-action case — a toast carrying an action has no countdown to
+ * pause in the first place.
+ */
+const isPaused = ref(false)
+
+let timer = null
+
+function clearTimer() {
+    if (timer === null) return
+
+    clearTimeout(timer)
+    timer = null
+}
+
+function startTimer() {
+    clearTimer()
+
+    /*
+     * Closed: reset the pause and stop, before anything else.
+     *
+     * The reset matters because `mouseleave` does NOT fire for an element removed from
+     * under the pointer — verified in Chrome: no boundary event at removal, and none on
+     * the next mouse move. So a toast closed from outside (a route change, an Inertia
+     * visit clearing the flash) while the pointer happened to be resting over it would
+     * leave isPaused stuck true, and every later toast from this same instance would hit
+     * the guard below and never arm a timer. A toast that silently stops dismissing, with
+     * no way back except hovering it and moving away.
+     *
+     * Stopping here also keeps the slot probe out of the closed case. visibleDuration()
+     * runs the consumer's render code, and running it for a toast Vue has not rendered
+     * can throw out of a consumer expression that is only safe once the toast is up —
+     * `deleted.name` on a null — which Vue routes to app.config.errorHandler and reports
+     * as a production error for a toast nobody saw.
+     */
+    if (!props.modelValue) {
+        isPaused.value = false
+
+        return
+    }
+
+    const duration = visibleDuration()
+
+    if (duration === 0 || isPaused.value) return
+
+    timer = setTimeout(() => close('timeout'), duration)
+}
+
+function close(reason = 'dismiss') {
+    clearTimer()
+    emit('update:modelValue', false)
+    emit('close', reason)
+}
+
+/*
+ * The timer restarts on every input that changes it: opening and closing, pausing and
+ * resuming, a duration the consumer changes while it is up, and the action appearing or
+ * disappearing. Pausing then resuming gives the full duration again rather than the
+ * remainder — the reader has just looked away from it, so time already spent reading is
+ * not time they still have.
+ *
+ * Load-bearing and easy to break: this watcher is PRE-FLUSH and deduped by job id, which
+ * is what makes Tab between the action and the close button safe. `focusout` bubbles and
+ * fires before the matching `focusin`, so isPaused goes true -> false -> true inside one
+ * tick and startTimer runs once, at flush, reading the final value. Switching this to
+ * `flush: 'sync'` would restart the countdown in the middle of a keyboard journey
+ * through the toast.
+ */
+watch(
+    () => [props.modelValue, props.duration, isPaused.value, hasAction.value],
+    startTimer,
+    { immediate: true },
+)
+
+onBeforeUnmount(clearTimer)
+
+function pause() {
+    isPaused.value = true
+}
+
+function resume() {
+    isPaused.value = false
+}
+
+/**
+ * Escape dismisses, matching every other transient surface in the library.
+ *
+ * Bound to the toast rather than to the document: a toast does not trap focus and does
+ * not own the page, so swallowing Escape from wherever the user happens to be would take
+ * it from a dialog or a menu that has a better claim on it.
+ */
+function handleKeydown(event) {
+    if (event.key !== 'Escape' || event.repeat) return
+
+    close('escape')
+}
+
+const toastClass = computed(() => [
+    'rsui-toast',
+    `rsui-toast--${safeVariant.value}`,
+])
+
+/**
+ * Dev-only, matching MessageBox, ButtonSlot and LinkSlot — this package ships raw `.vue`
+ * source, so an ungated warn reaches real users' consoles.
+ */
+watchEffect(() => {
+    if (process.env.NODE_ENV === 'production') return
+
+    if (!isKnownVariant.value) {
+        console.warn(`[RSUI] Toast: variant "${props.variant}" is not supported (${VARIANTS.join(', ')}). Falling back to "default".`)
+    }
+
+    if (!Number.isFinite(props.duration) || props.duration < 0) {
+        console.warn(`[RSUI] Toast: duration must be a finite, non-negative number of milliseconds; received ${props.duration}. Staying up until dismissed. Use 0 to ask for that deliberately.`)
+    }
+    // The floor is this library's, not the specification's. WCAG 2.2.1 requires a time
+    // limit to be adjustable, extendable or switchable off — it names no minimum display
+    // time. 5000ms is Material's guidance, and quoting a number as if the criterion
+    // contained it is the kind of claim that gets read back in an audit.
+    else if (props.duration !== 0 && props.duration < 5000 && !hasAction.value) {
+        console.warn(`[RSUI] Toast: duration ${props.duration}ms is below the 5000ms this library treats as the floor for a message that disappears on its own. Use 0 to keep it up until dismissed.`)
+    }
+
+    if (props.modelValue && hasAction.value && props.duration !== 5000) {
+        console.warn('[RSUI] Toast: `duration` is ignored when the toast carries an action — an actionable toast never auto-dismisses, because handing someone an Undo and then taking it away is a time limit on that action (WCAG 2.2.1). Remove the prop, or remove the action.')
+    }
+
+    if (!props.modelValue) return
+
+    if (!rendersContent(slots.default)) {
+        console.warn('[RSUI] Toast: no message. The default slot is what the toast is for — an empty live region announces nothing and renders a pill containing only a close button.')
+    }
+
+    if (document.querySelectorAll('.rsui-toast').length > 1) {
+        console.warn('[RSUI] Toast: more than one toast is open. They are all fixed to the same bottom-left position, so they render exactly on top of each other and a screen reader announces every one while only the last is visible. Show one at a time.')
+    }
+
+    /*
+     * An ACTIONABLE toast raised over a modal is a keyboard trap, and a silent one.
+     *
+     * Modal binds trapTab to the document and pulls focus back into its panel on every
+     * Tab (Modal.vue:195). The toast is teleported to the end of the body, outside that
+     * panel, so it cannot be reached — its position on screen is irrelevant, which is why
+     * a centred modal and a bottom-left toast not overlapping does not help.
+     *
+     * Narrowed to the actionable case on purpose. A plain confirmation is also unreachable
+     * while the modal is up, but it auto-dismisses and unsticks itself, so warning about
+     * it would be noise for a situation that resolves on its own. An actionable toast
+     * never auto-dismisses, cannot be tabbed to, and cannot be Escaped (that handler is
+     * bound to the toast element) — the only exit is a mouse. That is the case worth a
+     * warning, and it is rare: it needs an Undo raised while a dialog is open.
+     *
+     * The real fix exempts .rsui-toast from Modal's trapTab and lifts the toast above the
+     * modal's z-index. That is a change to Modal and belongs in its own PR; this turns an
+     * invisible trap into a message in the meantime.
+     */
+    if (hasAction.value && document.querySelector('.rsui-modal, .rsui-drawer')) {
+        console.warn('[RSUI] Toast: an actionable toast was opened while a modal or drawer is on screen. The dialog traps Tab inside its own panel, so a keyboard user cannot reach this toast — and it never auto-dismisses, so there is no way out but a mouse. Errors and actions raised inside a dialog belong in the dialog.')
+    }
+})
+</script>
+<template>
+<!--
+    Teleported to the body so the toast is positioned against the viewport rather than
+    against whichever ancestor happens to carry a transform, a filter or a containment —
+    any of which makes `position: fixed` resolve to that ancestor instead, and none of
+    which the toast can see from where it is written.
+-->
+<Teleport to="body">
+    <div v-if="modelValue"
+        :class="toastClass"
+        :role="safeVariant === 'error' ? 'alert' : 'status'"
+        :aria-live="safeVariant === 'error' ? 'assertive' : 'polite'"
+        @mouseenter="pause"
+        @mouseleave="resume"
+        @focusin="pause"
+        @focusout="resume"
+        @keydown="handleKeydown"
+    >
+        <!--
+            rendersContent, not `$slots.icon` — a slot that exists and draws nothing would
+            otherwise emit an empty flex child, and the row's column gap would open 12px
+            of unexplained space. Measured. This is the presence-versus-renders bug
+            helpers/slots.js exists for, and the timer already gets it right.
+        -->
+        <div v-if="rendersContent($slots.icon)" class="rsui-toast__icon">
+            <slot name="icon"></slot>
+        </div>
+
+        <div class="rsui-toast__message">
+            <slot></slot>
+        </div>
+
+        <!--
+            One action, per Material's snackbar. Undo belongs here whenever undoing is
+            possible; the slot is scoped with `close` so the action can dismiss the toast
+            it lives in without the consumer tracking the model itself.
+
+            Calls rendersAction() rather than reading the hasAction ref, and that is
+            load-bearing: invoking the slot HERE, inside the render, is what subscribes
+            this component to the consumer's own `v-if` condition. Read the ref instead
+            and a hidden action is never probed during render, so nothing tracks the
+            condition, the component never re-renders when it flips, and onUpdated never
+            fires to restart the timer. The ref would freeze at its first answer — the
+            exact #332 shape, one level up.
+        -->
+        <div v-if="rendersAction()" class="rsui-toast__action">
+            <slot name="action" :close="close"></slot>
+        </div>
+
+        <button type="button"
+            class="rsui-toast__close"
+            :aria-label="closeLabel"
+            @click="close('dismiss')"
+        >
+            <Icon sm>
+                <XMarkIcon aria-hidden="true" />
+            </Icon>
+        </button>
+    </div>
+</Teleport>
+</template>

package/src/components/Toast/index.js

@@ -0,0 +1,5 @@
+import Toast from './Toast.vue'
+
+export {
+    Toast,
+}

package/src/composables/useFormFieldA11y.js

@@ -1,28 +1,85 @@
-import { inject, ref } from 'vue'
+import { computed, inject, useAttrs, useSlots } from 'vue'
 
-// Injection key used by FormFieldSlot to provide a11y values
+// Injection key used by FormFieldSlot to hand these values to anything nested deeper.
 export const FormFieldA11yKey = Symbol('FormFieldA11y')
 
 /**
- * Consumer side of a provide/inject pattern for WCAG a11y attributes.
+ * The three WCAG wiring values every field control needs:
  *
- * FormFieldSlot (the wrapper) provides three reactive values under FormFieldA11yKey:
- *   - inputId:          a unique ID (from _.uniqueId()) for <label for> / <input id> association
- *   - ariaDescribedby:  computed string linking to help/error text element IDs
- *   - ariaInvalid:      computed boolean, true when an error slot is present
+ *   - inputId          the id on the control, and the target of the label's `for`
+ *   - ariaDescribedby  points at the help and error text, when either is present
+ *   - ariaInvalid      true while an error slot is rendered
  *
- * Child input components (FormFieldText, Checkbox, Select, Toggle, etc.) call this
- * composable to inject those values and bind them to their <input> elements.
+ * THE ID IS GENERATED HERE, by the field component, and handed DOWN to FormFieldSlot.
+ * That direction is the whole point, and it used to run the other way (#342).
  *
- * Safe to use outside FormFieldSlot — returns ref(null) fallbacks so ARIA attributes
- * simply won't render when there's no wrapper providing help/error context.
+ * FormFieldSlot generates an id too, and provides it under FormFieldA11yKey — but
+ * FormFieldSlot is the field's CHILD: it is the root element of FormFieldText's template,
+ * not its wrapper. provide/inject only ever flows parent to child, so a field injecting
+ * what its own child provides gets nothing and silently fell back to ref(null). Measured
+ * before the fix, with no consumer id passed:
+ *
+ *     label[for]  form-field-1
+ *     input id    undefined
+ *
+ * The label pointed at an element that did not exist, and aria-describedby never rendered,
+ * so help and error text did not reach the control either. WCAG 3.3.2 and 1.3.1, on every
+ * field in the library that did not pass an id by hand.
+ *
+ * Five components had already worked around it by recomputing a local `effectiveId`, and
+ * in four of those the workaround was itself broken: the control took the local id while
+ * the label took FormFieldSlot's separate one, so the two still disagreed. Those are gone;
+ * this is the single place an id is minted.
+ *
+ * A consumer-supplied `id` still wins, so nothing changes for a call site that passes one.
+ *
+ * The inject is kept for the genuinely nested case — a control rendered *inside* a
+ * FormFieldSlot's slots rather than being its parent. When there is a provider above, its
+ * values win, which keeps a nested control on the same id as the label above it.
  */
 export function useFormFieldA11y() {
-    const a11y = inject(FormFieldA11yKey, null)
+    const provided = inject(FormFieldA11yKey, null)
+
+    /*
+     * Adopt an injected id only when no control owns it yet.
+     *
+     * A provider above means one of two things, and they look identical from here:
+     *
+     *   a consumer's bare FormFieldSlot wrapping this control — one field, and this IS its
+     *   control, so it should take the outer id or the label points at nothing;
+     *
+     *   another FIELD's FormFieldSlot, because this control sits in its #prefix, #suffix or
+     *   default slot — two controls, and taking the outer id puts the same id on both.
+     *
+     * The second was a real regression: `<FormFieldText><template #prefix><FormFieldText/>`
+     * rendered two inputs sharing one id, so `label[for]` resolved to whichever the browser
+     * picked. WCAG 4.1.1, and silent — the markup reads correctly and nothing warns.
+     *
+     * `idClaimed` is the discriminator. A field sets it when it puts the id on its own
+     * control; a bare FormFieldSlot leaves it false because it owns no control.
+     */
+    if (provided && !provided.idClaimed?.value) return provided
+
+    const attrs = useAttrs()
+    const slots = useSlots()
+
+    const autoId = _.uniqueId('form-field-')
+    const inputId = computed(() => attrs.id || autoId)
+
+    const ariaDescribedby = computed(() => {
+        const ids = []
+
+        if (slots.help) ids.push(`${inputId.value}-help`)
+        if (slots.error) ids.push(`${inputId.value}-error`)
+
+        return ids.length > 0 ? ids.join(' ') : undefined
+    })
+
+    const ariaInvalid = computed(() => slots.error ? true : undefined)
 
     return {
-        inputId: a11y?.inputId ?? ref(null),
-        ariaDescribedby: a11y?.ariaDescribedby ?? ref(null),
-        ariaInvalid: a11y?.ariaInvalid ?? ref(null),
+        inputId,
+        ariaDescribedby,
+        ariaInvalid,
     }
 }

package/src/helpers/slots.js

@@ -15,12 +15,15 @@ import { Comment, Fragment } from 'vue'
  * their own content down then stand it down for a slot that renders nothing, and
  * the region ends up empty, or the fallback it was suppressing comes back.
  *
- * Two callers, for two versions of that bug: SectionFooter, where an empty region
- * claimed `flex-1` and shoved a centred link into one half of the footer, and
+ * Two bugs worth keeping as worked examples. SectionFooter, where an empty region
+ * claimed `flex-1` and shoved a centred link into one half of the footer. And
  * SectionSlider, where an `#actions` slot rendering nothing let the arrows return
  * to the header while `hoverActions` had already put a pair on the rail — two
  * pairs on one rail, with identical accessible names.
  *
+ * Deliberately not a count of callers: there are several now, and the number was
+ * already stale the last two times someone added one.
+ *
  * Call this from the template or from a plain function, never from a `computed`:
  * `useSlots()` returns a non-reactive object, so a computed over it caches its
  * first answer for the life of the component and a conditionally-supplied slot