Skip to content

Commit

Permalink
Merge pull request #1430 from genesiscommunitysuccess/gg/PTL-1029
Browse files Browse the repository at this point in the history 
PTL-1029: Improve radio documentation
  • Loading branch information
@GuiWar
GuiWar authored Dec 7, 2023
2 parents fc0fe4d + e15ee26 commit 8414579
Show file tree
Hide file tree
Showing 4 changed files with 321 additions and 23 deletions.
89 changes: 83 additions & 6 deletions docs/04_web/02_web-components/01_form/08_radio-group.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,20 +24,97 @@ import { provideDesignSystem, alphaRadioGroup, alphaRadio } from '@genesislcap/a
provideDesignSystem().register(alphaRadioGroup(), alphaRadio());
```

## Attributes

You can define the following attributes in an `<alpha-radio-group>`.

| Name | Type | Description |
|-------------|----------------------------|-------------------------------------------------------------------------------------------|
| checked | `boolean` | Sets or retrieves the current state of the component. **Default: `false`** |
| disabled | `boolean` | Similar to `readonly`, but with a blur on the component |
| name | `string` | Sets a name for the component |
| orientation | `vertical` or `horizontal` | Sets the orientation of the group of radios components. **Default: `horizontal`** |
| readonly | `boolean` | If true, the user cannot change the value of this checkbox (which is greyed out) |
| value | `string` | Sets a initial value for the component, so the corresponding radio component gets checked |

These attributes must be defined alongside the declaration of the component.

## Events

You can define the following events when using the `alpha-radio` component:

| Name | Description |
|---------|-----------------------------------------------|
| @change | Fires the event when a radio change its state |

## Usage
All examples below use the `alpha-design-system`. If you are using any other design system, change the declaration
of this component accordingly.

- **Example 1**: simple implementation of a radio-group
```html title="Example 1"
<alpha-radio-group>
<alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio value="orange">Orange</alpha-radio>
</alpha-radio-group>
```
- **Example 2**: a radio-group component initialized with "apple" value
```html title="Example 2"
<alpha-radio-group value="apple">
<alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio value="orange">Orange</alpha-radio>
</alpha-radio-group>
```

### Get the user input
Once the user has input a value to this component, you need to make it accessible to the application:

1. Create an `@observable` variable where you want to use this value:

```html {1,5}
import {... , observable} from '@microsoft/fast-element';
...
export class TEMPLATE extends FASTElement {
...
@observable radioGroup: boolean
...
}
```

2. Use the `sync` function to insert the value from the component into the variable `checkbox`:

```typescript tile="Example 4" {1,4}
import {sync} from '@genesislcap/foundation-utils';
...
...
<alpha-radio-group :value="${sync((x) => x.radioGroup)}">
<alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio value="orange">Orange</alpha-radio>
</alpha-radio-group>
...
...
```

From this point, you can access the value of the component in your application.

## Try yourself

```html live
<alpha-radio-group value="apple" name="favorite-fruit">
<alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio value="orange">Orange</alpha-radio>
<alpha-radio-group>
<alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio value="orange">Orange</alpha-radio>
</alpha-radio-group>
```

## Use cases

* To provide options where only one option is allowed. You could use this for BUY or SELL, for example.
Selecting multiple options in the same input: You could have a set of broker codes, for example, and the user could select one or more of those codes.

## Additional resources

[W3C Component Aria Practices](https://www.w3.org/TR/wai-aria/#radiogroup)
- [W3C Component Aria Practices](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)

80 changes: 76 additions & 4 deletions docs/04_web/02_web-components/01_form/09_radio.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,16 +22,88 @@ import {
provideDesignSystem().register(alphaRadio());
```

## Attributes

You can define the following attributes in an `<alpha-radio>`.

| Name | Type | Description |
|----------|-----------|----------------------------------------------------------------------------------|
| checked | `boolean` | Sets or retrieves the current state of the component. **Default: `false`** |
| disabled | `boolean` | Similar to `readonly`, but with a blur on the component |
| value | `string` | Sets a value for the component. Not visible to the user |
| readonly | `boolean` | If true, the user cannot change the value of this checkbox (which is greyed out) |

These attributes must be defined alongside the declaration of the component.

## Events

You can define the following events when using the `alpha-radio` component:

| Name | Description |
|---------|---------------------------------------------|
| @change | Fires the event when the radio component changes its state |

## Usage
All examples below use the `alpha-design-system`. If you are using any other design system, change the declaration
of this component accordingly.

- **Example 1**: simple implementation of a radio
```html title="Example 1"
<alpha-radio>Radio component</alpha-radio>
```
- **Example 2**: a radio component checked with a change event pointing to a function
```html title="Example 2"
<alpha-radio checked="true" @change="${(x) => x.changeRadio()}">Radio</alpha-radio>
```

### Get the user input
Once the user has input a value to this component, you need to make it accessible to the application:

