@ticatec/topside-elements 1.0.0

package/dist/data_display/concise_data_table/README_CN.md

@@ -0,0 +1,177 @@
+# ConciseListTable 简洁数据表
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `RowClickHandler`, `rowClickHandler`, `setFocus` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+**只用于展示** 的轻量表格：固定列、可选跑马灯自动滚动、交替行配色。不支持排序、调整列宽、选择 —— 那些功能请用完整的 `DataTable`。
+
+> Svelte 5 组件。表格填满父容器（100% × 100%），父容器必须给出明确高度。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```svelte
+<script lang="ts">
+  import ConciseListTable from '@ticatec/topside-elements/ConciseDataTable';
+  import type { Column, TableOptions, OnRowClick } from '@ticatec/topside-elements/ConciseDataTable';
+</script>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `list` | `Array<any>` | — | 必填。要渲染的行 |
+| `columns` | `Array<Column>` | — | 必填。列定义 |
+| `options` | `TableOptions` | `{}` | 视觉选项（行高、配色等）。缺省 `headerHeight=36`、`rowHeight=32` |
+| `autoScroll` | `boolean` | `false` | 跑马灯自动滚动。开启后会把 list **连续渲染 3 次**，用 CSS `translateY` 关键帧无缝循环 |
+| `scrollInterval` | `number` | `2000` | 每行停留的毫秒数（动画总时长 = `scrollInterval × list.length`） |
+| `onRowClick` | `(row: any) => void \| null` | `null` | 行点击回调 |
+| `style` | `string` | `''` | 根节点内联 CSS |
+| `class` | `string` | `''` | 根节点附加 class |
+| `onfocus` | `(e: FocusEvent) => void` | `undefined` | 通过 `focusin` 转发 |
+| `onblur` | `(e: FocusEvent) => void` | `undefined` | 通过 `focusout` 转发 |
+
+### `Column`
+
+```ts
+interface Column {
+  title: string;                          // 标题
+  field: string;                          // 行数据上的属性名
+  width: number;                          // 基础宽度（px），一定会保留
+  align?: 'left' | 'center' | 'right';    // 单元格文字对齐，默认 'left'
+  weight?: number;                        // 剩余水平空间的分配权重（默认 0 = 固定宽度）
+  formatter?: (value: any) => string;     // 渲染前对原始值做转换
+  escapeHTML?: boolean;                   // 为 true 时 formatter 输出按 HTML 渲染（{@html}）；默认纯文本
+}
+```
+
+**宽度算法**（见 `utils.ts`）：每列实际宽度 = `col.width + col.weight × ((viewWidth − Σ col.width) / Σ col.weight)`。所有列都不设 weight 时各列保持固定 `width`，右侧剩余空间留白。
+
+### `TableOptions`
+
+全部可选。不传则用 `headerHeight=36`、`rowHeight=32` 以及 CSS 变量默认配色。
+
+```ts
+interface TableOptions {
+  backgroundColor?: string;            // 根背景色
+  color?: string;                       // 根文字色
+  headerHeight?: number;                // 标题行高（px）
+  headerBackgroundColor?: string;
+  headerColor?: string;
+  rowHeight?: number;                   // 数据行高（px）—— 仅传它时也会作用于标题行
+  alternativeBackgroundColor?: string;  // 偶数行背景
+  alternativeColor?: string;            // 偶数行文字色
+}
+```
+
+## 示例
+
+### 基础
+
+```svelte
+<script lang="ts">
+  import ConciseListTable from '@ticatec/topside-elements/ConciseDataTable';
+  import type { Column } from '@ticatec/topside-elements/ConciseDataTable';
+
+  const columns: Column[] = [
+    { title: '姓名', field: 'name', width: 150 },
+    { title: '年龄', field: 'age', width: 80, align: 'center' },
+  ];
+
+  const list = [
+    { name: 'Alice', age: 30 },
+    { name: 'Bob', age: 25 },
+  ];
+</script>
+
+<div style="height: 320px;">
+  <ConciseListTable {list} {columns} />
+</div>
+```
+
+### 加权列 + formatter
+
+两个有权重的列按 1:2 分剩余空间；100px 的状态列保持固定。
+
+```svelte
+<script lang="ts">
+  import ConciseListTable from '@ticatec/topside-elements/ConciseDataTable';
+  import type { Column, TableOptions } from '@ticatec/topside-elements/ConciseDataTable';
+
+  const columns: Column[] = [
+    { title: '商品', field: 'product', width: 120, weight: 1 },
+    { title: '描述', field: 'desc',    width: 120, weight: 2 },
+    { title: '状态', field: 'status',  width: 100, align: 'center',
+      formatter: (v: string) => v === 'available' ? '✅ 有货' : '❌ 缺货' },
+  ];
+
+  const options: TableOptions = {
+    headerHeight: 40,
+    rowHeight: 36,
+    alternativeBackgroundColor: '#f8fafc',
+  };
+
+  const products = [
+    { product: '笔记本',  desc: '14 寸超薄本',  status: 'available' },
+    { product: '鼠标',    desc: '无线',         status: 'out' },
+  ];
+
+  const onRowClick = (row: any) => console.log('clicked', row);
+</script>
+
+<div style="height: 400px;">
+  <ConciseListTable list={products} {columns} {options} {onRowClick} />
+</div>
+```
+
+### 跑马灯（大屏自动滚动）
+
+```svelte
+<div style="height: 280px;">
+  <ConciseListTable list={longList} columns={columns} autoScroll scrollInterval={2000} />
+</div>
+```
+
+`autoScroll` 开启时：
+- list 会**连续渲染 3 次**，跑马灯循环时看不到接缝
+- 数据区 `overflow-y` 被隐藏，不能手动滚动
+- `list` / `autoScroll` / `scrollInterval` 变化时动画会被销毁重建
+- 如果所有行都能在视口里放下（`list.length ≤ visibleRowCount`），**不会**启动动画
+
+## 样式定制
+
+SCSS 中消费的 CSS 变量（在根或任意祖先覆盖）：
+
+| 变量 | 用处 |
+|------|------|
+| `--topside-concise-table-bg` | 根文字色回退 |
+| `--topside-concise-table-row-alter-bg` | 交替行背景（默认 `#F8FAFC`） |
+| `--topside-concise-table-row-alter-color` | 交替行文字色（默认 `#374151`） |
+
+一次性主题化建议用 `options`（会按唯一 `#tab_{id}` 前缀生成作用域 CSS）；CSS 变量留给全局默认值。
+
+## 命令式 API
+
+`focus()` 暴露在组件实例上，通过 `bind:this` 调用：
+
+```svelte
+<script lang="ts">
+  let table: ConciseListTable;
+  // table.setFocus()
+</script>
+
+<ConciseListTable bind:this={table} {list} {columns} />
+```
+
+内部用 50ms 延迟把焦点切到第一行 body row。
+
+## 无障碍
+
+- 根节点有 `role="table"` 和 `aria-rowcount={list.length + 1}`
+- 标题单元格 `role="columnheader"`，body 行 `role="row"`
+- 行点击仅支持鼠标 —— 没有内置键盘激活，需要的话自己加

