lightning-base-components 1.17.7-alpha → 1.18.2-alpha

package/src/lightning/accordionSection/accordionSection.html

@@ -1,24 +1,28 @@
 <template>
-    <section class={computedSectionClasses}>
-        <div class="slds-accordion__summary">
-            <h2 aria-level={_privateHeadingAriaLevel} onkeydown={handleKeyDown} class="slds-accordion__summary-heading">
-                <button class="section-control slds-button slds-button_reset slds-accordion__summary-action"
+    <div class="slds-accordion__list-item">
+        <section class={computedSectionClasses} part="accordion-section">
+            <div class="slds-accordion__summary">
+                <h2 aria-level={_privateHeadingAriaLevel} onkeydown={handleKeyDown} class="slds-accordion__summary-heading">
+                    <button 
+                        class="section-control slds-button slds-button_reset slds-accordion__summary-action"
                         type="button"
                         aria-expanded={computedAriaExpanded}
                         aria-controls='lgt-accordion-section'
-                        onclick={handleSelectSection}>
-                    <lightning-primitive-icon
-                        icon-name="utility:switch"
-                        svg-class="slds-accordion__summary-action-icon slds-button__icon slds-button__icon_left"
-                        size="x-small">
-                    </lightning-primitive-icon>
-                    <span class="slds-accordion__summary-content" title={label}>{label}</span>
-                </button>
-            </h2>
-            <slot name="actions"></slot>
-        </div>
-        <div id='lgt-accordion-section' hidden={computedHidden} aria-hidden={computedAriaHidden} class="slds-accordion__content">
-            <slot></slot>
-        </div>
-    </section>
+                        onclick={handleSelectSection}
+                        part="button">
+                        <lightning-primitive-icon
+                            icon-name={accordionTitleIcon}
+                            svg-class="slds-button__icon slds-button__icon_left"
+                            size="x-small">
+                        </lightning-primitive-icon>
+                        <span class="slds-accordion__summary-content" title={label}>{label}</span>
+                    </button>
+                </h2>
+                <slot name="actions"></slot>
+            </div>
+            <div id='lgt-accordion-section' hidden={computedHidden} aria-hidden={computedAriaHidden} class="slds-accordion__content">
+                <slot></slot>
+            </div>
+        </section>
+    </div>
 </template>

package/src/lightning/accordionSection/accordionSection.js

@@ -1,7 +1,9 @@
-import { LightningElement, api, track } from 'lwc';
+import { api, track } from 'lwc';
+import LightningShadowBaseClass from 'lightning/shadowBaseClassPrivate';
 import { generateUniqueId } from 'lightning/inputUtils';
 import { keyCodes, isHeadingLevelValid } from 'lightning/utilsPrivate';
 import { classSet } from 'lightning/utils';
+import DIR from '@salesforce/i18n/dir';
 
 /**
  * A single section that is nested in an accordion component.
@@ -9,7 +11,7 @@ import { classSet } from 'lightning/utils';
  * Actions are displayed at the top right corner of the accordion section.
  * @slot default Placeholder for your content in the accordion section.
  */
