@redseed/redseed-ui-vue3 10.3.3 → 10.4.0

package/package.json

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

package/src/components/Card/CardHeader.vue

@@ -4,6 +4,8 @@ import ButtonTertiary from '../Button/ButtonTertiary.vue'
 import Icon from '../Icon/Icon.vue'
 import { rendersContent } from '../../helpers/slots'
 import { useResponsiveWidth } from '../../helpers'
+import DisclosureTrigger from '../Disclosure/DisclosureTrigger.vue'
+import { useDisclosureTrigger } from '../../composables/useDisclosureTrigger'
 import { EllipsisVerticalIcon } from '@heroicons/vue/24/outline'
 
 const props = defineProps({
@@ -11,6 +13,20 @@ const props = defineProps({
         type: Boolean,
         default: true,
     },
+    /**
+     * Render the enclosing Disclosure's trigger in the title row, rather than making
+     * the consumer leave an empty `<div :id="triggerId">` for it to be teleported
+     * into. Two lms1 call sites put that pad in `#more-actions`, where
+     * `:showMoreActions="false"` removes it and takes the trigger with it.
+     *
+     * Opt-in for the same reason as SectionHeader's: a CardHeader inside an outer
+     * Disclosure's content is still a descendant, and every call site that keeps its
+     * own pad would otherwise render two triggers. See #407.
+     */
+    collapsible: {
+        type: Boolean,
+        default: false,
+    },
     showBadge: {
         type: Boolean,
         default: true,
@@ -121,6 +137,9 @@ const emit = defineEmits(['click:more-actions'])
  */
 const cardHasBody = inject('rsuiCardHasBody', null)
 
+// Claims the enclosing Disclosure's trigger so it does not also render its own.
+const { rendersTrigger } = useDisclosureTrigger(() => props.collapsible)
+
 const isHeaderOnly = computed(() => {
     if (headerOnlyCard.value !== null) return headerOnlyCard.value
     if (cardHasBody) return !cardHasBody.value
@@ -182,10 +201,26 @@ function handleMoreActionsClick() {
 
             <!-- Title slot, default slot -->
             <div class="rsui-card-header__title-container">
+                <!--
+                    A SIBLING of the title, not a child of it. Unlike SectionHeader's
+                    `__title` — a flex row holding a separate `__title-text` — this one
+                    carries the line clamp itself (`--single-line` is `display:
+                    -webkit-box` with `-webkit-line-clamp`). A control inside a clamped
+                    box lays out as a block above the words, and counts against the clamp.
+                -->
+                <div v-if="rendersTrigger()"
+                    class="rsui-card-header__trigger"
+                >
+                    <DisclosureTrigger sm />
+                </div>
                 <div :class="[
                     'rsui-card-header__title',
                     {
                         'rsui-card-header__title--single-line': singleLine,
+                        // __title is w-full, which in this wrapping container would push
+                        // it onto the line below the trigger. It gives that up only when
+                        // it is no longer alone on the row.
+                        'rsui-card-header__title--with-trigger': rendersTrigger(),
                     }
                 ]">
                     <slot></slot>

package/src/components/Disclosure/Disclosure.vue

@@ -1,8 +1,6 @@
 <script setup>
-import { ref, shallowRef, watch, watchEffect, nextTick, onMounted, onBeforeUnmount } from 'vue'
-import { ChevronDownIcon } from '@heroicons/vue/24/outline'
-import { ButtonTertiary } from '../Button'
-import Icon from '../Icon/Icon.vue'
+import { ref, shallowRef, computed, watch, watchEffect, nextTick, onMounted, onBeforeUnmount, provide, toRef } from 'vue'
+import DisclosureTrigger from './DisclosureTrigger.vue'
 
 defineOptions({
     inheritAttrs: false,
@@ -43,6 +41,55 @@ function handleTrigger() {
     emit('click', { open: isOpen.value })
 }
 
+/**
+ * How a descendant renders its own trigger without a teleport target.
+ *
+ * `SectionHeader` and `CardHeader` take a `collapsible` prop and render a
+ * `DisclosureTrigger` from this, which is what lets the chevron sit in a title
+ * row at every width instead of being posted into an empty div the consumer had
+ * to place — and hide, or conditionally render, or wrap in utility classes to
+ * position. See #407; #408 removes the teleports once no consumer places a pad.
+ *
+ * Same shape as `Card` providing `rsuiCardHasBody` to `CardHeader`, including
+ * through a slot boundary: slot content is compiled in the parent's scope but
+ * mounted with this component as its parent instance, so inject resolves here.
+ *
+ * Refs rather than values, or a descendant would read the props once and never
+ * see `triggerLabel` change.
+ */
+/*
+ * How many descendants are rendering this disclosure's trigger themselves.
+ *
+ * A count rather than a flag: two headers inside one Disclosure is a consumer
+ * mistake, but it should not leave the count stuck claimed when only one of them
+ * unmounts.
+ */
+const descendantTriggers = ref(0)
+
+function claimTrigger() {
+    descendantTriggers.value++
+}
+
+function releaseTrigger() {
+    descendantTriggers.value--
+}
+
+// Whether THIS component still renders a trigger. It stands down entirely while a
+// descendant is rendering one — including when a teleport target exists, so a
+// consumer adopting `collapsible` without deleting their old pad gets one trigger
+// rather than two.
+const rendersOwnTrigger = computed(() => descendantTriggers.value === 0)
+
+provide('rsuiDisclosure', {
+    isOpen,
+    handleTrigger,
+    contentId,
+    triggerLabel: toRef(props, 'triggerLabel'),
+    iconProps: toRef(props, 'iconProps'),
+    claimTrigger,
+    releaseTrigger,
+})
+
 const contentRef = ref(null)
 
 async function setContentMaxHeight() {
@@ -161,7 +208,8 @@ onBeforeUnmount(() => {
         Vue's own `disabled` keeps this as one definition rendered in one of two
         places, rather than two copies that can drift.
     -->
-    <Teleport :to="triggerTarget"
+    <Teleport v-if="rendersOwnTrigger"
+        :to="triggerTarget"
         :disabled="!triggerTarget"
     >
         <slot name="trigger"
@@ -169,29 +217,19 @@ onBeforeUnmount(() => {
             :isOpen="isOpen"
             :contentId="contentId"
         >
-            <ButtonTertiary
+            <!--
+                The markup itself moved to DisclosureTrigger so a header can render
+                the same button in its own title row. Rendered here it is unchanged:
+                ButtonSlot treats an unset size prop and a false one alike.
+            -->
+            <DisclosureTrigger
                 :sm="$attrs.sm"
                 :md="$attrs.md"
                 :lg="$attrs.lg"
                 :xl="$attrs.xl"
                 :2xl="$attrs['2xl']"
                 :full="$attrs.full"
-                :aria-label="triggerLabel || undefined"
-                :aria-expanded="isOpen"
-                :aria-controls="contentId"
-                @click.stop="handleTrigger"
-            >
-                <Icon v-bind="iconProps">
-                    <ChevronDownIcon
-                        :class="[
-                            'rsui-disclosure__trigger-icon',
-                            {
-                                'rsui-disclosure__trigger-icon--open': isOpen,
-                            }
-                        ]"
-                    ></ChevronDownIcon>
-                </Icon>
-            </ButtonTertiary>
+            />
         </slot>
     </Teleport>
 

package/src/components/Disclosure/DisclosureTrigger.vue

@@ -0,0 +1,90 @@
+<script setup>
+import { inject } from 'vue'
+import { ChevronDownIcon } from '@heroicons/vue/24/outline'
+import ButtonTertiary from '../Button/ButtonTertiary.vue'
+import Icon from '../Icon/Icon.vue'
+
+/*
+ * The disclosure's chevron button, in one place.
+ *
+ * It used to live inline as `Disclosure`'s default `#trigger` content, which was
+ * fine while the Teleport was the only way to get it into a consumer's header.
+ * Now that a header can render its own (see `SectionHeader`'s `collapsible`),
+ * that inline definition would have had to be duplicated — and a duplicate is a
+ * drift waiting to happen, across `aria-expanded`, `aria-controls`, the label and
+ * the rotation class.
+ *
+ * So it MOVED here rather than being copied. `Disclosure` renders this as its own
+ * default, a header renders this, and a consumer placing one by hand renders this.
+ * One definition, one appearance, nothing to keep in sync. See #407.
+ */
+
+// Size passthrough, matching what Disclosure forwarded from its attrs. ButtonSlot
+// declares these as Boolean/false, so an unset prop and a false one are the same
+// button — the move does not change Disclosure's own rendering.
+defineProps({
+    sm: {
+        type: Boolean,
+        default: false,
+    },
+    md: {
+        type: Boolean,
+        default: false,
+    },
+    lg: {
+        type: Boolean,
+        default: false,
+    },
+    xl: {
+        type: Boolean,
+        default: false,
+    },
+    '2xl': {
+        type: Boolean,
+        default: false,
+    },
+    full: {
+        type: Boolean,
+        default: false,
+    },
+})
+
+/**
+ * `null` when there is no enclosing Disclosure, and then nothing renders — the
+ * same "no opinion, fall through quietly" shape `CardHeader` uses for
+ * `rsuiCardHasBody`. A trigger with nothing to toggle is worse than no trigger:
+ * it is a control that looks operable and answers to nothing.
+ */
+const disclosure = inject('rsuiDisclosure', null)
+</script>
+<template>
+<ButtonTertiary v-if="disclosure"
+    :sm="sm"
+    :md="md"
+    :lg="lg"
+    :xl="xl"
+    :2xl="$props['2xl']"
+    :full="full"
+    :aria-label="disclosure.triggerLabel.value || undefined"
+    :aria-expanded="disclosure.isOpen.value"
+    :aria-controls="disclosure.contentId"
+    @click.stop="disclosure.handleTrigger"
+>
+    <!--
+        `.stop` above is load-bearing rather than tidiness. A header that is itself
+        a control — `SectionHeader` with an `@click`, which is how a whole group
+        collapses on tap — would otherwise see this click bubble and toggle a
+        second time, landing back where it started. Pinned by a test.
+    -->
+    <Icon v-bind="disclosure.iconProps.value">
+        <ChevronDownIcon
+            :class="[
+                'rsui-disclosure__trigger-icon',
+                {
+                    'rsui-disclosure__trigger-icon--open': disclosure.isOpen.value,
+                }
+            ]"
+        ></ChevronDownIcon>
+    </Icon>
+</ButtonTertiary>
+</template>

package/src/components/Disclosure/index.js

@@ -1,6 +1,8 @@
 
 import Disclosure from './Disclosure.vue'
+import DisclosureTrigger from './DisclosureTrigger.vue'
 
 export {
-    Disclosure
-}
+    Disclosure,
+    DisclosureTrigger
+}

package/src/components/Section/SectionHeader.vue

@@ -4,6 +4,8 @@ import { rendersContent } from '../../helpers/slots'
 import ButtonTertiary from '../Button/ButtonTertiary.vue'
 import Icon from '../Icon/Icon.vue'
 import { useResponsiveWidth } from '../../helpers'
+import DisclosureTrigger from '../Disclosure/DisclosureTrigger.vue'
+import { useDisclosureTrigger } from '../../composables/useDisclosureTrigger'
 import { EllipsisVerticalIcon } from '@heroicons/vue/24/outline'
 
 const props = defineProps({
@@ -46,6 +48,46 @@ const props = defineProps({
         type: Boolean,
         default: false,
     },
+    /**
+     * Render the enclosing Disclosure's trigger in the title row.
+     *
+     * Consumers used to leave an empty `<div :id="triggerId">` for the trigger to be
+     * teleported into, and had to choose a slot to leave it in. Every choice was wrong
+     * somewhere: `#icon` is width-gated so the control vanished below 640px (#372);
+     * `#more-actions` is killed by `:showMoreActions="false"`, which threw
+     * `insertBefore` of null; `#actions` renders at every width but puts the chevron at
+     * the far end of the header, away from the title it collapses.
+     *
+     * OPT-IN, and that is load-bearing rather than politeness. A SectionHeader sitting
+     * in an outer Disclosure's content is still a descendant in the component tree, so
+     * rendering automatically would put chevrons on unrelated headers; and every call
+     * site that still places its own pad would get two triggers on upgrade. Default
+     * false means upgrading changes nothing until a header asks.
+     *
+     * Outside a Disclosure this renders nothing rather than warning — there is simply
+     * no disclosure to drive. See #407.
+     */
+    collapsible: {
+        type: Boolean,
+        default: false,
+    },
+    /**
+     * Keep the badge on the title line on a narrow header.
+     *
+     * `--stacked` puts `basis-full` on the title text, so below 640px the badge does
+     * not wrap when it runs out of room — it ALWAYS starts a new line. A group header
+     * carrying a count then stacks three rows above the first card, which is the second
+     * of the two reasons TeamCoachingIndex gives for hand-placing its badge inside the
+     * title rather than using `#badge` at all.
+     *
+     * Separate from `collapsible` on purpose: a collapsible section does not necessarily
+     * want an inline badge, and a badge-carrying section need not collapse. Default
+     * false, so no existing header moves. See #407.
+     */
+    inlineBadge: {
+        type: Boolean,
+        default: false,
+    },
     /**
      * 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,
@@ -111,6 +153,9 @@ function handleKeydown(event) {
 
 const slots = useSlots()
 
+// Claims the enclosing Disclosure's trigger so it does not also render its own.
+const { rendersTrigger } = useDisclosureTrigger(() => props.collapsible)
+
 /**
  * Whether the overflow region renders. The prop wins when set; otherwise the slot
  * decides by whether it actually produces anything.
@@ -192,8 +237,20 @@ const titleTag = computed(() => HEADING_LEVELS.includes(String(props.headingLeve
             <!-- Title slot, default slot -->
             <div :class="[
                 'rsui-section-header__title',
-                { 'rsui-section-header__title--stacked': !responsiveWidth.specific },
+                { 'rsui-section-header__title--stacked': !responsiveWidth.specific && !inlineBadge },
             ]">
+                <!--
+                    First child of the TITLE row, not a sibling of the whole text block
+                    the way `#icon` is: `__icon` centres against title AND subtitle
+                    together, so with a subtitle present the chevron drifts off the line
+                    it belongs to. `sm` matches the ACTION SIZE guidance in
+                    section_header.css.
+                -->
+                <div v-if="rendersTrigger()"
+                    class="rsui-section-header__trigger"
+                >
+                    <DisclosureTrigger sm />
+                </div>
                 <component :is="titleTag"
                     :class="[
                         'rsui-section-header__title-text',

package/src/composables/useDisclosureTrigger.js

@@ -0,0 +1,51 @@
+import { inject, watch, onBeforeUnmount } from 'vue'
+
+/**
+ * Lets a header render the enclosing Disclosure's trigger in its own markup.
+ *
+ * The claim is the point. `Disclosure` renders its trigger in place when it finds
+ * no teleport target (#406), which is the right fallback when nobody else is
+ * rendering one — but a header that renders its own would otherwise leave you with
+ * two, its own in the title row and Disclosure's falling out below the card. Both
+ * wired to the same disclosure, so both work, which is what makes it easy to miss.
+ *
+ * So a header claims while it is rendering a trigger, and `Disclosure` stands down
+ * for as long as the claim is held. A claim beats a teleport target too: a consumer
+ * that adopts `collapsible` without deleting their old `<div :id="triggerId">` gets
+ * one trigger in the title row rather than two in different places.
+ *
+ * Shared by SectionHeader and CardHeader rather than written twice — the release
+ * paths (prop flipped off, header unmounted) are exactly where a duplicate would
+ * drift. See #407; #408 deletes the teleport and with it the need to claim at all.
+ */
+export function useDisclosureTrigger(wantsTrigger) {
+    // `null` outside a Disclosure, the same fallback CardHeader uses for
+    // rsuiCardHasBody. `collapsible` then renders nothing: a trigger with nothing to
+    // toggle is worse than no trigger, since it looks operable and answers to nothing.
+    const disclosure = inject('rsuiDisclosure', null)
+
+    // Tracked here rather than read back off the context, so a release can never be
+    // paired with a claim this header did not make.
+    let hasClaimed = false
+
+    function syncClaim(claims) {
+        if (!disclosure?.claimTrigger) return
+        if (claims === hasClaimed) return
+
+        hasClaimed = claims
+
+        if (claims) disclosure.claimTrigger()
+        if (!claims) disclosure.releaseTrigger()
+    }
+
+    const rendersTrigger = () => Boolean(wantsTrigger() && disclosure)
+
+    watch(rendersTrigger, syncClaim, { immediate: true })
+
+    onBeforeUnmount(() => syncClaim(false))
+
+    return {
+        disclosure,
+        rendersTrigger,
+    }
+}