@redseed/redseed-ui-vue3 9.0.0 → 10.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@redseed/redseed-ui-vue3",
-    "version": "9.0.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/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/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))
+    })
+}