mensa 0.6.13 → 0.6.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46f7dffd40faf8998fef427762261e9dd6cd5474a177e297e0829ac35b62fc7c
-  data.tar.gz: 8b779ac0acb96d3bc9c1e75d8006c89f678ac98563e8882237d169e390b955c6
+  metadata.gz: a3d23dc5f37173fea8736de1271cd1c55f192f9bf28df2b2df7bc6d5c8e0d922
+  data.tar.gz: 190e32dd6e3d9b8e8cd3fb34875535dc494873a923895a6306289df521a17ae3
 SHA512:
-  metadata.gz: 5e4a1c95251b0125871c5af7fb6c09285987c1e6de8f5a5139927d1793a195fe280f19c0bf90aa72a093b21d16d4906700976a680fb67abdfa6fa991ac72336f
-  data.tar.gz: 8456ecef92194eef7807dc672f1c3d1fd05064ffa4b4569da78f70f297afa19e6d434322a4afedfceec66b92cfc311a4a8374dcf40d109be79039aa190fd5bfe
+  metadata.gz: 9b5913385d0de9990422c6a897631d8a3f119e025f48a994f976a30c94f7655f04874da6626e02d4aa6e88f4f45d952089b87784fb8228e2f24c14030342f950
+  data.tar.gz: ef17f02b50efaa802a7dbdbfe0fde4f8463da3c8c16fd3aa87b5344c2bbfcd21d52a36a072515a43d34caa21894bd3d4f7c75e6ac71ee613264d5692299c43c5

data/.shipkit.yml

@@ -1,2 +1,2 @@
 ---
-previous_version: 0.6.12
+previous_version: 0.6.13

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mensa (0.6.11)
+    mensa (0.6.13)
       csv
       importmap-rails
       pagy (>= 43)

data/README.md

@@ -22,15 +22,7 @@ Features:
 - [X] Search works on all table columns
 - [X] Exports can be scheduled to run recurring (daily/weekly/monthly/quarterly/bi-yearly/yearly)
       You will have to bring your own mailer, see configuration for details.
-
-TODO:
-- [ ] ...
-
-Nice to haves:
-
-- [ ] group by
-- [ ] sum/max/min
-- [ ] tables backed by arrays (of ActiveModel)
+- [X] Grouping rows by a column, with collapsible groups and count/sum/min/max per group
 
 ## Usage
 
@@ -61,6 +53,16 @@ class UserTable < ApplicationTable
     attribute "roles_count" # We use a database column here
   end
 
+  # Customize how a cell looks. Each cell is wrapped in a <td>, unless the html
+  # block returns its own td, so you can style the td itself.
+  column(:state) do
+    render do
+      html do |user|
+        content_tag(:td, user.human_state_name, class: "state state--#{user.state}")
+      end
+    end
+  end
+
   # You can add one or more actions to a row
   action :delete do
     title "Delete row"
@@ -116,6 +118,33 @@ You can show your tables on the page using the following:
 Custom views are views not defined by the developer (SystemViews) but by the end-user by adding/removing filters.
 When you enable these, they are stored in the database and can be used across sessions, by the user who created them.
 
+### Grouping
+
+Rows can be shown in groups, each with a header that shows the group's value and
+number of rows, and that collapses the group when clicked. Mark the columns users
+may group by with `groupable`, and the aggregates they may choose per column with
+`aggregates` (any of `:count`, `:sum`, `:min` and `:max`). Users pick both from the
+group button in the control bar; their choice is remembered and saved with custom views.
+
+```ruby
+column(:status) do
+  groupable true
+end
+
+column(:amount) do
+  aggregates :sum, :min, :max
+end
+
+# Optional defaults, also possible per view
+group_by :status
+aggregates amount: :sum
+```
+
+Both need an SQL attribute: a database column, or an `attribute` expression. Rows are
+sorted by the group column first (in the direction it is sorted, ascending otherwise),
+then by the chosen order. Counts and aggregates are calculated with SQL `GROUP BY` over
+all filtered rows, so they cover the whole group, also when it continues on the next page.
+
 ### Fast
 
 Mensa selects only the data it needs, based on the columns. Sometimes it needs additional columns to do it's work, but you don't want them displayed. This can be done by adding `internal true` to the column definition, or shorter: use `internal` instead. If your table scope joins an association, Mensa also auto-adds the foreign key column as internal when it is needed.

