npm package: @polarityio/pi-input
Description: Text input component with multiple types, validation, clearable field, and error states
Latest version: 1.0.3

# Polarity Integration Component Library

## Input Component

A text input component supporting multiple input types with validation, clearable functionality, password visibility toggle, and comprehensive error state management.

## Installation

```bash
npm install @polarityio/pi-input
```

### Peer Dependencies

- [lit](https://lit.dev/) ^3.0.0

## Usage

```javascript
import '@polarityio/pi-input';
```

```html
<!-- Basic text input -->
<pi-input label="Username" placeholder="Enter your username"></pi-input>

<!-- Password input with toggle visibility -->
<pi-input type="password" label="Password" placeholder="Enter password"></pi-input>

<!-- Clearable input -->
<pi-input clearable placeholder="Search..." value="some text"></pi-input>

<!-- Number input with constraints -->
<pi-input type="number" label="Quantity" min="0" max="100" step="1"></pi-input>

<!-- Input with error message -->
<pi-input label="Email" type="email" error error-message="Please enter a valid email"></pi-input>

<!-- With prefix and suffix slots -->
<pi-input placeholder="Amount">
  <span slot="prefix">$</span>
  <span slot="suffix">.00</span>
</pi-input>
```

### Handling Events

```javascript
const input = document.querySelector('pi-input');

input.addEventListener('pi-input', (e) => {
  console.log('Current value:', e.detail.value);
});

input.addEventListener('pi-change', (e) => {
  console.log('Committed value:', e.detail.value);
});

input.addEventListener('pi-clear', () => {
  console.log('Input cleared');
});
```

## API Reference

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'text' \| 'number' \| 'password' \| 'email' \| 'search' \| 'tel' \| 'url'` | `'text'` | Input type |
| `value` | `string` | `''` | Current input value |
| `placeholder` | `string` | `''` | Placeholder text displayed when input is empty |
| `label` | `string` | `''` | Label text displayed above the input |
| `name` | `string` | `''` | HTML name attribute for form submission |
| `disabled` | `boolean` | `false` | Disables the input and hides action buttons |
| `readonly` | `boolean` | `false` | Makes the input read-only |
| `clearable` | `boolean` | `false` | Shows a clear button when the input has a value |
| `error` | `boolean` | `false` | Sets error state styling on the input |
| `errorMessage` | `string` | `''` | Error message displayed below the input. Setting this also activates the error state. |
| `min` | `string \| undefined` | `undefined` | Minimum value (for number inputs) |
| `max` | `string \| undefined` | `undefined` | Maximum value (for number inputs) |
| `step` | `string \| undefined` | `undefined` | Step value for number inputs |
| `maxlength` | `number \| undefined` | `undefined` | Maximum character length |
| `minlength` | `number \| undefined` | `undefined` | Minimum character length |
| `pattern` | `string \| undefined` | `undefined` | Regex pattern for validation |
| `autocomplete` | `string` | `'off'` | HTML autocomplete attribute |

### Events

| Event Name | Detail | Description |
| --- | --- | --- |
| `pi-input` | `{ value: string }` | Fired on each keystroke in the input field |
| `pi-change` | `{ value: string }` | Fired when the value changes and the input loses focus |
| `pi-clear` | *(none)* | Fired when the clear button is clicked |

### Slots

| Slot Name | Description |
| --- | --- |
| `prefix` | Content displayed to the left of the input (e.g., icons, currency symbols) |
| `suffix` | Content displayed to the right of the input (e.g., units, icons) |

### CSS Custom Properties

| Property | Default | Description |
| --- | --- | --- |
| `--pi-input-line-height` | `1.75em` | Height of the input wrapper |
| `--pi-input-padding` | `4px 8px` | Padding inside the input wrapper |
| `--pi-input-border` | `1px solid var(--pi-input-border-color)` | Border definition |
| `--pi-input-border-color` | `var(--pi-color-border-element)` | Border color |
| `--pi-input-border-radius` | `var(--pi-size-radius-base, 4px)` | Border radius |
| `--pi-input-background` | `var(--pi-color-background-container-base)` | Background color |
| `--pi-input-text-color` | `var(--pi-color-font-primary)` | Text color |
| `--pi-input-disabled-bg` | `var(--pi-color-background-container-disabled)` | Background when disabled |

### CSS Parts

| Part Name | Description |
| --- | --- |
| `wrapper` | The main flex container holding the input and action buttons |
| `input` | The native HTML `<input>` element |
| `clear-button` | The clear (×) button shown when `clearable` is true and the input has a value |
| `password-toggle` | The password visibility toggle button (eye icon) for password inputs |
| `error-message` | The error message container below the input |

### Public Methods

| Method | Description |
| --- | --- |
| `focus(options?: FocusOptions)` | Programmatically focuses the native input element |
| `select()` | Selects all text in the input field |

## Theming

Customize the appearance using CSS custom properties. This component uses design tokens from `@polarityio/pi-shared` for consistent theming across the component library.

```css
pi-input {
  --pi-input-border-radius: 8px;
  --pi-input-padding: 8px 12px;
}

pi-input::part(input) {
  font-size: 1rem;
}
```

## License

MIT