1.1.8 • Published 8 months ago

@wral/studio.ui.components.tags.selector v1.1.8

Weekly downloads
-
License
ISC
Repository
-
Last release
8 months ago

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

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.

1.1.8

8 months ago

1.1.7

8 months ago

1.1.6

8 months ago

1.1.4

8 months ago

1.1.5

8 months ago

0.5.2

9 months ago

0.5.1

9 months ago

0.5.0

9 months ago

0.4.0

9 months ago

0.3.0

9 months ago

0.2.6

9 months ago

0.2.5

9 months ago

0.2.4

9 months ago