Adds Radio and RadioGroup as new web components

change/@fluentui-web-components-94ca1c7a-1462-4aa5-9458-41a54f17527e.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat(radio): add radio and radio-group web components",
+  "packageName": "@fluentui/web-components",
+  "email": "brianbrady@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/web-components/package.json

@@ -76,6 +76,14 @@
       "types": "./dist/esm/progress-bar/define.d.ts",
       "default": "./dist/esm/progress-bar/define.js"
     },
+    "./radio": {
+      "types": "./dist/esm/radio/define.d.ts",
+      "default": "./dist/esm/radio/define.js"
+    },
+    "./radio-group": {
+      "types": "./dist/esm/radio-group/define.d.ts",
+      "default": "./dist/esm/radio-group/define.js"
+    },
     "./slider": {
       "types": "./dist/esm/slider/define.d.ts",
       "default": "./dist/esm/slider/define.js"

packages/web-components/src/index.ts

@@ -11,6 +11,8 @@ export * from './image/index.js';
 export * from './label/index.js';
 export * from './menu-button/index.js';
 export * from './progress-bar/index.js';
+export * from './radio/index.js';
+export * from './radio-group/index.js';
 export * from './slider/index.js';
 export * from './spinner/index.js';
 export * from './switch/index.js';

packages/web-components/src/radio-group/README.md

@@ -1,6 +1,6 @@
 # Radio Group
 
-> RadioGroup lets people select a single option from two or more Radio items. Use RadioGroup to present all available choices if there's enough space..
+> RadioGroup lets users select a single option from two or more Radio items. Use RadioGroup to present all available choices if there's enough space..
 
 <br />
 
@@ -36,13 +36,14 @@ Used anywhere an author might group a list of radio options.
 
 ### **Fields**
 
-| Name          | Privacy | Type                     | Default      | Description                                                                                           |
-| ------------- | ------- | ------------------------ | ------------ | ----------------------------------------------------------------------------------------------------- |
-| `disabled`    | public  | `boolean`                | `false`      | Disables the radio group and child radios.                                                            |
-| `name`        | public  | `string`                 |              | The name of the radio group. Setting this value will set the name value for all child radio elements. |
-| `value`       | public  | `string`                 |              | The value of the checked radio.                                                                       |
-| `orientation` | public  | `horizontal \| vertical` | `horizontal` | The orientation of the group                                                                          |
-| default slot  | public  | `HTMLElement[]`          |              | The default slot expecting Radio items                                                                |
+| Name          | Privacy | Type                     | Default      | Description                                                                                                                                                                                                                                                                                                                                         |
+| ------------- | ------- | ------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `disabled`    | public  | `boolean`                | `false`      | Disables the radio group and child radios.                                                                                                                                                                                                                                                                                                          |
+| `name`        | public  | `string`                 |              | The name of the radio group. Setting this value will set the name value for all child radio elements.                                                                                                                                                                                                                                               |
+| `value`       | public  | `string`                 |              | The value of the checked radio.                                                                                                                                                                                                                                                                                                                     |
+| `orientation` | public  | `horizontal \| vertical` | `horizontal` | The orientation of the group                                                                                                                                                                                                                                                                                                                        |
+| `stacked`     | public  | `boolean`                | `false`      | When the orientation attribute is set to `horizontal`, `stacked` arranges each radio item in a row, with the labels displayed beneath the radio indicators. However, when the orientation is set to `vertical` and the stacked attribute is also present, the stacked styles will be overridden, and the default `vertical` layout will be applied. |
+| default slot  | public  | `HTMLElement[]`          |              | The default slot expecting Radio items                                                                                                                                                                                                                                                                                                              |
 
 <br />
 
@@ -57,9 +58,9 @@ Used anywhere an author might group a list of radio options.
 
 ### **Events**
 
-| Name     | Type | Description                                          |
-| -------- | ---- | ---------------------------------------------------- |
-| `change` |      | Fires a custom 'change' event when the value changes |
+| Name     | Event Type    | Target           | Arguments | Description                                                                                                       |
+| -------- | ------------- | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
+| `change` | `CustomEvent` | `FASTRadioGroup` | none      | Fired when the value of the RadioGroup changes (i.e., when a different radio button within the group is selected) |
 
 <br />
 
@@ -97,9 +98,10 @@ Used anywhere an author might group a list of radio options.
 
 ### **WAI-ARIA Roles, States, and Properties**
 
-| Attributes        | value | Description                              |
-| ----------------- | ----- | ---------------------------------------- |
-| `aria-labelledby` |       | used to associate a label with the group |
+| Attributes        | value          | Description                              |
+| ----------------- | -------------- | ---------------------------------------- |
+| `aria-labelledby` |                | used to associate a label with the group |
+| `role`            | `"radiogroup"` | used to define a group of radio buttons  |
 
 <br />
 <hr />
@@ -122,6 +124,6 @@ Used anywhere an author might group a list of radio options.
 <br />
 
 **Property Mapping**
-| Fluent UI React 9 | Fluent Web Components 3 | Description of difference |
-|-------------------|------------------------ |---------------------------|
-| `layout` | `orientation` | React implementation requires user to pass either `"horizontal"` or `"horizontal-stacked"` through `layout` prop. <br /> WC3 implementation requires user to either pass `"vertical"` or "`horizontal"` through `orientation` attribute.
+| Fluent UI React 9 | Fluent Web Components | Description of difference |
+|-------------------|-------------------------- |---------------------------|
+| `layout` | `orientation` + `stacked` | React implementation requires user to pass either `"horizontal"` or `"horizontal-stacked"` through `layout` prop. <br /> WC3 implementation requires user to either pass `"vertical"` or "`horizontal"` through `orientation` attribute. Additionally, adding the `boolean` attribute `stacked` when the orientation is set to `horizontal` will create the `horizontal-stacked` layout available in FUIR9.

packages/web-components/src/radio-group/define.ts

@@ -0,0 +1,4 @@
+import { FluentDesignSystem } from '../fluent-design-system.js';
+import { definition } from './radio-group.definition.js';
+
+definition.define(FluentDesignSystem.registry);

packages/web-components/src/radio-group/index.ts

@@ -0,0 +1,5 @@
+export * from './radio-group.js';
+export { definition as RadioGroupDefinition } from './radio-group.definition.js';
+export { styles as RadioGroupStyles } from './radio-group.styles.js';
+export { template as RadioGroupTemplate } from './radio-group.template.js';
+export { RadioGroupOrientation } from '@microsoft/fast-foundation';

packages/web-components/src/radio-group/radio-group.definition.ts

@@ -0,0 +1,18 @@
+import { FluentDesignSystem } from '../fluent-design-system.js';
+import { RadioGroup } from './radio-group.js';
+import { styles } from './radio-group.styles.js';
+import { template } from './radio-group.template.js';
+
+/**
+ * The Fluent RadioGroup Element.
+ *
+ *
+ * @public
+ * @remarks
+ * HTML Element: \<fluent-radio-group\>
+ */
+export const definition = RadioGroup.compose({
+  name: `${FluentDesignSystem.prefix}-radio-group`,
+  template,
+  styles,
+});

packages/web-components/src/radio-group/radio-group.stories.ts

@@ -0,0 +1,200 @@
+import { html } from '@microsoft/fast-element';
+import type { Args, Meta } from '@storybook/html';
+import { RadioGroupOrientation } from '@microsoft/fast-foundation';
+import { renderComponent } from '../helpers.stories.js';
+import { RadioGroup as FluentRadioGroup } from './radio-group.js';
+import './define.js';
+import '../radio/define.js';
+
+type RadioGroupStoryArgs = Args & FluentRadioGroup;
+type RadioGroupStoryMeta = Meta<RadioGroupStoryArgs>;
+
+const storyTemplate = html<RadioGroupStoryArgs>`
+  <fluent-radio-group
+    aria-labelledby="label-1"
+    ?disabled=${x => x.disabled}
+    ?stacked=${x => x.stacked}
+    orientation=${x => x.orientation}
+    name="radio-story"
+  >
+    <span id="label-1" slot="label">Favorite Fruit</span>
+    <fluent-radio value="apple">Apple</fluent-radio>
+    <fluent-radio value="pear">Pear</fluent-radio>
+    <fluent-radio value="banana">Banana</fluent-radio>
+    <fluent-radio value="orange">Orange</fluent-radio>
+  </fluent-radio-group>
+`;
+
+export default {
+  title: 'Components/RadioGroup',
+  args: {
+    disabled: false,
+    orientation: RadioGroupOrientation.horizontal,
+  },
+  argTypes: {
+    disabled: {
+      control: {
+        type: 'boolean',
+      },
+      table: {
+        type: {
+          summary: 'Sets disabled state on radio',
+        },
+        defaultValue: {
+          summary: 'false',
+        },
+      },
+    },
+    stacked: {
+      control: {
+        type: 'boolean',
+      },
+      table: {
+        type: {
+          summary: 'Creates a stacked layout for horizontal radio buttons',
+        },
+        defaultValue: {
+          summary: 'false',
+        },
+      },
+    },
+    orientation: {
+      control: {
+        type: 'select',
+        options: Object.values(RadioGroupOrientation),
+      },
+      defaultValue: RadioGroupOrientation.horizontal,
+      table: {
+        type: {
+          summary: 'Sets orientation of radio group',
+        },
+        defaultValue: {
+          summary: RadioGroupOrientation.horizontal,
+        },
+      },
+    },
+    change: {
+      action: 'change',
+      table: {
+        type: {
+          summary: 'Event that is fired when the selected radio button changes',
+        },
+        defaultValue: {
+          summary: null,
+        },
+      },
+    },
+  },
+} as RadioGroupStoryMeta;
+
+export const RadioGroup = renderComponent(storyTemplate).bind({});
+
+export const RadioGroupLabelledby = renderComponent(html<RadioGroupStoryArgs>`
+  <fluent-radio-group aria-labelledby="label-2" name="radio-story">
+    <span id="label-2" slot="label">Favorite Fruit</span>
+    <fluent-radio value="apple">Apple</fluent-radio>
+    <fluent-radio value="pear">Pear</fluent-radio>
+    <fluent-radio value="banana">Banana</fluent-radio>
+    <fluent-radio value="orange">Orange</fluent-radio>
+  </fluent-radio-group>
+`);
+
+export const RadioGroupLayoutVertical = renderComponent(html<RadioGroupStoryArgs>`
+  <fluent-radio-group aria-labelledby="label-3" orientation="vertical" name="radio-story">
+    <span id="label-3" slot="label">Favorite Fruit</span>
+    <fluent-radio value="apple">Apple</fluent-radio>
+    <fluent-radio value="pear">Pear</fluent-radio>
+    <fluent-radio value="banana">Banana</fluent-radio>
+    <fluent-radio value="orange">Orange</fluent-radio>
+  </fluent-radio-group>
+`);
+
+export const RadioGroupLayoutHorizontal = renderComponent(html<RadioGroupStoryArgs>`
+  <fluent-radio-group aria-labelledby="label-4" orientation="horizontal" name="radio-story">
+    <span id="label-4" slot="label">Favorite Fruit</span>
+    <fluent-radio value="apple">Apple</fluent-radio>
+    <fluent-radio value="pear">Pear</fluent-radio>
+    <fluent-radio value="banana">Banana</fluent-radio>
+    <fluent-radio value="orange">Orange</fluent-radio>
+  </fluent-radio-group>
+`);
+
+export const RadioGroupLayoutHorizontalStacked = renderComponent(html<RadioGroupStoryArgs>`
+  <fluent-radio-group stacked aria-labelledby="label-5" orientation="horizontal" name="radio-story">
+    <span id="label-5" slot="label">Favorite Fruit</span>
+    <fluent-radio value="apple">Apple</fluent-radio>
+    <fluent-radio value="pear">Pear</fluent-radio>
+    <fluent-radio value="banana">Banana</fluent-radio>
+    <fluent-radio value="orange">Orange</fluent-radio>
+  </fluent-radio-group>
+`);
+
+export const RadioGroupDefaultChecked = renderComponent(html<RadioGroupStoryArgs>`
+  <fluent-radio-group aria-labelledby="label-6" orientation="horizontal" name="radio-story">
+    <span id="label-6" slot="label">Favorite Fruit</span>
+    <fluent-radio value="apple">Apple</fluent-radio>
+    <fluent-radio checked value="pear">Pear</fluent-radio>
+    <fluent-radio value="banana">Banana</fluent-radio>
+    <fluent-radio value="orange">Orange</fluent-radio>
+  </fluent-radio-group>
+`);
+
+export const RadioGroupDisabled = renderComponent(html<RadioGroupStoryArgs>`
+  <fluent-radio-group disabled aria-labelledby="label-7" name="radio-story">
+    <span id="label-7" slot="label">Favorite Fruit</span>
+    <fluent-radio checked value="apple">Apple</fluent-radio>
+    <fluent-radio checked value="pear">Pear</fluent-radio>
+    <fluent-radio value="banana">Banana</fluent-radio>
+    <fluent-radio value="orange">Orange</fluent-radio>
+  </fluent-radio-group>
+`);
+
+export const RadioGroupDisabledItem = renderComponent(html<RadioGroupStoryArgs>`
+  <fluent-radio-group aria-labelledby="label-8" name="radio-story">
+    <span id="label-8" slot="label">Favorite Fruit</span>
+    <fluent-radio id="baby" checked value="apple">Apple</fluent-radio>
+    <fluent-radio disabled value="pear">Pear</fluent-radio>
+    <fluent-radio value="banana">Banana</fluent-radio>
+    <fluent-radio value="orange">Orange</fluent-radio>
+  </fluent-radio-group>
+`);
+
+const getLabelContent = (): string | undefined => {
+  const radioGroup = document.querySelector('#radio-group-fruit') as FluentRadioGroup;
+
+  if (!radioGroup) return; // add a check to make sure radioGroup exists
+  const selectedRadio = radioGroup.value as string;
+  if (selectedRadio) {
+    return `Favorite fruit: ${selectedRadio.charAt(0).toUpperCase() + selectedRadio.slice(1)}`;
+  } else {
+    return 'Please select your favorite fruit';
+  }
+};
+
+const handleChange = (event: CustomEvent) => {
+  const radioGroup = document.querySelector('#radio-group-fruit') as FluentRadioGroup;
+
+  if (!radioGroup) return; // add a check to make sure radioGroup exists
+
+  const selectedRadio = radioGroup.value as string;
+  const labelElement = radioGroup.querySelector('[slot="label"]') as HTMLSpanElement;
+  if (selectedRadio) {
+    const labelContent = selectedRadio.charAt(0).toUpperCase() + selectedRadio.slice(1);
+    labelElement.textContent = `Favorite fruit: ${labelContent}`;
+  }
+};
+
+export const RadioGroupChangeEvent = renderComponent(html<RadioGroupStoryArgs>`
+  <fluent-radio-group
+    id="radio-group-fruit"
+    aria-labelledby="label-8"
+    name="radio-story"
+    @change="${(event: CustomEvent) => handleChange(event)}"
+  >
+    <span id="label-8" slot="label">${getLabelContent}</span>
+    <fluent-radio checked value="apple">Apple</fluent-radio>
+    <fluent-radio value="pear">Pear</fluent-radio>
+    <fluent-radio value="Banana">Banana</fluent-radio>
+    <fluent-radio value="Orange">Orange</fluent-radio>
+  </fluent-radio-group>
+`);

packages/web-components/src/radio-group/radio-group.styles.ts

@@ -0,0 +1,68 @@
+import { css } from '@microsoft/fast-element';
+import { display } from '@microsoft/fast-foundation';
+import {
+  colorCompoundBrandForeground1,
+  colorNeutralForeground1,
+  colorNeutralForeground3,
+  colorNeutralForegroundDisabled,
+  colorNeutralStrokeAccessible,
+  fontFamilyBase,
+  fontSizeBase300,
+  fontWeightRegular,
+  lineHeightBase300,
+  spacingHorizontalS,
+  spacingHorizontalXS,
+  spacingVerticalS,
+} from '../theme/design-tokens.js';
+
+/** RadioGroup styles
+ * @public
+ */
+export const styles = css`
+  ${display('flex')}
+
+  :host {
+    --control-border-color: ${colorNeutralStrokeAccessible};
+    --checked-indicator-background-color: ${colorCompoundBrandForeground1};
+    --state-color: ${colorNeutralForeground3};
+    align-items: flex-start;
+    flex-direction: column;
+    row-gap: ${spacingVerticalS};
+  }
+  :host([disabled]) {
+    --control-border-color: ${colorNeutralForegroundDisabled};
+    --checked-indicator-background-color: ${colorNeutralForegroundDisabled};
+    --state-color: ${colorNeutralForegroundDisabled};
+  }
+  ::slotted([slot='label']) {
+    color: ${colorNeutralForeground1};
+    padding: ${spacingVerticalS} ${spacingHorizontalS} ${spacingVerticalS} ${spacingHorizontalXS};
+    font: ${fontWeightRegular} ${fontSizeBase300} / ${lineHeightBase300} ${fontFamilyBase};
+    cursor: default;
+  }
+  .positioning-region {
+    display: flex;
+    flex-wrap: wrap;
+  }
+  :host([orientation='vertical']) .positioning-region {
+    flex-direction: column;
+    justify-content: flex-start;
+  }
+  :host([orientation='horizontal']) .positioning-region {
+    flex-direction: row;
+  }
+  :host([orientation='horizontal']) ::slotted([role='radio']) {
+    padding-inline-end: ${spacingHorizontalS};
+  }
+  :host([orientation='horizontal'][stacked]) ::slotted([role='radio']) {
+    display: flex;
+    flex-direction: column;
+    padding-inline: ${spacingHorizontalS};
+    height: auto;
+    align-items: center;
+    justify-content: center;
+  }
+  :host([disabled]) ::slotted([role='radio']) {
+    pointer-events: none;
+  }
+`;