jirametrics 3.4 → 3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f7292394330330ca10f89a28f02fab3e95cff385736c423ca3602c23551e4ca
-  data.tar.gz: 4690b5ce8cc47d3e980ee026e68f6f245e564ec51aa914914dd7a0db32f3c0b2
+  metadata.gz: 056e9e0149e1e7f1d03968b91d5a62937d82a5f529ceba4917b6b23c74f33103
+  data.tar.gz: e883680589519bb9c527873d607755dbca2d4082053a5747a9bd7de2506305f4
 SHA512:
-  metadata.gz: 6f32fbe86ecfb9ecc5ce7ace7d0a2971b6777c7a61e4513d41d2444a976699487ba4da415b6e84484cad72a45ee6af4a822f14da430018e6b40b39bb48046a70
-  data.tar.gz: 2b4af2fe6c95834710901e3aacccc1d260ceb7c28020a853f1a643be1faf3c48a0663488839c522249e2a14a2d3c6e4665425a3c7bf5175354a0311493679ee6
+  metadata.gz: bd257eb627a31909dcb389ec7d66739d9d5d3aebf6d8301af76c41c4f989ebce899ca8fa543d2557dfd3a4ffd4af0110eb3f8bea7872bdf6ae4931fb15b6fc13
+  data.tar.gz: be1fee3d08642e25db8a998803921ef385cef5dd5cef99b074808553c7619c6af7069833df5fce644a95976ef7e7ffc4ca1cb9ccc0047b066ce8e85900a7ca85

data/lib/jirametrics/chart_base.rb

@@ -198,12 +198,24 @@ class ChartBase
 
   LABEL_POSITIONS = %w[5% 25% 45% 65%].freeze
 
-  def date_annotation
-    annotations = settings['date_annotations'] || []
-    in_range = annotations
-      .map { |a| [a, normalize_annotation_datetime(a['date'])] }
-      .select { |(_, dt)| date_range.cover?(Date.parse(dt)) }
-      .sort_by { |(_, dt)| dt }
+  # chartjs-plugin-annotation renders each array element as its own line and does no wrapping of
+  # its own, so anything long has to arrive already split.
+  ANNOTATION_DESCRIPTION_WIDTH = 60
+
+  # The descriptions a chart needs to draw its own hover reveal, with the dates already normalized
+  # and the text already wrapped, so the JavaScript only has to decide when to show them.
+  def date_annotation_hover_data
+    annotations_in_range
+      .select { |(a, _)| a['description'] }
+      .map { |(a, normalized)| { 'date' => normalized, 'lines' => wrap_annotation_description(a['description']) } }
+      .to_json
+  end
+
+  # hover: false leaves out the reveal callbacks and the widened hit target, for a chart that
+  # draws its own hover reveal. The CFD does, because its flow metrics triangle switches Chart.js
+  # events off and the plugin's hover cannot fire while that is on.
+  def date_annotation hover: true
+    in_range = annotations_in_range
 
     positions = stagger_label_positions(in_range.map { |(_, dt)| dt })
 
@@ -214,17 +226,94 @@ class ChartBase
           xMin: #{normalized.to_json},
           xMax: #{normalized.to_json},
           borderColor: 'rgba(0,0,0,0.7)',
-          borderWidth: 1,
-          label: {
-            display: true,
-            content: #{a['label'].to_json},
-            position: #{positions[index].to_json}
-          }
+          borderWidth: 1#{annotation_hit_tolerance(a) if hover}#{annotation_label a, positions[index]}#{annotation_hover_callbacks(a, index) if hover}
         },
       TEXT
     end.join
   end
 
