@redseed/redseed-ui-vue3 8.69.0 → 9.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@redseed/redseed-ui-vue3",
-    "version": "8.69.0",
+    "version": "9.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,5 +1,5 @@
 <script setup>
-import { computed, ref, toRefs, useAttrs } from 'vue'
+import { computed, inject, ref, toRefs, useAttrs } from 'vue'
 import ButtonTertiary from '../Button/ButtonTertiary.vue'
 import Icon from '../Icon/Icon.vue'
 import { useResponsiveWidth } from '../../helpers'
@@ -45,9 +45,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,
@@ -67,8 +79,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() {

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

@@ -1,4 +1,6 @@
 <script setup>
+import { computed, useId } from 'vue'
+import { ArrowUpRightIcon, ArrowDownRightIcon, ArrowRightIcon } from '@heroicons/vue/24/outline'
 import Card from './Card.vue'
 import FlexContainer from '../FlexContainer/FlexContainer.vue'
 
@@ -34,12 +36,99 @@ 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:
+    // attrition up is bad, completions up is good. One prop driving both would
+    // render every metric where rising is bad in green.
+    trend: {
+        type: String,
+        default: null,
+        validator: value => ['up', 'down', 'flat'].includes(value),
+    },
+    // Whether that direction is GOOD NEWS — colour only. Defaults to deriving
+    // from `trend` (up => positive) so the common case stays terse, but it is
+    // independently overridable, which is the entire point of the split.
+    sentiment: {
+        type: String,
+        default: null,
+        validator: value => ['positive', 'negative', 'neutral'].includes(value),
+    },
+    // WHERE the comparison sits relative to the figure.
+    //
+    //   below   the comparison is a caption under the number (the default, and
+    //           what every existing tile already renders).
+    //   inline  the comparison sits on the number's own row, immediately beside
+    //           it, centred against its line box.
+    //
+    // A string rather than an `inlineComparison` boolean because the reference
+    // carries a third shape too — the change as a bordered chip pushed to the far
+    // right of the number row — and a boolean would have to be retired to add it.
+    //
+    // Inline is the tighter tile: it buys back a line of height, which is what
+    // makes a dense dashboard row of these work. It costs horizontal room, so the
+    // row wraps back to two lines rather than overflowing when the tile is narrow.
+    comparisonPlacement: {
+        type: String,
+        default: 'below',
+        validator: value => ['below', 'inline'].includes(value),
     },
 })
+
+// The terse default. `sentiment` is read first so an explicit value always wins,
+// including 'neutral', which is why this tests for null rather than falsiness.
+const TREND_SENTIMENT = {
+    up: 'positive',
+    down: 'negative',
+    flat: 'neutral',
+}
+
+const resolvedSentiment = computed(() => {
+    if (props.sentiment !== null) return props.sentiment
+
+    return TREND_SENTIMENT[props.trend] ?? 'neutral'
+})
+
+const TREND_ICON = {
+    up: ArrowUpRightIcon,
+    down: ArrowDownRightIcon,
+    flat: ArrowRightIcon,
+}
+
+const trendIcon = computed(() => TREND_ICON[props.trend] ?? null)
+
+// Ties the comparison to the number for assistive tech, so the trend is not read
+// as a loose fragment floating after the figure. DOM order already puts them
+// adjacent; aria-describedby is what survives the number being queried alone.
+const comparisonId = useId()
 </script>
 
 <template>
