vue-virtual-flow 0.0.8 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-14
+
+### Added
+- **VirtualCarousel**: Add configurable mouse dragging, momentum, controlled snapping, intrinsic `autoWidth` slides, RTL support, continuous looping, bounded keep-alive caching, and pinned slide instances
+- **ChatVirtualScroll**: Add per-message size estimates, scroll activity state, visible-range events, key-based scrolling, logical position restoration, pinned/focused message retention, forced bottom-follow rules, and configurable synchronous measurement
+- **ChatVirtualScroll**: Add an accessible new-message counter with a customizable slot and localized built-in label
+- **ChatVirtualScroll**: Add `itemsVersion` and `refresh()` for explicitly reconciling arbitrary in-place mutations without an always-on deep watcher
+
+### Fixed
+- **ChatVirtualScroll**: Anchor native scrolling at the bottom so prepended history is immediately reachable during touch scrolling, without rebasing the scroll position
+- **ChatVirtualScroll**: Preserve the reading position when messages below the viewport resize or new messages arrive during a gesture
+- **ChatVirtualScroll**: Keep the new-message control inside the viewport instead of scrolling it away with message content
+- **ChatVirtualScroll**: Defer measurement corrections during wheel, keyboard, touch, smooth-scroll, and scrollbar-drag activity so native momentum is not interrupted
+- **ChatVirtualScroll**: Use stable identity fallbacks instead of array indexes and reject duplicate keys before they can corrupt measurements or anchors
+
+### Improved
+- **VirtualCarousel**: Extract autoplay, interaction, layout, and motion responsibilities and add cross-browser regression coverage for dragging, looping, RTL, auto-width, and cached state
+- **ChatVirtualScroll**: Measure previously unseen messages before paint and update append, prepend, measurement, offset, and key operations through an incremental keyed index
+- **ChatVirtualScroll**: Remove the duplicate measured-height map and split input activity from layout/measurement logic
+- Cover cold variable-height scrolling, native Chromium touch input, new-message overlay geometry, and prepend/resize anchoring across Chromium, Firefox, and WebKit
+
+### Changed
+- The chat's internal DOM `scrollTop` is now negative above the bottom. Exposed scrolling methods and `scroll` event offsets remain measured from the top; use those APIs instead of accessing the native offset directly
+- **ChatVirtualScroll**: Add a `.vue-chat-virtual-scroll__root` layout wrapper while keeping inherited attributes on the scroll viewport
+- **ChatVirtualScroll**: Duplicate keys now fail fast; every message must have a unique stable key
+
+## [0.0.7] - 2026-09-29
+
+### Fixed
+- **ChatVirtualScroll**: Preserve visible message DOM and scroll position when older messages are prepended
+- **ChatVirtualScroll**: Defer native scroll corrections during touch gestures and momentum while visually compensating for measured height changes
+- **ChatVirtualScroll**: Prevent gaps at the top and double scroll adjustments near the bottom when message heights shrink
+
+### Improved
+- Reserve image dimensions in the chat playground to reduce layout shifts while media loads
+- Added regression coverage for touch scrolling, prepend anchoring, height changes, imperative scrolling, and cleanup across unit and browser tests
+
+## [0.0.6] - 2026-09-29
+
+### Added
+- **ChatVirtualScroll**: Added an optional `size` prop to limit mounted messages including overscan, while always keeping enough messages to fill the viewport
+
+### Improved
+- Added English and Vietnamese documentation for `size` and configured the chat playground with a render budget of 12 messages
+- Added regression tests for render budgets, reactive updates, variable message heights, append/prepend behavior, and scrolling up in a portrait mobile viewport
+
+## [0.0.5] - 2026-09-29
+
+### Added
+- **SkeletonLoader**: Added configurable dimensions, rectangle/rounded/circle variants, shimmer animation, reduced-motion support, and an accessible loading label
+- **Public API**: Exported `SkeletonLoader` and `SkeletonLoaderProps`, and registered the component in the Vue plugin
+- **Playground**: Added skeleton placeholders to the load-more demo
+
+### Improved
+- Added English and Vietnamese SkeletonLoader usage guides
+- Converted API references and usage recipes into tables, including event listeners, ref actions, responsive configuration, autoplay, and release commands
+
+## [0.0.4] - 2026-09-11
+
+### Added
+- **WindowGirdVirtualScroll**: Added fixed-height, multi-column window virtualization with configurable columns, gaps, overscan, loading, pull-to-refresh, and imperative scrolling
+- **Playground**: Added an interactive window grid demo with column controls and direct item navigation
+
+### Fixed
+- **WindowDynamicVirtualScroll**: Reset stale measurements and load-more state when the item key set changes without changing the item count
+- **WindowDynamicVirtualScroll**: Batched window scroll and ResizeObserver updates with `requestAnimationFrame` to reduce redundant work
+- **WindowDynamicVirtualScroll**: Cancelled pending frames and guarded deferred callbacks during component cleanup
+
+### Improved
+- Added regression coverage for window scroll batching, resize compensation, same-size dataset replacement, and lifecycle cleanup
+
+## [0.0.3] - 2026-08-08
+
+### Fixed
+- **All Components**: Smooth scroll animation now works correctly for all distances instead of being force-disabled when scrolling > 3 viewports
+- **VirtualCarousel**: Fixed responsive mode stability when window is resized
+- **VirtualCarousel**: Fixed circular dependency in computed properties causing scroll calculation issues
+- **All Components**: Improved ResizeObserver cleanup to prevent potential memory leaks
+
+### Added
+- **VirtualCarousel**: Exported `ResponsiveBreakpoint` type for TypeScript users
+
+### Improved
+- Better memory management in all components with explicit observer cleanup
+- More consistent scroll behavior respecting user's `behavior` option
+
+## [0.0.2] - Previous release
+
+Initial public release with core functionality.

