npm package: @outbook/webcomponents-form-combobox-select
Description: Web components form-combobox-select
Author: Antonio Rodríguez
Latest version: 1.0.0

# @outbook/webcomponents-form-combobox-select

A customizable, accessible combobox select web component built with Lit and Haunted.

## Features

- Fully accessible following WAI-ARIA combobox patterns.
- Supports type-ahead searching.
- Keyboard navigation (Arrow keys, Enter, Escape, PageUp/Down, Home/End).
- Integrated validation and error messaging.
- Multi-language support (i18n).
- Easy to use as a standalone custom element or through a Lit-ready wrapper function.

## Installation

```bash
npm install @outbook/webcomponents-form-combobox-select
```

## Usage

### Direct Custom Element

You can use the `<outbook-form-combobox-select>` tag directly in your HTML. To set the options, you must assign the `options` property via JavaScript.

```html
<outbook-form-combobox-select
  label="Select an option"
  description="Please choose one from the list"
  input-name="my-selection"
  required="required"
></outbook-form-combobox-select>

<script type="module">
  import '@outbook/webcomponents-form-combobox-select';

  const combobox = document.querySelector('outbook-form-combobox-select');
  combobox.options = [
    { value: '1', label: 'Option One' },
    { value: '2', label: 'Option Two' },
    { value: '3', label: 'Option Three' }
  ];

  combobox.addEventListener('change', (e) => {
    console.log('Selected value:', e.detail.value);
  });
</script>
```

### Wrapper Helper Function (Lit)

If you are using Lit, you can use the `FormComboboxSelect` helper function for a more declarative approach.

```javascript
import { html } from 'lit';
import { FormComboboxSelect } from '@outbook/webcomponents-form-combobox-select';

const myOptions = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
  { value: 'cherry', label: 'Cherry' }
];

const template = html`
  ${FormComboboxSelect({
    label: 'Favorite Fruit',
    inputName: 'fruit',
    options: myOptions,
    isRequired: true,
    placeholder: 'Select a fruit...',
    validateFn: (e) => console.log('Is valid:', e.detail.isValid),
    onChange: (e) => console.log('Changed to:', e.detail.value)
  })}
`;
```

## API Reference

### Attributes & Properties

| Attribute | Property | Type | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `input-name` | `inputName` | `string` | - | Name attribute for the underlying hidden input. |
| `description` | `description` | `string` | - | Helper text displayed below the field. |
| `label` | `label` | `string` | - | Label text for the combobox. |
| `labelledby` | `labelledby` | `string` | - | ID of an external element to use as a label (ARIA). |
| `input-id` | `inputId` | `string` | auto-generated | ID for the combobox element. |
| `required` | `required` | `'required'\|'optional'` | `'optional'` | Whether the field is mandatory. |
| `disabled` | `disabled` | `boolean` | `false` | Disables the component when true. |
| `validate-message`| `validateMessage` | `string` | - | Custom error message to show when invalid. |
| `placeholder` | `placeholder` | `string` | - | Text to show when no option is selected. |
| `lang` | `lang` | `string` | `'en'` | Language code for internationalization. |
| `test-id` | `testId` | `string` | - | ID for testing purposes (data-test-id). |
| - | `options` | `Array` | `[]` | Array of options. Each can be a string or `{ value, label, content, selected }`. |

### Events

| Event | Detail | Description |
| :--- | :--- | :--- |
| `change` | `{ index, value, label, option }` | Fired when an option is selected. |
| `validated` | `{ isValid }` | Fired when validation state changes. |
| `input-keyup` | `{ originalEvent }` | Fired on keyup within the combobox. |

### Imperative Methods

- `reset()`: Resets the selection and validation state.
- `getValue()`: Returns the currently selected value.

## Styling

The component uses Shadow DOM. Customization is primarily handled through the internal SCSS, following the project's design system.