@ticatec/topside-elements 1.0.0

package/dist/form/time_editor/README_CN.md

@@ -0,0 +1,386 @@
+# TimeEditor 时间输入组件
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `mandatory` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+专业的时间输入组件，支持交互式的时分/时分秒选择功能。具有键盘导航、自动校验，支持分钟（HH:MM）和秒（HH:MM:SS）两种精度。组件内部以分钟数（含小数秒）存储时间值。
+
+## 功能特性
+
+- **交互选择**: 点击或键盘方向键在不同时间段之间导航。
+- **自动校验**: 防止无效时间输入（如 25:70）。
+- **灵活精度**: 支持分钟精度（HH:MM）和秒精度（HH:MM:SS）。
+- **清除功能**: 内置清除按钮重置时间。
+- **视觉反馈**: 高亮显示当前光标所在时间段。
+- **必填模式**: 可选显示 `00:00` 而非 `__:__` 表示必填字段。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import TimeEditor from "@ticatec/topside-elements/TimeEditor";
+```
+
+## 基础用法
+
+```svelte
+<script>
+  import TimeEditor from "@ticatec/topside-elements/TimeEditor";
+
+  let timeValue = undefined; // undefined 或数字（分钟数）
+</script>
+
+<TimeEditor bind:value={timeValue} />
+```
+
+## 属性（Props）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `number \| undefined` | `undefined` | 时间值（分钟数），如 `90.5` = 1:30:30。可双向绑定。 |
+| `precision` | `"M" \| "S"` | `"M"` | 时间精度：`"M"` 为分钟（HH:MM），`"S"` 为秒（HH:MM:SS）。 |
+| `clearable` | `boolean` | `true` | 是否允许清空（显示清空按钮）。旧名 `mandatory` 语义相反（`mandatory={true}` = `clearable={false}`），5.1.0 已移除。 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉样式变体。 |
+| `compact` | `boolean` | `false` | 紧凑间距布局。 |
+| `disabled` | `boolean` | `false` | 禁用编辑器。 |
+| `readonly` | `boolean` | `false` | 设为只读。 |
+| `prefix` | `string` | `""` | 时间前面的文本。 |
+| `suffix` | `string` | `""` | 时间后面的文本。 |
+| `leadingIcon` | `Snippet` | `undefined` | 渲染在时间前面的代码片段。 |
+| `trailingIcon` | `Snippet` | `undefined` | 渲染在时间后面的代码片段。 |
+| `error` | `string` | `undefined` | 错误信息文本。 |
+| `tooltip` | `string` | `undefined` | 悬停提示文本。 |
+| `theme` | `string` | `undefined` | 主题名称，用于切换外观。 |
+| `style` | `string` | `""` | 内联 CSS 样式。 |
+| `onchange` | `(value: number \| undefined) => void` | `undefined` | 失焦时触发，返回已提交的时间值。 |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | 输入框获取焦点时触发。 |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | 输入框失去焦点时触发。 |
+
+## 值格式
+
+TimeEditor 以分钟数存储时间：
+
+| 值 | 显示 | 说明 |
+|---|------|------|
+| `undefined` | `__:__` 或 `00:00` | 空/未设置 |
+| `570` | `09:30` | 9 小时 30 分钟 |
+| `90.5` | `01:30:30` | 1 小时 30 分 30 秒 |
+
+范围：`0` 到 `1439` 分钟（23:59）。
+
+## 键盘导航
+
+| 按键 | 动作 |
+|------|------|
+| `Arrow Left/Up` | 光标移到上一个时间段。 |
+| `Arrow Right/Down` | 光标移到下一个时间段。 |
+| `0-9` | 在当前光标位置输入数字。 |
+| `Delete` | 清除当前时间段。 |
+| `Backspace` | 清除当前时间段并后退光标。 |
+| `Tab` | 移到下一个元素。 |
+
+## 示例
+
+### 基本时间输入（分钟）
+
+```svelte
+<script>
+  import TimeEditor from "@ticatec/topside-elements/TimeEditor";
+
+  let meetingTime = 570; // 上午 9:30（9*60 + 30 = 570 分钟）
+</script>
+
+<div class="form-group">
+  <label>会议时间：</label>
+  <TimeEditor bind:value={meetingTime} precision="M" />
+</div>
+
+<p>选中时间：{Math.floor(meetingTime / 60)}:{(meetingTime % 60).toString().padStart(2, '0')}</p>
+```
+
+### 带秒的时间输入
+
+```svelte
+<script>
+  import TimeEditor from "@ticatec/topside-elements/TimeEditor";
+
+  let duration = 125.75; // 2:05:45（125 分钟 + 45 秒）
+</script>
+
+<div class="form-group">
+  <label>视频时长：</label>
+  <TimeEditor bind:value={duration} precision="S" />
+</div>
+```
+
+### 带事件处理
+
+```svelte
+<script>
+  import TimeEditor from "@ticatec/topside-elements/TimeEditor";
+
+  let scheduleTime = undefined;
+  let isFocused = false;
+
+  function handleTimeChange(newTime) {
+    console.log("时间变更为:", newTime);
+    if (newTime !== undefined) {
+      const hours = Math.floor(newTime / 60);
+      const minutes = Math.floor(newTime % 60);
+      const seconds = Math.floor((newTime % 1) * 60);
+      console.log(`时间: ${hours}:${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`);
+    }
+  }
+
+  function handleFocus() {
+    isFocused = true;
+  }
+
+  function handleBlur() {
+    isFocused = false;
+  }
+</script>
+
+<TimeEditor
+  bind:value={scheduleTime}
+  precision="S"
+  onchange={handleTimeChange}
+  onfocus={handleFocus}
+  onblur={handleBlur}
+/>
+
+<p>{isFocused ? "时间编辑器处于激活状态" : "时间编辑器未激活"}</p>
+```
+
+### 必填模式
+
+```svelte
+<script>
+  import TimeEditor from "@ticatec/topside-elements/TimeEditor";
+
+  let optionalTime = undefined;
+  let requiredTime = undefined;
+</script>
+
+<!-- 可选模式（显示下划线） -->
+<div class="form-group">
+  <label>可选时间：</label>
+  <TimeEditor bind:value={optionalTime} />
+</div>
+
+<!-- 必填模式（显示零） -->
+<div class="form-group">
+  <label>必填时间：</label>
+  <TimeEditor bind:value={requiredTime} clearable={false} />
+</div>
+```
+
+### 带前缀和后缀
+
+```svelte
+<script>
+  import TimeEditor from "@ticatec/topside-elements/TimeEditor";
+
+  let startTime = 480; // 8:00 AM
+  let duration = 120;  // 2:00 小时
+</script>
+
+<div class="form-group">
+  <label>开始时间：</label>
+  <TimeEditor bind:value={startTime} suffix=" AM" />
+</div>
+
+<div class="form-group">
+  <label>时长：</label>
+  <TimeEditor bind:value={duration} prefix="时长: " suffix=" 小时" />
+</div>
+```
+
+### 日程表单
+
+```svelte
+<script>
+  import TimeEditor from "@ticatec/topside-elements/TimeEditor";
+
+  let schedule = {
+    title: "",
+    startTime: undefined,
+    endTime: undefined,
+    breakDuration: 15 // 15 分钟
+  };
+
+  function handleSubmit() {
+    console.log("日程:", schedule);
+  }
+
+  function formatTime(minutes) {
+    if (minutes === undefined) return "未设置";
+    const hours = Math.floor(minutes / 60);
+    const mins = Math.floor(minutes % 60);
+    return `${hours}:${mins.toString().padStart(2, '0')}`;
+  }
+</script>
+
+<div class="schedule-form">
+  <h3>创建日程</h3>
+
+  <div class="form-field">
+    <label>活动标题</label>
+    <input bind:value={schedule.title} placeholder="输入活动标题" />
+  </div>
+
+  <div class="form-row">
+    <div class="form-field">
+      <label>开始时间</label>
+      <TimeEditor bind:value={schedule.startTime} precision="M" />
+    </div>
+
+    <div class="form-field">
+      <label>结束时间</label>
+      <TimeEditor bind:value={schedule.endTime} precision="M" />
+    </div>
+  </div>
+
+  <div class="form-field">
+    <label>休息时长（分钟）</label>
+    <TimeEditor bind:value={schedule.breakDuration} precision="M" />
+  </div>
+
+  <button onclick={handleSubmit}>创建日程</button>
+</div>
+
+<style>
+  .schedule-form {
+    max-width: 500px;
+    padding: 24px;
+    border: 1px solid #ddd;
+    border-radius: 8px;
+  }
+  .form-row {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 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 TimeEditor from "@ticatec/topside-elements/TimeEditor";
+
+  let timerDuration = 5; // 5 分钟
+  let currentTime = 0;
+  let isRunning = false;
+  let interval;
+
+  function startTimer() {
+    if (timerDuration > 0) {
+      currentTime = timerDuration;
+      isRunning = true;
+
+      interval = setInterval(() => {
+        currentTime -= 1 / 60; // 减去 1 秒（1/60 分钟）
+
+        if (currentTime <= 0) {
+          currentTime = 0;
+          stopTimer();
+          alert("计时结束！");
+        }
+      }, 1000);
+    }
+  }
+
+  function stopTimer() {
+    isRunning = false;
+    if (interval) {
+      clearInterval(interval);
+      interval = undefined;
+    }
+  }
+
+  function resetTimer() {
+    stopTimer();
+    currentTime = 0;
+  }
+</script>
+
+<div class="timer-container">
+  <h3>计时器</h3>
+
+  <div class="form-field">
+    <label>设置时长：</label>
+    <TimeEditor bind:value={timerDuration} precision="S" disabled={isRunning} />
+  </div>
+
+  <div class="form-field">
+    <label>剩余时间：</label>
+    <TimeEditor bind:value={currentTime} precision="S" readonly />
+  </div>
+
+  <div class="timer-controls">
+    {#if !isRunning}
+      <button onclick={startTimer} disabled={timerDuration <= 0}>开始</button>
+    {:else}
+      <button onclick={stopTimer}>停止</button>
+    {/if}
+    <button onclick={resetTimer}>重置</button>
+  </div>
+</div>
+
+<style>
+  .timer-container {
+    max-width: 300px;
+    padding: 20px;
+    border: 1px solid #ddd;
+    border-radius: 8px;
+  }
+  .form-field {
+    margin-bottom: 16px;
+  }
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+  .timer-controls {
+    display: flex;
+    gap: 8px;
+  }
+  button {
+    padding: 8px 16px;
+    cursor: pointer;
+  }
+</style>
+```
+
+## 最佳实践
+
+1. **精度选择**: 大多数日程场景使用分钟精度；仅当需要亚分钟精度时使用 `"S"`。
+2. **校验**: 组件在失焦时校验；可在 `onchange` 中添加额外校验。
+3. **标签**: 提供清晰的标签说明预期的时间格式。
+4. **默认值**: 考虑提供合理的默认时间。
+5. **范围校验**: 在应用逻辑中校验时间范围。
+
+## 相关组件
+
+- [DatePicker](../date_picker/README_CN.md) — 日期选择组件。
+- [DateTimePicker](../date_picker/README_CN.md) — 组合日期时间选择。
+- [NumberEditor](../number_editor/README_CN.md) — 带校验的数字输入。

package/dist/form/time_editor/TimeEditor.svelte

@@ -0,0 +1,231 @@
+<script lang="ts">
+    import type {Snippet} from "svelte";
+    import {tick} from "svelte";
+    import CommonEditor from "../common_editor/CommonEditor.svelte";
+    import type CommonFieldProps from "../common_editor/CommonFieldProps";
+
+    type TimePrecision = 'M' | 'S';
+
+    interface Props extends CommonFieldProps {
+        precision?: TimePrecision;
+        /** 是否允许清空（显示清空按钮），默认 true */
+        clearable?: boolean;
+        suffix?: string;
+        prefix?: string;
+        value?: number | undefined;
+        leadingIcon?: Snippet;
+        trailingIcon?: Snippet;
+    }
+
+    let {
+        disabled = false,
+        readonly = false,
+        clearable = true,
+        precision = 'M',
+        variant,
+        theme,
+        compact = false,
+        style,
+        value = $bindable<number | undefined>(),
+        suffix,
+        prefix,
+        onfocus,
+        onblur,
+        onchange,
+        leadingIcon,
+        trailingIcon,
+    }: Props = $props();
+
+
+    let editor: HTMLInputElement;
+    let hasFocus = $state(false);
+    let cursorIndex = 0;
+    let oldValue: number | undefined = value;
+
+    const lastPos = $derived(precision === 'M' ? 4 : 7);
+
+    let textValue = $state(toTimeText(value));
+
+    $effect(() => {
+        if (!hasFocus) {
+            textValue = toTimeText(value);
+        }
+    });
+
+    function focus() {
+        editor?.focus();
+    }
+
+    function getEmptyStr(): string {
+        return precision === 'M' ? '__:__' : '__:__:__';
+    }
+
+    function toTimeText(v: number | undefined): string {
+        if (v == null) {
+            return clearable ? getEmptyStr() : getEmptyStr().replaceAll('_', '0');
+        }
+        const totalMinutes = Math.floor(v);
+        const hh = Math.min(23, Math.floor(totalMinutes / 60));
+        const mm = totalMinutes % 60;
+        const ss = Math.min(59, Math.floor((v - totalMinutes) * 100)) % 60;
+        let time = String(hh).padStart(2, "0") + ":" + String(mm).padStart(2, "0");
+        if (precision === "S") {
+            time += ":" + String(ss).padStart(2, "0");
+        }
+        return time;
+    }
+
+    function toTimeValue(): number {
+        const tt = textValue.replaceAll('_', '0').split(':');
+        const h = parseInt(tt[0]);
+        const m = parseInt(tt[1]);
+        const ss = tt.length === 3 ? parseInt(tt[2]) : 0;
+        return h * 60 + m + ss / 100;
+    }
+
+    function isValidTime(s: string): boolean {
+        const tt = s.replaceAll('_', '0').split(':');
+        const h = parseInt(tt[0]);
+        const m = parseInt(tt[1]);
+        const ss = tt.length === 3 ? parseInt(tt[2]) : 0;
+        return m < 60 && h * 60 + m < 1440 && ss < 60;
+    }
+
+    function replaceChar(position: number, newChar: string): string {
+        const arr = textValue.split('');
+        arr[position] = newChar;
+        return arr.join('');
+    }
+
+    function moveCursor(direction: number) {
+        let next = cursorIndex + direction;
+        if (next > lastPos) {
+            next = 0;
+        } else if (next < 0) {
+            next = lastPos;
+        }
+        if (next === 2 || next === 5) {
+            next += direction;
+        }
+        cursorIndex = next;
+        editor.setSelectionRange(cursorIndex, cursorIndex + 1);
+    }
+
+    function handleFocusEvent(e: FocusEvent) {
+        hasFocus = true;
+        if (!readonly) {
+            editor.setSelectionRange(cursorIndex, cursorIndex + 1);
+        }
+        onfocus?.(e);
+    }
+
+    function handleBlurEvent(e: FocusEvent) {
+        hasFocus = false;
+        if (!readonly) {
+            if (/^[_:]*$/.test(textValue)) {
+                value = undefined;
+            } else {
+                value = toTimeValue();
+            }
+            if (oldValue !== value) {
+                onchange?.(value);
+                oldValue = value;
+            }
+        }
+        onblur?.(e);
+    }
+
+    function handleMouseDown(e: MouseEvent) {
+        editor.focus();
+        e.stopPropagation();
+        e.preventDefault();
+    }
+
+    async function handleKeyDown(e: KeyboardEvent) {
+        if (e.key === 'Tab') return;
+        switch (e.key) {
+            case 'ArrowLeft':
+            case 'ArrowUp':
+                moveCursor(-1);
+                break;
+            case 'ArrowRight':
+            case 'ArrowDown':
+                moveCursor(1);
+                break;
+            case 'Delete':
+                textValue = replaceChar(cursorIndex, clearable ? '_' : '0');
+                break;
+            case 'Backspace':
+                textValue = replaceChar(cursorIndex, clearable ? '_' : '0');
+                await tick();
+                moveCursor(cursorIndex > 0 ? -1 : 0);
+                break;
+            case '0':
+            case '1':
+            case '2':
+            case '3':
+            case '4':
+            case '5':
+            case '6':
+            case '7':
+            case '8':
+            case '9': {
+                const s = replaceChar(cursorIndex, e.key);
+                if (isValidTime(s)) {
+                    textValue = s;
+                    await tick();
+                    moveCursor(1);
+                }
+                break;
+            }
+            default:
+                break;
+        }
+        e.stopPropagation();
+        e.preventDefault();
+    }
+
+    // 清空按钮 / 键盘清空都走这里：统一通知 onchange（与 Lookup / ColorPicker / OptionsMultiSelect 一致）
+    // 立即通知并同步 oldValue，之后失焦不会重复触发
+    async function clear() {
+        value = undefined;
+        textValue = getEmptyStr();
+        if (oldValue !== undefined) {
+            oldValue = undefined;
+            onchange?.(undefined);
+        }
+        await tick();
+        cursorIndex = 0;
+        editor.setSelectionRange(cursorIndex, cursorIndex + 1);
+        editor.focus();
+    }
+
+    // 只有允许清空且当前有内容时才显示清空按钮
+    const showClear = $derived(clearable && textValue !== getEmptyStr());
+</script>
+
+<CommonEditor
+    {style}
+    textValue={textValue}
+    {suffix}
+    {prefix}
+    {disabled}
+    {readonly}
+    {variant}
+    {theme}
+    {compact}
+    {leadingIcon}
+    {trailingIcon}
+    clearable={showClear}
+    {clear}>
+    <input
+        bind:this={editor}
+        type="text"
+        style="flex: 1 1 auto"
+        bind:value={textValue}
+        {disabled}
+        onkeydown={handleKeyDown}
+        onfocus={handleFocusEvent}
+        onblur={handleBlurEvent}
+        onmousedown={handleMouseDown}/>
+</CommonEditor>

package/dist/form/time_editor/TimeEditor.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Snippet } from "svelte";
+import type CommonFieldProps from "../common_editor/CommonFieldProps";
+type TimePrecision = 'M' | 'S';
+interface Props extends CommonFieldProps {
+    precision?: TimePrecision;
+    /** 是否允许清空（显示清空按钮），默认 true */
+    clearable?: boolean;
+    suffix?: string;
+    prefix?: string;
+    value?: number | undefined;
+    leadingIcon?: Snippet;
+    trailingIcon?: Snippet;
+}
+declare const TimeEditor: import("svelte").Component<Props, {}, "value">;
+type TimeEditor = ReturnType<typeof TimeEditor>;
+export default TimeEditor;

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

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

package/dist/form/time_editor/index.js

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

package/dist/form/types.d.ts

@@ -0,0 +1,8 @@
+export type EditorVariant = '' | 'plain' | 'outlined' | 'filled';
+export type InputType = 'text' | 'search' | 'email' | 'tel' | 'url' | 'password' | 'number';
+export type CaseMode = 'upper' | 'lower';
+/**
+ * 删除文件前的否决钩子（NAMING R2）：返回 false 取消删除。
+ * @template T 文件对象类型（AttachmentFile / ImageFile）
+ */
+export type BeforeRemove<T = any> = (file: T) => boolean | void | Promise<boolean | void>;

package/dist/form/types.js

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