@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/form/prompts_text_editor/README.md

@@ -0,0 +1,318 @@
+# 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.
+
+## Features
+
+- **Auto-suggestion**: Dropdown list of predefined words/prompts triggered on click.
+- **Free text input**: Users can type custom values not in the suggestion list.
+- **Clear functionality**: Optional clear button when the field has content.
+- **Focus management**: Automatic focus handling and event forwarding.
+- **Flexible styling**: Multiple visual variants and custom styling support.
+
+## 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={value}
+  words={suggestions}
+  onchange={handleChange}
+  placeholder="Type or select a fruit..."
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string \| undefined` | `undefined` | Current input value (bindable). |
+| `words` | `Array<string>` | — (required) | Array of suggestion words to display in the dropdown. |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Visual style variant. |
+| `compact` | `boolean` | `false` | Compact spacing layout. |
+| `disabled` | `boolean` | `false` | Disables the editor. |
+| `readonly` | `boolean` | `false` | Makes the editor read-only. |
+| `style` | `string` | `""` | Inline CSS styles. |
+| `placeholder` | `string` | `""` | Placeholder text when value is empty. |
+| `tooltip` | `string` | `undefined` | Hover tooltip text. |
+| `error` | `string` | `undefined` | Error message text. |
+| `theme` | `string` | `undefined` | Theme name for appearance switching. |
+| `prefix` | `string` | `""` | Text prefix shown before the input. |
+| `suffix` | `string` | `""` | Text suffix shown after the input. |
+| `menu$height` | `number` | `0` | Fixed height (px) for the suggestion dropdown. `0` means auto. |
+| `onchange` | `(value: string \| undefined) => void` | `undefined` | Fired when the value changes. |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | Input gains focus. |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | Input loses focus. |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `focus()` | Programmatically focuses the input element. |
+
+## 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.
+
+## 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() {
+    console.log("Input focused");
+  }
+
+  function handleBlur() {
+    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" />
+```
+
+### 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";
+
+  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 onsubmit={(e) => { e.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="submit">Submit</button>
+</form>
+
+<style>
+  .form-field {
+    margin-bottom: 16px;
+  }
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+  button {
+    padding: 8px 16px;
+    cursor: pointer;
+  }
+</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"
+/>
+```
+
+### Command Palette
+
+```svelte
+<script>
+  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
+
+  let command = "";
+  const commands = [
+    "File: New", "File: Open", "File: Save",
+    "Edit: Undo", "Edit: Redo", "Edit: Cut", "Edit: Copy", "Edit: Paste",
+    "View: Zoom In", "View: Zoom Out", "View: Reset Zoom",
+    "Terminal: New", "Terminal: Close",
+    "Help: Documentation", "Help: About"
+  ];
+</script>
+
+<div class="command-palette">
+  <PromptsTextEditor
+    bind:value={command}
+    words={commands}
+    variant="outlined"
+    placeholder="Type a command..."
+  />
+</div>
+
+<style>
+  .command-palette {
+    max-width: 400px;
+  }
+</style>
+```
+
+## 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.
+
+## Related Components
+
+- [TextEditor](../text_editor/README.md) — Simple text input without suggestions.
+- [NumberEditor](../number_editor/README.md) — Numeric input with validation.

package/dist/form/prompts_text_editor/README_CN.md

@@ -0,0 +1,318 @@
+# PromptsTextEditor 带建议的文本输入
+
+带自动建议功能的文本输入组件，点击时显示预定义词语/提示的下拉菜单。适用于用户需要从已知选项集中输入，同时支持输入自定义值的场景。
+
+## 功能特性
+
+- **自动建议**: 点击下拉箭头显示预定义词语列表。
+- **自由输入**: 用户可以输入不在建议列表中的自定义文本。
+- **清除功能**: 字段有内容时显示清除按钮。
+- **焦点管理**: 自动焦点处理和事件透传。
+- **灵活样式**: 支持多种视觉变体和自定义样式。
+
+## 安装
+
+```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={value}
+  words={suggestions}
+  onchange={handleChange}
+  placeholder="输入或选择一个水果..."
+/>
+```
+
+## 属性（Props）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `string \| undefined` | `undefined` | 当前输入值（可双向绑定）。 |
+| `words` | `Array<string>` | —（必填） | 下拉菜单中显示的建议词语数组。 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉样式变体。 |
+| `compact` | `boolean` | `false` | 紧凑间距布局。 |
+| `disabled` | `boolean` | `false` | 禁用编辑器。 |
+| `readonly` | `boolean` | `false` | 设为只读。 |
+| `style` | `string` | `""` | 内联 CSS 样式。 |
+| `placeholder` | `string` | `""` | 值为空时的占位符文本。 |
+| `tooltip` | `string` | `undefined` | 悬停提示文本。 |
+| `error` | `string` | `undefined` | 错误信息文本。 |
+| `theme` | `string` | `undefined` | 主题名称，用于切换外观。 |
+| `prefix` | `string` | `""` | 输入框前面的文本。 |
+| `suffix` | `string` | `""` | 输入框后面的文本。 |
+| `menu$height` | `number` | `0` | 建议下拉菜单的固定高度（像素）。`0` 表示自动。 |
+| `onchange` | `(value: string \| undefined) => void` | `undefined` | 值变更时触发。 |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | 输入框获取焦点时触发。 |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | 输入框失去焦点时触发。 |
+
+## 方法
+
+| 方法 | 说明 |
+|------|------|
+| `focus()` | 编程方式让 input 获取焦点。 |
+
+## 行为说明
+
+1. **下拉触发**: 点击下拉箭头显示所有可用选项。
+2. **选择**: 点击任意选项选中并关闭下拉菜单。
+3. **自由输入**: 可输入不在建议列表中的任何文本。
+4. **清除操作**: 点击清除按钮清空输入（当可用时）。
+5. **点击外部**: 点击组件外部区域关闭下拉菜单。
+
+## 示例
+
+### 基本标签选择
+
+```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() {
+    console.log("输入框获得焦点");
+  }
+
+  function handleBlur() {
+    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";
+
+  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";
+
+  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("表单已提交:", formData);
+  }
+</script>
+
+<form onsubmit={(e) => { e.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="submit">提交</button>
+</form>
+
+<style>
+  .form-field {
+    margin-bottom: 16px;
+  }
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+  button {
+    padding: 8px 16px;
+    cursor: pointer;
+  }
+</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="这是禁用的"
+/>
+```
+
+### 命令面板
+
+```svelte
+<script>
+  import PromptsTextEditor from "@ticatec/uniface-element/PromptsTextEditor";
+
+  let command = "";
+  const commands = [
+    "文件: 新建", "文件: 打开", "文件: 保存",
+    "编辑: 撤销", "编辑: 重做", "编辑: 剪切", "编辑: 复制", "编辑: 粘贴",
+    "视图: 放大", "视图: 缩小", "视图: 重置缩放",
+    "终端: 新建", "终端: 关闭",
+    "帮助: 文档", "帮助: 关于"
+  ];
+</script>
+
+<div class="command-palette">
+  <PromptsTextEditor
+    bind:value={command}
+    words={commands}
+    variant="outlined"
+    placeholder="输入命令..."
+  />
+</div>
+
+<style>
+  .command-palette {
+    max-width: 400px;
+  }
+</style>
+```
+
+## 最佳实践
+
+1. **建议质量**: 提供相关、有用的建议，符合用户预期。
+2. **列表长度**: 建议列表保持简洁（建议少于 20 项以获得最佳体验）。
+3. **自定义高度**: 对长列表使用 `menu$height` 防止 UI 溢出。
+4. **清晰标签**: 提供描述性的占位符和标签。
+5. **事件处理**: 使用 `onchange`、`onfocus` 和 `onblur` 实现完善的表单集成。
+6. **状态管理**: 绑定到响应式变量以确保正确的状态更新。
+
+## 相关组件
+
+- [TextEditor](../text_editor/README_CN.md) — 不带建议的简单文本输入。
+- [NumberEditor](../number_editor/README_CN.md) — 带校验的数字输入。