data/app/assets/stylesheets/mensa/application.css

@@ -5,6 +5,8 @@
 @import "../../../components/mensa/empty_state/component.css";
 @import "../../../components/mensa/filter_pill/component.css";
 @import "../../../components/mensa/filter_pill_list/component.css";
+@import "../../../components/mensa/group_by/component.css";
+@import "../../../components/mensa/group_header/component.css";
 @import "../../../components/mensa/header/component.css";
 @import "../../../components/mensa/row_action/component.css";
 @import "../../../components/mensa/search/component.css";

data/app/components/mensa/cell/component.html.erb

@@ -1 +1 @@
-<td><%= cell.render(:html) %></td>
+<%= cell.render(:html) %>

data/app/components/mensa/control_bar/component.html.erb

@@ -3,6 +3,7 @@
     <% if view_columns_ordering? %>
       <%= render Mensa::ColumnCustomizer::Component.new(table: table) %>
     <% end %>
+    <%= render Mensa::GroupBy::Component.new(table: table) %>
 
     <div class="mensa-table__save-reset hidden" data-mensa-table-target="saveResetButtons">
       <button class="mensa-table__control_bar__button" type="button" title="<%= t(".reset", default: "Reset") %>" data-action="mensa-table#cancelFiltersAndSearch">

data/app/components/mensa/filter_pill_list/component_controller.js

@@ -180,6 +180,8 @@ export default class FilterPillListComponentController extends ApplicationContro
             page: "",
         };
         this.persistState(state);
+        // The selected view brings its own grouping
+        this.clearPersistedGrouping();
         this.setSearchField("");
         this.updateSearchPlaceholder();
         if (this.hasMensaTableOutlet) {
@@ -293,7 +295,9 @@ export default class FilterPillListComponentController extends ApplicationContro
             query.length > 0 ||
             Object.keys(order).length > 0 ||
             columnOrder.length > 0 ||
-            hiddenColumns.length > 0
+            hiddenColumns.length > 0 ||
+            this.loadGroupBy() !== null ||
+            this.loadAggregates() !== null
         ) {
             this._notifyUnsavedState();
         }
@@ -352,6 +356,7 @@ export default class FilterPillListComponentController extends ApplicationContro
         this.removeFilterParams(url);
         this.removeOrderParams(url);
         this.removeColumnParams(url);
+        this.removeGroupingParams(url);
         url.searchParams.delete("query");
         url.searchParams.delete("page");
         url.searchParams.delete("table_view_id");
@@ -399,9 +404,30 @@ export default class FilterPillListComponentController extends ApplicationContro
             url.searchParams.append("hidden_columns[]", col),
         );
 
+        // Only send grouping the user chose, otherwise the view's default
+        // applies. Blank values mean "explicitly none".
+        const groupBy = this.loadGroupBy();
+        if (groupBy !== null) url.searchParams.set("group_by", groupBy);
+        const aggregates = this.loadAggregates();
+        if (aggregates !== null) {
+            const entries = Object.entries(aggregates);
+            if (entries.length === 0) url.searchParams.set("aggregates", "");
+            entries.forEach(([column, fn]) =>
+                url.searchParams.set(`aggregates[${column}]`, fn),
+            );
+        }
+
         return url;
     }
 
