@ticatec/uniface-element 5.0.3 → 5.0.5

package/README.md

@@ -185,9 +185,9 @@ The library uses CSS custom properties for theming. You can customize the appear
 
 The library includes built-in internationalization support:
 
-default language is english. to load other languages:
+The default language is English. Other languages are loaded dynamically at runtime, so adding a new language never requires a code change.
 
-create a language resource json file in the static web directory, example: `/assets/uniface_zh-CN.json`
+Create a language resource json file in the static web directory, example: `/assets/uniface_zh-CN.json` (this is the complete key list):
 ```json
 {
   "uniface": {
@@ -195,7 +195,9 @@ create a language resource json file in the static web directory, example: `/ass
       "btnClose": "关闭",
       "btnCancel": "取消",
       "btnConfirm": "确定",
-      "textMore": "加载更多"
+      "textMore": "加载更多",
+      "filterPlaceholder": "搜索...",
+      "noResultsText": "无匹配结果..."
     },
     "colorPicker": "选择颜色",
     "calendar": {
@@ -218,14 +220,12 @@ create a language resource json file in the static web directory, example: `/ass
       "btnRemove": "删除",
       "btnPickup": "选择文件"
     },
-    "propertyEditor": {
-      "colName": "属性",
-      "colValue": "值"
-    },
     "dataTable": {
       "rowNo": "#",
       "actions": "操作",
-      "emptyDataSet": "暂无数据"
+      "emptyDataSet": "暂无数据",
+      "totalInfo": "共 <b>{{total}}</b> 条",
+      "rowsPerPage": "行/页"
     },
     "transfer": {
       "selectIndicator": "已选择: {{selected}}/{{total}}"
@@ -234,14 +234,14 @@ create a language resource json file in the static web directory, example: `/ass
 }
 ```
 
-You can load the resource file in the `+page.svelte` or other startup page.
+Load the resource file in `+page.svelte` or another startup page:
 
 ```typescript
 import i18n, {i18nUtils} from "@ticatec/i18n";
 
 // 设置语言
 i18n.setLanguage('zh-CN'); // 或 'en'
