feat: Add MaxItems Option To Limit Multi-Select HSSelect

[eadwinCode]

MaxItems Feature for HSSelect

Overview

This feature adds the ability to limit the number of selections in a multi-select HSSelect component. When the maximum number of items is reached, the dropdown automatically filters to show only the selected items, providing a better user experience for limited selection scenarios.

Changes Made

1. Interface Updates (src/js/plugins/select/interfaces.ts)

• Added maxItems?: number property to ISelectOptions interface

2. HSSelect Class Updates (src/js/plugins/select/index.ts)

New Properties

• private readonly maxItems: number | null - Stores the maximum number of items that can be selected

Constructor Updates

• Reads maxItems from options or data attributes
• Initializes the maxItems property

New Methods

isMaxItemsReached(): boolean

• Checks if the maximum items limit has been reached
• Returns true only for multiple select with items at or above the max
• Returns false for single select or when no limit is set

filterOptionsToSelected(): void

• Filters the dropdown to show only currently selected items
• Hides all non-selected options
• Used when max items limit is reached

showAllOptions(): void

• Shows all options in the dropdown
• Removes the hidden class from all options
• Used when going below the max items limit

searchWithinSelected(val: string): void

• Searches only within the selected items when max is reached
• Applies search filtering while respecting the selected items constraint
• Handles "no results" messaging appropriately

Modified Methods

buildDropdown()

• Added check at the end to apply initial filtering if max items is already reached
• Ensures proper state when component initializes with pre-selected items

searchOptions(val: string)

• Added check at the beginning to use searchWithinSelected when max items is reached
• Maintains normal search behavior when below the limit

onSelectOption(val: string)

• Tracks whether max was reached before and after selection
• Filters to selected items when max is just reached
• Shows all options and re-applies search when going below max
• Maintains smooth transition between filtered and unfiltered states

remoteSearch(val: string)

• Added check to use searchWithinSelected when max items is reached
• Works seamlessly with API-based data sources
• Maintains normal remote search behavior when below the limit

Usage

Via JavaScript Options

new HSSelect(element, {
    maxItems: 3,
    hasSearch: true,
    mode: 'tags',
    placeholder: 'Select up to 3 items...'
});

Via Data Attributes

<select 
    data-select='{"maxItems": 3, "hasSearch": true, "mode": "tags"}'
    multiple
    class="hidden">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
    <!-- more options -->
</select>

Via data-max-items Attribute

<select 
    data-select='{"hasSearch": true, "mode": "tags"}'
    data-max-items="5"
    multiple
    class="hidden">
    <!-- options -->
</select>

Features

Core Functionality

• ✅ Limits the number of selectable items in multi-select
• ✅ Works with both tags mode and default mode
• ✅ Automatically filters dropdown when max is reached
• ✅ Shows all options again when going below the max
• ✅ Seamlessly integrates with search functionality
• ✅ Works with remote API data sources
• ✅ No breaking changes to existing code

User Experience

• When max items is reached:

  • Dropdown shows only selected items
  • Search is limited to selected items only
  • Users can still deselect and swap items

• When below max items:

  • Normal behavior - all options visible
  • Full search functionality available
  • Can select any available option

Edge Cases Handled

• Pre-selected items on initialization
• Switching between above/below max threshold
• Search state preservation when toggling
• Remote data with pagination
• Single select (maxItems is ignored)
• No max limit set (feature disabled)

Compatibility

Works With

• ✅ Tags mode (mode: 'tags')
• ✅ Default multi-select mode
• ✅ Search functionality (hasSearch: true)
• ✅ Remote API data (apiUrl)
• ✅ Pagination/infinite scroll (apiLoadMore)
• ✅ All existing HSSelect options

Does Not Affect

• ❌ Single select dropdowns (feature is automatically disabled)
• ❌ Multi-select without maxItems set (normal behavior)