feat(toggle): allow to be labelled by another element

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -8498,6 +8498,9 @@ Map {
   },
   "Toggle" => Object {
     "propTypes": Object {
+      "aria-labelledby": Object {
+        "type": "string",
+      },
       "className": Object {
         "type": "string",
       },
@@ -8520,10 +8523,7 @@ Map {
       "labelB": Object {
         "type": "node",
       },
-      "labelText": Object {
-        "isRequired": true,
-        "type": "node",
-      },
+      "labelText": [Function],
       "onClick": Object {
         "type": "func",
       },

packages/react/src/components/Toggle/Toggle-test.js

@@ -88,10 +88,28 @@ describe('Toggle', () => {
           .classList.contains(`${prefix}--visually-hidden`)
       ).toBe(true);
       expect(
-        wrapper.container.querySelector(`.${prefix}--toggle__label-text`)
-          .textContent
+        wrapper.container.querySelector(`.${prefix}--toggle__text`).textContent
       ).toBe(props.labelText);
     });
+
+    it("doesn't render sideLabel if props.hideLabel and props['aria-labelledby'] are provided", () => {
+      const externalElementId = 'external-element-id';
+      wrapper.rerender(
+        <Toggle {...props} hideLabel aria-labelledby={externalElementId} />
+      );
+
+      expect(
+        wrapper.container.querySelector(`.${prefix}--toggle__text`)
+      ).toBeNull();
+
+      expect(wrapper.getByRole('switch').getAttribute('aria-labelledby')).toBe(
+        externalElementId
+      );
+
+      expect(
+        wrapper.container.querySelector(`.${prefix}--toggle__label`).tagName
+      ).toBe('DIV');
+    });
   });
 
   describe('behaves as expected', () => {

packages/react/src/components/Toggle/Toggle.js

@@ -12,6 +12,7 @@ import { useControllableState } from '../../internal/useControllableState';
 import { usePrefix } from '../../internal/usePrefix';
 
 export function Toggle({
+  'aria-labelledby': ariaLabelledby,
   className,
   defaultToggled = false,
   disabled = false,
@@ -45,6 +46,8 @@ export function Toggle({
 
   const isSm = size === 'sm';
   const sideLabel = hideLabel ? labelText : checked ? labelB : labelA;
+  const renderSideLabel = !(hideLabel && ariaLabelledby);
+  const LabelComponent = ariaLabelledby ? 'div' : 'label';
 
   const wrapperClasses = classNames(
     `${prefix}--toggle`,
@@ -76,11 +79,14 @@ export function Toggle({
         role="switch"
         type="button"
         aria-checked={checked}
+        aria-labelledby={ariaLabelledby}
         disabled={disabled}
         onClick={handleClick}
       />
-      <label htmlFor={id} className={`${prefix}--toggle__label`}>
-        <span className={labelTextClasses}>{labelText}</span>
+      <LabelComponent
+        htmlFor={ariaLabelledby ? null : id}
+        className={`${prefix}--toggle__label`}>
+        {labelText && <span className={labelTextClasses}>{labelText}</span>}
         <div className={appearanceClasses}>
           <div className={switchClasses}>
             {isSm && (
@@ -93,16 +99,23 @@ export function Toggle({
               </svg>
             )}
           </div>
-          <span className={`${prefix}--toggle__text`} aria-hidden="true">
-            {sideLabel}
-          </span>
+          {renderSideLabel && (
+            <span className={`${prefix}--toggle__text`} aria-hidden="true">
+              {sideLabel}
+            </span>
+          )}
         </div>
-      </label>
+      </LabelComponent>
     </div>
   );
 }
 
 Toggle.propTypes = {
+  /**
+   * Specify another element's id to be used as the label for this toggle
+   */
+  'aria-labelledby': PropTypes.string,
+
   /**
    * Specify a custom className to apply to the form-item node
    */
@@ -140,9 +153,17 @@ Toggle.propTypes = {
 
   /**
    * Provide the text that will be read by a screen reader when visiting this
-   * control
+   * control. This is required unless 'aria-labelledby' is provided instead
    */
-  labelText: PropTypes.node.isRequired,
+  labelText: (props, ...rest) => {
+    if (!props['aria-labelledby'] && !props.labelText) {
+      return new Error(
+        'labelText property is required if no aria-labelledby is provided.'
+      );
+    }
+
+    return PropTypes.node(props, ...rest);
+  },
 
   /**
    * Provide an event listener that is called when the control is clicked

packages/react/src/components/Toggle/Toggle.stories.js

@@ -35,14 +35,7 @@ export const SmallToggle = () => (
 );
 
 export const Playground = (args) => (
-  <Toggle
-    labelText="Toggle element label"
-    labelA="Off"
-    labelB="On"
-    defaultToggled
-    id="toggle-1"
-    {...args}
-  />
+  <Toggle labelA="Off" labelB="On" defaultToggled id="toggle-1" {...args} />
 );
 
 Playground.argTypes = {