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

Salesforce Lightning Design System

var SLDS=SLDS||{};SLDS["__internal/chunked/docs/ui/components/dueling-picklist/docs.mdx.js"]=function(e){function t(t){for(var i,n,o=t[0],d=t[1],r=t[2],u=0,h=[];u<o.length;u++)n=o[u],a[n]&&h.push(a[n][0]),a[n]=0;for(i in d)Object.prototype.hasOwnProperty.call(d,i)&&(e[i]=d[i]);for(c&&c(t);h.length;)h.shift()();return s.push.apply(s,r||[]),l()}function l(){for(var e,t=0;t<s.length;t++){for(var l=s[t],i=!0,o=1;o<l.length;o++){var d=l[o];0!==a[d]&&(i=!1)}i&&(s.splice(t--,1),e=n(n.s=l[0]))}return e}var i={},a={2:0},s=[];function n(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,n),l.l=!0,l.exports}n.m=e,n.c=i,n.d=function(e,t,l){n.o(e,t)||Object.defineProperty(e,t,{configurable:!1,enumerable:!0,get:l})},n.r=function(e){Object.defineProperty(e,"__esModule",{value:!0})},n.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return n.d(t,"a",t),t},n.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},n.p="/assets/scripts/bundle/";var o=this.webpackJsonpSLDS___internal_chunked_docs=this.webpackJsonpSLDS___internal_chunked_docs||[],d=o.push.bind(o);o.push=t,o=o.slice();for(var r=0;r<o.length;r++)t(o[r]);var c=d;return s.push([82,0]),l()}({0:function(e,t){e.exports=React},6:function(e,t){e.exports=JSBeautify},82:function(e,t,l){"use strict";Object.defineProperty(t,"__esModule",{value:!0}),t.getContents=t.getElement=void 0;var i=l(0),a=(u(i),l(7)),s=u(a),n=u(l(9)),o=u(l(11)),d=u(l(10)),r=u(l(12)),c=l(43);l(31);function u(e){return e&&e.__esModule?e:{default:e}}var h=a.factories.a,m=a.factories.code,p=a.factories.em,f=a.factories.h2,g=a.factories.h3,b=a.factories.h4,v=a.factories.li,S=a.factories.p,E=a.factories.ul,w=t.getElement=function(){return(0,i.createElement)(s.default,{},(0,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."),(0,i.createElement)(d.default,{title:"Dueling Picklist with Reorder"},(0,i.createElement)(c.MultiSelect,{dataSet:c.DefaultSnapShot})),S({},"This component is essentially 2 ARIA listboxes side by side, so we follow the ",h({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:"),f({id:"Notable-Attributes"},"Notable Attributes"),E({},v({},m({},'aria-multiselectable="true"')," should be set on each listbox"),v({},m({},"aria-selected")," should be placed on each ",m({},'role="option"'),", and set to ",m({},"false")," by default"),v({},m({},"aria-labelledby")," is used to identify the list to the user and should point to the list label"),v({},m({},"aria-describedby")," is used to provide operation instructions for the Drag and Drop interaction"),v({},m({},"tabindex"),' should be set to "0" when an item is selected and "-1" otherwise')),f({id:"Focus-Management"},"Focus Management"),E({},v({},"Initially, nothing should be selected and the first item in each list should have ",m({},'tabindex="0"')),v({},"When an item is focused, it becomes selected"),v({},"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."),v({},"When moving items:",E({},v({},"With the move button: the items are unselected and added to the target list. The focus should remain on the move button."),v({},"With a keyboard shortcut: focus remains on the item, but in the target list. Since the item is focused, it is also selected."),v({},"If there are already selected items in the target list, they stay selected and the new items are added below them.")))),f({id:"Expected-Keyboard-Navigation"},"Expected Keyboard Navigation"),E({},v({},"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."),v({},"Because we support drag and drop re-ordering within a list, we implement the second multi-select keyboard model.",E({},v({},m({},"up")," and ",m({},"down")," arrows move focus ",p({},"and")," selection, with ",m({},'aria-selected="true"'),". Any previously selected items are deselected."),v({},m({},"shift + up")," and ",m({},"shift + down")," move focus and creates addition selections"),v({},m({},"ctrl + down")," or ",m({},"ctrl + up")," moves focus but selection remains where it is"),v({},m({},"ctrl + space")," toggles selection on the focused option, in addition to previous selections"),v({},m({},"ctrl + a")," selects all options in the list"),v({},m({},"cmd/ctrl + right")," and ",m({},"cmd/ctrl + left")," Moves selected items between lists"),v({},m({},"space"),' toggles "Drag and Drop" mode. When in "Drag and Drop" mode:',E({},v({},m({},"up")," and ",m({},"down")," arrows move the selected items ",p({},"within")," the current list")))))),f({id:"Group-Label"},"Group Label"),S({},"A Dueling Picklist should have a group label, similar to using a ",m({},"fieldset")," and ",m({},"legend")," on grouped form controls. To achieve this, wrap the Dueling Picklist in an ",m({},"slds-form-element")," and add a ",m({},"div")," with the same class names that are applied to a ",m({},"legend")," element in a fieldset, ",m({},"slds-form-element__label slds-form-element__legend"),"."),S({},(0,i.createElement)(r.default,{header:"Labeling the group",type:"a11y"},"It is important that the ",m({},"slds-form-element")," ",m({},"<div>")," has the ",m({},'role="group"')," attribute applied, along with ",m({},"aria-labelledby"),", whose value is the ID of the visible group label.")),(0,i.createElement)(d.default,{title:"Dueling Picklist With Group Label"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.DefaultSnapShot}))),f({id:"Responsive"},"Responsive"),S({},"To make the dueling picklist responsive or use it within narrow regions, apply the class ",m({},"slds-dueling-picklist__column_responsive")," to the ",m({},"<div>"),"s with class ",m({},"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."),(0,i.createElement)(d.default,{title:"Dueling Picklist Responsive"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.CountriesSnapshot,noReorder:!0,isResponsive:!0}))),S({},(0,i.createElement)(r.default,{header:"Adjusting Height",type:"note"},"To adjust the height of the listboxes, set the height using an inline style on ",p({},"both")," of the ",m({},"<div>"),"s with class ",m({},"slds-dueling-picklist__column"),". If you are setting it based on a maximum number of items being shown before scrolling, you can set ",m({},"height = (2.25rem * numItems) + 1rem"),".")),S({},(0,i.createElement)(o.default,{toggleCode:!1},(0,i.createElement)("div",{className:"slds-dueling-list"},(0,i.createElement)("div",{className:"slds-dueling-list__column"},(0,i.createElement)("span",{className:"slds-form-element__label",id:"label-1"},"Available Languages"),(0,i.createElement)("div",{className:"slds-dueling-list__options",style:{height:"10rem"}},"{...}")),(0,i.createElement)("div",{className:"slds-dueling-list__column"},"{...}"),(0,i.createElement)("div",{className:"slds-dueling-list__column"},(0,i.createElement)("span",{className:"slds-form-element__label",id:"label-2"},"Selected Languages"),(0,i.createElement)("div",{className:"slds-dueling-list__options",style:{height:"10rem"}},"{...}"))))),f({id:"Edit-Mode"},"Edit Mode"),S({},"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."),S({},(0,i.createElement)(r.default,{header:"Helpful Assistive Text",type:"a11y"},"The assistive text content in the ",m({},"option-drag-label")," ",m({},"<div>")," should provide clear instructions on how to drag and drop with a keyboard.")),(0,i.createElement)(d.default,{title:"Dueling Picklist"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.CountriesSnapshot,noReorder:!0}))),g({id:"Selected-Item"},"Selected Item"),(0,i.createElement)(r.default,{header:"Aria Selected",type:"a11y"},(0,i.createElement)("code",{className:"doc"},"aria-selected")," should be placed on each ",(0,i.createElement)("code",{className:"doc"},'role="option"'),", and set to ",(0,i.createElement)("code",{className:"doc"},"true")," when the item is selected."),(0,i.createElement)(d.default,{title:"Dueling Picklist with Item Selected"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.SelectedCountriesSnapshot,noReorder:!0}))),g({id:"Multiple-Selected-Items"},"Multiple Selected Items"),(0,i.createElement)(d.default,{title:"Dueling Picklist with Multiple Items Selected"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.MultipleSelectedCountriesSnapshot,noReorder:!0}))),g({id:"Dropped-Items"},"Dropped Items"),S({},(0,i.createElement)(r.default,{type:"a11y",header:"Aria Live"},"The ",m({},"drag-live-region")," ",m({},"<div>")," with ",m({},'aria-live="assertive"')," should update as items are moved to provide context about the state and location of the items.")),(0,i.createElement)(o.default,{toggleCode:!1},(0,i.createElement)("div",{className:"slds-dueling-list"},(0,i.createElement)("div",{className:"slds-assistive-text",id:"drag-live-region","aria-live":"assertive"},"Arabic and German: Moved to Selected Languages."))),(0,i.createElement)(d.default,{title:"Dueling Picklist with Items Dropped"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.DroppedCountriesSnapshot,noReorder:!0}))),g({id:"Locked-Items"},"Locked Items"),S({},"If items are not able to be removed from the selected list, a lock icon appears next to the item name."),(0,i.createElement)(d.default,{title:"Dueling Picklist with a Locked Item"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.LockedSnapShot,noReorder:!0}))),g({id:"With-Reordering"},"With Reordering"),S({},"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."),(0,i.createElement)(d.default,{title:"Dueling Picklist with Reoder Active"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.DefaultSnapShot}))),S({},"The following examples show the process of selecting an item, moving it within a list, and dropping it in a final position."),S({},(0,i.createElement)(r.default,{type:"a11y",header:"Aria Live"},"Pay attention to the ",m({},"drag-live-region")," ",m({},"<div>")," with ",m({},'aria-live="assertive"'),". This should update as items are moved to provide context about the state and location of the items at all times.")),b({id:"Item-Selected"},"Item Selected"),(0,i.createElement)(d.default,{title:"Dueling Picklist with Reoder Active Item Selected"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.SelectedSnapShot}))),b({id:"Item-Grabbed"},"Item Grabbed"),S({},"Within a list, users are able to drag and drop an item."),(0,i.createElement)(d.default,{title:"Dueling Picklist with Reoder Active Item Grabbed"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.GrabbedSnapShot}))),b({id:"Item-Moved-Within-a-List"},"Item Moved Within a List"),(0,i.createElement)(d.default,{title:"Dueling Picklist with Reoder Active Item Moved within List"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.MovedInSnapShot}))),b({id:"Item-Dropped-in-a-List"},"Item Dropped in a List"),(0,i.createElement)(d.default,{title:"Dueling Picklist with Reoder Active Item Dropped"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.DroppedSnapShot}))),g({id:"Disabled"},"Disabled"),S({},"If the user is not able to interact with the dueling picklist, then it should be marked as disabled."),(0,i.createElement)(r.default,{type:"a11y",header:"Aria Disabled"},"In disabled mode, both list boxes ",(0,i.createElement)("code",{className:"doc"},"ul[role=listbox]")," should receive ",(0,i.createElement)("code",{className:"doc"},'aria-disabled="true"'),", and all directional buttons should receive the ",(0,i.createElement)("code",{className:"doc"},"disabled")," attribute."),(0,i.createElement)(r.default,{type:"note",header:"Utility Class"},"The class ",(0,i.createElement)("code",{className:"doc"},"slds-is-disabled")," should also be applied to the divs with the class ",(0,i.createElement)("code",{className:"doc"},"slds-dueling-list_options"),"."),(0,i.createElement)(d.default,{title:"Dueling Picklist Disabled"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.DisabledSnapShot,disabled:!0}))),g({id:"Required"},"Required"),(0,i.createElement)(d.default,{title:"Dueling Picklist with Required Indicator"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.DefaultSnapShot,isRequired:!0}))),g({id:"With-Tooltip"},"With Tooltip"),S({},"If some contextual information regarding the dueling picklist is needed, add a tooltip next to the group label."),(0,i.createElement)(d.default,{title:"Dueling Picklist with Tooltip"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.Demo,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.DefaultSnapShot,hasTooltip:!0,showTooltip:!0})))),g({id:"Required-With-Tooltip"},"Required With Tooltip"),(0,i.createElement)(d.default,{title:"Dueling Picklist with Required Indicator and Tooltip"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.Demo,null,(0,i.createElement)(c.MultiSelect,{dataSet:c.DefaultSnapShot,isRequired:!0,hasTooltip:!0,showTooltip:!0})))),f({id:"View-Mode"},"View Mode"),S({},"When the user is done selecting options, or is in view mode of the field, they are presented with a comma separated list."),(0,i.createElement)(d.default,{title:"Dueling Picklist in View Mode"},(0,i.createElement)(n.default,null,(0,i.createElement)(c.MultiSelectViewMode,null))))};t.getContents=function(){return(0,a.createTableOfContents)(w())}}});