@ticatec/topside-elements 1.0.6 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.1.0
+
+### 新增
+- **DataTable 行展开重做（`rowExpansion` 属性）**：展开区组件、触发方式与控制方式分离。`showToggle`（默认 true）控制指示列的展开图标；`trigger: 'click' | 'dblclick'` 整行单击 / 双击切换（点到按钮、链接、输入框不触发）；`isExpandable` 限制可展开行；`onExpandChange` 回调。
+- **组件方法**：`expandRow(data)` / `collapseRow(data?)` / `toggleRowExpand(data)` / `isRowExpanded(data)` / `getExpandedRow()`，操作列按钮、外部按钮都可以借此控制展开。
+- **行内事件请求**：自定义 `render` 单元格 / `ActionCell` / 展开区内部在任意元素上调用 `requestRowExpand(el)` / `requestRowCollapse(el)` / `requestRowToggle(el)`（或自行派发 `ROW_EXPAND_EVENT`），由 DataTable 定位所在行处理，不需要拿到表格实例。
+- **展开区上下文**：展开区组件除 `data` 外还收到 `context: RowExpandContext`——`collapse()` 关闭本行、`actions` 为本行行动作（来自 `actionsColumn.getActions`）、`invoke(label)` 按标签执行行动作，可在展开区里直接做“编辑明细”等操作。
+- 异步 `build` 期间切换到别的行时，过期的结果不再覆盖当前展开行。
+
+### 变更
+- `indicatorColumn.buildInlineComponent` 标记为 `@deprecated`，保留兼容（等价于 `rowExpansion = { build }`）。
+
+### 测试与文档
+- `topside-test-suite`：新增 `tests/elements/data_table/DataTable.expand.test.ts`（17 个用例）；`/test/data/data-table/expand` 演示页扩充为图标 / 双击 + 展开区行动作 / 自定义单元格 + 组件方法三个示例。
+- `data_table/README(_CN).md` 新增「行展开」章节与 `RowExpansion` / `RowExpandContext` 类型说明。
+
 ## 1.0.6
 
 ### 变更

package/dist/data_table/DataTable.svelte

@@ -15,6 +15,13 @@
     import { buildTableSummary } from "./lib/summary";
     import { isSameColumn } from "./lib/TableUtils";
     import i18nRes from "../i18nRes";
+    import type RowExpansion from "./lib/RowExpansion";
+    import {
+        type RowExpandContext,
+        type RowExpandRequest,
+        type RowEventHandlers,
+        isInteractiveTarget
+    } from "./lib/RowExpansion";
 
     interface Props {
         columns: Array<DataColumn>;
@@ -45,6 +52,13 @@
          * 分页场景下用它显示服务端算好的全量合计（数字串会按数字格式化）。
          */
         summaryValues?: Record<string, any> | null;
+        /**
+         * 行展开配置：展开区组件、是否显示指示列图标（默认显示）、整行单击 / 双击触发等。
+         * 不配置图标时可以用组件方法 expandRow / collapseRow / toggleRowExpand，
+         * 或在行内（自定义单元格、操作列、展开区）派发 ROW_EXPAND_EVENT 事件来控制。
+         * 同一时间只展开一行。
+         */
+        rowExpansion?: RowExpansion<T> | null;
     }
 
     let {
@@ -65,6 +79,7 @@
         overscan = 8,
         summaryLabel,
         summaryValues = null,
+        rowExpansion = null,
     }: Props = $props();
 
     const id: string = Math.round(new Date().getTime() + Math.random() * 1000).toString(36);
@@ -78,13 +93,24 @@
     let frozenWidth = $state(0);
     let styleEl: HTMLStyleElement | undefined;
 
-    let expandRow = $state<TableRow | null>(null);
+    let expandedRow = $state<TableRow | null>(null);
     let scrollTop = $state(0);
     let inlineComponent = $state<any>(null);
 
+    // 有效的行展开配置：rowExpansion 优先，兼容旧的 indicatorColumn.buildInlineComponent
+    let expansion = $derived.by<RowExpansion<T> | null>(() => {
+        if (rowExpansion) return rowExpansion;
+        const legacy = indicatorColumn?.buildInlineComponent;
+        return legacy ? { build: legacy } : null;
+    });
+    let expandable = $derived(expansion != null);
+    // 指示列图标：默认显示；需要有 indicatorColumn 才有地方放
+    let showExpandToggle = $derived(expandable && indicatorColumn != null && expansion?.showToggle !== false);
+    let expandTrigger = $derived(expansion?.trigger ?? null);
+
     // Measured by ContentPanel (its scrollable data area); drives the virtual window.
     let viewportHeight = $state(0);
