@salesforce-ux/design-system/__internal/chunked/docs/ui/components/dueling-picklist/docs.mdx.js

Salesforce Lightning Design System

var SLDS="object"==typeof SLDS?SLDS:{};SLDS["__internal/chunked/docs/./ui/components/dueling-picklist/docs.mdx.js"]=function(e){function t(t){for(var i,c,s=t[0],o=t[1],r=t[2],u=0,m=[];u<s.length;u++)c=s[u],Object.prototype.hasOwnProperty.call(a,c)&&a[c]&&m.push(a[c][0]),a[c]=0;for(i in o)Object.prototype.hasOwnProperty.call(o,i)&&(e[i]=o[i]);for(d&&d(t);m.length;)m.shift()();return n.push.apply(n,r||[]),l()}function l(){for(var e,t=0;t<n.length;t++){for(var l=n[t],i=!0,s=1;s<l.length;s++){var o=l[s];0!==a[o]&&(i=!1)}i&&(n.splice(t--,1),e=c(c.s=l[0]))}return e}var i={},a={31:0},n=[];function c(t){if(i[t])return i[t].exports;var l=i[t]={i:t,l:!1,exports:{}};return e[t].call(l.exports,l,l.exports,c),l.l=!0,l.exports}c.m=e,c.c=i,c.d=function(e,t,l){c.o(e,t)||Object.defineProperty(e,t,{enumerable:!0,get:l})},c.r=function(e){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},c.t=function(e,t){if(1&t&&(e=c(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var l=Object.create(null);if(c.r(l),Object.defineProperty(l,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var i in e)c.d(l,i,function(t){return e[t]}.bind(null,i));return l},c.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return c.d(t,"a",t),t},c.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},c.p="/assets/scripts/bundle/";var s=this.webpackJsonpSLDS___internal_chunked_docs=this.webpackJsonpSLDS___internal_chunked_docs||[],o=s.push.bind(s);s.push=t,s=s.slice();for(var r=0;r<s.length;r++)t(s[r]);var d=o;return n.push([714,0]),l()}({0:function(e,t){e.exports=React},20:function(e,t){e.exports=ReactDOM},22:function(e,t){e.exports=JSBeautify},714:function(e,t,l){"use strict";l.r(t),l.d(t,"getElement",(function(){return E})),l.d(t,"getContents",(function(){return f}));var i=l(0),a=l(4),n=l(2),c=l(27),s=l(15),o=l(14),r=l(37),d=(l(147),a.c.a),u=a.c.code,m=a.c.em,b=a.c.h2,h=a.c.h3,p=a.c.h4,j=a.c.li,g=a.c.p,O=a.c.ul,E=function(){return Object(i.createElement)(a.b,{},Object(i.createElement)("div",{className:"doc lead"},"A dueling-picklist is used to move options between two lists and is often referred to as a multi-select. Sometimes, the list options can then be re-ordered, depending on the use case."),Object(i.createElement)(n.a,{exampleOnly:!0},Object(i.createElement)(r.j,{dataSet:r.m,noReorder:!0})),b({id:"About-Dueling-Picklist"},"About Dueling-Picklist"),h({id:"Accessibility"},"Accessibility"),g({},"This component is essentially 2 ARIA listboxes side by side, so we follow the ",d({href:"https://www.w3.org/TR/wai-aria-practices/#Listbox"},"ARIA practices guide")," to help implement their interaction in an accessible way. Some additional details, supplementary to the ARIA guide include:"),p({id:"Markup"},"Markup"),O({},j({},u({},'aria-multiselectable="true"')," should be set on each listbox"),j({},u({},"aria-selected")," should be placed on each ",u({},'role="option"'),", and set to ",u({},"false")," by default"),j({},u({},"aria-labelledby")," is used to identify the list to the user and should point to the list label"),j({},u({},"aria-describedby")," is used to provide operation instructions for the Drag and Drop interaction"),j({},u({},"tabindex"),' should be set to "0" when an item is selected and "-1" otherwise')),p({id:"Focus-Management"},"Focus Management"),O({},j({},"Initially, nothing should be selected and the first item in each list should have ",u({},'tabindex="0"')),j({},"When an item is focused, it becomes selected"),j({},"When focus leaves the list, the last selected item remains selected and focusable. When focus returns to the list focus is placed on the last selected item."),j({},"When moving items:",O({},j({},"With the move button: the items are unselected and added to the target list. The focus should remain on the move button."),j({},"With a keyboard shortcut: focus remains on the item, but in the target list. Since the item is focused, it is also selected."),j({},"If there are already selected items in the target list, they stay selected and the new items are added below them.")))),p({id:"Keyboard-Interactions"},"Keyboard Interactions"),O({},j({},"Each list has a single focusable option inside. There is only ever one focusable option per list and it is expected that a user will use their arrow keys, and some modifier keys, to perform all actions."),j({},"Because we support drag and drop re-ordering within a list, we implement the second multi-select keyboard model.",O({},j({},u({},"up")," and ",u({},"down")," arrows move focus ",m({},"and")," selection, with ",u({},'aria-selected="true"'),". Any previously selected items are deselected."),j({},u({},"shift + up")," and ",u({},"shift + down")," move focus and creates addition selections"),j({},u({},"ctrl + down")," or ",u({},"ctrl + up")," moves focus but selection remains where it is"),j({},u({},"ctrl + space")," toggles selection on the focused option, in addition to previous selections"),j({},u({},"ctrl + a")," selects all options in the list"),j({},u({},"cmd/ctrl + right")," and ",u({},"cmd/ctrl + left")," Moves selected items between lists"),j({},u({},"space"),' toggles "Drag and Drop" mode. When in "Drag and Drop" mode:',O({},j({},u({},"up")," and ",u({},"down")," arrows move the selected items ",m({},"within")," the current list")))))),b({id:"Base"},"Base"),Object(i.createElement)(s.a,{title:"Dueling Picklist with Reorder"},Object(i.createElement)(r.j,{dataSet:r.b})),b({id:"Group-Label"},"Group Label"),g({},"A Dueling Picklist should have a group label, similar to using a ",u({},"fieldset")," and ",u({},"legend")," on grouped form controls. To achieve this, wrap the Dueling Picklist in an ",u({},"slds-form-element")," and add a ",u({},"div")," with the same class names that are applied to a ",u({},"legend")," element in a fieldset, ",u({},"slds-form-element__label slds-form-element__legend"),"."),Object(i.createElement)(o.a,{header:"Labeling the group",type:"a11y"},Object(i.createElement)("p",null,"It is important that the ",Object(i.createElement)("code",null,"slds-form-element")," ",Object(i.createElement)("code",null,"<div>")," has the ",Object(i.createElement)("code",null,'role="group"')," attribute applied, along with ",Object(i.createElement)("code",null,"aria-labelledby"),", whose value is the ID of the visible group label.")),Object(i.createElement)(s.a,{title:"Dueling Picklist With Group Label"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.b}))),b({id:"Responsive"},"Responsive"),g({},"To make the dueling picklist responsive or use it within narrow regions, apply the class ",u({},"slds-dueling-picklist__column_responsive")," to the ",u({},"<div>"),"s with class ",u({},"slds-dueling-picklist__column")," that contain options (not the columns that only contain buttons). The dueling picklist will take up all available horizontal space, and any items longer than the available space will truncate with an ellipsis."),Object(i.createElement)(s.a,{title:"Dueling Picklist Responsive"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.a,noReorder:!0,isResponsive:!0}))),Object(i.createElement)(o.a,{header:"Adjusting Height",type:"note"},Object(i.createElement)("p",null,"To adjust the height of the listboxes, set the height using an inline style on _both_ of the ",Object(i.createElement)("code",null,"<div>"),"s with class ",Object(i.createElement)("code",null,"slds-dueling-picklist__column"),". If you are setting it based on a maximum number of items being shown before scrolling, you can set ",Object(i.createElement)("code",null,"height = (2.25rem * numItems) + 1rem"),".")),Object(i.createElement)(c.a,{toggleCode:!1},Object(i.createElement)("div",{className:"slds-dueling-list"},Object(i.createElement)("div",{className:"slds-dueling-list__column"},Object(i.createElement)("span",{className:"slds-form-element__label",id:"label-1"},"Available Languages"),Object(i.createElement)("div",{className:"slds-dueling-list__options",style:{height:"10rem"}},"...")),Object(i.createElement)("div",{className:"slds-dueling-list__column"},"..."),Object(i.createElement)("div",{className:"slds-dueling-list__column"},Object(i.createElement)("span",{className:"slds-form-element__label",id:"label-2"},"Selected Languages"),Object(i.createElement)("div",{className:"slds-dueling-list__options",style:{height:"10rem"}},"...")))),b({id:"Edit-Mode"},"Edit Mode"),g({},"If the user needs to select multiple options for a field, like a list of languages supported, then use a dueling picklist without the re-order arrows on the right."),Object(i.createElement)(o.a,{header:"Helpful Assistive Text",type:"a11y"},Object(i.createElement)("p",null,"The assistive text content in the ",Object(i.createElement)("code",null,"option-drag-label")," ",Object(i.createElement)("code",null,"<div>")," should provide clear instructions on how to drag and drop with a keyboard. See the ",Object(i.createElement)("a",{href:"#Keyboard-Interactions"},"keyboard interactions section")," above for modifier key information.")),Object(i.createElement)(s.a,{title:"Dueling Picklist"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.a,noReorder:!0}))),h({id:"Selected-Item"},"Selected Item"),Object(i.createElement)(o.a,{header:"Aria Selected",type:"a11y"},Object(i.createElement)("p",null,Object(i.createElement)("code",null,"aria-selected")," should be placed on each"," ",Object(i.createElement)("code",null,'role="option"'),", and set to"," ",Object(i.createElement)("code",null,"true")," when the item is selected.")),Object(i.createElement)(s.a,{title:"Dueling Picklist with Item Selected"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.m,noReorder:!0}))),h({id:"Multiple-Selected-Items"},"Multiple Selected Items"),Object(i.createElement)(s.a,{title:"Dueling Picklist with Multiple Items Selected"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.l,noReorder:!0}))),h({id:"Dropped-Items"},"Dropped Items"),Object(i.createElement)(o.a,{type:"a11y",header:"Aria Live"},Object(i.createElement)("p",null,"The ",Object(i.createElement)("code",null,"drag-live-region")," ",Object(i.createElement)("code",null,"<div>")," with ",Object(i.createElement)("code",null,'aria-live="assertive"')," should update as items are moved to provide context about the state and location of the items.")),Object(i.createElement)(c.a,{toggleCode:!1},Object(i.createElement)("div",{className:"slds-dueling-list"},Object(i.createElement)("div",{className:"slds-assistive-text",id:"drag-live-region","aria-live":"assertive"},"Arabic and German: Moved to Selected Languages."))),Object(i.createElement)(s.a,{title:"Dueling Picklist with Items Dropped"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.e,noReorder:!0}))),h({id:"Locked-Items"},"Locked Items"),g({},"If items are not able to be removed or reordered from the selected list, a lock icon appears next to the item name."),Object(i.createElement)(o.a,{type:"a11y",header:"Aria Disabled and Assistive Text"},Object(i.createElement)("p",null,"For each locked item, ",Object(i.createElement)("code",null,'aria-disabled="true"')," must be applied to ",Object(i.createElement)("code",null,".slds-listbox__option")," and assistive text (",Object(i.createElement)("code",null,".slds-assistive-text"),") must be added to"," ",Object(i.createElement)("code",null,".slds-icon_container"),".")),Object(i.createElement)(s.a,{title:"Dueling Picklist with a Locked Item"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.h,noReorder:!0}))),h({id:"With-Reordering"},"With Reordering"),g({},"If the order of the selected options matters, include the vertical arrows to the right. This allows the user to reorder the second listbox of options."),Object(i.createElement)(s.a,{title:"Dueling Picklist with Reorder Active"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.b}))),g({},"The following examples show the process of selecting an item, moving it within a list, and dropping it in a final position."),Object(i.createElement)(o.a,{type:"a11y",header:"Aria Live"},Object(i.createElement)("p",null,"Pay attention to the ",Object(i.createElement)("code",null,"drag-live-region")," ",Object(i.createElement)("code",null,"<div>")," with"," ",Object(i.createElement)("code",null,'aria-live="assertive"'),". This should update as items are moved to provide context about the state and location of the items at all times.")),p({id:"Item-Selected"},"Item Selected"),Object(i.createElement)(s.a,{title:"Dueling Picklist with Reorder Active Item Selected"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.n}))),p({id:"Item-Grabbed"},"Item Grabbed"),g({},"Within a list, users are able to drag and drop an item."),Object(i.createElement)(s.a,{title:"Dueling Picklist with Reorder Active Item Grabbed"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.g}))),p({id:"Item-Moved-Within-a-List"},"Item Moved Within a List"),Object(i.createElement)(s.a,{title:"Dueling Picklist with Reorder Active Item Moved within List"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.i}))),p({id:"Item-Dropped-in-a-List"},"Item Dropped in a List"),Object(i.createElement)(s.a,{title:"Dueling Picklist with Reorder Active Item Dropped"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.f}))),h({id:"Disabled"},"Disabled"),g({},"If the user is not able to interact with the dueling picklist, then it should be marked as disabled."),Object(i.createElement)(o.a,{type:"a11y",header:"Aria Disabled"},Object(i.createElement)("p",null,"In disabled mode, both list boxes"," ",Object(i.createElement)("code",null,"ul[role=listbox]")," should receive"," ",Object(i.createElement)("code",null,'aria-disabled="true"'),", and all directional buttons should receive the ",Object(i.createElement)("code",null,"disabled")," attribute.")),Object(i.createElement)(o.a,{type:"note",header:"Utility Class"},Object(i.createElement)("p",null,"The class ",Object(i.createElement)("code",null,"slds-is-disabled")," should also be applied to the divs with the class"," ",Object(i.createElement)("code",null,"slds-dueling-list_options"),".")),Object(i.createElement)(s.a,{title:"Dueling Picklist Disabled"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.d,disabled:!0}))),h({id:"Required"},"Required"),Object(i.createElement)(s.a,{title:"Dueling Picklist with Required Indicator"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.j,{dataSet:r.b,isRequired:!0}))),h({id:"With-Tooltip"},"With Tooltip"),g({},"If some contextual information regarding the dueling picklist is needed, add a tooltip next to the group label."),Object(i.createElement)(s.a,{title:"Dueling Picklist with Tooltip"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.c,null,Object(i.createElement)(r.j,{dataSet:r.b,hasTooltip:!0,showTooltip:!0})))),h({id:"Required-With-Tooltip"},"Required With Tooltip"),Object(i.createElement)(s.a,{title:"Dueling Picklist with Required Indicator and Tooltip"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.c,null,Object(i.createElement)(r.j,{dataSet:r.b,isRequired:!0,hasTooltip:!0,showTooltip:!0})))),b({id:"View-Mode"},"View Mode"),g({},"When the user is done selecting options, or is in view mode of the field, they are presented with a comma separated list."),Object(i.createElement)(s.a,{title:"Dueling Picklist in View Mode"},Object(i.createElement)(n.a,null,Object(i.createElement)(r.k,null))))},f=function(){return Object(a.a)(E())}}});