jirametrics 3.3 → 3.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25832ca03b7dcdc188d741171ee47d3f463551d1893257e39a9b52c0fb45dd83
-  data.tar.gz: a4d1b9ce7039e568e8c1a614862688887bc4e188c3b24af646922983eb859b9f
+  metadata.gz: 6a2003eb5e447333b282b856e553c7f3f68792da373ce3b563c7f9e4e56dec45
+  data.tar.gz: 50b443fbcad6fe9dff8b247a7e0662cfed8c41724bb1e8dbd5d17c33a58ff416
 SHA512:
-  metadata.gz: cdbfed22a95da07665930c339330d1f6def0f3ce36118fa68fd249295bbb7386d1a85bd0fe4301de8c5fc35d94e1a98bdee22f81daf9fc59db8095ea02000cec
-  data.tar.gz: 9122e7aa6cfb881723e7acc7b20df65a12ba372ab0736e94fe2e92e6e5206f69c342b94242e5f7e67d43135a426dab7c82b01d8e57fd5f33ee2a2227b0302445
+  metadata.gz: bdaa2c39f21752d0a1a815dc39dd10235cea508f873d89a32d722ea5db4d0d59eef1738febdffde062eaa31cb9b8c24598e2e0b96ccce478a296fe255c0b7997
+  data.tar.gz: 8a9013ed9d3bd5ebef3d2a70c1b870ec5624125d0f2fb5989d375e4d005b7259646d66b24d9babcf49d794671dbc65505770b16c5438624406e4dd21e182b98a

data/lib/jirametrics/dependency_chart.rb

@@ -32,9 +32,40 @@ class DependencyChart < ChartBase
     attr_accessor :color, :label
   end
 
+  # A fill and the label colour that goes on top of it, kept together because they are not
+  # independent choices: some of these fills are light and take black text, others are dark and
+  # take white, and a node that took its fill from one and its label from another would be
+  # unreadable. Always hand them out as a pair.
+  Palette = Struct.new :fill, :label
+
+  def self.palette_entry name
+    Palette.new CssVariable["--dependency-chart-#{name}-color"],
+      CssVariable["--dependency-chart-#{name}-label-color"]
+  end
+
+  PALETTE = {
+    story: palette_entry('story'),
+    task: palette_entry('task'),
+    bug: palette_entry('bug'),
+    epic: palette_entry('epic'),
+    spike: palette_entry('spike')
+  }.freeze
+
   def initialize rules_block
     super()
 
+    # Not the inherited type colours, because these are fills with label text sitting on top of
+    # them and those are line colours, judged against the page rather than against the text. See
+    # index.css for which colours these are and why.
+    @palette_by_type = {
+      'Story' => PALETTE[:story],
+      'Task' => PALETTE[:task],
+      'Bug' => PALETTE[:bug],
+      'Defect' => PALETTE[:bug],
+      'Epic' => PALETTE[:epic],
+      'Spike' => PALETTE[:spike]
+    }
+
     header_text 'Dependencies'
     description_text <<-HTML
       <p>
@@ -57,7 +88,7 @@ class DependencyChart < ChartBase
         '<div>No data matched the selected criteria. Nothing to show.</div>'
     end
 
-    svg = execute_graphviz(dot_graph.join("\n"))
+    svg = restore_css_variables execute_graphviz(dot_graph.join("\n"))
     "<h1 class='foldable'>#{@header_text}</h1><div>#{@description_text}#{shrink_svg svg}</div>"
   end
 
@@ -77,6 +108,42 @@ class DependencyChart < ChartBase
     result
   end
 