+  def annotations_in_range
+    (settings['date_annotations'] || [])
+      .map { |a| [a, normalize_annotation_datetime(a['date'])] }
+      .select { |(_, dt)| date_range.cover?(Date.parse(dt)) }
+      .sort_by { |(_, dt)| dt }
+  end
+
+  # The label block for one annotation, or nothing at all when there is neither a label nor a
+  # description to put in it.
+  def annotation_label annotation, position
+    # drawTime: the CFD hatches its correction windows over the chart and the scatterplot draws
+    # dots and percentile lines. Drawing the label last keeps it readable on both.
+
+    label = annotation['label']
+    description = annotation['description']
+    return '' if label.nil? && description.nil?
+
+    ",\n" \
+      "  label: {\n" \
+      "    display: #{!label.nil?},\n" \
+      "    content: #{annotation_content(annotation).to_json},\n" \
+      "    position: #{position.to_json},\n" \
+      "    drawTime: 'afterDraw'\n" \
+      '  }'
+  end
+
+  # A label on its own stays a plain string, exactly as it always was. Paired with a description it
+  # becomes a single element array so that hovering can append the description lines below it. With
+  # no label at all the description is the whole content, hidden until the line is hovered.
+  def annotation_content annotation
+    label = annotation['label']
+    return wrap_annotation_description annotation['description'] if label.nil?
+
+    annotation['description'] ? [label] : label
+  end
+
+  # The line is a single pixel wide, so without widening the hit target there is nothing the
+  # mouse can realistically land on. Only annotations that react to hovering need it.
+  def annotation_hit_tolerance annotation
+    annotation['description'] ? ",\n  hitTolerance: 6" : ''
+  end
+
+  def wrap_annotation_description description
+    description.split.each_with_object([]) do |word, lines|
+      if lines.empty? || "#{lines.last} #{word}".length > ANNOTATION_DESCRIPTION_WIDTH
+        lines << word
+      else
+        lines[-1] = "#{lines.last} #{word}"
+      end
+    end
+  end
+
+  # Two things here are easy to get wrong, and both were, so they are worth spelling out.
+  #
+  # update('none') rather than draw(): the label's box is measured during the update, so a plain
+  # redraw paints the new lines at the old box size and they spill across the chart as white text
+  # on nothing. 'none' skips the animation.
+  #
+  # Writing to the chart config rather than to ctx.element: update() re-resolves every annotation
+  # from the config, so anything written to the element is discarded before it can be drawn. The
+  # percentile lines elsewhere can write to the element because they call draw(), not update().
+  def annotation_hover_callbacks annotation, index
+    description = annotation['description']
+    return '' unless description
+    return annotation_reveal_callbacks if annotation['label'].nil?
+
+    expanded = [annotation['label'], *wrap_annotation_description(description)]
+    target = "ctx.chart.options.plugins.annotation.annotations.dateAnnotation#{index}.label.content"
+    ",\n" \
+      "  enter(ctx) { #{target} = #{expanded.to_json}; ctx.chart.update('none'); },\n" \
+      "  leave(ctx) { #{target} = #{annotation_content(annotation).to_json}; ctx.chart.update('none'); }"
+  end
+
+  # With no label there is nothing on screen at rest, so hovering only has to switch the hidden
+  # label on. The content never changes, so its box is already measured and draw() is enough.
+  # That avoids the update() dance the case above needs, and the element can be written directly.
+  def annotation_reveal_callbacks
+    ",\n" \
+      '  enter(ctx) { ctx.element.label.options.display = true; ctx.chart.draw(); },' \
+      "\n  leave(ctx) { ctx.element.label.options.display = false; ctx.chart.draw(); }"
+  end
+
   def stagger_label_positions datetimes
     return [] if datetimes.empty?
 

data/lib/jirametrics/html/cumulative_flow_diagram.erb

