From 271b6bbcc8361e05e663ec3ab16dfbf8f6aec300 Mon Sep 17 00:00:00 2001
From: Cory LaViska <cory@abeautifulsite.net>
Date: Thu, 27 Apr 2023 13:17:54 -0400
Subject: [PATCH] update docs; fixes #1315

---
 docs/components/radio-button.md | 70 +++++++++++++++++----------------
 docs/components/radio-group.md  | 47 ++++++++++++++++++++++
 docs/components/radio.md        | 48 ++++++++++++++++++----
 3 files changed, 124 insertions(+), 41 deletions(-)

diff --git a/docs/components/radio-button.md b/docs/components/radio-button.md
index 9a24ec8c07..d3619d8161 100644
--- a/docs/components/radio-button.md
+++ b/docs/components/radio-button.md
@@ -78,29 +78,29 @@ const App = () => (
 
 ### Sizes
 
-Use the `size` attribute to change a radio button's size.
+Add the `size` attribute to the [Radio Group](/components/radio-group) to change the size of the radio buttons.
 
 ```html preview
-<sl-radio-group label="Select an option" name="a" value="1">
-  <sl-radio-button size="small" value="1">Option 1</sl-radio-button>
-  <sl-radio-button size="small" value="2">Option 2</sl-radio-button>
-  <sl-radio-button size="small" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" size="small" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2">Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 
 <br />
 
-<sl-radio-group label="Select an option" name="a" value="1">
-  <sl-radio-button size="medium" value="1">Option 1</sl-radio-button>
-  <sl-radio-button size="medium" value="2">Option 2</sl-radio-button>
-  <sl-radio-button size="medium" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" size="medium" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2">Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 
 <br />
 
-<sl-radio-group label="Select an option" name="a" value="1">
-  <sl-radio-button size="large" value="1">Option 1</sl-radio-button>
-  <sl-radio-button size="large" value="2">Option 2</sl-radio-button>
-  <sl-radio-button size="large" value="3">Option 3</sl-radio-button>
+<sl-radio-group label="Select an option" size="large" value="1">
+  <sl-radio-button value="1">Option 1</sl-radio-button>
+  <sl-radio-button value="2">Option 2</sl-radio-button>
+  <sl-radio-button value="3">Option 3</sl-radio-button>
 </sl-radio-group>
 ```
 
@@ -108,27 +108,29 @@ Use the `size` attribute to change a radio button's size.
 import { SlRadioButton, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
-  <SlRadioGroup label="Select an option" name="a" value="1">
-    <SlRadioButton size="small" value="1">Option 1</SlRadioButton>
-    <SlRadioButton size="small" value="2">Option 2</SlRadioButton>
-    <SlRadioButton size="small" value="3">Option 3</SlRadioButton>
-  </SlRadioGroup>
-
-  <br />
-
-  <SlRadioGroup label="Select an option" name="a" value="1">
-    <SlRadioButton size="medium" value="1">Option 1</SlRadioButton>
-    <SlRadioButton size="medium" value="2">Option 2</SlRadioButton>
-    <SlRadioButton size="medium" value="3">Option 3</SlRadioButton>
-  </SlRadioGroup>
-
-  <br />
-
-  <SlRadioGroup label="Select an option" name="a" value="1">
-    <SlRadioButton size="large" value="1">Option 1</SlRadioButton>
-    <SlRadioButton size="large" value="2">Option 2</SlRadioButton>
-    <SlRadioButton size="large" value="3">Option 3</SlRadioButton>
-  </SlRadioGroup>
+  <>
+    <SlRadioGroup label="Select an option" size="small" value="1">
+      <SlRadioButton value="1">Option 1</SlRadioButton>
+      <SlRadioButton value="2">Option 2</SlRadioButton>
+      <SlRadioButton value="3">Option 3</SlRadioButton>
+    </SlRadioGroup>
+
+    <br />
+
+    <SlRadioGroup label="Select an option" size="medium" value="1">
+      <SlRadioButton value="1">Option 1</SlRadioButton>
+      <SlRadioButton value="2">Option 2</SlRadioButton>
+      <SlRadioButton value="3">Option 3</SlRadioButton>
+    </SlRadioGroup>
+
+    <br />
+
+    <SlRadioGroup label="Select an option" size="large" value="1">
+      <SlRadioButton value="1">Option 1</SlRadioButton>
+      <SlRadioButton value="2">Option 2</SlRadioButton>
+      <SlRadioButton value="3">Option 3</SlRadioButton>
+    </SlRadioGroup>
+  </>
 );
 ```
 
diff --git a/docs/components/radio-group.md b/docs/components/radio-group.md
index 20d99d82d3..3f859ec93a 100644
--- a/docs/components/radio-group.md
+++ b/docs/components/radio-group.md
@@ -98,6 +98,53 @@ const App = () => (
 );
 ```
 
+### Sizing Options
+
+The size of [Radios](/components/radio) and [Radio Buttons](/components/radio-buttons) will be determined by the Radio Group's `size` attribute.
+
+```html preview
+<sl-radio-group label="Select an option" size="medium" value="medium" class="radio-group-size">
+  <sl-radio value="small">Small</sl-radio>
+  <sl-radio value="medium">Medium</sl-radio>
+  <sl-radio value="large">Large</sl-radio>
+</sl-radio-group>
+
+<script>
+  const radioGroup = document.querySelector('.radio-group-size');
+
+  radioGroup.addEventListener('sl-change', () => {
+    radioGroup.size = radioGroup.value;
+  });
+</script>
+```
+
+```jsx react
+import { useState } from 'react';
+import { SlRadio, SlRadioGroup } from '@shoelace-style/shoelace/dist/react';
+
+const App = () => {
+  const [size, setSize] = useState('medium');
+
+  return (
+    <>
+      <SlRadioGroup
+        label="Select an option"
+        size={size}
+        value={size}
+        class="radio-group-size"
+        onSlChange={event => setSize(event.target.value)}
+      >
+        <SlRadio value="small">Small</SlRadio>
+        <SlRadio value="medium">Medium</SlRadio>
+        <SlRadio value="large">Large</SlRadio>
+      </SlRadioGroup>
+    </>
+  );
+};
+```
+
+?> [Radios](/components/radio) and [Radio Buttons](/components/radio-button) also have a `size` attribute. This can be useful in certain compositions, but it will be ignored when used inside of a Radio Group.
+
 ### Validation
 
 Setting the `required` attribute to make selecting an option mandatory. If a value has not been selected, it will prevent the form from submitting and display an error message.
diff --git a/docs/components/radio.md b/docs/components/radio.md
index 003260d403..bfba74b0e6 100644
--- a/docs/components/radio.md
+++ b/docs/components/radio.md
@@ -80,12 +80,30 @@ const App = () => (
 
 ## Sizes
 
-Use the `size` attribute to change a radio's size.
+Add the `size` attribute to the [Radio Group](/components/radio-group) to change the size of the radios.
 
 ```html preview
-<sl-radio size="small">Small</sl-radio>
-<sl-radio size="medium">Medium</sl-radio>
-<sl-radio size="large">Large</sl-radio>
+<sl-radio-group label="Select an option" size="small" value="1">
+  <sl-radio value="1">Small 1</sl-radio>
+  <sl-radio value="2">Small 2</sl-radio>
+  <sl-radio value="3">Small 3</sl-radio>
+</sl-radio-group>
+
+<br />
+
+<sl-radio-group label="Select an option" size="medium" value="1">
+  <sl-radio value="1">Medium 1</sl-radio>
+  <sl-radio value="2">Medium 2</sl-radio>
+  <sl-radio value="3">Medium 3</sl-radio>
+</sl-radio-group>
+
+<br />
+
+<sl-radio-group label="Select an option" size="large" value="1">
+  <sl-radio value="1">Large 1</sl-radio>
+  <sl-radio value="2">Large 2</sl-radio>
+  <sl-radio value="3">Large 3</sl-radio>
+</sl-radio-group>
 ```
 
 ```jsx react
@@ -93,11 +111,27 @@ import { SlRadio } from '@shoelace-style/shoelace/dist/react';
 
 const App = () => (
   <>
-    <SlRadio size="small">Small</SlRadio>
+    <SlRadioGroup size="small" value="1">
+      <SlRadio value="1">Small 1</SlRadio>
+      <SlRadio value="2">Small 2</SlRadio>
+      <SlRadio value="3">Small 3</SlRadio>
+    </SlRadioGroup>
+
     <br />
-    <SlRadio size="medium">Medium</SlRadio>
+
+    <SlRadioGroup size="medium" value="1">
+      <SlRadio value="1">Medium 1</SlRadio>
+      <SlRadio value="2">Medium 2</SlRadio>
+      <SlRadio value="3">Medium 3</SlRadio>
+    </SlRadioGroup>
+
     <br />
-    <SlRadio size="large">Large</SlRadio>
+
+    <SlRadioGroup size="large" value="1">
+      <SlRadio value="1">Large 1</SlRadio>
+      <SlRadio value="2">Large 2</SlRadio>
+      <SlRadio value="3">Large 3</SlRadio>
+    </SlRadioGroup>
   </>
 );
 ```