-export default class LightningAccordionSection extends LightningElement {
+export default class LightningAccordionSection extends LightningShadowBaseClass {
     /**
      * The unique section name to use with the active-section-name attribute in the accordion component.
      * @type {string}
@@ -57,6 +59,7 @@ export default class LightningAccordionSection extends LightningElement {
     privateUniqueId = generateUniqueId('lgt-accordion-section');
 
     connectedCallback() {
+        super.connectedCallback();
         this.setAttribute('role', 'listitem');
         this.classList.add('slds-accordion__list-item');
         this.registerSectionWithParent();
@@ -116,6 +119,30 @@ export default class LightningAccordionSection extends LightningElement {
         this.privateAccordionSectionObserver.notifySectionSelect();
     }
 
+    get hostDirection() {
+        // need to use .parentElement as accordionSection needs parentElement accordion to render
+        const host = this.template.host;
+        if (host.parentElement) {
+            return (
+                window
+                    .getComputedStyle(host.parentElement)
+                    .direction.toLowerCase() || 'ltr'
+            );
+        }
+
+        // if no parentElement, return direction from @salesforce/i18n; else fallback to 'ltr'
+        return DIR || 'ltr';
+    }
+
+    get accordionTitleIcon() {
+        if (this.privateIsOpen) {
+            return 'utility:switch';
+        }
+        return this.hostDirection === 'ltr'
+            ? 'utility:chevronright'
+            : 'utility:chevronleft';
+    }
+
     registerSectionWithParent() {
         const detail = {
             targetId: this.privateUniqueId,

package/src/lightning/ariaObserver/__docs__/ariaObserver.md

@@ -1,7 +1,7 @@
 The `lightning/ariaObserver` module provides an easy way for users to write accessible component that works in both synthetic and native shadow.
 
 ## Aria ID referencing in native shadow
-Use the` AriaObserver` library to write accessible component that works where `ariaLabelledBy` would break native shadow. 
+Use the `AriaObserver` library to write accessible component that works where `ariaLabelledBy` would break native shadow.
 
 Here's an example that won't work with native shadow. In the following code, we support attribute `ariaLabelledBy` in our component `c-foo`, so the `input` element is labelled by external elements.
 
@@ -45,9 +45,11 @@ class Foo extends LightningElement {
 ```
 
 Next, use the `connect(options)` method to connect between the internal element and the external reference. It takes an options object with the following keys:
+- `attribute` The name of the aria attribute. Two supported options: `aria-labelledby`, `aria-describedby`, `aria-activedescendant` and `aria-controls`.
 - `targetSelector` The selector to the internal element where the aria attribute should be attached.
-- `attribute` The name of the aria attribute. Two supported options: `aria-labelledby`and `aria-describedby`.
-- `id` The ID of the external element. Alternatively, you can use `ids` for multiple IDs.
+- `targetNode` The element where the aria attribute should be attached. If not provided, the `targetSelector` is used.
+- `relatedNodeIds` ID(s) of the external element(s) to which the `targetNode` will be related. Passed as a space separated string `id1 id2 id3` or an Array of strings `['id1', 'id2', 'id3']`. Combined with `relatedNodes` if both are present.
+- `relatedNodes` An Array of HTMLElement element(s) to which the `targetNode` will be related. Combined with `relatedNodeIds` if both are present.
 
 This example uses `connect(options)` to display an aria label for the internal `input` element.
 ``` js
@@ -61,12 +63,15 @@ set ariaLabelledBy(refs) {
     this.ariaObserver.connect({
         targetSelector: 'input',
         attribute: 'aria-labelledby',
-        id: refs
+        relatedNodeIds: refs
     });
 }
 ```
 
-Then use the `sync()` method to synchronize the ID references when the template is re-rendered.
+Then use the `sync(isNativeShadow)` method to synchronize the ID references when the template is re-rendered.
+- `isNativeShadow` An optional parameter that indicates whether the relationships involve components rendered in native shadow.
+Used when the `targetSelector` or `targetNode` is within a shadow boundary, but the parent component where AriaObserver has been
+instantiated is not. Example: `lightning-primitive-input-simple` may be rendered in native shadow, but `lightning-input` may not be.
 
 ``` js
 renderedCallback() {
@@ -74,6 +79,14 @@ renderedCallback() {
 }
 ```
 
+When the containing component is native shadow enabled, AriaObserver observes the component's root node to find and link
+the related elements. This can be overridden in cases where the component's root node does not contain the related elements,
+but one of it's ancestor nodes does. For example, `lightning-base-combobox` is contained within `lightning-combobox` so the root of `lightning-combobox` should be used in place of the root of `lightning-base-combobox`.
+
+```js
+    this.ariaObserver.root = parentRootNode;
+```
+
 Finally, disconnect the aria observer and free the resources at the end of the component lifecycle.
 
 ``` js
@@ -117,7 +130,7 @@ export default class Foo extends LightningElement {
         this.ariaObserver.connect({
             targetSelector: 'input',
             attribute: 'aria-labelledby',
-            id: refs
+            relatedNodeIds: refs
         });
     }
 
@@ -134,9 +147,8 @@ export default class Foo extends LightningElement {
 }
 ```
 
-## Limitations
-`AriaObserver` only works with text-only aria ID references.
-
 Supported attributes:
 - `aria-labelledby`
 - `aria-describedby`
+- `aria-activedescendant`
+- `aria-controls`

package/src/lightning/ariaObserver/ariaObserver.js

@@ -4,14 +4,49 @@ import {
     isNativeComponent,
 } from 'lightning/utilsPrivate';
 
-const CONTENT_SEPARATOR = '\n';
-
-function getAttr(elm, attr) {
-    if (elm.tagName.match(/lightning/i)) {
-        return elm[attr];
-    }
-    return elm.getAttribute(attr);
-}
+import {
+    setAriaActiveDescendant,
+    setAriaDescribedBy,
+    setAriaLabelledBy,
+    setAriaControls,
+} from './polyfill.js';
+
+/*
+    Aria Reflection is used if supported by browser.
+    If Aria Reflection is not available, fallback to polyfill
+    Aria Reflection: https://wicg.github.io/aom/aria-reflection-explainer.html
+    Polyfill: https://git.soma.salesforce.com/lwc/aria-element-reflection
+*/
+const SUPPORTED_ATTRIBUTES = new Map([
+    [
+        'aria-controls',
+        {
+            ariaReflection: 'ariaControlsElements',
+            polyfill: setAriaControls,
+        },
+    ],
+    [
+        'aria-labelledby',
+        {
+            ariaReflection: 'ariaLabelledByElements',
+            polyfill: setAriaLabelledBy,
+        },
+    ],
+    [
+        'aria-describedby',
+        {
+            ariaReflection: 'ariaDescribedByElements',
+            polyfill: setAriaDescribedBy,
+        },
+    ],
+    [
+        'aria-activedescendant',
+        {
+            ariaReflection: 'ariaActiveDescendantElement',
+            polyfill: setAriaActiveDescendant,
+        },
+    ],
+]);
 
 function extractElements(root, ids) {
     if (typeof ids !== 'string' || ids === '') {
@@ -24,80 +59,15 @@ function extractElements(root, ids) {
         .filter((el) => !!el);
 }
 
-function extractContent(elements) {
-    return elements
-        .map((element) => element.textContent)
-        .filter((text) => text.length)
-        .join(CONTENT_SEPARATOR);
-}
-
 function splitIds(ids) {
-    return (ids + '').trim().split(/\s+/);
-}
-
-function hashIds(ids) {
-    return (ids + '')
-        .trim()
-        .split(/\s+/)
-        .reduce((r, v) => {
-            r[v] = 1;
-            return r;
-        }, {});
-}
-
-// this method should check each individual id from computedIds
-// against the existing value of the attrName on elm, and dupe
-// them, and add the new ones.
-function addAriaRefWhenNeeded(elm, attrName, computedIds) {
-    const newIds = splitIds(computedIds);
-    const oldIds = getAttr(elm, attrName) || '';
-    const oldIdsHash = hashIds(oldIds);
-    const suffix = [];
-    for (let i = 0; i < newIds.length; i += 1) {
-        if (!oldIdsHash[newIds[i]]) {
-            suffix.push(newIds[i]);
-        }
-    }
-
-    if (suffix.length !== 0) {
-        synchronizeAttrs(elm, {
-            [attrName]:
-                oldIds + (oldIds.length === 0 ? '' : ' ') + suffix.join(' '),
-        });
-    }
-}
-
-// this method should check each individual id from computedIds
-// against the existing value of the attrName on elm, and remove
-// them when possible in preparation for some new values.
-function removeAriaRefWhenPossible(elm, attrName, computedIds) {
-    const newIds = splitIds(computedIds);
-    const oldIds = getAttr(elm, attrName) || '';
-    const oldIdsHash = hashIds(oldIds);
-    const newValues = [];
-    for (let i = 0; i < newIds.length; i += 1) {
-        if (!oldIdsHash[newIds[i]]) {
-            newValues.push(newIds[i]);
-        }
-    }
-
-    synchronizeAttrs(elm, {
-        [attrName]: newValues.join(' '),
-    });
-}
-
-function createPlaceholderContainer() {
-    const container = document.createElement('span');
-    container.className = 'slds-assistive-text';
-    container.setAttribute('placeholder-container', '');
-    return container;
+    return ids ? (ids + '').trim().split(/\s+/) : [];
 }
 
 export default class AriaObserver {
     constructor(component) {
         this.component = component;
         this.template = component.template;
-        this.isNative = isNativeComponent(component);
+        this.isNativeShadow = isNativeComponent(component);
         this.state = {};
         this.liveIds = {};
         this.guid = guid();
@@ -114,54 +84,139 @@ export default class AriaObserver {
         this.liveIds[refs] = liveId;
     }
 
-    connect({ targetSelector, attribute, id, ids }) {
-        ids = ids || id;
-
+    /**
+     * Connects the internal element and the external reference. It takes an options object with the following keys:
+     * @param {String} attribute The name of the aria attribute. Two supported options: `aria-labelledby`, `aria-describedby`, `aria-activedescendant` and `aria-controls`.
+     * @param {String} targetSelector The selector to the internal element where the aria attribute should be attached.
+     * @param {HTMLElement} targetNode The element where the aria attribute should be attached. If not provided, the `targetSelector` is used.
+     * @param {String|Array[String]} relatedNodeIds ID(s) of the external element(s) to which the `targetNode` will be related. Passed as a space separated string `id1 id2 id3`. Combined with `relatedNodes` if both are present.
+     * @param {Array[HTMLElement]} relatedNodes an Array of HTMLElement element(s) to which the `targetNode` will be related. Combined with `relatedNodeIds` if both are present.
+     */
+    connect({
+        attribute,
+        targetSelector,
+        targetNode,
+        relatedNodeIds,
+        relatedNodes,
+    }) {
         this.state[attribute] = this.state[attribute] || {};
         const attrState = this.state[attribute];
 
-        // note: we don't support linking to a different targetSelector
-        attrState.innerSelector = attrState.innerSelector || targetSelector;
+        attrState.targetNode = targetNode;
+        attrState.targetSelector = targetSelector;
+        attrState.relatedNodes = (
+            !Array.isArray(relatedNodes) ? [relatedNodes] : relatedNodes
+        ).filter(Boolean);
 
-        // removing the old ids if possible before setting the new ones
-        if (!this.isNative && attrState.ids) {
-            const elm = this.template.querySelector(attrState.innerSelector);
-            if (elm) {
-                removeAriaRefWhenPossible(elm, attribute, attrState.ids);
-            }
-        }
-
-        attrState.ids = ids;
-
-        if (this.isNative && !attrState.placeholder) {
-            // create placeholder element for copied content
-            attrState.placeholder = document.createElement('span');
-            attrState.placeholder.id = `auto-link-${attribute}-${this.guid}`;
-        }
+        attrState.relatedNodeIds = Array.isArray(relatedNodeIds)
+            ? relatedNodeIds.join(' ')
+            : relatedNodeIds;
 
         if (this.component.isConnected) {
             this.privateUpdate(attribute);
         }
     }
 
-    sync() {
+    /**
+     * Connects the MutationObserver when in native shadow mode and connects the
+     * appropriate aria attributes to the correct elements
+     * @param {Boolean} isNativeShadow - This flag is used when a subcomponent
+     * (like lightning-primitive-input-simple) is in native shadow mode and the parent
+     * (lightning-input) that was passed on AriaObserver instantiation is not.
+     */
+    sync(isNativeShadow) {
+        if (isNativeShadow != null) {
+            this.isNativeShadow = isNativeShadow;
+        }
+
         if (!this.component.isConnected) {
             throw new Error(
                 `Invalid sync invocation. It can only be invoked during renderedCallback().`
             );
         }
-        if (this.isNative && !this.mo) {
-            this.privateConnect();
+
+        if (!this.root) {
+            this.root =
+                this.template && this.template.host
+                    ? this.template.host.getRootNode()
+                    : null;
         }
+
+        this.privateUpdateLiveIds();
+
         for (const attrName in this.state) {
             if (Object.prototype.hasOwnProperty.call(this.state, attrName)) {
                 this.privateUpdate(attrName);
             }
         }
+    }
+
+    get privateIsMoRequired() {
+        return this.isNativeShadow || Object.keys(this.liveIds).length !== 0;
+    }
+
+    get root() {
+        return this._root;
+    }
+
+    /**
+     * Sets the specified root element and observes it. The root element should contain
+     * Observes the root element. The root element should contain
+     * the related node elements. By default, this is the template host's root node, but can be
+     * overridden where required.
+     */
+    set root(root) {
+        this._root = root;
+        if (this._root && this.privateIsMoRequired) {
+            this.privateCreateMutationObserver();
+        }
+    }
+
+    privateUpdate(attrName) {
+        const {
+            targetSelector,
+            targetNode = this.template.querySelector(targetSelector),
+            relatedNodeIds,
+            relatedNodes,
+        } = this.state[attrName];
+
+        if (!targetNode) {
+            return; // nothing to update
+        }
 
-        // live idRef feature is a no-op in native
-        if (!this.isNative) {
-            this.privateUpdateLiveIds();
+        const attribute = SUPPORTED_ATTRIBUTES.get(attrName);
+        if (!attribute) {
+            throw new Error(
+                `${attrName} is not supported by AriaObserver. Supported attributes: ${Array.from(
+                    SUPPORTED_ATTRIBUTES.keys()
+                )}`
+            );
+        }
+
+        if (this.isNativeShadow) {
+            const allRelatedNodes = [
+                ...relatedNodes,
+                ...extractElements(this.root, relatedNodeIds),
+            ];
+            if (targetNode[attribute.ariaReflection]) {
+                /*
+                    Remove any existing polyfill relationships that might have been created
+                    before the ariaReflection property was available (initial connection can occur before the property
+                    exists).
+                */
+                attribute.polyfill(targetNode, null, attrName);
+                // Use Aria Reflection to manage relationships
+                targetNode[attribute.ariaReflection] = relatedNodes;
+            } else {
+                attribute.polyfill(targetNode, allRelatedNodes, attrName);
+            }
+        } else {
+            synchronizeAttrs(targetNode, {
+                [attrName]: [
+                    ...splitIds(relatedNodeIds),
+                    ...relatedNodes.map((n) => n.id),
+                ].join(' '),
+            });
         }
     }
 
@@ -175,6 +230,26 @@ export default class AriaObserver {
         });
     }
 
+    /**
+     * Observes the root element. The root element should contain
+     * the related node elements. By default, this is the template host's root node, but can be
+     * overridden where required.
+     */
+    privateCreateMutationObserver() {
+        this.disconnect();
+        this.mo = new MutationObserver(() => {
+            if (!this.component.isConnected) {
+                return; // do nothing when the template is not connected
+            }
+            this.sync();
+        });
+        this.mo.observe(this.root, {
+            characterData: true,
+            childList: true,
+            subtree: true,
+        });
+    }
+
     privateExtractIds(elements) {
         return elements
             .map((el) => {
@@ -184,7 +259,10 @@ export default class AriaObserver {
     }
 
     privateUpdateLiveIds() {
-        const root = this.template.host.getRootNode();
+        const root =
+            this.template && this.template.host
+                ? this.template.host.getRootNode()
+                : null;
 
         // if not connected do nothing
         if (!root) {
@@ -193,7 +271,7 @@ export default class AriaObserver {
         for (const liveId in this.liveIds) {
             if (Object.prototype.hasOwnProperty.call(this.liveIds, liveId)) {
                 const thisId = this.liveIds[liveId];
-                if (!thisId.elements?.length) {
+                if (!thisId.elements || !thisId.elements.length) {
                     const splitRefIds = splitIds(liveId);
                     // element refs are cached
                     const refElements = [
@@ -213,13 +291,15 @@ export default class AriaObserver {
                         );
                     });
                 }
+
                 const newThisId = this.privateExtractCorrectElements(
                     thisId.refs,
                     thisId.elements
                 );
                 const newIds = this.privateExtractIds(newThisId);
-                // only fire calback if the value changed
-                if (newIds !== thisId.ids) {
+
+                // only fire callback if the value changed and the root node has been rendered
+                if (newIds.length && newIds !== thisId.ids) {
                     thisId.callback(newIds);
                     thisId.ids = newIds;
                 }
@@ -227,55 +307,6 @@ export default class AriaObserver {
         }
     }
 
-    privateUpdate(attrName) {
-        const { innerSelector } = this.state[attrName];
-        const elm = this.template.querySelector(innerSelector);
-        if (!elm) {
-            return; // nothing to update
-        }
-        let computedIds;
-        if (this.isNative) {
-            const { ids, content, placeholder } = this.state[attrName];
-
-            const newContent = extractContent(extractElements(this.root, ids));
-            if (content !== newContent) {
-                this.state[attrName].content = placeholder.textContent =
-                    newContent;
-            }
-            if (!placeholder.parentNode) {
-                // create placeholder container at template root, if not already exist
-                if (!this.placeholderContainer) {
-                    this.placeholderContainer = createPlaceholderContainer();
-                    this.template.appendChild(this.placeholderContainer);
-                }
-
-                // inserting the placeholder once
-                this.placeholderContainer.appendChild(placeholder);
-            }
-            computedIds = placeholder.id;
-        } else {
-            computedIds = this.state[attrName].ids;
-        }
-        addAriaRefWhenNeeded(elm, attrName, computedIds);
-    }
-
-    privateConnect() {
-        // caching root ref
-        this.root = this.template.host.getRootNode();
-        // creating the observer once
-        this.mo = new MutationObserver(() => {
-            if (!this.component.isConnected) {
-                return; // do nothing when the template is not connected
-            }
-            this.sync();
-        });
-        this.mo.observe(this.root, {
-            characterData: true,
-            childList: true,
-            subtree: true,
-        });
-    }
-
     disconnect() {
         // MutationObservers must be disconnected manually when using @lwc/synthetic-shadow
         // https://lwc.dev/guide/composition#:~:text=memory%20leak