fix(radio-button): allow standalone usage with checked prop

docs/src/pages/components/RadioButton.svx

@@ -11,6 +11,8 @@ components: ["RadioButtonGroup", "RadioButton", "RadioButtonSkeleton"]
 
 ## Default
 
+`RadioButton` is intended to be used within a `RadioButtonGroup`. See [Standalone usage](#standalone-usage) for individual usage.
+
 Create a group of radio buttons with a shared name and legend.
 
 <RadioButtonGroup legendText="Storage tier (disk)" name="plan" selected="standard">
@@ -19,6 +21,12 @@ Create a group of radio buttons with a shared name and legend.
   <RadioButton labelText="Pro (128 GB)" value="pro" />
 </RadioButtonGroup>
 
+## Standalone usage
+
+Use `RadioButton` individually with a bindable `checked` prop for simple use cases.
+
+<FileSource src="/framed/RadioButton/RadioButtonStandalone" />
+
 ## Hidden legend
 
 Visually hide the legend while maintaining accessibility.

docs/src/pages/framed/RadioButton/RadioButtonStandalone.svelte

@@ -0,0 +1,25 @@
+<script>
+  import { RadioButton, Button } from "carbon-components-svelte";
+
+  let agreedToTerms = false;
+</script>
+
+<div style:display="flex">
+  <RadioButton
+    bind:checked={agreedToTerms}
+    labelText="I agree to the terms and conditions"
+    name="terms"
+    value="agreed"
+  />
+</div>
+
+<div style:margin="var(--cds-layout-02) 0">
+  <Button
+    size="small"
+    kind="secondary"
+    disabled={!agreedToTerms}
+    on:click={() => (agreedToTerms = !agreedToTerms)}
+  >
+    Reset
+  </Button>
+</div>

src/RadioButton/RadioButton.svelte

@@ -53,7 +53,11 @@
     add({ id, checked, disabled, value });
   }
 
-  $: checked = $selectedValue === value;
+  // Only sync checked when inside RadioButtonGroup.
+  // This allows standalone `RadioButton` usage.
+  $: if (add) {
+    checked = $selectedValue === value;
+  }
 </script>
 
 <div
@@ -74,9 +78,12 @@
     on:focus
     on:blur
     on:change
-    on:change={() => {
+    on:change={(e) => {
       if (update) {
         update(value);
+      } else {
+        // Update `checked` for standalone `RadioButton` usage.
+        checked = e.currentTarget.checked;
       }
     }}
   />

tests/RadioButton/RadioButtonStandalone.test.svelte

@@ -0,0 +1,14 @@
+<svelte:options accessors />
+
+<script lang="ts">
+  import { RadioButton } from "carbon-components-svelte";
+
+  export let checked = false;
+</script>
+
+<RadioButton
+  bind:checked
+  value="standalone"
+  labelText="Standalone Option"
+  name="standalone-radio"
+/>

tests/RadioButton/RadioButtonStandalone.test.ts

@@ -0,0 +1,48 @@
+import { render, screen } from "@testing-library/svelte";
+import { user } from "../setup-tests";
+import RadioButtonStandalone from "./RadioButtonStandalone.test.svelte";
+
+describe("RadioButton (Standalone)", () => {
+  it("should allow checked prop to be updated programmatically when standalone", async () => {
+    const { component } = render(RadioButtonStandalone, {
+      props: { checked: false },
+    });
+
+    const input = screen.getByRole("radio") as HTMLInputElement;
+    expect(input).not.toBeChecked();
+
+    component.checked = true;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(input).toBeChecked();
+
+    component.checked = false;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(input).not.toBeChecked();
+  });
+
+  it("should bind checked state when user clicks standalone radio button", async () => {
+    const { component } = render(RadioButtonStandalone, {
+      props: { checked: false },
+    });
+
+    const input = screen.getByRole("radio");
+    expect(component.checked).toBe(false);
+
+    await user.click(input);
+
+    expect(component.checked).toBe(true);
+    expect(input).toBeChecked();
+  });
+
+  it("should support initial checked state for standalone radio button", () => {
+    const { component } = render(RadioButtonStandalone, {
+      props: { checked: true },
+    });
+
+    const input = screen.getByRole("radio");
+    expect(input).toBeChecked();
+    expect(component.checked).toBe(true);
+  });
+});