import { ArgTypes, Canvas, Markdown, Meta } from '@storybook/addon-docs/blocks';
import { cdnJs } from '../../globals/internal/storybook-cdn';
import * as TagStories from './tag.stories';

<Meta of={TagStories} />

# Tag

[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/web-components/src/components/tag)
&nbsp;|&nbsp;
[Usage guidelines](https://www.carbondesignsystem.com/components/tag/usage)
&nbsp;|&nbsp;
[Accessibility](https://www.carbondesignsystem.com/components/tag/accessibility)

## Table of Contents

- [Overview](#overview)
- [Read Only](#read-only)
- [Dismissible](#dismissible)
- [Selectable](#selectable)
- [Operational](#operational)
- [With AI Label](#with-ai-label)
- [Skeleton](#skeleton)
- [Component API](#component-api)
- [CDN](#cdn)
- [Feedback](#feedback)

## Overview

Tags can be used to categorize items. Use short labels for easy scanning. Use
two words only if necessary to describe the status and differentiate it from
other tags.

## Read Only

Read-only tags are used to categorize, are used for labeling, and do not have
interactive functionality. Read-only tags come in several color choices and can
use optional decorative icons to delineate between multiple categories.

<Canvas of={TagStories.ReadOnly} />

## Dismissible

Dismissible tags are used to remove tags that can be filtered out by the user.

When to use:

- Use `cds-disimissible-tag` when you want to allow users to easily clear or dismiss
  specific filters applied to items.

<Canvas of={TagStories.Dismissible} />

Here it is a sample code to help you get started.

```javascript
const tags = [
  {
    type: 'red',
    text: 'Tag content with a long text description',
    tagTitle: 'Provide a custom title to the tag',
  },
  {
    type: 'magenta',
    text: 'Tag content 1',
  },
  {
    type: 'purple',
    text: 'Tag content 2',
  },
];

function App() {
  return html`
    <cds-button style="margin-bottom: 3rem;"> Reset </cds-button>
    <br />
    ${tags.map(
      (tag) => html`
        <cds-dismissible-tag
          type=${tag.type}
          ?open=${true}
          tag-title=${tag.tagTitle || ''}>
          ${iconLoader(Asleep16, { slot: 'icon' })} ${tag.text}
        </cds-dismissible-tag>
      `
    )}
  `;
}

const button = document.querySelector('cds-button');
button.addEventListener('click', () => resetTags());

function resetTags() {
  const dismissibleTags = document.querySelectorAll('cds-dismissible-tag');
  dismissibleTags.forEach((tag) => tag.setAttribute('open', 'true'));
}
```

## Selectable

Selectable tags are used to select or unselect single or multiple items.
Selectable tags can also be used in filtering by label scenarios when they do
not need to be dismissed.

When to use:

- Use selectable tags to toggle between a selected or unselected state.
- Use when needing to filter without an explicit dismissable functionality. (We
  need to be a little more specific around filtering for selectable versus
  dismissable tags).

<Canvas of={TagStories.Selectable} />

Here it is a sample code to help you get started.

```javascript
const tags = [
  {
    text: 'Tag content with a long text description',
  },
  {
    text: 'Tag content 1',
  },
  {
    text: 'Tag content 2',
  },
  {
    text: 'Tag content 3',
  },
];

function App() {
  return html`
    <div aria-label="Selectable tags" role="group">
      ${tags.map(
        (tag) =>
          html`<cds-selectable-tag
            ?disabled="${disabled}"
            ?selected="${tag.selected}"
            id="${tag.id}"
            text="${text || tag.text}"
            size="${size}"
            >${iconLoader(Asleep16, { slot: 'icon' })}
          </cds-selectable-tag>`
      )}
    </div>
  `;
}

const tags = document.querySelectorAll('cds-selectable-tag');

tags.forEach((tag) =>
  tag.addEventListener('cds-selectable-tag-selected', (e) => {
    console.log(e.detail);
  })
);
```

## Operational

Operational tags enable the user to view a list of all items associated with a
given tag in different ways.

When to use:

- Use to view a list of items with the same tag in a popover, or breadcrumb
  detail view.

When not to use:

- Do not use operational tags as a replacement for links that direct you to an
  entirely different page or launch you out to another tab.
- Do not use in combination with Dismissable tags. Instead, consider letting the
  user enter an "edit mode" to dismiss tags.

<Canvas of={TagStories.Operational} />

## With AI Label

`<cds-tag>` with AI label is now stable for Read Only tags. This addition changes the
visual appearance of the component and introduces an AI explainability feature
when AI is present in the component.

<Canvas of={TagStories.WithAILabel} />

## Skeleton

<Canvas
  of={TagStories.Skeleton}
/>

## Component API

## `cds-tag`
<ArgTypes of="cds-tag" />

## `cds-dismissible-tag`
<ArgTypes of="cds-dismissible-tag" />

## `cds-selectable-tag`
<ArgTypes of="cds-selectable-tag" />

## `cds-operational-tag`
<ArgTypes of="cds-operational-tag" />

## `cds-tag-skeleton`
<ArgTypes of="cds-tag-skeleton" />

<Markdown>{`${cdnJs({ components: ['tag'] })}`}</Markdown>

## Feedback

Help us improve this component by providing feedback, asking questions on Slack,
or updating this file on
[GitHub](https://github.com/carbon-design-system/carbon/edit/main/packages/web-components/src/components/tag/tag.mdx).
