@redseed/redseed-ui-vue3 8.70.0 → 10.0.0

package/package.json

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

package/src/components/Card/Card.vue

@@ -1,15 +1,32 @@
 <script setup>
-import { computed, ref, useSlots } from 'vue'
+import { computed, provide, ref, useSlots } from 'vue'
 import { useResponsiveWidth } from '../../helpers'
 
 const props = defineProps({
+    /**
+     * Whether the whole card is a control.
+     *
+     * Opt-in. It used to default to true, so every card was a focusable
+     * role="button" with a hover state until a consumer said otherwise — 44 call
+     * sites passing `:clickable="false"` and 38 passing `:hoverable="false"`,
+     * against exactly one card that opted in. Most cards are containers, and only
+     * an actionable thing may carry an actionable role (WCAG 4.1.2). A hover
+     * state, a pointer cursor and a focus ring are promises.
+     *
+     * `ButtonCard` exists for the deliberate case and passes this explicitly.
+     */
     clickable: {
         type: Boolean,
-        default: true,
+        default: false,
     },
+    /**
+     * Hover feedback. Opt-in for the same reason: a card that opens nothing
+     * should not respond as though it does. A clickable card usually wants this
+     * too, and asks for it.
+     */
     hoverable: {
         type: Boolean,
-        default: true,
+        default: false,
     },
     padded: {
         type: Boolean,
@@ -155,6 +172,21 @@ const accentStyle = computed(() =>
 
 const slots = useSlots()
 
+/**
+ * Whether this card will render a body, handed down so a CardHeader in the
+ * `header` slot can pay for its own bottom edge when there is nothing beneath it
+ * to borrow one from.
+ *
+ * `.rsui-card-header` is `pt-space-lg pb-0` on purpose — it takes its bottom edge
+ * from the body's padding. With no body, nobody pays, and the title sits flush
+ * against the card's border. `headerOnlyCard` existed for that but defaulted to
+ * false, so the broken rendering was the default and the correct one had to be
+ * asked for. CheckboxCard fell into it and it took a visual bug report to find.
+ *
+ * Mirrors the body's own `v-if` exactly, so the two cannot drift.
+ */
+provide('rsuiCardHasBody', computed(() => Boolean(slots.default || slots.meta)))
+
 const cardElement = ref(null)
 const { responsiveWidth } = useResponsiveWidth(cardElement)
 

package/src/components/Card/CardHeader.vue

@@ -1,7 +1,8 @@
 <script setup>
-import { computed, 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
@@ -45,9 +64,21 @@ const props = defineProps({
         type: Boolean,
         default: true,
     },
+    /**
+     * Pay for a bottom edge because nothing sits beneath this header.
+     *
+     * Left unset, a CardHeader inside a Card works it out: Card provides whether
+     * it will render a body, and a header with no body beneath it pads itself.
+     * That way the correct rendering is what you get, and this prop is an
+     * override rather than a requirement — it defaulted to false, which made the
+     * broken rendering the default.
+     *
+     * Null rather than false so an explicit `false` can still win. A CardHeader
+     * used outside a Card gets no answer and keeps the old behaviour.
+     */
     headerOnlyCard: {
         type: Boolean,
-        default: false,
+        default: null,
     },
     avatarTop: {
         type: Boolean,
@@ -59,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)
@@ -67,8 +114,22 @@ const { responsiveWidth } = useResponsiveWidth(cardHeaderElement, 640)
 
 const emit = defineEmits(['click:more-actions'])
 
+/**
+ * `null` means "no opinion from the consumer", so fall through to what the
+ * enclosing Card says. Outside a Card there is nothing to inject and the value
+ * is null, which lands on the old behaviour.
+ */
+const cardHasBody = inject('rsuiCardHasBody', null)
+
+const isHeaderOnly = computed(() => {
+    if (headerOnlyCard.value !== null) return headerOnlyCard.value
+    if (cardHasBody) return !cardHasBody.value
+
+    return false
+})
+
 const shouldPadBottom = computed(() =>
-    headerOnlyCard.value ? true : showDivider.value
+    isHeaderOnly.value ? true : showDivider.value
 )
 
 function handleMoreActionsClick() {
@@ -157,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/Card/CardHorizontal.vue

@@ -4,13 +4,20 @@ import { useResizeObserver, useMutationObserver } from '@vueuse/core'
 import Card from './Card.vue'
 
 const props = defineProps({
+    /**
+     * Declared here and forwarded to Card, so these defaults must track Card's —
+     * a true default here would have kept every CardHorizontal a focusable
+     * role="button" after Card's own flip, unreachable from a call site. Same
+     * trap SectionSlider hit with headingLevel and CardGroup/List with Empty's
+     * showImage. See #335.
+     */
     clickable: {
         type: Boolean,
-        default: true,
+        default: false,
     },
     hoverable: {
         type: Boolean,
-        default: true,
+        default: false,
     },
     bordered: {
         type: Boolean,

package/src/components/Card/MetricCard.vue

@@ -36,10 +36,34 @@ const props = defineProps({
     // assume light-on-dark: surface, ink, muted ink and rule move together.
     //
     // Not combinable with Card's semantic variants (brand, success, …) — pick one.
+    //
+    // `bloom` is for a MetricCard sitting on PageHeader's bloom band — not for that
+    // header's own stats strip, which is PageHeaderStat. Like the others it names an
+    // opaque surface rather than a translucent white: the band's own colour changes
+    // across its width, so a tile that let it through would have a different contrast
+    // ratio at each end of the same row. See metric_card.css for the measurement.
     tone: {
         type: String,
         default: null,
-        validator: value => ['green', 'teal', 'light'].includes(value),
+        validator: value => ['green', 'teal', 'light', 'bloom'].includes(value),
+    },
+    // Which edge carries a colour accent, and the token that paints it — both passed
+    // straight through to the underlying Card, which already implements them.
+    //
+    // A stat tile is the case the accent was made for: a strip of counts where one of
+    // them is the one to act on, and a rail down its leading edge says so without giving
+    // that tile a different surface from the rest of the row.
+    accent: {
+        type: String,
+        default: 'none',
+        validator: value => ['none', 'left', 'top'].includes(value),
+    },
+    // A runtime CSS variable NAME, not a colour — `Colors-Warm-Yellow-500` paints the
+    // rail Warm Yellow. Card's own note applies: an RSUI @theme token will not resolve,
+    // and an unresolvable one degrades to neutral grey rather than to an invisible edge.
+    color: {
+        type: String,
+        default: '',
     },
     // DIRECTION of travel — which arrow. Deliberately separate from `sentiment`,
     // because an arrow direction and a colour are not the same decision:
@@ -117,6 +141,8 @@ const comparisonId = useId()
     :clickable="props.clickable"
     :hoverable="props.hoverable"
     :pressed="active"
+    :accent="props.accent"
+    :color="props.color"
     ph-component="MetricCard"
 >
     <template v-if="$slots['aria-label']" #aria-label>

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/Empty/Empty.vue

@@ -1,5 +1,5 @@
 <script setup>
-import { ref, computed } from 'vue'
+import { ref, computed, useSlots } from 'vue'
 import ButtonPrimary from '../Button/ButtonPrimary.vue'
 import ButtonSecondary from '../Button/ButtonSecondary.vue'
 import ButtonTertiary from '../Button/ButtonTertiary.vue'
@@ -7,14 +7,84 @@ import BodyText from '../HTML/BodyText.vue'
 import IconCircleBackground from '../Icon/IconCircleBackground.vue'
 import { ExclamationCircleIcon } from '@heroicons/vue/24/outline'
 import { useResponsiveWidth } from '../../helpers'
+import { rendersContent } from '../../helpers/slots'
 
 const props = defineProps({
+    /**
+     * Whether to show the illustration above the message.
+     *
+     * Opt-in, because an empty state is a short message in a panel and a circled
+     * exclamation mark above it reads as a warning about a list that is merely
+     * new. Two thirds of call sites were already turning it off, which is the
+     * definition of a wrong default.
+     *
+     * It could not be fixed at the call sites: CardGroup and List render their
+     * own Empty and pass no `showImage`, so those four instances were unreachable
+     * from consuming code and showed the illustration whatever a consumer did.
+     * Flipping the default is the only change that reaches them. See #348.
+     *
+     * Note this gates the `image` slot too, so a consumer supplying their own
+     * illustration sets `showImage` alongside it.
+     */
     showImage: {
+        type: Boolean,
+        default: null,
+    },
+    /**
+     * Announce this empty state to a screen reader (WCAG 4.1.3).
+     *
+     * On by default. A list that changes state has to say so — someone who has
+     * just filtered a table to nothing gets silence where the rows were, and on
+     * a phone there is no peripheral view of the page to fall back on.
+     *
+     * Defaulting this to `false` would repeat the mistake this component was
+     * just fixed for: the right behaviour has to be what you get without asking.
+     * Turn it off for an empty state that is simply page content rather than the
+     * result of something the user did.
+     *
+     * A caveat worth knowing, because the attribute alone does not buy as much as
+     * it looks: a live region announces CHANGES made after it is registered. A
+     * region that is already present when the page loads stays quiet, which is
+     * what you want. But an Empty that is inserted wholesale — `v-if` flipping,
+     * which is what CardGroup and List both do — is announced inconsistently
+     * across screen readers, because the region and its content arrive together.
+     * For a guaranteed announcement the region has to outlive the change, which
+     * only the consumer can arrange.
+     */
+    announce: {
         type: Boolean,
         default: true,
     },
 })
 
+const slots = useSlots()
+
+/**
+ * Whether the illustration region renders. Three states, because two were not
+ * enough to flip the default without deleting work.
+ *
+ *   unset   — show only if a consumer supplied an `image` slot that renders
+ *             something. Passing the slot IS the opt-in.
+ *   true    — show, falling back to the built-in icon.
+ *   false   — hide, even with a slot supplied.
+ *
+ * `showImage` used to default to `true`, so every empty state led with a circled
+ * exclamation mark that reads as a warning about a list that is merely new — and
+ * two thirds of call sites turned it off. But the prop gates the `image` slot as
+ * well as the icon, so flipping it to a plain `false` would have silently deleted
+ * the illustration from everyone who had chosen their own: 14 places in the LMS,
+ * each a deliberate choice, none of them erroring. Hence the third state.
+ *
+ * Rendered output rather than slot presence, and 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. See helpers/slots.
+ */
+function showsImage() {
+    if (props.showImage !== null) return props.showImage
+
+    return rendersContent(slots.image)
+}
+
 const emit = defineEmits(['clickPrimaryAction', 'clickSecondaryAction', 'clickTertiaryAction'])
 
 const emptyElement = ref(null)
@@ -34,13 +104,15 @@ const emptyClass = computed(() => [
 <div v-if="$slots.title || $slots.default"
     ref="emptyElement"
     :class="emptyClass"
+    :role="announce ? 'status' : undefined"
+    :aria-live="announce ? 'polite' : undefined"
 >
     <!--
         Image slot with a default icon.
         This slot is used to render the image.
         The image is used to display an icon or an image.
     -->
-    <div v-if="showImage"
+    <div v-if="showsImage()"
         class="rsui-empty__image"
     >
         <slot name="image">

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({
@@ -15,14 +14,99 @@ const props = defineProps({
     //
     // A toned header supplies its own padding, so place it outside the page's content
     // gutter and let the band bleed. Omit the prop and nothing changes.
+    //
+    // `bloom` is the brand's hero treatment — a green-to-mauve sweep with three radial
+    // washes over it — rather than a flat fill like the other three. It is a tone rather
+    // than a modifier layered over one because its wash alphas are a measured contrast
+    // budget against its own base sweep; over a different background the measurement
+    // does not hold. See page_header.css for the figures.
     tone: {
         type: String,
         default: null,
-        validator: value => ['green', 'teal', 'light'].includes(value),
+        validator: value => ['green', 'teal', 'light', 'bloom'].includes(value),
+    },
+    // Bleeds a toned band to the viewport edges while keeping its text on the page's own
+    // gutter, so the greeting lines up with the logo and nav above it rather than sitting
+    // 24px from the screen edge.
+    //
+    // This is what a toned header wants in an app shell, and the note on `tone` — "place
+    // it outside the page's content gutter" — is the version of it a consumer has to build
+    // themselves. With this the header stays INSIDE the container where it belongs in the
+    // document, and only its paint escapes.
+    //
+    // Requires `overflow-x: clip` on the document (html and body): the bleed is measured
+    // in vw, which includes the scrollbar gutter, so it overshoots by half a scrollbar
+    // each side. Clip it on the document rather than on the page root — clipping the root
+    // clips the bleed itself, and the band's box reaches the edge while its paint stops at
+    // the container. `clip` rather than `hidden`, so neither element becomes a scroll
+    // container and position: sticky keeps working.
+    //
+    // No effect without a tone: there is no band to bleed.
+    bleed: {
+        type: Boolean,
+        default: false,
     },
 })
 
-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',
@@ -30,6 +114,7 @@ const pageHeaderClass = computed(() => [
         'rsui-page-header--profile': props.profile,
         'rsui-page-header--toned': !!props.tone,
         [`rsui-page-header--tone-${props.tone}`]: !!props.tone,
+        'rsui-page-header--bleed': !!props.tone && props.bleed,
     },
 ])
 </script>
@@ -41,6 +126,22 @@ const pageHeaderClass = computed(() => [
                     <slot name="avatar"></slot>
                 </div>
                 <div class="rsui-page-header__title-text">
+                    <!--
+                        A small label ABOVE the h1, matching CardHeader's #eyebrow: the
+                        line a page uses to say what kind of thing it is, or what day it
+                        is, before it says which one. Without it the only home for that
+                        line is #title, which puts it inside the h1 and gives the page two
+                        headings in one.
+
+                        Gated on slot presence alone rather than on a showEyebrow prop
+                        like CardHeader's, because every other slot on this component is
+                        gated the same way and a prop that only ever hides an absent
+                        element earns nothing.
+                    -->
+                    <div v-if="$slots.eyebrow" class="rsui-page-header__eyebrow">
+                        <slot name="eyebrow"></slot>
+                    </div>
+
                     <div class="rsui-page-header__title-text-container">
                         <h1>
                             <slot name="title"></slot>
@@ -55,37 +156,28 @@ const pageHeaderClass = computed(() => [
                 </div>
             </div>
 
+            <!--
+                A row of summary tiles belonging to the header itself — the counts a page
+                leads with, as MetricCards rather than as label/value pairs.
+
+                Inside __top rather than under it, so it inherits the row/column the
+                header already switches at lg: stacked under the title on a phone, beside
+                it on a desktop. That is one layout rule, not a second set of breakpoints.
+
+                NOT the meta slot. __meta is `hidden lg:flex` — a grid of label/value
+                facts that collapses into a modal on a phone (see #369) — and a count the
+                page leads with is not a fact you go looking for in a modal. It also
+                carries the tonal rule above it, which puts a line between the title and
+                anything placed there.
+            -->
+            <div v-if="$slots.stats" class="rsui-page-header__stats">
+                <slot name="stats"></slot>
+            </div>
+
             <div v-if="$slots.actions" class="rsui-page-header__status-actions">
 
 
                 <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>
@@ -108,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/Layout/PageHeaderStat.vue

@@ -0,0 +1,84 @@
+<script setup>
+import { computed } from 'vue'
+
+/*
+    One count in PageHeader's #stats row: a large figure with a small label under it,
+    on a tile that lets the header's band through.
+
+    NOT a MetricCard. The two look alike in a listing and are different objects: a
+    MetricCard is a Card — 24px padding, the sans number step, a comparison, a trend, a
+    sentiment — and is sized by the grid it sits in. This is a 150px tile, 12px/16px of
+    padding, a serif figure at 46px and nothing else, because it sits in a band beside a
+    title rather than in a dashboard. Reproducing it out of MetricCard meant overriding
+    most of MetricCard from the header's stylesheet, which is the smell this component
+    exists to remove. Reach for MetricCard when the tile is the content of the page.
+*/
+const props = defineProps({
+    // Renders a <button> rather than a <div>. A count that scrolls to its section or
+    // opens a filtered list is a control and has to be one — but a stat that only reports
+    // a number is not, and a button that does nothing is worse than a div (WCAG 4.1.2).
+    clickable: {
+        type: Boolean,
+        default: false,
+    },
+    // Renders an <a> instead, for a count whose destination is a page. Wins over
+    // `clickable`, since a link that is also a button is neither.
+    href: {
+        type: String,
+        default: '',
+    },
+    // Paints the rail down the tile's leading edge. A runtime CSS variable NAME, the same
+    // contract Card's `color` takes: `Colors-Warm-Yellow-500`, not a colour. RSUI's own
+    // @theme tokens are inlined into utilities and will NOT resolve here.
+    //
+    // The rail marks the one count in a row that is asking for something, without giving
+    // that tile a different surface from the rest. Unset, the edge is reserved and
+    // transparent, so a tile with a rail and one without still line up.
+    accent: {
+        type: String,
+        default: '',
+    },
+    // Names the control for assistive technology when the visible label is a fragment —
+    // "8 / To do" reads as two unrelated strings out of context.
+    ariaLabel: {
+        type: String,
+        default: '',
+    },
+})
+
+defineEmits(['click'])
+
+const tag = computed(() => {
+    if (props.href) return 'a'
+    if (props.clickable) return 'button'
+
+    return 'div'
+})
+
+// Only set when an accent is supplied, so the CSS transparent default holds otherwise.
+// Carries an inline fallback for the same reason Card's does: an unresolvable token
+// degrades to a neutral rail rather than to an invisible one.
+const accentStyle = computed(() =>
+    props.accent
+        ? { '--rsui-page-header-stat-accent': `var(--${props.accent}, var(--Colors-Grey-500))` }
+        : {},
+)
+</script>
+<template>
+    <component :is="tag"
+        class="rsui-page-header__stat"
+        :class="{ 'rsui-page-header__stat--interactive': tag !== 'div' }"
+        :style="accentStyle"
+        :type="tag === 'button' ? 'button' : undefined"
+        :href="tag === 'a' ? props.href : undefined"
+        :aria-label="props.ariaLabel || undefined"
+        @click="$emit('click', $event)"
+    >
+        <span class="rsui-page-header__stat-value">
+            <slot name="value"></slot>
+        </span>
+        <span class="rsui-page-header__stat-label">
+            <slot name="label"></slot>
+        </span>
+    </component>
+</template>

package/src/components/Layout/index.js

@@ -1,10 +1,12 @@
 import PageHeader from './PageHeader.vue'
+import PageHeaderStat from './PageHeaderStat.vue'
 import SidebarLayout from './SidebarLayout.vue'
 import SingleColumnLayout from './SingleColumnLayout.vue'
 import TwoColumnLayout from './TwoColumnLayout.vue'
 
 export {
     PageHeader,
+    PageHeaderStat,
     SidebarLayout,
     SingleColumnLayout,
     TwoColumnLayout,

package/src/components/Modal/Modal.vue

@@ -1,5 +1,5 @@
 <script setup>
-import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue'
+import { computed, nextTick, onMounted, onUnmounted, ref, useSlots, watch, watchEffect } from 'vue'
 
 // Apply all attributes to the input element, not the wrapper div
 defineOptions({
@@ -111,9 +111,11 @@ watch(() => props.show, (value) => {
         nextTick(() => {
             const modal = modalContentRef.value
             if (!modal) return
-            const focusable = modal.querySelector('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])')
-            if (focusable) {
-                focusable.focus()
+
+            const [firstFocusable] = focusableItems(modal)
+
+            if (firstFocusable) {
+                firstFocusable.focus()
             } else {
                 modal.focus()
             }
@@ -141,10 +143,110 @@ function closeOnEscape(e) {
     }
 }
 
-onMounted(() => document.addEventListener('keydown', closeOnEscape))
+/**
+ * `:not([disabled])` matters: the open-focus path used to omit it and could land
+ * focus on a disabled control, which then looks like focus went nowhere.
+ */
+const FOCUSABLE_SELECTOR = [
+    'button:not([disabled])',
+    '[href]',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(', ')
+
+function focusableItems(modal) {
+    return [...modal.querySelectorAll(FOCUSABLE_SELECTOR)]
+}
+
+/**
+ * The focus trap (WCAG 2.4.3). Nothing intercepted Tab, so focus walked out of
+ * the dialog and into the page behind it, where it could reach controls under an
+ * overlay it cannot see. `aria-modal="true"` does not help here — it makes screen
+ * readers treat outside content as inert, and does nothing to the tab order.
+ * Measured before the fix: a button outside the dialog stayed reachable.
+ *
+ * On `document` rather than the dialog, so it still catches Tab if focus has
+ * ended up outside — a click through a gap, or a stale activeElement — and pulls
+ * it back rather than only wrapping at the two ends.
+ */
+function trapTab(e) {
+    if (e.key !== 'Tab' || !props.show) return
+
+    const modal = modalContentRef.value
+    if (!modal) return
+
+    const items = focusableItems(modal)
+
+    // A dialog with nothing focusable still must not leak: the panel itself is
+    // `tabindex="-1"`, so it can hold focus even though it is not tabbable.
+    if (items.length === 0) {
+        e.preventDefault()
+        modal.focus()
+
+        return
+    }
+
+    const first = items[0]
+    const last = items[items.length - 1]
+    const active = document.activeElement
+
+    if (!modal.contains(active)) {
+        e.preventDefault()
+        first.focus()
+
+        return
+    }
+
+    if (!e.shiftKey && active === last) {
+        e.preventDefault()
+        first.focus()
+    }
+
+    if (e.shiftKey && active === first) {
+        e.preventDefault()
+        last.focus()
+    }
+}
+
+const slots = useSlots()
+
+/**
+ * `aria-labelledby` is bound to the header slot's id, so a modal with no header
+ * announces as "dialog" and nothing else. Eleven of the 45 in the product are in
+ * that state, one of which archives a team. The component knows, so it says so
+ * once rather than being missed eleven times.
+ *
+ * Slot *presence*, deliberately, rather than rendered output: the header slot is
+ * scoped (`:close`), and probing a scoped slot without passing its scope throws
+ * out of a consumer's own destructuring — the bug fixed in #330. Presence is
+ * enough to catch the case this is about.
+ *
+ * Dev-only and deferred by a tick, matching SectionFooter and ButtonSlot: this
+ * package ships raw `.vue` source, so an ungated warn reaches real users, and a
+ * modal whose header arrives a tick later should not be scolded for it.
+ */
+watchEffect((onCleanup) => {
+    if (process.env.NODE_ENV === 'production') return
+    if (!props.show) return
+    if (slots.header) return
+
+    const timer = setTimeout(() => console.warn(
+        '[RSUI] Modal: rendered with no `header` slot, so `aria-labelledby` is unset and the dialog announces as "dialog" with no name. Give it a header, or an accessible name another way.',
+    ), 0)
+
+    onCleanup(() => clearTimeout(timer))
+})
+
+onMounted(() => {
+    document.addEventListener('keydown', closeOnEscape)
+    document.addEventListener('keydown', trapTab)
+})
 
 onUnmounted(() => {
     document.removeEventListener('keydown', closeOnEscape)
+    document.removeEventListener('keydown', trapTab)
     document.body.style.overflow = null
 })
 

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
@@ -38,12 +49,24 @@ const props = defineProps({
     /**
      * Heading level (1-6) for the title. When set, the title renders as a real
      * <h1>-<h6> so consuming pages get a correct document outline (WCAG 1.3.1,
-     * 2.4.6). Left unset it stays a non-heading <span>, keeping existing
-     * consumers unaffected — pick the level that fits the page's heading order.
+     * 2.4.6).
+     *
+     * Defaults to 2. It used to default to null, which rendered a non-heading
+     * <span> — and three quarters of section titles in the product took that
+     * default: 72 of 97. Those sections did not exist for anyone navigating by
+     * heading, which is a WCAG 1.3.1 failure rather than untidiness, and it is
+     * not something a consumer can be expected to remember at every call site.
+     *
+     * 2 rather than 3 because PageHeader already renders the page title as <h1>,
+     * so a section beneath it wants 2 almost every time; a nested section asks
+     * for 3, as the 25 call sites that already pass a level are doing.
+     *
+     * Explicit null is still honoured, for a title that genuinely is not a
+     * section heading — a toolbar label rather than a landmark.
      */
     headingLevel: {
         type: [Number, String],
-        default: null,
+        default: 2,
         validator: (value) => value === null || ['1', '2', '3', '4', '5', '6'].includes(String(value)),
     },
 })
@@ -60,20 +83,61 @@ 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,
- * otherwise a non-heading <span> (preserves the previous, level-less markup).
+ * otherwise a non-heading <span>, which now requires passing null explicitly.
  */
 const titleTag = computed(() => props.headingLevel ? `h${props.headingLevel}` : 'span')
 </script>
@@ -86,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">
 
@@ -98,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 -->
@@ -129,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"
@@ -139,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'
@@ -37,12 +38,20 @@ const props = defineProps({
     },
     /**
      * Heading level (1-6) for the slider title. When set, the title renders
-     * as a real <h1>-<h6> for a correct document outline; left unset it stays
-     * a non-heading <span> so existing consumers are unaffected.
+     * as a real <h1>-<h6> for a correct document outline.
+     *
+     * Defaults to 2, matching SectionHeader. Declared here rather than left to
+     * SectionHeader's own default because this component forwards the value
+     * explicitly — so a null default would have passed null through and kept
+     * every slider title a non-heading <span> while every other section title
+     * became a heading. A default a call site cannot reach is the same trap
+     * CardGroup and List hit with Empty's showImage. See #337.
+     *
+     * Explicit null is still honoured for a title that is not a section heading.
      */
     headingLevel: {
         type: [Number, String],
-        default: null,
+        default: 2,
         validator: (value) => value === null || ['1', '2', '3', '4', '5', '6'].includes(String(value)),
     },
     /**
@@ -122,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/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))
+    })
+}