@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/prompts-text-editor/README.md

@@ -0,0 +1,329 @@
+# 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

package/dist/prompts-text-editor/README_CN.md

@@ -0,0 +1,329 @@
+# 提示文本编辑器组件
+
+一个带自动建议功能的文本输入组件，点击时显示预定义单词/提示的下拉菜单。适用于用户需要从一组已知选项中输入并支持自定义输入的场景。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
+  
+  let value = '';
+  let suggestions = ['苹果', '香蕉', '樱桃', '枣', '接骨木'];
+  
+  function handleChange(newValue) {
+    console.log('值已更改：', newValue);
+  }
+</script>
+
+<PromptsTextEditor 
+  bind:value 
+  words={suggestions} 
+  onchange={handleChange} 
+  placeholder="输入或选择一种水果..."
+/>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `value` | `string \| null` | 必需 | 当前输入值 |
+| `words` | `Array<string>` | 必需 | 显示的建议单词数组 |
+| `onchange` | `OnChangeHandler<string \| null>` | `null` | 值更改时的回调函数 |
+| `onfocus` | `((event: FocusEvent) => void) \| null` | `null` | 输入框获得焦点时的回调函数 |
+| `onblur` | `((event: FocusEvent) => void) \| null` | `null` | 输入框失去焦点时的回调函数 |
+| `disabled` | `boolean` | `false` | 输入框是否禁用 |
+| `readonly` | `boolean` | `false` | 输入框是否只读 |
+| `placeholder` | `string` | `""` | 占位符文本 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 输入框的视觉变体 |
+| `compact` | `boolean` | `false` | 是否使用紧凑间距 |
+| `prefix` | `string` | `""` | 显示的文本前缀 |
+| `suffix` | `string` | `""` | 显示的文本后缀 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式（编辑/查看） |
+| `removable` | `boolean` | `true` | 是否显示清除按钮 |
+| `menu$height` | `number` | `0` | 下拉菜单的固定高度 |
+| `style` | `string` | `""` | 附加 CSS 样式 |
+| `class` | `string` | `""` | CSS 类名 |
+
+## 示例
+
+### 基本文本提示
+
+```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="选择或输入一种编程语言..."
+/>
+```
+
+### 带事件处理程序
+
+```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('命令已更改：', newValue);
+  }
+  
+  function handleFocus(event) {
+    console.log('输入框已聚焦');
+  }
+  
+  function handleBlur(event) {
+    console.log('输入框已失焦');
+  }
+</script>
+
+<PromptsTextEditor 
+  bind:value={currentValue}
+  words={commands}
+  onchange={handleValueChange}
+  onfocus={handleFocus}
+  onblur={handleBlur}
+  placeholder="输入或选择一个命令..."
+/>
+```
+
+### 不同变体
+
+```svelte
+<script>
+  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
+  
+  let value1 = '', value2 = '', value3 = '';
+  let options = ['选项 1', '选项 2', '选项 3'];
+</script>
+
+<!-- 默认变体 -->
+<PromptsTextEditor bind:value={value1} words={options} placeholder="默认" />
+
+<!-- 轮廓变体 -->
+<PromptsTextEditor bind:value={value2} words={options} variant="outlined" placeholder="轮廓" />
+
+<!-- 填充变体 -->
+<PromptsTextEditor bind:value={value3} words={options} variant="filled" placeholder="填充" />
+```
+
+### 带图标
+
+```svelte
+<script>
+  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
+  import Icon from "@ticatec/uniface-element/Icon";
+  
+  let searchQuery = '';
+  let recentSearches = [
+    'JavaScript 教程', 'Svelte 组件', 'TypeScript 类型',
+    'CSS 动画', 'HTML 语义'
+  ];
+</script>
+
+<PromptsTextEditor 
+  bind:value={searchQuery}
+  words={recentSearches}
+  placeholder="搜索...">
+  <svelte:fragment slot="leading-icon">
+    <Icon name="search" />
+  </svelte:fragment>
+</PromptsTextEditor>
+```
+
+### 自定义菜单高度
+
+```svelte
+<script>
+  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
+  
+  let selectedItem = '';
+  let longList = Array.from({length: 50}, (_, i) => `项目 ${i + 1}`);
+</script>
+
+<PromptsTextEditor 
+  bind:value={selectedItem}
+  words={longList}
+  menu$height={200}
+  placeholder="从多个选项中选择..."
+/>
+```
+
+### 表单集成
+
+```svelte
+<script>
+  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
+  import Button from "@ticatec/uniface-element/Button";
+  
+  let formData = {
+    category: '',
+    priority: '',
+    status: ''
+  };
+  
+  const categories = ['错误', '功能', '增强', '文档'];
+  const priorities = ['低', '中', '高', '紧急'];
+  const statuses = ['开放', '进行中', '审核', '关闭'];
+  
+  function handleSubmit() {
+    console.log('表单提交：', formData);
+  }
+</script>
+
+<form on:submit|preventDefault={handleSubmit}>
+  <div class="form-field">
+    <label>类别</label>
+    <PromptsTextEditor 
+      bind:value={formData.category}
+      words={categories}
+      placeholder="选择类别..."
+    />
+  </div>
+  
+  <div class="form-field">
+    <label>优先级</label>
+    <PromptsTextEditor 
+      bind:value={formData.priority}
+      words={priorities}
+      placeholder="选择优先级..."
+    />
+  </div>
+  
+  <div class="form-field">
+    <label>状态</label>
+    <PromptsTextEditor 
+      bind:value={formData.status}
+      words={statuses}
+      placeholder="选择状态..."
+    />
+  </div>
+  
+  <Button type="primary" label="提交" onClick={handleSubmit} />
+</form>
+
+<style>
+  .form-field {
+    margin-bottom: 16px;
+  }
+  
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+</style>
+```
+
+### 禁用和只读状态
+
+```svelte
+<script>
+  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
+  
+  let value1 = '只读值';
+  let value2 = '';
+  let options = ['选项 A', '选项 B', '选项 C'];
+</script>
+
+<!-- 只读 -->
+<PromptsTextEditor 
+  bind:value={value1} 
+  words={options} 
+  readonly 
+  placeholder="这是只读的"
+/>
+
+<!-- 禁用 -->
+<PromptsTextEditor 
+  bind:value={value2} 
+  words={options} 
+  disabled 
+  placeholder="这是禁用的"
+/>
+```
+
+## 功能
+
+- **自动建议**：显示预定义单词/提示的下拉列表
+- **自由文本输入**：用户可以输入不在建议列表中的自定义值
+- **清除功能**：当 `removable` 为 true 时显示可选的清除按钮
+- **焦点管理**：自动处理焦点及相关事件
+- **键盘导航**：支持通过键盘导航建议选项
+- **灵活样式**：支持多种视觉变体和自定义样式
+- **图标支持**：支持前导图标插槽以提供额外上下文
+
+## 行为
+
+1. **下拉触发**：点击下拉箭头显示所有可用选项
+2. **选择**：点击任意选项进行选择并关闭下拉菜单
+3. **自由输入**：输入任意文本，即使不在建议列表中
+4. **清除操作**：点击清除按钮（启用时）清空输入框
+5. **点击外部**：点击组件外部时关闭下拉菜单
+
+## 样式
+
+组件继承自基础 `CommonEditor` 的样式，并可通过以下方式自定义：
+
+- CSS 自定义属性（在主题中定义）
+- `style` 属性用于内联样式
+- `class` 属性用于自定义 CSS 类
+- `variant` 属性用于预定义视觉样式
+
+## 可访问性
+
+- 全面支持键盘导航
+- 屏幕阅读器兼容
+- 焦点管理和指示器
+- 语义化 HTML 结构
+- 下拉交互的 ARIA 属性
+
+## 最佳实践
+
+1. **建议质量**：提供符合用户预期的相关且有用的建议
+2. **列表长度**：保持建议列表长度适中（少于 20 项以获得最佳用户体验）
+3. **自定义高度**：对长列表使用 `menu$height` 以防止 UI 溢出
+4. **清晰标签**：提供描述性的占位符和标签
+5. **事件处理**：使用 `onchange`、`onfocus` 和 `onblur` 进行适当的表单集成
+6. **状态管理**：绑定到响应式变量以确保状态正确更新
+
+## 浏览器支持
+
+- 支持 ES6+ 的现代浏览器
+- 兼容 Svelte 5+
+- 响应式设计原则
+
+## 相关组件
+
+- `TextEditor` - 不带建议的简单文本输入
+- `OptionsSelect` - 从预定义选项中进行下拉选择
+- `OptionsMultiSelect` - 多选下拉菜单
+- `LookupEditor` - 具有搜索功能的高级查找组件