@spectrum-web-components/radio 1.3.1-beta.0 → 1.4.0

package/README.md

@@ -1,8 +1,6 @@
-## Description
+## Overview
 
-`<sp-radio>` and `<sp-radio-group>` allow users to select a single option from a list of mutually exclusive options. All possible options are exposed up front for users to compare.
-
-`<sp-radio-group>` holds a list of `<sp-radio>` elements, and is responsible for deselecting radio buttons when a new one is selected, which in turn makes it responsible for keeping track of which one is selected. `<sp-radio>` is responsible for handling user interactions and for visually reflecting if it is the one that is checked or not.
+`<sp-radio>` and [`<sp-radio-group>`](../radio-group) allow users to select a single option from a list of mutually exclusive options. All possible options are exposed up front for users to compare.
 
 ### Usage
 
@@ -10,34 +8,59 @@
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/radio?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/radio)
 [![Try it on webcomponents.dev](https://img.shields.io/badge/Try%20it%20on-webcomponents.dev-green?style=for-the-badge)](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/vUinRWkhayMTAmr9AK9J/src/index.ts)
 
-```
+```zsh
 yarn add @spectrum-web-components/radio
 ```
 
 Import the side effectful registration of `<sp-radio>` or `<sp-radio-group>` via:
 
-```
+```js
 import '@spectrum-web-components/radio/sp-radio.js';
 import '@spectrum-web-components/radio/sp-radio-group.js';
 ```
 
 When looking to leverage the `Radio` or `RadioGroup` base classes as a type and/or for extension purposes, do so via:
 
+```js
+import { Radio, RadioGroup } from '@spectrum-web-components/radio';
 ```
-import {
-    Radio,
-    RadioGroup
-} from '@spectrum-web-components/radio';
+
+### Anatomy
+
+`<sp-radio-group>` holds a list of `<sp-radio>` elements, and is responsible for deselecting radio buttons when a new one is selected, which in turn makes it responsible for keeping track of which one is selected. `<sp-radio>` is responsible for handling user interactions and for visually reflecting if it is the one that is checked or not.
+
+```html
+<sp-radio-group label="Choose an option" name="anatomy">
+    <sp-radio value="first">Option 1</sp-radio>
+    <sp-radio value="second">Option 2</sp-radio>
+    <sp-radio value="third">Option 3</sp-radio>
+    <sp-radio value="fourth">Option 4</sp-radio>
+</sp-radio-group>
 ```
 
-## Sizes
+#### Label
+
+The `<sp-radio>` elements are labelled with text in their default slot.
+
+```html
+<sp-radio-group label="Choose an option" name="anatomy">
+    <sp-radio value="first">Option 1</sp-radio>
+    <sp-radio value="second">Option 2</sp-radio>
+    <sp-radio value="third">Option 3</sp-radio>
+    <sp-radio value="fourth">Option 4</sp-radio>
+</sp-radio-group>
+```
+
+### Options
+
+#### Sizes
 
 <sp-tabs selected="m" auto label="Size Attribute Options">
 <sp-tab value="s">Small</sp-tab>
 <sp-tab-panel value="s">
 
 ```html
-<sp-radio-group label="Small" selected="first" name="example">
+<sp-radio-group label="Small" selected="first" name="small">
     <sp-radio value="first" size="s">Option 1</sp-radio>
     <sp-radio value="second" size="s">Option 2</sp-radio>
     <sp-radio value="third" size="s">Option 3</sp-radio>
@@ -50,7 +73,7 @@ import {
 <sp-tab-panel value="m">
 
 ```html
-<sp-radio-group label="Medium" selected="first" name="example">
+<sp-radio-group label="Medium" selected="first" name="medium">
     <sp-radio value="first" size="m">Option 1</sp-radio>
     <sp-radio value="second" size="m">Option 2</sp-radio>
     <sp-radio value="third" size="m">Option 3</sp-radio>
@@ -63,7 +86,7 @@ import {
 <sp-tab-panel value="l">
 
 ```html
-<sp-radio-group label="Large" selected="first" name="example">
+<sp-radio-group label="Large" selected="first" name="large">
     <sp-radio value="first" size="l">Option 1</sp-radio>
     <sp-radio value="second" size="l">Option 2</sp-radio>
     <sp-radio value="third" size="l">Option 3</sp-radio>
@@ -76,7 +99,7 @@ import {
 <sp-tab-panel value="xl">
 
 ```html
-<sp-radio-group label="Extra large" selected="first" name="example">
+<sp-radio-group label="Extra large" selected="first" name="extra-large">
     <sp-radio value="first" size="xl">Option 1</sp-radio>
     <sp-radio value="second" size="xl">Option 2</sp-radio>
     <sp-radio value="third" size="xl">Option 3</sp-radio>
@@ -87,13 +110,17 @@ import {
 </sp-tab-panel>
 </sp-tabs>
 
-### Standard radio buttons
+#### Styles
 
 Standard radio buttons are the default style for radio buttons. They are optimal for application panels where all visual elements are monochrome in order to direct focus to the content.
 
-Invalid selections in radio groups are identified using the `negative-help-text` slot. Read more about using [help text](#help-text) below.
+**Emphasized** radio buttons are a secondary style for radio buttons. The blue color provides a visual prominence that is optimal for forms, settings, etc. where the radio buttons need to be noticed.
+
+<sp-tabs selected="standard" auto label="Style Options">
+<sp-tab value="standard">Standard</sp-tab>
+<sp-tab-panel value="standard">
 
-```html-live
+```html
 <div style="display: flex; justify-content: space-between;">
     <div style="display: flex; flex-direction: column;">
         <sp-field-label for="example-1" size="l">
@@ -130,13 +157,11 @@ Invalid selections in radio groups are identified using the `negative-help-text`
 </div>
 ```
 
-### Emphasized radio buttons
-
-Emphasized radio buttons are a secondary style for radio buttons. The blue color provides a visual prominence that is optimal for forms, settings, etc. where the radio buttons need to be noticed.
-
-Invalid selections in radio groups are identified using the `negative-help-text` slot. Read more about using [help text](#help-text) below.
+</sp-tab-panel>
+<sp-tab value="emphasized">Emphasized</sp-tab>
+<sp-tab-panel value="emphasized">
 
-```html-live
+```html
 <div style="display: flex; justify-content: space-between;">
     <div style="display: flex; flex-direction: column;">
         <sp-field-label for="example-a" size="l">
@@ -173,7 +198,12 @@ Invalid selections in radio groups are identified using the `negative-help-text`
 </div>
 ```
 
-### Handling events
+</sp-tab-panel>
+</sp-tabs>
+
+### Behaviors
+
+#### Handling events
 
 Event handlers for clicks and other user actions can be registered on an `<sp-radio>` similar to a standard `<input type="radio">` element.
 
@@ -183,64 +213,10 @@ Event handlers for clicks and other user actions can be registered on an `<sp-ra
 </sp-radio>
 ```
 
-## Help text
-
-Help text can be accessibly associated with an `<sp-radio-group>` element by using the `help-text` or `negative-help-text` slots. When using the `negative-help-text` slot, `<sp-radio-group>` will self manage the presence of this content based on the value of the `invalid` property on your `<sp-radio-group>` element. Content within the `help-text` slot will be show by default. When your `<sp-radio-group>` should receive help text based on state outside of the complexity of `invalid` or not, manage the content addressed to the `help-text` from above to ensure that it displays the right messaging and possesses the right `variant`.
-
-<sp-tabs selected="self" auto label="Help text usage in radio groups">
-<sp-tab value="self">Self managed</sp-tab>
-<sp-tab-panel value="self">
-
-```html
-<sp-field-label for="self">
-    What is your favorite ice cream flavor?
-</sp-field-label>
-<sp-radio-group
-    id="self"
-    onchange="
-        this.invalid = this.selected === 'fourth';
-    "
->
-    <sp-radio value="first">Vanilla</sp-radio>
-    <sp-radio value="second">Chocolate</sp-radio>
-    <sp-radio value="third">Strawberry</sp-radio>
-    <sp-radio value="fourth">I don't like ice cream</sp-radio>
-    <sp-help-text slot="help-text">Everyone likes ice cream.</sp-help-text>
-    <sp-help-text slot="negative-help-text" icon>
-        You can't not like ice cream.
-    </sp-help-text>
-</sp-radio-group>
-```
-
-</sp-tab-panel>
-<sp-tab value="above">Managed from above</sp-tab>
-<sp-tab-panel value="above">
-
-```html
-<sp-field-label for="managed">
-    What is your favorite ice cream flavor?
-</sp-field-label>
-<sp-radio-group
-    id="managed"
-    onchange="
-        const helpText = this.querySelector(`[slot='help-text']`);
-        const isInvalid = this.selected === 'fourth';
-        helpText.icon = isInvalid;
-        helpText.textContent = isInvalid ? 'You can\'t not like ice cream.' : 'Everyone likes ice cream.';
-        helpText.variant = isInvalid ? 'negative' : 'neutral';
-    "
->
-    <sp-radio value="first">Vanilla</sp-radio>
-    <sp-radio value="second">Chocolate</sp-radio>
-    <sp-radio value="third">Strawberry</sp-radio>
-    <sp-radio value="fourth">I don't like ice cream</sp-radio>
-    <sp-help-text slot="help-text">Everyone likes ice cream.</sp-help-text>
-</sp-radio-group>
-```
+### Accessibility
 
-</sp-tab-panel>
-</sp-tabs>
+Tabbing into a group of radio buttons places the focus on the first radio button selected. If none of the radio buttons are selected, the focus is set on the first one in the group. Space selects the radio button in focus (if not already selected). Using the arrow keys moves focus and selection to the previous or next radio button in the group (last becomes first, and first becomes last). The new radio button in focus gets selected even if the previous one was not.
 
-## Accessibility
+#### Provide a label
 
-Radio buttons are accessible by default, rendered in HTML using the `<input type="radio">` element. Tabbing into a group of radio buttons places the focus on the first radio button selected. If none of the radio buttons are selected, the focus is set on the first one in the group. Space selects the radio button in focus (if not already selected). Using the arrow keys moves focus and selection to the previous or next radio button in the group (last becomes first, and first becomes last). The new radio button in focus gets selected even if the previous one was not.
+Radio groups and radio items should always have labels.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@spectrum-web-components/radio",
-    "version": "1.3.1-beta.0",
+    "version": "1.4.0",
     "publishConfig": {
         "access": "public"
     },
@@ -66,11 +66,11 @@
         "lit-html"
     ],
     "dependencies": {
-        "@spectrum-web-components/base": "1.3.1-beta.0",
-        "@spectrum-web-components/field-group": "1.3.1-beta.0",
-        "@spectrum-web-components/help-text": "1.3.1-beta.0",
-        "@spectrum-web-components/reactive-controllers": "1.3.1-beta.0",
-        "@spectrum-web-components/shared": "1.3.1-beta.0"
+        "@spectrum-web-components/base": "1.4.0",
+        "@spectrum-web-components/field-group": "1.4.0",
+        "@spectrum-web-components/help-text": "1.4.0",
+        "@spectrum-web-components/reactive-controllers": "1.4.0",
+        "@spectrum-web-components/shared": "1.4.0"
     },
     "devDependencies": {
         "@spectrum-css/radio": "10.0.0-s2-foundations.17"