keystone_ui 0.44.0 → 0.46.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 399e1a496d6abbf8fc37149cbf05ea62223222c1cf6b5678dc400b286a17f06a
-  data.tar.gz: 5d7566e89343b57e8a35a6693e4fe6107184203299a880d58eab541b6ff16d81
+  metadata.gz: 1209af69898ff5cfa1879680b8d9de9a9ca569474d6471a85f906f1bdcac7425
+  data.tar.gz: 4f7d5750c98755ccc5ac4a7c17095f018219e731417101d60e2ea5b2f2e164d1
 SHA512:
-  metadata.gz: e0e0ab5ac2704a8612ec78bd80987d61ddfaee104cf0eedf976075e8ea28b4d64ac26990e061055165d334f06c8951b0eb8083b6005cb666dd8d47fec7ec5a7f
-  data.tar.gz: 8de679cd46c03c8c8856196fc1d73d87def5ab3910c7b142d744ab7fca02c8b011f0cea93a2a2b42979d677b84c7448c32880d2ab6783851506188622bba7c30
+  metadata.gz: 251cec86be528ce9676410c4eb8f317df3954060faa79c4e841c918681618b39f7778d2fd22e51116ec12fd4237b5dd1f617d549bd06e0c4149c412869b5da25
+  data.tar.gz: d1f9983ec813ce4ef08ee138470df4c7d60b583a07742fa0855a1d4b5ca7b69a5d1c3c0b98a0ea11defbd026c9cbe7aa99cc0a65e53613808e33446722666cbf

data/app/components/keystone/ui/bar_chart_component.html.erb

@@ -0,0 +1,13 @@
+<svg class="ks-bar-chart" viewBox="0 0 <%= Keystone::Ui::BarChartComponent::WIDTH %> <%= Keystone::Ui::BarChartComponent::HEIGHT %>" role="img">
+  <% ticks.each do |tick| %>
+    <line class="ks-bar-chart-grid" x1="<%= Keystone::Ui::BarChartComponent::LEFT %>" x2="<%= Keystone::Ui::BarChartComponent::WIDTH - Keystone::Ui::BarChartComponent::RIGHT %>" y1="<%= tick[:y].round(2) %>" y2="<%= tick[:y].round(2) %>"></line>
+    <text class="ks-bar-chart-text" data-axis-tick x="<%= axis_x %>" y="<%= (tick[:y] + 4).round(2) %>" text-anchor="end"><%= tick[:label] %></text>
+  <% end %>
+  <% drawn_bars.each do |bar| %>
+    <rect class="<%= bar[:classes] %>" x="<%= bar[:x].round(2) %>" y="<%= bar[:y].round(2) %>" width="<%= bar[:width].round(2) %>" height="<%= bar[:height].round(2) %>"></rect>
+    <% if show_values? %>
+      <text class="ks-bar-chart-value" x="<%= bar[:center].round(2) %>" y="<%= (bar[:y] - 4).round(2) %>" text-anchor="middle"><%= bar[:value] %></text>
+    <% end %>
+    <text class="ks-bar-chart-text" data-bar-label x="<%= bar[:center].round(2) %>" y="<%= label_baseline %>" text-anchor="middle"><%= bar[:label] %></text>
+  <% end %>
+</svg>

