@redseed/redseed-ui-vue3 9.0.0 → 10.1.0

package/index.js

@@ -48,5 +48,6 @@ export * from './src/components/Switcher'
 export * from './src/components/TabSlider'
 export * from './src/components/Table'
 export * from './src/components/Toggle'
+export * from './src/components/Toast'
 export * from './src/components/Tooltip'
 export * from './src/helpers'

package/package.json

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

package/src/components/Card/CardHeader.vue

@@ -1,7 +1,8 @@
 <script setup>
-import { computed, inject, ref, toRefs, useAttrs } from 'vue'
+import { computed, inject, ref, toRefs, useAttrs, useSlots } from 'vue'
 import ButtonTertiary from '../Button/ButtonTertiary.vue'
 import Icon from '../Icon/Icon.vue'
+import { rendersContent } from '../../helpers/slots'
 import { useResponsiveWidth } from '../../helpers'
 import { EllipsisVerticalIcon } from '@heroicons/vue/24/outline'
 
@@ -28,9 +29,27 @@ const props = defineProps({
         type: Boolean,
         default: true,
     },
+    /**
+     * Force the overflow menu on, or suppress it.
+     *
+     * Left unset, the menu renders when the `more-actions` slot renders something
+     * — so a menu whose only option is behind a falsy `v-if` shows no trigger,
+     * rather than a three-dot button that opens on nothing. That was the bug: the
+     * gate tested the PROP, not what the slot produced.
+     *
+     * `true` forces it on, which is how a consumer asks for the built-in
+     * three-dot button with no slot of their own. `false` suppresses it even with
+     * a populated slot.
+     *
+     * Null rather than false as the default, and the gate is OR rather than AND,
+     * so every existing call site behaves identically: the ~38 that pass `false`
+     * still suppress, and the ones passing a slot with no prop — 3 in the LMS,
+     * plus this library's own Table.vue — still render. That makes the flip safe
+     * to ship without coordinating a consumer release. See #345.
+     */
     showMoreActions: {
         type: Boolean,
-        default: true,
+        default: null,
     },
     // Default false: Material 3 cards are one continuous padded surface, and a
     // full-bleed rule between the header and the body made every card read as two
@@ -71,6 +90,22 @@ const { showDivider, headerOnlyCard } = toRefs(props)
 
 const attrs = useAttrs()
 
+const slots = useSlots()
+
+/**
+ * Whether the overflow region renders. The prop wins when set; otherwise the slot
+ * decides by whether it actually produces anything.
+ *
+ * A plain function rather than a computed: `useSlots()` is not reactive, so a
+ * computed over it caches its first answer for the life of the component and a
+ * conditionally-supplied menu would never appear. See helpers/slots.
+ */
+function showsMoreActions() {
+    if (props.showMoreActions !== null) return props.showMoreActions
+
+    return rendersContent(slots['more-actions'], { handleMoreActionsClick })
+}
+
 const isClickable = computed(() => !!attrs.onClick)
 
 const cardHeaderElement = ref(null)
@@ -183,7 +218,7 @@ function handleMoreActionsClick() {
             </div>
 
             <!-- More actions slot, optional -->
-            <div v-if="showMoreActions"
+            <div v-if="showsMoreActions()"
                 class="rsui-card-header__more-actions"
             >
                 <slot name="more-actions"

package/src/components/Disclosure/Disclosure.vue

@@ -1,5 +1,5 @@
 <script setup>
-import { ref, watch, watchEffect, nextTick, onMounted } from 'vue'
+import { ref, watch, watchEffect, nextTick, onMounted, onBeforeUnmount } from 'vue'
 import { ChevronDownIcon } from '@heroicons/vue/24/outline'
 import { ButtonTertiary } from '../Button'
 import Icon from '../Icon/Icon.vue'
@@ -87,28 +87,43 @@ watch(isOpen, (open, wasOpen) => {
     }
 }, { flush: 'sync' })
 
+/**
+ * Whether each teleport target currently exists.
+ *
+ * Re-checked rather than latched. These used to only ever flip true, and the
+ * observer disconnected once both had been found — so a consumer that removed a
+ * target left a Teleport mounted against nothing and the trigger vanished.
+ * `SectionHeader` does exactly that: it width-gates the slots a target is
+ * mounted into, so narrowing a header past 640px took the trigger away and the
+ * section could no longer be opened. See #372.
+ */
 const canTeleportTrigger = ref(false)
 const canTeleportContent = ref(false)
 
+let observer = null
+
 function setTeleport() {
-    if (document.getElementById(triggerId)) canTeleportTrigger.value = true
-    if (document.getElementById(contentId)) canTeleportContent.value = true
+    canTeleportTrigger.value = Boolean(document.getElementById(triggerId))
+    canTeleportContent.value = Boolean(document.getElementById(contentId))
 }
 
 onMounted(() => {
     setTeleport()
 
-    const observer = new MutationObserver(() => {
-        setTeleport()
-
-        if (canTeleportTrigger.value && canTeleportContent.value) observer.disconnect()
-    })
+    // Never disconnected: a target can appear AND disappear over a component's
+    // life, so there is no point at which the answer is settled.
+    observer = new MutationObserver(setTeleport)
 
     observer.observe(document.body, {
         childList: true,
         subtree: true,
     })
 })
+
+onBeforeUnmount(() => {
+    observer?.disconnect()
+    observer = null
+})
 </script>
 
 <template>
@@ -121,8 +136,21 @@ onMounted(() => {
         ></slot>
     </div>
 
-    <Teleport v-if="canTeleportTrigger"
-        :to="`#${triggerId}`"
+    <!--
+        `disabled` rather than `v-if`, so the trigger renders in place when the
+        consumer supplies no target instead of not rendering at all.
+
+        There used to be no second branch: `<Teleport v-if="canTeleportTrigger">`
+        and nothing else, so a missing target meant no trigger ANYWHERE rather
+        than one in a less good place. `SectionHeader` width-gates the slots a
+        target is mounted into, so below 640px of its OWN width — container, not
+        viewport — a section simply could not be opened. See #372.
+
+        Vue's own `disabled` keeps this as one definition rendered in one of two
+        places, rather than two copies that can drift.
+    -->
+    <Teleport :to="`#${triggerId}`"
+        :disabled="!canTeleportTrigger"
     >
         <slot name="trigger"
             :handleTrigger="handleTrigger"
@@ -155,8 +183,9 @@ onMounted(() => {
         </slot>
     </Teleport>
 
-    <Teleport v-if="canTeleportContent"
-        :to="`#${contentId}`"
+    <!-- Same reasoning as the trigger above: in place rather than nowhere. -->
+    <Teleport :to="`#${contentId}`"
+        :disabled="!canTeleportContent"
     >
         <div ref="contentRef"
             :class="[

package/src/components/Layout/PageHeader.vue

@@ -1,6 +1,5 @@
 <script setup>
-import { ref, computed } from 'vue'
-import Modal from '../Modal/Modal.vue'
+import { ref, computed, onMounted, onBeforeUnmount } from 'vue'
 import ButtonTertiary from '../Button/ButtonTertiary.vue'
 
 const props = defineProps({
@@ -49,7 +48,65 @@ const props = defineProps({
     },
 })
 
-const showMetaModal = ref(false)
+/**
+ * The meta cap, and why the count is measured from the DOM rather than declared.
+ *
+ * `#meta` is a slot, and every consumer fills it with a `v-for` over their own
+ * data — so the component cannot know how many facts there are without either a
+ * prop nobody would remember to keep in sync, or walking vnodes. The row itself
+ * is capped in CSS with `:nth-child`, which needs no count at all; this observer
+ * exists only to decide whether the TOGGLE is needed, and what number to put in
+ * it.
+ *
+ * A MutationObserver rather than a one-off count, because those lists change:
+ * a fact arrives with a fetch, or a filter removes one, and a toggle offering
+ * "+2 more" when there is one left is worse than no toggle.
+ */
+const META_CAP = 4
+
+const metaElement = ref(null)
+const metaCount = ref(0)
+const isMetaExpanded = ref(false)
+
+const hiddenMetaCount = computed(() => Math.max(0, metaCount.value - META_CAP))
+
+const metaToggleLabel = computed(() =>
+    isMetaExpanded.value ? 'Show fewer' : `+${hiddenMetaCount.value} more`
+)
+
+/**
+ * WCAG 2.5.3 Label in Name: the accessible name has to contain the visible text,
+ * or a speech-input user has nothing to say. Same shape as CategoryList's toggle.
+ */
+const metaToggleAccessibleName = computed(() =>
+    isMetaExpanded.value
+        ? 'Show fewer details'
+        : `+${hiddenMetaCount.value} more details`
+)
+
+let metaObserver = null
+
+function countMetaFacts() {
+    if (!metaElement.value) return
+
+    // Every child is a fact: the toggle lives outside this element precisely so
+    // neither this count nor `:nth-child` has to special-case it.
+    metaCount.value = metaElement.value.children.length
+}
+
+onMounted(() => {
+    countMetaFacts()
+
+    if (!metaElement.value) return
+
+    metaObserver = new MutationObserver(countMetaFacts)
+    metaObserver.observe(metaElement.value, { childList: true })
+})
+
+onBeforeUnmount(() => {
+    metaObserver?.disconnect()
+    metaObserver = null
+})
 
 const pageHeaderClass = computed(() => [
     'rsui-page-header',
@@ -121,33 +178,6 @@ const pageHeaderClass = computed(() => [
 
 
                 <div class="rsui-page-header__actions">
-                    <div v-if="$slots['meta-action-label'] && $slots['meta']" class="rsui-page-header__meta-action">
-                        <ButtonTertiary @click="showMetaModal = true">
-                            <slot name="meta-action-label"></slot>
-                        </ButtonTertiary>
-
-                        <Modal sm v-if="$slots['meta']" class="rsui-page-header__meta-modal" :show="showMetaModal"
-                            @close="showMetaModal = false">
-                            <template #header v-if="$slots['meta-modal-header']">
-                                <slot name="meta-modal-header"></slot>
-                            </template>
-
-                            <div v-if="$slots.meta" class="rsui-page-header__meta-modal__body">
-                                <slot name="meta"></slot>
-                            </div>
-
-                            <template #footer v-if="$slots['meta-modal-footer'] || $slots['meta-modal-close-label']">
-                                <div v-if="$slots['meta-modal-footer']">
-                                    <slot name="meta-modal-footer"></slot>
-                                </div>
-
-                                <ButtonTertiary @click="showMetaModal = false">
-                                    <slot name="meta-modal-close-label"></slot>
-                                </ButtonTertiary>
-                            </template>
-                        </Modal>
-                    </div>
-
                     <slot name="actions"></slot>
                 </div>
             </div>
@@ -170,8 +200,48 @@ const pageHeaderClass = computed(() => [
             <slot name="categories"></slot>
         </div>
 
-        <div v-if="$slots['meta']" class="rsui-page-header__meta">
-            <slot name="meta"></slot>
+        <!--
+            Meta stays at every width. It used to be `hidden lg:flex`, with a
+            "Details" button opening a modal below lg — so the facts a header
+            exists to show disappeared on a phone, which is where a reader has
+            least context to spare. See #369.
+
+            The cap is CSS rather than JS: `#meta` is a slot and its contents are
+            usually a `v-for`, so the component cannot count facts without
+            inspecting vnodes, and a count taken at setup would be wrong the
+            moment the list changed. `:nth-child` does not need to know.
+        -->
+        <div v-if="$slots['meta']" class="rsui-page-header__meta-region">
+            <!--
+                The facts and the toggle are siblings in the GRID but the toggle
+                is not one of the facts, and `:nth-child` cannot tell the
+                difference — put it inside the same element and it takes a
+                position, shifting every fact after it and hiding one too many.
+                Measured: with six facts the toggle landed fourth and only three
+                showed.
+
+                So the facts own this element alone, and the toggle sits after it
+                in a wrapper that participates in the same grid via
+                `display: contents`. The count is then honest at every size.
+            -->
+            <div :class="[
+                    'rsui-page-header__meta',
+                    { 'rsui-page-header__meta--expanded': isMetaExpanded },
+                ]"
+                ref="metaElement"
+            >
+                <slot name="meta"></slot>
+            </div>
+
+            <button v-if="hiddenMetaCount > 0"
+                type="button"
+                class="rsui-page-header__meta-toggle"
+                :aria-expanded="isMetaExpanded"
+                :aria-label="metaToggleAccessibleName"
+                @click="isMetaExpanded = !isMetaExpanded"
+            >
+                {{ metaToggleLabel }}
+            </button>
         </div>
     </div>
 </template>

package/src/components/Section/SectionHeader.vue

@@ -1,5 +1,6 @@
 <script setup>
 import { ref, computed, useAttrs, useSlots } from 'vue'
+import { rendersContent } from '../../helpers/slots'
 import ButtonTertiary from '../Button/ButtonTertiary.vue'
 import Icon from '../Icon/Icon.vue'
 import { useResponsiveWidth } from '../../helpers'
@@ -18,9 +19,19 @@ const props = defineProps({
         type: Boolean,
         default: true,
     },
+    /**
+     * Force the overflow menu on, or suppress it. Left unset, the menu renders
+     * when the `more-actions` slot renders something — so a menu whose only
+     * option is behind a falsy `v-if` shows no trigger rather than a three-dot
+     * button that opens on nothing.
+     *
+     * Null default with an OR gate, so every existing call site is unaffected:
+     * the ones passing `false` still suppress, the ones passing a slot with no
+     * prop still render. Same shape as CardHeader. See #345.
+     */
     showMoreActions: {
         type: Boolean,
-        default: true,
+        default: null,
     },
     // Default false. It was true, but no CSS rule existed behind the --divider class,
     // so every consumer has been seeing no rule regardless. The rule exists now; keeping
@@ -72,16 +83,57 @@ function handleMoreActionsClick() {
 
 const attrs = useAttrs()
 
+/**
+ * A header with a click handler is a control, so it gets a control's semantics —
+ * a role, a tab stop and keyboard activation — rather than only a pointer cursor
+ * and a hover state.
+ *
+ * It responded to a click before this, but as a plain <div>: nothing announced
+ * it, nothing could reach it by keyboard, and the hover state was a promise it
+ * could not keep. See #338.
+ *
+ * This is also what takes the disclosure trigger out of the width-gated `#icon`
+ * slot: with the header itself as the target, a section no longer becomes
+ * unopenable below 640px of container width. See #372.
+ */
 const isClickable = computed(() => !!attrs.onClick)
 
+/**
+ * Enter and Space, the two keys a button answers to. `.self` so a keypress inside
+ * the header's own controls — a more-actions menu, a toolbar button — does not
+ * also toggle the header, and a repeat guard so a held key fires once.
+ */
+function handleKeydown(event) {
+    if (event.repeat) return
+
+    attrs.onClick?.(event)
+}
+
 const slots = useSlots()
 
-const showToolbar = computed(() => {
-    const showMoreActions = props.showMoreActions && slots['more-actions']
+/**
+ * Whether the overflow region renders. The prop wins when set; otherwise the slot
+ * decides by whether it actually produces anything.
+ */
+function showsMoreActions() {
+    if (props.showMoreActions !== null) return props.showMoreActions
 
-    return props.showActions
-        && (slots.actions || showMoreActions)
-})
+    return rendersContent(slots['more-actions'], { handleMoreActionsClick })
+}
+
+/**
+ * Whether the toolbar region renders at all.
+ *
+ * A plain function, not a computed. `useSlots()` returns a non-reactive object,
+ * so a computed over it cached its first answer for the life of the component —
+ * a consumer supplying `#actions` conditionally would never have seen the toolbar
+ * appear. That is the #332 defect, and this is the confirmed-broken instance of
+ * it: the desktop region is gated here while the mobile one reads `$slots.actions`
+ * inline, so the same header worked below 640px and not above it.
+ */
+function showsToolbar() {
+    return props.showActions && (rendersContent(slots.actions) || showsMoreActions())
+}
 
 /**
  * Element used to render the title — a real heading when a level is supplied,
@@ -98,6 +150,10 @@ const titleTag = computed(() => props.headingLevel ? `h${props.headingLevel}` :
             'rsui-section-header--clickable': isClickable,
         }
     ]"
+    :role="isClickable ? 'button' : undefined"
+    :tabindex="isClickable ? 0 : undefined"
+    @keydown.enter.self.prevent="handleKeydown"
+    @keydown.space.self.prevent="handleKeydown"
 >
     <div class="rsui-section-header__header">
 
@@ -110,7 +166,7 @@ const titleTag = computed(() => props.headingLevel ? `h${props.headingLevel}` :
 
         <div :class="{
             'rsui-section-header__text': true,
-            'rsui-section-header__text--with-toolbar': showToolbar || $slots.icon,
+            'rsui-section-header__text--with-toolbar': showsToolbar() || $slots.icon,
         }">
 
             <!-- Title slot, default slot -->
@@ -141,7 +197,7 @@ const titleTag = computed(() => props.headingLevel ? `h${props.headingLevel}` :
 
         <!-- Actions slot, optional -->
         <div class="rsui-section-header__toolbar"
-            v-if="showToolbar"
+            v-if="showsToolbar()"
         >
             <!-- Desktop actions slot, optional -->
             <div class="rsui-section-header__actions-desktop"
@@ -151,7 +207,7 @@ const titleTag = computed(() => props.headingLevel ? `h${props.headingLevel}` :
             </div>
 
             <!-- More actions slot, optional -->
-            <div v-if="showMoreActions"
+            <div v-if="showsMoreActions()"
                 class="rsui-section-header__more-actions"
             >
                 <slot name="more-actions"

package/src/components/Section/SectionSlider.vue

@@ -1,6 +1,7 @@
 <script setup>
-import { ref, computed, watch, watchEffect, useSlots } from 'vue'
+import { ref, computed, watch, watchEffect, useSlots, useAttrs } from 'vue'
 import { rendersContent } from '../../helpers/slots'
+import { warnOnUnknownProps } from '../../helpers/unknownProps'
 import { useScroll, useEventListener, watchDebounced } from '@vueuse/core'
 import Section from './Section.vue'
 import SectionHeader from './SectionHeader.vue'
@@ -130,6 +131,14 @@ const sliderClasses = computed(() => [
 
 const slots = useSlots()
 
+/**
+ * Both sliders in the product pass a `variant` prop this component does not have.
+ * Vue drops it into `$attrs`, it lands on the root as a bare DOM attribute, and
+ * nothing happens — so the consumer believes they configured something. Dev-only.
+ * See #339.
+ */
+warnOnUnknownProps('SectionSlider', useAttrs())
+
 /**
  * A consumer-supplied `actions` slot always wins and always renders in the
  * header — that slot exists so consumers can put their own controls up there.

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/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

package/src/helpers/unknownProps.js

@@ -0,0 +1,72 @@
+import { watchEffect } from 'vue'
+
+/**
+ * Warn, in development, when a component is handed an attribute that looks like
+ * a prop it does not declare.
+ *
+ * Internal — not re-exported from `helpers/index.js`. It is a authoring guard for
+ * this library's own components, not something a consuming app should call.
+ *
+ * The case it catches: a consumer passes `variant="featured"` to a component with
+ * no `variant` prop. Vue puts it in `$attrs`, it lands on the root as a bare DOM
+ * attribute, and nothing happens — no effect, no error, nothing in the console.
+ * The consumer believes they have configured something. Both sliders in the
+ * product do exactly this (#339).
+ *
+ * Deliberately conservative about what counts as suspicious, because a warning
+ * that cries wolf is worse than none: anything a consumer legitimately passes
+ * through is ignored, and only a plain lowercase word with no dash is flagged.
+ * That is the shape of a prop name, and it is not the shape of `data-*`,
+ * `aria-*`, an event listener, or a standard global attribute.
+ */
+
+/**
+ * Attributes any consumer may pass for their own reasons. Not exhaustive — it
+ * does not need to be, because the dash and `on*` rules below already exclude
+ * most of what is left.
+ */
+const PASS_THROUGH = new Set([
+    'id', 'class', 'style', 'title', 'role', 'tabindex', 'hidden', 'slot', 'part',
+    'lang', 'dir', 'draggable', 'contenteditable', 'spellcheck', 'translate',
+    'autofocus', 'inert', 'popover', 'key', 'ref',
+])
+
+function looksLikeAProp(name) {
+    if (PASS_THROUGH.has(name)) return false
+
+    // `data-*`, `aria-*`, and any other namespaced or hyphenated attribute.
+    if (name.includes('-')) return false
+
+    // Event listeners arrive as onClick, onFooBar.
+    if (/^on[A-Z]/.test(name)) return false
+
+    // A prop name is a bare word, optionally camelCased.
+    return /^[a-z][a-zA-Z0-9]*$/.test(name)
+}
+
+/**
+ * @param {string} component  Name used in the message, e.g. 'SectionSlider'.
+ * @param {object} attrs      The component's `useAttrs()` object.
+ *
+ * Call from `setup()`. Dev-only and deferred by a tick, matching SectionFooter
+ * and Modal: this package ships raw `.vue` source, so an ungated warn reaches
+ * real users' consoles, and an attribute that is present for one tick during a
+ * transition should not be scolded.
+ */
+export function warnOnUnknownProps(component, attrs) {
+    if (process.env.NODE_ENV === 'production') return
+
+    watchEffect((onCleanup) => {
+        const suspicious = Object.keys(attrs).filter(looksLikeAProp)
+
+        if (suspicious.length === 0) return
+
+        const timer = setTimeout(() => console.warn(
+            `[RSUI] ${component}: received ${suspicious.map(name => `\`${name}\``).join(', ')}, which ${suspicious.length === 1 ? 'is not a prop' : 'are not props'} of this component. `
+            + `${suspicious.length === 1 ? 'It has' : 'They have'} landed on the root element as a plain attribute and will do nothing. `
+            + 'Check the spelling, or remove it.',
+        ), 0)
+
+        onCleanup(() => clearTimeout(timer))
+    })
+}