package/dist/data_display/concise_data_table/TableOptions.d.ts

@@ -0,0 +1,11 @@
+export interface TableOptions {
+    backgroundColor?: string;
+    color?: string;
+    headerHeight?: number;
+    headerBackgroundColor?: string;
+    headerColor?: string;
+    alternativeBackgroundColor?: string;
+    alternativeColor?: string;
+    rowHeight?: number;
+}
+export type OnRowClick = (row: any) => void;

package/dist/data_display/concise_data_table/TableOptions.js

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

package/dist/data_display/concise_data_table/index.d.ts

@@ -0,0 +1,5 @@
+import ConciseListTable from "./ConciseListTable.svelte";
+import type Column from "./Column";
+import type { TableOptions } from "./TableOptions";
+export default ConciseListTable;
+export type { Column, TableOptions };

package/dist/data_display/concise_data_table/index.js

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

package/dist/data_display/concise_data_table/utils.d.ts

@@ -0,0 +1,6 @@
+import type Column from "./Column";
+import type { TableOptions } from "./TableOptions";
+declare const _default: {
+    generateTableStyle: (id: string, columns: Array<Column>, options: TableOptions, viewWidth: number) => string;
+};
+export default _default;

package/dist/data_display/concise_data_table/utils.js

@@ -0,0 +1,38 @@
+const generateBlockStyle = (prefix, options, keys) => {
+    let style = '';
+    keys.forEach(key => {
+        if (options[key.code]) {
+            style += `${key.attr}: ${options[key.code]}${key.suffix ?? ''};\n`;
+        }
+    });
+    if (style.length > 0) {
+        return `${prefix} { ${style} }`;
+    }
+    else {
+        return '';
+    }
+};
+/**
+ *
+ * @param id
+ * @param columns
+ * @param options
+ * @param viewWidth
+ */
+const generateTableStyle = (id, columns, options, viewWidth) => {
+    let style = '';
+    if (options && columns) {
+        style += generateBlockStyle(`#tab_${id}`, options, [{ code: 'backgroundColor', attr: 'background-color' }, { code: 'color', attr: 'color' }]);
+        style += generateBlockStyle(`#tab_${id} .table-row.alternative `, options, [{ code: 'alternativeBackgroundColor', attr: 'background-color' }, { code: 'alternativeColor', attr: 'color' }]);
+        style += generateBlockStyle(`#tab_${id} .table-header .table-row `, options, [{ code: 'headerBackgroundColor', attr: 'background-color' }, { code: 'headerColor', attr: 'color' }, { code: 'headerHeight', attr: 'height', suffix: 'px' }]);
+        style += generateBlockStyle(`#tab_${id} .table-body .table-row`, options, [{ code: 'headerHeight', attr: 'height', suffix: 'px' }]);
+        let totalWeight = columns.reduce((sum, col) => sum + (col.weight || 0), 0);
+        let tabWidth = columns.reduce((sum, col) => sum + col.width, 0);
+        let diff = (viewWidth - tabWidth) / totalWeight;
+        columns.forEach((col, idx) => {
+            style += `#tab_${id} .col_${idx} {\n width: ${col.width + (col.weight ?? 0) * diff}px; \n text-align: ${col.align ?? 'left'};} \n`;
+        });
+    }
+    return `<style>${style}</style>`;
+};
+export default { generateTableStyle };

package/dist/data_display/list_box/ListBox.svelte

@@ -0,0 +1,424 @@
+<script lang="ts">
+    import {tick, onDestroy, untrack} from "svelte";
+    import SearchBox from "../../form/search_box"
+    import type {FilterFn} from "../../types";
+    import type {ListLazyLoader} from "../../types";
+    import CheckBox from "../../form/checkbox/CheckBox.svelte";
+    import loading from "../../assets/loading.gif"
+
+    type OnSelectChange = (item: any) => void;
+    type OnItemDblClick = (item: any) => void;
+    type OnItemClick = (item: any) => void;
+
+    interface Props {
+        readonly?: boolean;
+        style?: string;
+        list?: Array<any>;
+        itemRender?: any;
+        selectMode?: 'none' | 'single' | 'multiple';
+        filter?: FilterFn | null;
+        lazyLoader?: ListLazyLoader | null;
+        selectedItem?: any;
+        /** 多选模式下的已选项 */
+        selectedItems?: Array<any>;
+        class?: string;
+        item$props?: any;
+        onchange?: OnSelectChange;
+        onItemDblClick?: OnItemDblClick;
+        onItemClick?: OnItemClick;
+        title?: string;
+        round?: boolean;
+        filterText?: string;
+        header?: any;
+        footer?: any;
+        loadMoreIndicator?: any;
+    }
+
+    let {
+        readonly = false,
+        style,
+        list,
+        itemRender: ItemRender,
+        selectMode = 'none',
+        filter,
+        lazyLoader,
+        selectedItem,
+        selectedItems = $bindable([]),
+        class: className,
+        item$props,
+        onchange,
+        onItemDblClick,
+        onItemClick,
+        title,
+        round = false,
+        filterText,
+        header,
+        footer,
+        loadMoreIndicator
+    }: Props = $props();
+
+    // External values are synchronized by the effects below. Neutral initial values
+    // avoid implying that these props are intentionally captured only once.
+    let localSelectedItem = $state<any>(null);
+    let localSelectedList = $state<Array<any>>([]);
+    let localFilterText = $state('');
+
+    let hasMore = $state(false);
+    let isBusy = $state(false);
+    let pageNo = $state(1);
+    let filteredList = $state<Array<any>>([]);
+
+    let scrollElement: HTMLElement;
+    let searchBox = $state<any>();
+
+    // Sync external props to local state
+    $effect(() => {
+        localSelectedItem = selectedItem ?? null;
+    });
+
+    $effect(() => {
+        localSelectedList = selectedItems ?? [];
+    });
+
+    $effect(() => {
+        localFilterText = filterText ?? '';
+    });
+
+    const notifySelectChange = (item: any) => {
+        onchange?.(item);
+    };
+
+    const handleItemClick = (item: any) => (e: MouseEvent) => {
+        if (readonly == false) {
+            if (selectMode == 'single') {
+                if (localSelectedItem != item) {
+                    localSelectedItem = item;
+                    notifySelectChange(item);
+                }
+            } else {
+                onItemClick?.(item);
+            }
+        }
+    }
+
+    const handleItemDblClick = (item: any) => (e: MouseEvent) => {
+        if (selectMode == 'single') {
+            onItemDblClick?.(item);
+        }
+    }
+
+    const handleItemKeyDown = (item: any) => (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            handleItemClick(item)(e as unknown as MouseEvent);
+        }
+    }
+
+    const doFilter = () => {
+        const newList: Array<any> = [];
+        list?.forEach(item => {
+            if (filter?.(item, localFilterText)) {
+                newList.push(item)
+            }
+        });
+        // Assign once after the loop: when `list` is empty (or becomes empty), forEach
+        // never runs, so assigning inside the loop body left the previous, stale
+        // filteredList in place instead of clearing it to an empty result.
+        filteredList = newList;
+        if (selectMode == 'single') {
+            localSelectedItem = null;
+            notifySelectChange(null);
+        }
+    }
+
+    // Guards against out-of-order responses: only the most recently issued
+    // request is allowed to write its result into component state.
+    let lazyLoadSeq = 0;
+    let destroyed = false;
+
+    const lazyLoad = async (clean: boolean = true) => {
+        const seq = ++lazyLoadSeq;
+        isBusy = true;
+        try {
+            let result = await lazyLoader?.(localFilterText, pageNo);
+            if (destroyed || seq !== lazyLoadSeq) {
+                return;
+            }
+            if (result) {
+                if (clean) {
+                    list = result.list;
+                } else {
+                    list = [...(list ?? []), ...result.list];
+                }
+                localSelectedItem = null;
+                filteredList = list ?? [];
+                hasMore = result.hasMore;
+            }
+        } catch (e) {
+            if (!clean) {
+                // Failed page-2+ fetch: undo the optimistic pageNo increment so a
+                // retry (e.g. re-triggered by scroll) re-requests the same page.
+                pageNo--;
+            }
+            throw e;
+        } finally {
+            if (!destroyed && seq === lazyLoadSeq) {
+                isBusy = false;
+            }
+        }
+    }
+
+    let idleTime = 0;
+    let interval: any = null;
+
+    const delayReload = async () => {
+        idleTime++;
+        if (idleTime > 10) {
+            clearInterval(interval);
+            interval = null;
+            pageNo = 1;
+            scrollElement.scrollTop = 0;
+            try {
+                await lazyLoad();
+            } catch (e) {
+                console.error('ListBox: failed to reload items', e);
+            }
+            if (!destroyed) {
+                await tick();
+                searchBox?.focus();
+            }
+        }
+    }
+
+    onDestroy(() => {
+        destroyed = true;
+        if (interval != null) {
+            clearInterval(interval);
+            interval = null;
+        }
+    });
+
+    const handleCriteriaChange = () => {
+        if (lazyLoader != null) {
+            if (interval == null) {
+                idleTime = 0;
+                interval = setInterval(delayReload, 50)
+            } else {
+                idleTime = 0;
+            }
+
+        } else {
+            if (localFilterText.length > 0) {
+                doFilter();
+            } else {
+                filteredList = [...(list ?? [])]
+            }
+        }
+    }
+
+    $effect(() => {
+        if (list && lazyLoader == null) {
+            if (filter != null && localFilterText && localFilterText.length > 0) {
+                doFilter();
+            } else {
+                filteredList = list;
+            }
+        }
+    });
+
+    const handleSelectionChanged = (item: any) => () => {
+        let idx = localSelectedList.indexOf(item);
+        if (idx < 0) {
+            localSelectedList = [...localSelectedList, item];
+        } else {
+            localSelectedList.splice(idx, 1);
+            localSelectedList = [...localSelectedList];
+        }
+        // Write the selection back through the two-way binding (regression: bind:selectedList
+        // never received updates, which left Transfer's move buttons dead).
+        selectedItems = localSelectedList;
+    }
+
+    // untrack: lazyLoad() reads pageNo/isBusy/localFilterText synchronously
+    // before its first await. Without untrack, those reads register as
+    // dependencies of *this* effect, so a later change to pageNo (e.g. from
+    // fetchMore) would re-run this effect and fire a second, unrelated
+    // "initial load" — this must only re-run when the lazyLoader prop itself
+    // changes.
+    $effect(() => {
+        if (lazyLoader != null) {
+            untrack(() => {
+                lazyLoad().catch((e) => console.error('ListBox: failed to load items', e));
+            });
+        }
+    });
+
+    const fetchMore = async () => {
+        pageNo++;
+        try {
+            await lazyLoad(false);
+        } catch (e) {
+            console.error('ListBox: failed to load more items', e);
+        }
+    }
+
+    const handleScroll = () => {
+        const bottom = scrollElement.scrollHeight - scrollElement.scrollTop - scrollElement.clientHeight < 2;
+        if (bottom && lazyLoader && !isBusy && hasMore) {
+            fetchMore();
+        }
+    }
+
+</script>
+
+<div {style} class="topside-listbox {className}" class:round>
+    {#if title || header}
+        <div class="box-header">
+            {#if header}
+                {@render header()}
+            {:else}
+                {#if title}
+                    <div class="title">
+                        <span>{title}</span>
+                    </div>
+                {/if}
+            {/if}
+        </div>
+    {/if}
+    {#if readonly === false && (filter || lazyLoader)}
+        <div class="header-search">
+            <SearchBox bind:this={searchBox} compact disabled={isBusy} style="width: 100%" bind:value={localFilterText}
+                       onchange={handleCriteriaChange}/>
+        </div>
+    {/if}
+    <div class="listbox-content" class:selectable={selectMode==='single'} bind:this={scrollElement} onscroll={handleScroll}
+         role="listbox" aria-multiselectable={selectMode === 'multiple' ? true : undefined}>
+        {#if filteredList && ItemRender}
+            {#each filteredList as item}
+                {#if selectMode === "multiple"}
+                    <div class="listview-item" style="display: flex; flex-direction: row; align-items: center; gap: 8px"
+                         role="option" aria-selected={localSelectedList.indexOf(item) > -1}>
+                        <CheckBox style="flex: 0 0 auto; margin-left: 8px" {readonly} value={localSelectedList.indexOf(item) > -1}
+                                  onchange={handleSelectionChanged(item)}/>
+                        <div style="flex: 1 1 auto; cursor: pointer" role="button" tabindex="0"
+                             onclick={handleSelectionChanged(item)}
+                             onkeydown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); handleSelectionChanged(item)(); } }}>
+                            <ItemRender {readonly} {item} {...item$props}/>
+                        </div>
+                    </div>
+                {:else }
+                    <div class="listview-item" class:selected={item===localSelectedItem}
+                         role="option" aria-selected={item===localSelectedItem} tabindex="0"
+                         ondblclick={handleItemDblClick(item)} onclick={handleItemClick(item)} onkeydown={handleItemKeyDown(item)}>
+                        <ItemRender {item} {readonly} selected={item===localSelectedItem}
+                                    {...item$props}/>
+                    </div>
+                {/if}
+            {/each}
+        {/if}
+        {#if hasMore && loadMoreIndicator}
+            {@render loadMoreIndicator()}
+        {/if}
+    </div>
+    {#if footer}
+        <div class="box-footer flex-container">
+            {@render footer()}
+        </div>
+    {/if}
+    {#if isBusy}
+        <div class="list-view-mask">
+            <div style="height: 100%; text-align: center">
+                <img width="48" height="48" style="position: relative; top: 50%; transform: translateY(-50%)" src={loading} alt="nothing">
+            </div>
+        </div>
+    {/if}
+</div>
+
+<style>
+    .topside-listbox {
+        position: relative;
+        display: flex;
+        flex-direction: column;
+        overflow: hidden;
+        box-sizing: border-box;
+        user-select: none;
+        border: 1px solid var(--topside-list-box-border-color);
+        background-color: var(--topside-list-box-color-surface);
+        color: var(--topside-list-box-color);
+    }
+
+    .topside-listbox.round {
+        border-radius: var(--topside-radius, 4px);
+    }
+
+    .list-view-mask {
+        width: 100%;
+        height: 100%;
+        position: absolute;
+        top: 0;
+        left: 0;
+        background-color: var(--topside-color-overlay-mask-surface);
+    }
+
+    .box-header {
+        flex: 0 0 auto;
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+        gap: 8px;
+        padding: var(--topside-list-box-header-margin);
+        background-color: var(--topside-list-box-header-surface, #F8FAFC);
+        height: var(--topside-list-box-header-height);
+        border-bottom: var(--topside-list-box-header-bottom-border);
+    }
+
+    .box-header .title {
+        font-weight: 600;
+        padding: 0 8px;
+    }
+
+    .header-search {
+        flex: 0 0 auto;
+        width: 100%;
+    }
+
+    .box-footer {
+        border-top: var(--topside-list-box-fotter-top-border);
+        background-color: var(--topside-list-box-footer-surface);
+        height: auto;
+    }
+
+    .box-footer.flex-container {
+        display: flex;
+    }
+
+    .listbox-content {
+        width: 100%;
+        height: 100%;
+        box-sizing: border-box;
+        overflow-y: auto;
+        overflow-x: hidden;
+        flex: 1 1 auto;
+    }
+
+    .listbox-content .listview-item {
+        border-bottom: 1px solid var(--topside-listbox-separator-color);
+    }
+
+    .listbox-content.selectable .listview-item {
+        cursor: pointer;
+    }
+
+    .listbox-content.selectable .listview-item:hover {
+        background-color: var(--topside-list-box-hover-surface);
+    }
+
+    .listbox-content.selectable .listview-item.selected {
+        background-color: var(--topside-list-box-selected-surface);
+    }
+
+    .listbox-content .listview-item:focus-visible {
+        outline: 2px solid var(--topside-primary-border-color, #298DFF);
+        outline-offset: -2px;
+    }
+</style>