@redseed/redseed-ui-vue3 8.66.0 → 8.67.0

package/package.json

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

package/src/components/Chart/HeatmapChart.vue

@@ -0,0 +1,100 @@
+<script setup>
+// A magnitude grid: one cell per (row, column), shaded light-to-dark by the
+// size of its value. The GitHub contributions grid is the familiar example —
+// days down, weeks across.
+//
+// ApexCharts touches window/DOM, so this renders client-side only (guarded by
+// the `mounted` ref), matching the other rsui charts.
+//
+// Colour comes from the rsui sequential scale, never from the consumer: pass
+// `ranges` as plain numeric buckets and each one takes the next step of the
+// ramp, so a consuming app still writes no colours of its own.
+import { ref, computed, onMounted } from 'vue'
+import VueApexCharts from 'vue3-apexcharts'
+import { resolveTheme, baseChartOptions, deepMergeOptions } from './chartTheme'
+
+const props = defineProps({
+    // ApexCharts heatmap series: [{ name: <row label>, data: [{ x: <column
+    // label>, y: <value> }] }]. Rows render bottom-up, so pass them in the
+    // order you want read from the bottom of the grid.
+    series: {
+        type: Array,
+        default: () => [],
+    },
+    // Value buckets, lowest first: [{ from, to, name }]. Each takes the next
+    // step of the rsui scale, so five is the most that shade distinctly.
+    // Omitted, ApexCharts shades continuously from one colour.
+    ranges: {
+        type: Array,
+        default: () => [],
+    },
+    height: {
+        type: [Number, String],
+        default: 240,
+    },
+    // Escape hatch — deep-merged over the rsui defaults
+    options: {
+        type: Object,
+        default: () => ({}),
+    },
+})
+
+const root = ref(null)
+const mounted = ref(false)
+const theme = ref(resolveTheme(null))
+
+onMounted(() => {
+    theme.value = resolveTheme(root.value)
+    mounted.value = true
+})
+
+// Buckets past the end of the ramp reuse its darkest step rather than coming
+// back undefined, which ApexCharts renders as a black cell.
+const shadedRanges = computed(() =>
+    props.ranges.map((range, index) => ({
+        ...range,
+        color: theme.value.scale[index] ?? theme.value.scale[theme.value.scale.length - 1],
+    })),
+)
+
+const hasRanges = computed(() => props.ranges.length > 0)
+
+const chartOptions = computed(() =>
+    deepMergeOptions(
+        deepMergeOptions(
+            baseChartOptions({
+                type: 'heatmap',
+                theme: theme.value,
+                height: props.height,
+            }),
+            hasRanges.value
+                ? {
+                    plotOptions: {
+                        heatmap: {
+                            shadeIntensity: 0,
+                            enableShades: false,
+                            colorScale: { ranges: shadedRanges.value },
+                        },
+                    },
+                }
+                : {},
+        ),
+        props.options,
+    ),
+)
+</script>
+
+<template>
+    <div
+        ref="root"
+        class="rsui-chart"
+    >
+        <VueApexCharts
+            v-if="mounted"
+            type="heatmap"
+            :height="height"
+            :series="series"
+            :options="chartOptions"
+        />
+    </div>
+</template>

package/src/components/Chart/chartTheme.js

@@ -31,9 +31,24 @@ const PALETTE_TOKENS = [
     { name: '--Colors-RedSeed-Purple-600', fallback: 'hsla(271, 55%, 54%, 1)' },
 ]
 
+// Sequential light-to-dark ramp for magnitude charts (heatmap). Ordered, not
+// categorical: step 0 is the "nothing here" ground and every step after it
+// reads as more. Grey rather than the palest brand at the bottom so an empty
+// cell cannot be mistaken for a small value.
+const SCALE_TOKENS = [
+    { name: '--Colors-Grey-100', fallback: '#f5f5f5' },
+    { name: '--Colors-Brand-100', fallback: '#c8eadf' },
+    { name: '--Colors-Brand-300', fallback: '#53c6a3' },
+    { name: '--Colors-Brand-400', fallback: '#279b78' },
+    { name: '--Colors-Brand-500', fallback: '#136c52' },
+]
+
 const TEXT_TOKEN = { name: '--Colors-Grey-900', fallback: 'hsla(220, 24%, 12%, 1)' }
 const TEXT_MUTED_TOKEN = { name: '--Colors-Grey-700', fallback: 'hsla(220, 11%, 29%, 1)' }
 const GRID_TOKEN = { name: '--Colors-Grey-200', fallback: 'hsla(220, 5%, 92%, 1)' }
