@ticatec/topside-elements 1.0.0

package/dist/form/text_editor/README.md

@@ -0,0 +1,356 @@
+# TextEditor
+
+A versatile single-line text input component with case mode support, prefix/suffix text, icon slots, and comprehensive event forwarding. Built on top of `CommonEditor`.
+
+## Features
+
+- **Case Mode**: Automatic uppercase/lowercase conversion via `caseMode`.
+- **Prefix / Suffix**: Display text before or after the input (e.g. `$`, `@`).
+- **Icon Slots**: `leadingIcon` / `trailingIcon` snippet props.
+- **Clear Functionality**: Built-in clear button.
+- **Variants**: Support for `plain`, `outlined`, and `filled` styles.
+- **Event Forwarding**: All native input events are forwarded automatically.
+- **Keyboard Events**: Passthrough for `onkeydown` / `onkeyup` / `onkeypress`.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import TextEditor from "@ticatec/topside-elements/TextEditor";
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let inputValue = "";
+</script>
+
+<TextEditor
+  bind:value={inputValue}
+  placeholder="Enter text..."
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | `""` | Current input value (bindable). |
+| `caseMode` | `"upper" \| "lower"` | `undefined` | Automatic case conversion. `"upper"` forces uppercase, `"lower"` forces lowercase. |
+| `prefix` | `string` | `""` | Text rendered before the value. |
+| `suffix` | `string` | `""` | Text rendered after the value. |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | Visual style variant. |
+| `compact` | `boolean` | `false` | Compact spacing layout. |
+| `disabled` | `boolean` | `false` | Disables the input. |
+| `readonly` | `boolean` | `false` | Makes the input read-only. |
+| `placeholder` | `string` | `""` | Placeholder text when value is empty. |
+| `error` | `string` | `undefined` | Error message text (clears on first change). |
+| `tooltip` | `string` | `undefined` | Hover tooltip text. |
+| `theme` | `string` | `undefined` | Theme name for appearance switching. |
+| `style` | `string` | `""` | Inline CSS styles. |
+| `leadingIcon` | `Snippet` | `undefined` | Snippet rendered before the value/prefix. |
+| `trailingIcon` | `Snippet` | `undefined` | Snippet rendered after the value/suffix. |
+| `onchange` | `(value: string) => void` | `undefined` | Fired when the value changes. |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | Input gains focus. |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | Input loses focus. |
+| `onkeydown` | `(e: KeyboardEvent) => void` | `undefined` | Key down handler. |
+| `onkeyup` | `(e: KeyboardEvent) => void` | `undefined` | Key up handler. |
+| `onkeypress` | `(e: KeyboardEvent) => void` | `undefined` | Key press handler. |
+
+### Event passthrough
+
+Any additional props prefixed with `input$` are forwarded to the underlying `<input>` element. For example `input$aria-label` becomes `aria-label` on the native input.
+
+The following attributes are excluded (managed internally): `type`, `readonly`, `disabled`, `required`, `wrap`, `value`.
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `focus()` | Programmatically focuses the input element. |
+
+## Examples
+
+### Basic Text Input
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let username = "";
+</script>
+
+<TextEditor
+  bind:value={username}
+  placeholder="Enter username"
+  variant="outlined"
+/>
+```
+
+### Uppercase Mode (e.g. Order Numbers)
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let orderNo = "";
+</script>
+
+<TextEditor
+  bind:value={orderNo}
+  caseMode="upper"
+  placeholder="Enter order number"
+  variant="outlined"
+  input$maxlength="20"
+/>
+```
+
+### Lowercase Mode (e.g. Email)
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let email = "";
+</script>
+
+<TextEditor
+  bind:value={email}
+  caseMode="lower"
+  placeholder="Enter email address"
+  variant="outlined"
+  input$autocomplete="email"
+/>
+```
+
+### With Prefix and Suffix
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let price = "";
+  let website = "";
+  let username = "";
+</script>
+
+<TextEditor
+  bind:value={price}
+  prefix="$"
+  placeholder="0.00"
+  variant="outlined"
+/>
+
+<TextEditor
+  bind:value={website}
+  prefix="https://"
+  placeholder="example.com"
+  variant="outlined"
+/>
+
+<TextEditor
+  bind:value={username}
+  suffix="@company.com"
+  placeholder="username"
+  variant="outlined"
+/>
+```
+
+### With Leading Icon
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let searchTerm = "";
+</script>
+
+<TextEditor
+  bind:value={searchTerm}
+  placeholder="Search..."
+  variant="outlined"
+>
+  {#snippet leadingIcon()}
+    <i class="icon_google_search" aria-hidden="true"></i>
+  {/snippet}
+</TextEditor>
+```
+
+### With Trailing Icon and Error Handling
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let password = "";
+  let errorMsg = "";
+
+  function handleChange(value) {
+    errorMsg = value && value.length < 8
+      ? "Password must be at least 8 characters"
+      : "";
+  }
+</script>
+
+<TextEditor
+  bind:value={password}
+  placeholder="Enter password"
+  variant="outlined"
+  error={errorMsg}
+  onchange={handleChange}
+>
+  {#snippet trailingIcon()}
+    <i class="icon_google_lock" aria-hidden="true"></i>
+  {/snippet}
+</TextEditor>
+```
+
+### Disabled and Readonly States
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let normalValue = "";
+  let readonlyValue = "This is readonly";
+  let disabledValue = "";
+</script>
+
+<TextEditor bind:value={normalValue} placeholder="Normal input" variant="outlined" />
+<TextEditor bind:value={readonlyValue} readonly variant="outlined" />
+<TextEditor bind:value={disabledValue} disabled placeholder="Disabled input" variant="outlined" />
+```
+
+### Compact Mode
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let compactValue = "";
+</script>
+
+<div class="toolbar">
+  <TextEditor
+    bind:value={compactValue}
+    compact
+    placeholder="Compact input"
+    variant="outlined"
+  />
+</div>
+
+<style>
+  .toolbar {
+    display: flex;
+    align-items: center;
+    padding: 8px;
+    background: #f8f9fa;
+  }
+</style>
+```
+
+### Form Integration
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let formData = {
+    firstName: "",
+    lastName: "",
+    email: "",
+    company: ""
+  };
+
+  function handleSubmit() {
+    console.log("Form submitted:", formData);
+  }
+</script>
+
+<form onsubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
+  <div class="form-row">
+    <div class="form-field">
+      <label>First Name</label>
+      <TextEditor bind:value={formData.firstName} placeholder="John" variant="outlined" />
+    </div>
+    <div class="form-field">
+      <label>Last Name</label>
+      <TextEditor bind:value={formData.lastName} placeholder="Doe" variant="outlined" />
+    </div>
+  </div>
+
+  <div class="form-field">
+    <label>Email</label>
+    <TextEditor bind:value={formData.email} placeholder="john@example.com" variant="outlined" caseMode="lower" />
+  </div>
+
+  <div class="form-field">
+    <label>Company</label>
+    <TextEditor bind:value={formData.company} placeholder="Acme Corp" variant="outlined" />
+  </div>
+
+  <button type="submit">Submit</button>
+</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;
+  }
+  button {
+    padding: 8px 16px;
+    cursor: pointer;
+  }
+</style>
+```
+
+### Programmatic Focus
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let editor;
+  let inputValue = "";
+</script>
+
+<button onclick={() => editor?.focus()}>Focus Input</button>
+
+<TextEditor
+  bind:this={editor}
+  bind:value={inputValue}
+  placeholder="Click button to focus me"
+/>
+```
+
+## Best Practices
+
+1. **Use `caseMode` for data normalization**: `"upper"` for codes/order numbers, `"lower"` for emails.
+2. **Clear error on change**: The error message auto-clears on first user input.
+3. **Provide `prefix`/`suffix`** for units and domains to improve readability.
+4. **Add `input$aria-label`** when the editor is not paired with a visible label.
+5. **Use `compact`** in dense form layouts or toolbars.
+
+## Related Components
+
+- [NumberEditor](../number_editor/README.md) — Numeric input with validation.
+- [MemoEditor](../memo_editor/README.md) — Multi-line text input.
+- [PromptsTextEditor](../prompts_text_editor/README.md) — Text input with suggestion dropdown.