data/app/components/keystone/ui/bar_chart_component.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class BarChartComponent < ViewComponent::Base
+      WIDTH = 600
+      HEIGHT = 240
+      LEFT = 40
+      RIGHT = 8
+      TOP = 18
+      BOTTOM = 24
+      BAR_SHARE = 0.7
+      TICK_COUNT = 4
+      ROUND_STEPS = [ 1, 2, 2.5, 5, 10 ].freeze
+
+      attr_reader :bars
+
+      def initialize(bars:, show_values: false)
+        @bars = bars
+        @show_values = show_values
+      end
+
+      def show_values?
+        @show_values
+      end
+
+      def drawn_bars
+        bars.each_with_index.map do |bar, index|
+          height = bar[:value].to_f / axis_max * plot_height
+          { x: LEFT + (index * band) + (band * (1 - BAR_SHARE) / 2), y: TOP + plot_height - height, width: band * BAR_SHARE, height: height,
+            center: LEFT + (index * band) + (band / 2), label: bar[:label], value: bar[:value],
+            classes: [ "ks-bar-chart-bar", ("ks-bar-chart-bar-shaded" if bar[:shaded]) ].compact.join(" ") }
+        end
+      end
+
+      def ticks
+        (0..TICK_COUNT).map do |position|
+          value = (step * position).round(6)
+          { y: TOP + plot_height - (value / axis_max * plot_height), label: (value % 1).zero? ? value.to_i.to_s : value.to_s }
+        end
+      end
+
+      def axis_x
+        LEFT - 6
+      end
+
+      def label_baseline
+        HEIGHT - 6
+      end
+
+      private
+
+      def axis_max
+        step * (largest / step).ceil
+      end
+
+      def step
+        @step ||= begin
+          raw = largest / TICK_COUNT
+          magnitude = 10.0**Math.log10(raw).floor
+          ROUND_STEPS.map { |round| round * magnitude }.find { |candidate| candidate >= raw }
+        end
+      end
+
+      def largest
+        bars.map { |bar| bar[:value].to_f }.select(&:positive?).max || 1.0
+      end
+
+      def band
+        plot_width / [ bars.size, 1 ].max
+      end
+
+      def plot_width
+        WIDTH - LEFT - RIGHT
+      end
+
+      def plot_height
+        HEIGHT - TOP - BOTTOM
+      end
+    end
+  end
+end

data/app/components/keystone/ui/column.rb

@@ -3,10 +3,11 @@
 module Keystone
   module Ui
     class Column
-      attr_reader :key, :header_text
+      attr_reader :key, :header_text, :align
 
-      def initialize(key, header_text, mobile_hidden: false, sortable: false, hideable: false, locked: false)
+      def initialize(key, header_text, mobile_hidden: false, sortable: false, hideable: false, locked: false, align: nil)
         @key = key
+        @align = align
         @header_text = header_text
         @mobile_hidden = mobile_hidden
         @sortable = sortable

data/app/components/keystone/ui/data_table_component.html.erb

@@ -36,6 +36,14 @@
         <% end %>
       <% else %>
         <% @items.each_with_index do |item, idx| %>
+          <% if (group = group_starting_at(idx)) %>
+            <tr class="<%= Keystone::Ui::DataTableComponent::HEAD_CLASSES %>" data-table-group>
+              <% group_cells(group).each do |cell| %>
+                <th scope="colgroup" class="<%= cell[:classes] %>"><%= cell[:value] %></th>
+              <% end %>
+              <% if actions? %><th></th><% end %>
+            </tr>
+          <% end %>
           <tr>
             <% row_cells[idx].each do |cell| %>
               <td class="<%= cell[:classes] %>">
@@ -60,5 +68,15 @@
         <% end %>
       <% end %>
     </tbody>
+    <% if total_cells.any? %>
+      <tfoot class="<%= Keystone::Ui::DataTableComponent::HEAD_CLASSES %>">
+        <tr>
+          <% total_cells.each do |cell| %>
+            <th scope="row" class="<%= cell[:classes] %>"><%= cell[:value] %></th>
+          <% end %>
+          <% if actions? %><th></th><% end %>
+        </tr>
+      </tfoot>
+    <% end %>
   </table>
 </div>

data/app/components/keystone/ui/data_table_component.rb

@@ -16,6 +16,7 @@ module Keystone
       ROW_CLASSES_MIDDLE = "ks-table-cell-middle text-sm whitespace-nowrap"
       ROW_CLASSES_LAST = "ks-table-cell-last text-right text-sm whitespace-nowrap"
 
+      ALIGN_CLASSES = { start: "text-left", end: "text-right" }.freeze
       MOBILE_HIDDEN_CLASSES = "hidden sm:table-cell"
       HEADER_LOCKED_CLASSES = "ks-table-header-locked sticky left-0"
       CELL_LOCKED_CLASSES = "ks-table-cell-locked sticky left-0"
