npm package: @outbook/webcomponents-form-input-text
Description: Web components form-input-text
Author: Antonio Rodríguez
Latest version: 1.1.5

# @outbook/webcomponents-form-input-text

This package provides a customizable text input form web component, supporting various input types, validation, and internationalization.

## Installation

```bash
npm install @outbook/webcomponents-form-input-text
```

## Usage

### As a Lit Element

```javascript
import {html, useState} from 'lit';
import {FormInputText} from '@outbook/webcomponents-form-input-text';

function MyForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  const handleValidation = (event) => {
    console.log(`Input validity for ${event.target.inputName}:`, event.detail.isValid);
  };

  const handleKeyup = (event) => {
    if (event.target.inputName === 'email') {
      setEmail(event.target.value);
    } else if (event.target.inputName === 'password') {
      setPassword(event.target.value);
    }
  };

  return html`
    <form>
      ${FormInputText({
    type: 'email',
    inputName: 'email',
    label: 'Email Address',
    required: true,
    inputValue: email,
    onKeyup: handleKeyup,
    validateFn: handleValidation,
  })}
      ${FormInputText({
    type: 'password',
    inputName: 'password',
    label: 'Password',
    required: true,
    inputValue: password,
    onKeyup: handleKeyup,
    validateFn: handleValidation,
  })}
    </form>
  `;
}
```

### Direct HTML Usage

You can also use the custom element directly in your HTML. Remember to import the component's JavaScript for the custom element to be defined.

```javascript
import '@outbook/webcomponents-form-input-text';
```

```html
<outbook-form-input-text
  type="text"
  input-name="username"
  label="Username"
  input-value="initial_value"
  required="required"
  lang="en"
></outbook-form-input-text>

<script>
  document.querySelector('outbook-form-input-text').addEventListener('validated', (e) => {
    console.log('Input validated:', e.detail.isValid);
  });
  document.querySelector('outbook-form-input-text').addEventListener('input-keyup', (e) => {
    console.log('Input keyup:', e.detail.originalEvent);
  });

  // To access methods like reset() or getValue()
  const myInput = document.querySelector('outbook-form-input-text');
  console.log(myInput.getValue());
  // myInput.reset();
</script>
```

## Component: `outbook-form-input-text`

This is the underlying web component. It can be used directly in HTML or in any framework.

### Properties

| Attribute       | Property        | Type      | Default        | Description                                                                     |
|-----------------|-----------------|-----------|----------------|---------------------------------------------------------------------------------|
| `type`          | `type`          | `String`  | `'text'`       | The input type (e.g., `text`, `email`, `password`).                             |
| `input-name`    | `inputName`     | `String`  | `''`           | The `name` attribute for the internal `<input>` element.                        |
| `label`         | `label`         | `String`  | `''`           | The text for the input's label.                                                 |
| `labelledby`    | `labelledby`    | `String`  | `undefined`    | `aria-labelledby` attribute for accessibility.                                  |
| `placeholder`   | `placeholder`   | `String`  | `undefined`    | The `placeholder` text for the input.                                           |
| `input-id`      | `inputId`       | `String`  | `null`         | The `id` for the internal `<input>`. A unique ID is generated if not provided.  |
| `icon`          | `icon`          | `String`  | `null`         | The name of an icon to display inside the input.                                |
| `.icons`        | `icons`         | `Object`  | `{}`           | An object containing icon definitions.                                          |
| `input-value`   | `inputValue`    | `String`  | `''`           | The initial value of the input.                                                 |
| `required`      | `required`      | `String`  | `'optional'`   | Set to `'required'` to make the field mandatory.                                |
| `disabled`      | `disabled`      | `String`  | `false`        | Set to `'disabled'` to disable the input.                                       |
| `validate-message` | `validateMessage` | `String`  | `''`           | A custom error message to display on validation failure.                        |
| `lang`          | `lang`          | `String`  | `'en'`         | Sets the language for localization (e.g., "en", "es").                          |
| `test-id`       | `testId`        | `String`  | `null`         | A test identifier for testing purposes (`data-test-id`).                        |

### Methods

-   **`reset()`**: Resets the input value and validation state.
-   **`getValue()`**: Returns the current value of the input.

### Events

-   **`validated`**: Dispatched whenever the input's validity changes. `event.detail.isValid` (boolean) indicates the current validity.
-   **`input-keyup`**: Dispatched on every `keyup` event inside the input. `event.detail.originalEvent` contains the original `keyup` event.

### Styling

This component does not use Shadow DOM, so its internal elements can be styled directly using global stylesheets.

You need to include the component's SCSS file in your project's main stylesheet.

```scss
@use '@outbook/webcomponents-form-input-text/form-input-text' as form-input-text;

@include form-input-text.style();
```

## License

This component is licensed under the Apache-2.0 License.