package/dist/form/text_editor/README_CN.md

@@ -0,0 +1,356 @@
+# TextEditor 单行文本编辑器
+
+多功能单行文本输入组件，支持大小写转换、前后缀文本、图标插槽和完整的事件透传。基于 `CommonEditor` 构建。
+
+## 功能特性
+
+- **大小写模式**: 通过 `caseMode` 自动转换大小写。
+- **前缀 / 后缀**: 在输入前后显示文本（如 `$`、`@`）。
+- **图标插槽**: `leadingIcon` / `trailingIcon` 代码片段属性。
+- **清除功能**: 内置清除按钮。
+- **多种变体**: 支持 `plain`、`outlined`、`filled` 样式。
+- **事件透传**: 所有原生输入事件自动透传。
+- **键盘事件**: 支持 `onkeydown` / `onkeyup` / `onkeypress` 透传。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import TextEditor from "@ticatec/topside-elements/TextEditor";
+```
+
+## 基础用法
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let inputValue = "";
+</script>
+
+<TextEditor
+  bind:value={inputValue}
+  placeholder="请输入文本..."
+/>
+```
+
+## 属性（Props）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `string` | `""` | 当前输入值（可双向绑定）。 |
+| `caseMode` | `"upper" \| "lower"` | `undefined` | 自动大小写转换。`"upper"` 强制大写，`"lower"` 强制小写。 |
+| `prefix` | `string` | `""` | 显示在值前面的文本。 |
+| `suffix` | `string` | `""` | 显示在值后面的文本。 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉样式变体。 |
+| `compact` | `boolean` | `false` | 紧凑间距布局。 |
+| `disabled` | `boolean` | `false` | 禁用输入框。 |
+| `readonly` | `boolean` | `false` | 设为只读。 |
+| `placeholder` | `string` | `""` | 值为空时的占位符文本。 |
+| `error` | `string` | `undefined` | 错误信息文本（首次输入时自动清除）。 |
+| `tooltip` | `string` | `undefined` | 悬停提示文本。 |
+| `theme` | `string` | `undefined` | 主题名称，用于切换外观。 |
+| `style` | `string` | `""` | 内联 CSS 样式。 |
+| `leadingIcon` | `Snippet` | `undefined` | 渲染在前缀之前的代码片段。 |
+| `trailingIcon` | `Snippet` | `undefined` | 渲染在后缀之后的代码片段。 |
+| `onchange` | `(value: string) => void` | `undefined` | 值变更时触发。 |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | 输入框获取焦点时触发。 |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | 输入框失去焦点时触发。 |
+| `onkeydown` | `(e: KeyboardEvent) => void` | `undefined` | 按键按下时触发。 |
+| `onkeyup` | `(e: KeyboardEvent) => void` | `undefined` | 按键抬起时触发。 |
+| `onkeypress` | `(e: KeyboardEvent) => void` | `undefined` | 按键按下时触发。 |
+
+### 事件透传
+
+任何以 `input$` 为前缀的额外属性都会被透传给底层 `<input>` 元素。例如 `input$aria-label` 会被转换成原生 input 的 `aria-label`。
+
+以下属性由于由编辑器内部管理，即便通过 `input$` 传入也会被剔除：`type`、`readonly`、`disabled`、`required`、`wrap`、`value`。
+
+## 方法
+
+| 方法 | 说明 |
+|------|------|
+| `focus()` | 编程方式让 input 获取焦点。 |
+
+## 示例
+
+### 基本文本输入
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let username = "";
+</script>
+
+<TextEditor
+  bind:value={username}
+  placeholder="请输入用户名"
+  variant="outlined"
+/>
+```
+
+### 大写模式（如订单号）
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let orderNo = "";
+</script>
+
+<TextEditor
+  bind:value={orderNo}
+  caseMode="upper"
+  placeholder="输入订单号"
+  variant="outlined"
+  input$maxlength="20"
+/>
+```
+
+### 小写模式（如邮箱）
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let email = "";
+</script>
+
+<TextEditor
+  bind:value={email}
+  caseMode="lower"
+  placeholder="输入邮箱地址"
+  variant="outlined"
+  input$autocomplete="email"
+/>
+```
+
+### 带前缀和后缀
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let price = "";
+  let website = "";
+  let username = "";
+</script>
+
+<TextEditor
+  bind:value={price}
+  prefix="$"
+  placeholder="0.00"
+  variant="outlined"
+/>
+
+<TextEditor
+  bind:value={website}
+  prefix="https://"
+  placeholder="example.com"
+  variant="outlined"
+/>
+
+<TextEditor
+  bind:value={username}
+  suffix="@company.com"
+  placeholder="用户名"
+  variant="outlined"
+/>
+```
+
+### 带前导图标
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let searchTerm = "";
+</script>
+
+<TextEditor
+  bind:value={searchTerm}
+  placeholder="搜索..."
+  variant="outlined"
+>
+  {#snippet leadingIcon()}
+    <i class="icon_google_search" aria-hidden="true"></i>
+  {/snippet}
+</TextEditor>
+```
+
+### 带后置图标和错误处理
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let password = "";
+  let errorMsg = "";
+
+  function handleChange(value) {
+    errorMsg = value && value.length < 8
+      ? "密码至少需要 8 个字符"
+      : "";
+  }
+</script>
+
+<TextEditor
+  bind:value={password}
+  placeholder="输入密码"
+  variant="outlined"
+  error={errorMsg}
+  onchange={handleChange}
+>
+  {#snippet trailingIcon()}
+    <i class="icon_google_lock" aria-hidden="true"></i>
+  {/snippet}
+</TextEditor>
+```
+
+### 禁用与只读状态
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let normalValue = "";
+  let readonlyValue = "这是只读的";
+  let disabledValue = "";
+</script>
+
+<TextEditor bind:value={normalValue} placeholder="正常输入" variant="outlined" />
+<TextEditor bind:value={readonlyValue} readonly variant="outlined" />
+<TextEditor bind:value={disabledValue} disabled placeholder="已禁用输入" variant="outlined" />
+```
+
+### 紧凑模式
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let compactValue = "";
+</script>
+
+<div class="toolbar">
+  <TextEditor
+    bind:value={compactValue}
+    compact
+    placeholder="紧凑输入"
+    variant="outlined"
+  />
+</div>
+
+<style>
+  .toolbar {
+    display: flex;
+    align-items: center;
+    padding: 8px;
+    background: #f8f9fa;
+  }
+</style>
+```
+
+### 表单集成
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let formData = {
+    firstName: "",
+    lastName: "",
+    email: "",
+    company: ""
+  };
+
+  function handleSubmit() {
+    console.log("表单已提交:", formData);
+  }
+</script>
+
+<form onsubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
+  <div class="form-row">
+    <div class="form-field">
+      <label>名</label>
+      <TextEditor bind:value={formData.firstName} placeholder="约翰" variant="outlined" />
+    </div>
+    <div class="form-field">
+      <label>姓</label>
+      <TextEditor bind:value={formData.lastName} placeholder="多伊" variant="outlined" />
+    </div>
+  </div>
+
+  <div class="form-field">
+    <label>邮箱</label>
+    <TextEditor bind:value={formData.email} placeholder="john@example.com" variant="outlined" caseMode="lower" />
+  </div>
+
+  <div class="form-field">
+    <label>公司</label>
+    <TextEditor bind:value={formData.company} placeholder="ACME 公司" variant="outlined" />
+  </div>
+
+  <button type="submit">提交</button>
+</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;
+  }
+  button {
+    padding: 8px 16px;
+    cursor: pointer;
+  }
+</style>
+```
+
+### 编程聚焦
+
+```svelte
+<script>
+  import TextEditor from "@ticatec/topside-elements/TextEditor";
+
+  let editor;
+  let inputValue = "";
+</script>
+
+<button onclick={() => editor?.focus()}>聚焦输入框</button>
+
+<TextEditor
+  bind:this={editor}
+  bind:value={inputValue}
+  placeholder="点击按钮聚焦我"
+/>
+```
+
+## 最佳实践
+
+1. **使用 `caseMode` 进行数据标准化**: `"upper"` 用于代码/订单号，`"lower"` 用于邮箱。
+2. **错误信息自动清除**: 首次用户输入时自动清除错误信息。
+3. **善用 `prefix`/`suffix`** 标注单位和域名，提升可读性。
+4. **无可见标签时添加 `input$aria-label`**，保证可访问性。
+5. **密集表单布局中优先使用 `compact`**。
+
+## 相关组件
+
+- [NumberEditor](../number_editor/README_CN.md) — 带校验的数字输入。
+- [MemoEditor](../memo_editor/README_CN.md) — 多行文本输入。
+- [PromptsTextEditor](../prompts_text_editor/README_CN.md) — 带建议下拉的文本输入。