@@ -29,8 +30,11 @@ module Keystone
       SORT_DESC_ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor"><path fill-rule="evenodd" d="M10 3a.75.75 0 0 1 .75.75v10.638l3.96-4.158a.75.75 0 1 1 1.08 1.04l-5.25 5.5a.75.75 0 0 1-1.08 0l-5.25-5.5a.75.75 0 0 1 1.08-1.04l3.96 4.158V3.75A.75.75 0 0 1 10 3Z" clip-rule="evenodd" /></svg>'
       SORT_NEUTRAL_ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor"><path fill-rule="evenodd" d="M10 3a.75.75 0 0 1 .55.24l3.25 3.5a.75.75 0 1 1-1.1 1.02L10 4.852 7.3 7.76a.75.75 0 0 1-1.1-1.02l3.25-3.5A.75.75 0 0 1 10 3Zm-3.76 9.2a.75.75 0 0 1 1.06.04l2.7 2.908 2.7-2.908a.75.75 0 1 1 1.1 1.02l-3.25 3.5a.75.75 0 0 1-1.1 0l-3.25-3.5a.75.75 0 0 1 .04-1.06Z" clip-rule="evenodd" /></svg>'
 
-      def initialize(items:, columns:, empty_message: nil, sort: nil, sort_direction: nil, sort_url: nil, hidden_columns: [], key: nil)
+      def initialize(items:, columns:, empty_message: nil, sort: nil, sort_direction: nil, sort_url: nil, hidden_columns: [], key: nil, group_by: nil, group_totals: {}, total: nil)
         @items = items.to_a
+        @group_by = group_by
+        @group_totals = group_totals.to_h.transform_keys(&:to_s)
+        @total = total&.to_h&.transform_keys(&:to_s)
         @all_columns = columns.map { |col| normalize_column(col) }
         @default_hidden = hidden_columns
         @layout = SavedLayout.new(columns: @all_columns, value: nil, default_hidden: hidden_columns)
@@ -83,7 +87,7 @@ module Keystone
 
           cell = {
             label: column.header_text,
-            classes: tokens.join(" "),
+            classes: aligned(tokens.join(" "), column),
             scope: "col"
           }
 
@@ -127,7 +131,7 @@ module Keystone
 
             cell = {
               value: resolve_value(item, column.key),
-              classes: tokens.join(" ")
+              classes: aligned(tokens.join(" "), column)
             }
 
             link_block = @link_blocks[column.key]
@@ -146,6 +150,28 @@ module Keystone
         visual_column_count
       end
 
+      def group_starting_at(index)
+        return unless @group_by
+
+        name = resolve_value(@items[index], @group_by)
+        name if index.zero? || name != resolve_value(@items[index - 1], @group_by)
+      end
+
+      def total_cells
+        return [] unless @total
+
+        @columns.map.with_index do |column, index|
+          { value: @total[column.key.to_s], classes: aligned(header_classes_for(index), column) }
+        end
+      end
+
+      def group_cells(name)
+        subtotals = @group_totals.fetch(name.to_s, {}).to_h.transform_keys(&:to_s)
+        @columns.map.with_index do |column, index|
+          { value: index.zero? ? name : subtotals[column.key.to_s], classes: aligned(header_classes_for(index), column) }
+        end
+      end
+
       private
 
       def apply_saved_layout
@@ -170,6 +196,12 @@ module Keystone
         end
       end
 
+      def aligned(classes, column)
+        return classes unless column.align
+
+        [ *classes.split.grep_v(/\Atext-(left|right)\z/), ALIGN_CLASSES.fetch(column.align) ].join(" ")
+      end
+
       def resolve_value(item, key)
         if item.respond_to?(key)
           item.public_send(key)

data/app/helpers/keystone_ui_helper.rb

@@ -21,6 +21,10 @@ module KeystoneUiHelper
     render Keystone::Ui::LineChartComponent.new(**args)
   end
 
+  def ui_bar_chart(**args)
+    render Keystone::Ui::BarChartComponent.new(**args)
+  end
+
   def ui_cta_banner(**args, &block)
     render Keystone::Ui::CtaBannerComponent.new(**args), &block
   end

data/lib/keystone_ui/safelist.rb

@@ -21,6 +21,7 @@ module Keystone
       Keystone::Ui::ModalComponent,
       Keystone::Ui::SelectComponent,
       Keystone::Ui::BadgeComponent,
