Merge pull request #3180 from salesforce-ux/feat/dueling-picklist-gro…

…up-label Feat(dueling picklist) Add a group label
salesforce-ux · Apr 2, 2018 · b5e0083 · b5e0083
2 parents f6a66d9 + fe3d668
commit b5e0083
Show file tree

Hide file tree

Showing 16 changed files with 195 additions and 23 deletions.
diff --git a/...cklist/__tests__/__snapshots__/renders_a_default_dueling_picklist_with_no_reordering.json b/...cklist/__tests__/__snapshots__/renders_a_default_dueling_picklist_with_no_reordering.json
diff --git a/...ponents/dueling-picklist/__tests__/__snapshots__/renders_a_disabled_dueling_picklist.json b/...ponents/dueling-picklist/__tests__/__snapshots__/renders_a_disabled_dueling_picklist.json
diff --git a/...ng-picklist/__tests__/__snapshots__/renders_a_dueling_picklist_with_a_dropped_option.json b/...ng-picklist/__tests__/__snapshots__/renders_a_dueling_picklist_with_a_dropped_option.json
diff --git a/...ng-picklist/__tests__/__snapshots__/renders_a_dueling_picklist_with_a_grabbed_option.json b/...ng-picklist/__tests__/__snapshots__/renders_a_dueling_picklist_with_a_grabbed_option.json
diff --git a/...eling-picklist/__tests__/__snapshots__/renders_a_dueling_picklist_with_a_group_label.json b/...eling-picklist/__tests__/__snapshots__/renders_a_dueling_picklist_with_a_group_label.json
diff --git a/...g-picklist/__tests__/__snapshots__/renders_a_dueling_picklist_with_a_required_option.json b/...g-picklist/__tests__/__snapshots__/renders_a_dueling_picklist_with_a_required_option.json
diff --git a/...g-picklist/__tests__/__snapshots__/renders_a_dueling_picklist_with_a_selected_option.json b/...g-picklist/__tests__/__snapshots__/renders_a_dueling_picklist_with_a_selected_option.json
diff --git a/...ist/__tests__/__snapshots__/renders_a_dueling_picklist_with_an_option_that_was_moved.json b/...ist/__tests__/__snapshots__/renders_a_dueling_picklist_with_an_option_that_was_moved.json
diff --git a/...snapshots__/renders_a_dueling_picklist_with_an_option_that_was_moved_to_another_list.json b/...snapshots__/renders_a_dueling_picklist_with_an_option_that_was_moved_to_another_list.json
diff --git a/...st/__tests__/__snapshots__/renders_a_dueling_picklist_with_multiple_selected_options.json b/...st/__tests__/__snapshots__/renders_a_dueling_picklist_with_multiple_selected_options.json
diff --git a/...nents/dueling-picklist/__tests__/__snapshots__/renders_a_responsive_dueling_picklist.json b/...nents/dueling-picklist/__tests__/__snapshots__/renders_a_responsive_dueling_picklist.json
diff --git a/...cklist/__tests__/__snapshots__/renders_a_responsive_non_reorderable_dueling_picklist.json b/...cklist/__tests__/__snapshots__/renders_a_responsive_non_reorderable_dueling_picklist.json
diff --git a/ui/components/dueling-picklist/__tests__/index.spec.js b/ui/components/dueling-picklist/__tests__/index.spec.js
@@ -4,6 +4,7 @@ import React from 'react';
 import {
   MultiSelect,
   DefaultSnapShot,
+  GroupLabelSnapShot,
   LockedSnapShot,
   DisabledSnapShot,
   SelectedSnapShot,
@@ -22,6 +23,9 @@ const { matchesMarkupAndStyle } = createHelpers(__dirname);
 it('renders a default dueling picklist', () =>
   matchesMarkupAndStyle(<MultiSelect dataSet={DefaultSnapShot} />));
 
+it('renders a dueling picklist with a group label', () =>
+  matchesMarkupAndStyle(<MultiSelect dataSet={GroupLabelSnapShot} />));
+
 it('renders a default dueling picklist with no reordering', () =>
   matchesMarkupAndStyle(<MultiSelect dataSet={DefaultSnapShot} noReorder />));
 

diff --git a/ui/components/dueling-picklist/base/example.jsx b/ui/components/dueling-picklist/base/example.jsx
@@ -5,6 +5,7 @@ import React from 'react';
 import {
   MultiSelect,
   DefaultSnapShot,
+  GroupLabelSnapShot,
   LockedSnapShot,
   DisabledSnapShot,
   SelectedSnapShot,
@@ -22,6 +23,11 @@ import {
 export default <MultiSelect dataSet={DefaultSnapShot} />;
 
 export let states = [
+  {
+    id: 'group-label-dueling-picklist',
+    label: 'Group Label',
+    element: <MultiSelect dataSet={GroupLabelSnapShot} />
+  },
   {
     id: 'required-dueling-picklist',
     label: 'Locked',

diff --git a/ui/components/dueling-picklist/docs.mdx b/ui/components/dueling-picklist/docs.mdx
@@ -2,7 +2,7 @@ import CodeView from '../../../shared/components/CodeView';
 import CodeBlock from '../../../shared/components/CodeBlock';
 import Example from '../../../shared/components/Example';
 import Blockquote from '../../../shared/components/Blockquote';
-import { MultiSelect, MultiSelectViewMode, DefaultSnapShot, LockedSnapShot, DisabledSnapShot, SelectedSnapShot, MultiSelectedSnapShot, GrabbedSnapShot, MovedInSnapShot, DroppedSnapShot, MoveToSnapShot, CountriesSnapshot, SelectedCountriesSnapshot, MultipleSelectedCountriesSnapshot, DroppedCountriesSnapshot } from './';
+import { MultiSelect, MultiSelectViewMode, DefaultSnapShot, GroupLabelSnapShot, LockedSnapShot, DisabledSnapShot, SelectedSnapShot, MultiSelectedSnapShot, GrabbedSnapShot, MovedInSnapShot, DroppedSnapShot, MoveToSnapShot, CountriesSnapshot, SelectedCountriesSnapshot, MultipleSelectedCountriesSnapshot, DroppedCountriesSnapshot } from './';
 import { DoctypeIcon } from '../icons/doctype/example';
 
 <div className="doc lead">
@@ -43,11 +43,25 @@ This component is essentially 2 ARIA listboxes side by side, so we follow the [A
   - `space` toggles "Drag and Drop" mode. When in "Drag and Drop" mode:
     - `up` and `down` arrows move the selected items _within_ the current list
 
+## Showing a Group Label
+
+A Dueling Picklist has the option to display a group label, similar to using a `fieldset` and `legend` on grouped form controls. To achieve this, wrap the Dueling Picklist in an `slds-form-element` and add a `div` with the same class names that are applied to a `legend` element in a fieldset, `slds-form-element__label slds-form-element__legend slds-text-title_caps`.
+
+<Blockquote header="Labeling the group" type="a11y">
+  It is important that the `slds-form-element` `<div>` has the `role="group"` attribute applied, along with `aria-labelledby`, whose value is the ID of the visible group label.
+</Blockquote>
+
+<Example title="Dueling Picklist With Group Label">
+  <CodeView>
+    <MultiSelect dataSet={GroupLabelSnapShot} />
+  </CodeView>
+</Example>
+
 ## Responsive
 
 To make the dueling picklist responsive or use it within narrow regions, apply the class `slds-dueling-picklist__column_responsive` to the `<div>`s with class `slds-dueling-picklist__column` that contain options (not the columns that only contain buttons). Any items longer than the space available will truncate with ellipses.
 
-<Example title="Dueling Picklist">
+<Example title="Dueling Picklist Responsive">
   <CodeView>
     <MultiSelect dataSet={CountriesSnapshot} noReorder isResponsive />
   </CodeView>

diff --git a/ui/components/dueling-picklist/index.js b/ui/components/dueling-picklist/index.js
@@ -11,7 +11,23 @@ import _ from '../../shared/helpers';
 /// ////////////////////////////////////////
 
 export const MultiSelect = props => {
-  return (
+  const GroupedMultiSelect = () => (
+    <div
+      className="slds-form-element"
+      role="group"
+      aria-labelledby="picklist-group-label"
+    >
+      <div
+        id="picklist-group-label"
+        className="slds-form-element__label slds-form-element__legend slds-text-title_caps"
+      >
+        {props.dataSet.groupLabel}
+      </div>
+      <BaseMultiSelect dataSet={props.dataSet} />
+    </div>
+  );
+
+  const BaseMultiSelect = () => (
     <div className="slds-dueling-list">
       <div
         className="slds-assistive-text"
@@ -44,6 +60,11 @@ export const MultiSelect = props => {
       )}
     </div>
   );
+  return props.dataSet.groupLabel ? (
+    <GroupedMultiSelect />
+  ) : (
+    <BaseMultiSelect />
+  );
 };
 
 export const MultiSelectViewMode = props => {
@@ -241,6 +262,61 @@ export const DefaultSnapShot = {
   ]
 };
 
+export const GroupLabelSnapShot = {
+  groupLabel: 'Select an option',
+  liveRegionText: '',
+  optionDragLabel:
+    'Press space bar when on an item, to move it within the list. CMD plus left and right arrow keys, to move items between lists.',
+  selectionGroups: [
+    {
+      label: 'First Category',
+      options: [
+        {
+          text: 'Option 1',
+          tabIndex: 0,
+          isSelected: false,
+          isGrabbed: false
+        },
+        {
+          text: 'Option 2',
+          tabIndex: -1,
+          isSelected: false,
+          isGrabbed: false
+        },
+        {
+          text: 'Option 3',
+          tabIndex: -1,
+          isSelected: false,
+          isGrabbed: false
+        },
+        {
+          text: 'Option 6',
+          tabIndex: -1,
+          isSelected: false,
+          isGrabbed: false
+        }
+      ]
+    },
+    {
+      label: 'Second Category',
+      options: [
+        {
+          text: 'Option 4',
+          tabIndex: 0,
+          isSelected: false,
+          isGrabbed: false
+        },
+        {
+          text: 'Option 5',
+          tabIndex: -1,
+          isSelected: false,
+          isGrabbed: false
+        }
+      ]
+    }
+  ]
+};
+
 export const DisabledSnapShot = {
   liveRegionText: '',
   optionDragLabel: