Adds DataTable external sorting mode

Adds sorting: :external, leaving row order to the caller (e.g. SQL
ordering). Sortable headers render plain links built by a required
sort_href_builder proc, which receives the column id and the
direction the link requests next (NONE and DESC cycle to ASC, ASC
to DESC). aria-sort renders exactly as in client mode.

External tables emit no client sort metadata: no data-sort-strategy
on headers, no per-cell sort values, and no toggleSort binding. The
data-table element additionally ignores connect and toggleSort when
the data-external-sorting attribute is present.

Diverges from Primer React, whose externalSorting keeps sort
buttons and an onToggleSort callback; links suit server rendering
and work without JavaScript.

Author: myabc

app/components/primer/open_project/data_table.html.erb

@@ -17,18 +17,13 @@
     </div>
   <% else %>
     <%= render(Primer::BaseComponent.new(**@wrapper_arguments)) do %>
-      <data-table>
+      <data-table<% if external_sorting? %> data-external-sorting=""<% end %>>
         <%= render(Primer::OpenProject::Table.new(**@system_arguments)) do |table| %>
           <% table.with_head(classes: "TableHead") do |thead| %>
             <% thead.with_row(classes: "TableRow") do |tr| %>
               <% headers.each do |header| %>
                 <% if header.sortable? %>
-                  <% tr.with_header(
-                       component_klass: Primer::OpenProject::DataTable::SortHeader,
-                       align: header.column.align,
-                       direction: header.sort_direction,
-                       data: { sort_strategy: header.sort_strategy }
-                     ) { header.column.header.to_s } %>
+                  <% tr.with_header(**sort_header_arguments(header)) { header.column.header.to_s } %>
                 <% else %>
                   <% tr.with_header(classes: "TableHeader", align: header.column.align) { header.column.header.to_s } %>
                 <% end %>

app/components/primer/open_project/data_table.pcss

@@ -18,6 +18,17 @@
     border: 0;
 }
 
