keystone_ui 0.43.0 → 0.45.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebff0095e42a243e35a441d1fd749813728e8abe011529ec23cb599602312c45
-  data.tar.gz: 0fc80932c6f8b9ea4c8511fa4ba83e9989eb97e4a74cbe9339999efdd8f62249
+  metadata.gz: 978bd820f9629e5a312c465218ba68c9f055edbf7d4e740b450ffc935541ef00
+  data.tar.gz: 1d210e3d67198f807e6ebd626de17c8f39ff98182409b6b1746061f1b63830f9
 SHA512:
-  metadata.gz: f9b81f7b07775c5ba362010016b5dacd0bb9a298620723cb20fee5fbd2ee96da12211256da33f4bb72029e8bfcc3392e6b5d42fad8efceb33a48d11642cbf99a
-  data.tar.gz: b0debeea715db19ec6aaac0731abd03bd7f4670a9f2a979f0a541a72588cccb2324b2569f3962c70812af5b0c514af17e57adcb46de28f509a27a173b84cd2fc
+  metadata.gz: 57965061e3a70ccd8ee5be0dd9c9ba7af36afac30278bcb84fa1ec19a74c2b135367bb4fddc06371b5c914d5a6ad2c1b8332dca913ec823aa6030a28028a514a
+  data.tar.gz: 2d8c7a55901017fc335b759596bf13a400ece07714e13a986029fa142cf94f287db343a8468555074d0847433ca227e9893466625b5c94da4d2edc936d371afc

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/components/keystone/ui/value_list_component.html.erb

@@ -0,0 +1,11 @@
+<dl class="<%= classes %>">
+  <% rows.each do |row| %>
+    <div class="<%= row_classes(row) %>">
+      <dt class="ks-value-list-label">
+        <%= row[:label] %>
+        <% if row[:note] %><span class="ks-value-list-note"><%= row[:note] %></span><% end %>
+      </dt>
+      <dd class="ks-value-list-value"><%= shown_value(row) %></dd>
+    </div>
+  <% end %>
+</dl>

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class ValueListComponent < ViewComponent::Base
+      ALIGN_CLASSES = { start: nil, end: "ks-value-list-end" }.freeze
+
+      attr_reader :rows
+
+      def initialize(rows:, align: :start)
+        @rows = rows
+        @align = align
+      end
+
+      def classes
+        [ "ks-value-list", ALIGN_CLASSES.fetch(@align) ].compact.join(" ")
+      end
+
+      def shown_value(row)
+        row[:value].to_s.empty? ? row[:fallback] : row[:value]
+      end
+
+      def row_classes(row)
+        [ "ks-value-list-row", ("ks-value-list-total" if row[:total]) ].compact.join(" ")
+      end
+    end
+  end
+end

data/app/helpers/keystone_ui_helper.rb

@@ -249,6 +249,10 @@ module KeystoneUiHelper
     render Keystone::Ui::ParagraphComponent.new(**args)
   end
 
+  def ui_value_list(**args)
+    render Keystone::Ui::ValueListComponent.new(**args)
+  end
+
   def ui_info(**args, &block)
     render(Keystone::Ui::InfoComponent.new(**args), &block)
   end

data/lib/keystone_ui/safelist.rb

@@ -32,6 +32,7 @@ module Keystone
       Keystone::Ui::CardLinkComponent,
       Keystone::Ui::InputComponent,
       Keystone::Ui::TextareaComponent,
+      Keystone::Ui::ValueListComponent,
       Keystone::Ui::FormFieldComponent,
       Keystone::Ui::PageHeaderComponent,
       Keystone::Ui::ParagraphComponent,

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -66,6 +66,7 @@ not available in the app yet, that is `keystone_ui-install`'s job.
 - `ui_heading` — a heading at one of three sizes, with an optional short note on its right.
 - `ui_caption` — small uppercase muted text placed above a title or a figure.
 - `ui_paragraph` — a paragraph of running text.
+- `ui_value_list` — rows of a label and its value, such as a ledger or a byline.
 - `ui_alert` — a banner message, optionally dismissible.
 - `ui_progress` — a labelled progress bar.
 - `ui_stat_card` — a single metric tile with optional change, link and info button.
@@ -332,13 +333,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
@@ -404,6 +410,9 @@ two exceptions: `ui_page`'s `padding:` treats any value other than `:none` as
      and `note:` puts a short muted note at the right end of the heading's row.
    - `ui_caption(text:)` shows small uppercase muted text above a title or a figure.
    - `ui_paragraph(text:)` shows running text.
+   - `ui_value_list(rows:, align: :start)` — each row is `{ label:, value: }`
+     with optional `note:`, `total: true` and `fallback:`, shown when the value
+     is `nil` or empty. `align: :end` pushes values to the right, as in a ledger.
 
 10. Explain figures.
 

data/the_local/interface.yml

@@ -67,6 +67,7 @@ develop:
   - ui_heading
   - ui_caption
   - ui_paragraph
+  - ui_value_list
   - ui_breakdown
   - ui_theme_toggle
   - Keystone::Ui::Column

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.43.0
+  version: 0.45.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.19.0
+        version: 0.20.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.19.0
+        version: 0.20.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -202,6 +202,8 @@ files:
 - app/components/keystone/ui/textarea_component.rb
 - app/components/keystone/ui/theme_toggle_component.html.erb
 - app/components/keystone/ui/theme_toggle_component.rb
+- app/components/keystone/ui/value_list_component.html.erb
+- app/components/keystone/ui/value_list_component.rb
 - app/helpers/keystone_ui_helper.rb
 - config/importmap.rb
 - lib/generators/keystone/install_generator.rb