@wral/studio.ui.components.tags.selector NPM

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.

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.