@ticatec/topside-elements 1.0.0

package/dist/form/search_box/README.md

@@ -0,0 +1,301 @@
+# SearchBox
+
+A simple text input with a search icon leading icon. Wraps a plain `<input>` with the shared editor chrome (`CommonEditor`), giving it the same visual consistency as other form editors in the library. Useful for search bars, filter inputs, or any scenario where you need a text field with a consistent look.
+
+## Features
+
+- **Simple text input** — no dropdown, no options, just a plain input.
+- **Search icon** — a leading icon (🔍) is rendered by default.
+- **Debounced input** — `oninput` and `onchange` events are debounced to reduce unnecessary processing.
+- **Keyboard events** — supports `onenter` and `onescape` for action bindings.
+- **Disabled / readonly** modes.
+- **Compact mode** for dense UIs.
+- **Shared form-editor props** — `variant`, `style`, `error`, `tooltip`, `theme`, `placeholder`.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import SearchBox from "@ticatec/topside-elements/SearchBox";
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let query = $state("");
+
+  function handleSearch(newQuery: string) {
+    console.log("Searching for:", newQuery);
+    // ... perform search
+  }
+
+  function handleKeyDown(event: KeyboardEvent) {
+    if (event.key === 'Enter') {
+      console.log("Enter pressed, query:", query);
+    }
+  }
+</script>
+
+<SearchBox
+  bind:value={query}
+  placeholder="Search..."
+  oninput={handleSearch}
+  onenter={handleKeyDown}
+/>
+```
+
+## Props
+
+`SearchBox` extends `CommonFieldProps`, so it inherits `variant`, `compact`, `disabled`, `readonly`, `style`, `error`, `tooltip`, `theme`, `placeholder`.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` (bindable) | `""` | The current input value. `bind:value={...}` for two-way binding. |
+| `placeholder` | `string` | — | Shown when the input is empty. |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | Visual style variant. |
+| `compact` | `boolean` | `false` | Dense layout for table cells and inline forms. |
+| `disabled` | `boolean` | `false` | Fully disabled — input is non-interactive. |
+| `readonly` | `boolean` | `false` | Read-only — input is non-interactive but visible. |
+| `style` | `string` | — | Inline CSS on the editor root. |
+| `error` | `string` | — | Validation error text — triggers the editor's error state. |
+| `tooltip` | `string` | — | Hover tooltip on the editor. |
+| `theme` | `string` | — | Rendered as `data-theme` on the editor for scoped styling. |
+| `oninput` | `(event: InputEvent) => void` | — | Fires on every keystroke (debounced). Receives the input event. |
+| `onchange` | `(value: string) => void` | — | Fires when the value changes (debounced). Receives the new string value. |
+| `onfocus` | `(event: FocusEvent) => void` | — | Input focus. |
+| `onblur` | `(event: FocusEvent) => void` | — | Input blur. |
+| `onenter` | `(event: KeyboardEvent) => void` | — | Fires when the user presses Enter. |
+| `onescape` | `(event: KeyboardEvent) => void` | — | Fires when the user presses Escape. |
+| `onkeydown` | `(event: KeyboardEvent) => void` | — | Fires on any key down. |
+| `onkeyup` | `(event: KeyboardEvent) => void` | — | Fires on any key up. |
+| `onkeypress` | `(event: KeyboardEvent) => void` | — | Fires on any key press. |
+
+## Events
+
+| Event | Signature | Description |
+|-------|-----------|-------------|
+| `oninput` | `(event: InputEvent) => void` | Fires on every keystroke (debounced). Receives the input event. |
+| `onchange` | `(value: string) => void` | Fires when the value changes (debounced). Receives the new string value. |
+| `onenter` | `(event: KeyboardEvent) => void` | Fires when the user presses Enter. |
+| `onescape` | `(event: KeyboardEvent) => void` | Fires when the user presses Escape. |
+| `onfocus` | `(event: FocusEvent) => void` | Input focus. |
+| `onblur` | `(event: FocusEvent) => void` | Input blur. |
+| `onkeydown` | `(event: KeyboardEvent) => void` | Fires on any key down. |
+| `onkeyup` | `(event: KeyboardEvent) => void` | Fires on any key up. |
+| `onkeypress` | `(event: KeyboardEvent) => void` | Fires on any key press. |
+
+## Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `focus()` | `() => void` | Moves focus to the input. |
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let inputRef;
+
+  function focusInput() {
+    inputRef.focus();
+  }
+</script>
+
+<SearchBox bind:this={inputRef} bind:value placeholder="Search..." />
+<button onclick={focusInput}>Focus</button>
+```
+
+## Examples
+
+### Search bar with debounce
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let query = $state("");
+  let results = $state<string[]>([]);
+
+  // Simulated search
+  const performSearch = (searchTerm: string) => {
+    if (!searchTerm.trim()) {
+      results = [];
+      return;
+    }
+
+    const allItems = ["Apple", "Banana", "Cherry", "Date", "Elderberry", "Fig", "Grape"];
+    results = allItems.filter(item =>
+      item.toLowerCase().includes(searchTerm.toLowerCase())
+    );
+  };
+
+  function handleInput(event: InputEvent) {
+    const target = event.target as HTMLInputElement;
+    query = target.value;
+    performSearch(query);
+  }
+</script>
+
+<div class="search-container">
+  <SearchBox
+    bind:value={query}
+    placeholder="Search fruits..."
+    oninput={handleInput}
+  />
+  <ul class="results">
+    {#each results as item}
+      <li>{item}</li>
+    {/each}
+  </ul>
+</div>
+
+<style>
+  .search-container {
+    max-width: 400px;
+    margin: 20px;
+  }
+  .results {
+    list-style: none;
+    padding: 0;
+  }
+  .results li {
+    padding: 8px;
+    border-bottom: 1px solid #e5e7eb;
+  }
+  .results li:hover {
+    background: #f9fafb;
+  }
+</style>
+```
+
+### Filter input with keyboard actions
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let filter = $state("");
+
+  function handleEnter() {
+    console.log("Apply filter:", filter);
+  }
+
+  function handleEscape() {
+    filter = "";
+    console.log("Filter cleared");
+  }
+</script>
+
+<SearchBox
+  bind:value={filter}
+  placeholder="Filter items..."
+  onenter={handleEnter}
+  onescape={handleEscape}
+/>
+```
+
+### Disabled and readonly states
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let disabledValue = $state("");
+  let readonlyValue = $state("ReadOnly text");
+  let normalValue = $state("");
+</script>
+
+<div style="display: flex; flex-direction: column; gap: 16px;">
+  <SearchBox
+    bind:value={disabledValue}
+    placeholder="Disabled"
+    disabled
+  />
+  <SearchBox
+    bind:value={readonlyValue}
+    placeholder="Readonly"
+    readonly
+  />
+  <SearchBox
+    bind:value={normalValue}
+    placeholder="Normal"
+  />
+</div>
+```
+
+### Compact mode
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let searchQuery = $state("");
+</script>
+
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Search</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Row 1</td>
+      <td>
+        <SearchBox
+          bind:value={searchQuery}
+          placeholder="Search"
+          compact
+        />
+      </td>
+    </tr>
+    <tr>
+      <td>Row 2</td>
+      <td>
+        <SearchBox
+          bind:value={searchQuery}
+          placeholder="Search"
+          compact
+        />
+      </td>
+    </tr>
+  </tbody>
+</table>
+```
+
+## Behavior Notes
+
+### Debouncing
+
+Both `oninput` and `onchange` are debounced to reduce unnecessary processing. The debounce delay is approximately 300ms.
+
+### Keyboard events
+
+- `onenter` fires when the user presses Enter.
+- `onescape` fires when the user presses Escape.
+- `onkeydown`, `onkeyup`, and `onkeypress` fire for any keyboard interaction.
+
+### Read-only / disabled rendering
+
+Both modes render a plain `<input readonly>` with the search icon. The input is non-interactive in both states.
+
+## Accessibility
+
+- The input has a default `id` of `search-box-{timestamp}` for label association.
+- For full ARIA, wrap with `<label>` or use `aria-label`.
+- The search icon is decorative and marked with `aria-hidden="true"`.
+
+## Related Components
+
+- [TextEditor](../text_editor/README.md) — multi-line text area.
+- [NumberEditor](../number_editor/README.md) — numeric input.
+- [DatePicker](../date_picker/README.md) — date selection.

package/dist/form/search_box/README_CN.md

@@ -0,0 +1,301 @@
+# SearchBox
+
+带搜索图标的简单文本输入框。包裹在普通 `<input>` 外面，使用共享的编辑器外壳（`CommonEditor`），与库中其他表单编辑器保持一致的视觉风格。适用于搜索栏、过滤输入框，或任何需要统一外观的文本字段场景。
+
+## 特性
+
+- **简单文本输入** —— 没有下拉，没有选项，只是一个普通的输入框。
+- **搜索图标** —— 默认渲染一个前导图标（🔍）。
+- **防抖输入** —— `oninput` 和 `onchange` 事件会进行防抖处理，减少不必要的处理。
+- **键盘事件** —— 支持 `onenter` 和 `onescape` 用于动作绑定。
+- **禁用 / 只读** 模式。
+- **紧凑模式** —— 适用于密集 UI。
+- **共享的 form-editor 属性** —— `variant`、`style`、`error`、`tooltip`、`theme`、`placeholder`。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import SearchBox from "@ticatec/topside-elements/SearchBox";
+```
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let query = $state("");
+
+  function handleSearch(newQuery: string) {
+    console.log("搜索:", newQuery);
+    // ... 执行搜索
+  }
+
+  function handleKeyDown(event: KeyboardEvent) {
+    if (event.key === 'Enter') {
+      console.log("按下了回车，查询:", query);
+    }
+  }
+</script>
+
+<SearchBox
+  bind:value={query}
+  placeholder="搜索..."
+  oninput={handleSearch}
+  onenter={handleKeyDown}
+/>
+```
+
+## 属性（Props）
+
+`SearchBox` 继承自 `CommonFieldProps`，因此自动获得 `variant`、`compact`、`disabled`、`readonly`、`style`、`error`、`tooltip`、`theme`、`placeholder`。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `string`（可绑定） | `""` | 当前输入值。`bind:value={...}` 用于双向绑定。 |
+| `placeholder` | `string` | — | 输入框为空时显示的文字。 |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 视觉风格。 |
+| `compact` | `boolean` | `false` | 紧凑布局。 |
+| `disabled` | `boolean` | `false` | 完全禁用 —— 输入框不可交互。 |
+| `readonly` | `boolean` | `false` | 只读 —— 输入框不可交互但可见。 |
+| `style` | `string` | — | 编辑器根节点的内联 CSS。 |
+| `error` | `string` | — | 校验错误文本，触发编辑器的 error 状态。 |
+| `tooltip` | `string` | — | 编辑器的 hover tooltip。 |
+| `theme` | `string` | — | 渲染为编辑器根的 `data-theme`，用于作用域样式覆盖。 |
+| `oninput` | `(event: InputEvent) => void` | — | 每次按键时触发（防抖）。接收输入事件。 |
+| `onchange` | `(value: string) => void` | — | 值变化时触发（防抖）。接收新的字符串值。 |
+| `onfocus` | `(event: FocusEvent) => void` | — | 输入框获焦。 |
+| `onblur` | `(event: FocusEvent) => void` | — | 输入框失焦。 |
+| `onenter` | `(event: KeyboardEvent) => void` | — | 用户按 Enter 时触发。 |
+| `onescape` | `(event: KeyboardEvent) => void` | — | 用户按 Escape 时触发。 |
+| `onkeydown` | `(event: KeyboardEvent) => void` | — | 任何按键按下时触发。 |
+| `onkeyup` | `(event: KeyboardEvent) => void` | — | 任何按键抬起时触发。 |
+| `onkeypress` | `(event: KeyboardEvent) => void` | — | 任何按键按下时触发。 |
+
+## 事件
+
+| 事件 | 签名 | 说明 |
+|------|------|------|
+| `oninput` | `(event: InputEvent) => void` | 每次按键时触发（防抖）。接收输入事件。 |
+| `onchange` | `(value: string) => void` | 值变化时触发（防抖）。接收新的字符串值。 |
+| `onenter` | `(event: KeyboardEvent) => void` | 用户按 Enter 时触发。 |
+| `onescape` | `(event: KeyboardEvent) => void` | 用户按 Escape 时触发。 |
+| `onfocus` | `(event: FocusEvent) => void` | 输入框获焦。 |
+| `onblur` | `(event: FocusEvent) => void` | 输入框失焦。 |
+| `onkeydown` | `(event: KeyboardEvent) => void` | 任何按键按下时触发。 |
+| `onkeyup` | `(event: KeyboardEvent) => void` | 任何按键抬起时触发。 |
+| `onkeypress` | `(event: KeyboardEvent) => void` | 任何按键按下时触发。 |
+
+## 方法
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `focus()` | `() => void` | 让输入框获取焦点。 |
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let inputRef;
+
+  function focusInput() {
+    inputRef.focus();
+  }
+</script>
+
+<SearchBox bind:this={inputRef} bind:value placeholder="搜索..." />
+<button onclick={focusInput}>聚焦</button>
+```
+
+## 示例
+
+### 带防抖的搜索栏
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let query = $state("");
+  let results = $state<string[]>([]);
+
+  // 模拟搜索
+  const performSearch = (searchTerm: string) => {
+    if (!searchTerm.trim()) {
+      results = [];
+      return;
+    }
+
+    const allItems = ["Apple", "Banana", "Cherry", "Date", "Elderberry", "Fig", "Grape"];
+    results = allItems.filter(item =>
+      item.toLowerCase().includes(searchTerm.toLowerCase())
+    );
+  };
+
+  function handleInput(event: InputEvent) {
+    const target = event.target as HTMLInputElement;
+    query = target.value;
+    performSearch(query);
+  }
+</script>
+
+<div class="search-container">
+  <SearchBox
+    bind:value={query}
+    placeholder="搜索水果..."
+    oninput={handleInput}
+  />
+  <ul class="results">
+    {#each results as item}
+      <li>{item}</li>
+    {/each}
+  </ul>
+</div>
+
+<style>
+  .search-container {
+    max-width: 400px;
+    margin: 20px;
+  }
+  .results {
+    list-style: none;
+    padding: 0;
+  }
+  .results li {
+    padding: 8px;
+    border-bottom: 1px solid #e5e7eb;
+  }
+  .results li:hover {
+    background: #f9fafb;
+  }
+</style>
+```
+
+### 带键盘动作的过滤输入
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let filter = $state("");
+
+  function handleEnter() {
+    console.log("应用过滤:", filter);
+  }
+
+  function handleEscape() {
+    filter = "";
+    console.log("过滤已清空");
+  }
+</script>
+
+<SearchBox
+  bind:value={filter}
+  placeholder="过滤项目..."
+  onenter={handleEnter}
+  onescape={handleEscape}
+/>
+```
+
+### 禁用和只读状态
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let disabledValue = $state("");
+  let readonlyValue = $state("只读文本");
+  let normalValue = $state("");
+</script>
+
+<div style="display: flex; flex-direction: column; gap: 16px;">
+  <SearchBox
+    bind:value={disabledValue}
+    placeholder="禁用"
+    disabled
+  />
+  <SearchBox
+    bind:value={readonlyValue}
+    placeholder="只读"
+    readonly
+  />
+  <SearchBox
+    bind:value={normalValue}
+    placeholder="正常"
+  />
+</div>
+```
+
+### 紧凑模式
+
+```svelte
+<script lang="ts">
+  import SearchBox from "@ticatec/topside-elements/SearchBox";
+
+  let searchQuery = $state("");
+</script>
+
+<table>
+  <thead>
+    <tr>
+      <th>名称</th>
+      <th>搜索</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>行 1</td>
+      <td>
+        <SearchBox
+          bind:value={searchQuery}
+          placeholder="搜索"
+          compact
+        />
+      </td>
+    </tr>
+    <tr>
+      <td>行 2</td>
+      <td>
+        <SearchBox
+          bind:value={searchQuery}
+          placeholder="搜索"
+          compact
+        />
+      </td>
+    </tr>
+  </tbody>
+</table>
+```
+
+## 行为说明
+
+### 防抖
+
+`oninput` 和 `onchange` 都会进行防抖处理，以减少不必要的处理。防抖延迟约为 300ms。
+
+### 键盘事件
+
+- `onenter` 在用户按 Enter 时触发。
+- `onescape` 在用户按 Escape 时触发。
+- `onkeydown`、`onkeyup` 和 `onkeypress` 在任何键盘交互时触发。
+
+### 只读 / 禁用渲染
+
+两种模式都渲染普通 `<input readonly>`，带有搜索图标。输入框在两种状态下都不可交互。
+
+## 无障碍
+
+- 输入框默认有 `id` 为 `search-box-{timestamp}`，用于标签关联。
+- 完整的 ARIA 需要外层 `<label>` 或使用 `aria-label`。
+- 搜索图标是装饰性的，标记为 `aria-hidden="true"`。
+
+## 相关组件
+
+- [TextEditor](../text_editor/README_CN.md) —— 多行文本区域。
+- [NumberEditor](../number_editor/README_CN.md) —— 数值输入。
+- [DatePicker](../date_picker/README_CN.md) —— 日期选择。

package/dist/form/search_box/SearchBox.svelte

@@ -0,0 +1,91 @@
+<script lang="ts">
+    import CommonEditor from "../common_editor/CommonEditor.svelte";
+    import type {EditorVariant} from "../types";
+    import type {EditorEvents} from "../events";
+    import type {KeyboardEvents} from "../events";
+    import {eventFilter} from "../../utils/prefixFilter";
+    import type CommonFieldProps from "../common_editor/CommonFieldProps";
+
+    interface Props extends CommonFieldProps, KeyboardEvents {
+
+        value?: string;
+        oninput?: (event: Event) => void;
+    }
+
+    let {
+        variant,
+        theme,
+        tooltip,
+        compact = false,
+        style,
+        value = $bindable(),
+        disabled = false,
+        placeholder,
+        onchange,
+        oninput,
+        ...restProps
+    }: Props = $props();
+
+
+    let editor: HTMLInputElement;
+
+    export function focus() {
+        editor?.focus();
+    }
+
+    let composing = $state(false);
+    let inputText = $state(value ?? '');
+
+    // 外部 value 变化时同步到输入框文本
+    $effect(() => {
+        if (!composing) {
+            inputText = value ?? '';
+        }
+    });
+
+    const handleInput = (e: Event) => {
+        if (!composing) {
+            value = inputText;
+            oninput?.(e as InputEvent);
+            onchange?.(value);
+        }
+    };
+
+    const handleCompositionStart = () => {
+        composing = true;
+    };
+
+    const handleCompositionEnd = (e: Event) => {
+        composing = false;
+        value = inputText;
+        oninput?.(e as InputEvent);
+    };
+
+    // Must stay reactive: restProps (and therefore any on* handlers a consumer passes
+    // through, e.g. onkeydown) can change after mount. A plain `const` snapshot would
+    // freeze the handlers captured on the first render and silently ignore later updates.
+    let events = $derived(eventFilter(restProps));
+
+    const eventHandlers = {
+        oninput: handleInput,
+        oncompositionstart: handleCompositionStart,
+        oncompositionend: handleCompositionEnd,
+    };
+</script>
+
+<CommonEditor {variant} {theme} {compact} {tooltip} {style} {disabled} input$class='search-box'>
+    {#snippet leadingIcon()}
+        <div style="line-height: 16px; font-size: 18px">
+            <i class="icon_google_search"></i>
+        </div>
+    {/snippet}
+    <input
+            bind:this={editor}
+            style="width: 100%"
+            bind:value={inputText}
+            {disabled}
+            {placeholder}
+            {...eventHandlers}
+            {...events}
+    />
+</CommonEditor>

package/dist/form/search_box/SearchBox.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { KeyboardEvents } from "../events";
+import type CommonFieldProps from "../common_editor/CommonFieldProps";
+interface Props extends CommonFieldProps, KeyboardEvents {
+    value?: string;
+    oninput?: (event: Event) => void;
+}
+declare const SearchBox: import("svelte").Component<Props, {
+    focus: () => void;
+}, "value">;
+type SearchBox = ReturnType<typeof SearchBox>;
+export default SearchBox;

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

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

package/dist/form/search_box/index.js

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