-i18nUtils.loadResources('/assets/uniface.json'); //the language code will insert before .json
+i18nUtils.loadResources('/assets/uniface.json'); // the language code will insert before .json => /assets/uniface_zh-CN.json
 ```
 
 ## Available Imports

package/README_CN.md

@@ -261,10 +261,11 @@ await messageBox.showInfo("操作完成", { title: "提示" });
 
 ## 国际化
 
-组件库内置国际化支持：
+组件库内置国际化支持:
 
-中文资源文件：  
-可以将文件放置在静态网站的目录下，比如`/assets/uniface_zh-CN.json`
+默认语言为英文。其他语言在运行时动态加载,未来新增语言无需修改代码。
+
+在静态资源目录下创建语言资源 json 文件,例如 `/assets/uniface_zh-CN.json`(以下为完整键列表):
 ```json
 {
   "uniface": {
@@ -272,7 +273,9 @@ await messageBox.showInfo("操作完成", { title: "提示" });
       "btnClose": "关闭",
       "btnCancel": "取消",
       "btnConfirm": "确定",
-      "textMore": "加载更多"
+      "textMore": "加载更多",
+      "filterPlaceholder": "搜索...",
+      "noResultsText": "无匹配结果..."
     },
     "colorPicker": "选择颜色",
     "calendar": {
@@ -295,14 +298,12 @@ await messageBox.showInfo("操作完成", { title: "提示" });
       "btnRemove": "删除",
       "btnPickup": "选择文件"
     },
-    "propertyEditor": {
-      "colName": "属性",
-      "colValue": "值"
-    },
     "dataTable": {
       "rowNo": "#",
       "actions": "操作",
-      "emptyDataSet": "暂无数据"
+      "emptyDataSet": "暂无数据",
+      "totalInfo": "共 <b>{{total}}</b> 条",
+      "rowsPerPage": "行/页"
     },
     "transfer": {
       "selectIndicator": "已选择: {{selected}}/{{total}}"
@@ -311,16 +312,16 @@ await messageBox.showInfo("操作完成", { title: "提示" });
 }
 ```
 
+在 `+page.svelte` 或其他启动页加载资源文件:
+
 ```typescript
 import i18n, {i18nUtils} from "@ticatec/i18n";
 
 // 设置语言
 i18n.setLanguage('zh-CN'); // 或 'en'
-i18nUtils.loadResources('/assets/uniface.json');
+i18nUtils.loadResources('/assets/uniface.json'); // 语言代码会插入到 .json 之前 => /assets/uniface_zh-CN.json
 ```
 
-
-
 ## 可用导入
 
 ### 模块化导入

package/dist/base-calendar/DateContext.d.ts

@@ -1,3 +1,4 @@
+import "../i18nRes";
 export default class DateContext {
     private _weekBegin;
     private _dateFmt;

package/dist/base-calendar/DateContext.js

@@ -1,5 +1,5 @@
-import i18nRes from "../i18nRes";
 import i18n from "@ticatec/i18n";
+import "../i18nRes"; // side effect: seeds the uniface namespace defaults used by i18n.get() below
 export default class DateContext {
     _weekBegin = 1;
     _dateFmt = "YYYY-MM-DD";
@@ -14,19 +14,16 @@ export default class DateContext {
         return DateContext.instance;
     }
     get months() {
-        return i18nRes.calendar.months;
+        return i18n.get('uniface.calendar.months');
     }
     get monthsAbbr() {
-        return i18nRes.calendar.monthsAbbr;
-        ;
+        return i18n.get('uniface.calendar.monthsAbbr');
     }
     get weekTitle() {
-        return i18nRes.calendar.weekTitle;
-        ;
+        return i18n.get('uniface.calendar.weekTitle');
     }
     get weekTitleAbbr() {
-        return i18nRes.calendar.weekTitleAbbr;
-        ;
+        return i18n.get('uniface.calendar.weekTitleAbbr');
     }
     set weekBegin(value) {
         if (value < 0 || value > 6) {

package/dist/composite/pagination_panel/PaginationPanel.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
     import Pagination from "../../navigation/pagination";
     import OptionsSelect from "../../form/options_select";
+    import i18nRes from "../../i18nRes";
     import type {GenerateTotalInfo, OnPageChange, OnPageSizeChange} from "../../types";
 
     interface Props {
@@ -29,7 +30,7 @@
         total = 0,
         generateInfo,
         rowCount = $bindable(25),
-        rowCountLabel = 'Rows/Page',
+        rowCountLabel = i18nRes.dataTable.rowsPerPage(),
         align = '',
         onPageSizeChange,
         onchange,
@@ -40,10 +41,12 @@
     );
     // Rendered via {@html} below: generateInfo is a trusted, caller-supplied
     // renderer (not user input) — same opt-in-HTML boundary as DataColumn#renderHTML.
+    // The default text comes from the i18n resources (dataTable.totalInfo), so it
+    // follows the active language instead of being hardcoded English.
     let totalText = $derived(
         generateInfo
             ? generateInfo(total, pageCount, pageNo, rowCount)
-            : `Total: <b>${total}</b> entities.`
+            : i18nRes.dataTable.totalInfo({total})
     );
 
     const handleRowCountChange = () => {

package/dist/composite/transfer/Transfer.svelte

@@ -5,7 +5,6 @@
     import type {FunFilter} from "../../data_display/list_box";
     import type {TransferData} from "../../types";
     import i18n, {i18nUtils} from "@ticatec/i18n";
-    import i18nRes from "../../i18nRes";
 
 
     interface Props {

package/dist/data_display/card/Card.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
     import type {Snippet} from 'svelte';
     import type CardAction from "./CardAction";
+    import type {CardActionsAlign} from "./CardAction";
     import CommonCardActionBar from "./CommonCardActionBar.svelte";
     import CardHeader from "./CardHeader.svelte";
 
@@ -13,6 +14,11 @@
         headerBar?: Snippet;
         children?: Snippet;
         theme?: string;
+        /** 操作栏图标排布方式，默认 'distribute'（按数量平分宽度、每个居中，不会被拉到两端） */
+        actionsAlign?: CardActionsAlign;
+        /** 'center'/'left'/'right' 模式下相邻图标的固定间距，例如 '16px' */
+        actionsGap?: string;
+        contentStyle?: string;
     }
 
     let {
@@ -23,7 +29,10 @@
         data = null,
         headerBar,
         children,
-        theme = ""
+        theme = "",
+        actionsAlign = 'distribute',
+        actionsGap,
+        contentStyle = ''
     }: Props = $props();
 </script>
 
@@ -38,13 +47,13 @@
                 {@render headerBar()}
             </div>
         {/if}
-        <div class="card-content">
+        <div class="card-content" style={contentStyle}>
             {#if children}
                 {@render children()}
             {/if}
         </div>
         {#if actions && actions.length > 0}
-            <CommonCardActionBar {actions} {data}/>
+            <CommonCardActionBar {actions} {data} align={actionsAlign} gap={actionsGap}/>
         {/if}
     </div>
 </div>

package/dist/data_display/card/Card.svelte.d.ts

@@ -1,5 +1,6 @@
 import type { Snippet } from 'svelte';
 import type CardAction from "./CardAction";
+import type { CardActionsAlign } from "./CardAction";
 interface Props {
     style?: string;
     title?: string;
@@ -9,6 +10,11 @@ interface Props {
     headerBar?: Snippet;
     children?: Snippet;
     theme?: string;
+    /** 操作栏图标排布方式，默认 'distribute'（按数量平分宽度、每个居中，不会被拉到两端） */
+    actionsAlign?: CardActionsAlign;
+    /** 'center'/'left'/'right' 模式下相邻图标的固定间距，例如 '16px' */
+    actionsGap?: string;
+    contentStyle?: string;
 }
 declare const Card: import("svelte").Component<Props, {}, "">;
 type Card = ReturnType<typeof Card>;

package/dist/data_display/card/CardAction.d.ts

@@ -21,3 +21,11 @@ export default interface CardAction {
      */
     callback: ActionCallback;
 }
+/**
+ * 操作栏图标的排布方式：
+ * - distribute（默认）：按图标数量平分整行宽度，每个图标在自己的等分格子里居中
+ *   （等价于 justify-content: space-around；数量少时不会被拉到两端）
+ * - center / left / right：固定间距（见 CommonCardActionBar 的 gap），整组图标
+ *   在操作栏里居中 / 左对齐 / 右对齐
+ */
+export type CardActionsAlign = 'distribute' | 'center' | 'left' | 'right';

package/dist/data_display/card/CardHeader.svelte

@@ -6,4 +6,15 @@
     let {title}: Props = $props();
 </script>
 
-<span>{title}</span>
+<span class="card-header-title" title={title}>{title}</span>
+
+<style>
+    .card-header-title {
+        display: block;
+        flex: 1 1 auto;
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+    }
+</style>

package/dist/data_display/card/CommonCardActionBar.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
     import type CardAction from "./CardAction";
+    import type {CardActionsAlign} from "./CardAction";
     import utils from "../../overlay/common/utils";
 
     interface Props {
@@ -7,15 +8,23 @@
         color?: string | null;
         data?: any;
         theme?: string;
+        /** 图标排布方式，默认 'distribute'（按数量平分宽度、每个居中） */
+        align?: CardActionsAlign;
+        /** 'center'/'left'/'right' 模式下相邻图标的固定间距；不设置则用 --uniface-spacing-actionbar */
+        gap?: string;
     }
 
     let {
         actions,
         color = null,
         data,
-        theme = ""
+        theme = "",
+        align = 'distribute',
+        gap
     }: Props = $props();
 
+    let barStyle = $derived(gap ? `--card-action-gap: ${gap}` : '');
+
     let clickEnable = $state(true);
 
     const handleActionClick = (action: CardAction) => async (e: MouseEvent) => {
@@ -35,7 +44,7 @@
     };
 </script>
 
-<div class="card-action-bar">
+<div class="card-action-bar align-{align}" style={barStyle}>
     {#each actions as action}
         {#if action.icon}
             <i class="action-icon {action.icon}"
@@ -69,13 +78,32 @@
         flex-direction: row;
         width: 100%;
         align-items: center;
-        justify-content: space-between;
         text-align: center;
         font-size: var(--uniface-card-bar-font-size);
         border-top: 1px solid var(--uniface-card-color-inside-border);
         color: var(--uniface-card-color-action-bar);
     }
 
+    /* 按数量平分整行宽度，每个图标在自己的等分格子里居中 — 数量少时不会被拉到两端 */
+    .card-action-bar.align-distribute {
+        justify-content: space-around;
+    }
+
+    .card-action-bar.align-center {
+        justify-content: center;
+        gap: var(--card-action-gap, var(--uniface-spacing-actionbar, 8px));
+    }
+
+    .card-action-bar.align-left {
+        justify-content: flex-start;
+        gap: var(--card-action-gap, var(--uniface-spacing-actionbar, 8px));
+    }
+
+    .card-action-bar.align-right {
+        justify-content: flex-end;
+        gap: var(--card-action-gap, var(--uniface-spacing-actionbar, 8px));
+    }
+
     .action-icon {
         display: block;
         cursor: pointer;

package/dist/data_display/card/CommonCardActionBar.svelte.d.ts

@@ -1,9 +1,14 @@
 import type CardAction from "./CardAction";
+import type { CardActionsAlign } from "./CardAction";
 interface Props {
     actions: Array<CardAction>;
     color?: string | null;
     data?: any;
     theme?: string;
+    /** 图标排布方式，默认 'distribute'（按数量平分宽度、每个居中） */
+    align?: CardActionsAlign;
+    /** 'center'/'left'/'right' 模式下相邻图标的固定间距；不设置则用 --uniface-spacing-actionbar */
+    gap?: string;
 }
 declare const CommonCardActionBar: import("svelte").Component<Props, {}, "">;
 type CommonCardActionBar = ReturnType<typeof CommonCardActionBar>;

package/dist/data_display/card/README.md

@@ -23,12 +23,15 @@ npm install @ticatec/uniface-element
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `title` | `string` | `''` | Plain-text title rendered by `CardHeader`. If empty and `headerBar` is provided, the custom snippet is used instead |
+| `title` | `string` | `''` | Plain-text title rendered by `CardHeader`. Single-line, truncated with an ellipsis (native tooltip shows the full text) when it overflows. If empty and `headerBar` is provided, the custom snippet is used instead |
 | `headerBar` | `Snippet` | `undefined` | Custom header content (takes over when `title` is empty) |
 | `actions` | `CardAction[]` | `[]` | Action bar items rendered at the bottom. Empty array → no footer |
 | `data` | `any` | `null` | Passed as the argument to each action's `callback(data)` |
+| `actionsAlign` | `'distribute' \| 'center' \| 'left' \| 'right'` | `'distribute'` | How action icons are laid out — see below |
+| `actionsGap` | `string` | `undefined` | Fixed spacing between icons for `'center'`/`'left'`/`'right'` (e.g. `'16px'`); falls back to `--uniface-spacing-actionbar` |
 | `variant` | `'plain' \| '3d'` | `'plain'` | `'3d'` adds a box-shadow to lift the card |
 | `style` | `string` | `''` | Inline CSS on the root |
+| `contentStyle` | `string` | `''` | Inline CSS on the body wrapper (`.card-content`) |
 | `theme` | `string` | `''` | Theme value, exposed as `data-theme` on the root for scoped CSS |
 | `children` | `Snippet` | `undefined` | Card body |
 
@@ -92,6 +95,19 @@ interface CardAction {
 </Card>
 ```
 
+### Action bar layout
+
+With few actions, `justify-content: space-between` (the old, fixed behavior) pushes them to opposite edges — two icons end up one at the far left, one at the far right. `actionsAlign` controls this:
+
+- `'distribute'` (default) — the row is split into as many equal-width slots as there are actions, each icon centered in its own slot. Equivalent to `justify-content: space-around`; icons never get pushed all the way to the edges regardless of count.
+- `'center'` / `'left'` / `'right'` — icons keep a fixed gap (`actionsGap`, default `--uniface-spacing-actionbar`) and the whole group is aligned as a block within the footer.
+
+```svelte
+<Card title="Item Details" {actions} data={cardData} actionsAlign="center" actionsGap="24px">
+  ...
+</Card>
+```
+
 ## Styling
 
 ### Card body
@@ -118,6 +134,7 @@ interface CardAction {
 | `--uniface-card-color-action-bar-hover` | Icon hover color |
 | `--uniface-card-color-action-bar-disabled` | Icon disabled color |
 | `--action-image-size` / `--uniface-action-image-size` | Per-card override for action icon/image size |
+| `--uniface-spacing-actionbar` | Default `actionsGap` for `'center'`/`'left'`/`'right'` (falls back to `8px`) |
 
 ## Variants
 

package/dist/data_display/card/README_CN.md

@@ -23,12 +23,15 @@ npm install @ticatec/uniface-element
 
 | 属性 | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| `title` | `string` | `''` | 纯文本标题，由 `CardHeader` 渲染。为空且传了 `headerBar` 时改用自定义 snippet |
+| `title` | `string` | `''` | 纯文本标题，由 `CardHeader` 渲染。默认单行显示，超出宽度会用省略号截断（原生 tooltip 显示完整文字）。为空且传了 `headerBar` 时改用自定义 snippet |
 | `headerBar` | `Snippet` | `undefined` | 自定义标题内容（`title` 为空时生效） |
 | `actions` | `CardAction[]` | `[]` | 底部操作栏。空数组 → 不渲染底栏 |
 | `data` | `any` | `null` | 作为参数传给每个 action 的 `callback(data)` |
+| `actionsAlign` | `'distribute' \| 'center' \| 'left' \| 'right'` | `'distribute'` | 操作图标的排布方式，见下文 |
+| `actionsGap` | `string` | `undefined` | `'center'`/`'left'`/`'right'` 模式下图标之间的固定间距（比如 `'16px'`），不设则回退到 `--uniface-spacing-actionbar` |
 | `variant` | `'plain' \| '3d'` | `'plain'` | `'3d'` 加盒阴影让卡片浮起来 |
 | `style` | `string` | `''` | 根节点的内联 CSS |
+| `contentStyle` | `string` | `''` | 内容区域包裹层（`.card-content`）的内联 CSS |
 | `theme` | `string` | `''` | 主题值，作为 `data-theme` 写到根节点上方便做作用域 CSS |
 | `children` | `Snippet` | `undefined` | 卡片内容体 |
 
@@ -92,6 +95,19 @@ interface CardAction {
 </Card>
 ```
 
+### 操作栏排布方式
+
+当图标数量比较少时，`justify-content: space-between`（旧的固定行为）会把它们推到两端 —— 两个图标就变成一个在最左，一个在最右。`actionsAlign` 用来控制这个行为：
+
+- `'distribute'`（默认）—— 把整行按图标数量平分成若干等宽格子，每个图标在自己的格子里居中。等价于 `justify-content: space-around`；不管图标数量多少，都不会被拉到两端。
+- `'center'` / `'left'` / `'right'` —— 图标之间保持固定间距（`actionsGap`，默认回退到 `--uniface-spacing-actionbar`），整组图标作为一个整体在底栏里居中 / 左对齐 / 右对齐。
+
+```svelte
+<Card title="项目详情" {actions} data={cardData} actionsAlign="center" actionsGap="24px">
+  ...
+</Card>
+```
+
 ## 样式定制
 
 ### 卡片本体
@@ -118,6 +134,7 @@ interface CardAction {
 | `--uniface-card-color-action-bar-hover` | 图标悬停颜色 |
 | `--uniface-card-color-action-bar-disabled` | 图标禁用颜色 |
 | `--action-image-size` / `--uniface-action-image-size` | 单卡片覆盖操作图标/图片的尺寸 |
+| `--uniface-spacing-actionbar` | `'center'`/`'left'`/`'right'` 模式下 `actionsGap` 的默认值（缺省回退到 `8px`） |
 
 ## variant
 

package/dist/data_table/DataTable.svelte

@@ -11,6 +11,7 @@
     import { OrderDirection } from "./lib/OrderDirection";
     import type { CompareFunction } from "./lib/CompareFunction";
     import type { GetRowFontStyle } from "../types";
+    import { computeVirtualWindow } from "./lib/virtualWindow";
 
     interface Props {
         columns: Array<DataColumn>;
@@ -26,6 +27,13 @@
         emptyIndicator?: string;
         getRowFontStyle?: GetRowFontStyle<T>;
         style?: string;
+        /**
+         * 行虚拟化(窗口化渲染):仅渲染可视区域附近的行,大数据集(数千行以上)
+         * 建议开启。要求所有行高度一致(即统一的 rowHeight),因此默认关闭。
+         */
+        virtual?: boolean;
+        /** 虚拟化时可视区上下额外渲染的行数。 */
+        overscan?: number;
     }
 
     let {
@@ -42,6 +50,8 @@
         emptyIndicator = undefined,
         getRowFontStyle = undefined,
         style = '',
+        virtual = false,
+        overscan = 8,
     }: Props = $props();
 
     const id: string = Math.round(new Date().getTime() + Math.random() * 1000).toString(36);
@@ -59,6 +69,23 @@
     let scrollTop = $state(0);
     let inlineComponent = $state<any>(null);
 
+    // Measured by ContentPanel (its scrollable data area); drives the virtual window.
+    let viewportHeight = $state(0);
+    let expandIndex = $derived(expandRow ? rows.indexOf(expandRow) : -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
+        ? computeVirtualWindow({
+            scrollTop,
+            viewportHeight,
+            rowHeight,
+            count: rows.length,
+            overscan,
+            expandIndex,
+            inlineRowHeight
+        })
+        : null);
+
     let orderColumn = $state<DataColumn | null>(null);
     let orderDirection = $state<OrderDirection>(OrderDirection.Ascending);
 
@@ -162,6 +189,7 @@
                 {handleWidthChange}
                 width={frozenWidth}
                 bind:scrollTop
+                {vwindow}
             />
         {/if}
 
@@ -185,10 +213,12 @@
             displayHorizontalScroll={actionsColumn != null || indicatorColumn != null || fixedCols.length > 0}
             showVerticalScroll={actionsColumn == null}
             {getRowFontStyle}
+            {vwindow}
+            bind:viewportHeight
         />
     {/if}
 
     {#if actionsColumn}
-        <ActionPanel {expandRow} {rowHeight} {headerHeight} {actionsColumn} {rows} {inlineRowHeight} bind:scrollTop />
+        <ActionPanel {expandRow} {rowHeight} {headerHeight} {actionsColumn} {rows} {inlineRowHeight} bind:scrollTop {vwindow} />
     {/if}
 </div>

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

@@ -17,6 +17,13 @@ declare function $$render<T = any>(): {
         emptyIndicator?: string;
         getRowFontStyle?: GetRowFontStyle<T>;
         style?: string;
+        /**
+         * 行虚拟化(窗口化渲染):仅渲染可视区域附近的行,大数据集(数千行以上)
+         * 建议开启。要求所有行高度一致(即统一的 rowHeight),因此默认关闭。
+         */
+        virtual?: boolean;
+        /** 虚拟化时可视区上下额外渲染的行数。 */
+        overscan?: number;
     };
     exports: {};
     bindings: "inlineRowHeight" | "selectedRows";

package/dist/data_table/lib/virtualWindow.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Row-windowing math for the DataTable's opt-in virtual scrolling.
+ *
+ * The table renders three vertically synced panels (frozen columns, data
+ * content, actions). Each panel renders only the rows inside the computed
+ * window, with a top and bottom spacer so the scroll container keeps its
+ * full natural scrollHeight (the native scrollbar and the existing
+ * wheel/scroll sync logic keep working unchanged).
+ *
+ * All rows share one fixed `rowHeight`; at most one row (`expandIndex`) has
+ * an inline expansion panel of `inlineRowHeight` rendered directly below it.
+ */
+export interface VirtualWindow {
+    /** Index of the first rendered row (inclusive). */
+    start: number;
+    /** Index just past the last rendered row (exclusive). */
+    end: number;
+    /** Height (px) of the spacer above the rendered rows. */
+    topPad: number;
+    /** Height (px) of the spacer below the rendered rows. */
+    bottomPad: number;
+}
+export interface VirtualWindowInput {
+    scrollTop: number;
+    /** Height (px) of the scrollable viewport. 0 is tolerated (renders overscan only). */
+    viewportHeight: number;
+    rowHeight: number;
+    /** Total number of rows. */
+    count: number;
+    /** Extra rows rendered above and below the visible range. */
+    overscan?: number;
+    /** Index of the expanded row, or -1 when none. */
+    expandIndex?: number;
+    /** Height (px) of the inline expansion panel below the expanded row. */
+    inlineRowHeight?: number;
+}
+export declare function computeVirtualWindow(input: VirtualWindowInput): VirtualWindow;

package/dist/data_table/lib/virtualWindow.js

@@ -0,0 +1,41 @@
+/**
+ * Row-windowing math for the DataTable's opt-in virtual scrolling.
+ *
+ * The table renders three vertically synced panels (frozen columns, data
+ * content, actions). Each panel renders only the rows inside the computed
+ * window, with a top and bottom spacer so the scroll container keeps its
+ * full natural scrollHeight (the native scrollbar and the existing
+ * wheel/scroll sync logic keep working unchanged).
+ *
+ * All rows share one fixed `rowHeight`; at most one row (`expandIndex`) has
+ * an inline expansion panel of `inlineRowHeight` rendered directly below it.
+ */
+/** Top offset (px) of row `i`, accounting for an expansion panel above it. */
+const rowTop = (i, rowHeight, expandIndex, inlineRowHeight) => i * rowHeight + (expandIndex >= 0 && i > expandIndex ? inlineRowHeight : 0);
+export function computeVirtualWindow(input) {
+    const { scrollTop, viewportHeight, rowHeight, count } = input;
+    const overscan = input.overscan ?? 8;
+    const expandIndex = input.expandIndex ?? -1;
+    const inlineRowHeight = expandIndex >= 0 ? (input.inlineRowHeight ?? 0) : 0;
+    if (count === 0 || rowHeight <= 0) {
+        return { start: 0, end: 0, topPad: 0, bottomPad: 0 };
+    }
+    const st = Math.max(0, scrollTop);
+    // First row whose bottom edge is below the viewport top.
+    let start = Math.floor(st / rowHeight);
+    if (expandIndex >= 0 && start > expandIndex) {
+        // The viewport top sits below the expanded row: shift the estimate by the
+        // expansion panel's height. Clamping to expandIndex keeps the expanded
+        // row (and with it the inline panel, which is rendered inside the #each
+        // body next to its row) in the window while any part of the panel is
+        // visible.
+        start = Math.max(expandIndex, Math.floor((st - inlineRowHeight) / rowHeight));
+    }
+    start = Math.max(0, Math.min(start, count - 1) - overscan);
+    const visibleCount = Math.ceil(viewportHeight / rowHeight) + 1;
+    let end = Math.min(count, start + visibleCount + overscan * 2);
+    const totalHeight = count * rowHeight + inlineRowHeight;
+    const topPad = rowTop(start, rowHeight, expandIndex, inlineRowHeight);
+    const bottomPad = totalHeight - rowTop(end, rowHeight, expandIndex, inlineRowHeight);
+    return { start, end, topPad, bottomPad };
+}