@ticatec/topside-elements 1.0.0

package/dist/form/number_range/README_CN.md

@@ -0,0 +1,488 @@
+# NumberRange 数字范围
+
+用于指定数字范围的双数字输入组件，具有自动验证功能，确保"起始"值不超过"结束"值。
+
+## 功能特性
+
+- **范围输入**: 两个连接的数字输入框，用于"起始"和"结束"值。
+- **自动验证**: 确保逻辑范围顺序（起始 ≤ 结束）。
+- **负数支持**: 可选的负数值支持。
+- **边界约束**: 为整个范围设置最小/最大限制。
+- **多种变体**: 支持轮廓、填充、朴素和默认样式。
+- **紧凑模式**: 用于密集表单的节省空间布局。
+- **清除功能**: 内置清除按钮，可分别重置起始或结束值。
+- **实时验证**: 输入过程中的即时反馈。
+- **焦点管理**: 输入框之间的自动焦点处理。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import NumberRange from "@ticatec/topside-elements/NumberRange";
+```
+
+## 基础用法
+
+```svelte
+<script>
+  import NumberRange from "@ticatec/topside-elements/NumberRange";
+
+  let fromValue = 10;
+  let toValue = 50;
+</script>
+
+<NumberRange bind:fromValue={fromValue} bind:toValue={toValue} />
+```
+
+## 属性（Props）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `fromValue` | `number \| undefined` | `undefined` | 范围的"起始"（最小）值（可双向绑定）。 |
+| `toValue` | `number \| undefined` | `undefined` | 范围的"结束"（最大）值（可双向绑定）。 |
+| `min` | `number \| undefined` | `undefined` | 两个输入框的最小允许值。 |
+| `max` | `number \| undefined` | `undefined` | 两个输入框的最大允许值。 |
+| `allowNegative` | `boolean` | `false` | 允许两个输入框输入负数。 |
+| `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 类名。 |
+
+## 示例
+
+### 基本范围选择
+
+```svelte
+<script>
+  import NumberRange from "@ticatec/topside-elements/NumberRange";
+
+  let ageFrom = 18;
+  let ageTo = 65;
+</script>
+
+<NumberRange
+  bind:fromValue={ageFrom}
+  bind:toValue={ageTo}
+  variant="outlined"
+  min={0}
+  max={120}
+/>
+```
+
+### 价格范围过滤器
+
+```svelte
+<script>
+  import NumberRange from "@ticatec/topside-elements/NumberRange";
+
+  let priceMin = 100;
+  let priceMax = 1000;
+
+  $: console.log(`价格范围: ¥${priceMin} - ¥${priceMax}`);
+</script>
+
+<div class="price-filter">
+  <label>价格范围 (¥)</label>
+  <NumberRange
+    bind:fromValue={priceMin}
+    bind:toValue={priceMax}
+    variant="filled"
+    min={0}
+    max={10000}
+  />
+  <div class="range-display">
+    ¥{priceMin || 0} - ¥{priceMax || 0}
+  </div>
+</div>
+
+<style>
+  .price-filter {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+  .range-display {
+    font-size: 0.875rem;
+    color: #6b7280;
+    text-align: right;
+  }
+</style>
+```
+
+### 温度范围（支持负值）
+
+```svelte
+<script>
+  import NumberRange from "@ticatec/topside-elements/NumberRange";
+
+  let tempMin = -10;
+  let tempMax = 25;
+</script>
+
+<div class="temperature-range">
+  <label>温度范围 (°C)</label>
+  <NumberRange
+    bind:fromValue={tempMin}
+    bind:toValue={tempMax}
+    variant="outlined"
+    allowNegative={true}
+    min={-50}
+    max={50}
+  />
+</div>
+
+<style>
+  .temperature-range {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+  label {
+    font-weight: 500;
+  }
+</style>
+```
+
+### 搜索条件表单
+
+```svelte
+<script>
+  import NumberRange from "@ticatec/topside-elements/NumberRange";
+
+  let criteria = {
+    salaryFrom: null,
+    salaryTo: null,
+    experienceFrom: 0,
+    experienceTo: 10,
+    ageFrom: 22,
+    ageTo: 60
+  };
+
+  function handleSearch() {
+    console.log("搜索条件:", criteria);
+  }
+</script>
+
+<div class="search-form">
+  <div class="form-group">
+    <label>薪资范围</label>
+    <NumberRange
+      bind:fromValue={criteria.salaryFrom}
+      bind:toValue={criteria.salaryTo}
+      variant="outlined"
+      min={0}
+      max={500000}
+    />
+  </div>
+
+  <div class="form-group">
+    <label>工作年限</label>
+    <NumberRange
+      bind:fromValue={criteria.experienceFrom}
+      bind:toValue={criteria.experienceTo}
+      variant="outlined"
+      min={0}
+      max={50}
+    />
+  </div>
+
+  <div class="form-group">
+    <label>年龄范围</label>
+    <NumberRange
+      bind:fromValue={criteria.ageFrom}
+      bind:toValue={criteria.ageTo}
+      variant="outlined"
+      min={16}
+      max={80}
+    />
+  </div>
+
+  <button onclick={handleSearch}>搜索</button>
+</div>
+
+<style>
+  .form-group {
+    margin-bottom: 16px;
+  }
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+  button {
+    padding: 8px 16px;
+    cursor: pointer;
+  }
+</style>
+```
+
+### 表格紧凑布局
+
+```svelte
+<script>
+  import NumberRange from "@ticatec/topside-elements/NumberRange";
+
+  let filters = [
+    { label: "分数", from: 80, to: 100 },
+    { label: "数量", from: 1, to: 999 },
+    { label: "评级", from: 3, to: 5 }
+  ];
+</script>
+
+<table class="filter-table">
+  <thead>
+    <tr>
+      <th>过滤器</th>
+      <th>范围</th>
+    </tr>
+  </thead>
+  <tbody>
+    {#each filters as filter}
+      <tr>
+        <td>{filter.label}</td>
+        <td>
+          <NumberRange
+            bind:fromValue={filter.from}
+            bind:toValue={filter.to}
+            compact
+            variant="outlined"
+            min={0}
+          />
+        </td>
+      </tr>
+    {/each}
+  </tbody>
+</table>
+
+<style>
+  .filter-table {
+    width: 100%;
+    border-collapse: collapse;
+  }
+  th, td {
+    text-align: left;
+    padding: 8px;
+  }
+</style>
+```
+
+### 带验证的动态范围
+
+```svelte
+<script>
+  import NumberRange from "@ticatec/topside-elements/NumberRange";
+
+  let budgetMin = 1000;
+  let budgetMax = 5000;
+  let isValidRange = true;
+
+  $: isValidRange = budgetMin <= budgetMax;
+  $: rangeSize = budgetMax - budgetMin;
+
+  function resetRange() {
+    budgetMin = 1000;
+    budgetMax = 5000;
+  }
+</script>
+
+<div class="budget-selector">
+  <label>预算范围</label>
+  <NumberRange
+    bind:fromValue={budgetMin}
+    bind:toValue={budgetMax}
+    variant="outlined"
+    min={0}
+    max={100000}
+  />
+
+  <div class="range-info" class:error={!isValidRange}>
+    {#if isValidRange}
+      <span>范围大小: ¥{rangeSize}</span>
+    {:else}
+      <span>无效范围: 最小值不能超过最大值</span>
+    {/if}
+  </div>
+
+  <button onclick={resetRange}>重置</button>
+</div>
+
+<style>
+  .budget-selector {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  label {
+    font-weight: 500;
+  }
+  .range-info.error {
+    color: #d32f2f;
+  }
+</style>
+```
+
+### 统计分析范围
+
+```svelte
+<script>
+  import NumberRange from "@ticatec/topside-elements/NumberRange";
+
+  let dataRange = { min: -100, max: 100 };
+  let outlierThreshold = { from: -50, to: 50 };
+
+  $: normalDataPercentage = calculateNormalData(dataRange, outlierThreshold);
+
+  function calculateNormalData(range, threshold) {
+    const totalRange = range.max - range.min;
+    const normalRange = threshold.to - threshold.from;
+    return ((normalRange / totalRange) * 100).toFixed(1);
+  }
+</script>
+
+<div class="analysis-panel">
+  <h3>数据分析</h3>
+
+  <div class="range-control">
+    <label>数据范围</label>
+    <NumberRange
+      bind:fromValue={dataRange.min}
+      bind:toValue={dataRange.max}
+      variant="filled"
+      allowNegative={true}
+      min={-1000}
+      max={1000}
+    />
+  </div>
+
+  <div class="range-control">
+    <label>正常范围（排除异常值）</label>
+    <NumberRange
+      bind:fromValue={outlierThreshold.from}
+      bind:toValue={outlierThreshold.to}
+      variant="outlined"
+      allowNegative={true}
+      min={dataRange.min}
+      max={dataRange.max}
+    />
+  </div>
+
+  <div class="statistics">
+    <p>正常数据覆盖率: {normalDataPercentage}%</p>
+  </div>
+</div>
+
+<style>
+  .analysis-panel {
+    max-width: 500px;
+  }
+  .range-control {
+    margin-bottom: 16px;
+  }
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+</style>
+```
+
+### 库存管理
+
+```svelte
+<script>
+  import NumberRange from "@ticatec/topside-elements/NumberRange";
+
+  let stockLevels = {
+    lowStock: 0,
+    highStock: 100,
+    reorderFrom: 10,
+    reorderTo: 90
+  };
+
+  $: isValidReorderRange = (
+    stockLevels.reorderFrom >= stockLevels.lowStock &&
+    stockLevels.reorderTo <= stockLevels.highStock &&
+    stockLevels.reorderFrom <= stockLevels.reorderTo
+  );
+</script>
+
+<div class="inventory-config">
+  <h3>库存配置</h3>
+
+  <div class="config-row">
+    <label>库存水平范围</label>
+    <NumberRange
+      bind:fromValue={stockLevels.lowStock}
+      bind:toValue={stockLevels.highStock}
+      variant="outlined"
+      min={0}
+      max={10000}
+    />
+  </div>
+
+  <div class="config-row">
+    <label>补货范围</label>
+    <NumberRange
+      bind:fromValue={stockLevels.reorderFrom}
+      bind:toValue={stockLevels.reorderTo}
+      variant="filled"
+      min={stockLevels.lowStock}
+      max={stockLevels.highStock}
+    />
+  </div>
+
+  <div class="validation" class:valid={isValidReorderRange}>
+    {isValidReorderRange ? "✓ 配置有效" : "✗ 补货范围无效"}
+  </div>
+</div>
+
+<style>
+  .config-row {
+    margin-bottom: 16px;
+  }
+  label {
+    display: block;
+    margin-bottom: 4px;
+    font-weight: 500;
+  }
+  .validation {
+    font-weight: 500;
+  }
+  .validation.valid { color: #2e7d32; }
+  .validation:not(.valid) { color: #d32f2f; }
+</style>
+```
+
+## 验证逻辑
+
+NumberRange 组件自动执行逻辑约束：
+
+1. **范围顺序**: "起始"值不能超过"结束"值。
+2. **边界遵守**: 两个值都遵守全局最小/最大约束。
+3. **交叉验证**: 当一个值改变时，必要时另一个值会调整。
+4. **实时反馈**: 在输入过程中进行验证。
+
+## 最佳实践
+
+1. **设置适当的边界**: 使用 min/max 防止不现实的值。
+2. **提供清晰的标签**: 指明范围代表什么。
+3. **处理空状态**: 考虑值为 null 时的情况。
+4. **明智使用紧凑模式**: 在密集布局或表格中。
+5. **验证范围逻辑**: 确保满足业务规则。
+6. **考虑用户工作流**: 用户通常应该先填写哪个输入框。
+7. **提供反馈**: 显示范围计算或验证消息。
+
+## 相关组件
+
+- [NumberEditor](../number_editor/README_CN.md) — 用于单个数字输入。
+- [DateRange](../date_range/README_CN.md) — 用于日期范围选择。

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

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

package/dist/form/number_range/index.js

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

package/dist/form/options_multi_select/OptionsMultiSelect.svelte

@@ -0,0 +1,229 @@
+<script lang="ts">
+
+    import utils from "../../overlay/common/utils";
+    import Tag from "../../general/tag";
+    import type PickerProps from "../common_editor/CommonPickerProps";
+    import {CommonPicker} from "../common_editor";
+    import CheckBox from "../checkbox";
+    import type {KeyboardEvents} from "../events";
+
+
+    interface Props extends PickerProps, KeyboardEvents {
+        menu$height?: number;
+        value?: string;
+        delimiter?: string;
+        options: Array<any>;
+        keyField?: string;
+        textField?: string;
+        emptyText?: string;
+        /** 要渲染但禁用的选项 key 列表 */
+        disabledOptions?: Array<string>;
+        hideOptions?: Array<string>;
+        tagColor?: string;
+        tagVariant?: 'borderless' | 'border' | 'round';
+    }
+
+    let {
+        error,
+        tooltip,
+        style,
+        theme,
+        variant,
+        compact,
+        disabled,
+        clearable,
+        readonly,
+        menu$height = 0,
+        value = $bindable(),
+        delimiter = ';',
+        options,
+        keyField = "code",
+        textField = "text",
+        placeholder,
+        emptyText,
+        disabledOptions = [],
+        hideOptions = [],
+        onchange,
+        onfocus,
+        onblur,
+        tagColor,
+        tagVariant = 'border'
+    }: Props = $props();
+
+
+    export function focus() {
+        setTimeout(() => {
+            editor?.focus();
+        }, 50);
+    }
+
+    let selectedList = $state<Array<string>>([]);
+    let isOpen = $state(false);
+    let hasFocus = $state(false);
+    let editor: HTMLElement | undefined = $state(undefined);
+
+    const getOptionItem = (code: string) => {
+        let item = options.find(el => el[keyField] == code);
+        return item == null ? '' : item[textField];
+    }
+
+
+    const mh = $derived(`height: ${menu$height > 0 ? menu$height + 'px' : 'auto'}`);
+
+    const handleCheckboxChange = (key: string) => (checked: any) => {
+        if (checked) {
+            if (selectedList.indexOf(key) < 0) {
+                selectedList = [...selectedList, key];
+                value = selectedList.length > 0 ? selectedList.join(delimiter) : '';
+            }
+        } else {
+            removeSelectCode(key);
+        }
+        onchange?.(selectedList);
+
+        // 确保焦点状态正确
+        if (!hasFocus) {
+            //editor?.focus();
+        }
+    }
+
+
+    const removeSelectCode = (code: string) => {
+        let pos = selectedList.findIndex(sc => sc == code);
+        if (pos > -1) {
+            selectedList = selectedList.filter(sc => sc !== code);
+            value = selectedList.length > 0 ? selectedList.join(delimiter) : '';
+        }
+    }
+
+    const toggleOption = (key: string) => (event: MouseEvent) => {
+        if (selectedList.indexOf(key) < 0) {
+            selectedList = [...selectedList, key];
+            value = selectedList.length > 0 ? selectedList.join(delimiter) : '';
+        } else {
+            removeSelectCode(key);
+        }
+        onchange?.(selectedList);
+    }
+
+    const removeOption = (code: string) => () => {
+        removeSelectCode(code);
+        onchange?.(selectedList);
+    }
+
+
+
+    const clear = () => {
+        value = '';
+        onchange?.([]);
+    }
+
+    // 当 value 变化时，更新 selectedList
+    $effect(() => {
+        selectedList = utils.isEmpty(value) ? [] : ((value ?? '').toString()).split(delimiter);
+    });
+
+
+    const openPopupLayer = () => {
+        if (!disabled && !readonly && !isOpen) {
+            isOpen = true
+        }
+    }
+
+    const handleEditorKeyDown = (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            openPopupLayer();
+        }
+    };
+
+    const handleOptionKeyDown = (key: string, itemDisabled: boolean) => (e: KeyboardEvent) => {
+        if (!itemDisabled && (e.key === 'Enter' || e.key === ' ')) {
+            e.preventDefault();
+            toggleOption(key)(e as unknown as MouseEvent);
+        }
+    };
+
+    const input$style = "position: absolute; left: 0; top: 0; width: 1px; height: 1px; opacity: 0; pointer-events: none";
+
+</script>
+
+<CommonPicker {variant} {style} {compact} {tooltip} {error} {readonly} {disabled} {theme} {placeholder} {value} {clearable} {clear}
+              bind:expanded={isOpen} {onblur} {onfocus} autoFit {input$style}>
+    <div class="option-field">
+        <div class="options-editor" onclick={openPopupLayer} onkeydown={handleEditorKeyDown} tabindex="0" role="button" aria-haspopup="listbox" aria-expanded={isOpen}>
+            {#if selectedList.length > 0 }
+                {#each selectedList as code}
+                    <Tag style="flex-shrink: 0" size={compact ? 'small' : 'medium'} color={tagColor} variant={tagVariant}
+                         text={getOptionItem(code)}
+                         removable={!readonly && !disabled && !isOpen} ondelete={removeOption(code)}/>
+                {/each}
+            {:else}
+                {#if !readonly && !disabled}
+                    {#if (emptyText ?? '').trim().length > 0}
+                        <span>{emptyText}</span>
+                    {:else if (placeholder ?? '').trim().length > 0}
+                        <span class="placeholder">{placeholder}</span>
+                    {/if}
+                {/if}
+            {/if}
+        </div>
+    </div>
+    {#snippet popup()}
+        <div class="options-popover" style={mh} role="listbox" aria-multiselectable="true">
+            {#each options as op}
+                {#if hideOptions.indexOf(op[keyField]) < 0}
+                    {@const itemDisabled = disabledOptions.indexOf(op[keyField]) > -1}
+                    <div class="option-item" class:disabled={itemDisabled} onclick={itemDisabled ? null : toggleOption(op[keyField])}
+                         onkeydown={handleOptionKeyDown(op[keyField], itemDisabled)}
+                         role="option" tabindex={itemDisabled ? -1 : 0}
+                         aria-selected={selectedList.indexOf(op[keyField])>-1} aria-disabled={itemDisabled}>
+                        <CheckBox style="width: 100%; pointer-events: none" {theme} value={selectedList.indexOf(op[keyField])>-1} disabled={itemDisabled}
+                                  label={op[textField]}/>
+                    </div>
+                {/if}
+            {/each}
+        </div>
+    {/snippet}
+</CommonPicker>
+
+<style>
+    .option-field {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+        user-select: none;
+    }
+
+    .option-item {
+        line-height: unset !important;
+        user-select: none;
+        cursor: pointer;
+    }
+
+    .option-item.disabled {
+        cursor: default;
+    }
+
+    .options-editor {
+        width: 100%;
+        overflow: hidden;
+        position: relative;
+        display: flex;
+        flex-direction: row;
+        gap: 6px;
+        flex: 1 1 auto;
+    }
+
+    .options-editor:focus {
+        outline: none;
+    }
+
+    .options-editor .placeholder {
+        color: var(--topside-editor-color-placeholder);
+    }
+
+</style>