Merge pull request #23 from sul-dlss/keyboard-a11y

Update markup, styling, and js to have better a11y

Gemfile

@@ -31,6 +31,11 @@ else
       gem 'rails', ENV['RAILS_VERSION']
     end
   end
+
+  case ENV['RAILS_VERSION']
+  when /^5.[12]/, /^6.0/
+    gem 'sass-rails', '~> 5.0'
+  end
 end
 # END ENGINE_CART BLOCK
 eval_gemfile File.expand_path("spec/test_app_templates/Gemfile.extra", File.dirname(__FILE__))

README.md

@@ -83,6 +83,15 @@ Facet fields should be added for each permutation of hierarchy key and term valu
 config.facet_display[:hierarchy].each{ |k,v| puts "#{k}_#{v}" }
 ```
 
+### Overriding the icon
+The icon is available in an engine configuration.  You can change them in an initializer in your app.
+
+```ruby
+Blacklight::Hierarchy::Engine.config.closed_icon = '➕'
+Blacklight::Hierarchy::Engine.config.opened_icon = '➖'
+
+```
+
 ## Caveats
 
 This code was ripped out of another project, and is still quite immature as a standalone project. Every effort has been made to make it as plug-and-play as possible, but it may stomp on Blacklight in unintended ways (e.g., ways that made sense in context of its former host app, but which aren't compatible with generic Blacklight). Proceed with caution, and report issues.

app/assets/javascripts/blacklight/hierarchy/hierarchy.js

@@ -12,23 +12,23 @@ Blacklight.onLoad(function(){
 
   Blacklight.hierarchical_facet_expand_contract = function() {
     var li = $(this);
-    
+
     $('ul', this).each(function() {
       li.addClass('twiddle');
       if($('span.selected', this).length == 0){
         $(this).hide();
       } else {
         li.addClass('twiddle-open');
+        li.children('.toggle-handle').attr('aria-expanded', 'true');
       }
     });
 
     // attach the toggle behavior to the li tag
-    li.click(function(e){
-      if (e.target == this) {
-        // toggle the content
-        $(this).toggleClass('twiddle-open');
-        $(this).children('ul').slideToggle();
-      }
+    li.children('.toggle-handle').click(function(e){
+      // toggle the content
+      $(this).attr('aria-expanded', $(this).attr('aria-expanded') === 'true' ? 'false' : 'true');
+      $(this).parent('li').toggleClass('twiddle-open');
+      $(this).parent('li').children('ul').slideToggle();
     });
   };
 })(jQuery);

app/assets/stylesheets/blacklight/hierarchy/hierarchy.scss

@@ -1,23 +1,63 @@
-$text-muted: #777777 !default;
+$text-muted: #777 !default;
 
 .facet-hierarchy {
-  margin-left: -28px;
+  list-style-type: none;
+  padding-left: 0;
 
   ul {
-    margin-left: 0;
-    border-bottom: none;
+    border-bottom: 0;
+    list-style-type: none;
     padding-bottom: 0;
-    li {
-      margin-left: 8px;
+    padding-left: 1.3em;
+  }
+
+  .facet_select {
+    display: inline-block;
+    margin-bottom: 6px;
+    max-width: calc(100% - 5em);
+  }
+
+  .facet-count {
+    float: right;
+  }
+
+  .toggle-handle {
+    border: 0;
+    margin: 0;
+    min-width: 1em;
+    padding: 0;
+    vertical-align: top;
+
+    .closed,
+    .opened {
+      display: none;
     }
   }
+
+  .twiddle>.toggle-handle .closed {
+    display: inline;
+  }
+
+  .twiddle>.toggle-handle .opened {
+    display: none;
+  }
+
+  .twiddle-open>.toggle-handle .closed {
+    display: none;
+  }
+
+  .twiddle-open>.toggle-handle .opened {
+    display: inline;
+  }
+
+  .h-leaf {
+    padding-left: 1.3em;
+  }
+
   .h-node {
     cursor: pointer;
-    list-style-image: asset_data_url("collapsed.png")
-  }
-  .h-node.twiddle-open {
-    list-style-image: asset_data_url("expanded.png");
   }
+
   .remove {
     color: $text-muted;
   }

app/helpers/blacklight/hierarchy_helper.rb

@@ -7,23 +7,26 @@ def render_facet_hierarchy_item(field_name, data, key)
     subset = data.reject { |k, _v| !k.is_a?(String) }
 
     li_class = subset.empty? ? 'h-leaf' : 'h-node'
+    id = SecureRandom.uuid
     ul = ''
-    li = if item.nil?
-           key
-         elsif facet_in_params?(field_name, item.qvalue)
-           render_selected_qfacet_value(field_name, item)
-         else
-           render_qfacet_value(field_name, item)
-         end
+    li = ''
+    li << facet_toggle_button(field_name, id) if subset.any?
+    li << if item.nil?
+            key
+          elsif facet_in_params?(field_name, item.qvalue)
+            render_selected_qfacet_value(field_name, item)
+          else
+            render_qfacet_value(field_name, item, id: id)
+          end
 
     unless subset.empty?
       subul = subset.keys.sort.collect do |subkey|
         render_facet_hierarchy_item(field_name, subset[subkey], subkey)
       end.join('')
-      ul = "<ul>#{subul}</ul>".html_safe
+      ul = "<ul role=\"group\">#{subul}</ul>".html_safe
     end
 
-    %(<li class="#{li_class}">#{li.html_safe}#{ul.html_safe}</li>).html_safe
+    %(<li class="#{li_class}" role="treeitem">#{li.html_safe}#{ul.html_safe}</li>).html_safe
   end
 
   # @param [Blacklight::Configuration::FacetField] as defined in controller with config.add_facet_field (and with :partial => 'blacklight/hierarchy/facet_hierarchy')
@@ -41,7 +44,8 @@ def render_hierarchy(bl_facet_field, delim = '_')
   end
 
   def render_qfacet_value(facet_solr_field, item, options = {})
-    (link_to_unless(options[:suppress_link], item.value, path_for_facet(facet_solr_field, item.qvalue), class: 'facet_select') + ' ' + render_facet_count(item.hits)).html_safe
+    id = options.delete(:id)
+    (link_to_unless(options[:suppress_link], item.value, path_for_facet(facet_solr_field, item.qvalue), id: id, class: 'facet_select') + ' ' + render_facet_count(item.hits)).html_safe
   end
 
   # Standard display of a SELECTED facet value, no link, special span with class, and 'remove' button.
@@ -100,6 +104,24 @@ def facet_tree(hkey)
     @facet_tree[hkey]
   end
 
+  def facet_toggle_button(field_name, described_by)
+    aria_label = I18n.t(
+      "blacklight.hierarchy.#{field_name}_toggle_aria_label",
+      default: :'blacklight.hierarchy.toggle_aria_label'
+    )
+    <<-HTML
+      <button
+        aria-expanded="false"
+        aria-label="#{aria_label}"
+        aria-describedby="#{described_by}"
+        class="toggle-handle"
+      >
+        <span aria-hidden="true" class="closed">#{Blacklight::Hierarchy::Engine.config.closed_icon}</span>
+        <span aria-hidden="true" class="opened">#{Blacklight::Hierarchy::Engine.config.opened_icon}</span>
+      </button>
+    HTML
+  end
+
   # --------------------------------------------------------------------------------------------------------------------------------
   # below are methods pertaining to the "rotate" notion where you may want to look at the same tree data organized another way
   # --------------------------------------------------------------------------------------------------------------------------------

app/views/blacklight/hierarchy/_facet_hierarchy.html.erb

@@ -1,3 +1,3 @@
-<ul class="facet-hierarchy">
+<ul class="facet-hierarchy" role="tree">
   <%= render_hierarchy(facet_field) %>
 </ul>

blacklight-hierarchy.gemspec

@@ -18,9 +18,10 @@ Gem::Specification.new do |s|
   s.executables   = s.files.grep(%r{^exe/}) { |f| File.basename(f) }
   s.require_paths = ['lib']
 
-  s.add_dependency 'rails', '>= 4.1', '< 6'
+  # Most likely available for even earlier versions of Blacklight, but this is what I validated
+  s.add_dependency 'blacklight', '> 6.20', '< 8.0'
+  s.add_dependency 'rails', '>= 5.1', '< 7'
   s.add_dependency 'jquery-rails'
-  s.add_dependency 'blacklight', '~> 7.0'
 
   s.add_development_dependency 'rsolr'
   s.add_development_dependency 'rspec-rails'

config/locales/blacklight-hierarchy.en.yml

@@ -0,0 +1,4 @@
+en:
+  blacklight:
+    hierarchy:
+      toggle_aria_label: Toggle subgroup

lib/blacklight/hierarchy/engine.rb

@@ -4,6 +4,8 @@
 module Blacklight
   module Hierarchy
     class Engine < Rails::Engine
+      config.closed_icon = '⊞'
+      config.opened_icon = '⊟'
     end
   end
 end

spec/test_app_templates/lib/generators/test_app_generator.rb

@@ -17,4 +17,12 @@ def run_blacklight_generator
   def run_hierarchy_install
     generate 'blacklight_hierarchy:install'
   end
+
+  def create_images_directory
+    run 'mkdir app/assets/images'
+  end
+
+  def add_js_reference
+    inject_into_file 'app/assets/config/manifest.js', "\n//= link application.js", after: '//= link_directory ../stylesheets .css'
+  end
 end