@redseed/redseed-ui-vue3 8.64.0 → 8.66.0

package/index.js

@@ -12,6 +12,7 @@ export * from './src/components/Button'
 export * from './src/components/ButtonGroup'
 export * from './src/components/Card'
 export * from './src/components/CardGroup'
+export * from './src/components/Category'
 export * from './src/components/Chart'
 export * from './src/components/Comment'
 export * from './src/components/Disclosure'

package/package.json

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

package/src/components/Category/CategoryList.vue

@@ -0,0 +1,177 @@
+<script setup>
+import { ref, computed } from 'vue'
+import Badge from '../Badge/Badge.vue'
+import { isSafeHref } from '../../helpers/href'
+
+const props = defineProps({
+    /**
+     * The categories, in the order the record gives them. Entries are either a string
+     * or `{ label, href }` — see `href` below for when the second form applies.
+     *
+     * Never sorted. The first category is usually the primary one, so alphabetising
+     * throws away the only ordering information the record carries.
+     */
+    items: {
+        type: Array,
+        default: () => [],
+    },
+    /**
+     * Accessible name for the list. A bare row of badges is four unexplained words to a
+     * screen reader; named, it announces as "Categories, list, 4 items".
+     */
+    label: {
+        type: String,
+        default: 'Categories',
+    },
+    /**
+     * How many categories show before the rest are counted. Four is the cap the header
+     * standards set: eight categories is four lines of a phone screen before the meta
+     * even starts.
+     *
+     * Zero — or anything below it — caps nothing, for the rare row that must show in
+     * full. There is deliberately no horizontal-scroller option, for the same reason a
+     * table never scrolls the page sideways.
+     */
+    cap: {
+        type: Number,
+        default: 4,
+    },
+    /**
+     * Toggle labels. `{count}` is substituted rather than concatenated, so a translation
+     * can put the number wherever its grammar needs it.
+     */
+    moreLabel: {
+        type: String,
+        default: '+{count} more',
+    },
+    fewerLabel: {
+        type: String,
+        default: 'Show fewer',
+    },
+    /**
+     * The toggle's accessible name. "+4 more" on its own says nothing about what there
+     * are four more of, and that visible text is otherwise the whole name.
+     *
+     * Each one extends its visible label rather than replacing it, which WCAG 2.5.3
+     * Label in Name requires: a name of "Show all 8 categories" over a button reading
+     * "+4 more" gives a speech-input user nothing to say.
+     */
+    expandLabel: {
+        type: String,
+        default: '+{count} more categories',
+    },
+    collapseLabel: {
+        type: String,
+        default: 'Show fewer categories',
+    },
+})
+
+const emit = defineEmits(['toggle'])
+
+const isExpanded = ref(false)
+
+/**
+ * Strings and `{ label, href }` both arrive here as the same shape, so the template has
+ * one branch rather than two.
+ *
+ * Labels are coerced and trimmed rather than dereferenced: `default: () => []` only
+ * applies to `undefined`, and Vue skips type checking entirely for a `null` on a
+ * non-required prop, so a null label arrives with no warning and `.trim()` on it would
+ * throw out of setup and take the parent subtree down.
+ *
+ * Empty labels are dropped. An empty badge is a rendering artefact — a grey pill with
+ * nothing in it — and it would also count against the cap, pushing a real category into
+ * the hidden remainder.
+ */
+const categories = computed(() => {
+    // Normalise both accepted item shapes, then drop the ones with nothing to render —
+    // done in one chain so an empty label cannot survive as a blank badge.
+    return props.items
+        .map(item => {
+            const isObject = item !== null && typeof item === 'object'
+            const rawLabel = isObject ? item.label : item
+            const rawHref = isObject ? item.href : ''
+            const href = String(rawHref ?? '').trim()
+
+            return {
+                label: String(rawLabel ?? '').trim(),
+                // A refused href degrades to a label rather than to nothing. The category
+                // is still a true fact about the record; only its link was unusable.
+                href: isSafeHref(href) ? href : '',
+            }
+        })
+        .filter(category => category.label !== '')
+})
+
+const isCapped = computed(() => props.cap > 0 && categories.value.length > props.cap)
+
+const visibleCategories = computed(() => {
+    if (!isCapped.value) return categories.value
+    if (isExpanded.value) return categories.value
+
+    return categories.value.slice(0, props.cap)
+})
+
+const hiddenCount = computed(() => categories.value.length - props.cap)
+
+function withCount(template, count) {
+    return String(template ?? '').replace('{count}', count)
+}
+
+const toggleText = computed(() => {
+    if (isExpanded.value) return props.fewerLabel
+
+    return withCount(props.moreLabel, hiddenCount.value)
+})
+
+/**
+ * A disclosure, not a one-way reveal. Removing the toggle on expand would drop keyboard
+ * focus to the body mid-interaction, and `aria-expanded` needs something to describe.
+ * The visible resting state is still just "+4 more".
+ */
+const toggleAccessibleName = computed(() => {
+    if (isExpanded.value) return withCount(props.collapseLabel, props.cap)
+
+    return withCount(props.expandLabel, hiddenCount.value)
+})
+
+function toggle() {
+    isExpanded.value = !isExpanded.value
+
+    emit('toggle', isExpanded.value)
+}
+</script>
+<template>
+<div v-if="categories.length > 0" class="rsui-category-list">
+    <ul class="rsui-category-list__items" :aria-label="label">
+        <li v-for="(category, index) in visibleCategories"
+            :key="index"
+            class="rsui-category-list__item"
+        >
+            <a v-if="category.href !== ''"
+                class="rsui-category-list__link"
+                :href="category.href"
+            >
+                <Badge neutral>{{ category.label }}</Badge>
+            </a>
+            <Badge v-if="category.href === ''" neutral>{{ category.label }}</Badge>
+        </li>
+    </ul>
+
+    <!--
+        Outside the list, because the toggle is not a category. Sibling to the `ul`
+        rather than inside it so the list keeps its semantics: `display: contents` on a
+        `ul` would let the items join this row directly, but it also drops list
+        semantics in Chrome and Safari, which is the one thing the row exists to keep.
+    -->
+    <button v-if="isCapped"
+        type="button"
+        class="rsui-category-list__more"
+        :aria-label="toggleAccessibleName"
+        :aria-expanded="isExpanded"
+        @click="toggle"
+    >
+        {{ toggleText }}
+    </button>
+</div>
+</template>

