Make pass/fail edges the loudest lines in the run graph
Treat `success` and `error` as the emphasised outcomes so pass/fail is obvious at a glance and from a distance. An executed pass/fail edge now uses PASSFAIL_EDGE_STROKE=7f (was 3f), a same-hue, more saturated stroke (PASSFAIL_SATURATION=1.6f via the new pure boostSaturation helper) and a matched PASSFAIL_ARROW_HEAD_SIZE=20f arrowhead. Other executed outcomes keep EDGE_STROKE=3f and not-executed routes the finer INACTIVE_EDGE_STROKE=2.5f, so the two decisive outcomes dominate. All widths, the arrowhead size and the saturation factor are named tokens chosen by edgeStrokeWidth/edgeArrowHeadSize/edgeStrokeColor; the old 12f arrowhead literal at the call site is gone (drawArrowHead now takes the size as a parameter). Outcome hues are unchanged; the boosted stroke keeps the original hue and value. The run Graph tab help line notes that executed success and failure routes are drawn thickest, and the definition-only view gets the same emphasis since every route counts as executed there. New unit tests cover the saturation maths (hue/value/alpha preserved, safe and clamped) and the per-edge width/arrowhead/colour choices.
This commit is contained in:
@@ -94,6 +94,36 @@ internal fun graphNodeKind(terminal: Boolean, key: String, type: String?): Graph
|
||||
else -> GraphNodeKind.Custom
|
||||
}
|
||||
|
||||
/**
|
||||
* A more vivid version of [color] with the same hue, value and alpha: the HSV
|
||||
* saturation is scaled by [factor] and clamped to 1. Used to make an executed
|
||||
* pass/fail edge stroke stronger without changing its outcome hue, so both
|
||||
* terminal colours get more punch while staying recognisably success/failure.
|
||||
*
|
||||
* Pure sRGB maths. A non-finite/non-positive [factor], an achromatic colour or
|
||||
* one already at full saturation returns [color] unchanged, so callers never get
|
||||
* NaN and every input is safe.
|
||||
*/
|
||||
internal fun boostSaturation(color: Color, factor: Float): Color {
|
||||
if (!factor.isFinite() || factor <= 0f) return color
|
||||
val r = color.red
|
||||
val g = color.green
|
||||
val b = color.blue
|
||||
val max = maxOf(r, g, b)
|
||||
val min = minOf(r, g, b)
|
||||
val delta = max - min
|
||||
if (max <= 0f || delta <= 0f) return color
|
||||
val current = delta / max
|
||||
val saturation = (current * factor).coerceAtMost(1f)
|
||||
if (saturation <= current) return color
|
||||
val hue = (when (max) {
|
||||
r -> ((g - b) / delta + 6f) % 6f
|
||||
g -> (b - r) / delta + 2f
|
||||
else -> (r - g) / delta + 4f
|
||||
}) * 60f
|
||||
return Color.hsv(hue, saturation, max, color.alpha)
|
||||
}
|
||||
|
||||
/**
|
||||
* WCAG relative luminance of [color] (sRGB), the building block of the WCAG
|
||||
* contrast ratio. Pure so the palette's legibility is measured in a unit test
|
||||
|
||||
@@ -145,8 +145,11 @@ internal data class ZoomResult(val offset: Offset, val scale: Float)
|
||||
* not-executed one is dashed and arrowless (nodes hollow with a muted, legible
|
||||
* label), so the two states differ in shape, fill and border style rather than
|
||||
* by a faded tint and survive a screenshot, a dim screen and a colour-blind
|
||||
* reader; a one-line legend names both states. When [runState] is null the full
|
||||
* definition is shown, unchanged.
|
||||
* reader; a one-line legend names both states. An executed `success`/`error`
|
||||
* edge is drawn noticeably heavier with a stronger, same-hue stroke and a larger
|
||||
* arrowhead, so the two decisive outcomes are the loudest lines in the graph.
|
||||
* When [runState] is null the full definition is shown, with the same pass/fail
|
||||
* emphasis (every route counts as executed) and no legend.
|
||||
*
|
||||
* A tap that lands inside a node (stage or terminal) calls [onStageTap] with the
|
||||
* node key; tapping empty space does nothing. Pan/zoom keep working because the
|
||||
@@ -405,7 +408,7 @@ private fun LegendSwatch(executed: Boolean, colors: GraphColors) {
|
||||
strokeWidth = EDGE_STROKE,
|
||||
pathEffect = if (executed) null else INACTIVE_DASH_EFFECT,
|
||||
)
|
||||
if (executed) drawArrowHead(listOf(from, to), color)
|
||||
if (executed) drawArrowHead(listOf(from, to), color, ARROW_HEAD_SIZE)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1074,16 +1077,25 @@ private fun DrawScope.drawEdgePaths(
|
||||
// Executed = solid full-colour stroke plus an arrowhead; not executed =
|
||||
// dashed muted stroke with no arrowhead. The difference is carried by line
|
||||
// style and arrowhead presence, never by opacity alone, so it survives a
|
||||
// screenshot, a dim screen and a colour-blind reader.
|
||||
// screenshot, a dim screen and a colour-blind reader. An executed
|
||||
// `success`/`error` edge uses the heavier pass/fail width, a stronger
|
||||
// (same-hue) stroke and a matched arrowhead, so pass/fail dominates.
|
||||
if (edgeIsExecuted(edge.edge, runState)) {
|
||||
val color = outcomeColor(edge.edge.outcome, colors)
|
||||
drawPath(path, color = color, style = Stroke(width = EDGE_STROKE))
|
||||
drawArrowHead(points, color)
|
||||
val color = edgeStrokeColor(edge.edge, runState, colors)
|
||||
drawPath(
|
||||
path,
|
||||
color = color,
|
||||
style = Stroke(width = edgeStrokeWidth(edge.edge, runState)),
|
||||
)
|
||||
drawArrowHead(points, color, edgeArrowHeadSize(edge.edge, runState))
|
||||
} else {
|
||||
drawPath(
|
||||
path,
|
||||
color = colors.labelText,
|
||||
style = Stroke(width = EDGE_STROKE, pathEffect = INACTIVE_DASH_EFFECT),
|
||||
style = Stroke(
|
||||
width = edgeStrokeWidth(edge.edge, runState),
|
||||
pathEffect = INACTIVE_DASH_EFFECT,
|
||||
),
|
||||
)
|
||||
}
|
||||
}
|
||||
@@ -1128,17 +1140,18 @@ private fun DrawScope.drawEdgeLabels(
|
||||
}
|
||||
|
||||
/**
|
||||
* Draws an arrowhead at the tip of [points], oriented along the final segment's
|
||||
* direction (see [arrowDirection]) instead of the from-to chord, so a route that
|
||||
* turns a corner still gets an arrow pointing the way it actually travels.
|
||||
* Draws an arrowhead of length [size] at the tip of [points], oriented along the
|
||||
* final segment's direction (see [arrowDirection]) instead of the from-to chord,
|
||||
* so a route that turns a corner still gets an arrow pointing the way it
|
||||
* actually travels. [size] is passed by the caller from the matching named token
|
||||
* (see [edgeArrowHeadSize]) rather than written here.
|
||||
*/
|
||||
private fun DrawScope.drawArrowHead(points: List<Offset>, color: Color) {
|
||||
private fun DrawScope.drawArrowHead(points: List<Offset>, color: Color, size: Float) {
|
||||
if (points.size < 2) return
|
||||
val to = points.last()
|
||||
val direction = arrowDirection(points)
|
||||
if (direction.x == 0f && direction.y == 0f) return
|
||||
val angle = kotlin.math.atan2(direction.y.toDouble(), direction.x.toDouble())
|
||||
val size = 12f
|
||||
val left = Offset(
|
||||
x = to.x - size * kotlin.math.cos(angle - 0.5).toFloat(),
|
||||
y = to.y - size * kotlin.math.sin(angle - 0.5).toFloat(),
|
||||
@@ -1263,6 +1276,46 @@ internal fun stageIsExecuted(key: String, runState: RunGraphState?): Boolean =
|
||||
internal fun edgeIsExecuted(edge: GraphEdge, runState: RunGraphState?): Boolean =
|
||||
runState == null || GraphRoute(edge.source, edge.outcome, edge.target) in runState.takenRoutes
|
||||
|
||||
/**
|
||||
* True for the two decisive outcomes the graph emphasises: `success` (pass) and
|
||||
* `error` (fail). These are the protocol's terminal outcomes, the only two whose
|
||||
* stroke is widened. Pure, so drawing and the tests share one definition.
|
||||
*/
|
||||
internal fun isPassFailOutcome(outcome: String): Boolean =
|
||||
outcome == "success" || outcome == "error"
|
||||
|
||||
/** True for an executed pass/fail edge: the edges drawn heaviest. */
|
||||
internal fun isEmphasizedEdge(edge: GraphEdge, runState: RunGraphState?): Boolean =
|
||||
isPassFailOutcome(edge.outcome) && edgeIsExecuted(edge, runState)
|
||||
|
||||
/**
|
||||
* The named stroke-width token for [edge]: the heavier pass/fail width for an
|
||||
* executed `success`/`error`, the base width for any other executed outcome, and
|
||||
* the finest width for a not-executed edge. Pure, so the widths are asserted in a
|
||||
* unit test and no call site writes a stroke literal.
|
||||
*/
|
||||
internal fun edgeStrokeWidth(edge: GraphEdge, runState: RunGraphState?): Float = when {
|
||||
!edgeIsExecuted(edge, runState) -> INACTIVE_EDGE_STROKE
|
||||
isPassFailOutcome(edge.outcome) -> PASSFAIL_EDGE_STROKE
|
||||
else -> EDGE_STROKE
|
||||
}
|
||||
|
||||
/** The named arrowhead-size token for [edge], scaled to match [edgeStrokeWidth]. */
|
||||
internal fun edgeArrowHeadSize(edge: GraphEdge, runState: RunGraphState?): Float =
|
||||
if (isEmphasizedEdge(edge, runState)) PASSFAIL_ARROW_HEAD_SIZE else ARROW_HEAD_SIZE
|
||||
|
||||
/**
|
||||
* The stroke colour for an executed [edge]: its outcome colour, made more
|
||||
* saturated when pass/fail so it is stronger without changing its hue (see
|
||||
* [boostSaturation]). A not-executed edge is drawn muted elsewhere.
|
||||
*/
|
||||
internal fun edgeStrokeColor(edge: GraphEdge, runState: RunGraphState?, colors: GraphColors): Color =
|
||||
if (isEmphasizedEdge(edge, runState)) {
|
||||
boostSaturation(outcomeColor(edge.outcome, colors), PASSFAIL_SATURATION)
|
||||
} else {
|
||||
outcomeColor(edge.outcome, colors)
|
||||
}
|
||||
|
||||
/** A screen-reader description so meaning is never conveyed by colour alone. */
|
||||
private fun graphDescription(graph: Graph, runState: RunGraphState?): String {
|
||||
if (graph.stages.isEmpty()) return "Empty workflow graph"
|
||||
@@ -1290,12 +1343,38 @@ private val FIT_PADDING = 16.dp
|
||||
private val MIN_VISIBLE = 48.dp
|
||||
|
||||
/**
|
||||
* Line-style tokens shared by the graph and its legend. An executed stroke is
|
||||
* solid; a not-executed stroke is dashed with [INACTIVE_DASH_INTERVALS] on/off
|
||||
* Line-style tokens shared by the graph and its legend. Widths and the arrowhead
|
||||
* size are named here so no call site writes a stroke literal. An executed route
|
||||
* is solid; a not-executed route is dashed with [INACTIVE_DASH_INTERVALS] on/off
|
||||
* pixels, so the two states differ by shape, not by a faded tint.
|
||||
*
|
||||
* The two decisive outcomes (`success`/`error`) use the heavier
|
||||
* [PASSFAIL_EDGE_STROKE] with the matching [PASSFAIL_ARROW_HEAD_SIZE] and a
|
||||
* stronger [PASSFAIL_SATURATION] stroke, so pass/fail reads at a glance and from
|
||||
* a distance, while every other outcome keeps the finer [EDGE_STROKE] and a
|
||||
* not-executed route the finer still [INACTIVE_EDGE_STROKE].
|
||||
*/
|
||||
private const val EDGE_STROKE = 3f
|
||||
|
||||
/** Stroke width for an executed `success`/`error` edge; heavier than [EDGE_STROKE]. */
|
||||
private const val PASSFAIL_EDGE_STROKE = 7f
|
||||
|
||||
/** Stroke width for a not-executed edge; finer than either executed width. */
|
||||
private const val INACTIVE_EDGE_STROKE = 2.5f
|
||||
|
||||
/** Arrowhead length for a normal executed edge. */
|
||||
private const val ARROW_HEAD_SIZE = 12f
|
||||
|
||||
/** Arrowhead length for an executed pass/fail edge, scaled with its heavier stroke. */
|
||||
private const val PASSFAIL_ARROW_HEAD_SIZE = 20f
|
||||
|
||||
/**
|
||||
* How much more saturated an executed pass/fail stroke is than its outcome
|
||||
* colour: hue and value are preserved (see [boostSaturation]) so the meaning of
|
||||
* the colour does not change.
|
||||
*/
|
||||
private const val PASSFAIL_SATURATION = 1.6f
|
||||
|
||||
/** The dash pattern (on/off, px) for every not-executed stroke; pure data. */
|
||||
internal val INACTIVE_DASH_INTERVALS = floatArrayOf(14f, 10f)
|
||||
|
||||
|
||||
@@ -385,7 +385,7 @@ private fun RunGraphTab(
|
||||
Text("This server did not include the run graph.", style = text.meta)
|
||||
} else {
|
||||
Text(
|
||||
"Executed stages and routes are solid; not-executed ones are dashed and outlined. Pinch to zoom, drag to pan, tap a stage for details.",
|
||||
"Executed stages and routes are solid; not-executed ones are dashed and outlined. Executed success and failure routes are drawn thickest. Pinch to zoom, drag to pan, tap a stage for details.",
|
||||
style = text.meta,
|
||||
)
|
||||
WorkflowGraph(
|
||||
|
||||
@@ -1,7 +1,10 @@
|
||||
package net.awan.pipelines.ui.graph
|
||||
|
||||
import androidx.compose.ui.graphics.Color
|
||||
import net.awan.pipelines.data.protocol.GraphEdge
|
||||
import net.awan.pipelines.data.protocol.GraphRoute
|
||||
import net.awan.pipelines.data.protocol.Protocol
|
||||
import net.awan.pipelines.data.protocol.RunGraphState
|
||||
import org.junit.Assert.assertEquals
|
||||
import org.junit.Assert.assertFalse
|
||||
import org.junit.Assert.assertTrue
|
||||
@@ -98,6 +101,87 @@ class GraphPaletteTest {
|
||||
assertTrue(contrastRatio(errorRole, darkSurface) >= 4.5)
|
||||
}
|
||||
|
||||
/**
|
||||
* The emphasis helper keeps the outcome hue and value and only raises
|
||||
* saturation, so a stronger pass/fail stroke is still recognisably the same
|
||||
* success/failure colour.
|
||||
*/
|
||||
@Test
|
||||
fun boostSaturationRaisesSaturationButKeepsHueValueAndAlpha() {
|
||||
val base = successRole
|
||||
val boosted = boostSaturation(base, 1.6f)
|
||||
assertTrue(saturationOf(boosted) > saturationOf(base))
|
||||
assertEquals(hueOf(base), hueOf(boosted), 1f)
|
||||
assertEquals(valueOf(base), valueOf(boosted), 0.001f)
|
||||
assertEquals(base.alpha, boosted.alpha, 0.001f)
|
||||
// A second hue is left on its own hue, not shifted toward the first.
|
||||
val red = errorRole
|
||||
assertEquals(hueOf(red), hueOf(boostSaturation(red, 1.6f)), 1f)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun boostSaturationIsSafeAndClampedAtTheEdges() {
|
||||
val base = successRole
|
||||
// A no-op factor, and invalid factors, return the colour unchanged.
|
||||
assertEquals(base, boostSaturation(base, 1f))
|
||||
assertEquals(base, boostSaturation(base, 0f))
|
||||
assertEquals(base, boostSaturation(base, -1f))
|
||||
assertEquals(base, boostSaturation(base, Float.NaN))
|
||||
// Achromatic colours have no saturation to raise.
|
||||
assertEquals(Color.Gray, boostSaturation(Color.Gray, 2f))
|
||||
// An already fully-saturated colour clamps at 1 instead of overshooting.
|
||||
assertEquals(Color.Red, boostSaturation(Color.Red, 2f))
|
||||
}
|
||||
|
||||
/**
|
||||
* Only an executed pass/fail edge is emphasised: its stroke is the stronger
|
||||
* same-hue colour, while a non-pass/fail edge and a not-executed edge keep
|
||||
* their exact outcome colour.
|
||||
*/
|
||||
@Test
|
||||
fun onlyExecutedPassFailStrokesAreSaturatedFurther() {
|
||||
val colors = colors()
|
||||
val success = GraphEdge(1, "a", "success", Protocol.SUCCESS_END, "success")
|
||||
val blocked = GraphEdge(2, "a", "blocked", Protocol.FAILURE_END, "blocked")
|
||||
val error = GraphEdge(3, "b", "error", Protocol.FAILURE_END, "error")
|
||||
val executed = RunGraphState(
|
||||
visitedStages = setOf("a"),
|
||||
takenRoutes = setOf(GraphRoute("a", "success", Protocol.SUCCESS_END)),
|
||||
currentStage = "a",
|
||||
)
|
||||
|
||||
val baseSuccess = outcomeColor("success", colors)
|
||||
val strokeSuccess = edgeStrokeColor(success, executed, colors)
|
||||
assertEquals(hueOf(baseSuccess), hueOf(strokeSuccess), 1f)
|
||||
assertTrue(saturationOf(strokeSuccess) > saturationOf(baseSuccess))
|
||||
|
||||
// A non-pass/fail edge and a not-executed pass/fail edge are untouched.
|
||||
assertEquals(outcomeColor("blocked", colors), edgeStrokeColor(blocked, executed, colors))
|
||||
assertEquals(outcomeColor("error", colors), edgeStrokeColor(error, executed, colors))
|
||||
}
|
||||
|
||||
/** Hue in degrees, matching the conversion [boostSaturation] uses. */
|
||||
private fun hueOf(color: Color): Float {
|
||||
val max = maxOf(color.red, color.green, color.blue)
|
||||
val min = minOf(color.red, color.green, color.blue)
|
||||
val delta = max - min
|
||||
if (delta == 0f) return 0f
|
||||
val h = when (max) {
|
||||
color.red -> ((color.green - color.blue) / delta + 6f) % 6f
|
||||
color.green -> (color.blue - color.red) / delta + 2f
|
||||
else -> (color.red - color.green) / delta + 4f
|
||||
}
|
||||
return h * 60f
|
||||
}
|
||||
|
||||
private fun saturationOf(color: Color): Float {
|
||||
val max = maxOf(color.red, color.green, color.blue)
|
||||
val min = minOf(color.red, color.green, color.blue)
|
||||
return if (max <= 0f) 0f else (max - min) / max
|
||||
}
|
||||
|
||||
private fun valueOf(color: Color): Float = maxOf(color.red, color.green, color.blue)
|
||||
|
||||
@Test
|
||||
fun nodeKindIsDeterministicAndCoversEveryKind() {
|
||||
assertEquals(GraphNodeKind.Model, graphNodeKind(false, "planner", null))
|
||||
|
||||
@@ -518,6 +518,56 @@ class WorkflowGraphTest {
|
||||
assertFalse(edgeIsExecuted(notTaken, runState))
|
||||
}
|
||||
|
||||
/**
|
||||
* The emphasis contract: an executed `success`/`error` edge uses the widest
|
||||
* named stroke token, every other executed outcome a finer one and a
|
||||
* not-executed edge the finest, with the arrowhead scaled to match. The
|
||||
* definition-only view applies the same pass/fail emphasis.
|
||||
*/
|
||||
@Test
|
||||
fun executedPassFailEdgesAreTheWidest() {
|
||||
val graph = sampleGraph()
|
||||
val success = graph.edges().first { it.outcome == "success" }
|
||||
val error = graph.edges().first { it.outcome == "error" }
|
||||
val other = graph.edges().first { it.outcome == "blocked" }
|
||||
val untaken = graph.edges().first { it.outcome == "rejected" }
|
||||
val runState = RunGraphState(
|
||||
visitedStages = setOf("planner", "implementer", "reviewer"),
|
||||
takenRoutes = setOf(
|
||||
GraphRoute(success.source, success.outcome, success.target),
|
||||
GraphRoute(error.source, error.outcome, error.target),
|
||||
GraphRoute(other.source, other.outcome, other.target),
|
||||
),
|
||||
currentStage = "reviewer",
|
||||
)
|
||||
|
||||
val passFailWidth = edgeStrokeWidth(success, runState)
|
||||
assertEquals(passFailWidth, edgeStrokeWidth(error, runState), 0.001f)
|
||||
assertTrue(edgeStrokeWidth(other, runState) < passFailWidth)
|
||||
assertTrue(edgeStrokeWidth(untaken, runState) < edgeStrokeWidth(other, runState))
|
||||
assertTrue(edgeStrokeWidth(untaken, runState) > 0f)
|
||||
|
||||
// The arrowhead scales with the heavier stroke.
|
||||
assertEquals(edgeArrowHeadSize(success, runState), edgeArrowHeadSize(error, runState), 0.001f)
|
||||
assertTrue(edgeArrowHeadSize(success, runState) > edgeArrowHeadSize(other, runState))
|
||||
|
||||
// The definition-only view emphasises the same pass/fail edges.
|
||||
assertEquals(passFailWidth, edgeStrokeWidth(success, null), 0.001f)
|
||||
assertTrue(isEmphasizedEdge(success, runState))
|
||||
assertFalse(isEmphasizedEdge(other, runState))
|
||||
assertFalse(isEmphasizedEdge(untaken, runState))
|
||||
}
|
||||
|
||||
/** Only `success` and `error` are the decisive, emphasised outcomes. */
|
||||
@Test
|
||||
fun onlySuccessAndErrorArePassFailOutcomes() {
|
||||
assertTrue(isPassFailOutcome("success"))
|
||||
assertTrue(isPassFailOutcome("error"))
|
||||
for (outcome in listOf("blocked", "rejected", "skipped", "exhausted", "approved", "done", "")) {
|
||||
assertFalse(outcome, isPassFailOutcome(outcome))
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The not-executed dash pattern is a real on/off rhythm, not a faded tint: a
|
||||
* positive, even-length interval list so a dashed stroke reads differently
|
||||
|
||||
Reference in New Issue
Block a user