@ticatec/topside-elements 1.0.0

package/dist/form/date_range/README_CN.md

@@ -0,0 +1,250 @@
+# DateRangeEditor 日期范围选择器
+
+带双日历弹层的日期范围字段，用于选择起始（`fromValue`）与结束（`toValue`）。输入框只读，通过日历点选赋值，并对起止两端做交叉约束。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import DateRangeEditor from "@ticatec/topside-elements/DateRange";
+```
+
+## 功能特性
+
+- 左右并排日历选择起始 / 结束日期
+- 交叉约束：起始不晚于结束，结束不早于起始
+- 全局 `min` / `max` 限制两端可选范围
+- 起始归一化为**当天开始**，结束归一化为**当天结束**
+- 通过 Day.js 格式标记自定义展示 `format`
+- 起止日期可分别清除
+- 样式变体：默认、`plain`、`outlined`、`filled`
+- 紧凑、禁用、只读
+- 通过表单编辑器外壳支持错误信息与 tooltip
+
+## 基本用法
+
+```svelte
+<script>
+  import DateRangeEditor from "@ticatec/topside-elements/DateRange";
+
+  let fromDate = $state(/** @type {Date | string | undefined} */ (undefined));
+  let toDate = $state(/** @type {Date | string | undefined} */ (undefined));
+</script>
+
+<DateRangeEditor bind:fromValue={fromDate} bind:toValue={toDate} />
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `fromValue` | `UniDate` | — | 起始日期，支持 `bind:fromValue`。可为 `Date`、Day.js、字符串或 `undefined` |
+| `toValue` | `UniDate` | — | 结束日期，支持 `bind:toValue` |
+| `format` | `string` | `"YYYY-MM-DD"` | 两端展示格式（Day.js 格式标记） |
+| `min` | `string \| Date` | — | 全局最早可选日期 |
+| `max` | `string \| Date` | — | 全局最晚可选日期 |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉样式 |
+| `compact` | `boolean` | `false` | 紧凑间距 |
+| `disabled` | `boolean` | `false` | 禁用，不可交互 |
+| `readonly` | `boolean` | `false` | 只读，不打开弹层 |
+| `error` | `string` | — | 错误信息（由表单外壳展示） |
+| `tooltip` | `string` | — | 悬停提示 |
+| `theme` | `string` | — | 主题名，传给表单编辑器外壳 |
+| `style` | `string` | `""` | 编辑器内联样式 |
+| `class` | `string` | `""` | 编辑器额外 CSS 类名 |
+
+组件**没有** `onchange` / `onfocus` / `onblur` 回调。请通过 `bind:fromValue`、`bind:toValue`（或对这两个变量的 `$effect` / 响应式逻辑）感知范围变化。
+
+## 类型定义
+
+```typescript
+// 来自 dateUtils
+type UniDate = dayjs.Dayjs | Date | string | undefined;
+
+type EditorVariant = "" | "plain" | "outlined" | "filled";
+```
+
+## 示例
+
+### 自定义格式 + 描边样式
+
+```svelte
+<script>
+  import DateRangeEditor from "@ticatec/topside-elements/DateRange";
+
+  let projectStart = $state(/** @type {Date | undefined} */ (undefined));
+  let projectEnd = $state(/** @type {Date | undefined} */ (undefined));
+</script>
+
+<DateRangeEditor
+  variant="outlined"
+  format="DD/MM/YYYY"
+  bind:fromValue={projectStart}
+  bind:toValue={projectEnd}
+/>
+```
+
+### 紧凑填充
+
+```svelte
+<script>
+  import DateRangeEditor from "@ticatec/topside-elements/DateRange";
+
+  let reportFrom = $state(/** @type {Date | undefined} */ (undefined));
+  let reportTo = $state(/** @type {Date | undefined} */ (undefined));
+</script>
+
+<DateRangeEditor
+  variant="filled"
+  compact
+  bind:fromValue={reportFrom}
+  bind:toValue={reportTo}
+/>
+```
+
+### 最小 / 最大约束
+
+```svelte
+<script>
+  import DateRangeEditor from "@ticatec/topside-elements/DateRange";
+
+  const year = new Date().getFullYear();
+  let periodStart = $state(new Date(year, 0, 1));
+  let periodEnd = $state(new Date(year, 11, 31));
+</script>
+
+<DateRangeEditor
+  variant="outlined"
+  bind:fromValue={periodStart}
+  bind:toValue={periodEnd}
+  min={new Date(year, 0, 1)}
+  max={new Date(year, 11, 31)}
+/>
+```
+
+### 禁用、只读与错误
+
+```svelte
+<script>
+  import DateRangeEditor from "@ticatec/topside-elements/DateRange";
+
+  let fromDate = $state("2025-03-01");
+  let toDate = $state("2025-03-15");
+</script>
+
+<DateRangeEditor disabled bind:fromValue={fromDate} bind:toValue={toDate} />
+<DateRangeEditor readonly bind:fromValue={fromDate} bind:toValue={toDate} />
+<DateRangeEditor error="日期范围无效" />
+```
+
+### 派生入住晚数
+
+```svelte
+<script>
+  import DateRangeEditor from "@ticatec/topside-elements/DateRange";
+  import dayjs from "dayjs";
+
+  let checkIn = $state(/** @type {Date | undefined} */ (undefined));
+  let checkOut = $state(/** @type {Date | undefined} */ (undefined));
+
+  let nights = $derived(
+    checkIn && checkOut
+      ? dayjs(checkOut).startOf("day").diff(dayjs(checkIn).startOf("day"), "day")
+      : 0
+  );
+</script>
+
+<div class="hotel-booking">
+  <h3>酒店预订</h3>
+  <DateRangeEditor
+    variant="outlined"
+    format="MMM DD, YYYY"
+    min={new Date()}
+    bind:fromValue={checkIn}
+    bind:toValue={checkOut}
+  />
+  <p>入住 {nights} 晚</p>
+</div>
+```
+
+## 行为说明
+
+### 布局
+
+字段展示两个居中的只读输入框，中间有分隔线，右侧为日历操作图标（`icon_google_event_note`）。点击任一输入框或图标会打开固定宽度（约 452px）的弹层，内含左右两个日历。
+
+### 归一化
+
+选中某一天时：
+
+| 端点 | 存储方式 |
+|------|----------|
+| **起始**（`fromValue`） | `dayjs(date).startOf("day").toDate()` |
+| **结束**（`toValue`） | `dayjs(date).endOf("day").toDate()` |
+
+展示文本基于归一化后的值，用 `format` 格式化。
+
+### 日历约束
+
+| 日历 | `min` | `max` |
+|------|-------|-------|
+| **起始**（左） | 全局 `min` | 已选结束日期（若有），否则全局 `max` |
+| **结束**（右） | 已选起始日期（若有），否则全局 `min` | 全局 `max` |
+
+### 选择流程
+
+1. 打开弹层（点击输入框或日历图标；`disabled` / `readonly` 时不可打开）。
+2. 在**左侧**日历选择起始日期 — 弹层保持打开。
+3. 在**右侧**日历选择结束日期 — 弹层关闭。
+4. 可用 × 分别清除起始或结束（有值且可编辑时显示）。
+
+### 清除
+
+- 清除起始：`fromValue = undefined`
+- 清除结束：`toValue = undefined`
+- `disabled` 或 `readonly` 时不显示清除图标
+
+## 日期格式
+
+`format` 支持 Day.js 格式标记：
+
+| 格式 | 示例 | 说明 |
+|------|------|------|
+| `YYYY-MM-DD` | 2024-03-15 | 默认 |
+| `DD/MM/YYYY` | 15/03/2024 | 日在前 |
+| `MM/DD/YYYY` | 03/15/2024 | 月在前 |
+| `MMM DD, YYYY` | Mar 15, 2024 | 短月份名 |
+| `DD MMM YYYY` | 15 Mar 2024 | 日 + 短月份 |
+
+```svelte
+<DateRangeEditor format="DD/MM/YYYY" bind:fromValue={start} bind:toValue={end} />
+<DateRangeEditor format="MMM DD, YYYY" bind:fromValue={start} bind:toValue={end} />
+```
+
+## 样式变体
+
+| 变体 | 说明 |
+|------|------|
+| `""` | 默认字段外观 |
+| `"plain"` | 极简样式 |
+| `"outlined"` | 描边 |
+| `"filled"` | 填充背景 |
+
+## 注意事项
+
+- 内部使用 Day.js 解析、归一化与格式化。
+- 输入框始终为 `readonly`，只能通过日历或绑定赋值。
+- 关闭弹层（点击外部等）不会清除已选的一端。
+- 入参可为字符串，如 `"2025-03-01"`。
+- 点选后写出的值为原生 `Date`（当天开始 / 当天结束）。
+
+## 相关组件
+
+- [DatePicker](../date_picker/README_CN.md) — 单日期 / 日期时间
+- [NumberRange](../number_range/README_CN.md) — 数字起止范围
+- [TimeEditor](../time_editor/README_CN.md) — 独立时间输入

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

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