package/src/components/Category/index.js

@@ -0,0 +1,5 @@
+import CategoryList from './CategoryList.vue'
+
+export {
+    CategoryList,
+}

package/src/components/HTML/BodyText.vue

@@ -73,7 +73,12 @@ const clampClasses = {
     6: 'rsui-body-text--line-clamp-6',
 }
 
+// Only ONE of these applies, and the first match in this order wins — so
+// `onColor` leads. It marks a dark ground, and a muted ink passed alongside it
+// (`tertiary onColor` for a date under a body paragraph) is a light-ground grey
+// that all but disappears there; white is the readable reading of that pair.
 const colorClasses = {
+    onColor: 'rsui-body-text--on-color',
     secondary: 'rsui-body-text--secondary',
     tertiary: 'rsui-body-text--tertiary',
     quaternary: 'rsui-body-text--quaternary',
@@ -84,7 +89,6 @@ const colorClasses = {
     error: 'rsui-body-text--error',
     info: 'rsui-body-text--info',
     ai: 'rsui-body-text--ai',
-    onColor: 'rsui-body-text--on-color',
 }
 
 const clampClass = computed(() => clampClasses[props.lines] || null)

package/src/components/Layout/PageHeader.vue

@@ -95,6 +95,19 @@ const pageHeaderClass = computed(() => [
             </div>
         </div>
 
+        <!--
+            Between the subtitle and the meta, and outside `__top` for the same reason the
+            meta row is: both are full-width rows under the title block rather than
+            columns beside it.
+
+            Unlike the meta it is never hidden. The meta collapses into a modal below lg
+            because it is a grid of label/value pairs; categories are a wrapping row of
+            badges, and the cap is what keeps them short on a phone.
+        -->
+        <div v-if="$slots['categories']" class="rsui-page-header__categories">
+            <slot name="categories"></slot>
+        </div>
+
         <div v-if="$slots['meta']" class="rsui-page-header__meta">
             <slot name="meta"></slot>
         </div>

package/src/components/Section/Section.vue

@@ -5,7 +5,9 @@ const props = defineProps({
     variant: {
         type: String,
         default: 'primary',
-        validator: (value) => ['primary', 'secondary', 'brand', 'success', 'info', 'warning', 'error', 'ai', 'classic'].includes(value)
+        // `ai` is the pale animated wash; `ai-bold` is the same family at full
+        // strength — the dark plum surface Card's `aiBold` uses.
+        validator: (value) => ['primary', 'secondary', 'brand', 'success', 'info', 'warning', 'error', 'ai', 'ai-bold', 'classic'].includes(value)
     },
     bordered: {
         type: Boolean,
@@ -59,6 +61,7 @@ const variantClass = computed(() => [
         'rsui-section--warning': props.variant === 'warning',
         'rsui-section--error': props.variant === 'error',
         'rsui-section--ai': props.variant === 'ai',
+        'rsui-section--ai-bold': props.variant === 'ai-bold',
         'rsui-section--classic': props.variant === 'classic',
     },
 ])

package/src/components/Section/SectionFooter.vue

@@ -1,5 +1,6 @@
 <script setup>
 import { computed, watchEffect, useSlots, Comment, Fragment } from 'vue'
+import { isSafeHref } from '../../helpers/href'
 
 const props = defineProps({
     showContent: {
@@ -42,44 +43,16 @@ const viewAllLabelText = computed(() => String(props.viewAllLabel ?? '').trim())
 const rawViewAllHref = computed(() => String(props.viewAllHref ?? '').trim())
 
 /**
- * Schemes an anchor may safely carry. `javascript:` and `data:` in an href are
- * script execution, and this is a declared prop on a design-system component
- * rather than an attribute passthrough — a consuming app can reasonably expect
- * the anchor it did not write to be safe. Anything else is refused loudly, since
- * a link that quietly stops working is the failure this component exists to
- * avoid.
- */
-const SAFE_HREF_SCHEME = /^(https?:|mailto:|tel:)/i
-
-/**
- * `//evil.com` is protocol-relative: it starts with a slash but navigates to
- * another host entirely, so a leading-slash test alone would wave it through.
- */
-const PROTOCOL_RELATIVE = /^\/\//
-
-/**
- * Anything with a scheme has one before the first slash. No colon in that span
- * means a relative path — `courses/1`, `./x`, `../x`, `#anchor`, `?q=1` — which
- * cannot leave the site and so needs no allow-list of its own. This is what the
- * warning text has always told consumers to use; the previous check only accepted
- * paths beginning with `/`, and refused the rest while telling them they were
- * fine.
+ * `javascript:` and `data:` in an href are script execution, and this is a
+ * declared prop on a design-system component rather than an attribute
+ * passthrough — a consuming app can reasonably expect the anchor it did not
+ * write to be safe. Anything unrecognised is refused loudly, since a link that
+ * quietly stops working is the failure this component exists to avoid.
+ *
+ * The rule itself lives in `helpers/href`, because CategoryList builds an anchor
+ * out of a declared prop the same way and two copies of a safety check drift.
  */
-function isRelativeHref(href) {
-    const beforeFirstSlash = href.split('/')[0]
-
-    return !beforeFirstSlash.includes(':')
-}
-
-const isViewAllHrefSafe = computed(() => {
-    const href = rawViewAllHref.value
-
-    if (href === '') return true
-    if (PROTOCOL_RELATIVE.test(href)) return false
-    if (SAFE_HREF_SCHEME.test(href)) return true
-
-    return isRelativeHref(href)
-})
+const isViewAllHrefSafe = computed(() => isSafeHref(rawViewAllHref.value))
 
 const hasViewAllLabel = computed(() => viewAllLabelText.value !== '')
 

package/src/helpers/href.js

@@ -0,0 +1,46 @@
+/**
+ * Whether a URL is safe to put in an `href` this library renders itself.
+ *
+ * Internal on purpose — not re-exported from `helpers/index.js`. It is a guard for
+ * components that build an anchor out of a declared prop, not a public utility, and
+ * consuming apps have their own escaping rules.
+ *
+ * The rule is the one SectionFooter's view-all link established: a consuming app can
+ * reasonably expect an anchor it did not write to be safe, so `javascript:` and
+ * `data:` — which are script execution, not navigation — are refused, and so is
+ * anything else with an unrecognised scheme.
+ */
+
+/** Schemes an anchor may safely carry. */
+const SAFE_HREF_SCHEME = /^(https?:|mailto:|tel:)/i
+
+/**
+ * `//evil.com` is protocol-relative: it starts with a slash but navigates to another
+ * host entirely, so a leading-slash test alone would wave it through.
+ */
+const PROTOCOL_RELATIVE = /^\/\//
+
+/**
+ * Anything with a scheme has one before the first slash. No colon in that span means a
+ * relative path — `courses/1`, `./x`, `../x`, `#anchor`, `?q=1` — which cannot leave the
+ * site and so needs no allow-list of its own.
+ */
+function isRelativeHref(href) {
+    const beforeFirstSlash = href.split('/')[0]
+
+    return !beforeFirstSlash.includes(':')
+}
+
+/**
+ * An empty href counts as safe: it means "no link was asked for", which callers handle
+ * by rendering no anchor at all rather than by rejecting it.
+ */
+export function isSafeHref(href) {
+    const trimmed = String(href ?? '').trim()
+
+    if (trimmed === '') return true
+    if (PROTOCOL_RELATIVE.test(trimmed)) return false
+    if (SAFE_HREF_SCHEME.test(trimmed)) return true
+
+    return isRelativeHref(trimmed)
+}