1. Create an `@observable` variable where you want to use this value:

```html {1,5}
import {... , observable} from '@microsoft/fast-element';
...
export class TEMPLATE extends FASTElement {
...
@observable radioComponent: boolean
...
}
```

2. Use the `sync` function to insert the value from the component into the variable `checkbox`:

```typescript tile="Example 4" {1,4}
import {sync} from '@genesislcap/foundation-utils';
...
...
<alpha-radio :value="${sync((x) => x.radioComponent)}">Radio component</alpha-radio>
...
...
```

From this point, you can access the value of the component in your application.

:::tip
Once the radio has been checked, the user cannot uncheck it.
:::

## Try yourself

```html live
<div>
<alpha-radio alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio alpha-radio value="orange">Orange</alpha-radio>
<alpha-radio alpha-radio value="Try">Try</alpha-radio>
<alpha-radio alpha-radio value="Your">Your</alpha-radio>
<alpha-radio alpha-radio value="Self">Self</alpha-radio>
</div>
```

## Use cases

Selecting multiple options in the same input: You could have a set of broker codes, for example, and the user could select one or more of those codes.
Selecting multiple options in the same input; you could have a set of broker codes, for example, and the user could select one or more of those codes.

## Additional resources

- [W3C Component Aria Practices](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)


95 changes: 86 additions & 9 deletions versioned_docs/version-previous/04_web/02_web-components/01_form/08_radio-group.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ sidebar_label: 'Radio group'
id: radio-group
keywords: [web, web components, radio group]
tags:
- web
- web components
- radio group
- web
- web components
- radio group
---
As defined by the [W3C](https://w3c.github.io/aria-practices/#radiobutton):

Expand All @@ -24,20 +24,97 @@ import { provideDesignSystem, alphaRadioGroup, alphaRadio } from '@genesislcap/a
provideDesignSystem().register(alphaRadioGroup(), alphaRadio());
```

## Attributes

You can define the following attributes in an `<alpha-radio-group>`.

| Name | Type | Description |
|-------------|----------------------------|-------------------------------------------------------------------------------------------|
| checked | `boolean` | Sets or retrieves the current state of the component. **Default: `false`** |
| disabled | `boolean` | Similar to `readonly`, but with a blur on the component |
| name | `string` | Sets a name for the component |
| orientation | `vertical` or `horizontal` | Sets the orientation of the group of radios components. **Default: `horizontal`** |
| readonly | `boolean` | If true, the user cannot change the value of this checkbox (which is greyed out) |
| value | `string` | Sets a initial value for the component, so the corresponding radio component gets checked |

These attributes must be defined alongside the declaration of the component.

## Events

You can define the following events when using the `alpha-radio` component:

| Name | Description |
|---------|-----------------------------------------------|
| @change | Fires the event when a radio change its state |

## Usage
All examples below use the `alpha-design-system`. If you are using any other design system, change the declaration
of this component accordingly.

- **Example 1**: simple implementation of a radio-group
```html title="Example 1"
<alpha-radio-group>
<alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio value="orange">Orange</alpha-radio>
</alpha-radio-group>
```
- **Example 2**: a radio-group component initialized with "apple" value
```html title="Example 2"
<alpha-radio-group value="apple">
<alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio value="orange">Orange</alpha-radio>
</alpha-radio-group>
```

### Get the user input
Once the user has input a value to this component, you need to make it accessible to the application:

1. Create an `@observable` variable where you want to use this value:

```html {1,5}
import {... , observable} from '@microsoft/fast-element';
...
export class TEMPLATE extends FASTElement {
...
@observable radioGroup: boolean
...
}
```

2. Use the `sync` function to insert the value from the component into the variable `checkbox`:

```typescript tile="Example 4" {1,4}
import {sync} from '@genesislcap/foundation-utils';
...
...
<alpha-radio-group :value="${sync((x) => x.radioGroup)}">
<alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio value="orange">Orange</alpha-radio>
</alpha-radio-group>
...
...
```

From this point, you can access the value of the component in your application.

## Try yourself

```html live
<alpha-radio-group value="apple" name="favorite-fruit">
<alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio value="orange">Orange</alpha-radio>
<alpha-radio-group>
<alpha-radio value="apple">Apple</alpha-radio>
<alpha-radio value="mango">Mango</alpha-radio>
<alpha-radio value="orange">Orange</alpha-radio>
</alpha-radio-group>
```

## Use cases

* To provide options where only one option is allowed. You could use this for BUY or SELL, for example.
Selecting multiple options in the same input: You could have a set of broker codes, for example, and the user could select one or more of those codes.

## Additional resources

[W3C Component Aria Practices](https://www.w3.org/TR/wai-aria/#radiogroup)
- [W3C Component Aria Practices](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)

Loading

0 comments on commit 8414579

Please sign in to comment.