@redseed/redseed-ui-vue3 8.66.1 → 8.67.0

package/package.json

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