# PromptsTextEditor

A text input component with auto-suggestion functionality that displays a dropdown menu of predefined words/prompts when clicked. Perfect for scenarios where users need to input from a set of known options with the ability to type custom values.

## Installation

```bash
npm install @ticatec/uniface-element
```

## Import

```typescript
import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
```

## Basic Usage

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let value = '';
  let suggestions = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];
  
  function handleChange(newValue) {
    console.log('Value changed:', newValue);
  }
</script>

<PromptsTextEditor 
  bind:value 
  words={suggestions} 
  onchange={handleChange} 
  placeholder="Type or select a fruit..."
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string \| null` | Required | Current input value |
| `words` | `Array<string>` | Required | Array of suggestion words to display |
| `onchange` | `OnChangeHandler<string \| null>` | `null` | Callback when value changes |
| `onfocus` | `((event: FocusEvent) => void) \| null` | `null` | Callback when input gains focus |
| `onblur` | `((event: FocusEvent) => void) \| null` | `null` | Callback when input loses focus |
| `disabled` | `boolean` | `false` | Whether the input is disabled |
| `readonly` | `boolean` | `false` | Whether the input is read-only |
| `placeholder` | `string` | `""` | Placeholder text |
| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Input visual variant |
| `compact` | `boolean` | `false` | Whether to use compact spacing |
| `prefix` | `string` | `""` | Text prefix to display |
| `suffix` | `string` | `""` | Text suffix to display |
| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | Display mode (Edit/View) |
| `removable` | `boolean` | `true` | Whether to show clear button |
| `menu$height` | `number` | `0` | Fixed height for dropdown menu |
| `style` | `string` | `""` | Additional CSS styles |
| `class` | `string` | `""` | CSS class name |

## Examples

### Basic Text Prompts

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let selectedTag = '';
  let availableTags = [
    'JavaScript', 'TypeScript', 'Svelte', 'React', 'Vue',
    'Python', 'Java', 'C++', 'Go', 'Rust'
  ];
</script>

<PromptsTextEditor 
  bind:value={selectedTag}
  words={availableTags}
  placeholder="Select or type a programming language..."
/>
```

### With Event Handlers

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let currentValue = '';
  let commands = [
    'git add .', 'git commit -m', 'git push origin', 
    'npm install', 'npm run build', 'npm test'
  ];
  
  function handleValueChange(newValue) {
    console.log('Command changed:', newValue);
  }
  
  function handleFocus(event) {
    console.log('Input focused');
  }
  
  function handleBlur(event) {
    console.log('Input blurred');
  }
</script>

<PromptsTextEditor 
  bind:value={currentValue}
  words={commands}
  onchange={handleValueChange}
  onfocus={handleFocus}
  onblur={handleBlur}
  placeholder="Type or select a command..."
/>
```

### Different Variants

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let value1 = '', value2 = '', value3 = '';
  let options = ['Option 1', 'Option 2', 'Option 3'];
</script>

<!-- Default variant -->
<PromptsTextEditor bind:value={value1} words={options} placeholder="Default" />

<!-- Outlined variant -->
<PromptsTextEditor bind:value={value2} words={options} variant="outlined" placeholder="Outlined" />

<!-- Filled variant -->
<PromptsTextEditor bind:value={value3} words={options} variant="filled" placeholder="Filled" />
```

### With Icons

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  import Icon from "@ticatec/uniface-element/Icon";
  
  let searchQuery = '';
  let recentSearches = [
    'JavaScript tutorials', 'Svelte components', 'TypeScript types',
    'CSS animations', 'HTML semantics'
  ];
</script>

<PromptsTextEditor 
  bind:value={searchQuery}
  words={recentSearches}
  placeholder="Search...">
  <svelte:fragment slot="leading-icon">
    <Icon name="search" />
  </svelte:fragment>
</PromptsTextEditor>
```

### Custom Menu Height

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let selectedItem = '';
  let longList = Array.from({length: 50}, (_, i) => `Item ${i + 1}`);
</script>

<PromptsTextEditor 
  bind:value={selectedItem}
  words={longList}
  menu$height={200}
  placeholder="Select from many options..."
/>
```

### Form Integration

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  import Button from "@ticatec/uniface-element/Button";
  
  let formData = {
    category: '',
    priority: '',
    status: ''
  };
  
  const categories = ['Bug', 'Feature', 'Enhancement', 'Documentation'];
  const priorities = ['Low', 'Medium', 'High', 'Critical'];
  const statuses = ['Open', 'In Progress', 'Review', 'Closed'];
  
  function handleSubmit() {
    console.log('Form submitted:', formData);
  }
</script>

<form on:submit|preventDefault={handleSubmit}>
  <div class="form-field">
    <label>Category</label>
    <PromptsTextEditor 
      bind:value={formData.category}
      words={categories}
      placeholder="Select category..."
    />
  </div>
  
  <div class="form-field">
    <label>Priority</label>
    <PromptsTextEditor 
      bind:value={formData.priority}
      words={priorities}
      placeholder="Select priority..."
    />
  </div>
  
  <div class="form-field">
    <label>Status</label>
    <PromptsTextEditor 
      bind:value={formData.status}
      words={statuses}
      placeholder="Select status..."
    />
  </div>
  
  <Button type="primary" label="Submit" onClick={handleSubmit} />
</form>

<style>
  .form-field {
    margin-bottom: 16px;
  }
  
  label {
    display: block;
    margin-bottom: 4px;
    font-weight: 500;
  }
</style>
```

### Disabled and Readonly States

```svelte
<script>
  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
  
  let value1 = 'Readonly value';
  let value2 = '';
  let options = ['Option A', 'Option B', 'Option C'];
</script>

<!-- Readonly -->
<PromptsTextEditor 
  bind:value={value1} 
  words={options} 
  readonly 
  placeholder="This is readonly"
/>

<!-- Disabled -->
<PromptsTextEditor 
  bind:value={value2} 
  words={options} 
  disabled 
  placeholder="This is disabled"
/>
```

## Features

- **Auto-suggestion**: Dropdown list of predefined words/prompts
- **Free text input**: Users can type custom values not in the suggestion list
- **Clear functionality**: Optional clear button when `removable` is true
- **Focus management**: Automatic focus handling and events
- **Keyboard navigation**: Navigate suggestions with keyboard
- **Flexible styling**: Multiple visual variants and custom styling
- **Icon support**: Leading icon slot for additional context

## Behavior

1. **Dropdown Trigger**: Click the dropdown arrow to show all available options
2. **Selection**: Click any option to select it and close the dropdown
3. **Free Input**: Type any text, even if not in the suggestions list
4. **Clear Action**: Click the clear button (when enabled) to empty the input
5. **Click Outside**: Dropdown closes when clicking outside the component

## Styling

The component inherits styling from the base `CommonEditor` and can be customized using:

- CSS custom properties (defined in the theme)
- The `style` prop for inline styles
- The `class` prop for custom CSS classes
- The `variant` prop for predefined visual styles

## Accessibility

- Proper keyboard navigation support
- Screen reader compatible
- Focus management and indicators
- Semantic HTML structure
- ARIA attributes for dropdown interaction

## Best Practices

1. **Suggestion Quality**: Provide relevant, useful suggestions that match user expectations
2. **List Length**: Keep suggestion lists manageable (under 20 items for optimal UX)
3. **Custom Height**: Use `menu$height` for long lists to prevent UI overflow
4. **Clear Labels**: Provide descriptive placeholders and labels
5. **Event Handling**: Use `onchange`, `onfocus`, and `onblur` for proper form integration
6. **State Management**: Bind to reactive variables for proper state updates

## Browser Support

- Modern browsers with ES6+ support
- Compatible with Svelte 5+
- Responsive design principles

## Related Components

- `TextEditor` - Simple text input without suggestions
- `OptionsSelect` - Dropdown selection from predefined options
- `OptionsMultiSelect` - Multiple selection dropdown
- `LookupEditor` - Advanced lookup with search capabilities