+/* External sorting renders the header as a plain link */
+.TableSortLink {
+    color: inherit;
+
+    &:hover,
+    &:focus {
+        color: inherit;
+        text-decoration: none;
+    }
+}
+
 /* Container ---------------------------------------------------------------- */
 .TableContainer {
     display: grid;

app/components/primer/open_project/data_table.rb

@@ -33,6 +33,9 @@ def sort_data
       CELL_PADDING_DEFAULT = :normal
       CELL_PADDING_OPTIONS = [:condensed, CELL_PADDING_DEFAULT, :spacious].freeze
 
+      SORTING_DEFAULT = :client
+      SORTING_OPTIONS = [SORTING_DEFAULT, :external].freeze
+
       TITLE_TAG_DEFAULT = :h2
 
       SUBTITLE_TAG_DEFAULT = :div
@@ -109,6 +112,17 @@ def sort_data
       # @param initial_sort_direction [Symbol, nil]
       #   Sort direction for the initially sorted column.
       #   Options: :ASC, :DESC
+      # @param sorting [Symbol]
+      #   How sorting is performed. `:client` sorts rows in Ruby for the initial
+      #   render and re-sorts in the browser. `:external` leaves row order to the
+      #   caller (e.g. SQL ordering): sortable headers become links built by
+      #   `sort_href_builder`, and `initial_sort_column`/`initial_sort_direction`
+      #   only drive the rendered sort state.
+      #   Options: :client, :external
+      # @param sort_href_builder [Proc, nil]
+      #   `->(column_id, direction)` returning the URL a sortable header links to,
+      #   where `direction` is the direction the link requests next. Required when
+      #   `sorting: :external` and any column is sortable.
       # @param divider [Boolean]
       #   Whether to render a presentational divider line below the title row,
       #   ported from Primer React's `Table.Divider`
@@ -130,6 +144,8 @@ def initialize(
         cell_padding: CELL_PADDING_DEFAULT,
         initial_sort_column: nil,
         initial_sort_direction: nil,
+        sorting: SORTING_DEFAULT,
+        sort_href_builder: nil,
         divider: false,
         row_id: nil,
         row_dom_id: false,
@@ -140,6 +156,8 @@ def initialize(
         @cell_padding = fetch_or_fallback(CELL_PADDING_OPTIONS, cell_padding, CELL_PADDING_DEFAULT)
         @initial_sort_column = initial_sort_column
         @initial_sort_direction = initial_sort_direction
+        @sorting = fetch_or_fallback(SORTING_OPTIONS, sorting, SORTING_DEFAULT)
+        @sort_href_builder = sort_href_builder
         @divider = fetch_or_fallback_boolean(divider, false)
         @row_id_proc = row_id
         @row_dom_id = fetch_or_fallback_boolean(row_dom_id, false)
@@ -169,6 +187,10 @@ def render?
       def before_render
         return unless render?
 
+        if external_sorting? && @sort_href_builder.nil? && columns.any?(&:sortable?)
+          raise ArgumentError, "`sorting: :external` requires a `sort_href_builder` when columns are sortable"
+        end
+
         @initial_sort_state = build_initial_sort_state
         @headers = build_headers
         @rows = sorted_rows
@@ -249,6 +271,7 @@ def build_headers
       end
 
       def sorted_rows
+        return @rows if external_sorting?
         return @rows unless @initial_sort_state
 
         Sorting.sort_rows(
@@ -258,6 +281,30 @@ def sorted_rows
         )
       end
 
+      def external_sorting?
+        @sorting == :external
+      end
+
+      def next_direction_for(header)
+        header.sort_direction == :ASC ? :DESC : :ASC
+      end
+
+      def sort_header_arguments(header)
+        arguments = {
+          component_klass: Primer::OpenProject::DataTable::SortHeader,
+          align: header.column.align,
+          direction: header.sort_direction
+        }
+
+        if external_sorting?
+          arguments[:href] = @sort_href_builder.call(header.id, next_direction_for(header))
+        else
+          arguments[:data] = { sort_strategy: header.sort_strategy }
+        end
+
+        arguments
+      end
+
       def grid_template_from_columns(columns)
         columns.map do |column|
           column_width = column.width || :grow
@@ -321,7 +368,7 @@ def cell_content(cell, row)
 
       def cells_for(row)
         headers.map do |header|
-          sort_metadata = header.sortable? ? header.column.sort_metadata(row) : {}
+          sort_metadata = header.sortable? && !external_sorting? ? header.column.sort_metadata(row) : {}
 
           Cell.new(
             column: header.column,

app/components/primer/open_project/data_table/sort_header.html.erb

@@ -1,12 +1,5 @@
 <%= render(Primer::OpenProject::Table::Header.new(**@system_arguments)) do %>
-  <%=
-    render(
-      Primer::Beta::BaseButton.new(
-        classes: "TableSortButton",
-        data: { action: "click:data-table#toggleSort" }
-      )
-    ) do
-  %>
+  <%= render(sort_control) do %>
     <%= content %>
     <%=
       render(

app/components/primer/open_project/data_table/sort_header.rb

@@ -15,10 +15,14 @@ class SortHeader < Primer::Component
 
         # @param direction [Symbol] select [:ASC, :DESC, :NONE]
         #   Specify the sort direction for the header.
+        # @param href [String, nil]
+        #   When given, the header renders a plain sort link to this URL instead
+        #   of the client-side sort button (used for external sorting).
         # @param system_arguments [Hash]
         #   System arguments passed to the root element
-        def initialize(direction: DEFAULT_DIRECTION, **system_arguments)
+        def initialize(direction: DEFAULT_DIRECTION, href: nil, **system_arguments)
           @direction = fetch_or_fallback(DIRECTION_OPTIONS, direction, DEFAULT_DIRECTION)
+          @href = href
           aria_sort = ARIA_SORT_OPTIONS.fetch(@direction, nil)
 
           @system_arguments = system_arguments
@@ -30,6 +34,23 @@ def initialize(direction: DEFAULT_DIRECTION, **system_arguments)
             @system_arguments, { aria: { sort: aria_sort } }
           )
         end
+
+        private
+
+        def sort_control
+          if @href
+            Primer::Beta::Link.new(
+              href: @href,
+              muted: true,
+              classes: "TableSortButton TableSortLink"
+            )
+          else
+            Primer::Beta::BaseButton.new(
+              classes: "TableSortButton",
+              data: { action: "click:data-table#toggleSort" }
+            )
+          end
+        end
       end
     end
   end

app/components/primer/open_project/data_table_element.ts

@@ -16,11 +16,15 @@ const DEFAULT_SORT_DIRECTION = SortDirection.ASC
 @controller('data-table')
 export class DataTableElement extends HTMLElement {
   connectedCallback() {
+    if (this.externalSorting) return
+
     sortTableByAriaSort(this.table)
     updateSortIcons(this.table)
   }
 
   toggleSort(event: MouseEvent) {
+    if (this.externalSorting) return
+
     const header = (event.target as Element).closest('th')!
     const direction = getSortDirection(header)
     const nextDirection =
@@ -45,6 +49,10 @@ export class DataTableElement extends HTMLElement {
   get table(): HTMLTableElement {
     return this.querySelector('table')!
   }
+
+  get externalSorting(): boolean {
+    return this.hasAttribute('data-external-sorting')
+  }
 }
 
 function resetSort(th: HTMLElement) {

previews/primer/open_project/data_table_preview.rb

@@ -76,6 +76,22 @@ def with_cell_placeholder
         render_with_template(locals: { rows: rows })
       end
 
+      # @label With External Sorting
+      # @snapshot
+      # @param sort_column [Symbol] select [name, status_code, created_at]
+      # @param sort_direction [Symbol] select [ASC, DESC]
+      def with_external_sorting(sort_column: :name, sort_direction: :ASC)
+        column = sort_column.to_sym
+        direction = sort_direction.to_s.upcase == "DESC" ? :DESC : :ASC
+
+        rows = sample_rows.sort_by { |row| row.public_send(column).to_s } # rubocop:disable GitHub/AvoidObjectSendWithDynamicMethod
+        rows.reverse! if direction == :DESC
+
+        render_with_template(
+          locals: { rows: rows, sort_column: column, sort_direction: direction }
+        )
+      end
+
       # @label With Pagination
       # @snapshot
       # @param page [Integer] number

previews/primer/open_project/data_table_preview/with_external_sorting.html.erb

@@ -0,0 +1,20 @@
+<%=
+  render(
+    Primer::OpenProject::DataTable.new(
+      rows,
+      sorting: :external,
+      initial_sort_column: sort_column,
+      initial_sort_direction: sort_direction,
+      sort_href_builder: ->(column_id, direction) { "?sort_column=#{column_id}&sort_direction=#{direction}" }
+    )
+  ) do |data_table|
+    data_table.with_title(tag: :h2) { "Projects" }
+    data_table.with_subtitle { "The server owns the sort order; headers are plain links (Preview-only: links round-trip via preview params)." }
+
+    data_table.with_column(field: :name, header: "Name", row_header: true, sort_by: true)
+    data_table.with_column(field: :status_code, header: "Status", sort_by: true)
+    data_table.with_column(field: :created_at, header: "Created", align: :end, sort_by: true) do |column|
+      column.with_cell { |row| row.created_at.strftime("%Y-%m-%d") }
+    end
+  end
+%>

static/arguments.json

@@ -6088,6 +6088,18 @@
         "default": "`nil`",
         "description": "Sort direction for the initially sorted column. Options: :ASC, :DESC"
       },
+      {
+        "name": "sorting",
+        "type": "Symbol",
+        "default": "`:client`",
+        "description": "How sorting is performed. `:client` sorts rows in Ruby for the initial render and re-sorts in the browser. `:external` leaves row order to the caller (e.g. SQL ordering): sortable headers become links built by `sort_href_builder`, and `initial_sort_column`/`initial_sort_direction` only drive the rendered sort state. Options: :client, :external"
+      },
+      {
+        "name": "sort_href_builder",
+        "type": "Proc, nil",
+        "default": "`nil`",
+        "description": "`->(column_id, direction)` returning the URL a sortable header links to, where `direction` is the direction the link requests next. Required when `sorting: :external` and any column is sortable."
+      },
       {
         "name": "divider",
         "type": "Boolean",
@@ -6306,6 +6318,12 @@
         "default": "`:ASC`",
         "description": "select [:ASC, :DESC, :NONE] Specify the sort direction for the header."
       },
+      {
+        "name": "href",
+        "type": "String, nil",
+        "default": "`nil`",
+        "description": "When given, the header renders a plain sort link to this URL instead of the client-side sort button (used for external sorting)."
+      },
       {
         "name": "system_arguments",
         "type": "Hash",

static/constants.json

@@ -1780,6 +1780,11 @@
     "GeneratedSlotMethods": "Primer::OpenProject::DataTable::GeneratedSlotMethods",
     "Header": "Primer::OpenProject::DataTable::Header",
     "PaginationFooter": "Primer::OpenProject::DataTable::PaginationFooter",
+    "SORTING_DEFAULT": "client",
+    "SORTING_OPTIONS": [
+      "client",
+      "external"
+    ],
     "SUBTITLE_TAG_DEFAULT": "div",
     "SUBTITLE_TAG_OPTIONS": [
       "div",