+      Keystone::Ui::BarChartComponent,
       Keystone::Ui::CopyButtonComponent,
       Keystone::Ui::CardComponent,
       Keystone::Ui::ButtonComponent,

data/lib/keystone_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeystoneUi
-  VERSION = "0.44.0"
+  VERSION = "0.46.0"
 end

data/the_local/agents/keystone_ui-develop.md

@@ -82,6 +82,7 @@ not available in the app yet, that is `keystone_ui-install`'s job.
 - `ui_swipe_deck` — a stack of cards accepted or rejected by button or swipe.
 - `ui_chart_card` — a titled card holding a chart.
 - `ui_line_chart` — a line chart with one line per series, over labels or dates.
+- `ui_bar_chart` — a bar chart drawn on the server, which needs no JavaScript and prints.
 - `ui_funnel` — a conversion funnel drawn as bars or one joined shape.
 - `ui_bucket` — an upright container filled toward a goal.
 - `ui_bucket_series` — a wrapping row of buckets.
@@ -333,13 +334,18 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
 
 8. Build tables.
 
-   - `ui_data_table(items:, columns:, empty_message: nil, sort: nil, sort_direction: nil, sort_url: nil, hidden_columns: [], key: nil)`
+   - `ui_data_table(items:, columns:, empty_message: nil, sort: nil, sort_direction: nil, sort_url: nil, hidden_columns: [], key: nil, group_by: nil, group_totals: {}, total: nil)`
      takes a block yielding the table. `items:` are records or hashes, and a
      cell's value is the column key called on the item, or `item[key]`.
+     `group_by:` lists rows under heading rows named by that key's value,
+     `group_totals:` (`{ "Group name" => { column_key => value } }`) puts
+     subtotals in each heading row, and `total:` (`{ column_key => value }`)
+     ends the table with a total row. Pass every subtotal and total already
+     calculated. `align: :start` or `:end` on a `Column` aligns it left or right.
    - `columns:` takes `{ key: "Label" }` hashes when every column is plain.
      Switch the whole set to `Keystone::Ui::Column` objects once one column
      needs an option.
-   - `Keystone::Ui::Column.new(key, header_text, mobile_hidden: false, sortable: false, hideable: false, locked: false)`
+   - `Keystone::Ui::Column.new(key, header_text, mobile_hidden: false, sortable: false, hideable: false, locked: false, align: nil)`
      — `mobile_hidden:` hides the column below `sm:`, `sortable:` gives it a
      sort header, and `hideable:` lets it be hidden and moved.
      `locked: true` on the first column keeps it in view while the rest scrolls
@@ -450,6 +456,10 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
 
     - `ui_chart_card(title:, height: :md)` takes a block holding a chart, with
       `height:` `:sm` `:md` `:lg`.
+    - `ui_bar_chart(bars:, show_values: false)` — `bars:` is
+      `[{ label:, value:, shaded: }, ...]`, where `shaded: true` draws a bar
+      faded. It is drawn on the server as an SVG, so use it, not
+      `ui_line_chart`, for a chart that must print or show without JavaScript.
     - `ui_line_chart(series:, labels: nil, dates: nil, height: :md)` —
       `series:` is `[{ name:, data:, color:, dashed: }, ...]`, where `color:`
       is a CSS colour and `dashed: true` is optional. Pass exactly one of

data/the_local/interface.yml

@@ -11,6 +11,7 @@ develop:
   - ui_stat_card
   - ui_chart_card
   - ui_line_chart
+  - ui_bar_chart
   - ui_cta_banner
   - ui_feature_grid
   - ui_hero

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.44.0
+  version: 0.46.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: 0.22.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: 0.22.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -82,6 +82,8 @@ files:
 - app/components/keystone/ui/alert_component.rb
 - app/components/keystone/ui/badge_component.html.erb
 - app/components/keystone/ui/badge_component.rb
+- app/components/keystone/ui/bar_chart_component.html.erb
+- app/components/keystone/ui/bar_chart_component.rb
 - app/components/keystone/ui/bottom_nav_component.html.erb
 - app/components/keystone/ui/bottom_nav_component.rb
 - app/components/keystone/ui/bottom_nav_item_component.html.erb