Tag Selector Component

The Tag Selector Component is a customizable and reusable web component built with the Lit framework. It provides an intuitive interface for managing tags, including adding, removing, and displaying selected tags.

Features

• Tag Management: Add, remove, and display selected tags.
• Suggestions: Dynamically display tag suggestions fetched from APIs.
• Accessibility: Full keyboard navigation and ARIA support.
• Customizable: Modify styles or extend functionality with slots.
• Mobile-Friendly: Optimized for responsive layouts.
• Event-Driven: Emits events for tag additions, removals, updates, and suggestions.
• Test Coverage: Well-tested with robust unit tests using @open-wc/testing.

Table of Contents

• Installation
• Usage
• API Reference
• Styling
• Events
• Development
• Testing
• Troubleshooting
• License

Installation

Install the Tag Selector component via npm:

npm install @your-package/tag-selector

Or include it in your project directly via script:

<script type="module" src="./dist/tag-selector.es.js"></script>

Usage

Basic Example

<studio.ui.components.tags.selector_tag-selector></studio.ui.components.tags.selector_tag-selector>

Predefined Selected Tags

<studio.ui.components.tags.selector_tag-selector
  .selectedTags=\${[
    { id: '1', displayName: 'Tag 1', description: 'First tag', name: 'tag-1' },
    { id: '2', displayName: 'Tag 2', description: 'Second tag', name: 'tag-2' },
  ]}
></studio.ui.components.tags.selector_tag-selector>

Providing Suggestions

<studio.ui.components.tags.selector_tag-selector
  .tagList=\${[
    { id: '3', displayName: 'Tag 3', description: 'Third tag', name: 'tag-3' },
    { id: '4', displayName: 'Tag 4', description: 'Fourth tag', name: 'tag-4' },
  ]}
></studio.ui.components.tags.selector_tag-selector>

API Reference

Properties

• selectedTags (Array): The list of tags currently selected.
• tagList (Array): The list of available tags for suggestions.

Methods

• handleTagAdded(event): Handles tag additions and emits a tags-changed event.
• handleTagRemoved(event): Handles tag removals and emits a tags-changed event.
• handleTagsRequested(event): Populates tag suggestions.
• updateSuggestions(): Updates the suggestion list to reflect selected tags.

Events

tags-changed

• Description: Fired whenever tags are added or removed.
• Payload:

  {
    "action": "added" | "removed",
    "tag": Object,
    "tags": Array
  }

tags-requested

• Description: Fired when the component requires new suggestions.

• Payload:

  {
    "query": string
  }

• Example: Use this event to fetch suggestions from an API:

  myTagSelector.addEventListener("tags-requested", (event) => {
    fetchTagsFromApi(event.detail.query).then((tags) => {
      myTagSelector.tagList = tags;
    });
  });

  You can use this to update the tagList attribute in the <studio.ui.components.tags.selector_tag-selector> component.

Styling

The component uses Shadow DOM encapsulation. To customize styles, use the following approach:

studio.ui.components.tags.selector_tag-selector {
  --tag-background-color: #f0f0f0;
  --tag-font-size: 14px;
}

For more complex overrides, use slots to inject custom elements.

Development

Clone the repository and install dependencies:

git clone https://github.com/your-repo/tag-selector.git
cd tag-selector
npm install

File Structure

• src/: Source files
  • tag-selector.mjs: Main component
  • tag-input.mjs: Input field for adding tags
  • selected-tags-list.mjs: List of selected tags
  • utils/debounce.mjs: Utility function for debouncing
• dist/: Bundled output files
• tests/: Unit test files

Running the Development Server

Use the following command to start a local development server:

npm run dev

Testing

The project includes unit tests written with @open-wc/testing. Run the tests using:

npm test

Key test files include:

• src/tag-input.test.mjs
• src/selected-tags-list.test.mjs
• src/tag-selector.test.mjs

Troubleshooting

• Suggestions Not Loading: Ensure the tags-requested event is handled correctly.
• Styling Issues: Confirm that your CSS applies to shadow DOM or use ::part selectors.

License

UNLICENSED. COPYRIGHT 2024 CAPITOL BROADCASTING COMPANY. ALL RIGHTS RESERVED.