package/dist/form/date_range/index.js

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

package/dist/form/events.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 事件接口的唯一定义处（NAMING R13）。
+ * 组件 Props 通过 extends 组合这些接口；参数名统一为 event。
+ */
+export interface FocusEvents {
+    onfocus?: (event: FocusEvent) => void;
+    onblur?: (event: FocusEvent) => void;
+    onfocusin?: (event: FocusEvent) => void;
+    onfocusout?: (event: FocusEvent) => void;
+}
+export interface KeyboardEvents {
+    onkeydown?: (event: KeyboardEvent) => void;
+    onkeyup?: (event: KeyboardEvent) => void;
+    onkeypress?: (event: KeyboardEvent) => void;
+}
+export interface InputEvents {
+    oninput?: (event: InputEvent) => void;
+    onbeforeinput?: (event: InputEvent) => void;
+}
+export interface CompositionEvents {
+    oncompositionstart?: (event: CompositionEvent) => void;
+    oncompositionend?: (event: CompositionEvent) => void;
+    oncompositionupdate?: (event: CompositionEvent) => void;
+}
+export interface ClipboardEvents {
+    oncopy?: (event: ClipboardEvent) => void;
+    oncut?: (event: ClipboardEvent) => void;
+    onpaste?: (event: ClipboardEvent) => void;
+}
+export interface MouseEvents {
+    onclick?: (event: MouseEvent) => void;
+    ondblclick?: (event: MouseEvent) => void;
+    onmousedown?: (event: MouseEvent) => void;
+    onmouseup?: (event: MouseEvent) => void;
+    onmouseover?: (event: MouseEvent) => void;
+    onmousemove?: (event: MouseEvent) => void;
+    onmouseout?: (event: MouseEvent) => void;
+    onmouseenter?: (event: MouseEvent) => void;
+    onmouseleave?: (event: MouseEvent) => void;
+    onwheel?: (event: WheelEvent) => void;
+}
+export interface TouchEvents {
+    ontouchstart?: (event: TouchEvent) => void;
+    ontouchend?: (event: TouchEvent) => void;
+    ontouchmove?: (event: TouchEvent) => void;
+    ontouchcancel?: (event: TouchEvent) => void;
+}
+export interface DragEvents {
+    ondrag?: (event: DragEvent) => void;
+    ondragstart?: (event: DragEvent) => void;
+    ondragend?: (event: DragEvent) => void;
+    ondragover?: (event: DragEvent) => void;
+    ondragenter?: (event: DragEvent) => void;
+    ondragleave?: (event: DragEvent) => void;
+    ondrop?: (event: DragEvent) => void;
+}
+export interface FormEvents {
+    onselect?: (event: Event) => void;
+    oninvalid?: (event: Event) => void;
+    onreset?: (event: Event) => void;
+}
+/**
+ * 原生输入控件的完整事件集合。
+ * onchange 由 Topside 接管：各组件传新值 (value) 而不是 DOM 事件。
+ */
+export interface EditorEvents extends FocusEvents, KeyboardEvents, InputEvents, CompositionEvents, ClipboardEvents, MouseEvents, TouchEvents, DragEvents, FormEvents {
+    onchange?: (value: any) => void;
+}
+/** 透传到原生 input 的键盘事件属性名；用 satisfies 绑定到 KeyboardEvents 的键。 */
+export declare const keyboardAttrs: readonly ["onkeydown", "onkeyup", "onkeypress"];

package/dist/form/events.js

@@ -0,0 +1,6 @@
+/**
+ * 事件接口的唯一定义处（NAMING R13）。
+ * 组件 Props 通过 extends 组合这些接口；参数名统一为 event。
+ */
+/** 透传到原生 input 的键盘事件属性名；用 satisfies 绑定到 KeyboardEvents 的键。 */
+export const keyboardAttrs = ['onkeydown', 'onkeyup', 'onkeypress'];

package/dist/form/group_box/group-check-box/GroupCheckBox.svelte

@@ -0,0 +1,211 @@
+<script lang="ts">
+    import utils from "../../../overlay/common/utils";
+    import CheckBox from "../../checkbox/CheckBox.svelte";
+    import FormEditor from "../../FormEditor.svelte";
+    import type {EditorVariant} from "../../types";
+    import type {EditorEvents} from "../../events";
+
+    interface OptionItem {
+        [key: string]: any;
+    }
+
+    interface Props {
+        disabled?: boolean;
+        readonly?: boolean;
+        style?: string;
+        error?: string;
+        tooltip?: string;
+        value: string | number;
+        bitBase?: boolean;
+        options: Array<OptionItem>;
+        keyField?: string;
+        textField?: string;
+        delimiter?: string;
+        /** 每个选项的内联样式 */
+        item$style?: string;
+        disabledOptions?: Array<string>;
+        hideOptions?: Array<string>;
+        variant?: EditorVariant;
+        compact?: boolean;
+        class?: string;
+        onchange?: (value: any) => void;
+        onblur?: (event: FocusEvent) => void;
+        onfocus?: (event: FocusEvent) => void;
+    }
+
+    let {
+        disabled = false,
+        readonly = false,
+        error,
+        tooltip,
+        style = "",
+        value = $bindable(),
+        bitBase = false,
+        options,
+        keyField = "code",
+        textField = "text",
+        delimiter = ';',
+        item$style = '',
+        disabledOptions = [],
+        hideOptions = [],
+        variant,
+        compact = false,
+        class: className = '',
+        onchange,
+        onfocus,
+        onblur
+    }: Props = $props();
+
+    let groupContainer: HTMLDivElement;
+    let checkboxStates = $state<Record<string, boolean>>({});
+    let oldValue = value;
+    let isUserChange = $state(false);
+    let hasFocus = $state(false);
+
+    // 根据 value 生成 checkbox 状态
+    const generateCheckboxStates = () => {
+        const states: Record<string, boolean> = {};
+
+        if (bitBase) {
+            const numValue = utils.getNumberValue(value) ?? 0;
+            options.forEach((option, index) => {
+                states[option[keyField]] = ((numValue >> index) & 1) === 1;
+            });
+        } else {
+            const strValue = utils.getStringValue(value) ?? '';
+            const selectedList = strValue === '' ? [] : strValue.split(delimiter);
+            options.forEach((option) => {
+                states[option[keyField]] = selectedList.includes(option[keyField]);
+            });
+        }
+
+        checkboxStates = states;
+    };
+
+    // 监听 value 变化，更新 checkbox 状态
+    $effect(() => {
+        generateCheckboxStates();
+    });
+
+    // 处理 checkbox 变化
+    const handleCheckboxChange = (key: string) => (checked: boolean) => {
+        isUserChange = true;
+        checkboxStates[key] = checked;
+
+        if (bitBase) {
+            let v = 0;
+            options.forEach((option, index) => {
+                if (checkboxStates[option[keyField]]) {
+                    v += (1 << index);
+                }
+            });
+            value = v;
+        } else {
+            const selectedList = options
+                .filter(option => checkboxStates[option[keyField]])
+                .map(option => option[keyField]);
+            value = selectedList.length === 0 ? '' : selectedList.join(delimiter);
+        }
+    };
+
+    // 处理 onchange 事件
+    $effect(() => {
+        if (oldValue !== value) {
+            if (isUserChange) {
+                onchange?.(value);
+                isUserChange = false;
+            }
+            oldValue = value;
+            error = undefined;
+        }
+    });
+
+    // 处理 focus/blur 事件
+    const handleFocus = (e: FocusEvent) => {
+        if (!hasFocus) {
+            hasFocus = true;
+            onfocus?.(e);
+        }
+    };
+
+    const handleBlur = (e: FocusEvent) => {
+        if (hasFocus) {
+            hasFocus = false;
+            onblur?.(e);
+        }
+    };
+
+    const handleContainerClick = (e: MouseEvent) => {
+        if (!disabled && !readonly && e.target === groupContainer) {
+            handleFocus(new FocusEvent('focus'));
+            focus();
+        }
+    };
+
+    const handleContainerBlur = (e: FocusEvent) => {
+        // relatedTarget 是即将获得焦点的元素
+        // 如果它仍然在容器内，则不触发 onblur
+        const relatedTarget = e.relatedTarget as HTMLElement;
+        if (!groupContainer?.contains(relatedTarget)) {
+            handleBlur(e);
+        }
+    };
+
+    // 导出 focus 方法
+    export function focus() {
+        const firstCheckbox = groupContainer?.querySelector('input[type="checkbox"]:not(:disabled)') as HTMLInputElement;
+        if (firstCheckbox) {
+            firstCheckbox.focus();
+        }
+    }
+</script>
+
+<FormEditor
+        {variant}
+        {disabled}
+        {error}
+        {tooltip}
+        {readonly}
+        {compact}
+        {style}
+        class={className}
+>
+    <!-- onclick only forwards focus to the first checkbox when the container's
+         own background is clicked; each CheckBox inside is independently
+         focusable/keyboard-operable, so this isn't an additional action. -->
+    <!-- svelte-ignore a11y_click_events_have_key_events -->
+    <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+    <div bind:this={groupContainer} class="group-check-box" class:compact onfocusout={handleContainerBlur} onclick={handleContainerClick}
+         role="group">
+        {#each options as op}
+            {#if (hideOptions ?? []).indexOf(op[keyField]) === -1}
+                <CheckBox
+                        {compact}
+                        {readonly}
+                        disabled={disabled || disabledOptions.indexOf(op[keyField]) > -1}
+                        label={op[textField]}
+                        style={item$style}
+                        bind:value={checkboxStates[op[keyField]]}
+                        onchange={handleCheckboxChange(op[keyField])}
+                        onfocus={handleFocus}
+                />
+            {/if}
+        {/each}
+    </div>
+</FormEditor>
+
+<style>
+    .group-check-box {
+        user-select: none;
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+        height: 38px;
+        padding: 0 6px;
+    }
+
+    .group-check-box.compact {
+        height: 26px;
+    }
+</style>
+

package/dist/form/group_box/group-check-box/GroupCheckBox.svelte.d.ts

@@ -0,0 +1,32 @@
+import type { EditorVariant } from "../../types";
+interface OptionItem {
+    [key: string]: any;
+}
+interface Props {
+    disabled?: boolean;
+    readonly?: boolean;
+    style?: string;
+    error?: string;
+    tooltip?: string;
+    value: string | number;
+    bitBase?: boolean;
+    options: Array<OptionItem>;
+    keyField?: string;
+    textField?: string;
+    delimiter?: string;
+    /** 每个选项的内联样式 */
+    item$style?: string;
+    disabledOptions?: Array<string>;
+    hideOptions?: Array<string>;
+    variant?: EditorVariant;
+    compact?: boolean;
+    class?: string;
+    onchange?: (value: any) => void;
+    onblur?: (event: FocusEvent) => void;
+    onfocus?: (event: FocusEvent) => void;
+}
+declare const GroupCheckBox: import("svelte").Component<Props, {
+    focus: () => void;
+}, "value">;
+type GroupCheckBox = ReturnType<typeof GroupCheckBox>;
+export default GroupCheckBox;