chore(docs): tag and tag-group (VIV-2109)

apps/docs/content/_data/components.json

@@ -384,16 +384,14 @@
 		"parent": "Tree View"
 	},
 	{
-		"title": "Tag Group",
-		"page": "legacy",
-		"markdown": "./libs/components/src/lib/tag-group/README.md",
-		"children": ["Tag"]
-	},
-	{
-		"title": "Tag",
-		"page": "legacy",
-		"markdown": "./libs/components/src/lib/tag/README.md",
-		"parent": "Tag Group"
+		"title": "Tag & Tag Group",
+		"description": "A Tag Group controls the layout for a collection of Tags. Tags are small, interactive labels used to visually group, classify, or filter criteria.",
+		"variations": "./libs/components/src/lib/tag-group/VARIATIONS.md",
+		"guidelines": "./libs/components/src/lib/tag-group/GUIDELINES.md",
+		"hideGuidelines": "true",
+		"code": "./libs/components/src/lib/tag-group/README.md",
+		"accessibility": "./libs/components/src/lib/tag-group/ACCESSIBILITY.md",
+		"useCases": "./libs/components/src/lib/tag-group/USE-CASES.md"
 	},
 	{
 		"title": "Pagination",
@@ -447,12 +445,8 @@
 	},
 	{
 		"title": "Dial Pad",
-		"description": "Use when you need to allow users to enter / dial telephone numbers.",
-		"variations": "./libs/components/src/lib/dial-pad/VARIATIONS.md",
-		"guidelines": "./libs/components/src/lib/dial-pad/GUIDELINES.md",
-		"hideGuidelines": "true",
-		"code": "./libs/components/src/lib/dial-pad/README.md",
-		"accessibility": "./libs/components/src/lib/dial-pad/ACCESSIBILITY.md"
+		"page": "legacy",
+		"markdown": "./libs/components/src/lib/dial-pad/README.md"
 	},
 	{
 		"title": "Video Player",

libs/components/src/lib/tag-group/ACCESSIBILITY.md

@@ -0,0 +1,7 @@
+## Implementation
+
+- Use the `aria-label` attribute on the **Tag Group** component to clarify the purpose for screen reader users.
+
+## Resources
+
+- [Vivid Tag & Tag Group: Manual accessibility test](https://docs.google.com/spreadsheets/d/1hXS4ppjqdGpBYul29NC3aobj6OKomL0_Ij4w0fAMBIk/edit?gid=1175911860#gid=1175911860)

libs/components/src/lib/tag-group/README.md

@@ -1,46 +1,130 @@
-# Tag Group
+## Usage
 
-Represents a tag-group custom element.
-
-A tag group displays tags from left to right, handling overflow by wrapping to the next line.
-For a consistent user experience, tags within a tag group should generally be the same type.
+<vwc-tabs gutters="none">
+<vwc-tab label="Web component"></vwc-tab>
+<vwc-tab-panel>
 
 ```js
-<script type="module">import '@vonage/vivid/tag-group';</script>
+import '@vonage/vivid/tag-group';
+import '@vonage/vivid/tag';
 ```
 
-## Slots
+or, if you need to use a unique prefix:
 
-### Default
+```js
+import { registerTag, registerTagGroup } from '@vonage/vivid';
 
-Read more about [vwc-tag](/components/tag/).
+registerTag('your-prefix');
+registerTagGroup('your-prefix');
+```
 
 ```html preview
-<vwc-tag-group>
-	<vwc-tag label="first tag"></vwc-tag>
-	<vwc-tag label="second tag"></vwc-tag>
-	<vwc-tag label="third tag"></vwc-tag>
-</vwc-tag-group>
-```
+<script type="module">
+	import { registerTag, registerTagGroup } from '@vonage/vivid';
+	registerTag('your-prefix');
+	registerTagGroup('your-prefix');
+</script>
 
-## Use Case
+<your-prefix-tag-group>
+	<your-prefix-tag label="Tag one"></your-prefix-tag>
+	<your-prefix-tag label="Tag two"></your-prefix-tag>
+</your-prefix-tag-group>
+```
 
-### Selectable
+</vwc-tab-panel>
+<vwc-tab label="Vue"></vwc-tab>
+<vwc-tab-panel>
 
-```html preview
-<vwc-tag-group>
-	<vwc-tag label="first tag" selectable selected></vwc-tag>
-	<vwc-tag label="second tag" selectable></vwc-tag>
-	<vwc-tag label="third tag" selectable selected></vwc-tag>
-</vwc-tag-group>
+```html
+<script setup lang="ts">
+	import { VTag, VTagGroup } from '@vonage/vivid-vue';
+</script>
+<template>
+	<VTagGroup>
+		<VTag label="Tab one" />
+		<VTag label="Tab two" />
+	</VTagGroup>
+</template>
 ```
 
-### Removable
+</vwc-tab-panel>
+</vwc-tabs>
+
+## Slots
+
+### Icon Slot
+
+Use the `icon` slot in thr **Tag** component to customise icons. If set, the `icon` attribute is ignored.
 
 ```html preview
 <vwc-tag-group>
-	<vwc-tag label="first tag" removable></vwc-tag>
-	<vwc-tag label="second tag" removable></vwc-tag>
-	<vwc-tag label="third tag" removable></vwc-tag>
+	<vwc-tag label="With icon">
+		<vwc-icon slot="icon" name="heart-solid" connotation="alert"></vwc-icon>
+	</vwc-tag>
 </vwc-tag-group>
 ```
+
+## API Reference
+
+### Tag
+
+#### Properties
+
+<div class="table-wrapper">
+
+| Name            | Type                          | Description                                                                                                     |
+| --------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **appearance**  | `subtle` (default), `duotone` | Sets the appearance                                                                                             |
+| **connotation** | `accent` (default), `cta`     | Sets the connotation                                                                                            |
+| **disabled**    | `boolean`                     | Sets the disabled state                                                                                         |
+| **icon**        | Enum: `[icon-name]`           | A decorative icon the custom element should have. See the Vivid Icon Gallery for available icons and icon-names |
+| **label**       | `string`                      | Sets the label text                                                                                             |
+| **selectable**  | `boolean`                     | Enables the selectable behaviour                                                                                |
+| **selected**    | `boolean`                     | Sets the selected state                                                                                         |
+| **shape**       | `rounded` (default), `pill`   | Sets the shape                                                                                                  |
+| **removable**   | `boolean`                     | Enables the removable behaviour                                                                                 |
+
+</div>
+
+#### Events
+
+<div class="table-wrapper">
+
+| Name                | Type          | Bubbles | Composed | Description                             |
+| ------------------- | ------------- | ------- | -------- | --------------------------------------- |
+| **selected-change** | `CustomEvent` | Yes     | Yes      | Fires when the `selected` state changes |
+| **removed**         | `CustomEvent` | Yes     | Yes      | Fires when a tag is removed             |
+
+</div>
+
+#### Methods
+
+<div class="table-wrapper">
+
+| Name       | Returns | Description                                                                                                                                                                                                              |
+| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **remove** | `void`  | Removes the tag from the DOM. Fires the `removed` event and removes the tag from the DOM completely. If you have a variable that refers to the tag element make sure to clear it otherwise it might cause a memory leak. |
+
+</div>
+
+### Tag Group
+
+#### Properties
+
+<div class="table-wrapper">
+
+| Name           | Type     | Description               |
+| -------------- | -------- | ------------------------- |
+| **aria-label** | `string` | Sets the accessible label |
+
+</div>
+
+#### Slots
+
+<div class="table-wrapper">
+
+| Name        | Description                        |
+| ----------- | ---------------------------------- |
+| **default** | For a collection of Tag components |
+
+</div>

libs/components/src/lib/tag-group/USE-CASES.md

@@ -0,0 +1,19 @@
+## Selectable Tag Group
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag label="First tag" selectable selected></vwc-tag>
+	<vwc-tag label="Second tag" selectable></vwc-tag>
+	<vwc-tag label="Third tag" selectable selected></vwc-tag>
+</vwc-tag-group>
+```
+
+## Removable Tag Group
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag label="First tag" removable></vwc-tag>
+	<vwc-tag label="Second tag" removable></vwc-tag>
+	<vwc-tag label="Third tag" removable></vwc-tag>
+</vwc-tag-group>
+```

libs/components/src/lib/tag-group/VARIATIONS.md

@@ -0,0 +1,100 @@
+**Tags** should be wrapped by the **Tag Group** component to provide the correct layout and also semantic meaning.
+
+## Label
+
+The `label` attribute adds label text to the **Tag**.
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag label="Tag label"></vwc-tag>
+</vwc-tag-group>
+```
+
+## Selectable
+
+The `selectable` attribute enables the selectable behaviour. Use the `selected` attribute to mark the Tag as selected.
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag selectable label="Selectable tag"></vwc-tag>
+	<vwc-tag selected selectable label="Selected tag"></vwc-tag>
+</vwc-tag-group>
+```
+
+## Removable
+
+The `removable` attribute enables the removable behaviour. Clicking the remove icon removes the Tag from the Tag Group
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag removable label="Removable tag 1"></vwc-tag>
+	<vwc-tag removable label="Removable tag 2"></vwc-tag>
+</vwc-tag-group>
+```
+
+## Appearance
+
+The `appearance` attribute sets the Tag's appearance.
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag label="Subtle" appearance="subtle"></vwc-tag>
+	<vwc-tag label="Duotone" appearance="duotone"></vwc-tag>
+</vwc-tag-group>
+```
+
+## Connotation
+
+The `connotation` attribute sets the Tag's connotation.
+It accepts a subset of predefined values.
+
+### Subtle Tag With Connotation
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag label="Accent" appearance="subtle" connotation="accent"></vwc-tag>
+	<vwc-tag label="CTA" appearance="subtle" connotation="cta"></vwc-tag>
+</vwc-tag-group>
+```
+
+### Duotone Tag With Connotation
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag label="Accent" appearance="duotone" connotation="accent"></vwc-tag>
+	<vwc-tag label="CTA" appearance="duotone" connotation="cta"></vwc-tag>
+</vwc-tag-group>
+```
+
+## Shape
+
+The `shape` attribute sets Tag's shape.
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag label="Rounded" shape="rounded"></vwc-tag>
+	<vwc-tag label="Pill" shape="pill"></vwc-tag>
+</vwc-tag-group>
+```
+
+## Icon
+
+The `icon` attribute displays an icon from the [icon library](/icons/icons-gallery/), which is displayed on the leading side of the Tag.
+
+Custom icons can be provided using the [icon slot](/components/tag-and-tag-group/code/#icon-slot).
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag label="Tag with icon" icon="pin-line"></vwc-tag>
+</vwc-tag-group>
+```
+
+## Disabled
+
+The `disabled` attribute sets the disabled state.
+
+```html preview
+<vwc-tag-group>
+	<vwc-tag label="Disabled tag" disabled></vwc-tag>
+</vwc-tag-group>
+```

libs/components/src/lib/tag-group/ui.test.ts

@@ -1,24 +1,36 @@
-import * as path from 'path';
 import { expect, test } from '@playwright/test';
 import type { Page } from '@playwright/test';
 import {
-	extractHTMLBlocksFromReadme,
 	loadComponents,
 	loadTemplate,
 } from '../../visual-tests/visual-tests-utils.js';
 
 const components = ['tag-group', 'tag'];
 
 test('should show the component', async ({ page }: { page: Page }) => {
-	const template =
-		'<style>#wrapper{height: 250px; width: 1600px; display: flex; flex-wrap: wrap;}</style>' +
-		extractHTMLBlocksFromReadme(
-			path.join(new URL('.', import.meta.url).pathname, 'README.md')
-		).reduce(
-			(htmlString: string, block: string) =>
-				`${htmlString} <div style="margin: 5px;">${block}</div>`,
-			''
-		);
+	const template = `
+		<style>#wrapper{height: 250px; width: 1600px; display: flex; flex-wrap: wrap;}</style>
+		<div style="margin: 5px;">
+			<vwc-tag-group>
+				<vwc-tag label="first tag"></vwc-tag>
+				<vwc-tag label="second tag"></vwc-tag>
+				<vwc-tag label="third tag"></vwc-tag>
+			</vwc-tag-group>
+		</div>
+		<div style="margin: 5px;">
+			<vwc-tag-group>
+				<vwc-tag label="first tag" selectable selected></vwc-tag>
+				<vwc-tag label="second tag" selectable></vwc-tag>
+				<vwc-tag label="third tag" selectable selected></vwc-tag>
+			</vwc-tag-group>
+		</div>
+		<div style="margin: 5px;">
+			<vwc-tag-group>
+				<vwc-tag label="first tag" removable></vwc-tag>
+				<vwc-tag label="second tag" removable></vwc-tag>
+				<vwc-tag label="third tag" removable></vwc-tag>
+			</vwc-tag-group>
+		</div>`;
 
 	await loadComponents({
 		page,