@ticatec/topside-elements 1.0.0

package/dist/form/memo_editor/README_CN.md

@@ -0,0 +1,283 @@
+# MemoEditor 多行文本编辑器
+
+带字数统计、调整大小选项和完整事件透传的多行文本区域组件。基于 `FormEditor` 构建。
+
+## 功能特性
+
+- **多行文本输入**: 支持配置行数和文本换行的文本域。
+- **字数统计**: 可选的字数指示器，配合最大长度校验。
+- **调整大小**: 可配置调整大小行为（`none`、`horizontal`、`vertical`、`both`）。
+- **多种变体**: 支持 `plain`、`outlined`、`filled` 样式。
+- **清除按钮**: 字段有内容时快速清除。
+- **事件透传**: 通过 `input$` 前缀和事件属性实现完整的事件处理。
+- **键盘支持**: 键盘事件透传，支持自定义处理。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+```
+
+## 基础用法
+
+```svelte
+<script>
+  import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+
+  let notes = "";
+</script>
+
+<MemoEditor
+  bind:value={notes}
+  placeholder="在这里输入笔记..."
+  variant="outlined"
+  rows={4}
+/>
+```
+
+## 属性（Props）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `string` | `""` | 当前文本内容（可双向绑定）。 |
+| `rows` | `number` | `3` | 可见文本行数（`autoHeight` 为 true 时忽略）。 |
+| `autoHeight` | `boolean` | `false` | 自动调整高度以适配内容。 |
+| `wrap` | `"hard" \| "soft"` | `"hard"` | 文本换行行为。 |
+| `resize` | `'none' \| 'horizontal' \| 'vertical' \| 'both'` | `'none'` | 文本域的调整大小行为。 |
+| `showIndicator` | `boolean` | `false` | 显示字数统计指示器。 |
+| `maxLength` | `number \| undefined` | `undefined` | 最大字符数（`showIndicator` 为 true 时生效）。 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉样式变体。 |
+| `compact` | `boolean` | `false` | 紧凑间距布局。 |
+| `disabled` | `boolean` | `false` | 禁用编辑器。 |
+| `readonly` | `boolean` | `false` | 设为只读。 |
+| `error` | `string` | `undefined` | 错误信息文本。 |
+| `tooltip` | `string` | `undefined` | 悬停提示文本。 |
+| `theme` | `string` | `undefined` | 主题名称，用于切换外观。 |
+| `style` | `string` | `""` | 内联 CSS 样式。 |
+| `class` | `string` | `""` | 外层容器的 CSS 类名。 |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | 失去焦点时触发。 |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | 获取焦点时触发。 |
+
+### 输入属性透传
+
+以 `input$` 为前缀的属性会被透传给底层 `<textarea>`。例如：
+- `input$placeholder` — 占位符文本
+- `input$aria-label` — ARIA 标签
+- `input$spellcheck` — 启用/禁用拼写检查
+- `input$autocomplete` — 自动完成行为
+
+以下属性由编辑器内部管理，不会透传：`readonly`、`disabled`、`required`、`rows`、`form`、`wrap`。
+
+### 事件透传
+
+以 `input$` 为前缀的事件属性（如 `input$oninput`、`input$onkeydown`）会被透传给文本域。
+
+## 方法
+
+| 方法 | 说明 |
+|------|------|
+| `focus()` | 编程方式让文本域获取焦点。 |
+
+## 示例
+
+### 基本笔记编辑器
+
+```svelte
+<script>
+  import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+
+  let notes = "";
+</script>
+
+<MemoEditor
+  bind:value={notes}
+  variant="outlined"
+  placeholder="输入笔记..."
+  rows={4}
+/>
+```
+
+### 带字数统计
+
+```svelte
+<script>
+  import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+
+  let notes = "";
+</script>
+
+<MemoEditor
+  bind:value={notes}
+  variant="filled"
+  rows={5}
+  maxLength={500}
+  showIndicator
+  placeholder="输入笔记（最多 500 字）"
+/>
+
+<p>当前字数：{notes.length} / 500</p>
+```
+
+### 可调整大小编辑器
+
+```svelte
+<script>
+  import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+
+  let content = "";
+</script>
+
+<MemoEditor
+  bind:value={content}
+  variant="outlined"
+  rows={6}
+  resize="both"
+  placeholder="拖拽两个方向调整大小"
+/>
+```
+
+### 仅横向调整
+
+```svelte
+<script>
+  import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+
+  let content = "";
+</script>
+
+<MemoEditor
+  bind:value={content}
+  variant="outlined"
+  rows={3}
+  resize="horizontal"
+  placeholder="拖拽右边缘加宽"
+/>
+```
+
+### 软换行模式
+
+```svelte
+<script>
+  import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+
+  let notes = "";
+</script>
+
+<MemoEditor
+  bind:value={notes}
+  variant="filled"
+  rows={4}
+  wrap="soft"
+  placeholder="文本在单词边界处换行"
+/>
+```
+
+### 带焦点跟踪
+
+```svelte
+<script>
+  import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+
+  let notes = "";
+  let isFocused = false;
+
+  function handleFocus() {
+    isFocused = true;
+  }
+
+  function handleBlur() {
+    isFocused = false;
+  }
+</script>
+
+<MemoEditor
+  bind:value={notes}
+  variant="outlined"
+  rows={4}
+  onfocus={handleFocus}
+  onblur={handleBlur}
+/>
+
+<p>{isFocused ? "编辑器处于激活状态" : "编辑器未激活"}</p>
+```
+
+### 紧凑表单
+
+```svelte
+<script>
+  import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+
+  let description = "";
+</script>
+
+<div class="compact-form">
+  <label>描述</label>
+  <MemoEditor
+    bind:value={description}
+    compact
+    variant="outlined"
+    rows={2}
+    placeholder="简短描述..."
+  />
+</div>
+
+<style>
+  .compact-form {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+  label {
+    font-weight: 500;
+    font-size: 0.875rem;
+  }
+</style>
+```
+
+### 错误与提示
+
+```svelte
+<script>
+  import MemoEditor from "@ticatec/topside-elements/MemoEditor";
+
+  let notes = "";
+  let errorMsg = "";
+
+  function handleChange(value) {
+    errorMsg = value && value.length > 1000
+      ? "笔记过长（最多 1000 字）"
+      : "";
+  }
+</script>
+
+<MemoEditor
+  bind:value={notes}
+  variant="outlined"
+  rows={4}
+  maxLength={1000}
+  showIndicator
+  error={errorMsg}
+  tooltip="输入笔记（最多 1000 字）"
+  onchange={handleChange}
+/>
+```
+
+## 最佳实践
+
+1. **固定高度用 `rows`**，动态调整用 `autoHeight`。
+2. **有字数限制时设置 `maxLength` 配合 `showIndicator`**。
+3. **谨慎选择 `resize`**：`"horizontal"` 最适合全宽编辑器；`"both"` 可能在受限容器中溢出。
+4. **数据输入用 `wrap="hard"`**，展示型文本用 `wrap="soft"`。
+5. **使用 `onblur` 进行校验**，而非仅依赖 `onchange`。
+6. **密集表单布局中优先使用 `compact`**。
+
+## 相关组件
+
+- [TextEditor](../text_editor/README_CN.md) — 单行文本输入。
+- [PromptsTextEditor](../prompts_text_editor/README_CN.md) — 带建议下拉的文本输入。

package/dist/form/memo_editor/index.d.ts

@@ -0,0 +1,2 @@
+import MemoEditor from "./MemoEditor.svelte";
+export default MemoEditor;

package/dist/form/memo_editor/index.js

@@ -0,0 +1,2 @@
+import MemoEditor from "./MemoEditor.svelte";
+export default MemoEditor;

package/dist/form/number_editor/NumberEditor.svelte

@@ -0,0 +1,113 @@
+<script lang="ts">
+    import type {Snippet} from 'svelte';
+    import CommonEditor from "../common_editor/CommonEditor.svelte";
+    import NumberInput from "../common_editor/NumberInput.svelte";
+    import utils from "../../overlay/common/utils";
+    import prefixFilter from "../../utils/prefixFilter";
+    import type CommonFieldProps from "../common_editor/CommonFieldProps";
+    import type {KeyboardEvents} from "../events";
+
+    const excludeAttrs = ['type', 'readonly', 'disabled', 'required', 'wrap', 'value', 'max', 'min', 'step'];
+
+    interface Props extends CommonFieldProps, KeyboardEvents {
+
+        value?: any;
+        precision?: number;
+        suffix?: string;
+        prefix?: string;
+        allowNegative?: boolean;
+        max?: number;
+        min?: number;
+        leadingIcon?: Snippet;
+        trailingIcon?: Snippet;
+
+        [key: `input\$${string}`]: any;
+    }
+
+    let {
+        disabled = false,
+        readonly = false,
+        style,
+        tooltip,
+        error,
+        variant,
+        theme,
+        compact = false,
+        value = $bindable(),
+        precision,
+        suffix,
+        prefix,
+        allowNegative = false,
+        max,
+        min,
+        onchange,
+        onfocus,
+        onblur,
+        onkeydown,
+        onkeyup,
+        onkeypress,
+        leadingIcon,
+        trailingIcon,
+        ...restProps
+    }: Props = $props();
+
+    let numberInput = $state<NumberInput>();
+
+    export function focus() {
+        numberInput?.focus();
+    }
+
+    const formatWithThousands = (num: number | undefined, prec: number | undefined): string => {
+        if (num == null) return '';
+        const base = utils.formatNumber(num, prec);
+        if (!base) return base;
+        const parts = base.split('.');
+        parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+        return parts.join('.');
+    };
+
+    let displayValue = $derived(formatWithThousands(value, precision));
+    let input$ = $derived(prefixFilter(restProps, 'input$', excludeAttrs));
+
+    // 清空按钮 / 键盘清空都走这里：统一通知 onchange（与 Lookup / ColorPicker / OptionsMultiSelect 一致）
+    const clear = () => {
+        value = undefined;
+        onchange?.(undefined);
+    }
+
+</script>
+
+<CommonEditor
+    textValue={displayValue}
+    {style}
+    {suffix}
+    {prefix}
+    {readonly}
+    {disabled}
+    {variant}
+    {theme}
+    {compact}
+    {leadingIcon}
+    {trailingIcon}
+    {tooltip}
+    {error}
+    {clear}
+    input$class="number-editor">
+    {#if !readonly && !disabled}
+        <NumberInput
+            bind:this={numberInput}
+            bind:value
+            {precision}
+            {allowNegative}
+            {max}
+            {min}
+            {onchange}
+            {onfocus}
+            {onblur}
+            {onkeydown}
+            {onkeyup}
+            {onkeypress}
+            {...input$}
+        />
+    {/if}
+</CommonEditor>

package/dist/form/number_editor/NumberEditor.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { Snippet } from 'svelte';
+import type CommonFieldProps from "../common_editor/CommonFieldProps";
+import type { KeyboardEvents } from "../events";
+interface Props extends CommonFieldProps, KeyboardEvents {
+    value?: any;
+    precision?: number;
+    suffix?: string;
+    prefix?: string;
+    allowNegative?: boolean;
+    max?: number;
+    min?: number;
+    leadingIcon?: Snippet;
+    trailingIcon?: Snippet;
+    [key: `input\$${string}`]: any;
+}
+declare const NumberEditor: import("svelte").Component<Props, {
+    focus: () => void;
+}, "value">;
+type NumberEditor = ReturnType<typeof NumberEditor>;
+export default NumberEditor;