@@ -52,6 +141,8 @@ const props = defineProps({
     :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>
@@ -69,19 +160,82 @@ const props = defineProps({
             <div v-if="$slots.icon" class="rsui-metric-card__icon" aria-hidden="true">
                 <slot name="icon"></slot>
             </div>
-            <div class="rsui-metric-card__label">
-                <slot name="label"></slot>
+            <div class="rsui-metric-card__heading-text">
+                <div class="rsui-metric-card__label">
+                    <slot name="label"></slot>
+                </div>
+
+                <div v-if="$slots.description" class="rsui-metric-card__description">
+                    <slot name="description"></slot>
+                </div>
             </div>
         </div>
 
+        <!-- The figure and the thing that qualifies it, as one unit. The wrapper
+             stacks them by default, which renders exactly as the two siblings did
+             before it existed, and turns into a row when comparisonPlacement is
+             inline. Keeping both placements on the same two elements is what lets
+             the a11y wiring, the sentiment modifiers and the tonal overrides stay
+             placement-agnostic — only the direction of this one box changes. -->
         <div :class="[
-                'rsui-metric-card__number',
+                'rsui-metric-card__figure',
+                `rsui-metric-card__figure--${props.comparisonPlacement}`,
                 { 'rsui-metric-card--center': alignment === 'center' },
                 { 'rsui-metric-card--left': alignment === 'left' },
                 { 'rsui-metric-card--right': alignment === 'right' },
             ]"
         >
-            <slot name="number"></slot>
+            <div :class="[
+                    'rsui-metric-card__number',
+                    { 'rsui-metric-card--center': alignment === 'center' },
+                    { 'rsui-metric-card--left': alignment === 'left' },
+                    { 'rsui-metric-card--right': alignment === 'right' },
+                ]"
+                :aria-describedby="$slots.comparison ? comparisonId : undefined"
+            >
+                <slot name="number"></slot>
+            </div>
+
+            <!-- With the number at every labelFirst setting, matching the reference
+                 shape: the comparison qualifies the figure, not the label, so it
+                 stays with the figure wherever the label goes. -->
+            <div v-if="$slots.comparison"
+                :class="[
+                    'rsui-metric-card__comparison-row',
+                    { 'rsui-metric-card--center': alignment === 'center' },
+                    { 'rsui-metric-card--left': alignment === 'left' },
+                    { 'rsui-metric-card--right': alignment === 'right' },
+                ]"
+            >
+                <span :id="comparisonId"
+                    :class="[
+                        'rsui-metric-card__comparison',
+                        `rsui-metric-card__comparison--${resolvedSentiment}`,
+                    ]"
+                >
+                    <span v-if="trendIcon" class="rsui-metric-card__comparison-icon" aria-hidden="true">
+                        <component :is="trendIcon" />
+                    </span>
+
+                    <slot name="comparison"></slot>
+
+                    <!-- The quieter half of the reference's "Change and text": the change
+                         carries the sentiment colour, the phrase that qualifies it drops to
+                         tertiary ink so the eye lands on the figure first.
+
+                         A second slot rather than asking the consumer to wrap the phrase in
+                         a class themselves. The split is a colour decision, which belongs to
+                         the design system; the words and their translation stay with the
+                         consumer, exactly as the comparison itself does.
+
+                         Inside the comparison span, so it sits within the region the number's
+                         aria-describedby points at — "175.95% Increase vs last month" is one
+                         description of the figure, not a fragment plus an orphan. -->
+                    <span v-if="$slots.comparisonContext" class="rsui-metric-card__comparison-context">
+                        <slot name="comparisonContext"></slot>
+                    </span>
+                </span>
+            </div>
         </div>
 
         <div v-if="!labelFirst"
@@ -95,8 +249,14 @@ const props = defineProps({
             <div v-if="$slots.icon" class="rsui-metric-card__icon" aria-hidden="true">
                 <slot name="icon"></slot>
             </div>
-            <div class="rsui-metric-card__label">
-                <slot name="label"></slot>
+            <div class="rsui-metric-card__heading-text">
+                <div class="rsui-metric-card__label">
+                    <slot name="label"></slot>
+                </div>
+
+                <div v-if="$slots.description" class="rsui-metric-card__description">
+                    <slot name="description"></slot>
+                </div>
             </div>
         </div>
     </FlexContainer>

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

@@ -15,10 +15,37 @@ 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,
     },
 })
 
@@ -30,6 +57,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 +69,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,6 +99,24 @@ 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">
 
 

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

@@ -38,12 +38,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)),
     },
 })
@@ -73,7 +85,7 @@ const showToolbar = computed(() => {
 
 /**
  * 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>

package/src/components/Section/SectionSlider.vue

@@ -37,12 +37,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)),
     },
     /**