@@ -14,6 +14,8 @@ if (!Chart.Tooltip.positioners.legendItem) {
 }
 (function() {
   const hatchWindows = <%= hatch_windows.to_json %>;
+  const annotationDescriptions = <%= date_annotation_hover_data %>;
+  const ANNOTATION_HOVER_TOLERANCE = 6;
 
   // Custom plugin: draws diagonal hatching over correction windows in the affected band.
   // Uses createDiagonalPattern() defined in index.js.
@@ -23,7 +25,7 @@ if (!Chart.Tooltip.positioners.legendItem) {
       // Redraw each correction-window border line so that the gaps between
       // dashes show the band fill colour rather than being transparent.
       // Strategy: draw a solid line in the fill colour first, then the dashed
-      // border line on top. afterDraw (hatching) fires after this, so the
+      // border line on top. The hatching runs straight after this, so the
       // hatch pattern still appears over both lines.
       const ctx = chart.ctx;
       const ca  = chart.chartArea;
@@ -55,8 +57,15 @@ if (!Chart.Tooltip.positioners.legendItem) {
         drawSegment(win.fill_color, []);      // solid fill colour fills the gaps
         drawSegment(win.color,      [6, 4]);  // dashed border colour on top
       });
+
+      // The hatching used to run in afterDraw, which put it above the annotation labels no
+      // matter what drawTime those asked for. Running it here, immediately after the borders,
+      // lets a label drawn at afterDraw land on top of it. The trend lines still draw over the
+      // hatching, since cfdFlowMetricsPlugin.afterDraw runs later than this either way.
+      cfdHatchPlugin.drawHatching(chart);
     },
-    afterDraw: function(chart) {
+    // Not a Chart.js hook. Called explicitly from afterDatasetsDraw above.
+    drawHatching: function(chart) {
       const ctx = chart.ctx;
       const ca  = chart.chartArea;
       hatchWindows.forEach(function(win) {
@@ -203,6 +212,44 @@ if (!Chart.Tooltip.positioners.legendItem) {
       ctx.restore();
     }
 
+    // The description box for whichever annotation the cursor is near. This lives on the overlay
+    // rather than going through chartjs-plugin-annotation's own enter/leave, because those need
+    // Chart.js events and triangle mode switches those off.
+    function drawAnnotationDescription(ctx, chart, fm) {
+      const lines = fm._hoveredAnnotation.lines;
+      if (!lines.length) return;
+
+      const ca = chart.chartArea;
+      ctx.save();
+      ctx.font = '11px sans-serif';
+      const pad = 6, lineHeight = 14;
+      const w = Math.max.apply(null, lines.map(function (l) { return ctx.measureText(l).width; })) + pad * 2;
+      const h = lines.length * lineHeight + pad * 2;
+      // Sit below and right of the cursor, flipping when that would cross the edge of the plot.
+      let x = fm.mouseX + 12;
+      let y = fm.mouseY + 12;
+      if (x + w > ca.right)  x = fm.mouseX - 12 - w;
+      if (y + h > ca.bottom) y = fm.mouseY - 12 - h;
+      ctx.fillStyle = 'rgba(0,0,0,0.85)';
+      ctx.fillRect(x, y, w, h);
+      ctx.fillStyle = '#ffffff';
+      ctx.textAlign = 'left';
+      ctx.textBaseline = 'top';
+      lines.forEach(function (line, i) { ctx.fillText(line, x + pad, y + pad + i * lineHeight); });
+      ctx.restore();
+    }
+
+    function annotationNear(chart, x) {
+      if (x === null) return null;
+
+      let best = null, bestDistance = ANNOTATION_HOVER_TOLERANCE;
+      annotationDescriptions.forEach(function (a) {
+        const distance = Math.abs(chart.scales.x.getPixelForValue(new Date(a.date).getTime()) - x);
+        if (distance <= bestDistance) { bestDistance = distance; best = a; }
+      });
+      return best;
+    }
+
     function drawTriangle(ctx, chart, fm) {
       const ca    = chart.chartArea;
       const ds    = chart.data.datasets;
@@ -312,6 +359,8 @@ if (!Chart.Tooltip.positioners.legendItem) {
         const dates = chart.data.datasets[0].data.map(d => new Date(d.x).getTime());
         chart._flowMetrics = {
           mouseX:      null,
+          mouseY:      null,
+          _hoveredAnnotation: null,
           arrivals,
           departures,
           dates,
@@ -323,9 +372,9 @@ if (!Chart.Tooltip.positioners.legendItem) {
 
         // The triangle is drawn on a separate overlay canvas using native DOM
         // events, completely bypassing Chart.js's render/event cycle (which
-        // behaves unreliably in Safari). The triangle is hidden immediately on
-        // mouse move and redrawn after a short pause (debounce), preventing the
-        // browser from being overwhelmed by rapid redraws.
+        // behaves unreliably in Safari). Redraws are coalesced into a single
+        // requestAnimationFrame (see scheduleOverlayRedraw) so a fast mouse move
+        // cannot queue up more redraws than the browser can paint.
         const dpr     = window.devicePixelRatio || 1;
         const parent = canvas.parentNode;
         if (getComputedStyle(parent).position === 'static') parent.style.position = 'relative';
@@ -359,6 +408,12 @@ if (!Chart.Tooltip.positioners.legendItem) {
         // disabled entirely so its internal hover/tooltip logic cannot interfere
         // with the overlay canvas rAF (which hangs Safari at certain positions).
         // Our native canvas mousemove handler is unaffected by this setting.
+        //
+        // Switching events off wholesale looks heavy handed, and it is. We never found
+        // the root cause of the Safari hang. Other fixes we tried worked in some
+        // browsers but not all; this is the only one that was reliable across Safari,
+        // Chrome, Edge and Firefox. Treat it as load bearing: anything that re-enables
+        // events here has to be retested in all four.
         const defaultEvents = ['mousemove', 'mouseout', 'click', 'touchstart', 'touchmove'];
 
         function setTriangleMode(enabled) {
@@ -386,10 +441,9 @@ if (!Chart.Tooltip.positioners.legendItem) {
           if (fm._rafId !== null) return;
           fm._rafId = requestAnimationFrame(function () {
             fm._rafId = null;
-            if (fm._triangleEnabled) {
-              octx.clearRect(0, 0, cssW, cssH);
-              if (fm.mouseX !== null) drawTriangle(octx, chart, fm);
-            }
+            octx.clearRect(0, 0, cssW, cssH);
+            if (fm._triangleEnabled && fm.mouseX !== null) drawTriangle(octx, chart, fm);
+            if (fm._hoveredAnnotation) drawAnnotationDescription(octx, chart, fm);
           });
         }
 
@@ -399,12 +453,17 @@ if (!Chart.Tooltip.positioners.legendItem) {
           const y = e.clientY - rect.top;
           const ca = chart.chartArea;
           if (!ca) return;
-          fm.mouseX = (x >= ca.left && x <= ca.right && y >= ca.top && y <= ca.bottom) ? x : null;
+          const inside = x >= ca.left && x <= ca.right && y >= ca.top && y <= ca.bottom;
+          fm.mouseX = inside ? x : null;
+          fm.mouseY = inside ? y : null;
+          fm._hoveredAnnotation = annotationNear(chart, fm.mouseX);
           scheduleOverlayRedraw();
         }
 
         function onMouseLeave() {
           fm.mouseX = null;
+          fm.mouseY = null;
+          fm._hoveredAnnotation = null;
           scheduleOverlayRedraw();
         }
 
@@ -458,6 +517,15 @@ if (!Chart.Tooltip.positioners.legendItem) {
         point: { radius: 0 }
       },
       plugins: {
+        // The plugin draws the lines and their static labels. It does NOT get the hover callbacks,
+        // because triangle mode switches Chart.js events off and they would fire only when the
+        // triangle was hidden. The overlay canvas reveals descriptions instead, from the native
+        // mousemove handler, so it behaves the same in both modes.
+        annotation: {
+          annotations: {
+            <%= date_annotation hover: false %>
+          }
+        },
         tooltip: {
           enabled: false,
           position: 'legendItem',

data/lib/jirametrics/project_config.rb

@@ -44,6 +44,7 @@ class ProjectConfig
     load_fix_versions
     load_users
     resolve_blocked_stalled_status_settings
+    report_unusable_date_annotations
   end
 
   def run load_only: false
@@ -79,6 +80,29 @@ class ProjectConfig
   # passed through but that no longer exists in Jira). It fires often -- any workflow rework leaves
   # these behind -- so we say the explanation once and hand over a single ready-to-paste block of
   # mappings rather than one repetitive paragraph per status.
+  # Print one consolidated warning covering every date annotation that has neither a label nor a
+  # description. Such an annotation draws a bare line with nothing to say what it marks, which is
+  # almost always a typo in the config rather than a choice. One warning per project, because the
+  # same settings hash is usually shared across several projects and every chart re-reads it.
+  def report_unusable_date_annotations
+    return if @unusable_date_annotations_reported
+
+    @unusable_date_annotations_reported = true
+
+    unusable = (settings['date_annotations'] || []).reject do |annotation|
+      annotation['label'] || annotation['description']
+    end
+    return if unusable.empty?
+
+    dates = unusable.map { |annotation| annotation['date'].inspect }.join(', ')
+    file_system.warning(
+      "These date annotations have neither a label nor a description: #{dates}. Each will draw " \
+      'a bare line with nothing to say what it marks, which is almost certainly a mistake. Give ' \
+      'each one a label, a description, or both. If a bare line really is what you wanted, they ' \
+      'will work as they are.'
+    )
+  end
+
   def report_fabricated_statuses
     statuses = possible_statuses.fabricated_statuses
     return if statuses.empty? || @fabricated_statuses_reported

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: '3.4'
+  version: '3.5'
 platform: ruby
 authors:
 - Mike Bowler