+  # Graphviz has never heard of CSS variables. Handed one it emits a warning nobody sees and
+  # falls back to black, which is how a node ends up as black text on a black background. So a
+  # variable is swapped for a placeholder colour here and mapped back to the variable in the
+  # generated SVG, by #restore_css_variables. Anything that isn't a variable is left alone.
+  #
+  # The placeholders only need to be colours that nobody would ever choose deliberately, so that
+  # the CSS selectors matching them in the SVG cannot hit anything else.
+  def graphviz_color color
+    return color unless color.is_a? CssVariable
+
+    css_variable_placeholders[color.name] ||= format '#fe00%02x', css_variable_placeholders.size + 1
+  end
+
+  def css_variable_placeholders
+    @css_variable_placeholders ||= {}
+  end
+
+  # Turns the placeholders from #graphviz_color back into the variables they stood for, by way of
+  # a stylesheet that selects on the placeholder value. Rewriting the attributes in place would be
+  # the obvious move, but var() is only legal in a CSS value and not in an SVG presentation
+  # attribute, so the colour has to arrive as a real CSS rule. Author rules beat presentation
+  # attributes, so the placeholder never wins.
+  #
+  # fillcolor and fontcolor come out of graphviz as fill and color comes out as stroke, and an
+  # arrowhead uses both, so every placeholder gets a rule for each.
+  def restore_css_variables svg
+    return svg if css_variable_placeholders.empty?
+
+    rules = css_variable_placeholders.map do |name, placeholder|
+      %([fill="#{placeholder}"]{fill:var(#{name})}[stroke="#{placeholder}"]{stroke:var(#{name})})
+    end
+    svg.sub(/(?<opening_tag><svg\b[^>]*>)/) do
+      "#{Regexp.last_match[:opening_tag]}<style>#{rules.join}</style>"
+    end
+  end
+
   def make_dot_link issue_link:, link_rules:
     result = +''
     result << issue_link.origin.key.inspect
@@ -84,8 +151,9 @@ class DependencyChart < ChartBase
     result << issue_link.other_issue.key.inspect
     result << '['
     result << 'label=' << (link_rules.label || issue_link.label).inspect
-    result << ',color=' << (link_rules.line_color || 'gray').inspect
-    result << ',fontcolor=' << (link_rules.line_color || 'gray').inspect
+    line_color = graphviz_color(link_rules.line_color || default_link_color)
+    result << ',color=' << line_color.inspect
+    result << ',fontcolor=' << line_color.inspect
     result << ',dir=both' if link_rules.bidirectional_arrows?
     result << '];'
     result
@@ -102,24 +170,47 @@ class DependencyChart < ChartBase
     tooltip = "#{issue.key}: #{issue.summary}"
     result << ",tooltip=#{tooltip[0..80].inspect}"
     unless issue_rules.color == :none
-      result << %(,style=filled,fillcolor="#{issue_rules.color || color_for(type: issue.type)}")
+      fill_color = graphviz_color(issue_rules.color || color_for(type: issue.type))
+      result << %(,style=filled,fillcolor="#{fill_color}")
     end
+    result << %(,fontcolor="#{graphviz_color label_color(issue: issue, issue_rules: issue_rules)}")
     result << ']'
     result
   end
 
-  # This used to pull colours from chart_base but the migration to CSS colours kept breaking
-  # this chart so we moved it here, until we're finished with the rest. TODO: Revisit whether
-  # this can also use customizable CSS colours
+  # A filled node is its own background, so its label is measured against the fill rather than
+  # against the page.
+  def label_color issue:, issue_rules:
+    return CssVariable['--default-text-color'] if issue_rules.color == :none
+
+    # A colour somebody configured is one we know nothing about, so guessing that a particular
+    # type's label would suit it is worse than falling back to the general one.
+    return CssVariable['--dependency-chart-label-color'] if issue_rules.color
+
+    palette_for(issue.type).label
+  end
+
   def color_for type:
-    @chart_colors = {
-      'Story' => '#90EE90',
-      'Task' => '#87CEFA',
-      'Bug' => '#ffdab9',
-      'Defect' => '#ffdab9',
-      'Epic' => '#fafad2',
-      'Spike' => '#DDA0DD' # light purple
-    }[type] ||= next_palette_color
+    palette_for(type).fill
+  end
+
+  def palette_for type
+    @palette_by_type[type] ||= next_palette_entry
+  end
+
+  def default_link_color
+    CssVariable['--dependency-chart-link-color']
+  end
+
+  # An issue type we have no colour for cannot come from the shared palette, the way it does on
+  # every other chart. That palette holds line colours, judged against the page, and its first slot
+  # is Okabe-Ito blue, which leaves black label text at 4.05:1 once it becomes the fill behind it.
+  # These rotate this chart's own entries, which are all known to be comfortable. Two unknown types
+  # can therefore land on the same colour as each other or as a known type, which costs little:
+  # every node already names its type in the label.
+  def next_palette_entry
+    @fallback_color_index = (@fallback_color_index || -1) + 1
+    PALETTE.values[@fallback_color_index % PALETTE.size]
   end
 
   def build_dot_graph

data/lib/jirametrics/html/index.css

@@ -33,6 +33,41 @@
   --type-bug-color: #D55E00;         /* Okabe-Ito vermilion */
   --type-spike-color: #CC79A7;       /* Okabe-Ito reddish purple */
 
+  /* The dependency chart is drawn by graphviz, which sets the label text inside the node rather
+     than beside it, so unlike --type-*-color above these are judged against the text and not
+     against the page. They are opaque, so the fill is the background the text sits on and there
+     is nothing for a dark theme to override.
+
+     These are Okabe-Ito hues rather than Okabe-Ito itself. At full strength they sit in a middle
+     band of lightness where NEITHER black nor white text is comfortable on them, which is the
+     thing to understand before changing any of this. Contrast ratio alone will mislead you here:
+     two earlier attempts cleared 7:1 and then 9:1, both of which WCAG calls comfortable, and both
+     still read as muddy in a real report. A mid-toned fill with dark text on it looks wrong at
+     almost any ratio. Going DARK and putting white text on it is what actually reads, so most of
+     these fills are dark, and each carries its own label colour: they are a pair, and changing a
+     fill without rechecking its label is how you get unreadable nodes.
+
+     They are not all dark, because the lightness spread is what does most of the work of keeping
+     them apart. Levelling them all to the same darkness measures about 3, which is unusable;
+     pastelling them all measures about 4.7, which is what the original colours here did. Run
+     `rake check_colors` for what they currently measure, against the full Okabe-Ito set as a
+     reference ceiling. */
+  --dependency-chart-story-color: #015C41;         /* Okabe-Ito bluish green, darkened */
+  --dependency-chart-story-label-color: white;
+  --dependency-chart-task-color: #56B4E9;          /* Okabe-Ito sky blue, unchanged */
+  --dependency-chart-task-label-color: black;
+  --dependency-chart-bug-color: #783200;           /* Okabe-Ito vermilion, darkened. Also Defect */
+  --dependency-chart-bug-label-color: white;
+  --dependency-chart-epic-color: #F0E442;          /* Okabe-Ito yellow, unchanged */
+  --dependency-chart-epic-label-color: black;
+  --dependency-chart-spike-color: #762A58;         /* Okabe-Ito reddish purple, darkened */
+  --dependency-chart-spike-label-color: white;
+
+  /* For a node whose fill was set in the config rather than coming from the palette above, where
+     we cannot know what would read on it. */
+  --dependency-chart-label-color: black;
+  --dependency-chart-link-color: gray;
+
   --status-category-todo-color: gray;
   --status-category-inprogress-color: #0072B2;  /* Okabe-Ito blue */
   --status-category-done-color: #009E73;         /* Okabe-Ito bluish green */
@@ -248,6 +283,10 @@ div.child_issue {
 html[data-theme="dark"] {
   --warning-banner: #9F2B00;
   --non-working-days-color: #2f2f2f;
+
+  /* See the matching comment in the prefers-color-scheme block below. */
+  --dependency-chart-link-color: #999999;
+
   --type-story-color: #2DCB9A;       /* lighter bluish green for dark bg */
   --type-task-color: #56B4E9;        /* sky blue for dark bg */
   --type-bug-color: #E69F00;         /* orange instead of vermilion for dark bg */
@@ -400,6 +439,12 @@ html[data-theme="light"] {
     --warning-banner: #9F2B00;
 
     --non-working-days-color: #2f2f2f;
+
+    /* The only dependency chart colour needing a dark variant. The fills do not, because they
+       are opaque and are their own background, but link lines and their labels sit on the page.
+       Plain gray manages only 2.4:1 here against 3.94:1 in light mode, so it is lifted to match. */
+    --dependency-chart-link-color: #999999;
+
     --type-story-color: #2DCB9A;       /* lighter bluish green for dark bg */
     --type-task-color: #56B4E9;        /* sky blue for dark bg */
     --type-bug-color: #E69F00;         /* orange instead of vermilion for dark bg */

data/lib/jirametrics/html/legacy_colors.css

@@ -30,6 +30,22 @@ html[data-theme="light"] {
   --type-bug-color: orange;
   --type-spike-color: #9400D3;
 
+  /* The dependency chart's original pastels. They are pleasant but they are not safe: pale
+     colours sit close together, and green, peach and pale yellow are hard to separate for anyone
+     with red-green colour vision deficiency. Every one of them is light, so the label colours all
+     go back to black; the shipped set has dark fills that need white. */
+  --dependency-chart-story-color: #90EE90;
+  --dependency-chart-story-label-color: black;
+  --dependency-chart-task-color: #87CEFA;
+  --dependency-chart-task-label-color: black;
+  --dependency-chart-bug-color: #ffdab9;
+  --dependency-chart-bug-label-color: black;
+  --dependency-chart-epic-color: #fafad2;
+  --dependency-chart-epic-label-color: black;
+  --dependency-chart-spike-color: #DDA0DD;
+  --dependency-chart-spike-label-color: black;
+  --dependency-chart-link-color: gray;
+
   --status-category-todo-color: gray;
   --status-category-inprogress-color: #2663ff;
   --status-category-done-color: #00ff00;
@@ -106,6 +122,7 @@ html[data-theme="light"] {
 html[data-theme="dark"] {
   --warning-banner: #9F2B00;
   --non-working-days-color: #2f2f2f;
+  --dependency-chart-link-color: gray;   /* the chart had no dark variant originally */
   --type-story-color: #6fb86f;
   --type-task-color: #0021b3;
   --type-bug-color: #bb5603;
@@ -139,6 +156,7 @@ html[data-theme="dark"] {
   :root {
     --warning-banner: #9F2B00;
     --non-working-days-color: #2f2f2f;
+    --dependency-chart-link-color: gray;   /* the chart had no dark variant originally */
     --type-story-color: #6fb86f;
     --type-task-color: #0021b3;
     --type-bug-color: #bb5603;

data/lib/jirametrics/html/time_based_histogram.erb

@@ -100,16 +100,20 @@ if show_stats
       <% the_stats.each do |k, v| %>
           <tr>
             <td><%= k %></td>
-            <td style="text-align: right;"><%= v[:min] %></td>
-            <td style="text-align: right;"><%= v[:max] %></td>
-            <td style="text-align: right;"><%= sprintf('%.2f', v[:average]) %></td>
-            <td><%= v[:mode].join(', ') %></td>
+            <td style="text-align: right;"><%= stats_cell v[:min] %></td>
+            <td style="text-align: right;"><%= stats_cell v[:max] %></td>
+            <td style="text-align: right;"><%= stats_cell(v[:average]) { |average| format '%.2f', average } %></td>
+            <td><%= stats_cell(v[:mode]) { |modes| modes.join ', ' } %></td>
             <% percentiles.each do |percentile| %>
-               <td style="text-align: right;"><%= v[:percentiles][percentile] %></td>
+               <td style="text-align: right;"><%= stats_cell v.dig(:percentiles, percentile) %></td>
             <% end %>
           </tr>
        <% end %>
      </table>
+     <% if any_empty_stats? the_stats %>
+       <p><b>&ndash;</b> means no usable data for that group. Every item in it was excluded from the histogram
+       because it had no measurable cycle time. The Data Quality report has the details.</p>
+     <% end %>
   </div>
   <div>
     <p>These statistics help understand the <i>"shape"</i> of the histogram distribution, to help us with predictions.</p>

data/lib/jirametrics/time_based_histogram.rb

@@ -94,6 +94,20 @@ class TimeBasedHistogram < TimeBasedChart
     items_hash
   end
 
+  # One cell of the statistics table. A group can survive grouping and still have nothing to plot,
+  # when every item in it was excluded for having no measurable cycle time, and then there are no
+  # statistics to show for it at all. Dashing the cells keeps the group visible: dropping the row
+  # would make it look like the group had never existed.
+  def stats_cell value
+    return '&ndash;' if value.nil?
+
+    block_given? ? yield(value) : value
+  end
+
+  def any_empty_stats? the_stats
+    the_stats.any? { |_label, stats| stats.empty? }
+  end
+
   def stats_for histogram_data:, percentiles:
     return {} if histogram_data.empty?
 

metadata

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