+    removeGroupingParams(url) {
+        const keys = [];
+        url.searchParams.forEach((_v, key) => {
+            if (key === "group_by" || key.startsWith("aggregates")) keys.push(key);
+        });
+        keys.forEach((key) => url.searchParams.delete(key));
+    }
+
     removeFilterParams(url) {
         const keys = new Set();
         url.searchParams.forEach((_v, key) => {
@@ -570,6 +596,28 @@ export default class FilterPillListComponentController extends ApplicationContro
         this.writeStorage(this.orderStorageKey, null);
         this.writeStorage(`mensa:column_order:${this.storageName}`, null);
         this.writeStorage(`mensa:hidden_columns:${this.storageName}`, null);
+        this.clearPersistedGrouping();
+    }
+
+    clearPersistedGrouping() {
+        this.writeStorage(this.groupByStorageKey, null);
+        this.writeStorage(this.aggregatesStorageKey, null);
+    }
+
+    // null when the user didn't choose, "" for "no grouping"
+    loadGroupBy() {
+        return this.readStorage(this.groupByStorageKey);
+    }
+
+    // null when the user didn't choose, {} for "no aggregates"
+    loadAggregates() {
+        const raw = this.readStorage(this.aggregatesStorageKey);
+        if (raw === null) return null;
+        try {
+            return JSON.parse(raw);
+        } catch (e) {
+            return null;
+        }
     }
 
     // Keep these for backward-compatibility with other controllers that look up
@@ -742,6 +790,12 @@ export default class FilterPillListComponentController extends ApplicationContro
     get orderStorageKey() {
         return `mensa:order:${this.storageName}`;
     }
+    get groupByStorageKey() {
+        return `mensa:group_by:${this.storageName}`;
+    }
+    get aggregatesStorageKey() {
+        return `mensa:aggregates:${this.storageName}`;
+    }
 
     get ourUrl() {
         return this.mensaTableOutlet.ourUrl;

data/app/components/mensa/group_by/component.css

@@ -0,0 +1,49 @@
+.mensa-table {
+    &__control_bar__button[aria-pressed="true"] {
+        @apply text-primary-600 dark:text-primary-400;
+    }
+
+    &__group_by {
+        &__popover {
+            @apply fixed z-50 w-72 max-h-96 overflow-y-auto rounded-xl bg-white dark:bg-gray-800 shadow-lg ring-1 ring-black ring-opacity-5 py-2;
+        }
+
+        &__heading {
+            @apply px-4 pt-2 pb-1 text-sm font-semibold tracking-wider text-gray-900 dark:text-gray-500;
+        }
+
+        &__option {
+            @apply w-full flex items-center gap-3 px-4 py-2 text-left text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700 cursor-pointer;
+        }
+
+        &__check {
+            @apply w-3 flex-none text-xs text-gray-700 dark:text-gray-200;
+        }
+
+        &__option:not([aria-checked="true"]) &__check {
+            @apply invisible;
+        }
+
+        &__aggregates {
+            @apply mt-1 border-t border-gray-100 dark:border-gray-700 pt-1;
+
+            &[aria-disabled="true"] {
+                @apply opacity-50 pointer-events-none;
+            }
+        }
+
+        &__aggregate {
+            @apply block px-4 py-1.5;
+
+            label {
+                @apply mb-1 block truncate text-sm font-medium text-gray-900 dark:text-gray-100;
+            }
+        }
+    }
+}
+
+/* More specific than the table's general `.mensa-table select`, which
+   would otherwise win as it is imported later. */
+.mensa-table .mensa-table__group_by__aggregate select {
+    @apply w-full py-1.5 pl-3 pr-8 text-sm;
+}

data/app/components/mensa/group_by/component.html.erb

@@ -0,0 +1,41 @@
+<div class="relative"
+     data-controller="mensa-group-by"
+     data-mensa-group-by-storage-key-value="<%= table.storage_key %>"
+     data-mensa-group-by-group-by-value="<%= table.group_column&.name %>"
+     data-mensa-group-by-aggregates-value="<%= table.current_aggregates.to_json %>"
+     data-mensa-group-by-mensa-table-outlet="#table-<%= table.table_id %>">
+  <button class="mensa-table__control_bar__button" type="button" title="<%= t("mensa.group_by.heading") %>" data-mensa-group-by-target="button" data-action="click->mensa-group-by#toggle">
+    <i class="<%= Mensa.config.icons[:group_by_toggle] %>"></i>
+  </button>
+  <div class="mensa-table__group_by__popover hidden" data-mensa-group-by-target="popover">
+    <p class="mensa-table__group_by__heading"><%= t("mensa.group_by.heading") %></p>
+    <ul>
+      <% [nil, *groupable_columns].each do |column| %>
+        <li>
+          <button class="mensa-table__group_by__option" type="button" data-column-name="<%= column&.name %>" data-mensa-group-by-target="groupOption" data-action="click->mensa-group-by#selectGroup">
+            <i class="mensa-table__group_by__check <%= Mensa.config.icons[:group_by_selected] %>"></i>
+            <span><%= column ? column.human_name : t("mensa.group_by.none") %></span>
+          </button>
+        </li>
+      <% end %>
+    </ul>
+    <% if aggregatable_columns.any? %>
+      <div class="mensa-table__group_by__aggregates" data-mensa-group-by-target="aggregates">
+        <p class="mensa-table__group_by__heading"><%= t("mensa.group_by.aggregates") %></p>
+        <ul>
+          <% aggregatable_columns.each do |column| %>
+            <li class="mensa-table__group_by__aggregate">
+              <label for="<%= "mensa-aggregate-#{table.table_id}-#{column.name}" %>"><%= column.human_name %></label>
+              <select id="<%= "mensa-aggregate-#{table.table_id}-#{column.name}" %>" data-column-name="<%= column.name %>" data-mensa-group-by-target="aggregateSelect" data-action="change->mensa-group-by#selectAggregate">
+                <option value=""><%= t("mensa.aggregates.none") %></option>
+                <% column.aggregates.each do |function| %>
+                  <option value="<%= function %>"><%= t("mensa.aggregates.#{function}") %></option>
+                <% end %>
+              </select>
+            </li>
+          <% end %>
+        </ul>
+      </div>
+    <% end %>
+  </div>
+</div>

data/app/components/mensa/group_by/component.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mensa
+  module GroupBy
+    # Lets the user choose the column to group by and the aggregates shown in
+    # the group headers
+    class Component < ::Mensa::ApplicationComponent
+      attr_reader :table
+
+      def initialize(table:)
+        @table = table
+      end
+
+      def render?
+        groupable_columns.any?
+      end
+
+      def groupable_columns
+        @groupable_columns ||= table.columns.reject(&:internal?).select(&:groupable?)
+      end
+
+      def aggregatable_columns
+        @aggregatable_columns ||= table.columns.reject(&:internal?).select(&:aggregatable?)
+      end
+    end
+  end
+end

data/app/components/mensa/group_by/component_controller.js

@@ -0,0 +1,168 @@
+import ApplicationController from "mensa/controllers/application_controller";
+
+// The group-by popover in the control bar. The choice is stored in
+// localStorage (like order and filters) and sent along by the filter pill
+// list when it requests the table; a blank group_by or an empty aggregates
+// object means "explicitly none", so it overrides the view's default.
+export default class GroupByController extends ApplicationController {
+    static outlets = ["mensa-table"];
+    static targets = ["button", "popover", "groupOption", "aggregates", "aggregateSelect"];
+    static values = { storageKey: String, groupBy: String, aggregates: Object };
+
+    connect() {
+        super.connect();
+        this._outsideClickHandler = null;
+
+        const groupBy = this._readStorage(this.groupByStorageKey);
+        if (groupBy !== null) this.groupByValue = groupBy;
+        const aggregates = this._readJson(this.aggregatesStorageKey);
+        if (aggregates !== null) this.aggregatesValue = aggregates;
+        this._render();
+    }
+
+    disconnect() {
+        this._unbindOutsideClick();
+    }
+
+    toggle() {
+        if (this.popoverTarget.classList.contains("hidden")) {
+            this.popoverTarget.classList.remove("hidden");
+            this._positionPopover();
+            this._bindOutsideClick();
+        } else {
+            this._close();
+        }
+    }
+
+    selectGroup(event) {
+        this.groupByValue = event.currentTarget.dataset.columnName || "";
+        this._writeStorage(this.groupByStorageKey, this.groupByValue);
+        this._render();
+        this._reload();
+    }
+
+    selectAggregate(event) {
+        const aggregates = { ...this.aggregatesValue };
+        const column = event.currentTarget.dataset.columnName;
+        if (event.currentTarget.value) {
+            aggregates[column] = event.currentTarget.value;
+        } else {
+            delete aggregates[column];
+        }
+        this.aggregatesValue = aggregates;
+        this._writeStorage(this.aggregatesStorageKey, JSON.stringify(aggregates));
+        this._render();
+        this._reload();
+    }
+
+    // Called by the table controller with the state the server rendered,
+    // e.g. after selecting a view or resetting.
+    sync(groupBy, aggregates) {
+        this.groupByValue = groupBy || "";
+        this.aggregatesValue = aggregates || {};
+        this._render();
+    }
+
+    // --- private ---
+
+    _render() {
+        this.groupOptionTargets.forEach((option) => {
+            option.setAttribute(
+                "aria-checked",
+                ((option.dataset.columnName || "") === this.groupByValue).toString(),
+            );
+        });
+        this.aggregateSelectTargets.forEach((select) => {
+            select.value = this.aggregatesValue[select.dataset.columnName] || "";
+        });
+        if (this.hasAggregatesTarget) {
+            this.aggregatesTarget.setAttribute(
+                "aria-disabled",
+                (this.groupByValue === "").toString(),
+            );
+        }
+        if (this.hasButtonTarget) {
+            this.buttonTarget.setAttribute(
+                "aria-pressed",
+                (this.groupByValue !== "").toString(),
+            );
+        }
+    }
+
+    _reload() {
+        const list = this.hasMensaTableOutlet
+            ? this.mensaTableOutlet.mensaFilterPillListOutlet
+            : null;
+        if (list) list.refreshFilters();
+    }
+
+    _close() {
+        this.popoverTarget.classList.add("hidden");
+        this._unbindOutsideClick();
+    }
+
+    _positionPopover() {
+        const rect = this.buttonTarget.getBoundingClientRect();
+        const gap = 4;
+        const viewportPadding = 16;
+        const maxHeight = Math.min(
+            384,
+            window.innerHeight - rect.bottom - gap - viewportPadding,
+        );
+
+        this.popoverTarget.style.top = `${rect.bottom + gap}px`;
+        this.popoverTarget.style.right = `${window.innerWidth - rect.right}px`;
+        this.popoverTarget.style.left = "auto";
+        this.popoverTarget.style.maxHeight = `${Math.max(maxHeight, 160)}px`;
+    }
+
+    _bindOutsideClick() {
+        this._unbindOutsideClick();
+        this._outsideClickHandler = (event) => {
+            if (!this.element.contains(event.target)) this._close();
+        };
+        // Defer so the opening click doesn't immediately close the popover.
+        setTimeout(() => {
+            document.addEventListener("click", this._outsideClickHandler);
+        }, 0);
+    }
+
+    _unbindOutsideClick() {
+        if (this._outsideClickHandler) {
+            document.removeEventListener("click", this._outsideClickHandler);
+            this._outsideClickHandler = null;
+        }
+    }
+
+    get groupByStorageKey() {
+        return `mensa:group_by:${this.storageKeyValue}`;
+    }
+
+    get aggregatesStorageKey() {
+        return `mensa:aggregates:${this.storageKeyValue}`;
+    }
+
+    _readJson(key) {
+        const raw = this._readStorage(key);
+        if (raw === null) return null;
+        try {
+            return JSON.parse(raw);
+        } catch (e) {
+            return null;
+        }
+    }
+
+    _writeStorage(key, value) {
+        try {
+            window.localStorage.setItem(key, value);
+        } catch (e) {}
+    }
+
+    _readStorage(key) {
+        try {
+            return window.localStorage.getItem(key);
+        } catch (e) {
+            return null;
+        }
+    }
+}

data/app/components/mensa/group_header/component.css

@@ -0,0 +1,39 @@
+.mensa-table {
+    table tbody tr.mensa-table__group-header {
+        @apply bg-gray-50 dark:bg-gray-900 hover:bg-gray-100 dark:hover:bg-gray-700 select-none;
+
+        td {
+            @apply pt-3 pb-2 text-gray-900 dark:text-gray-100;
+        }
+    }
+
+    &__group-header {
+        &__title {
+            @apply flex items-center gap-2;
+        }
+
+        &__toggle {
+            @apply inline-flex w-4 justify-center text-xs text-gray-500 dark:text-gray-400 transition-transform;
+        }
+
+        &[aria-expanded="false"] &__toggle {
+            @apply -rotate-90;
+        }
+
+        &__value {
+            @apply font-semibold;
+        }
+
+        &__count {
+            @apply rounded-full bg-gray-200 dark:bg-gray-700 px-2 py-0.5 text-xs font-medium text-gray-600 dark:text-gray-300;
+        }
+
+        &__aggregate {
+            @apply text-sm font-medium text-gray-700 dark:text-gray-200;
+        }
+
+        &__aggregate-label {
+            @apply mr-1 text-xs font-normal uppercase text-gray-400 dark:text-gray-500;
+        }
+    }
+}

data/app/components/mensa/group_header/component.html.erb

@@ -0,0 +1,34 @@
+<tr class="mensa-table__group-header"
+    data-mensa-groups-target="header"
+    data-group-key="<%= group.key %>"
+    data-action="click->mensa-groups#toggle"
+    aria-expanded="true">
+  <td colspan="<%= leading_cells + title_columns.size %>">
+    <div class="mensa-table__group-header__title">
+      <span class="mensa-table__group-header__toggle"><i class="<%= Mensa.config.icons[:group_toggle] %>"></i></span>
+      <span class="mensa-table__group-header__value"><%= group.title %></span>
+      <% if group.count %>
+        <span class="mensa-table__group-header__count"><%= group.count %></span>
+      <% end %>
+      <% title_columns.select { |column| aggregate?(column) }.each do |column| %>
+        <span class="mensa-table__group-header__aggregate">
+          <span class="mensa-table__group-header__aggregate-label"><%= group.aggregate_label(column) %></span>
+          <%= group.aggregate(column) %>
+        </span>
+      <% end %>
+    </div>
+  </td>
+  <% aggregate_columns.each do |column| %>
+    <td>
+      <% if aggregate?(column) %>
+        <span class="mensa-table__group-header__aggregate">
+          <span class="mensa-table__group-header__aggregate-label"><%= group.aggregate_label(column) %></span>
+          <%= group.aggregate(column) %>
+        </span>
+      <% end %>
+    </td>
+  <% end %>
+  <% if trailing_cells.positive? %>
+    <td></td>
+  <% end %>
+</tr>

data/app/components/mensa/group_header/component.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Mensa
+  module GroupHeader
+    # The header row above each group of rows in a grouped table
+    class Component < ::Mensa::ApplicationComponent
+      attr_reader :table, :group
+
+      def initialize(table:, group:)
+        @table = table
+        @group = group
+      end
+
+      # The cells before the display columns (checkbox, front actions)
+      def leading_cells
+        (table.batch_actions? ? 1 : 0) + ((table.actions? && Mensa.config.row_actions_position == :front) ? 1 : 0)
+      end
+
+      def trailing_cells
+        (table.actions? && Mensa.config.row_actions_position == :back) ? 1 : 0
+      end
+
+      # The title spans the columns up to the first one with an aggregate, so
+      # the aggregates line up with their columns.
+      def title_columns
+        columns = table.display_columns
+        index = columns.index { |column| aggregate?(column) } || columns.size
+        columns.first([index, 1].max)
+      end
+
+      def aggregate_columns
+        table.display_columns.drop(title_columns.size)
+      end
+
+      def aggregate?(column)
+        group.aggregates.key?(column.name)
+      end
+    end
+  end
+end