@ticatec/topside-elements 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.2.1
+
+### 新增
+- **ListBox 列表内置首尾项（`contentHeader` / `contentFooter` Snippet）**：在 `.listbox-content` 滚动容器内部的最上部与最下部分别新增 `contentHeader` 与 `contentFooter` 插槽。与外部固定不滚动的 `header` / `footer` 不同，这两个插槽的内容位于滚动视口内，跟随列表项一起滚动，适合呈现“全部/快捷选项”、“底部新增”或说明信息。
+
 ## 1.2.0
 
 ### 新增

package/dist/data_display/list_box/ListBox.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-    import {tick, onDestroy, untrack} from "svelte";
+    import {tick, onDestroy, untrack, type Snippet} from "svelte";
     import SearchBox from "../../form/search_box"
     import type {FilterFn} from "../../types";
     import type {ListLazyLoader} from "../../types";
@@ -29,9 +29,11 @@
         title?: string;
         round?: boolean;
         filterText?: string;
-        header?: any;
-        footer?: any;
-        loadMoreIndicator?: any;
+        header?: Snippet | any;
+        footer?: Snippet | any;
+        contentHeader?: Snippet | any;
+        contentFooter?: Snippet | any;
+        loadMoreIndicator?: Snippet | any;
     }
 
     let {
@@ -54,6 +56,8 @@
         filterText,
         header,
         footer,
+        contentHeader,
+        contentFooter,
         loadMoreIndicator
     }: Props = $props();
 
@@ -293,6 +297,9 @@
     {/if}
     <div class="listbox-content" class:selectable={selectMode==='single'} bind:this={scrollElement} onscroll={handleScroll}
          role="listbox" aria-multiselectable={selectMode === 'multiple' ? true : undefined}>
