Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): Action Group docs update (VIV-2079) #2073

Merged
merged 6 commits into from
Jan 7, 2025
Merged

chore(docs): Action Group docs update (VIV-2079) #2073

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a845365
ui tests
rachelbt Jan 2, 2025
9e87a28
docs uplift
rachelbt Jan 2, 2025
a4bf07c
docs uplift
rachelbt Jan 5, 2025
cb73eea
Merge branch 'main' of https://github.com/Vonage/vivid-3 into VIV-207…
rachelbt Jan 7, 2025
bc2630e
new ui png
rachelbt Jan 7, 2025
01c1118
Update libs/components/src/lib/action-group/VARIATIONS.md
rachelbt Jan 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions apps/docs/content/_data/components.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,8 +171,13 @@
},
{
"title": "Action Group",
"page": "legacy",
"markdown": "./libs/components/src/lib/action-group/README.md"
"description": "The action group component should be used when you have a set of related actions or options that need to be grouped together within a limited space.",
"variations": "./libs/components/src/lib/action-group/VARIATIONS.md",
"guidelines": "./libs/components/src/lib/action-group/GUIDELINES.md",
"hideGuidelines": "true",
"code": "./libs/components/src/lib/action-group/README.md",
"accessibility": "./libs/components/src/lib/action-group/ACCESSIBILITY.md",
"useCases": "./libs/components/src/lib/action-group/USE-CASES.md"
},
{
"title": "Note",
Expand Down
9 changes: 9 additions & 0 deletions libs/components/src/lib/action-group/ACCESSIBILITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
## Best Practices

The `action-group` defaults to `role="group"`.
However - if this role does not suit the use-case, you can change it.
[For further reading about group role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/group_role).

## Resources

[Vivid Action Group: Manual accessibility test](https://docs.google.com/spreadsheets/d/1HzLt9iJf51TYpkdbQlTpl6jkV2oz5uJfWxKG6hFJptE/edit?gid=1175911860#gid=1175911860)
113 changes: 113 additions & 0 deletions libs/components/src/lib/action-group/GUIDELINES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
## Advantages of Card UI Design

Advantages of card UI design

### Highly Responsive

Probably the main advantage of UI cards is that they are very adaptive. It’s the rectangular shape that makes them transformative. That is why UI cards look good on all screen sizes.

### Easy-To-Understand

UI cards are rather minimalistic and understandable design elements. Small chunks of information they reveal are easy to consume.

### Intuitive and UX Friendly

Most users are familiar with the card interface design and can easily navigate through it. Rectangular shape and simple clickable elements make the user experience very intuitive.

### Attractive and Modern-Looking

Despite the fact that card-based design has been around for a decade now it is still an up-to-date design solution. Their key visual element makes it easy to make any product attractive using this layout.

## Appearance

### Elevated

<docs-do-dont no-gutters>

<div slot="description">

- default appearance
- can change the elevation to emphasis
</div>
<div>

```html preview center example 150px
<vwc-card elevation="12" headline="Card with Elevation 12"></vwc-card>
```

</div>
</docs-do-dont>

### Outlined

<docs-do-dont no-gutters>

<div slot="description">

</div>
<div>

```html preview center example 150px
<vwc-card
appearance="outlined"
headline="Card with Outlined Appearance"
class="card-appearance"
></vwc-card>

<style>
.card-appearance {
margin: 16px;
}
</style>
```

</div>
</docs-do-dont>

### Ghost

<docs-do-dont>
<docs-do slot="description" caption="use ghost appearance when using the card inside selectable box">

```html preview center example 170px
<vwc-selectable-box
tight
clickable-box
connotation="cta"
checked
class="selectable-box"
>
<vwc-card
appearance="ghost"
headline="Card with Ghost Appearance"
subtitle="slotted inside selectable box"
></vwc-card>
</vwc-selectable-box>

<style>
.selectable-box {
margin: 16px;
}
</style>
```

</docs-do>

<docs-do dont caption="don't use ghost appearance when not slotted, this will make the card noticeable">

```html preview center example 150px
<vwc-card
appearance="ghost"
headline="Card with Ghost Appearance"
class="card-appearance"
></vwc-card>

<style>
.card-appearance {
margin: 16px;
}
</style>
```

</docs-do>
</docs-do-dont>
215 changes: 39 additions & 176 deletions libs/components/src/lib/action-group/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,198 +1,61 @@
# Action Group
## Usage

The action group component should be used when you have a set of related actions or
options that need to be grouped together within a limited space.
<vwc-tabs>
<vwc-tab label="Web component"></vwc-tab>
<vwc-tab-panel>

```js
<script type="module">import '@vonage/vivid/action-group';</script>
import '@vonage/vivid/action-group';
```

```html preview
<vwc-action-group>
<vwc-button icon="reply-line"></vwc-button>
<vwc-button label="copy"></vwc-button>
<vwc-button label="paste"></vwc-button>
<vwc-button label="submit"></vwc-button>
</vwc-action-group>
```

## Members

### Appearance

Set the `appearance` attribute to change the action-group's appearance.

- Type: `'fieldset'` | `'ghost'`
- Default: `'fieldset'`

```html preview
<vwc-action-group appearance="fieldset">
<vwc-button label="edit"></vwc-button>
<vwc-button label="copy"></vwc-button>
<vwc-button label="paste"></vwc-button>
<vwc-button label="submit"></vwc-button>
</vwc-action-group>

<vwc-action-group appearance="ghost">
<vwc-button label="edit" appearance="filled"></vwc-button>
<vwc-button label="copy" appearance="filled"></vwc-button>
<vwc-button label="paste" appearance="filled"></vwc-button>
<vwc-button label="submit" appearance="filled"></vwc-button>
</vwc-action-group>
```

### Shape

Use the `shape` attribute to set the action-group's edges.
When using shape, remember to also set it on any slotted elements.

- Type: `'rounded'` | `'pill'`
- Default: `'rounded'`

```html preview
<vwc-action-group shape="pill">
<vwc-button label="edit" shape="pill"></vwc-button>
<vwc-button label="copy" shape="pill"></vwc-button>
<vwc-button label="paste" shape="pill"></vwc-button>
<vwc-button label="submit" shape="pill"></vwc-button>
</vwc-action-group>
```
or, if you need to use a unique prefix:

### Tight

By default, action group is styled in a spacious manner which visually extends the baseline row size and includes an inline gap.
Enabling the `tight` member will result in a dense style that fits the "normal" baseline.

- Type: `boolean`
- Default: `false`

```html preview
<style>
vwc-layout {
--layout-grid-template-columns: 250px;
}

vwc-action-group > vwc-text-field {
flex-grow: 1;
}
</style>
```js
import { registerActionGroup } from '@vonage/vivid';

<vwc-layout column-basis="block" column-spacing="small">
<vwc-text-field
name="username"
aria-label="Username"
placeholder="Username"
></vwc-text-field>
<vwc-action-group appearance="fieldset" tight>
<vwc-button icon="flag-uruguay"></vwc-button>
<vwc-text-field
appearance="ghost"
aria-label="Phone number"
placeholder="Phone number"
name="phone"
autocomplete=""
></vwc-text-field>
</vwc-action-group>
</vwc-layout>
registerActionGroup('your-prefix');
```

## Use Cases

### Separator

Use `<vwc-divider>` for adding separator between the action elements

```html preview
<vwc-action-group appearance="fieldset">
<vwc-button icon="reply-line"></vwc-button>
<vwc-divider orientation="vertical"></vwc-divider>
<vwc-button icon="compose-line"></vwc-button>
</vwc-action-group>
```

### Composed Search
<script type="module">
import { registerActionGroup } from '@vonage/vivid';
registerActionGroup('your-prefix');
</script>

```html preview
<vwc-action-group shape="pill">
<vwc-button
label="Action"
appearance="ghost"
icon="chevron-down-solid"
icon-trailing
shape="pill"
></vwc-button>
<vwc-divider orientation="vertical"></vwc-divider>
<vwc-text-field
icon="search-line"
placeholder="Search..."
appearance="ghost"
shape="pill"
style="min-width: 160px;"
></vwc-text-field>
</vwc-action-group>
<your-prefix-action-group>
<vwc-button label="copy"></vwc-button>
<vwc-button label="paste"></vwc-button>
</your-prefix-action-group>
```

### Toggle buttons
</vwc-tab-panel>
<vwc-tab label="Vue"></vwc-tab>
<vwc-tab-panel>

```html preview
<vwc-action-group role="region" aria-label="Text Alignment">
<vwc-button
icon="align-left-line"
aria-label="Text Align Left"
onclick="onClick(event)"
></vwc-button>
<vwc-button
aria-pressed="true"
icon="align-center-line"
aria-label="Text Align Center"
appearance="filled"
onclick="onClick(event)"
></vwc-button>
<vwc-button
icon="align-right-line"
aria-label="Text Align Right"
onclick="onClick(event)"
></vwc-button>
</vwc-action-group>

<script>
function onClick(event) {
currentPressed = document.querySelector('vwc-button[aria-pressed="true"]');
currentPressed?.removeAttribute('aria-pressed');
currentPressed?.removeAttribute('appearance');
event.currentTarget.setAttribute('aria-pressed', 'true');
event.currentTarget.setAttribute('appearance', 'filled');
}
```html
<script setup lang="ts">
import { VActionGroup } from '@vonage/vivid-vue';
</script>
<template>
<VActionGroup>
<VButton appearance="filled" label="Click me" />
</VActionGroup>
</template>
```

<!-- TODO: Update the example when will be a dropdown component / the popup will not be underlying -->
</vwc-tab-panel>
</vwc-tabs>

<!-- ### More Actions
## API Reference

```html preview center
<vwc-button id="anchor" icon="more-horizontal-solid" aria-label="open actions menu"></vwc-button>
### Properties

<vwc-popup id="popup" anchor="anchor" arrow open placement="top">
<vwc-action-group appearance="ghost">
<vwc-button icon="reply-line"></vwc-button>
<vwc-button icon="transfer-line"></vwc-button>
<vwc-divider orientation="vertical"></vwc-divider>
<vwc-button icon="compose-line"></vwc-button>
<vwc-button icon="crop-line"></vwc-button>
<vwc-divider orientation="vertical"></vwc-divider>
<vwc-button icon="copy-2-line"></vwc-button>
<vwc-button icon="save-line"></vwc-button>
</vwc-action-group>
</vwc-popup>

<script>
anchor.addEventListener('click', () => popup.open = !popup.open);
</script>
``` -->
<div class="table-wrapper">

## Accessibility
| Name | Type | Description |
| -------------- | ------------------------------------ | -------------------------------- |
| **appearance** | _Enum_:`fieldset` (default), `ghost` | Sets the element's appearance |
| **shape** | _Enum_:`rounded`(default), `pill` | Sets the element's border-radius |
| **tight** | `boolean` | Remove padding and gaps |

The `action-group` defaults its role to 'group'.
However - if this role does not suit the use-case, you can change it.
[For further reading about group role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/group_role).
</div>
Loading
Loading