nicklabs-ui 1.0.86 → 1.0.88

package/README.md

@@ -2,7 +2,7 @@
 
 A Vue 3 component library with glassmorphism design, built for modern web applications.
 
-**Version**: 1.0.81 | **Framework**: Vue 3.5+
+**Version**: 1.0.87 | **Framework**: Vue 3.5+
 
 ---
 
@@ -25,6 +25,7 @@ A Vue 3 component library with glassmorphism design, built for modern web applic
     - [NDatePicker](#ndatepicker)
   - [Data Display](#data-display)
     - [NTable](#ntable)
+    - [NVirtualTable](#nvirtualtable)
     - [NList](#nlist)
     - [NTag](#ntag)
     - [NEmpty](#nempty)
@@ -959,6 +960,125 @@ function handleItemClick(item: User) {
 
 ---
 
+#### NVirtualTable
+
+A virtualized data table built on `@tanstack/vue-virtual`. Only the visible rows are rendered, so it stays smooth with very large datasets. Shares the same look, sorting behavior, loading, and empty state as [NTable](#ntable), but you render each row's cells yourself through the `cell` scoped slot.
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `NVirtualTableColumn[]` | `[]` | Column definitions |
+| `items` | `T[]` | `[]` | Row data |
+| `bordered` | `boolean` | `false` | Show borders |
+| `hoverable` | `boolean` | `true` | Highlight rows on hover |
+| `loading` | `boolean` | `false` | Show loading state (overlay) |
+| `emptyTitle` | `string` | `"目前沒有資料"` | Title when no data |
+| `emptyDescription` | `string` | `"可以點擊上方的按鈕來新增資料或重新整理"` | Description when no data |
+| `itemKey` | `keyof T` | `"id"` | Unique key field |
+| `rowHeight` | `number` | `56` | Estimated row height in **px** (drives virtualization) |
+| `height` | `string` | `"480px"` | Height of the scrollable body |
+| `overscan` | `number` | `8` | Extra rows rendered above/below the viewport |
+| `actionsWidth` | `string` | `"120px"` | Fixed width of the actions column (only shown when the `actions` slot is used). Increase it when you render more buttons, otherwise they get clipped |
+
+**Events**
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `sort` | `NVirtualTableSortState` | Column sort changed |
+| `click` | `T` | Row was clicked |
+
+**Slots**
+
+| Slot | Description |
+|------|-------------|
+| `cell` | Renders all cells for a row (scoped: `{ item, columns, index }`). Wrap each cell in a `.vtable-td` element for correct grid layout |
+| `actions` | Custom action buttons per row (scoped: `{ item, index }`); the actions column only appears when this slot is provided |
+| `actions-header` | Custom header text for the actions column (default: "操作") |
+| `empty` | Custom empty state content |
+
+**NVirtualTableColumn Interface**
+
+```typescript
+interface NVirtualTableColumn {
+  key: string       // Data field key
+  label: string     // Column header text
+  sortable?: boolean
+  width?: string    // CSS grid track size (e.g. "120px", "2fr"); defaults to "1fr"
+}
+```
+
+**Usage**
+
+```vue
+<template>
+  <NVirtualTable
+    :columns="columns"
+    :items="users"
+    :row-height="56"
+    height="600px"
+    hoverable
+    @sort="handleSort"
+    @click="handleItemClick"
+  >
+    <!-- Render every cell for the row yourself -->
+    <template #cell="{ item, columns }">
+      <div v-for="column in columns" :key="column.key" class="vtable-td">
+        {{ item[column.key] }}
+      </div>
+    </template>
+
+    <template #actions="{ item }">
+      <NButton size="sm" variant="ghost" intent="primary" @click="edit(item)">Edit</NButton>
+      <NButton size="sm" variant="ghost" intent="error" @click="remove(item)">Delete</NButton>
+    </template>
+  </NVirtualTable>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { NVirtualTable, NButton } from 'nicklabs-ui'
+import type { NVirtualTableColumn, NVirtualTableSortState } from 'nicklabs-ui'
+
+interface User {
+  id: number
+  name: string
+  email: string
+  role: string
+}
+
+const columns: NVirtualTableColumn[] = [
+  { key: 'name', label: 'Name', sortable: true, width: '200px' },
+  { key: 'email', label: 'Email' },
+  { key: 'role', label: 'Role', width: '120px' },
+]
+
+// Virtualization shines with large datasets
+const users = ref<User[]>(
+  Array.from({ length: 10000 }, (_, i) => ({
+    id: i,
+    name: `User ${i}`,
+    email: `user${i}@example.com`,
+    role: i % 2 ? 'User' : 'Admin',
+  })),
+)
+
+function handleSort(state: NVirtualTableSortState) {
+  console.log('Sort by:', state.key, state.order)
+}
+
+function handleItemClick(item: User) {
+  console.log('Clicked:', item)
+}
+</script>
+```
+
+> **Sorting is emit-only.** Like [NTable](#ntable), clicking a sortable header emits `sort` with the next `{ key, order }` state — the component does not reorder `items` itself. Sort the data in the parent (or server-side) and feed it back via `items`.
+
+> **Responsive width.** Flexible (`1fr` / unset) columns won't compress below a readable minimum (120px). When the columns' combined minimum width exceeds the container — e.g. on phones — the whole table scrolls horizontally (header and body in sync) instead of squishing the columns. Fixed-width columns keep their exact width.
+
+---
+
 #### NList
 
 A full-featured data management component combining table, pagination, filtering, and CRUD operations.