feat(toggle): add ref prop (#2252)

Closes #2218

Author: metonym

COMPONENT_INDEX.md

@@ -4390,17 +4390,18 @@ export type CarbonTheme = "white" | "g10" | "g80" | "g90" | "g100";
 
 ### Props
 
-| Prop name | Required | Kind             | Reactive | Type                               | Default value                                    | Description                                     |
-| :-------- | :------- | :--------------- | :------- | ---------------------------------- | ------------------------------------------------ | ----------------------------------------------- |
-| toggled   | No       | <code>let</code> | Yes      | <code>boolean</code>               | <code>false</code>                               | Set to `true` to toggle the checkbox input      |
-| size      | No       | <code>let</code> | No       | <code>"default" &#124; "sm"</code> | <code>"default"</code>                           | Specify the toggle size                         |
-| disabled  | No       | <code>let</code> | No       | <code>boolean</code>               | <code>false</code>                               | Set to `true` to disable checkbox input         |
-| labelA    | No       | <code>let</code> | No       | <code>string</code>                | <code>"Off"</code>                               | Specify the label for the untoggled state       |
-| labelB    | No       | <code>let</code> | No       | <code>string</code>                | <code>"On"</code>                                | Specify the label for the toggled state         |
-| labelText | No       | <code>let</code> | No       | <code>string</code>                | <code>""</code>                                  | Specify the label text                          |
-| hideLabel | No       | <code>let</code> | No       | <code>boolean</code>               | <code>false</code>                               | Set to `true` to visually hide the label text   |
-| id        | No       | <code>let</code> | No       | <code>string</code>                | <code>"ccs-" + Math.random().toString(36)</code> | Set an id for the input element                 |
-| name      | No       | <code>let</code> | No       | <code>string</code>                | <code>undefined</code>                           | Specify a name attribute for the checkbox input |
+| Prop name | Required | Kind             | Reactive | Type                                      | Default value                                    | Description                                     |
+| :-------- | :------- | :--------------- | :------- | ----------------------------------------- | ------------------------------------------------ | ----------------------------------------------- |
+| ref       | No       | <code>let</code> | Yes      | <code>null &#124; HTMLInputElement</code> | <code>null</code>                                | Obtain a reference to the input HTML element    |
+| toggled   | No       | <code>let</code> | Yes      | <code>boolean</code>                      | <code>false</code>                               | Set to `true` to toggle the checkbox input      |
+| size      | No       | <code>let</code> | No       | <code>"default" &#124; "sm"</code>        | <code>"default"</code>                           | Specify the toggle size                         |
+| disabled  | No       | <code>let</code> | No       | <code>boolean</code>                      | <code>false</code>                               | Set to `true` to disable checkbox input         |
+| labelA    | No       | <code>let</code> | No       | <code>string</code>                       | <code>"Off"</code>                               | Specify the label for the untoggled state       |
+| labelB    | No       | <code>let</code> | No       | <code>string</code>                       | <code>"On"</code>                                | Specify the label for the toggled state         |
+| labelText | No       | <code>let</code> | No       | <code>string</code>                       | <code>""</code>                                  | Specify the label text                          |
+| hideLabel | No       | <code>let</code> | No       | <code>boolean</code>                      | <code>false</code>                               | Set to `true` to visually hide the label text   |
+| id        | No       | <code>let</code> | No       | <code>string</code>                       | <code>"ccs-" + Math.random().toString(36)</code> | Set an id for the input element                 |
+| name      | No       | <code>let</code> | No       | <code>string</code>                       | <code>undefined</code>                           | Specify a name attribute for the checkbox input |
 
 ### Slots
 

docs/src/COMPONENT_API.json

@@ -16858,6 +16858,18 @@
           "isRequired": false,
           "constant": false,
           "reactive": false
+        },
+        {
+          "name": "ref",
+          "kind": "let",
+          "description": "Obtain a reference to the input HTML element",
+          "type": "null | HTMLInputElement",
+          "value": "null",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": true
         }
       ],
       "moduleExports": [],

src/Toggle/Toggle.svelte

@@ -36,11 +36,12 @@
    */
   export let name = undefined;
 
+  /** Obtain a reference to the input HTML element */
+  export let ref = null;
+
   import { createEventDispatcher } from "svelte";
 
   const dispatch = createEventDispatcher();
-
-  let ref = null;
 </script>
 
 <!-- svelte-ignore a11y-mouse-events-have-key-events -->

tests/Toggle/Toggle.test.svelte

@@ -1,12 +1,16 @@
+<svelte:options accessors />
+
 <script lang="ts">
   import { Toggle } from "carbon-components-svelte";
 
   let toggled = false;
   let initialToggled = true;
+  export let ref: HTMLInputElement | null = null;
 </script>
 
 <Toggle
   bind:toggled
+  bind:ref
   labelText="Default toggle"
   on:toggle={(e) => {
     console.log("toggled:", e.detail.toggled);

tests/Toggle/Toggle.test.ts

@@ -269,4 +269,12 @@ describe("Toggle", () => {
 
     expect(screen.getByText("On slot")).toBeInTheDocument();
   });
+
+  it("should bind ref to input element", () => {
+    const { component } = render(Toggle);
+
+    expect(component.ref).toBeInstanceOf(HTMLInputElement);
+    assert(component.ref);
+    expect(component.ref.type).toBe("checkbox");
+  });
 });

types/Toggle/Toggle.svelte.d.ts

@@ -58,6 +58,12 @@ type $Props = {
    */
   name?: string;
 
+  /**
+   * Obtain a reference to the input HTML element
+   * @default null
+   */
+  ref?: null | HTMLInputElement;
+
   [key: `data-${string}`]: any;
 };