@ewc-lib/ewc-singleselect

EWC SingleSelect

A customizable single-select component built with LitElement and TailwindCSS. This component allows users to select a single option from a dropdown list, with support for grouping options and search functionality.

Features

• Single Selection: Allows users to select one option from the dropdown list.
• Option Grouping: Displays options in groups with dividers.
• Search Functionality: Includes a search field when there are 10 or more options (configurable).
• Keyboard Navigation: Supports navigation using arrow keys, Enter, Space, Tab, and Escape.
• Accessible: Uses appropriate ARIA roles and attributes for accessibility.
• Inactive State: Disables selection for inactive options.
• Customizable Appearance: Supports light and dark themes.
• Version Information: The component version can be retrieved using the ewc-version attribute.

Installation

To install the component, use NPM:

npm install @ewc-lib/ewc-singleselect

Usage

Import the component in your project and use it in your HTML:

Importing in a JavaScript or TypeScript File

import '@ewc-lib/ewc-singleselect';

Using in HTML

<ewc-singleselect
  options='[
    [{"code": "EU27_2020", "name": "European Union", "status": "active"}],
    [
      {"code": "AT", "name": "Austria", "status": "active"},
      {"code": "BE", "name": "Belgium", "status": "active"},
      ...
    ]
  ]'
  defaultOption="EU27_2020"
  activeOption="DE"
  dropdownHeight="200px"
  selectedLabel="Select below"
  invertColors="false"
  searchMode=""
></ewc-singleselect>

Retrieving Version Information

The component version can be accessed through the ewc-version attribute:

const singleSelect = document.querySelector('ewc-singleselect');
const version = singleSelect?.getAttribute('ewc-version');
console.log('Component version:', version); // e.g., "1.0.0-alpha"

Attributes

• options: JSON array of option groups. Each option object should have a code, name, and status.
• defaultOption: Default selected option code.
• activeOption: Initially active option code.
• dropdownHeight: Height of the dropdown list (e.g., "200px").
• selectedLabel: Text to display when no option is selected.
• invertColors: Use this when embedding the component on a dark background.
• useParentWidth: When set to true, the component will expand to fill the width of its parent container if the parent is wider than the component's calculated width.
• searchMode: Controls search field visibility:
  • "" (default): Shows search when 10+ options
  • "force": Always shows search
  • "false": Never shows search
• ewc-version: Read-only attribute that contains the component version.

Events

The component dispatches custom events for interactions:

• option-selected: Fired when an option is selected.
• option-status-change: Fired when an option's status changes.
• version-change: Fired when the component version changes.
• reset-select: Fired when the component is reset to its initial state.

singleSelect.addEventListener("option-selected", (event) => {
  console.log("Option selected:", event.detail.option);
});

singleSelect.addEventListener("option-status-change", (event) => {
  console.log("Option status changed:", event.detail.optionCode, event.detail.status);
});

singleSelect.addEventListener("version-change", (event) => {
  console.log("Component version:", event.detail.version);
});

singleSelect.addEventListener("reset-select", (event) => {
  console.log("Component reset to:", {
    defaultOption: event.detail.defaultOption,
    activeOption: event.detail.activeOption
  });
});

Methods

The component provides the following methods:

• toggleOptionStatus(optionCode: string): Toggles the active/inactive status of an option.
• resetSelect(): Resets the component to its initial state, including:
  • Restores all options to their initial active/inactive state
  • Sets the selection back to the default option
  • Resets the active option to its initial value

Dynamically Updating Options

To dynamically change the options of the ewc-singleselect component after it has been rendered, you should remove the existing component from the DOM and create a new instance with the updated options attribute.

Here is an example of how you can achieve this:

// Assuming 'app' is the parent container for the component
const app = document.querySelector('#app');
let singleSelect = document.querySelector('ewc-singleselect');

function updateOptions(newOptions, newDefaultOption, newActiveOption) {
  // If the component already exists, remove it
  if (singleSelect) {
    singleSelect.remove();
  }

  // Create a new instance of the component
  singleSelect = document.createElement('ewc-singleselect');

  // Set the new options and other attributes
  singleSelect.setAttribute('options', JSON.stringify(newOptions));
  singleSelect.setAttribute('defaultOption', newDefaultOption);
  singleSelect.setAttribute('activeOption', newActiveOption);
  // Set other attributes as needed...

  // Append the new component to the container
  app.appendChild(singleSelect);
}

// Example usage:
const newOptionsData = [
  [{ "code": "new1", "name": "New Option 1", "status": "active" }]
];
const newDefault = "new1";
const newActive = "new1";
updateOptions(newOptionsData, newDefault, newActive);

Development

Building the Project

Start a watch server for the SingleSelect

Compile the TypeScript code to JavaScript and watch for changes.

npm run watch

Start a server for the site to see development changes

cd site
npm run dev

Testing Locally

Before publishing, test the package locally:

• Run npm pack to create a tarball.
• Install it in another project with npm install ../path-to-your-package/@ewc-lib/ewc-singleselect-x.y.z.tgz.

License

This project is licensed under the EUPL License.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.

Changelog

[1.0.0] - Initial Release

• Initial version with single-select functionality
• Search support
• Keyboard navigation
• Accessibility features
• Version information via ewc-version attribute