+        {#if contentHeader}
+            {@render contentHeader()}
+        {/if}
         {#if filteredList && ItemRender}
             {#each filteredList as item}
                 {#if selectMode === "multiple"}
@@ -319,6 +326,9 @@
         {#if hasMore && loadMoreIndicator}
             {@render loadMoreIndicator()}
         {/if}
+        {#if contentFooter}
+            {@render contentFooter()}
+        {/if}
     </div>
     {#if footer}
         <div class="box-footer flex-container">

package/dist/data_display/list_box/ListBox.svelte.d.ts

@@ -1,3 +1,4 @@
+import { type Snippet } from "svelte";
 import type { FilterFn } from "../../types";
 import type { ListLazyLoader } from "../../types";
 type OnSelectChange = (item: any) => void;
@@ -22,9 +23,11 @@ interface Props {
     title?: string;
     round?: boolean;
     filterText?: string;
-    header?: any;
-    footer?: any;
-    loadMoreIndicator?: any;
+    header?: Snippet | any;
+    footer?: Snippet | any;
+    contentHeader?: Snippet | any;
+    contentFooter?: Snippet | any;
+    loadMoreIndicator?: Snippet | any;
 }
 declare const ListBox: import("svelte").Component<Props, {}, "selectedItems">;
 type ListBox = ReturnType<typeof ListBox>;

package/dist/data_display/list_box/README.md

@@ -4,7 +4,7 @@
 
 A list component with optional header / footer snippets, built-in search, lazy loading, and single / multiple selection modes.
 
-> Svelte 5 component. Custom header/footer/load-more content is passed as **Snippets** (`header`, `footer`, `loadMoreIndicator`).
+> Svelte 5 component. Custom header/footer/load-more/content snippets are passed as **Snippets** (`header`, `footer`, `contentHeader`, `contentFooter`, `loadMoreIndicator`).
 
 ## Installation
 
@@ -39,8 +39,10 @@ npm install @ticatec/topside-elements
 | `round` | `boolean` | `false` | Adds a border radius (`--topside-radius`) |
 | `class` | `string` | `undefined` | Extra class on the root |
 | `style` | `string \| null` | `null` | Inline CSS on the root |
-| `header` | `Snippet` | `undefined` | Custom header content (overrides `title`) |
-| `footer` | `Snippet` | `undefined` | Custom footer content |
+| `header` | `Snippet` | `undefined` | Custom header content (overrides `title`, fixed above content) |
+| `footer` | `Snippet` | `undefined` | Custom footer content (fixed below content) |
+| `contentHeader` | `Snippet` | `undefined` | Custom snippet at the top inside `listbox-content` (scrolls with list items) |
+| `contentFooter` | `Snippet` | `undefined` | Custom snippet at the bottom inside `listbox-content` (scrolls with list items) |
 | `loadMoreIndicator` | `Snippet` | `undefined` | Custom "loading more" indicator shown at the bottom while `hasMore` |
 | `onchange` | `(item: any) => void` | `undefined` | Single-mode: fires when the selected item changes (also fires with `null` when filter resets selection) |
 | `onItemDblClick` | `(item: any) => void` | `undefined` | Single-mode only |
@@ -111,6 +113,26 @@ interface LoadResult {
 <button disabled={selected.length === 0} onclick={() => console.log(selected)}>OK</button>
 ```
 
+### Scrolling content header & footer (`contentHeader` & `contentFooter`)
+
+Unlike `header` and `footer` which remain pinned outside the scroll viewport, `contentHeader` and `contentFooter` sit inside `.listbox-content` at the very top and bottom, scrolling alongside the list items:
+
+```svelte
+<ListBox list={users} itemRender={UserItem} selectMode="single" style="height: 300px;">
+  {#snippet contentHeader()}
+    <div style="padding: 8px 12px; background: #eef2ff; border-bottom: 1px solid #e0e7ff; cursor: pointer;">
+      All Users / Quick Actions (scrolls with list)
+    </div>
+  {/snippet}
+
+  {#snippet contentFooter()}
+    <div style="padding: 8px 12px; text-align: center; color: #64748b; border-top: 1px solid #f1f5f9;">
+      Bottom action or footer notice (scrolls with list)
+    </div>
+  {/snippet}
+</ListBox>
+```
+
 ### Lazy-loaded list with custom footer
 
 ```svelte

package/dist/data_display/list_box/README_CN.md

@@ -4,7 +4,7 @@
 
 列表组件，可选 header / footer snippet、内置搜索框、懒加载、单选 / 多选。
 
-> Svelte 5 组件。header / footer / 加载更多 通过 **Snippet** 传入（`header`、`footer`、`loadMoreIndicator`）。
+> Svelte 5 组件。header / footer / contentHeader / contentFooter / 加载更多 通过 **Snippet** 传入（`header`、`footer`、`contentHeader`、`contentFooter`、`loadMoreIndicator`）。
 
 ## 安装
 
@@ -39,8 +39,10 @@ npm install @ticatec/topside-elements
 | `round` | `boolean` | `false` | 加圆角（`--topside-radius`） |
 | `class` | `string` | `undefined` | 根节点附加 class |
 | `style` | `string \| null` | `null` | 根节点内联 CSS |
-| `header` | `Snippet` | `undefined` | 自定义 header（覆盖 `title`） |
-| `footer` | `Snippet` | `undefined` | 自定义 footer |
+| `header` | `Snippet` | `undefined` | 自定义 header（覆盖 `title`，固定在顶部不随列表滚动） |
+| `footer` | `Snippet` | `undefined` | 自定义 footer（固定在底部不随列表滚动） |
+| `contentHeader` | `Snippet` | `undefined` | 位于 `listbox-content` 最上部的自定义组件/片段（跟随列表滚动） |
+| `contentFooter` | `Snippet` | `undefined` | 位于 `listbox-content` 最下部的自定义组件/片段（跟随列表滚动） |
 | `loadMoreIndicator` | `Snippet` | `undefined` | 自定义"加载更多"指示器，`hasMore` 时显示在底部 |
 | `onchange` | `(item: any) => void` | `undefined` | 单选模式：选中变化时触发（过滤重置时也会以 `null` 触发一次） |
 | `onItemDblClick` | `(item: any) => void` | `undefined` | 仅单选模式 |
@@ -111,6 +113,26 @@ interface LoadResult {
 <button disabled={selected.length === 0} onclick={() => console.log(selected)}>OK</button>
 ```
 
+### 随列表滚动的内置首尾项 (`contentHeader` & `contentFooter`)
+
+与 `header` 和 `footer`（固定在滚动容器外部、不随内容滚动）不同，`contentHeader` 与 `contentFooter` 位于 `.listbox-content` 滚动容器内部的最上部与最下部，跟随列表项一起滚动，适合放置“全部选项”、“快捷动作”或底部的“新增选项”等条目：
+
+```svelte
+<ListBox list={users} itemRender={UserItem} selectMode="single" style="height: 300px;">
+  {#snippet contentHeader()}
+    <div style="padding: 8px 12px; background: #eef2ff; border-bottom: 1px solid #e0e7ff; cursor: pointer;">
+      全部选项 / 快捷操作（跟随列表滚动）
+    </div>
+  {/snippet}
+
+  {#snippet contentFooter()}
+    <div style="padding: 8px 12px; text-align: center; color: #64748b; border-top: 1px solid #f1f5f9;">
+      底部操作或说明（跟随列表滚动）
+    </div>
+  {/snippet}
+</ListBox>
+```
+
 ### 懒加载 + 自定义 footer
 
 ```svelte

package/docs/NAMING.md

@@ -342,7 +342,7 @@ interface Action<T = any> {
 **Events (notifications)**: `onchange` `onclick` `ondblclick` `onfocus` `onblur` `oninput` `onclose` `onselect` `ondelete` `onremove` `onrefresh` `onconfirm` `onaction` `ondownload` `onretry` `onkeydown` `onkeyup` `onkeypress` `oncontextmenu` `ontoggle` `onItemClick` `onRowClick` `onIconClick` `onPageSizeChange` `onFileUploaded` `onFileRejected` `onUploadError` `onPreview` `onResizeEnd`; between DataTable's internal panels: `onCellClick` `onWidthChange` `onRowExpand` `onRowSelectChange` `onToggleSelectAll`
 **Hooks (veto)**: `beforeClose` `beforeRemove` `beforeChange` `beforeTransfer`
 **Instance methods**: `focus()` `blur()` `clear()` `open()` `close()` `reset()` `push()` `pop()` `getElement()` `openFileDialog()`
-**Snippets**: `children` `header` `headerExtra` `footer` `left` `right` `top` `bottom` `sidebar` `home` `leadingIcon` `trailingIcon` `popup` `item` `tab` `node` `chevronIcon` `nodeIcon` `from` `to`
+**Snippets**: `children` `header` `headerExtra` `footer` `contentHeader` `contentFooter` `left` `right` `top` `bottom` `sidebar` `home` `leadingIcon` `trailingIcon` `popup` `item` `tab` `node` `chevronIcon` `nodeIcon` `from` `to`
 
 ---
 

package/docs/NAMING_CN.md

@@ -342,7 +342,7 @@ interface Action<T = any> {
 **事件（通知）**：`onchange` `onclick` `ondblclick` `onfocus` `onblur` `oninput` `onclose` `onselect` `ondelete` `onremove` `onrefresh` `onconfirm` `onaction` `ondownload` `onretry` `onkeydown` `onkeyup` `onkeypress` `oncontextmenu` `ontoggle` `onItemClick` `onRowClick` `onIconClick` `onPageSizeChange` `onFileUploaded` `onFileRejected` `onUploadError` `onPreview` `onResizeEnd`；DataTable 内部面板间：`onCellClick` `onWidthChange` `onRowExpand` `onRowSelectChange` `onToggleSelectAll`
 **钩子（否决）**：`beforeClose` `beforeRemove` `beforeChange` `beforeTransfer`
 **实例方法**：`focus()` `blur()` `clear()` `open()` `close()` `reset()` `push()` `pop()` `getElement()` `openFileDialog()`
-**Snippet**：`children` `header` `headerExtra` `footer` `left` `right` `top` `bottom` `sidebar` `home` `leadingIcon` `trailingIcon` `popup` `item` `tab` `node` `chevronIcon` `nodeIcon` `from` `to`
+**Snippet**：`children` `header` `headerExtra` `footer` `contentHeader` `contentFooter` `left` `right` `top` `bottom` `sidebar` `home` `leadingIcon` `trailingIcon` `popup` `item` `tab` `node` `chevronIcon` `nodeIcon` `from` `to`
 
 ---
 

package/docs/components/list-box/README.md

@@ -40,6 +40,8 @@ import ListBox from '@ticatec/topside-elements/ListBox';
 | `filterText` | 是 | `string` | 否 | `undefined` | 否 | 过滤输入框的外部初始值或受控值，用于预设搜索条件。 |
 | `header` | 否 | `any` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 | `footer` | 否 | `any` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
+| `contentHeader` | 否 | `Snippet \| any` | 否 | `undefined` | 否 | 位于 listbox-content 最上部的自定义组件/片段（跟随列表滚动）。 |
+| `contentFooter` | 否 | `Snippet \| any` | 否 | `undefined` | 否 | 位于 listbox-content 最下部的自定义组件/片段（跟随列表滚动）。 |
 | `loadMoreIndicator` | 否 | `any` | 否 | `undefined` | 否 | 可选配置，具体取值范围和数据结构见类型列。 |
 
 > 组件的“可绑定”表示源码使用了 Svelte 5 的 `$bindable`；服务的“响应式”表示成员使用了 `$state`。复杂类型请同时参考 TypeScript 自动补全。
@@ -121,6 +123,22 @@ import ListBox from '@ticatec/topside-elements/ListBox';
 - 默认值：`undefined`
 - 示例写法：`filterText="研发"`
 
+### `contentHeader`
+
+位于 `listbox-content` 滚动容器内部的最上部，在所有列表项之前渲染，**跟随列表一起滚动**（与固定的 `header` 区分）。可用于放置如“全部选项”、“快捷搜索”等类似选择项的内容。
+
+- 类型：`Snippet | any`
+- 默认值：`undefined`
+- 示例写法：`{#snippet contentHeader()}<div>全部选项</div>{/snippet}`
+
+### `contentFooter`
+
+位于 `listbox-content` 滚动容器内部的最下部，在所有列表项（及加载更多指示器）之后渲染，**跟随列表一起滚动**（与固定的 `footer` 区分）。可用于放置如“新增选项”、“列表说明”等类似选择项的内容。
+
+- 类型：`Snippet | any`
+- 默认值：`undefined`
+- 示例写法：`{#snippet contentFooter()}<div>新增选项</div>{/snippet}`
+
 ## 相关类型定义
 
 以下定义帮助理解复杂属性的数据结构；其中部分辅助类型属于内部实现，不一定是独立导出入口。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ticatec/topside-elements",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "A comprehensive UI component library for Svelte applications with rich form controls, data tables, layouts and interactive elements",
   "keywords": [
     "svelte",