@redseed/redseed-ui-vue3 8.60.0 → 8.61.0

package/index.js

@@ -42,6 +42,7 @@ export * from './src/components/Section'
 export * from './src/components/Skeleton'
 export * from './src/components/Social'
 export * from './src/components/Sorting'
+export * from './src/components/StageDial'
 export * from './src/components/Switcher'
 export * from './src/components/TabSlider'
 export * from './src/components/Table'

package/package.json

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

package/src/components/StageDial/StageDial.vue

@@ -0,0 +1,266 @@
+<script setup>
+import { ref, computed, onMounted } from 'vue'
+
+// A circular stage indicator built from DISCRETE segments — one per named stage,
+// filled up to the stage reached. Deliberately not ProgressCircle: a continuous
+// ring filled two-thirds reads as "67%", where three separate segments with two
+// filled reads as "the second of three named stages". For anything describing
+// capability or maturity rather than completion, the continuous version turns a
+// developmental stage into a score, which is the whole thing this avoids.
+const props = defineProps({
+    // Ordered stage labels, lowest first (e.g. ['Emerging', 'Developing', 'Strong']).
+    stages: {
+        type: Array,
+        default: () => [],
+    },
+    // The stage reached — fills every segment up to and including it. Matched
+    // against `stages` case-insensitively and trimmed, so both 'Developing' and
+    // 'developing' resolve. No match (or an empty value) fills nothing, which is
+    // the honest rendering for "no stage yet" rather than defaulting to stage one.
+    current: {
+        type: String,
+        default: '',
+    },
+    // The name of a RUNTIME CSS custom property to use as the accent for the
+    // filled segments — applied as `var(--<color>, <neutral>)`, same convention
+    // as Pill's `color` prop. Pass a real runtime theme variable, e.g. the
+    // consuming app's palette (`color7` → `var(--color7)`). NOTE: RSUI's own
+    // Tailwind `@theme` color tokens (e.g. `--color-brand-500`) are inlined into
+    // utilities, not exposed as runtime vars, so they will NOT resolve here. An
+    // UNRESOLVABLE (undefined) token degrades to a neutral grey rather than an
+    // invisible dial. Optional — falls back to a neutral accent when omitted, so
+    // RSUI stays theme-agnostic.
+    color: {
+        type: String,
+        default: '',
+    },
+    // Arc degrees. The default 270 leaves a 90° gap at the bottom for a label,
+    // and the empty span is always centred on the bottom whatever the sweep.
+    sweep: {
+        type: Number,
+        default: 270,
+    },
+    // Opt-in draw-in: filled segments animate their dash length from 0, staggered
+    // by segment. No-ops under `prefers-reduced-motion` (handled in CSS).
+    animate: {
+        type: Boolean,
+        default: false,
+    },
+    // Extra delay in ms before this dial's first segment draws. Lets a row of
+    // dials be staggered into a wave by passing an increasing delay per dial.
+    delay: {
+        type: Number,
+        default: 0,
+    },
+    // Optional prefix for the generated accessible label, e.g. 'Lead self' →
+    // "Lead self: Developing, stage 2 of 3".
+    label: {
+        type: String,
+        default: '',
+    },
+    // Size ramp. Booleans, only one applies at a time — matches the RSUI
+    // size-prop convention. Defaults to md.
+    sm: {
+        type: Boolean,
+        default: false,
+    },
+    md: {
+        type: Boolean,
+        default: false,
+    },
+    lg: {
+        type: Boolean,
+        default: false,
+    },
+})
+
+// --- geometry ---------------------------------------------------------------
+// Everything is drawn in a 100x100 viewBox so the whole dial scales with the
+// CSS box: the stroke is in user units, so it scales too.
+const RADIUS = 42
+const STROKE = 9
+// Preferred gap between segments, in path units. It MUST exceed the stroke
+// width: with `stroke-linecap: round` the caps extend half the stroke width past
+// each dash end, so a gap narrower than the stroke closes up and the segments
+// render as one continuous sweep — exactly the gauge look this component exists
+// to avoid. Twice the stroke is what reads unmistakably as separate stages.
+const PREFERRED_GAP = 18
+// Stagger between consecutive segments drawing in.
+const SEGMENT_STAGGER = 130
+
+const circumference = 2 * Math.PI * RADIUS
+
+// Clamped so a nonsense sweep still renders something sane.
+const safeSweep = computed(() => {
+    if (props.sweep < 30) return 30
+    if (props.sweep > 360) return 360
+
+    return props.sweep
+})
+
+const stageCount = computed(() => props.stages.length)
+
+// Total path length the segments and gaps share.
+const arcLength = computed(() => circumference * (safeSweep.value / 360))
+
+// The gap shrinks below the preferred value rather than letting the gaps eat the
+// arc, so a dial with many stages (or a tight sweep) still shows segments. Capped
+// at a third of each stage's nominal share of the arc, which keeps segments at
+// least twice the width of the gaps between them however many stages there are.
+const gapLength = computed(() => {
+    if (stageCount.value < 2) return 0
+
+    return Math.min(PREFERRED_GAP, arcLength.value / (stageCount.value * 3))
+})
+
+const segmentLength = computed(() => {
+    if (! stageCount.value) return 0
+
+    const gapTotal = gapLength.value * (stageCount.value - 1)
+
+    return (arcLength.value - gapTotal) / stageCount.value
+})
+
+// An SVG circle's path starts at 3 o'clock and runs clockwise, so an un-rotated
+// arc leaves its empty span centred at `sweep / 2 + 180`. Rotating the whole
+// group by the difference moves that span to the bottom (90°), which is where the
+// label goes — so the arc stays visually centred at any sweep.
+const rotation = computed(() => (90 - (safeSweep.value / 2 + 180) + 360) % 360)
+
+// --- stages -----------------------------------------------------------------
+// Compared lowercased so a consumer can pass either the label or a lowercase key.
+const normalisedStages = computed(() =>
+    props.stages.map((stage) => String(stage).trim().toLowerCase()),
+)
+
+const currentIndex = computed(() =>
+    normalisedStages.value.indexOf(String(props.current).trim().toLowerCase()),
+)
+
+// Segments up to and including the reached stage. Everything is derived from
+// this leading run, so unreached segments are never rendered at all — a
+// zero-length dash still paints a dot under round caps, so they have to be left
+// out rather than drawn at length 0.
+const filledCount = computed(() => currentIndex.value + 1)
+
+const segments = computed(() =>
+    props.stages.map((stage, index) => ({
+        stage,
+        index,
+        // Each segment starts one segment-plus-gap further round than the last.
+        offset: -(index * (segmentLength.value + gapLength.value)),
+        transitionDelay: `${props.delay + index * SEGMENT_STAGGER}ms`,
+    })),
+)
+
+const filledSegments = computed(() => segments.value.slice(0, filledCount.value))
+
+// --- animation --------------------------------------------------------------
+// Starts drawn when not animating, so a static dial paints in one frame.
+const isDrawn = ref(! props.animate)
+
+onMounted(() => {
+    if (! props.animate) return
+
+    // A frame later, so the transition has an initial value to move away from.
+    requestAnimationFrame(() => {
+        isDrawn.value = true
+    })
+})
+
+const dashArray = computed(() =>
+    isDrawn.value
+        ? `${segmentLength.value} ${circumference}`
+        : `0 ${circumference}`,
+)
+
+const trackDashArray = computed(() => `${segmentLength.value} ${circumference}`)
+
+// --- presentation -----------------------------------------------------------
+// Largest flag wins so a consumer passing more than one still gets a defined
+// result, and an unsized dial defaults to md.
+const activeSize = computed(() => {
+    if (props.lg) return 'lg'
+    if (props.md) return 'md'
+    if (props.sm) return 'sm'
+
+    return 'md'
+})
+
+const stageDialClass = computed(() => [
+    'rsui-stage-dial',
+    `rsui-stage-dial--${activeSize.value}`,
+    {
+        'rsui-stage-dial--animate': props.animate,
+    },
+])
+
+// When no color is supplied we leave the property unset so the CSS neutral
+// fallback applies. When a color IS supplied it carries an inline fallback to
+// the neutral grey, so an UNRESOLVABLE (undefined) token degrades to grey rather
+// than invisible segments. Note: var()'s fallback does not fire for a token that
+// *resolves* to transparent/empty — passing a real colour is the consumer's
+// responsibility.
+const accentStyle = computed(() =>
+    props.color
+        ? { '--rsui-stage-dial-accent': `var(--${props.color}, var(--Colors-Grey-500))` }
+        : {},
+)
+
+// The dial is a picture of a stage, not a percentage, so it gets `role="img"`
+// with a spelled-out label rather than progressbar semantics — an
+// `aria-valuenow` would reintroduce the score reading in the accessibility tree.
+const accessibleLabel = computed(() => {
+    if (! stageCount.value) return props.label
+
+    const reached = currentIndex.value
+    const stageText = reached === -1
+        ? `no stage reached, ${stageCount.value} stages`
+        : `${props.stages[reached]}, stage ${reached + 1} of ${stageCount.value}`
+
+    return props.label ? `${props.label}: ${stageText}` : stageText
+})
+
+// warn in development when the geometry will visually merge the segments
+if (process.env.NODE_ENV !== 'production') {
+    if (stageCount.value > 1 && gapLength.value <= STROKE) {
+        console.warn(
+            '[RSUI] StageDial segments will render as one continuous sweep: the gap between them is narrower than the stroke width. Widen `sweep` or pass fewer stages.',
+        )
+    }
+}
+</script>
+<template>
+<div :class="stageDialClass"
+    :style="accentStyle"
+    role="img"
+    :aria-label="accessibleLabel"
+>
+    <svg class="rsui-stage-dial__svg" viewBox="0 0 100 100" aria-hidden="true" focusable="false">
+        <g :transform="`rotate(${rotation} 50 50)`">
+            <circle v-for="segment in segments"
+                :key="`track-${segment.index}`"
+                class="rsui-stage-dial__track"
+                cx="50"
+                cy="50"
+                :r="RADIUS"
+                :stroke-dasharray="trackDashArray"
+                :stroke-dashoffset="segment.offset"
+            ></circle>
+            <circle v-for="segment in filledSegments"
+                :key="`fill-${segment.index}`"
+                class="rsui-stage-dial__fill"
+                cx="50"
+                cy="50"
+                :r="RADIUS"
+                :stroke-dasharray="dashArray"
+                :stroke-dashoffset="segment.offset"
+                :style="{ transitionDelay: segment.transitionDelay }"
+            ></circle>
+        </g>
+    </svg>
+    <div class="rsui-stage-dial__content">
+        <slot></slot>
+    </div>
+</div>
+</template>

package/src/components/StageDial/index.js

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