@ticatec/topside-elements 1.0.0

package/dist/form/color_picker/README_CN.md

@@ -0,0 +1,296 @@
+# ColorPicker
+
+颜色选择器组件，提供直观的颜色选择界面。它将原生 HTML5 颜色输入与视觉颜色色板预览相结合，使您可以一目了然地看到所选颜色。非常适合主题、品牌、设计系统以及任何需要颜色选择的场景。
+
+## 特性
+
+- **原生颜色输入** —— 使用浏览器的原生颜色选择器，在所有平台上提供一致的用户体验。
+- **视觉预览** —— 将所选颜色显示为输入旁边的色板。
+- **紧凑模式** —— 可用于密集布局。
+- **禁用和只读** —— 完全支持禁用和只读状态。
+- **多种变体** —— 支持纯净、轮廓和填充变体。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import ColorPicker from "@ticatec/topside-elements/ColorPicker";
+```
+
+## 基础用法
+
+```svelte
+<script lang="ts">
+  import ColorPicker from "@ticatec/topside-elements/ColorPicker";
+
+  let selectedColor = $state("#3b82f6");
+</script>
+
+<ColorPicker bind:value={selectedColor} />
+```
+
+## 属性（Props）
+
+`ColorPicker` 继承自 `CommonFieldProps`，因此自动获得 `variant`、`compact`、`disabled`、`readonly`、`style`、`error`、`tooltip`、`theme`、`placeholder`。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `string`（可绑定） | `"#000000"` | `#RRGGBB` 格式的颜色（例如 `#3b82f6`）。`bind:value={...}` 用于双向绑定。 |
+| `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`，用于作用域样式覆盖。 |
+| `onchange` | `(value: string) => void` | — | 颜色变化时触发。接收新的 hex 颜色值。 |
+| `onfocus` | `(event: FocusEvent) => void` | — | 输入框获焦。 |
+| `onblur` | `(event: FocusEvent) => void` | — | 输入框失焦。 |
+
+## 事件
+
+| 事件 | 签名 | 说明 |
+|------|------|------|
+| `onchange` | `(value: string) => void` | 颜色变化时触发。接收新的 hex 颜色值。 |
+| `onfocus` | `(event: FocusEvent) => void` | 输入框获焦。 |
+| `onblur` | `(event: FocusEvent) => void` | 输入框失焦。 |
+
+## 方法
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `focus()` | `() => void` | 让颜色选择器输入获取焦点。 |
+
+```svelte
+<script lang="ts">
+  import ColorPicker from "@ticatec/topside-elements/ColorPicker";
+
+  let pickerRef;
+
+  function focusPicker() {
+    pickerRef.focus();
+  }
+</script>
+
+<ColorPicker bind:this={pickerRef} bind:value={selectedColor} />
+<button onclick={focusPicker}>聚焦</button>
+```
+
+## 示例
+
+### 基本颜色选择器
+
+```svelte
+<script lang="ts">
+  import ColorPicker from "@ticatec/topside-elements/ColorPicker";
+
+  let color = $state("#3b82f6");
+</script>
+
+<ColorPicker bind:value={color} />
+<p>已选择颜色: {color}</p>
+```
+
+### 带预览框的颜色选择器
+
+```svelte
+<script lang="ts">
+  import ColorPicker from "@ticatec/topside-elements/ColorPicker";
+
+  let primaryColor = $state("#3b82f6");
+  let secondaryColor = $state("#10b981");
+  let accentColor = $state("#f59e0b");
+</script>
+
+<div class="color-pickers">
+  <div class="color-item">
+    <ColorPicker bind:value={primaryColor} />
+    <div class="preview" style="background-color: {primaryColor}"></div>
+  </div>
+  <div class="color-item">
+    <ColorPicker bind:value={secondaryColor} />
+    <div class="preview" style="background-color: {secondaryColor}"></div>
+  </div>
+  <div class="color-item">
+    <ColorPicker bind:value={accentColor} />
+    <div class="preview" style="background-color: {accentColor}"></div>
+  </div>
+</div>
+
+<style>
+  .color-pickers {
+    display: flex;
+    gap: 24px;
+    margin: 20px;
+  }
+  .color-item {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  .preview {
+    width: 48px;
+    height: 48px;
+    border-radius: 8px;
+    border: 1px solid #e5e7eb;
+  }
+</style>
+```
+
+### 禁用和只读模式
+
+```svelte
+<script lang="ts">
+  import ColorPicker from "@ticatec/topside-elements/ColorPicker";
+
+  let disabledColor = $state("#ef4444");
+  let readonlyColor = $state("#8b5cf6");
+  let normalColor = $state("#3b82f6");
+</script>
+
+<div style="display: flex; flex-direction: column; gap: 16px;">
+  <ColorPicker bind:value={disabledColor} disabled />
+  <ColorPicker bind:value={readonlyColor} readonly />
+  <ColorPicker bind:value={normalColor} />
+</div>
+```
+
+### 紧凑模式
+
+```svelte
+<script lang="ts">
+  import ColorPicker from "@ticatec/topside-elements/ColorPicker";
+
+  let color = $state("#10b981");
+</script>
+
+<table>
+  <thead>
+    <tr>
+      <th>名称</th>
+      <th>颜色</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>主色</td>
+      <td>
+        <ColorPicker bind:value={color} compact />
+      </td>
+    </tr>
+    <tr>
+      <td>辅助色</td>
+      <td>
+        <ColorPicker bind:value={color} compact />
+      </td>
+    </tr>
+  </tbody>
+</table>
+```
+
+### 主题定制
+
+```svelte
+<script lang="ts">
+  import ColorPicker from "@ticatec/topside-elements/ColorPicker";
+
+  let primaryColor = $state("#3b82f6");
+  let secondaryColor = $state("#10b981");
+  let accentColor = $state("#f59e0b");
+  let errorColor = $state("#ef4444");
+  let warningColor = $state("#f59e0b");
+  let successColor = $state("#10b981");
+</script>
+
+<div class="theme-customizer">
+  <h3>主题定制</h3>
+  <div class="color-grid">
+    <div class="color-item">
+      <label>主色</label>
+      <ColorPicker bind:value={primaryColor} />
+    </div>
+    <div class="color-item">
+      <label>辅助色</label>
+      <ColorPicker bind:value={secondaryColor} />
+    </div>
+    <div class="color-item">
+      <label>强调色</label>
+      <ColorPicker bind:value={accentColor} />
+    </div>
+    <div class="color-item">
+      <label>错误</label>
+      <ColorPicker bind:value={errorColor} />
+    </div>
+    <div class="color-item">
+      <label>警告</label>
+      <ColorPicker bind:value={warningColor} />
+    </div>
+    <div class="color-item">
+      <label>成功</label>
+      <ColorPicker bind:value={successColor} />
+    </div>
+  </div>
+</div>
+
+<style>
+  .theme-customizer {
+    max-width: 600px;
+    margin: 20px;
+  }
+  .color-grid {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    gap: 16px;
+    margin-top: 16px;
+  }
+  .color-item {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  .color-item label {
+    font-weight: 500;
+    color: #374151;
+  }
+</style>
+```
+
+## 行为说明
+
+### 原生颜色输入 + 可编辑的 hex 文本框
+
+组件并排展示两部分：原生 `<input type="color">` 色板（点击打开浏览器内置的颜色选择器）和展示 hex 值的文本框。文本框可以直接编辑——输入一个值并提交（失焦或回车）后，`value` 会像通过色板选色一样更新。
+
+不支持透明通道——`<input type="color">` 本身没有这个概念，因此 `value` 始终是纯 6 位 `#rrggbb`。
+
+### Hex 格式与校验
+
+`value` 必须是合法的 `#RRGGBB`（`#` 后跟 6 位十六进制数字，大小写不敏感）。在文本框中输入时：
+
+- 只能输入 `#` 和十六进制字符（`0-9a-fA-F`），最多 6 位——其他字符在输入时会被拦截或截断。
+- 校验只在提交时（失焦或回车）进行，不是每次按键都校验，因此可以正常输入中间的不完整状态。
+- 提交时如果缺少开头的 `#` 会自动补上（例如输入 `ff0000` 会被提交为 `#ff0000`）。
+- 如果提交的文本不是合法的 `#RRGGBB`，文本框会回退到上一个合法值——不会触发 `onchange`。
+
+### 禁用和只读状态
+
+- **禁用**：颜色选择器不可交互。视觉色板变暗，hex 文本框也被禁用。
+- **只读**：颜色选择器不可交互，但完全可见——色板会拦截点击（无法打开原生选择器），hex 文本框变为不可编辑（但不变暗）的只读文本框。
+
+## 无障碍
+
+- 原生颜色输入具有适当的 ARIA 属性。
+- 视觉色板是装饰性的，标记为 `aria-hidden="true"`。
+- 完整的 ARIA 需要外层 `<label>` 或使用 `aria-label`。
+
+## 相关组件
+
+- [TextEditor](../text_editor/README_CN.md) —— 多行文本区域。
+- [NumberEditor](../number_editor/README_CN.md) —— 数值输入。
+- [DatePicker](../date_picker/README_CN.md) —— 日期选择。

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

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