+// The surface the chart sits on. Heatmap cells tile edge to edge, so the gaps
+// between them are painted in this colour rather than left as holes.
+const SURFACE_TOKEN = { name: '--color-background-primary', fallback: 'hsla(0, 0%, 100%, 1)' }
 const FONT_TOKEN = { name: '--font-redseed', fallback: "'Inter', sans-serif" }
 
 function readToken(el, token) {
@@ -50,9 +65,11 @@ function readToken(el, token) {
 export function resolveTheme(el) {
     return {
         colors: PALETTE_TOKENS.map((token) => readToken(el, token)),
+        scale: SCALE_TOKENS.map((token) => readToken(el, token)),
         text: readToken(el, TEXT_TOKEN),
         textMuted: readToken(el, TEXT_MUTED_TOKEN),
         grid: readToken(el, GRID_TOKEN),
+        surface: readToken(el, SURFACE_TOKEN),
         fontFamily: readToken(el, FONT_TOKEN),
     }
 }
@@ -61,7 +78,7 @@ export function resolveTheme(el) {
  * Build the rsui ApexCharts defaults for a given chart type. Consumers layer
  * their own `options` over the result via deepMergeOptions().
  *
- * @param {'line'|'bar'|'donut'} type
+ * @param {'line'|'bar'|'donut'|'heatmap'} type
  * @param {object} theme         result of resolveTheme()
  * @param {number|string} height
  * @param {string[]} [categories] x-axis labels (line/bar)
@@ -118,6 +135,31 @@ export function baseChartOptions({ type, theme, height, categories, labels, stac
         options.yaxis = { labels: { style: { colors: theme.textMuted } } }
     }
 
+    if (type === 'heatmap') {
+        // The cell's own value is the reading, so no axis line, no grid and no
+        // legend — the colour scale carries the key instead.
+        //
+        // No entry animation either: ApexCharts fades a heatmap in cell by cell,
+        // which reads as a loading grid rather than a chart. The whole point of
+        // the grid is the shape you see at a glance, so show it at once.
+        options.chart.animations = { enabled: false }
+        options.legend = { show: false }
+        // Cells tile edge to edge, so the 2px gutter is a stroke painted in the
+        // surface colour — a transparent stroke paints nothing and the cells
+        // read as one solid block.
+        options.stroke = { width: 2, colors: [theme.surface] }
+        // No grid lines, but keep a gutter between the row labels and the first
+        // column so the key on the left is not jammed against the cells.
+        options.grid = { show: false, padding: { left: 8, right: 0 } }
+        options.xaxis = {
+            ...axis(categories, theme),
+            axisBorder: { show: false },
+            axisTicks: { show: false },
+            tooltip: { enabled: false },
+        }
+        options.yaxis = { labels: { style: { colors: theme.textMuted } } }
+    }
+
     if (type === 'donut') {
         options.labels = labels || []
         options.stroke = { width: 0 }

package/src/components/Chart/index.js

@@ -1,9 +1,11 @@
 import LineChart from './LineChart.vue'
 import BarChart from './BarChart.vue'
 import DoughnutChart from './DoughnutChart.vue'
+import HeatmapChart from './HeatmapChart.vue'
 
 export {
     LineChart,
     BarChart,
     DoughnutChart,
+    HeatmapChart,
 }

package/src/components/Section/SectionFooter.vue

@@ -1,6 +1,7 @@
 <script setup>
-import { computed, watchEffect, useSlots, Comment, Fragment } from 'vue'
+import { computed, watchEffect, useSlots } from 'vue'
 import { isSafeHref } from '../../helpers/href'
+import { rendersContent } from '../../helpers/slots'
 
 const props = defineProps({
     showContent: {
@@ -62,31 +63,6 @@ const showViewAll = computed(() => hasViewAllLabel.value && hasViewAllHref.value
 
 const slots = useSlots()
 
-/**
- * Whether a slot renders anything at all. Slot *presence* is not the same
- * question: `<template #default><Button v-if="canManage" /></template>` leaves a
- * truthy slot function that renders a comment placeholder, which would still
- * claim a `flex-1` region and shove the centred link into one half of the footer.
- */
-function rendersContent(slot) {
-    const nodes = slot?.()
-
-    if (!nodes) return false
-
-    // Comment vnodes are what a falsy `v-if` leaves behind. Fragments wrap lists
-    // and `<template v-if>` blocks, so a truthy wrapper around a falsy child is a
-    // Fragment whose only child is a Comment — counting its length would call that
-    // content and render an empty region claiming `flex-1`.
-    return nodes.some(rendersNode)
-}
-
-function rendersNode(node) {
-    if (node.type === Comment) return false
-    if (node.type === Fragment) return Array.isArray(node.children) && node.children.some(rendersNode)
-
-    return true
-}
-
 /**
  * Whether the view-all has the footer to itself, which is the case that wants
  * centring. With anything alongside it, a greedy region would split the row with

package/src/components/Section/SectionSlider.vue

@@ -1,5 +1,6 @@
 <script setup>
 import { ref, computed, watch, watchEffect, useSlots } from 'vue'
+import { rendersContent } from '../../helpers/slots'
 import { useScroll, useEventListener, watchDebounced } from '@vueuse/core'
 import Section from './Section.vue'
 import SectionHeader from './SectionHeader.vue'
@@ -124,13 +125,64 @@ const slots = useSlots()
 /**
  * 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.
- * The built-in arrows go to whichever placement `hoverActions` selects.
+ * The built-in arrows go to whichever placement `hoverActions` selects, unless
+ * a consumer `actions` slot displaces them from the header, in which case header
+ * mode renders none at all.
+ *
+ * Rendered output, not slot presence, and a plain function rather than a
+ * `computed`. Both matter, and getting either wrong breaks the combination this
+ * component exists to support — a consumer control in the header with the arrows
+ * on the rail:
+ *
+ *   - `Boolean(slots.actions)` is true for `<template #actions><Link v-if="hasMore"
+ *     /></template>` even when `hasMore` is false, because the slot function still
+ *     exists and just returns a comment. The arrows are this slot's FALLBACK
+ *     content, so Vue renders them back into the header the moment the slot
+ *     resolves to nothing — while `hoverActions` has already put a pair on the
+ *     rail. Two pairs on one rail, identical accessible names, and disagreeing
+ *     disabled states. Measured at four buttons.
+ *   - `useSlots()` is not reactive, so a `computed` over it has no dependency and
+ *     caches its first answer for the life of the component. A consumer writing
+ *     `<template v-if="hasMore" #actions>` against a count that arrives with a
+ *     fetch would never see their control appear at all.
+ *
+ * Same reasoning and the same helper as SectionFooter — see helpers/slots.
  */
-const hasCustomActions = computed(() => Boolean(slots.actions))
+/**
+ * The scope the `actions` slot is handed. Built once so the probe below and the
+ * real `<slot>` in the template receive the same object — a consumer template
+ * that destructures these compiles to a function destructuring its only
+ * parameter, so probing bare threw and rendered nothing at all.
+ */
+const actionsSlotScope = computed(() => ({
+    showNextSlide,
+    showPreviousSlide,
+    disabledPrevButton: disabledPrevButton.value,
+    disabledNextButton: disabledNextButton.value,
+}))
+
+function hasCustomActions() {
+    return rendersContent(slots.actions, actionsSlotScope.value)
+}
 
-const showHeaderActions = computed(() => hasCustomActions.value || !props.hoverActions)
+function showHeaderActions() {
+    return hasCustomActions() || !props.hoverActions
+}
 
-const showOverlayActions = computed(() => !hasCustomActions.value && props.hoverActions)
+/**
+ * Placement is `hoverActions`' decision alone. A custom `actions` slot does not
+ * suppress the overlay: the arrows are that slot's fallback content, so
+ * overriding it has already taken them out of the header — which is exactly when
+ * the rail needs them. Guarding on `hasCustomActions` here left the one
+ * combination consumers reach for (own header control, arrows on the rail) with
+ * no navigation at all from `lg` up, where the track is `overflow-x-hidden` and
+ * the arrows are the only way to move it. `hoverActions` exists to free the
+ * header for such a control in the first place.
+ *
+ * Safe as a `computed`: it reads only a prop. The header side is what has to
+ * track a slot.
+ */
+const showOverlayActions = computed(() => props.hoverActions)
 
 /**
  * Unique id for the slider
@@ -548,13 +600,8 @@ function showPreviousSlide() {
                     <slot name="see-all"></slot>
                 </template>
 
-                <template v-if="showHeaderActions" #actions>
-                    <slot name="actions"
-                        :showNextSlide="showNextSlide"
-                        :showPreviousSlide="showPreviousSlide"
-                        :disabledPrevButton="disabledPrevButton"
-                        :disabledNextButton="disabledNextButton"
-                    >
+                <template v-if="showHeaderActions()" #actions>
+                    <slot name="actions" v-bind="actionsSlotScope">
                         <SectionSliderAction direction="prev"
                             :disabled="disabledPrevButton"
                             :invert="featured"

package/src/helpers/slots.js

@@ -0,0 +1,59 @@
+import { Comment, Fragment } from 'vue'
+
+/**
+ * Whether a slot renders anything at all.
+ *
+ * Internal on purpose — not re-exported from `helpers/index.js`. It walks vnode
+ * internals, which is a detail of how this library composes its own regions
+ * rather than something consuming apps should depend on.
+ *
+ * Slot *presence* is a different question, and the wrong one in almost every
+ * case. `Boolean(slots.actions)` is true for
+ * `<template #actions><Button v-if="canManage" /></template>` even when
+ * `canManage` is false, because the slot function still exists — it just returns
+ * a comment placeholder. Components that use presence to decide whether to stand
+ * their own content down then stand it down for a slot that renders nothing, and
+ * the region ends up empty, or the fallback it was suppressing comes back.
+ *
+ * Two callers, for two versions of that bug: SectionFooter, where an empty region
+ * claimed `flex-1` and shoved a centred link into one half of the footer, and
+ * SectionSlider, where an `#actions` slot rendering nothing let the arrows return
+ * to the header while `hoverActions` had already put a pair on the rail — two
+ * pairs on one rail, with identical accessible names.
+ *
+ * Call this from the template or from a plain function, never from a `computed`:
+ * `useSlots()` returns a non-reactive object, so a computed over it caches its
+ * first answer for the life of the component and a conditionally-supplied slot
+ * would never appear.
+ *
+ * `scope` is REQUIRED for a scoped slot, and passing it is the caller's job. A
+ * consumer template that destructures its scoped props — `<template #actions="{
+ * showPreviousSlide }">` — compiles to a function that destructures its only
+ * parameter, so probing it bare throws `Cannot destructure property … of
+ * 'undefined'` and takes the whole component down with it. Hand it the same
+ * object the real `<slot>` receives, so the probe and the render agree. A
+ * non-scoped slot ignores the argument, so passing nothing stays correct there.
+ *
+ * Deliberately not wrapped in try/catch: that would swallow a genuine error
+ * thrown by the consumer's own slot content and leave a silently empty region.
+ */
+export function rendersContent(slot, scope) {
+    const nodes = slot?.(scope)
+
+    if (!nodes) return false
+
+    return nodes.some(rendersNode)
+}
+
+/**
+ * Comment vnodes are what a falsy `v-if` leaves behind. Fragments wrap lists and
+ * `<template v-if>` blocks, so a truthy wrapper around a falsy child is a
+ * Fragment whose only child is a Comment — counting length would treat that as
+ * content.
+ */
+function rendersNode(node) {
+    if (node.type === Comment) return false
+    if (node.type === Fragment) return Array.isArray(node.children) && node.children.some(rendersNode)
+
+    return true
+}