@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/text-editor/README.md

@@ -0,0 +1,466 @@
+# TextEditor
+
+A versatile text input component that provides comprehensive input handling, event forwarding, and display modes. Built on top of the CommonEditor base component with advanced features like prefix/suffix support, clear functionality, and flexible styling.
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import TextEditor from "@ticatec/uniface-element/TextEditor";
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let inputValue = '';
+</script>
+
+<TextEditor 
+  bind:value={inputValue} 
+  placeholder="Enter text..."
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | `""` | Current input value |
+| `disabled` | `boolean` | `false` | Whether the input is disabled |
+| `readonly` | `boolean` | `false` | Whether the input is read-only |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Input visual variant |
+| `compact` | `boolean` | `false` | Whether to use compact spacing |
+| `style` | `string` | `""` | Additional CSS styles |
+| `prefix` | `string` | `""` | Text prefix to display |
+| `suffix` | `string` | `""` | Text suffix to display |
+| `removable` | `boolean` | `true` | Whether to show clear button |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | Display mode (Edit/View) |
+| `class` | `string` | `""` | CSS class name |
+
+## Events
+
+The TextEditor component forwards all native input events:
+
+| Event | Description |
+|-------|-------------|
+| `input` | Fired on every input change |
+| `change` | Fired when input loses focus or Enter is pressed |
+| `focus` | Fired when input gains focus |
+| `blur` | Fired when input loses focus |
+| `keydown` | Fired when a key is pressed down |
+| `keyup` | Fired when a key is released |
+| `keypress` | Fired when a key is pressed |
+| `compositionstart` | Fired when IME composition starts |
+| `compositionend` | Fired when IME composition ends |
+| `compositionupdate` | Fired during IME composition |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `setFocus()` | Programmatically focus the input |
+
+## Examples
+
+### Basic Text Input
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let userName = '';
+  let email = '';
+</script>
+
+<div class="form-group">
+  <label>Username:</label>
+  <TextEditor bind:value={userName} placeholder="Enter username" />
+</div>
+
+<div class="form-group">
+  <label>Email:</label>
+  <TextEditor bind:value={email} placeholder="Enter email address" />
+</div>
+
+<style>
+  .form-group {
+    margin-bottom: 16px;
+  }
+  
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+</style>
+```
+
+### With Event Handlers
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let inputValue = '';
+  let isFocused = false;
+  
+  function handleInput(event) {
+    console.log('Input changed:', event.target.value);
+  }
+  
+  function handleChange(event) {
+    console.log('Change committed:', event.target.value);
+  }
+  
+  function handleFocus(event) {
+    console.log('Input focused');
+    isFocused = true;
+  }
+  
+  function handleBlur(event) {
+    console.log('Input blurred');
+    isFocused = false;
+  }
+</script>
+
+<TextEditor 
+  bind:value={inputValue}
+  placeholder="Type something..."
+  on:input={handleInput}
+  on:change={handleChange}
+  on:focus={handleFocus}
+  on:blur={handleBlur}
+/>
+
+{#if isFocused}
+  <p>Input is currently focused</p>
+{/if}
+```
+
+### Different Variants
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let value1 = '', value2 = '', value3 = '', value4 = '';
+</script>
+
+<!-- Default variant -->
+<TextEditor bind:value={value1} placeholder="Default" />
+
+<!-- Plain variant -->
+<TextEditor bind:value={value2} variant="plain" placeholder="Plain" />
+
+<!-- Outlined variant -->
+<TextEditor bind:value={value3} variant="outlined" placeholder="Outlined" />
+
+<!-- Filled variant -->
+<TextEditor bind:value={value4} variant="filled" placeholder="Filled" />
+```
+
+### With Prefix and Suffix
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let amount = '';
+  let website = '';
+  let username = '';
+</script>
+
+<!-- Currency input with prefix -->
+<TextEditor 
+  bind:value={amount} 
+  prefix="$" 
+  placeholder="0.00"
+/>
+
+<!-- Website URL with prefix -->
+<TextEditor 
+  bind:value={website} 
+  prefix="https://" 
+  placeholder="example.com"
+/>
+
+<!-- Username with suffix -->
+<TextEditor 
+  bind:value={username} 
+  suffix="@company.com" 
+  placeholder="username"
+/>
+```
+
+### With Icons
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  import Icon from "@ticatec/uniface-element/Icon";
+  
+  let searchTerm = '';
+  let email = '';
+</script>
+
+<!-- Search input with leading icon -->
+<TextEditor bind:value={searchTerm} placeholder="Search...">
+  <svelte:fragment slot="leading-icon">
+    <Icon name="search" />
+  </svelte:fragment>
+</TextEditor>
+
+<!-- Email input with trailing icon -->
+<TextEditor bind:value={email} placeholder="Enter email">
+  <svelte:fragment slot="trailing-icon">
+    <Icon name="email" />
+  </svelte:fragment>
+</TextEditor>
+```
+
+### Disabled and Readonly States
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let normalValue = '';
+  let readonlyValue = 'This is readonly';
+  let disabledValue = '';
+</script>
+
+<!-- Normal input -->
+<TextEditor bind:value={normalValue} placeholder="Normal input" />
+
+<!-- Readonly input -->
+<TextEditor bind:value={readonlyValue} readonly />
+
+<!-- Disabled input -->
+<TextEditor bind:value={disabledValue} disabled placeholder="Disabled input" />
+```
+
+### Compact Mode
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let compactValue = '';
+</script>
+
+<div class="toolbar">
+  <TextEditor 
+    bind:value={compactValue} 
+    compact 
+    placeholder="Compact input" 
+  />
+</div>
+
+<style>
+  .toolbar {
+    display: flex;
+    align-items: center;
+    padding: 8px;
+    background: #f8f9fa;
+  }
+</style>
+```
+
+### Without Clear Button
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  
+  let value = '';
+</script>
+
+<TextEditor 
+  bind:value 
+  removable={false}
+  placeholder="No clear button"
+/>
+```
+
+### Form Integration
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  import Button from "@ticatec/uniface-element/Button";
+  
+  let formData = {
+    firstName: '',
+    lastName: '',
+    company: '',
+    title: ''
+  };
+  
+  function handleSubmit() {
+    console.log('Form submitted:', formData);
+  }
+  
+  function resetForm() {
+    formData = {
+      firstName: '',
+      lastName: '',
+      company: '',
+      title: ''
+    };
+  }
+</script>
+
+<form on:submit|preventDefault={handleSubmit}>
+  <div class="form-row">
+    <div class="form-field">
+      <label>First Name</label>
+      <TextEditor bind:value={formData.firstName} placeholder="John" />
+    </div>
+    <div class="form-field">
+      <label>Last Name</label>
+      <TextEditor bind:value={formData.lastName} placeholder="Doe" />
+    </div>
+  </div>
+  
+  <div class="form-field">
+    <label>Company</label>
+    <TextEditor bind:value={formData.company} placeholder="Acme Corp" />
+  </div>
+  
+  <div class="form-field">
+    <label>Job Title</label>
+    <TextEditor bind:value={formData.title} placeholder="Software Engineer" />
+  </div>
+  
+  <div class="form-actions">
+    <Button type="secondary" label="Reset" onClick={resetForm} />
+    <Button type="primary" label="Submit" onClick={handleSubmit} />
+  </div>
+</form>
+
+<style>
+  .form-row {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 16px;
+    margin-bottom: 16px;
+  }
+  
+  .form-field {
+    margin-bottom: 16px;
+  }
+  
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+  
+  .form-actions {
+    display: flex;
+    gap: 12px;
+    justify-content: flex-end;
+  }
+</style>
+```
+
+### Programmatic Focus
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  import Button from "@ticatec/uniface-element/Button";
+  
+  let textEditor;
+  let inputValue = '';
+  
+  function focusInput() {
+    textEditor.setFocus();
+  }
+</script>
+
+<Button label="Focus Input" onClick={focusInput} />
+
+<TextEditor 
+  bind:this={textEditor}
+  bind:value={inputValue}
+  placeholder="Click button to focus me"
+/>
+```
+
+### Display Modes
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/uniface-element/TextEditor";
+  import { DisplayMode } from "@ticatec/uniface-element/common/DisplayMode";
+  
+  let value = 'Sample text';
+  let isEditing = false;
+</script>
+
+<button on:click={() => isEditing = !isEditing}>
+  {isEditing ? 'Switch to View' : 'Switch to Edit'}
+</button>
+
+<TextEditor 
+  bind:value 
+  displayMode={isEditing ? DisplayMode.Edit : DisplayMode.View}
+  placeholder="Enter text..."
+/>
+```
+
+## Features
+
+- **Comprehensive Event Handling**: Forwards all native input events automatically
+- **Advanced Input Support**: Handles composition events for international text input
+- **Flexible Display**: Supports both edit and view modes
+- **Clear Functionality**: Optional clear button with customizable behavior
+- **Icon Support**: Leading and trailing icon slots
+- **Prefix/Suffix**: Text prefix and suffix support
+- **Focus Management**: Programmatic focus control
+- **Flexible Styling**: Multiple visual variants and custom styling
+
+## Event Forwarding
+
+The TextEditor component uses an advanced event forwarding system that automatically forwards all native input events while allowing for custom handling of specific events like `input` and `change`.
+
+## Accessibility
+
+- Proper semantic HTML structure
+- Keyboard navigation support
+- Screen reader compatible
+- Focus indicators and management
+- ARIA attributes where appropriate
+
+## Best Practices
+
+1. **Event Handling**: Use `on:input` for real-time feedback and `on:change` for committed changes
+2. **Validation**: Implement validation logic in event handlers
+3. **Placeholder Text**: Provide helpful placeholder text for better UX
+4. **Labels**: Always associate inputs with proper labels
+5. **Error States**: Handle and display validation errors appropriately
+6. **Focus Management**: Use programmatic focus for better accessibility
+
+## Browser Support
+
+- Modern browsers with full input event support
+- Compatible with Svelte 5+
+- IME (Input Method Editor) support for international input
+- Touch-friendly interface
+
+## Related Components
+
+- `PasswordEditor` - Specialized password input with visibility toggle
+- `SearchBox` - Search-specific input with built-in search icon
+- `NumberEditor` - Numeric input with validation
+- `MemoEditor` - Multi-line text input (textarea)
+- `PromptsTextEditor` - Text input with auto-suggestions