package/dist/form/color_picker/index.js

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

package/dist/form/common_editor/BasePicker.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+
+    import Popover from "../../overlay/common/Popover.svelte";
+    import type {Snippet} from "svelte";
+    import FormEditor from "../FormEditor.svelte";
+    import type CommonPickerProps from "./CommonPickerProps";
+
+    interface Props extends CommonPickerProps {
+        expanded: boolean;
+        autoFit?: boolean;
+        children: Snippet;
+        popup?: Snippet;
+    }
+
+    let {
+        variant,
+        theme,
+        placeholder,
+        disabled = false,
+        readonly = false,
+        compact = false,
+        expanded = $bindable(false),
+        style,
+        autoFit = true,
+        tooltip,
+        error,
+        children,
+        popup,
+    }: Props = $props();
+
+
+    let editorElement: HTMLElement | undefined = $state();
+
+
+</script>
+<FormEditor {variant} {readonly} {disabled} {theme} {style} {tooltip} {compact} {error}>
+    <div bind:this={editorElement} class="topside-common-picker" tabindex="-1">
+        {@render children()}
+    </div>
+</FormEditor>
+
+{#if expanded}
+    <Popover target={editorElement} onclose={()=>{expanded=false}} {autoFit} {theme}>
+        {#if popup}
+            {@render children()}
+        {/if}
+    </Popover>
+{/if}

package/dist/form/common_editor/BasePicker.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+import type CommonPickerProps from "./CommonPickerProps";
+interface Props extends CommonPickerProps {
+    expanded: boolean;
+    autoFit?: boolean;
+    children: Snippet;
+    popup?: Snippet;
+}
+declare const BasePicker: import("svelte").Component<Props, {}, "expanded">;
+type BasePicker = ReturnType<typeof BasePicker>;
+export default BasePicker;

package/dist/form/common_editor/CommonEditor.svelte

@@ -0,0 +1,121 @@
+<script lang="ts">
+    import FormEditor from "../FormEditor.svelte";
+    import type CommonEditorProps from "./CommonEditorProps";
+    import { type Snippet } from "svelte";
+
+    interface Props extends CommonEditorProps {
+        textValue?: string;
+        children: Snippet;
+        input$class?: string;
+        clearable?: boolean;
+        clear?: () => void;
+    }
+
+    let {
+        theme,
+        tooltip,
+        error,
+        variant,
+        disabled = false,
+        readonly = false,
+        compact = false,
+        clearable = true,
+        style,
+        textValue,
+        suffix,
+        prefix,
+        children,
+        input$class,
+        leadingIcon,
+        trailingIcon,
+        clear
+    }: Props = $props();
+
+    let container = $state<HTMLDivElement | null>(null);
+
+    // ✨ 修复点 1：显式暴露获取原生 DOM 的方法
+    export function getElement() {
+        return container;
+    }
+
+    // ✨ 修复点 2：显式暴露让内部 input 聚焦的方法
+    export function focus() {
+        if (container) {
+            const inputElement = container.querySelector('input');
+            inputElement?.focus();
+        }
+    }
+
+    const handleContainerClick = () => {
+        if (disabled) return;
+        focus();
+    }
+
+    // Only intercept mousedowns that land on the wrapper's own decorative chrome
+    // (padding, prefix/suffix, icons) — preventing their default avoids a
+    // blur-then-refocus flicker when clicking near the control. A mousedown that
+    // originates on the actual form control (input/textarea, including the one
+    // rendered by NumberInput.svelte) must NOT be intercepted: preventDefault()
+    // there cancels the browser's native text-selection-start behavior for that
+    // same event, even though this listener runs on an ancestor during bubbling —
+    // that's what made it impossible to drag-select or double-click-select text
+    // inside every CommonEditor-based input (SearchBox, TextEditor, PasswordEditor,
+    // NumberEditor, TimeEditor, and anything built on CommonPopupEditor).
+    const handleContainerMouseDown = (e: MouseEvent) => {
+        const tag = (e.target as HTMLElement).tagName;
+        if (tag !== 'INPUT' && tag !== 'TEXTAREA') {
+            e.preventDefault();
+        }
+    };
+</script>
+
+<FormEditor {theme} {tooltip} {error} {style} {readonly} {disabled} {compact} {variant}>
+    <!-- Decorative flex wrapper only: the real interactive control is the
+         <input>/children snippet rendered inside, which carries its own
+         semantics — this div must not steal or hide them via role/aria-hidden.
+         onclick here only forwards focus to that inner control, it's not an
+         independent action, so no interactive role/keyboard handler applies. -->
+    <!-- svelte-ignore a11y_click_events_have_key_events -->
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <div class="topside-common-editor" bind:this={container} {style}
+         onmousedown={handleContainerMouseDown} onclick={handleContainerClick}>
+        {#if leadingIcon}
+            <div class="editor-embed-icon" style="flex: 0 0 auto;">
+                {@render leadingIcon()}
+            </div>
+        {:else if prefix}
+            <div class="editor-prefix" tabindex="-1" style="flex: 0 0 auto;">
+                <span>{prefix}</span>
+            </div>
+        {/if}
+        {#if disabled || readonly}
+            <input type="text" class={input$class} style="flex: 1 1 auto" value={textValue} {disabled} {readonly}>
+        {:else}
+            <div class={input$class} style="position: relative; flex: 1 1 auto">
+                {@render children()}
+                {#if clearable}
+                    <!-- Reserved unconditionally (not gated on textValue) so
+                         .topside-common-editor:has(.clean-icon)'s input
+                         padding-right in topside-form-editor.scss stays
+                         constant — otherwise the editor visibly grows/shifts
+                         the moment text is first entered. -->
+                    <div class="clean-icon" class:has-value={textValue}>
+                        <i class="icon_google_clear" role="button" tabindex="-1" aria-label="Clear"
+                           onmousedown={(e: MouseEvent)=>{e.preventDefault()}} onclick={textValue ? clear : undefined}
+                           onkeydown={(e: KeyboardEvent) => { if (textValue && (e.key === 'Enter' || e.key === ' ')) { e.preventDefault(); clear?.(); } }}></i>
+                    </div>
+                {/if}
+            </div>
+        {/if}
+        {#if suffix}
+            <div class="editor-suffix" style="flex: 0 0 auto;">
+                <span>{suffix}</span>
+            </div>
+        {/if}
+        {#if trailingIcon}
+            <div class="editor-embed-icon" style="flex: 0 0 auto;">
+                {@render trailingIcon()}
+            </div>
+        {/if}
+    </div>
+</FormEditor>

package/dist/form/common_editor/CommonEditor.svelte.d.ts

@@ -0,0 +1,15 @@
+import type CommonEditorProps from "./CommonEditorProps";
+import { type Snippet } from "svelte";
+interface Props extends CommonEditorProps {
+    textValue?: string;
+    children: Snippet;
+    input$class?: string;
+    clearable?: boolean;
+    clear?: () => void;
+}
+declare const CommonEditor: import("svelte").Component<Props, {
+    getElement: () => HTMLDivElement | null;
+    focus: () => void;
+}, "">;
+type CommonEditor = ReturnType<typeof CommonEditor>;
+export default CommonEditor;

package/dist/form/common_editor/CommonEditorProps.d.ts

@@ -0,0 +1,26 @@
+import type { Snippet } from "svelte";
+import type CommonFieldProps from "./CommonFieldProps";
+/**
+ * 通用编辑器属性接口
+ *
+ * 在 [[CommonFieldProps]] 基础上扩展前缀、后缀、前后置图标以及内容片段，
+ * 用于包装输入控件并附加装饰性内容。
+ */
+export default interface CommonEditorProps extends CommonFieldProps {
+    /**
+     * 字段前缀文本，展示在输入区域前方
+     */
+    prefix?: string;
+    /**
+     * 字段后缀文本，展示在输入区域后方
+     */
+    suffix?: string;
+    /**
+     * 前置图标片段，渲染在输入区域前方，优先级高于 prefix
+     */
+    leadingIcon?: Snippet;
+    /**
+     * 后置图标片段，渲染在输入区域后方，优先级高于 suffix
+     */
+    trailingIcon?: Snippet;
+}

package/dist/form/common_editor/CommonEditorProps.js

@@ -0,0 +1 @@
+export {};

package/dist/form/common_editor/CommonFieldProps.d.ts

@@ -0,0 +1,56 @@
+import type { EditorVariant } from "../types";
+/**
+ * 通用字段属性接口
+ *
+ * 定义所有表单字段编辑器共享的基础属性，可作为字段类型组件Props的基础契约。
+ */
+export default interface CommonFieldProps {
+    /**
+     * 主题样式名称，用于切换组件外观主题
+     */
+    theme?: string;
+    /**
+     * 悬停提示信息，鼠标悬浮在字段上时显示
+     */
+    tooltip?: string;
+    /**
+     * 错误信息，用于在字段下方展示校验错误提示
+     */
+    error?: string;
+    /**
+     * 是否禁用该字段，禁用后字段不可编辑且不响应交互
+     */
+    disabled?: boolean;
+    /**
+     * 是否只读，只读状态下字段不可编辑但可聚焦和复制
+     */
+    readonly?: boolean;
+    /**
+     * 是否启用紧凑模式，紧凑模式下字段内部间距更小
+     */
+    compact?: boolean;
+    /**
+     * 编辑器外观样式变体
+     */
+    variant?: EditorVariant;
+    /**
+     * 占位提示文本，字段值为空时在输入区域内展示
+     */
+    placeholder?: string;
+    /**
+     * 自定义内联样式，会应用到字段根容器上
+     */
+    style?: string;
+    /**
+     * 字段获得焦点时触发的回调
+     */
+    onfocus?: (event: FocusEvent) => void;
+    /**
+     * 字段失去焦点时触发的回调
+     */
+    onblur?: (event: FocusEvent) => void;
+    /**
+     * 字段值发生变化时触发的回调
+     */
+    onchange?: (value?: any) => void;
+}

package/dist/form/common_editor/CommonFieldProps.js

@@ -0,0 +1 @@
+export {};