package/README.md

@@ -551,6 +551,9 @@ async function loadOlder() {
     </template>
 
     <template #loadingOlder>Loading older messages…</template>
+    <template #newItems="{ count, scrollToBottom }">
+      <button @click="scrollToBottom('smooth')">{{ count }} new</button>
+    </template>
     <template #empty>No messages.</template>
   </ChatVirtualScroll>
 
@@ -563,12 +566,19 @@ async function loadOlder() {
 Prepend older data to the same keyed collection. The scroll container is anchored
 at the bottom, so adding or measuring older messages above the reader does not
 need a native scroll correction. Previously unseen messages are measured before
-paint, and cached height updates use an incremental size index.
-
-Use the exposed methods and the `scroll` event for positions measured from the
-top. The internal DOM scroller uses negative `scrollTop` values (zero at the
-bottom); code that directly reads or writes that DOM property must account for
-this. Message DOM order remains oldest to newest.
+paint, and cached height updates use an incremental keyed tree. Normal append,
+prepend, measurement, offset and key lookups are `O(log n)` per changed message;
+arbitrary replacement, removal or reorder falls back to rebuilding the index.
+Replace the `items` array for arbitrary edits. If application constraints require
+mutating the same array instance, increment `itemsVersion` (or call `refresh()`)
+after a same-length removal/reorder so the component can reconcile without an
+always-on `O(n)` deep watcher.
+
+Use the exposed methods, `getScrollPosition()`, and the `scroll` event for
+positive positions measured from the top. The internal DOM scroller uses
+negative `scrollTop` values (zero at the bottom) to preserve native momentum
+while history is prepended; consumers should not read or write that native
+property directly. Message DOM order remains oldest to newest.
 
 For smooth media conversations, reserve image/video dimensions with `width`,
 `height`, or `aspect-ratio`, use an estimate close to your message heights, and
@@ -581,11 +591,13 @@ virtualization cannot hide network latency once that boundary is reached.
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `items` | `readonly T[]` | required | Messages ordered from oldest to newest. |
+| `itemsVersion` | `PropertyKey` | unset | Increment after an arbitrary in-place mutation that keeps the same array reference/length. Immutable array replacement does not need it. |
 | `estimatedItemSize` | `number` | `48` | Initial average message height in pixels. |
+| `estimateItemSize` | `(item, index) => number` | unset | Per-message estimate for cold rows, useful when text and media have very different heights. |
 | `height` | `number \| string` | `400` | Viewport height. A number is pixels; `"fill"` maps to `100%`. |
 | `overscan` | `number` | `5` | Extra messages mounted before and after the visible range. |
 | `size` | `number` | unset | Optional total render budget including overscan, e.g. `:size="12"` for mobile. Trims overscan first; always renders enough messages to fill the viewport, even if this exceeds `size`. Does not add messages beyond `overscan`. Positive values are floored (minimum 1); non-positive or non-finite values disable the budget. |
-| `itemKey` | `keyof T \| (item, index) => PropertyKey` | `id`, `key`, or index | Stable identity; especially important when prepending. |
+| `itemKey` | `keyof T \| (item, index) => PropertyKey` | `id`, `key`, or item identity | Stable unique identity; especially important when prepending. Duplicate keys fail fast instead of corrupting anchors. |
 | `ariaLabel` | `string` | `"Chat messages"` | Accessible label for the live log. |
 | `stickToBottom` | `boolean` | `true` | Follows appended messages while currently near the bottom. |
 | `bottomThreshold` | `number` | `80` | Distance still considered “at bottom”, in pixels. |
@@ -593,6 +605,19 @@ virtualization cannot hide network latency once that boundary is reached.
 | `hasOlder` | `boolean` | `false` | Indicates that older history is available. |
 | `loadingOlder` | `boolean` | `false` | Prevents duplicate requests and shows the top indicator. |
 | `loadOlderThreshold` | `number` | `120` | Distance from the top that triggers `load-older`, in pixels. |
+| `scrollEndDelay` | `number` | `150` | Idle fallback in milliseconds for browsers without reliable `scrollend`. |
+| `syncMeasurement` | `boolean` | `true` | Measure new rows before paint. Set false to avoid synchronous layout reads and rely on `ResizeObserver`. |
+| `pinnedKeys` | `readonly PropertyKey[]` | `[]` | Messages kept mounted outside the visible range to preserve local state. |
+| `maxPinnedItems` | `number` | `20` | Maximum number of explicit pinned keys retained. |
+| `keepFocusedItem` | `boolean` | `true` | Keeps the message containing keyboard focus mounted while off-screen. |
+| `showNewItemsIndicator` | `boolean` | `true` | Shows the built-in new-message button while reading history. |
+| `newItemsLabel` | `(count) => string` | English label | Localizes the built-in new-message button without replacing the slot. |
+| `forceStickToBottom` | `(item, index) => boolean` | unset | Force-follows selected appended messages, commonly messages sent by the local user. |
+| `contain` | `boolean` | `true` | Enables layout/paint containment. Disable for overlays that intentionally escape without `Teleport`. |
+
+Pinned and keyboard-focused messages are intentionally additional to the
+`size` render budget. Keep `pinnedKeys` small; the `maxPinnedItems` guard does
+not cap the currently focused message.
 
 #### Slots
 
@@ -601,6 +626,7 @@ virtualization cannot hide network latency once that boundary is reached.
 | `default` | `{ item, index }` | Renders each mounted message. |
 | `empty` | none | Rendered when there are no messages. |
 | `loadingOlder` | none | Sticky top status; defaults to “Loading older messages…”. |
+| `newItems` | `{ count, scrollToBottom }` | Customizes the floating new-message control. |
 
 #### Events
 
@@ -609,14 +635,23 @@ virtualization cannot hide network latency once that boundary is reached.
 | `scroll` | `{ scrollTop, startIndex, endIndex }` | On container scroll. | `@scroll="onScroll"` |
 | `load-older` | none | Near the top when `hasOlder` is true and `loadingOlder` is false. | `@load-older="loadOlder"` |
 | `bottom-change` | `boolean` | When the viewport enters or leaves the bottom threshold. | `@bottom-change="onBottomChange"` |
+| `scrolling-change` | `boolean` | When user-driven scrolling starts or settles. | `@scrolling-change="onScrollingChange"` |
+| `new-items-change` | `number` | When the number of appended messages unseen at the bottom changes. | `@new-items-change="onNewItemsChange"` |
+| `visible-change` | `{ scrollTop, startIndex, endIndex }` | When the actual visible range changes, excluding overscan; useful for read tracking. | `@visible-change="markVisibleAsRead"` |
 
 #### Exposed API
 
 | Method / state | Description | Template example |
 | --- | --- | --- |
 | `isAtBottom` | Readonly boolean indicating whether the user is near the bottom. | `chat?.isAtBottom` |
+| `isScrolling` | Readonly boolean indicating an active user scroll gesture. | `chat?.isScrolling` |
+| `newItemsCount` | Number of appended messages received while reading history. | `chat?.newItemsCount` |
+| `clearNewItems()` | Clears the new-message count without moving the viewport. | `chat?.clearNewItems()` |
+| `refresh()` | Reconciles keys and measurements after mutating the same `items` array in place. | `chat?.refresh()` |
+| `getScrollPosition()` | Returns the positive logical pixel offset from the list start. | `chat?.getScrollPosition()` |
 | `scrollTo(position, options?)` | Scrolls to a pixel offset. | `chat?.scrollTo(200, { behavior: 'smooth' })` |
 | `scrollToIndex(index, options?)` | Scrolls to a zero-based message index. | `chat?.scrollToIndex(10, { behavior: 'smooth' })` |
+| `scrollToKey(key, options?)` | Scrolls to a message by its stable key. | `chat?.scrollToKey(messageId, { align: 'center' })` |
 | `scrollToTop(behavior?)` | Scrolls to the oldest loaded message. | `chat?.scrollToTop()` |
 | `scrollToBottom(behavior?)` | Scrolls to the newest loaded message. | `chat?.scrollToBottom('smooth')` |
 
@@ -720,8 +755,11 @@ These keys work while the viewport is focused:
 | `Home` | Moves to the first position. |
 | `End` | Moves to the last item. |
 
-For an unbounded feed, page data with `load-more` and keep a reasonable item
-window in the parent. Virtualization limits mounted DOM and media elements,
+The viewport also converts mouse-wheel input into slide transitions. The wheel
+handler in the component is enabled by default; nothing extra is required from
+the parent. For touch input, native scroll-snap continues to handle swipes.
+
+For an unbounded feed, page data with `load-more` and handle parents. Virtualization limits mounted DOM and media elements,
 but it does not remove objects from `items`.
 
 ### VirtualCarousel
@@ -802,8 +840,56 @@ five slides are normally mounted in the middle of the collection.
 | `autoplayDelay` | `number` | `3000` | Delay in milliseconds between automatic transitions; values below `1` are clamped and non-finite values use the default. |
 | `autoplayLoop` | `boolean` | `true` | Returns to the first slide when reaching the end. |
 | `pauseOnHover` | `boolean` | `true` | Pauses autoplay when the carousel is hovered. |
+| `mouseDrag` | `boolean` | `true` | Enables click-and-drag navigation with the primary mouse button. |
+| `dragThreshold` | `number` | `8` | Pointer movement in pixels required to recognize and commit a drag. |
+| `momentum` | `boolean` | `true` | Projects release velocity and decelerates into the destination. |
+| `settleDuration` | `number` | `250` | Base duration in milliseconds for drag/loop settling; `0` makes it instant. Native API scrolling still uses its `behavior` argument. |
+| `nativeSnap` | `boolean` | `true` | Uses native CSS snap for wheel/API scrolling. Set to `false` inside another snap container to settle with the motion controller instead. Loop always uses controlled settling. |
+| `autoWidth` | `boolean` | `false` | Measures each slide's intrinsic width; set the width of the slot content. Overrides `slidesPerView` for sizing. |
+| `estimatedItemWidth` | `number` | `240` | Estimated width in pixels for unmounted slides in `autoWidth` mode. |
+| `rtl` | `boolean` | `false` | Right-to-left layout, pointer movement, native scrolling, and arrow keys. |
+| `loop` | `boolean` | `false` | Continuous looping in either direction, separate from `autoplayLoop`. Disabled when all items fit in the viewport. |
+| `keepAlive` | `boolean` | `false` | Retains recently viewed slide instances and their local state in a bounded cache. |
+| `maxCachedItems` | `number` | `20` | Maximum additional offscreen cached/pinned slides. Visible/buffered slides and one focused slide are not counted. |
+| `pinnedIndexes` | `readonly number[]` | `[]` | Slide indices to retain even with `keepAlive=false`; consumes the offscreen cache budget. |
 | `responsive` | `ResponsiveBreakpoint[]` | `undefined` | Overrides slide count, scroll step, and gap at container-width breakpoints. |
 
+Touch gestures use directional locking: vertical gestures continue scrolling the
+page, while horizontal gestures move the carousel and snap to the nearest slide.
+While dragging, the track moves with compositor-friendly `translate3d` and the
+selected `activeIndex` remains unchanged until drag settling finishes. The render
+window and `inViewport` update only when slides enter or leave view. A fast release
+continues with the release velocity and decelerates to rest, with momentum limited
+to two extra slides. Holding before release disables this momentum. A deliberate
+horizontal drag of at least `dragThreshold` pixels commits one slide even when it does not cross the
+slide midpoint.
+
+Buttons and links keep their normal click behavior. Form fields and
+`data-carousel-no-drag` descendants do not start dragging; form fields also keep
+their own arrow-key behavior. Wheel/trackpad input interrupts an active animation
+at its displayed position.
+
+`autoWidth` uses `ResizeObserver`, cumulative offsets, and binary search. Widths
+of slides not yet mounted are estimates, so distant jumps may be refined when
+those slides are first measured. Late measurements are applied after dragging
+finishes, preserving the selected slide. Give content a resolvable width, for
+example `<ProductCard :style="{ width: item.width + 'px' }" />`.
+
+`keepAlive` retains local input/component state until LRU eviction. Only settled
+views update cache recency; intermediate frames do not evict the destination's
+state. Cached offscreen slides are hidden and inert. Use `pinnedIndexes` to retain
+playing media explicitly; pause media with the slot's `inViewport` flag. Persistent
+state should still be stored outside slides by a stable `itemKey`.
+
+`loop` repositions each keyed slide around the current cycle without creating
+duplicate component instances. `autoplayLoop` only rewinds a non-looping carousel.
+Loop mode uses the same motion controller to settle wheel input after it stops,
+instead of relying on native snap points that change during cycle recentering.
+The demo disables incremental loading while continuous loop is enabled so that
+the collection's boundaries remain fixed. The component still supports
+`load-more`; changing data or geometry cancels the current transition and realigns
+the selected index.
+
 #### Responsive configuration
 
 The largest `breakpoint` not exceeding the carousel container width is used.
@@ -834,7 +920,7 @@ the base props, not to another breakpoint.
 
 | Slot | Scope | Description |
 | --- | --- | --- |
-| `default` | `{ item, index, active, visible }` | Renders each mounted slide. |
+| `default` | `{ item, index, active, visible, inViewport }` | `active`/`visible` describe the selected group; `inViewport` reflects actual overlap during motion. |
 | `empty` | none | Rendered when `items` is empty. |
 
 #### Events
@@ -1210,6 +1296,7 @@ import type {
 | `bun run test:browser` | Run Playwright browser tests. |
 | `bun run check` | Run all checks: unit tests, build, consumer types, package lint, and browser tests. |
 | `npm pack --dry-run` | Inspect the files that will be published. |
+| `npm publish --access public` | Publish the already-versioned public package after the release commit is ready. |
 | `prepublishOnly` | Automatically runs `bun run check` before publishing. |
 
 ```bash
@@ -1221,8 +1308,8 @@ bun run check
 
 The playground includes fixed-height, variable-height, window, chat,
 load-more, short-media, and carousel demos. Before publishing, also run
-`npm pack --dry-run`. GitHub releases are published through
-`.github/workflows/publish.yml`.
+`npm pack --dry-run`. Commit the release, publish it with
+`npm publish --access public`, then create and push the matching Git tag.
 
 ## Contributing
 

package/README.vi.md

@@ -551,6 +551,9 @@ async function loadOlder() {
     </template>
 
     <template #loadingOlder>Đang tải tin nhắn cũ…</template>
+    <template #newItems="{ count, scrollToBottom }">
+      <button @click="scrollToBottom('smooth')">{{ count }} tin mới</button>
+    </template>
     <template #empty>Chưa có tin nhắn.</template>
   </ChatVirtualScroll>
 
@@ -563,12 +566,18 @@ async function loadOlder() {
 Hãy thêm dữ liệu cũ vào đầu cùng một collection có key ổn định. Vùng cuộn lấy
 đáy làm mốc nên việc thêm hoặc đo tin nhắn phía trên người đọc không cần sửa vị
 trí cuộn native. Tin nhắn xuất hiện lần đầu được đo trước khi vẽ; các thay đổi chiều cao
-được cập nhật riêng trong bảng chỉ mục.
-
-Dùng các method qua ref và sự kiện `scroll` để thao tác với vị trí tính từ đầu
-danh sách. Phần tử cuộn DOM bên trong dùng `scrollTop` âm (bằng 0 ở đáy); code
-đọc hoặc ghi trực tiếp thuộc tính DOM này cần tính đến khác biệt đó. Thứ tự DOM
-của tin nhắn vẫn từ cũ đến mới.
+được cập nhật trong cây chỉ mục theo key. Append, prepend, đo chiều cao, tìm
+offset và key thông thường có độ phức tạp `O(log n)` cho mỗi tin thay đổi; thay
+thế, xóa hoặc sắp xếp tùy ý sẽ dựng lại index.
+Nên thay cả array `items` khi sửa dữ liệu tùy ý. Nếu ứng dụng bắt buộc mutate
+cùng một array, hãy tăng `itemsVersion` (hoặc gọi `refresh()`) sau thao tác xóa/
+sắp xếp không đổi độ dài. Cách này giữ được hiệu năng mà không cần deep watcher
+`O(n)` chạy sau mọi tin nhắn mới.
+
+Dùng các method qua ref, `getScrollPosition()` và sự kiện `scroll` để thao tác
+với offset dương tính từ đầu danh sách. Phần tử DOM bên trong dùng `scrollTop`
+âm (bằng 0 ở đáy) nhằm giữ momentum native khi prepend; code sử dụng component
+không nên đọc hoặc ghi trực tiếp thuộc tính này. Thứ tự DOM vẫn từ cũ đến mới.
 
 Để chat có ảnh/video cuộn mượt, hãy dành sẵn kích thước bằng `width`, `height`
 hoặc `aspect-ratio`, đặt chiều cao ước lượng gần thực tế và tránh giới hạn `size`
@@ -581,11 +590,13 @@ kế tiếp trước khi người dùng chạm tin cũ nhất đã có; virtuali
 | Prop | Kiểu | Mặc định | Mô tả |
 | --- | --- | --- | --- |
 | `items` | `readonly T[]` | bắt buộc | Tin nhắn được sắp từ cũ nhất tới mới nhất. |
+| `itemsVersion` | `PropertyKey` | không đặt | Tăng giá trị sau mutation tại chỗ tùy ý không đổi reference/độ dài. Không cần dùng khi thay array theo kiểu immutable. |
 | `estimatedItemSize` | `number` | `48` | Chiều cao trung bình ban đầu của tin nhắn, tính bằng pixel. |
+| `estimateItemSize` | `(item, index) => number` | không đặt | Ước lượng riêng cho từng tin chưa đo, hữu ích khi text và media chênh lệch chiều cao lớn. |
 | `height` | `number \| string` | `400` | Chiều cao viewport. Số được hiểu là pixel; `"fill"` tương đương `100%`. |
 | `overscan` | `number` | `5` | Số tin nhắn mount thêm trước và sau vùng đang hiển thị. |
 | `size` | `number` | không đặt | Giới hạn tổng số tin nhắn render, bao gồm overscan, ví dụ `:size="12"` cho mobile. Giảm overscan trước; luôn render đủ vùng nhìn dù phải vượt `size`. Không tăng số tin nhắn vượt phạm vi `overscan`. Số dương được làm tròn xuống (tối thiểu 1); số không dương hoặc không hữu hạn sẽ tắt giới hạn. |
-| `itemKey` | `keyof T \| (item, index) => PropertyKey` | `id`, `key` hoặc index | Định danh ổn định, đặc biệt quan trọng khi thêm vào đầu. |
+| `itemKey` | `keyof T \| (item, index) => PropertyKey` | `id`, `key` hoặc identity của item | Định danh ổn định và duy nhất, đặc biệt quan trọng khi thêm vào đầu. Key trùng sẽ báo lỗi ngay thay vì làm hỏng anchor. |
 | `ariaLabel` | `string` | `"Chat messages"` | Nhãn hỗ trợ khả năng tiếp cận cho live log. |
 | `stickToBottom` | `boolean` | `true` | Bám theo tin nhắn mới nếu hiện tại đang gần cuối. |
 | `bottomThreshold` | `number` | `80` | Khoảng cách vẫn được xem là “ở cuối”, tính bằng pixel. |
@@ -593,6 +604,18 @@ kế tiếp trước khi người dùng chạm tin cũ nhất đã có; virtuali
 | `hasOlder` | `boolean` | `false` | Cho biết vẫn còn lịch sử cũ. |
 | `loadingOlder` | `boolean` | `false` | Ngăn request trùng và hiển thị indicator phía trên. |
 | `loadOlderThreshold` | `number` | `120` | Khoảng cách tới đầu để emit `load-older`, tính bằng pixel. |
+| `scrollEndDelay` | `number` | `150` | Thời gian chờ fallback tính bằng ms khi trình duyệt không có `scrollend` ổn định. |
+| `syncMeasurement` | `boolean` | `true` | Đo hàng mới trước paint. Đặt false để tránh đọc layout đồng bộ và chỉ dùng `ResizeObserver`. |
+| `pinnedKeys` | `readonly PropertyKey[]` | `[]` | Các tin nhắn luôn được mount để giữ state cục bộ. |
+| `maxPinnedItems` | `number` | `20` | Số key pin tối đa được giữ lại. |
+| `keepFocusedItem` | `boolean` | `true` | Giữ DOM của tin nhắn đang chứa keyboard focus dù ra ngoài viewport. |
+| `showNewItemsIndicator` | `boolean` | `true` | Hiển thị nút tin nhắn mới khi người dùng đang đọc lịch sử. |
+| `newItemsLabel` | `(count) => string` | nhãn tiếng Anh | Bản địa hóa nút tin nhắn mới mặc định mà không cần thay slot. |
+| `forceStickToBottom` | `(item, index) => boolean` | không đặt | Luôn bám đáy với tin append được chọn, thường dùng cho tin do người dùng hiện tại gửi. |
+| `contain` | `boolean` | `true` | Bật containment layout/paint; tắt nếu overlay không dùng `Teleport` cần tràn ra ngoài. |
+
+Tin nhắn được pin và tin đang chứa keyboard focus được render thêm ngoài giới
+hạn `size`. Nên giữ `pinnedKeys` nhỏ; `maxPinnedItems` không giới hạn tin đang focus.
 
 #### Slots
 
@@ -601,6 +624,7 @@ kế tiếp trước khi người dùng chạm tin cũ nhất đã có; virtuali
 | `default` | `{ item, index }` | Render từng tin nhắn đang được mount. |
 | `empty` | không có | Render khi chưa có tin nhắn. |
 | `loadingOlder` | không có | Status sticky phía trên; mặc định “Loading older messages…”. |
+| `newItems` | `{ count, scrollToBottom }` | Tùy chỉnh nút tin nhắn mới nổi phía dưới. |
 
 #### Events
 
@@ -609,14 +633,23 @@ kế tiếp trước khi người dùng chạm tin cũ nhất đã có; virtuali
 | `scroll` | `{ scrollTop, startIndex, endIndex }` | Khi container cuộn. | `@scroll="onScroll"` |
 | `load-older` | không có | Gần đầu khi `hasOlder` là true và `loadingOlder` là false. | `@load-older="loadOlder"` |
 | `bottom-change` | `boolean` | Khi viewport đi vào hoặc rời ngưỡng ở cuối. | `@bottom-change="onBottomChange"` |
+| `scrolling-change` | `boolean` | Khi thao tác cuộn của người dùng bắt đầu hoặc dừng. | `@scrolling-change="onScrollingChange"` |
+| `new-items-change` | `number` | Khi số tin append chưa được xem ở đáy thay đổi. | `@new-items-change="onNewItemsChange"` |
+| `visible-change` | `{ scrollTop, startIndex, endIndex }` | Khi vùng thực sự nhìn thấy thay đổi, không tính overscan; dùng để theo dõi đã đọc. | `@visible-change="markVisibleAsRead"` |
 
 #### API qua ref
 
 | Method / trạng thái | Mô tả | Ví dụ trong template |
 | --- | --- | --- |
 | `isAtBottom` | Boolean readonly cho biết người dùng có đang gần cuối hay không. | `chat?.isAtBottom` |
+| `isScrolling` | Boolean readonly cho biết người dùng đang thực hiện thao tác cuộn. | `chat?.isScrolling` |
+| `newItemsCount` | Số tin append nhận được trong lúc đang đọc lịch sử. | `chat?.newItemsCount` |
+| `clearNewItems()` | Xóa bộ đếm tin mới mà không đổi vị trí cuộn. | `chat?.clearNewItems()` |
+| `refresh()` | Đồng bộ lại key và measurement sau khi mutate tại chỗ cùng một array `items`. | `chat?.refresh()` |
+| `getScrollPosition()` | Trả về offset pixel logic dương tính từ đầu danh sách. | `chat?.getScrollPosition()` |
 | `scrollTo(position, options?)` | Cuộn tới offset pixel. | `chat?.scrollTo(200, { behavior: 'smooth' })` |
 | `scrollToIndex(index, options?)` | Cuộn tới index tin nhắn bắt đầu từ 0. | `chat?.scrollToIndex(10, { behavior: 'smooth' })` |
+| `scrollToKey(key, options?)` | Cuộn tới tin nhắn theo key ổn định. | `chat?.scrollToKey(messageId, { align: 'center' })` |
 | `scrollToTop(behavior?)` | Cuộn tới tin nhắn cũ nhất đã tải. | `chat?.scrollToTop()` |
 | `scrollToBottom(behavior?)` | Cuộn tới tin nhắn mới nhất đã tải. | `chat?.scrollToBottom('smooth')` |
 
@@ -720,6 +753,10 @@ Các phím sau hoạt động khi viewport có focus:
 | `Home` | Chuyển tới vị trí đầu. |
 | `End` | Chuyển tới item cuối. |
 
+Viewport còn chuyển cả input bánh xe chuột thành chuyển slide. Handler wheel đã
+bật sẵn trong component, parent không phải làm gì thêm. Còn touch để trackpad
+snap gốc của trình duyệt xử lý.
+
 Với feed không giới hạn, hãy tải theo trang bằng `load-more` và chỉ giữ một cửa
 sổ dữ liệu hợp lý ở component cha. Virtualization giới hạn DOM và media element
 đang mount, nhưng không xóa object khỏi `items`.
@@ -801,8 +838,51 @@ thường tối đa năm slide được mount ở giữa collection.
 | `autoplayDelay` | `number` | `3000` | Thời gian chờ giữa các lần tự động chuyển, tính bằng mili giây; giá trị dưới `1` được giới hạn và giá trị không hữu hạn dùng mặc định. |
 | `autoplayLoop` | `boolean` | `true` | Quay lại slide đầu tiên khi đến cuối. |
 | `pauseOnHover` | `boolean` | `true` | Tạm dừng autoplay khi con trỏ nằm trên carousel. |
+| `mouseDrag` | `boolean` | `true` | Cho phép giữ và kéo bằng nút chuột trái để chuyển slide trên máy tính. |
+| `dragThreshold` | `number` | `8` | Khoảng di chuyển con trỏ để nhận diện và commit thao tác kéo, tính bằng pixel. |
+| `momentum` | `boolean` | `true` | Chiếu vận tốc lúc thả thành quán tính rồi giảm tốc về slide đích. |
+| `settleDuration` | `number` | `250` | Thời lượng nền của animation drag/loop; `0` chuyển tức thì. Cuộn native qua API vẫn dùng tham số `behavior`. |
+| `nativeSnap` | `boolean` | `true` | Dùng CSS snap cho wheel/API. Đặt `false` khi lồng trong container có snap để căn slide bằng bộ điều khiển chuyển động. Loop luôn dùng cơ chế này. |
+| `autoWidth` | `boolean` | `false` | Đo chiều rộng riêng của từng slide; nội dung slot cần có chiều rộng xác định. Thay thế `slidesPerView` khi tính chiều rộng. |
+| `estimatedItemWidth` | `number` | `240` | Chiều rộng ước lượng cho slide chưa được mount khi bật `autoWidth`. |
+| `rtl` | `boolean` | `false` | Layout phải sang trái, bao gồm drag, native scroll và phím mũi tên. |
+| `loop` | `boolean` | `false` | Loop liên tục theo hai hướng, độc lập với `autoplayLoop`. Tự tắt khi toàn bộ item vừa viewport. |
+| `keepAlive` | `boolean` | `false` | Giữ instance và state cục bộ của slide đã xem trong cache giới hạn. |
+| `maxCachedItems` | `number` | `20` | Số slide cache/pin ngoài vùng render tối đa; không tính slide đang hiển thị/buffer và một slide có focus. |
+| `pinnedIndexes` | `readonly number[]` | `[]` | Giữ các index này mounted ngay cả khi `keepAlive=false`; dùng ngân sách cache ngoài vùng render. |
 | `responsive` | `ResponsiveBreakpoint[]` | `undefined` | Ghi đè số slide hiển thị, bước cuộn và khoảng cách theo breakpoint chiều rộng container. |
 
+Thao tác cảm ứng có khóa hướng: vuốt dọc tiếp tục cuộn trang, còn vuốt ngang
+di chuyển carousel và tự căn vào slide gần nhất. Trong lúc kéo, track di chuyển
+bằng `translate3d` và `activeIndex` được giữ nguyên tới khi animation drag kết thúc.
+Vùng render và `inViewport` chỉ cập nhật khi slide đi vào hoặc ra khỏi vùng nhìn.
+Khi thả nhanh, track tiếp tục theo vận tốc lúc thả rồi
+giảm tốc về 0, với quán tính giới hạn tối đa hai slide thêm. Giữ tay trước khi
+thả sẽ bỏ qua quán tính. Kéo ngang từ ngưỡng `dragThreshold` sẽ chuyển một slide ngay cả
+khi chưa đi qua nửa chiều rộng slide.
+
+Button và link giữ hành vi click bình thường. Input và phần tử có
+`data-carousel-no-drag` không bắt đầu drag; input giữ hành vi phím mũi tên riêng.
+Wheel/trackpad ngắt animation tại vị trí đang hiển thị.
+
+`autoWidth` dùng `ResizeObserver`, vị trí cộng dồn và binary search. Slide chưa
+mount dùng chiều rộng ước lượng, nên bước nhảy xa có thể được tinh chỉnh sau khi
+đo. Kết quả đo muộn được áp dụng khi drag kết thúc để giữ slide đang chọn. Nội dung
+slot cần có chiều rộng rõ ràng, ví dụ `<ProductCard :style="{ width: item.width + 'px' }" />`.
+
+`keepAlive` giữ state của input/component tới khi bị loại khỏi cache LRU. Chỉ nhóm
+slide khi chuyển động dừng mới cập nhật độ gần đây; frame trung gian không đẩy state
+của slide đích ra khỏi cache. Slide cache ngoài vùng render bị ẩn và inert.
+`pinnedIndexes` giữ media đang chạy; dùng `inViewport` để quyết định pause media.
+State cần tồn tại lâu dài vẫn nên lưu bên ngoài theo `itemKey` ổn định.
+
+`loop` di chuyển các slide có key quanh chu kỳ hiện tại, không tạo instance trùng.
+`autoplayLoop` chỉ quay về đầu khi không bật loop liên tục. Demo tắt tải thêm khi
+bật loop để biên collection cố định. Loop dùng cùng bộ điều khiển chuyển động để
+căn slide sau khi wheel dừng, tránh native snap bám theo node vừa đổi chu kỳ.
+Component vẫn hỗ trợ `load-more`. Thay đổi
+dữ liệu hoặc layout sẽ hủy chuyển động hiện tại và căn lại index đang chọn.
+
 #### Cấu hình responsive
 
 Component chọn `breakpoint` lớn nhất không vượt quá chiều rộng container của
@@ -833,7 +913,7 @@ Trường bị bỏ qua dùng prop gốc, không kế thừa từ breakpoint kh
 
 | Slot | Scope | Mô tả |
 | --- | --- | --- |
-| `default` | `{ item, index, active, visible }` | Render từng slide đang mount. |
+| `default` | `{ item, index, active, visible, inViewport }` | `active`/`visible` theo nhóm slide đã chọn; `inViewport` theo vùng nhìn thực tế trong lúc di chuyển. |
 | `empty` | không có | Render khi `items` rỗng. |
 
 #### Events
@@ -1208,6 +1288,7 @@ import type {
 | `bun run test:browser` | Chạy test trình duyệt bằng Playwright. |
 | `bun run check` | Chạy toàn bộ: unit test, build, type phía dùng package, lint package và test trình duyệt. |
 | `npm pack --dry-run` | Kiểm tra các file sẽ được publish. |
+| `npm publish --access public` | Publish package public đã được cập nhật version sau khi release commit sẵn sàng. |
 | `prepublishOnly` | Tự chạy `bun run check` trước khi publish. |
 
 ```bash
@@ -1219,8 +1300,8 @@ bun run check
 
 Playground có các demo riêng cho chiều cao cố định, chiều cao động, cuộn theo
 cửa sổ, chat, load-more, short-media và carousel. Trước khi publish, hãy chạy
-thêm `npm pack --dry-run`. GitHub Release được publish qua
-`.github/workflows/publish.yml`.
+thêm `npm pack --dry-run`. Sau đó commit release, chạy
+`npm publish --access public`, rồi tạo và push Git tag tương ứng.
 
 ## Đóng góp
 

package/dist/components/ChatVirtualScroll.d.cts

@@ -4,9 +4,15 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
         readonly onScroll?: ((event: VirtualScrollEvent) => any) | undefined;
         readonly onLoadOlder?: (() => any) | undefined;
         readonly onBottomChange?: ((isAtBottom: boolean) => any) | undefined;
-    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onScroll" | "onLoadOlder" | "onBottomChange"> & {
+        readonly onScrollingChange?: ((isScrolling: boolean) => any) | undefined;
+        readonly onNewItemsChange?: ((count: number) => any) | undefined;
+        readonly onVisibleChange?: ((event: VirtualScrollEvent) => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onScroll" | "onLoadOlder" | "onBottomChange" | "onScrollingChange" | "onNewItemsChange" | "onVisibleChange"> & {
         items: readonly T[];
+        /** Increment after mutating/reordering the same array instance in place. */
+        itemsVersion?: PropertyKey;
         estimatedItemSize?: number;
+        estimateItemSize?: (item: T, index: number) => number;
         height?: number | string;
         overscan?: number;
         /** Render budget including overscan; always keeps the viewport filled. */
@@ -19,13 +25,30 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
         hasOlder?: boolean;
         loadingOlder?: boolean;
         loadOlderThreshold?: number;
+        scrollEndDelay?: number;
+        syncMeasurement?: boolean;
+        pinnedKeys?: readonly PropertyKey[];
+        maxPinnedItems?: number;
+        keepFocusedItem?: boolean;
+        showNewItemsIndicator?: boolean;
+        newItemsLabel?: (count: number) => string;
+        forceStickToBottom?: (item: T, index: number) => boolean;
+        contain?: boolean;
     } & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<{
         isAtBottom: import('vue').Ref<boolean, boolean>;
+        isScrolling: import('vue').Ref<boolean, boolean>;
+        newItemsCount: import('vue').Ref<number, number>;
+        clearNewItems: () => void;
+        refresh: () => void;
+        getScrollPosition: () => number;
         scrollTo: (position: number, options?: ScrollToOptions) => void;
         scrollToIndex: (index: number, options?: ScrollToOptions & {
             align?: ScrollAlignment;
         }) => void;
+        scrollToKey: (key: PropertyKey, options?: ScrollToOptions & {
+            align?: ScrollAlignment;
+        }) => void;
         scrollToTop: (behavior?: ScrollBehavior) => void;
         scrollToBottom: (behavior?: ScrollBehavior) => void;
     }>): void;
@@ -37,8 +60,12 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
         }): unknown;
         empty?(): unknown;
         loadingOlder?(): unknown;