-    let expandIndex = $derived(expandRow ? rows.indexOf(expandRow) : -1);
+    let expandIndex = $derived(expandedRow ? rows.indexOf(expandedRow) : -1);
     // One shared window for all three panels (frozen / content / actions), so the
     // slices they render always cover the same absolute row indices.
     let vwindow = $derived(virtual
@@ -163,7 +189,7 @@
 
     const sortRows = (compareFun: CompareFn, descending: boolean) => {
         if (!table) return;
-        expandRow = null;
+        closeExpanded();
         let oList = list.sort(compareFun);
         table.data = descending ? oList.reverse() : oList;
         rows = table.rows;
@@ -183,15 +209,125 @@
         }
     };
 
-    const onRowExpand = async (row: TableRow) => {
-        if (row == expandRow) {
-            expandRow = null;
-            inlineComponent = null;
+    const isExpandableRow = (row: TableRow): boolean =>
+        expandable && (expansion?.isExpandable?.(row.data) ?? true);
+
+    const closeExpanded = () => {
+        if (expandedRow == null) return;
+        expandedRow = null;
+        inlineComponent = null;
+        expansion?.onExpandChange?.(null);
+    };
+
+    // 异步 build 期间用户可能又点了别的行：只接受最后一次请求的结果
+    let expandSeq = 0;
+    const openRow = async (row: TableRow) => {
+        if (!isExpandableRow(row)) return;
+        const seq = ++expandSeq;
+        const comp = await expansion!.build(row.data);
+        if (seq !== expandSeq) return;
+        inlineComponent = comp;
+        expandedRow = row;
+        expansion?.onExpandChange?.(row.data);
+    };
+
+    /** 切换某行展开状态；expanded 指定目标状态，不传则切换 */
+    const setRowExpanded = async (row: TableRow, expanded?: boolean) => {
+        const isOpen = row === expandedRow;
+        const target = expanded ?? !isOpen;
+        if (target === isOpen) return;
+        if (target) {
+            await openRow(row);
         } else {
-            inlineComponent = await indicatorColumn?.buildInlineComponent?.(row.data);
-            expandRow = row;
+            expandSeq++;
+            closeExpanded();
         }
     };
+
+    const onRowExpand = (row: TableRow) => setRowExpanded(row);
+
+    // 对外方法（bind:this 后调用）用它定位行：按数据对象同一性匹配
+    const findRow = (data: T): TableRow | undefined => rows.find(r => r.data === data);
+
+    /** 展开指定行（按行数据对象匹配）；行不存在或不允许展开时不做任何事 */
+    export async function expandRow(data: T): Promise<void> {
+        const row = findRow(data);
+        if (row) await setRowExpanded(row, true);
+    }
+
+    /** 收起指定行；不传参数则收起当前展开的行 */
+    export function collapseRow(data?: T): void {
+        if (data === undefined) {
+            expandSeq++;
+            closeExpanded();
+            return;
+        }
+        const row = findRow(data);
+        if (row) void setRowExpanded(row, false);
+    }
+
+    /** 切换指定行的展开状态 */
+    export async function toggleRowExpand(data: T): Promise<void> {
+        const row = findRow(data);
+        if (row) await setRowExpanded(row);
+    }
+
+    /** 某行当前是否展开 */
+    export function isRowExpanded(data: T): boolean {
+        return expandedRow != null && expandedRow.data === data;
+    }
+
+    /** 当前展开行的数据，没有则为 null */
+    export function getExpandedRow(): T | null {
+        return expandedRow?.data ?? null;
+    }
+
+    // ---- 行级触发（整行单击 / 双击） ----
+
+    const handleRowClick = (row: TableRow, e: MouseEvent) => {
+        if (expandTrigger !== 'click' || isInteractiveTarget(e)) return;
+        void setRowExpanded(row);
+    };
+
+    const handleRowDblClick = (row: TableRow, e: MouseEvent) => {
+        if (expandTrigger !== 'dblclick' || isInteractiveTarget(e)) return;
+        e.preventDefault();
+        void setRowExpanded(row);
+    };
+
+    // ---- 行内自定义事件：render cell / ActionCell / 操作列 / 展开区内部都可以派发 ----
+
+    const handleExpandRequest = (row: TableRow, e: Event) => {
+        if (!expandable) return;
+        e.stopPropagation();
+        const detail = (e as CustomEvent<RowExpandRequest>).detail;
+        void setRowExpanded(row, detail?.expanded);
+    };
+
+    // 传给展开区组件的上下文
+    let expandContext = $derived.by<RowExpandContext<T> | null>(() => {
+        const row = expandedRow;
+        if (!row) return null;
+        const data = row.data as T;
+        const actions = actionsColumn?.getActions(data) ?? [];
+        return {
+            data,
+            collapse: () => { void setRowExpanded(row, false); },
+            actions,
+            invoke: async (label: string) => {
+                const action = actions.find(a => a.label === label);
+                if (!action || action.disabled) return false;
+                await action.handler(data);
+                return true;
+            }
+        };
+    });
+
+    const rowEvents: RowEventHandlers<TableRow> = {
+        onRowClick: handleRowClick,
+        onRowDblClick: handleRowDblClick,
+        onExpandRequest: handleExpandRequest,
+    };
 </script>
 
 <div id="tab-{id}" {style} class="topside-data-table" class:cell-border={colBorder} class:row-border={rowBorder}>
@@ -204,7 +340,10 @@
                 {orderColumn}
                 {onCellClick}
                 {indicatorColumn}
-                bind:expandRow
+                expandRow={expandedRow}
+                expandable={showExpandToggle}
+                isExpandable={isExpandableRow}
+                {rowEvents}
                 {rowHeight}
                 {headerHeight}
                 {fixedCols}
@@ -227,7 +366,9 @@
             {tabWidth}
             bind:rows
             bind:scrollTop
-            {expandRow}
+            expandRow={expandedRow}
+            {expandContext}
+            {rowEvents}
             {rowHeight}
             {headerHeight}
             {list}
@@ -245,6 +386,6 @@
     {/if}
 
     {#if actionsColumn}
-        <ActionPanel {expandRow} {rowHeight} {headerHeight} {actionsColumn} {rows} {inlineRowHeight} bind:scrollTop {vwindow} showSummary={tableSummary != null} />
+        <ActionPanel expandRow={expandedRow} {rowEvents} {rowHeight} {headerHeight} {actionsColumn} {rows} {inlineRowHeight} bind:scrollTop {vwindow} showSummary={tableSummary != null} />
     {/if}
 </div>

package/dist/data_table/DataTable.svelte.d.ts

@@ -2,6 +2,7 @@ import type DataColumn from "./lib/DataColumn";
 import type ActionsColumn from "./lib/ActionsColumn";
 import type IndicatorColumn from "./lib/IndicatorColumn";
 import type { GetRowFontStyle } from "../types";
+import type RowExpansion from "./lib/RowExpansion";
 declare function $$render<T = any>(): {
     props: {
         columns: Array<DataColumn>;
@@ -32,8 +33,21 @@ declare function $$render<T = any>(): {
          * 分页场景下用它显示服务端算好的全量合计（数字串会按数字格式化）。
          */
         summaryValues?: Record<string, any> | null;
+        /**
+         * 行展开配置：展开区组件、是否显示指示列图标（默认显示）、整行单击 / 双击触发等。
+         * 不配置图标时可以用组件方法 expandRow / collapseRow / toggleRowExpand，
+         * 或在行内（自定义单元格、操作列、展开区）派发 ROW_EXPAND_EVENT 事件来控制。
+         * 同一时间只展开一行。
+         */
+        rowExpansion?: RowExpansion<T> | null;
+    };
+    exports: {
+        expandRow: (data: T) => Promise<void>;
+        collapseRow: (data?: T) => void;
+        toggleRowExpand: (data: T) => Promise<void>;
+        isRowExpanded: (data: T) => boolean;
+        getExpandedRow: () => T | null;
     };
-    exports: {};
     bindings: "inlineRowHeight" | "selectedRows";
     slots: {};
     events: {};
@@ -43,7 +57,13 @@ declare class __sveltets_Render<T = any> {
     events(): ReturnType<typeof $$render<T>>['events'];
     slots(): ReturnType<typeof $$render<T>>['slots'];
     bindings(): "inlineRowHeight" | "selectedRows";
-    exports(): {};
+    exports(): {
+        expandRow: (data: T) => Promise<void>;
+        collapseRow: (data?: T | undefined) => void;
+        toggleRowExpand: (data: T) => Promise<void>;
+        isRowExpanded: (data: T) => boolean;
+        getExpandedRow: () => T | null;
+    };
 }
 interface $$IsomorphicComponent {
     new <T = any>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {

package/dist/data_table/README.md

@@ -55,6 +55,7 @@ import type { DataColumn, ActionsColumn, IndicatorColumn, RowAction } from "@tic
 | `style` | `string` | `""` | Additional CSS styles |
 | `summaryLabel` | `string` | i18n `dataTable.summaryLabel` ("Total") | Label of the summary row; empty string hides it |
 | `summaryValues` | `Record<string, any> \| null` | `null` | External totals keyed by field; override local aggregation (server-side totals for paged data) |
+| `rowExpansion` | `RowExpansion \| null` | `null` | Row expansion config (inline component, toggle icon, click / double-click trigger…), see [Row Expansion](#row-expansion) |
 
 ## Types
 
@@ -134,7 +135,28 @@ interface IndicatorColumn {
   width: number;                   // Column width in pixels
   selectable?: boolean;            // Whether rows are selectable
   showRowNo?: boolean;             // Whether to show row numbers
-  buildInlineComponent?: (data: any) => Promise<any>;  // Inline component builder
+  /** @deprecated use the DataTable `rowExpansion` prop instead */
+  buildInlineComponent?: (data: any) => Promise<any>;
+}
+```
+
+### RowExpansion
+
+```typescript
+interface RowExpansion<T = any> {
+  build: (data: T) => Promise<Component> | Component; // inline component builder (may be async)
+  showToggle?: boolean;             // show the expand icon in the indicator column, default true (needs indicatorColumn)
+  trigger?: 'click' | 'dblclick';   // toggle by clicking / double-clicking the row; unset by default
+  isExpandable?: (data: T) => boolean; // which rows may expand
+  onExpandChange?: (data: T | null) => void; // fired on expand / collapse (null when collapsed)
+}
+
+// Props received by the inline component: data (row data) and context
+interface RowExpandContext<T = any> {
+  data: T;
+  collapse: () => void;                       // collapse the expanded row
+  actions: Array<RowAction<T>>;               // the row's actions (from actionsColumn.getActions)
+  invoke: (label: string) => Promise<boolean>; // run a row action by label
 }
 ```
 
@@ -486,60 +508,36 @@ Using the custom component in column definitions:
   import OrderDetails from "./OrderDetails.svelte";
   
   const columns = [
-    { text: "Order ID", field: "orderId", width: 120 },
-    { text: "Customer", field: "customer", width: 150 },
-    { text: "Total", field: "total", width: 100, align: "right",
+    { title: "Order ID", field: "orderId", width: 120 },
+    { title: "Customer", field: "customer", width: 150 },
+    { title: "Total", field: "total", width: 100, align: "right",
       formatter: (value) => `$${value?.toFixed(2) ?? '0.00'}`
     },
-    { text: "Status", field: "status", width: 120, align: "center" },
-    { text: "Date", field: "orderDate", width: 120 }
+    { title: "Status", field: "status", width: 120, align: "center" }
   ];
   
-  const indicatorColumn = {
-    width: 50,
-    selectable: false,
-    showRowNo: false,
-    buildInlineComponent: async (orderData) => {
-      // Simulate API call to fetch order details
-      await new Promise(resolve => setTimeout(resolve, 1000));
+  const indicatorColumn = { width: 50 };
+
+  const rowExpansion = {
+    build: async (orderData) => {
+      // e.g. fetch the details first, then pick the component
+      await new Promise(resolve => setTimeout(resolve, 300));
       return OrderDetails;
     }
   };
-  
-  const orders = [
-    {
-      orderId: "ORD-001",
-      customer: "John Doe",
-      total: 299.99,
-      status: "Shipped",
-      orderDate: "2024-01-15",
-      items: [
-        { product: "Laptop", quantity: 1, price: 299.99 }
-      ]
-    },
-    {
-      orderId: "ORD-002", 
-      customer: "Jane Smith",
-      total: 149.98,
-      status: "Processing",
-      orderDate: "2024-01-14",
-      items: [
-        { product: "Mouse", quantity: 2, price: 24.99 },
-        { product: "Keyboard", quantity: 1, price: 99.99 }
-      ]
-    }
-  ];
 </script>
 
 <DataTable 
   {columns} 
   list={orders} 
   {indicatorColumn}
-  inlineRowHeight={200}
+  {rowExpansion}
   emptyText="No orders found"
 />
 ```
 
+See [Row Expansion](#row-expansion) for other triggers and for closing / running row actions from inside the expanded panel.
+
 ### Table with Frozen Columns
 
 ```svelte
@@ -837,6 +835,89 @@ Set `summary` on any column (or pass `summaryValues` for a column's field) and a
 - **Paging**: pass server totals via `summaryValues` (keyed by field); they win over local aggregation and work on columns without `summary`.
 - Background: CSS variable `--topside-data-table-summary-bg` (defaults to the header background).
 
+## Row Expansion
+
+Configured through `rowExpansion`. Only one row is expanded at a time; the inline component receives `data` (the row data) and `context` (a `RowExpandContext`).
+
+### Triggers
+
+```svelte
+<script>
+  import DataTable from "@ticatec/topside-elements/DataTable";
+  import OrderDetails from "./OrderDetails.svelte";
+
+  let table;
+
+  const rowExpansion = {
+    build: async (order) => OrderDetails,
+    showToggle: false,       // no expand icon in the indicator column (default true)
+    trigger: 'dblclick',     // double-click the row to toggle; 'click' for single click (clicks on buttons / links / inputs are ignored)
+    isExpandable: (order) => order.items?.length > 0,
+    onExpandChange: (order) => console.log('expanded:', order)   // null when collapsed
+  };
+
+  const actionsColumn = {
+    width: 120,
+    getActions: (order) => [
+      { label: 'Edit', handler: () => edit(order) },
+      // an action button can drive expansion through the component methods
+      { label: 'Details', handler: () => table.toggleRowExpand(order) }
+    ]
+  };
+</script>
+
+<DataTable bind:this={table} {columns} {list} {rowExpansion} {actionsColumn} />
+<button onclick={() => table.expandRow(list[0])}>Expand first row</button>
+<button onclick={() => table.collapseRow()}>Collapse</button>
+```
+
+Component methods (call them on the `bind:this` instance; rows are matched by data object identity):
+
+| Method | Description |
+|--------|-------------|
+| `expandRow(data)` | Expand the row (ignored when already expanded, not allowed by `isExpandable`, or not found); returns a Promise |
+| `collapseRow(data?)` | Collapse the row; without an argument collapses whatever is expanded |
+| `toggleRowExpand(data)` | Toggle the row; returns a Promise |
+| `isRowExpanded(data)` | Whether the row is expanded |
+| `getExpandedRow()` | Data of the expanded row, or `null` |
+
+### Triggering from a custom cell
+
+A custom `render` component or an `ActionCell` does not need the table instance: dispatch a request from any element inside the row and the DataTable resolves the row itself.
+
+```svelte
+<!-- OrderNoCell.svelte -->
+<script>
+  import { requestRowToggle } from "@ticatec/topside-elements/DataTable";
+  let { data } = $props();
+</script>
+
+<a href="#" onclick={(e) => { e.preventDefault(); requestRowToggle(e.currentTarget); }}>{data.orderId}</a>
+```
+
+Helpers: `requestRowExpand(el)`, `requestRowCollapse(el)`, `requestRowToggle(el)`. You can also dispatch `ROW_EXPAND_EVENT` (`topside-row-expand`, `detail: { expanded?: boolean }`, `bubbles: true`) yourself. Requests are ignored when no `rowExpansion` is configured.
+
+### Closing / running row actions from the expanded panel
+
+```svelte
+<!-- OrderDetails.svelte -->
+<script>
+  let { data, context } = $props();
+</script>
+
+<div>
+  {#each context.actions as action}
+    <button disabled={action.disabled} onclick={() => action.handler(data)}>{action.label}</button>
+  {/each}
+  <button onclick={() => context.invoke('Edit')}>Edit</button>
+  <button onclick={() => context.collapse()}>Close</button>
+</div>
+```
+
+`context.actions` is the result of `actionsColumn.getActions(data)` (an empty array without an `actionsColumn`); deeply nested children can also call `requestRowCollapse(el)` to close their row.
+
+> Compatibility: the legacy `indicatorColumn.buildInlineComponent` still works and is equivalent to `rowExpansion = { build }`.
+
 ## Styling
 
 The DataTable component supports extensive styling customization through CSS custom properties and classes: