predictability-engine 0.6.6

data/lib/predictability_engine/vega_visualizer/basic_charts.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module PredictabilityEngine
+  module VegaVisualizer
+    module BasicCharts
+      def self.cycle_time_scatter(items, percentiles, title: 'Cycle Time Scatter Plot')
+        completed = PredictabilityEngine.completed_items(items)
+        data = completed.map do |i|
+          { date: PredictabilityEngine.format_date(i.end_date), cycle_time: i.cycle_time, id: i.id,
+            title: i.title, title_display: VegaVisualizer.wrap_tooltip_title(i.title), url: i.url }
+        end
+        pct_data = PredictabilityEngine.mapped_percentiles(items, percentiles)
+        VegaVisualizer.apply_standard_dims(
+          Vega.lite.data(data + pct_data.map { |p| { type: p[:label], val: p[:val], p: p[:p] } })
+              .layer([scatter_points_layer, scatter_rules_layer(pct_data)]),
+          title: title
+        )
+      end
+
+      def self.scatter_points_layer
+        x_axis = VegaVisualizer.date_x_axis(title: 'Completion Date',
+                                            tickCount: { interval: 'week' })
+        { mark: { type: 'point', opacity: 0.6, size: 20 },
+          encoding: { x: x_axis,
+                      y: VegaVisualizer.quantitative_y_axis('cycle_time', title: 'Cycle Time (days)'),
+                      color: { value: '#4c78a8' },
+                      **VegaVisualizer.item_href_and_tooltip(
+                        [{ field: 'date', type: 'temporal', title: 'Completion Date' },
+                         VegaVisualizer.cycle_time_tooltip_field]
+                      ) } }
+      end
+
+      def self.scatter_rules_layer(pct_data)
+        count = pct_data.size
+        palette = ['#72b7b2', '#e45756', '#b279a2', '#ff9da7', '#ad494a', '#8ca27a']
+        # More distinct dash styles and thicker lines
+        dash_map = { 50 => [], 75 => [8, 4], 85 => [4, 4], 95 => [2, 2], 98 => [1, 1] }
+        width_map = { 50 => 1.5, 75 => 2, 85 => 2.5, 95 => 3, 98 => 3.5 }
+
+        dash_condition = dash_map.map { |p, dash| { test: "datum.p == #{p}", value: dash } }
+        width_condition = width_map.map { |p, w| { test: "datum.p == #{p}", value: w } }
+
+        { transform: [{ filter: 'datum.type != null' }],
+          mark: { type: 'rule' },
+          encoding: { y: VegaVisualizer.quantitative_y_axis('val', title: 'Cycle Time (days)'),
+                      strokeDash: { condition: dash_condition, value: [4, 4] },
+                      strokeWidth: { condition: width_condition, value: 1 },
+                      color: { field: 'type', type: 'nominal', title: 'Percentiles',
+                               scale: { range: palette.take(count) },
+                               legend: { orient: 'bottom', columns: 3 } },
+                      tooltip: [{ field: 'type', type: 'nominal', title: 'Percentile' },
+                                VegaVisualizer.cycle_time_tooltip_field(field: 'val')] } }
+      end
+
+      def self.throughput_histogram(items, title: 'Throughput Histogram')
+        data = Calculators::Throughput.daily(items).values.map { |v| { throughput: v } }
+        bar_chart(data, title: title,
+                        x: VegaVisualizer.quantitative_x_axis('throughput', bin: true, title: 'Items per Day'),
+                        y: VegaVisualizer.quantitative_y_axis('count', aggregate: 'count', title: 'Frequency'))
+      end
+
+      BAND_COLORS = %w[#2ca02c #98df8a #ffdd57 #ff7f0e #d62728 #7b0000].freeze
+
+      GRANULARITY_PARAM = {
+        name: 'granularity',
+        value: 'yearweek',
+        bind: { input: 'select',
+                options: %w[yearday yearweek yearmonth],
+                labels: %w[Daily Weekly Monthly],
+                name: 'Group by: ' }
+      }.freeze
+
+      PERIOD_EXPR = "granularity === 'yearmonth' ? datum.date_month : " \
+                    "(granularity === 'yearday' ? datum.date : datum.date_week)"
+
+      def self.cycle_time_bands(items, title: 'Cycle Time Bands Over Time', **)
+        labels = RawDataExporter::DONE_THRESHOLD_LABELS
+        completed = PredictabilityEngine.completed_items(items)
+        return Vega.lite.data([]).title(title) if completed.empty?
+
+        data = completed.map do |item|
+          idx = RawDataExporter.threshold_index(item.cycle_time)
+          { date: PredictabilityEngine.format_date(item.end_date),
+            date_week: PredictabilityEngine.format_year_week(item.end_date),
+            date_month: PredictabilityEngine.format_year_month(item.end_date),
+            band: labels[idx], band_order: idx }
+        end
+        VegaVisualizer.apply_standard_dims(
+          Vega.lite.data(data)
+              .params([GRANULARITY_PARAM])
+              .transform([{ calculate: PERIOD_EXPR, as: 'period' }])
+              .mark(type: 'area')
+              .encoding(
+                x: { field: 'period', type: 'ordinal', sort: 'ascending',
+                     title: nil, axis: VegaVisualizer::LABEL_AXIS },
+                y: { aggregate: 'count', type: 'quantitative', title: 'Items Completed' },
+                color: { field: 'band', type: 'ordinal', sort: labels,
+                         scale: { domain: labels, range: BAND_COLORS },
+                         legend: { title: 'Cycle Time', orient: 'bottom', columns: labels.size } },
+                order: { field: 'band_order', type: 'quantitative' },
+                tooltip: [
+                  { field: 'period', type: 'ordinal', title: 'Period' },
+                  { field: 'band', type: 'ordinal', title: 'Cycle Time' },
+                  { aggregate: 'count', type: 'quantitative', title: 'Items' }
+                ]
+              ),
+          title: title
+        )
+      end
+
+      def self.bar_chart(data, title:, **encoding)
+        VegaVisualizer.apply_standard_dims(
+          Vega.lite.data(data).mark(type: 'bar', tooltip: true).encoding(**encoding),
+          title: title
+        )
+      end
+
+      private_class_method :bar_chart
+    end
+  end
+end

data/lib/predictability_engine/vega_visualizer/cfd_charts.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module PredictabilityEngine
+  module VegaVisualizer
+    module CfdCharts
+      def self.cfd(work_items, title: 'Cumulative Flow Diagram', history_range: nil)
+        data = Calculators::Cfd.calculate(work_items)
+        days = Duration.parse(history_range)
+        data = data.last(days) if days
+        formatted = VegaVisualizer.format_cfd_data(data)
+        render_cfd(formatted, [], title)
+      end
+
+      def self.forecasted_cfd(work_items, percentiles, title, history_range: nil)
+        data = Calculators::Cfd.forecast_series(work_items, percentiles: percentiles, history_range: history_range)
+        return cfd(work_items, title: title) unless data
+
+        unified = VegaVisualizer.build_cfd_unified_data(data, percentiles)
+        render_cfd(unified, percentiles, title, forecast: data)
+      end
+
+      def self.render_cfd(data, percentiles, title, forecast: nil)
+        dom, range = VegaVisualizer.cfd_color_scale(percentiles)
+        chart = base_cfd_chart(data, dom, range)
+                .layer(cfd_layers(percentiles, forecast))
+        resolved_title = forecast ? forecast_title(title) : title
+        padding = forecast ? { right: 80, top: 30 } : nil
+        VegaVisualizer.apply_standard_dims(chart, title: resolved_title, padding: padding)
+      end
+
+      def self.forecast_title(text)
+        { text: text,
+          subtitle: [
+            'Each X% Confidence surface = forecast of cumulative departures if backlog completes at that confidence',
+            '(Monte Carlo on historical throughput; NOT cycle-time percentile bands)'
+          ] }
+      end
+
+      def self.cfd_layers(percentiles, forecast)
+        layers = [VegaVisualizer.cfd_area_layer(percentiles, legend: !percentiles.empty?)]
+        return layers unless forecast
+
+        layers + [VegaVisualizer.cfd_line_layer(percentiles),
+                  *VegaVisualizer.cfd_vert_layers(forecast, percentiles)]
+      end
+
+      def self.base_cfd_chart(data, dom, range)
+        # Find last day to ensure it can be labeled
+        dates = data.map { |d| PredictabilityEngine.format_date(d[:date]) }.compact.uniq.sort
+        first_date = Date.parse(dates.first)
+        last_date = Date.parse(dates.last)
+
+        # Major ticks every week, starting from first_date, plus exactly last_date
+        major_ticks = []
+        curr = first_date
+        while curr < last_date
+          major_ticks << PredictabilityEngine.format_date(curr)
+          curr += 7
+        end
+        major_ticks << PredictabilityEngine.format_date(last_date)
+        major_ticks.uniq!
+
+        # Use axis options directly in date_x_axis to avoid hash merge overwrite
+        Vega.lite.data(data)
+            .encoding(
+              x: VegaVisualizer.date_x_axis(
+                values: major_ticks,
+                labelFlush: true,
+                labelOverlap: 'parity',
+                minorTicks: true,
+                tickSize: 8,
+                minorTickSize: 4
+              ),
+              y: VegaVisualizer.quantitative_y_axis('count', title: 'Total Items'),
+              color: { field: 'type', type: 'nominal', scale: { domain: dom, range: range } }
+            )
+      end
+
+      private_class_method :base_cfd_chart, :forecast_title
+    end
+  end
+end

data/lib/predictability_engine/vega_visualizer/cfd_layout.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module PredictabilityEngine
+  module VegaVisualizer
+    # Layout and data logic for CFD charts in Vega-Lite.
+    module CfdLayout
+      def self.build_unified_data(data, percentiles)
+        res = []
+        sorted_pcts = percentiles.sort
+        data[:dates].each_with_index do |date, i|
+          res << { date: PredictabilityEngine.format_date(date), count: data[:arrivals][i], type: 'Arrivals', order: 0 }
+          sorted_pcts.each_with_index do |p, pi|
+            res << { date: PredictabilityEngine.format_date(date), count: data[:forecasts][p][i],
+                     type: "#{p}% Confidence", order: pi + 1 }
+          end
+          if i < data[:departed].size
+            res << { date: PredictabilityEngine.format_date(date), count: data[:departed][i], type: 'Departures',
+                     order: sorted_pcts.size + 1 }
+          end
+        end
+        res
+      end
+
+      def self.color_scale(pcts)
+        sorted_pcts = pcts.sort
+        dom = ['Arrivals'] + sorted_pcts.map { |p| "#{p}% Confidence" } + ['Departures']
+        palette = ['#72b7b2', '#e45756', '#b279a2', '#ff9da7', '#ad494a', '#8ca27a']
+        range = ['#4c78a8'] + palette.take(sorted_pcts.size) + ['#59a14f']
+        [dom, range]
+      end
+
+      def self.area_layer(pcts, legend: true)
+        cfg = { field: 'type', type: 'nominal' }
+        cfg[:legend] = { title: 'Flow & Forecast', orient: 'bottom', columns: 3 } if legend && !pcts.empty?
+        { mark: { type: 'area' },
+          encoding: { y: VegaVisualizer.quantitative_y_axis('count', title: 'Total Items', stack: nil),
+                      color: cfg,
+                      order: { field: 'order', type: 'quantitative' },
+                      tooltip: VegaVisualizer.cfd_tooltip_fields } }
+      end
+
+      def self.line_layer
+        { mark: { type: 'line' },
+          encoding: { y: VegaVisualizer.quantitative_y_axis('count', title: 'Total Items'),
+                      strokeDash: {
+                        condition: { test: "datum.type == 'Arrivals' || datum.type == 'Departures'", value: [] },
+                        value: [4, 4]
+                      },
+                      tooltip: VegaVisualizer.cfd_tooltip_fields } }
+      end
+
+      def self.vert_layers(forecast, percentiles)
+        data = vert_data(forecast, percentiles)
+        [rule_layer(data), text_layer(data)]
+      end
+
+      def self.rule_layer(data)
+        base_layer(data).merge(
+          mark: { type: 'rule', strokeDash: [4, 2], strokeWidth: 2, tooltip: true },
+          encoding: vert_encoding(y: { datum: 0 }, y2: VegaVisualizer.quantitative_y_axis('count', title: nil))
+        )
+      end
+
+      def self.text_layer(data)
+        base_layer(data).merge(
+          mark: { type: 'text', align: 'left', baseline: 'middle',
+                  fontWeight: 'bold', fontSize: 10, angle: -45, dx: 5,
+                  clip: false, tooltip: true },
+          encoding: vert_encoding(y: VegaVisualizer.quantitative_y_axis('count', title: 'Total Items'),
+                                  text: { field: 'label' })
+        )
+      end
+
+      def self.vert_encoding(**opts)
+        { x: VegaVisualizer.date_axis_base, tooltip: tooltip_field, color: { value: '#e45756' } }.merge(opts)
+      end
+
+      def self.base_layer(data)
+        { data: { values: data } }
+      end
+
+      def self.tooltip_field
+        { field: 'tooltip', type: 'nominal' }
+      end
+
+      def self.vert_data(forecast, percentiles)
+        sorted_pcts = percentiles.sort
+        data_by_date = group_pcts_by_date(forecast, sorted_pcts)
+
+        # IMMUTABLE invariant — see CLAUDE.md §"Forecast alignment invariant".
+        # Rule height = percentile-surface plateau (departed_so_far + wip), so each
+        # vertical rule hits the top-right corner of its p% surface exactly.
+        plateau = forecast[:summary][:departed_so_far] + forecast[:summary][:wip]
+
+        data_by_date.sort_by { |date, _| date }.map do |date, p_list|
+          date_str = PredictabilityEngine.format_date(date)
+          label = "#{p_list.sort.map { |p| "#{p}%" }.join(', ')} (#{date_str})"
+
+          { date: date_str, label: label,
+            tooltip: p_list.map { |p| "#{p}% Confidence (#{date_str})" }.join("\n"),
+            count: plateau }
+        end
+      end
+
+      def self.group_pcts_by_date(forecast, sorted_pcts)
+        groups = []
+        today = forecast[:summary][:today]
+
+        sorted_pcts.each do |p|
+          days = forecast[:summary][:"p#{p}"]
+          next unless days
+
+          date = today + days
+
+          # Collision avoidance: if date is close to an existing group, add to it
+          # Threshold: 2 days seems reasonable for collision avoidance
+          matched_group = groups.find { |g| (g[:date] - date).abs <= 2 }
+          if matched_group
+            matched_group[:pcts] << p
+          else
+            groups << { date: date, pcts: [p] }
+          end
+        end
+
+        groups.to_h { |g| [PredictabilityEngine.format_date(g[:date]), g[:pcts]] }
+      end
+
+      private_class_method :rule_layer, :text_layer, :tooltip_field,
+                           :group_pcts_by_date, :base_layer, :vert_encoding
+    end
+  end
+end

data/lib/predictability_engine/vega_visualizer/tooltip_helpers.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module PredictabilityEngine
+  module VegaVisualizer
+    module TooltipHelpers
+      TOOLTIP_WRAP_WIDTH = 40
+
+      def item_id_tooltip_field = { field: 'id', type: 'nominal', title: 'Work Item ID' }
+      def title_tooltip_field = { field: 'title_display', type: 'nominal', title: 'Title' }
+      def standard_item_tooltip_fields = [item_id_tooltip_field, title_tooltip_field]
+      def item_href_and_tooltip(extra) = { href: url_href, tooltip: standard_item_tooltip_fields + extra }
+      def url_href = { field: 'url', type: 'nominal' }
+
+      def cycle_time_tooltip_field(field: 'cycle_time')
+        { field: field, type: 'quantitative', title: 'Cycle Time (days)' }
+      end
+
+      def cfd_tooltip_fields
+        [{ field: 'date', type: 'temporal', title: 'Date' }, { field: 'type', type: 'nominal', title: 'Type' },
+         { field: 'count', type: 'quantitative', title: 'Items' }]
+      end
+
+      def wrap_tooltip_title(text, width: TOOLTIP_WRAP_WIDTH)
+        str = text.to_s
+        return str if str.length <= width
+
+        str.split.each_with_object(['']) do |word, lines|
+          lines << '' if "#{lines.last} #{word}".strip.length > width
+          lines[-1] = "#{lines.last} #{word}".strip
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/predictability_engine/vega_visualizer.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'vega'
+require_relative 'vega_visualizer/tooltip_helpers'
+require_relative 'vega_visualizer/basic_charts'
+require_relative 'vega_visualizer/cfd_charts'
+require_relative 'vega_visualizer/aging_wip_visualizer'
+require_relative 'vega_visualizer/cfd_layout'
+
+module PredictabilityEngine
+  module VegaVisualizer
+    CHART_WIDTH = 500
+    CHART_HEIGHT = 300
+    LABEL_AXIS = { labelAngle: -45, labelOverlap: 'parity' }.freeze
+
+    extend TooltipHelpers
+
+    def self.apply_standard_dims(chart, title: nil, padding: nil)
+      chart = chart.title(title) if title
+      cfg = { autosize: { type: 'fit', contains: 'padding' }, axis: { grid: false } }
+      cfg[:padding] = padding if padding
+      chart.width('container').height('container').config(cfg)
+    end
+
+    def self.date_axis_base(title: 'Date')
+      { field: 'date', type: 'temporal', title: title, axis: { format: '%Y-%m-%d' } }
+    end
+
+    def self.date_x_axis(title: 'Date', **opts)
+      base = date_axis_base(title: title)
+      base[:axis] = base[:axis].merge(labelAngle: -45).merge(opts)
+      base
+    end
+
+    def self.quantitative_y_axis(...) = quantitative_axis(...)
+    def self.quantitative_x_axis(...) = quantitative_axis(...)
+
+    def self.quantitative_axis(field, title: :auto, **opts)
+      res = { field: field.to_s, type: 'quantitative' }
+      res[:title] = title == :auto ? field.to_s.capitalize : title
+      res.merge(opts)
+    end
+    private_class_method :quantitative_axis
+
+    def self.cycle_time_scatter(items, percentiles: PredictabilityEngine::DEFAULT_PERCENTILES,
+                                title: 'Cycle Time Scatter Plot', **)
+      BasicCharts.cycle_time_scatter(items, percentiles, title: title)
+    end
+
+    def self.throughput_histogram(items, title: 'Throughput Histogram', **)
+      BasicCharts.throughput_histogram(items, title: title)
+    end
+
+    def self.cycle_time_bands(items, title: 'Cycle Time Bands Over Time', **)
+      BasicCharts.cycle_time_bands(items, title: title)
+    end
+
+    def self.aging_wip(items, title: 'Aging Work In Progress',
+                       percentiles: PredictabilityEngine::DEFAULT_PERCENTILES, **)
+      AgingWipVisualizer.aging_wip(items, title: title, percentiles: percentiles, **)
+    end
+
+    def self.cfd(work_items, title: 'Cumulative Flow Diagram', history_range: nil, **_opts)
+      CfdCharts.cfd(work_items, title: title, history_range: history_range)
+    end
+
+    def self.forecasted_cfd(work_items, percentiles: PredictabilityEngine::DEFAULT_PERCENTILES,
+                            title: 'Forecasted Cumulative Flow Diagram', history_range: nil, **_opts)
+      CfdCharts.forecasted_cfd(work_items, percentiles, title, history_range: history_range)
+    end
+
+    def self.build_cfd_unified_data(data, percentiles)
+      CfdLayout.build_unified_data(data, percentiles)
+    end
+
+    def self.cfd_color_scale(pcts)
+      CfdLayout.color_scale(pcts)
+    end
+
+    def self.cfd_area_layer(pcts, legend: true)
+      CfdLayout.area_layer(pcts, legend: legend)
+    end
+
+    def self.cfd_line_layer(_pcts)
+      CfdLayout.line_layer
+    end
+
+    def self.cfd_vert_layers(forecast, percentiles)
+      CfdLayout.vert_layers(forecast, percentiles)
+    end
+
+    def self.format_cfd_data(cfd)
+      cfd.flat_map do |d|
+        [{ date: PredictabilityEngine.format_date(d[:date]), count: d[:arrived], type: 'Arrivals', order: 0 },
+         { date: PredictabilityEngine.format_date(d[:date]), count: d[:departed], type: 'Departures', order: 1 }]
+      end
+    end
+
+    def self.dashboard(items, percentiles: PredictabilityEngine::DEFAULT_PERCENTILES)
+      charts = [aging_wip(items), forecasted_cfd(items, percentiles: percentiles), cfd(items),
+                cycle_time_scatter(items, percentiles: percentiles),
+                throughput_histogram(items)]
+      Vega.lite.vconcat(charts.map { |c| c.spec.except('$schema') })
+    end
+  end
+end

data/lib/predictability_engine/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PredictabilityEngine
+  VERSION = '0.6.6'
+end

data/lib/predictability_engine/visualizer.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative 'terminal_visualizer'
+require_relative 'vega_visualizer'
+require_relative 'summary_visualizer'
+require_relative 'html_style'
+require_relative 'html_templates'
+
+module PredictabilityEngine
+  class Visualizer
+    def self.cycle_time_scatter(items, color: false, percentiles: PredictabilityEngine::DEFAULT_PERCENTILES)
+      TerminalVisualizer.cycle_time_scatter(items, color: color, percentiles: percentiles)
+    end
+
+    def self.throughput_histogram(items, color: false)
+      TerminalVisualizer.throughput_histogram(items, color: color)
+    end
+
+    def self.cfd_plot(items, color: false)
+      TerminalVisualizer.cfd_plot(items, color: color)
+    end
+
+    def self.forecasted_cfd_plot(items, color: false, percentiles: PredictabilityEngine::DEFAULT_PERCENTILES)
+      TerminalVisualizer.forecasted_cfd_plot(items, color: color, percentiles: percentiles)
+    end
+
+    def self.aging_wip(items, color: false, percentiles: PredictabilityEngine::DEFAULT_PERCENTILES)
+      TerminalVisualizer.aging_wip(items, color: color, percentiles: percentiles)
+    end
+
+    %i[cycle_time_scatter throughput_histogram cfd forecasted_cfd aging_wip dashboard].each do |m|
+      define_singleton_method("vega_#{m}") { |items, **opts| VegaVisualizer.send(m, items, **opts) }
+    end
+
+    def self.to_full_html(content_or_chart, work_items = nil, **opts)
+      title = opts.fetch(:title, 'Predictability Engine Dashboard')
+      percentiles = opts.fetch(:percentiles, PredictabilityEngine::DEFAULT_PERCENTILES)
+      sub_reports = opts.fetch(:sub_reports, nil)
+
+      style = HTML_STYLE_LANDSCAPE
+      body = HTML_LANDSCAPE_BODY
+      summary = work_items ? SummaryVisualizer.metrics_html(work_items, percentiles: percentiles) : ''
+
+      nav_bar = build_nav_bar(sub_reports)
+
+      html = HTML_BASE.gsub('{{STYLE}}', style).gsub('{{BODY}}', body)
+      html.gsub!('{{TITLE}}', title)
+      html.gsub!('{{DATE}}', PredictabilityEngine.format_datetime(Time.now))
+      html.gsub!('{{SUMMARY_CONTENT}}', summary)
+      html.gsub!('{{NAV_BAR}}', nav_bar)
+
+      content = prepare_html_content(content_or_chart, :landscape, html)
+      # If it was a single chart, it might still have {{CHART_PANELS}} placeholder
+      if html.include?('{{CHART_PANELS}}')
+        panel = "<div class='chart-panel' style='grid-column: span 2; grid-row: span 2;'>" \
+                "<div class='panel-header'>" \
+                "<button class='chart-expand' onclick='toggleFullscreen(this)' title='Expand'></button></div>" \
+                "<div class='chart-container'>#{content}</div></div>"
+        html.gsub!('{{CHART_PANELS}}', panel)
+      end
+      html
+    end
+
+    def self.build_nav_bar(sub_reports)
+      return '' unless sub_reports&.any?
+
+      view_items, dl_items = sub_reports.partition { |r| !r[:download] }
+      html = view_nav_section(view_items) + export_nav_section(dl_items, view_items.any?)
+      "<ul class='nav-links'>#{html}</ul>"
+    end
+
+    def self.view_nav_section(view_items)
+      return '' unless view_items.any?
+
+      "<li><strong>View:</strong></li>#{render_nav_items(view_items)}"
+    end
+
+    def self.export_nav_section(dl_items, has_view)
+      return '' unless dl_items.any?
+
+      sep = has_view ? "<li class='nav-sep' aria-hidden='true'>|</li>" : ''
+      "#{sep}<li><strong>Export:</strong></li>#{render_nav_items(dl_items)}"
+    end
+
+    def self.render_nav_items(items)
+      items.map { |r| nav_item(r) }.join
+    end
+
+    def self.nav_item(entry)
+      return "<li class='nav-sep' aria-hidden='true'>|</li>" if entry[:separator]
+
+      dl = entry[:download] ? ' download' : ''
+      "<li><a href='#{entry[:url]}' class='#{'active' if entry[:active]}'#{dl}>#{entry[:label]}</a></li>"
+    end
+
+    def self.prepare_html_content(content_or_chart, layout, html)
+      if layout == :landscape && content_or_chart.is_a?(Array)
+        panels = content_or_chart.map do |cfg|
+          "<div class='chart-panel'>" \
+            "<div class='panel-header'><h2>#{cfg[:title]}</h2>" \
+            "<button class='chart-expand' onclick='toggleFullscreen(this)' title='Expand'></button></div>" \
+            "<div class='chart-container'>#{cfg[:chart].to_html}</div></div>"
+        end.join("\n")
+        html.gsub!('{{CHART_PANELS}}', panels)
+        ''
+      else
+        content = content_or_chart.respond_to?(:to_html) ? content_or_chart.to_html : content_or_chart
+        content.is_a?(Array) ? content.join("\n") : content
+      end
+    end
+
+    private_class_method :prepare_html_content, :view_nav_section, :export_nav_section, :render_nav_items
+  end
+end