+        newItems?(props: {
+            count: number;
+            scrollToBottom: (behavior?: ScrollBehavior) => void;
+        }): unknown;
     };
-    emit: ((evt: "scroll", event: VirtualScrollEvent) => void) & ((evt: "loadOlder") => void) & ((evt: "bottomChange", isAtBottom: boolean) => void);
+    emit: ((evt: "scroll", event: VirtualScrollEvent) => void) & ((evt: "loadOlder") => void) & ((evt: "bottomChange", isAtBottom: boolean) => void) & ((evt: "scrollingChange", isScrolling: boolean) => void) & ((evt: "newItemsChange", count: number) => void) & ((evt: "visibleChange", event: VirtualScrollEvent) => void);
 }>) => import('vue').VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };

package/dist/components/ChatVirtualScroll.d.ts

@@ -4,9 +4,15 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
         readonly onScroll?: ((event: VirtualScrollEvent) => any) | undefined;
         readonly onLoadOlder?: (() => any) | undefined;
         readonly onBottomChange?: ((isAtBottom: boolean) => any) | undefined;
-    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onScroll" | "onLoadOlder" | "onBottomChange"> & {
+        readonly onScrollingChange?: ((isScrolling: boolean) => any) | undefined;
+        readonly onNewItemsChange?: ((count: number) => any) | undefined;
+        readonly onVisibleChange?: ((event: VirtualScrollEvent) => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onScroll" | "onLoadOlder" | "onBottomChange" | "onScrollingChange" | "onNewItemsChange" | "onVisibleChange"> & {
         items: readonly T[];
+        /** Increment after mutating/reordering the same array instance in place. */
+        itemsVersion?: PropertyKey;
         estimatedItemSize?: number;
+        estimateItemSize?: (item: T, index: number) => number;
         height?: number | string;
         overscan?: number;
         /** Render budget including overscan; always keeps the viewport filled. */
@@ -19,13 +25,30 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
         hasOlder?: boolean;
         loadingOlder?: boolean;
         loadOlderThreshold?: number;
+        scrollEndDelay?: number;
+        syncMeasurement?: boolean;
+        pinnedKeys?: readonly PropertyKey[];
+        maxPinnedItems?: number;
+        keepFocusedItem?: boolean;
+        showNewItemsIndicator?: boolean;
+        newItemsLabel?: (count: number) => string;
+        forceStickToBottom?: (item: T, index: number) => boolean;
+        contain?: boolean;
     } & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<{
         isAtBottom: import('vue').Ref<boolean, boolean>;
+        isScrolling: import('vue').Ref<boolean, boolean>;
+        newItemsCount: import('vue').Ref<number, number>;
+        clearNewItems: () => void;
+        refresh: () => void;
+        getScrollPosition: () => number;
         scrollTo: (position: number, options?: ScrollToOptions) => void;
         scrollToIndex: (index: number, options?: ScrollToOptions & {
             align?: ScrollAlignment;
         }) => void;
+        scrollToKey: (key: PropertyKey, options?: ScrollToOptions & {
+            align?: ScrollAlignment;
+        }) => void;
         scrollToTop: (behavior?: ScrollBehavior) => void;
         scrollToBottom: (behavior?: ScrollBehavior) => void;
     }>): void;
@@ -37,8 +60,12 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
         }): unknown;
         empty?(): unknown;
         loadingOlder?(): unknown;
+        newItems?(props: {
+            count: number;
+            scrollToBottom: (behavior?: ScrollBehavior) => void;
+        }): unknown;
     };
-    emit: ((evt: "scroll", event: VirtualScrollEvent) => void) & ((evt: "loadOlder") => void) & ((evt: "bottomChange", isAtBottom: boolean) => void);
+    emit: ((evt: "scroll", event: VirtualScrollEvent) => void) & ((evt: "loadOlder") => void) & ((evt: "bottomChange", isAtBottom: boolean) => void) & ((evt: "scrollingChange", isScrolling: boolean) => void) & ((evt: "newItemsChange", count: number) => void) & ((evt: "visibleChange", event: VirtualScrollEvent) => void);
 }>) => import('vue').VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };