sdr_view_components 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9de1e10f3e04a4a00b584e85fa5b06d862916a2e403e7ab3966020e04ec3deb0
-  data.tar.gz: 2df79a660409c1bed817b6823d81c6718d052026434611757f3883604b5d9411
+  metadata.gz: 1368eefb0da795ca19eb50623c50573654bc681bd419cd4f250a759aa1c969d9
+  data.tar.gz: 61d17dbefaeca0a568b845c2fc9872df5a484496cd1b9b07b18961e9d870afb5
 SHA512:
-  metadata.gz: 94cd03e80e3fdca7e03e83456141569c53d888ec7a3ace284a6a0a9ceca187ae76471b859d3d5d3696b6311dbaa603e70f0516d4173532565cfd2ea81c6b306b
-  data.tar.gz: 31b2838609b00ac1171421cf4481e82c6db92695309e38687cff917f2c585b983f60c2e7dda7500b496e31b38465e2c02f8f5876cb15480e983c8bdc30342e51
+  metadata.gz: d504ffc348734b15f10d607a2396f02e74e57922d3360ffd4b7c411b49156e1e5b1279997c21d1721bb1338c8a5ea18cfce4da7ee6995e27472cd5c3f466be6a
+  data.tar.gz: 59983cc56c2abfb208d2bfe3a05d5ff6656c93cdbb4e2c1ce9c9e8b54b7393ce2637b428703b4305aebbcacc249edadf3a14387849c9718db19a060668e59dde

data/README.md

@@ -96,6 +96,19 @@ import TabOverflowController from "sdr_view_components/tab_overflow_controller"
 application.register("sdr-tab-overflow", TabOverflowController)
 ```
 
+`SdrViewComponents::Tables::TreegridTableComponent` (see [Treegrid table component](#treegrid-table-component) below) ships `sdr_view_components/treegrid_controller`, registered as `sdr-treegrid`:
+
+```ruby
+pin "sdr_view_components/treegrid_controller", to: "sdr_view_components/treegrid_controller.js"
+```
+
+```javascript
+import { application } from "controllers/application"
+import TreegridController from "sdr_view_components/treegrid_controller"
+
+application.register("sdr-treegrid", TreegridController)
+```
+
 ## Usage
 
 ### Form components
@@ -250,6 +263,24 @@ Instead of `heading:`, the heading can be provided with the `heading_content` sl
 <% end %>
 ```
 
+### Treegrid table component
+
+`SdrViewComponents::Tables::TreegridTableComponent` renders files as an [ARIA treegrid](https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/): a row for each file, preceded by a collapsible row for each folder in its path, with Expand all / Collapse all controls when there are folders. Provide files in path order (each folder's files before its subfolders), with the `path_parts` of each file's folder. It requires the `sdr-treegrid` controller (see [JavaScript](#javascript) above).
+
+Folders are expanded unless `collapsed: true` is given. With `remember_expanded: true` (which requires an `id:`), folders the user expands or collapses stay so when the table is rendered again on the same page, e.g., when its turbo frame reloads. Enter on a file row activates the element in the row marked `data-sdr-treegrid-target="fileAction"`, if any.
+
+```erb
+<%= render SdrViewComponents::Tables::TreegridTableComponent.new(label: 'Files', id: 'files', collapsed: true) do |component| %>
+  <% component.with_header(label: 'File/folder name') %>
+  <% component.with_header(label: 'Size') %>
+  <% files.each do |file| %>
+    <% component.with_file(path_parts: file.path_parts, label: file.filename) do |row| %>
+      <% row.with_cell { number_to_human_size(file.size) } %>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
 ### Navigation components
 
 SdrViewComponents provides components for building navigation bar items and dropdown menus:

data/app/assets/sdr_view_components.css

@@ -216,6 +216,26 @@ table.table-data th {
   white-space: nowrap;
 }
 
+/* Treegrid tables */
+table.table-treegrid tr[data-sdr-treegrid-role="folder"] {
+  cursor: pointer;
+}
+
+table.table-treegrid .treegrid-name {
+  overflow-wrap: anywhere;
+}
+
+.treegrid-folder-icon {
+  display: inline-block;
+  margin-right: 0.25rem;
+  color: var(--bs-link-color);
+  transition: transform 0.2s ease-in-out;
+}
+
+table.table-treegrid tr[aria-expanded="false"] .treegrid-folder-icon {
+  transform: rotate(180deg);
+}
+
 /* Radio buttons */
 
 /* Inputs / labels are rendered in the opposite order than BS styles expect. */

data/app/components/sdr_view_components/tables/treegrid_expand_collapse_row_component.html.erb

@@ -0,0 +1,7 @@
+<tr class="treegrid-controls">
+  <%= tag.td colspan: do %>
+    <button type="button" class="btn btn-link p-0" data-action="sdr-treegrid#expandAll">Expand all</button>
+    <span aria-hidden="true">|</span>
+    <button type="button" class="btn btn-link p-0" data-action="sdr-treegrid#collapseAll">Collapse all</button>
+  <% end %>
+</tr>

data/app/components/sdr_view_components/tables/treegrid_expand_collapse_row_component.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module Tables
+    # Component for rendering the Expand all / Collapse all row of a treegrid table.
+    class TreegridExpandCollapseRowComponent < BaseComponent
+      def initialize(colspan:)
+        @colspan = colspan
+        super()
+      end
+
+      attr_reader :colspan
+    end
+  end
+end

data/app/components/sdr_view_components/tables/treegrid_file_row_component.html.erb

@@ -0,0 +1,9 @@
+<%= tag.tr role: 'row', tabindex: -1, hidden: hidden?, aria: { level: }, data: { sdr_treegrid_role: 'file' },
+           **row_options do %>
+  <%= tag.th scope: 'row', role: 'rowheader', class: 'treegrid-name fw-normal', style: indent_style do %>
+    <%= label || label_content %>
+  <% end %>
+  <% cells.each do |cell| %>
+    <%= cell %>
+  <% end %>
+<% end %>

data/app/components/sdr_view_components/tables/treegrid_file_row_component.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module Tables
+    # Component for rendering a file row of a treegrid table.
+    # Within the row, the element with data-sdr-treegrid-target="fileAction" (if any) is activated by Enter.
+    class TreegridFileRowComponent < TreegridRowComponent
+      renders_one :label_content
+      renders_many :cells, SdrViewComponents::Tables::CellComponent
+
+      # @param path_parts [Array<String>] the path of the file's folder (e.g., ['folder1', 'subfolder'])
+      # @param label [String] the file name; alternatively, provide label_content
+      def initialize(path_parts: [], label: nil, hidden: false, **row_options)
+        @label = label
+        @row_options = row_options
+        super(path_parts:, hidden:)
+      end
+
+      attr_reader :label, :row_options
+
+      def level
+        path_parts.size + 1
+      end
+    end
+  end
+end

data/app/components/sdr_view_components/tables/treegrid_folder_row_component.html.erb

@@ -0,0 +1,11 @@
+<%= tag.tr role: 'row', tabindex: -1, hidden: hidden?,
+           aria: { level:, expanded: expanded?.to_s },
+           data: { sdr_treegrid_role: 'folder', sdr_treegrid_key: key, action: 'click->sdr-treegrid#toggle' } do %>
+  <%= tag.th scope: 'row', role: 'rowheader', class: 'treegrid-name', style: indent_style do %>
+    <%= helpers.icon(icon_classes: 'bi bi-chevron-up', classes: 'treegrid-folder-icon', aria: { hidden: true }) %>
+    <span class="fw-bold"><%= label %></span>
+  <% end %>
+  <% empty_cells.times do %>
+    <td></td>
+  <% end %>
+<% end %>

data/app/components/sdr_view_components/tables/treegrid_folder_row_component.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module Tables
+    # Component for rendering a folder row of a treegrid table.
+    class TreegridFolderRowComponent < TreegridRowComponent
+      # @param path_parts [Array<String>] the folder's path (e.g., ['folder1', 'subfolder'])
+      # @param empty_cells [Integer] the number of empty cells following the folder name
+      def initialize(path_parts:, expanded:, empty_cells:, hidden: false)
+        @expanded = expanded
+        @empty_cells = empty_cells
+        super(path_parts:, hidden:)
+      end
+
+      attr_reader :empty_cells
+
+      def expanded?
+        @expanded
+      end
+
+      def level
+        path_parts.size
+      end
+
+      def label
+        path_parts.last
+      end
+
+      # Identifies the folder when the table is rendered again.
+      def key
+        path_parts.join('/')
+      end
+    end
+  end
+end

data/app/components/sdr_view_components/tables/treegrid_row_component.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module Tables
+    # Base component for the folder and file rows of a treegrid table.
+    class TreegridRowComponent < BaseComponent
+      def initialize(path_parts:, hidden: false)
+        @path_parts = path_parts
+        @hidden = hidden
+        super()
+      end
+
+      attr_reader :path_parts
+
+      def hidden?
+        @hidden
+      end
+
+      # Subclasses must provide level (the row's depth in the tree, starting at 1).
+      def indent_style
+        "padding-left: #{((level - 1) * 1.25) + 0.5}rem;"
+      end
+    end
+  end
+end

data/app/components/sdr_view_components/tables/treegrid_table_component.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module Tables
+    # Component for rendering files as a treegrid table, with a collapsible row for each folder in their paths.
+    # Requires the sdr-treegrid Stimulus controller.
+    class TreegridTableComponent < BaseTableComponent
+      # Files must be provided in path order, so that each folder's files and subfolders follow its row.
+      renders_many :files, lambda { |path_parts: [], **args|
+        TreegridFileRowComponent.new(path_parts:, hidden: collapsed? && path_parts.any?, **args)
+      }
+
+      # @param collapsed [Boolean] whether folders are initially collapsed
+      # @param remember_expanded [Boolean] whether folders the user expands or collapses stay so when the table
+      #   is rendered again (e.g., when its turbo frame reloads); requires an id
+      def initialize(collapsed: false, remember_expanded: false, classes: [], data: {}, **args)
+        raise ArgumentError, 'remember_expanded requires an id' if remember_expanded && args[:id].blank?
+
+        @collapsed = collapsed
+        super(classes: merge_classes('table-treegrid', classes),
+              role: 'treegrid',
+              data: data.merge(controller: merge_classes('sdr-treegrid', data[:controller]),
+                               action: merge_actions('keydown->sdr-treegrid#navigate', data[:action]),
+                               sdr_treegrid_remember_expanded_value: remember_expanded),
+              **args)
+      end
+
+      def collapsed?
+        @collapsed
+      end
+
+      def rows?
+        files?
+      end
+
+      # Folder rows are inserted before the first file in each folder.
+      def rows
+        @rows ||= [expand_collapse_row, *file_and_folder_rows].compact
+      end
+
+      private
+
+      def file_and_folder_rows
+        last_path_parts = []
+        files.flat_map do |file|
+          folder_rows = new_folder_path_parts(last_path_parts:, path_parts: file.path_parts).map do |folder_path_parts|
+            folder_row(folder_path_parts)
+          end
+          last_path_parts = file.path_parts
+          [*folder_rows, file]
+        end
+      end
+
+      # @return [Array<Array<String>>] the path parts of each folder in path_parts that is not in last_path_parts
+      def new_folder_path_parts(last_path_parts:, path_parts:)
+        matching_count = path_parts.zip(last_path_parts).take_while { |part, last_part| part == last_part }.size
+        (matching_count...path_parts.size).map { |index| path_parts[0..index] }
+      end
+
+      def folder_row(folder_path_parts)
+        render TreegridFolderRowComponent.new(path_parts: folder_path_parts,
+                                              expanded: !collapsed?,
+                                              hidden: collapsed? && folder_path_parts.size > 1,
+                                              empty_cells: column_count - 1)
+      end
+
+      def expand_collapse_row
+        return if files.none? { |file| file.path_parts.any? }
+
+        render TreegridExpandCollapseRowComponent.new(colspan: column_count)
+      end
+
+      def column_count
+        [headers.size, 1].max
+      end
+    end
+  end
+end

data/app/javascript/sdr_view_components/treegrid_controller.js

@@ -0,0 +1,193 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Expanded state of the folders that users have toggled, by table id then folder key, kept across renders.
+const expandedByTable = new Map()
+
+// Expands and collapses the folder rows of a treegrid table (TreegridTableComponent),
+// with keyboard navigation per https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/
+// Only one row (the last focused) is in the tab order.
+export default class extends Controller {
+  static targets = ["fileAction"]
+  static values = { rememberExpanded: Boolean }
+
+  connect() {
+    if (this.rememberExpandedValue) this.restoreExpanded()
+    this.element.addEventListener("focusin", this.focusRow)
+    this.setTabbableRow(this.visibleRows()[0])
+  }
+
+  disconnect() {
+    this.element.removeEventListener("focusin", this.focusRow)
+  }
+
+  focusRow = (event) => {
+    if (this.isTreeRow(event.target)) this.setTabbableRow(event.target)
+  }
+
+  setTabbableRow(row) {
+    if (!row) return
+
+    this.element.querySelectorAll(':scope > tbody > tr[tabindex="0"]').forEach((other) => { other.tabIndex = -1 })
+    row.tabIndex = 0
+  }
+
+  toggle(event) {
+    this.toggleFolder(event.target.closest("tr"))
+  }
+
+  expandAll(event) {
+    event.preventDefault()
+    this.folderRows().forEach((row) => {
+      if (!this.isOpenFolder(row)) this.toggleFolder(row)
+    })
+  }
+
+  collapseAll(event) {
+    event.preventDefault()
+    this.folderRows().forEach((row) => {
+      if (this.isOpenFolder(row)) this.toggleFolder(row)
+    })
+  }
+
+  navigate(event) {
+    const row = event.target
+    if (!this.isTreeRow(row)) return
+
+    const target = this.navigationTarget(event.key, row)
+    if (target === undefined) return
+
+    event.preventDefault()
+    if (typeof target === "function") {
+      target()
+    } else {
+      target?.focus()
+    }
+  }
+
+  // @return [Function, Element, null, undefined] an action or the row to focus; undefined if the key isn't handled
+  navigationTarget(key, row) {
+    switch (key) {
+      case "Enter":
+        if (this.isFolder(row)) return () => this.toggleFolder(row)
+        return this.fileAction(row) ? () => this.fileAction(row).click() : undefined
+      case "ArrowRight":
+        if (!this.isFolder(row)) return undefined
+        return this.isOpenFolder(row) ? this.nextVisibleRow(row) : () => this.toggleFolder(row)
+      case "ArrowLeft":
+        if (this.isOpenFolder(row)) return () => this.toggleFolder(row)
+        return this.level(row) > 1 ? this.parentRow(row) : undefined
+      case "ArrowUp":
+        return this.previousVisibleRow(row)
+      case "ArrowDown":
+        return this.nextVisibleRow(row)
+      case "Home":
+        return this.visibleRows()[0]
+      case "End":
+        return this.visibleRows().at(-1)
+      default:
+        return undefined
+    }
+  }
+
+  toggleFolder(row) {
+    const expand = !this.isOpenFolder(row)
+    row.setAttribute("aria-expanded", expand)
+    if (this.rememberExpandedValue) this.expandedFolders().set(row.dataset.sdrTreegridKey, expand)
+
+    if (expand) {
+      this.showDescendantRows(row)
+    } else {
+      const descendants = this.descendantRows(row)
+      descendants.forEach((descendant) => { descendant.hidden = true })
+      // Keeps a row in the tab order when the tabbable row is hidden.
+      if (descendants.some((descendant) => descendant.tabIndex === 0)) this.setTabbableRow(row)
+    }
+  }
+
+  // Shows the descendants of an expanded folder, except those within collapsed subfolders.
+  showDescendantRows(row) {
+    let collapsedLevel = null
+    this.descendantRows(row).forEach((descendant) => {
+      if (collapsedLevel !== null && this.level(descendant) > collapsedLevel) return
+
+      descendant.hidden = false
+      collapsedLevel = this.isFolder(descendant) && !this.isOpenFolder(descendant) ? this.level(descendant) : null
+    })
+  }
+
+  // Rows are in tree order, so a folder within a collapsed folder is only marked expanded.
+  restoreExpanded() {
+    this.folderRows().forEach((row) => {
+      const expanded = this.expandedFolders().get(row.dataset.sdrTreegridKey)
+      if (expanded === undefined || expanded === this.isOpenFolder(row)) return
+
+      if (expanded && row.hidden) {
+        row.setAttribute("aria-expanded", true)
+      } else {
+        this.toggleFolder(row)
+      }
+    })
+  }
+
+  expandedFolders() {
+    if (!expandedByTable.has(this.element.id)) expandedByTable.set(this.element.id, new Map())
+    return expandedByTable.get(this.element.id)
+  }
+
+  descendantRows(row) {
+    const descendants = []
+    let sibling = row.nextElementSibling
+    while (sibling && this.isTreeRow(sibling) && this.level(sibling) > this.level(row)) {
+      descendants.push(sibling)
+      sibling = sibling.nextElementSibling
+    }
+    return descendants
+  }
+
+  parentRow(row) {
+    let sibling = row.previousElementSibling
+    while (sibling && this.isTreeRow(sibling)) {
+      if (this.level(sibling) === this.level(row) - 1) return sibling
+      sibling = sibling.previousElementSibling
+    }
+    return null
+  }
+
+  nextVisibleRow(row) {
+    const rows = this.visibleRows()
+    return rows[rows.indexOf(row) + 1] || null
+  }
+
+  previousVisibleRow(row) {
+    const rows = this.visibleRows()
+    return rows[rows.indexOf(row) - 1] || null
+  }
+
+  visibleRows() {
+    return Array.from(this.element.querySelectorAll(":scope > tbody > tr[aria-level]:not([hidden])"))
+  }
+
+  folderRows() {
+    return this.element.querySelectorAll(':scope > tbody > tr[data-sdr-treegrid-role="folder"]')
+  }
+
+  fileAction(row) {
+    return this.fileActionTargets.find((target) => row.contains(target))
+  }
+
+  isTreeRow(element) {
+    return element.matches("tr[aria-level]")
+  }
+
+  isFolder(row) {
+    return row.dataset.sdrTreegridRole === "folder"
+  }
+
+  isOpenFolder(row) {
+    return this.isFolder(row) && row.getAttribute("aria-expanded") === "true"
+  }
+
+  level(row) {
+    return Number(row.getAttribute("aria-level"))
+  }
+}

data/lib/sdr_view_components/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SdrViewComponents
-  VERSION = '0.21.0'
+  VERSION = '0.22.0'
 end

data/spec/components/previews/sdr_view_components/tables/treegrid_table_component_preview/default.html.erb

@@ -0,0 +1,10 @@
+<%= render(SdrViewComponents::Tables::TreegridTableComponent.new(label: 'Files', id: 'preview-files', collapsed:,
+                                                                 remember_expanded: true)) do |component| %>
+  <% component.with_header(label: 'File/folder name') %>
+  <% component.with_header(label: 'Size') %>
+  <% files.each do |file| %>
+    <% component.with_file(path_parts: file[:path_parts], label: file[:label]) do |row| %>
+      <% row.with_cell { file[:size] } %>
+    <% end %>
+  <% end %>
+<% end %>

data/spec/components/previews/sdr_view_components/tables/treegrid_table_component_preview.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module Tables
+    class TreegridTableComponentPreview < ViewComponent::Preview
+      FILES = [
+        { path_parts: [], label: 'README.txt', size: '1 KB' },
+        { path_parts: %w[images], label: 'image1.tif', size: '10 MB' },
+        { path_parts: %w[images], label: 'image2.tif', size: '12 MB' },
+        { path_parts: %w[images thumbnails], label: 'image1.jpg', size: '20 KB' },
+        { path_parts: %w[data], label: 'data.csv', size: '3 MB' }
+      ].freeze
+
+      def default
+        render_with_template(locals: { files: FILES, collapsed: false })
+      end
+
+      def collapsed
+        render_with_template(template: 'sdr_view_components/tables/treegrid_table_component_preview/default',
+                             locals: { files: FILES, collapsed: true })
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sdr_view_components
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Aaron Collier
@@ -180,6 +180,14 @@ files:
 - app/components/sdr_view_components/tables/row_component.html.erb
 - app/components/sdr_view_components/tables/row_component.rb
 - app/components/sdr_view_components/tables/table_component.rb
+- app/components/sdr_view_components/tables/treegrid_expand_collapse_row_component.html.erb
+- app/components/sdr_view_components/tables/treegrid_expand_collapse_row_component.rb
+- app/components/sdr_view_components/tables/treegrid_file_row_component.html.erb
+- app/components/sdr_view_components/tables/treegrid_file_row_component.rb
+- app/components/sdr_view_components/tables/treegrid_folder_row_component.html.erb
+- app/components/sdr_view_components/tables/treegrid_folder_row_component.rb
+- app/components/sdr_view_components/tables/treegrid_row_component.rb
+- app/components/sdr_view_components/tables/treegrid_table_component.rb
 - app/javascript/sdr_view_components/lookbook.js
 - app/javascript/sdr_view_components/tab_error_controller.js
 - app/javascript/sdr_view_components/tab_link_controller.js
@@ -187,6 +195,7 @@ files:
 - app/javascript/sdr_view_components/tab_overflow_controller.js
 - app/javascript/sdr_view_components/tab_select_controller.js
 - app/javascript/sdr_view_components/toast_controller.js
+- app/javascript/sdr_view_components/treegrid_controller.js
 - app/views/layouts/lookbook.html.erb
 - config/routes.rb
 - lib/sdr_view_components.rb
@@ -368,6 +377,8 @@ files:
 - spec/components/previews/sdr_view_components/tables/row_component_preview/with_value.html.erb
 - spec/components/previews/sdr_view_components/tables/row_component_preview/with_values.html.erb
 - spec/components/previews/sdr_view_components/tables/table_component_preview.rb
+- spec/components/previews/sdr_view_components/tables/treegrid_table_component_preview.rb
+- spec/components/previews/sdr_view_components/tables/treegrid_table_component_preview/default.html.erb
 homepage: https://github.com/sul-dlss/sdr_view_components
 licenses: []
 metadata: