@vunk/plus 1.15.0 → 1.16.1

package/vue-virtual-scroller/src/engine/cache.d.ts

@@ -0,0 +1,8 @@
+import type { CacheSnapshot, KeyFieldValue, ScrollAlign } from '../types';
+export declare function getItemKey(item: unknown, index: number, keyField: KeyFieldValue<any> | null): string | number;
+export declare function getItemKeys(items: unknown[], keyField: KeyFieldValue<any> | null): Array<string | number>;
+export declare function buildCacheSnapshot(items: unknown[], keyField: KeyFieldValue<any> | null, getSize: (item: unknown, index: number, key: string | number) => number | undefined): CacheSnapshot;
+export declare function isCacheSnapshotCompatible(snapshot: CacheSnapshot | null | undefined, items: unknown[], keyField: KeyFieldValue<any> | null): snapshot is CacheSnapshot;
+export declare function restoreCacheMap(snapshot: CacheSnapshot | null | undefined, items: unknown[], keyField: KeyFieldValue<any> | null): Record<string | number, number>;
+export declare function findPrependOffset(previousKeys: Array<string | number>, nextKeys: Array<string | number>): number;
+export declare function getAlignedScrollOffset(itemStart: number, itemSize: number, viewportStart: number, viewportSize: number, align: ScrollAlign | undefined, offset?: number): number | null;

package/vue-virtual-scroller/src/engine/keyField.d.ts

@@ -0,0 +1,13 @@
+import type { KeyFieldValue, KeyValue } from '../types';
+/**
+ * Formats a keyField value for human-readable error messages.
+ */
+export declare function formatKeyField(keyField: KeyFieldValue<any> | null): string;
+/**
+ * Resolves the stable key for a list item from either a property name or a callback.
+ */
+export declare function resolveItemKey<TItem>(item: TItem, index: number, keyField: KeyFieldValue<TItem> | null): KeyValue;
+/**
+ * Resolves an object-item key when an index is available or can be ignored by the resolver.
+ */
+export declare function resolveItemKeyWithOptionalIndex<TItem>(item: TItem, index: number | undefined, keyField: KeyFieldValue<TItem>): KeyValue;

package/vue-virtual-scroller/src/engine/scroll.d.ts

@@ -0,0 +1,14 @@
+import type { ScrollDirection, ScrollToOptions } from '../types';
+export declare function normalizeOffset(offset: number, direction: ScrollDirection, target: HTMLElement | Window | null | undefined): number;
+export declare function denormalizeOffset(offset: number, direction: ScrollDirection, target: HTMLElement | Window | null | undefined): number;
+export declare function scrollElementTo(target: HTMLElement | Window, direction: ScrollDirection, position: number, options?: ScrollToOptions): void;
+/**
+ * Resolve the viewport size used to decide which items should be rendered.
+ *
+ * In page mode the viewport is the scroll parent (typically `window`, or a
+ * scrollable ancestor element when supplied). Outside page mode it is the
+ * scroller's own root element. The `scrollParent` argument lets callers opt
+ * into a custom HTMLElement viewport (issue #928) — without it page mode
+ * keeps its legacy `window.innerHeight/Width` reading.
+ */
+export declare function getViewportSize(el: HTMLElement, direction: ScrollDirection, pageMode: boolean, scrollParent?: HTMLElement | Window): number;

package/vue-virtual-scroller/src/index.d.ts

@@ -0,0 +1,25 @@
+import type { App } from 'vue';
+import type { PluginOptions } from './types';
+import './components/scroller.css';
+import DynamicScroller from './components/DynamicScroller.vue';
+import DynamicScrollerItem from './components/DynamicScrollerItem.vue';
+import RecycleScroller from './components/RecycleScroller.vue';
+import WindowScroller from './components/WindowScroller.vue';
+export { useDynamicScroller } from './composables/useDynamicScroller';
+export type { UseDynamicScrollerItemBindingOptions, UseDynamicScrollerOptions, UseDynamicScrollerReturn } from './composables/useDynamicScroller';
+export { useDynamicScrollerItem } from './composables/useDynamicScrollerItem';
+export type { UseDynamicScrollerItemOptions, UseDynamicScrollerItemReturn } from './composables/useDynamicScrollerItem';
+export { useIdState } from './composables/useIdState';
+export { useRecycleScroller } from './composables/useRecycleScroller';
+export type { UseRecycleScrollerOptions, UseRecycleScrollerReturn } from './composables/useRecycleScroller';
+export { useTableColumnWidths } from './composables/useTableColumnWidths';
+export type { UseTableColumnWidthsOptions, UseTableColumnWidthsReturn } from './composables/useTableColumnWidths';
+export { useWindowScroller } from './composables/useWindowScroller';
+export type { UseWindowScrollerOptions, UseWindowScrollerReturn } from './composables/useWindowScroller';
+export { DynamicScroller, DynamicScrollerItem, RecycleScroller, WindowScroller, };
+export type * from './types';
+declare const plugin: {
+    version: string;
+    install(app: App, options?: PluginOptions): void;
+};
+export default plugin;

package/vue-virtual-scroller/src/scrollparent.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Walk the DOM tree starting from `node`'s parent and return the first
+ * ancestor whose computed `overflow*` allows scrolling. Falls back to the
+ * document's scrolling element (typically `<html>`) when no ancestor scrolls.
+ *
+ * @param node - The element whose scroll parent should be resolved.
+ * @returns The first scrollable ancestor, or the document scrolling element.
+ */
+export declare function getScrollParent(node: Node): Element | undefined;
+/**
+ * Resolve the scroll-parent target used by the scroller's pageMode paths.
+ *
+ * Combines the auto-detection of `getScrollParent` with an optional explicit
+ * override and normalizes html/body to `window`, so callers get a single
+ * "target" they can listen on AND measure against (geometry math reads the
+ * returned target's rect; for `window` it uses `innerHeight/innerWidth`).
+ *
+ * @param node - The scroller's root element. Used as the start of the DOM
+ *   walk when no override is provided.
+ * @param override - Optional explicit scroll-parent. Accepts either an
+ *   `HTMLElement` or `Window`. When `undefined`, falls back to auto-detection.
+ * @returns A `Window` or `HTMLElement` to listen on and measure against.
+ *   Returns `undefined` only when `node` is not a host element AND no
+ *   override was supplied — callers should fall back to `window` in that
+ *   case (matches the legacy behavior in `useRecycleScroller`).
+ */
+export declare function resolveScrollParent(node: Node | undefined, override?: HTMLElement | Window): Window | HTMLElement | undefined;

package/vue-virtual-scroller/src/typecheck/generic-components.typecheck.vue.d.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/vue-virtual-scroller/src/typecheck/generic-composables.typecheck.d.ts

@@ -0,0 +1 @@
+export {};

package/vue-virtual-scroller/src/types.d.ts

@@ -0,0 +1,139 @@
+import type { ComputedRef, Ref } from 'vue';
+export type ScrollDirection = 'vertical' | 'horizontal';
+export type ScrollAlign = 'start' | 'center' | 'end' | 'nearest';
+export type KeyValue = string | number;
+export type KeyFieldResolver<TItem = unknown> = (item: TItem, index: number) => KeyValue;
+export type KeyFieldValue<TItem = unknown> = string | KeyFieldResolver<TItem>;
+export type ItemSizeResolver<TItem = unknown> = (item: TItem, index: number) => number;
+export type ItemSizeValue<TItem = unknown> = number | null | ItemSizeResolver<TItem>;
+export type StringKeyOf<T> = Extract<keyof T, string>;
+/**
+ * Default key-field shape for generic option helpers.
+ * Keep valid object field names plus resolver functions, instead of freezing to `'id'`.
+ */
+export type DefaultKeyField<TItem> = TItem extends object ? StringKeyOf<TItem> | KeyFieldResolver<TItem> : string;
+export type ValidKeyField<TItem, TKeyField extends KeyFieldValue<TItem>> = TItem extends object ? TKeyField extends KeyFieldResolver<TItem> ? TKeyField : TKeyField extends StringKeyOf<TItem> ? TKeyField : never : string;
+export type NumericFieldKey<TItem> = TItem extends object ? Extract<{
+    [K in StringKeyOf<TItem>]-?: Exclude<TItem[K], undefined> extends number ? K : never;
+}[StringKeyOf<TItem>], string> : string;
+export type ValidSizeField<TItem, TSizeField extends string> = TItem extends object ? [NumericFieldKey<TItem>] extends [never] ? string : TSizeField extends NumericFieldKey<TItem> ? TSizeField : never : string;
+export type ItemKey<TItem, TKeyField extends KeyFieldValue<TItem> = 'id'> = TItem extends object ? TKeyField extends KeyFieldResolver<TItem> ? Extract<ReturnType<TKeyField>, KeyValue> : Extract<TKeyField extends keyof TItem ? TItem[TKeyField] : never, KeyValue> : number;
+export type ClassValue = string | Record<string, boolean> | Array<string | Record<string, boolean>>;
+export interface ScrollToOptions {
+    align?: ScrollAlign;
+    smooth?: boolean;
+    offset?: number;
+}
+export interface ScrollState {
+    start: number;
+    end: number;
+}
+export interface ViewNonReactive<TKey = KeyValue> {
+    id: number;
+    index: number;
+    used: boolean;
+    key: TKey;
+    type: unknown;
+}
+export interface View<TItem = unknown, TKey = KeyValue> {
+    item: TItem;
+    position: number;
+    offset: number;
+    nr: ViewNonReactive<TKey>;
+}
+/**
+ * Public pooled-view shape exposed by `useDynamicScroller`.
+ * It flattens common render fields while still exposing measured metadata.
+ */
+export interface DynamicScrollerView<TItem = unknown, TKey = KeyValue> {
+    item: TItem;
+    itemWithSize: ItemWithSize<TItem, TKey>;
+    size: number | undefined;
+    position: number;
+    offset: number;
+    id: number;
+    index: number;
+    used: boolean;
+    key: TKey;
+    type: unknown;
+}
+export interface CacheSnapshot {
+    keys: KeyValue[];
+    sizes: Array<number | null>;
+}
+export interface SizeEntry {
+    accumulator: number;
+    size?: number;
+}
+export interface Sizes {
+    [key: number]: SizeEntry;
+}
+export interface VScrollData {
+    active: boolean;
+    sizes: Record<KeyValue, number>;
+    keyField: KeyFieldValue<any>;
+    simpleArray: boolean;
+}
+export interface ItemWithSize<TItem = unknown, TKey = KeyValue> {
+    item: TItem;
+    id: TKey;
+    size: number | undefined;
+}
+export interface RecycleScrollerSlotProps<TItem = unknown> {
+    item: TItem;
+    index: number;
+    active: boolean;
+}
+export interface DynamicScrollerSlotProps<TItem = unknown, TKey = KeyValue> extends RecycleScrollerSlotProps<TItem> {
+    itemWithSize: ItemWithSize<TItem, TKey>;
+}
+export interface RecycleScrollerExposed<TItem = unknown, TKey = KeyValue> {
+    el: Ref<HTMLElement | undefined>;
+    visiblePool: ComputedRef<Array<View<TItem, TKey>>>;
+    startSpacerSize: Ref<number>;
+    endSpacerSize: Ref<number>;
+    scrollToItem: (index: number, options?: ScrollToOptions) => void;
+    scrollToPosition: (position: number, options?: ScrollToOptions) => void;
+    getScroll: () => ScrollState;
+    findItemIndex: (offset: number) => number;
+    getItemOffset: (index: number) => number;
+    getItemSize: (index: number) => number;
+    cacheSnapshot: ComputedRef<CacheSnapshot>;
+    restoreCache: (snapshot: CacheSnapshot | null | undefined) => boolean;
+    updateVisibleItems: (itemsChanged: boolean, checkPositionDiff?: boolean) => {
+        continuous: boolean;
+    };
+}
+export interface DynamicScrollerExposed<TItem = unknown> {
+    startSpacerSize: Ref<number>;
+    endSpacerSize: Ref<number>;
+    scrollToItem: (index: number, options?: ScrollToOptions) => void;
+    scrollToPosition: (position: number, options?: ScrollToOptions) => void;
+    findItemIndex: (offset: number) => number;
+    getItemOffset: (index: number) => number;
+    scrollToBottom: () => void;
+    getItemSize: (item: TItem, index?: number) => number;
+    cacheSnapshot: ComputedRef<CacheSnapshot>;
+    restoreCache: (snapshot: CacheSnapshot | null | undefined) => boolean;
+    forceUpdate: (clear?: boolean) => void;
+}
+export interface WindowScrollerExposed<TItem = unknown, TKey = KeyValue> {
+    el: Ref<HTMLElement | undefined>;
+    startSpacerSize: Ref<number>;
+    endSpacerSize: Ref<number>;
+    scrollToItem: (index: number, options?: ScrollToOptions) => void;
+    scrollToPosition: (position: number, options?: ScrollToOptions) => void;
+    getScroll: () => ScrollState;
+    findItemIndex: (offset: number) => number;
+    getItemOffset: (index: number) => number;
+    getItemSize: (index: number) => number;
+    cacheSnapshot: ComputedRef<CacheSnapshot>;
+    restoreCache: (snapshot: CacheSnapshot | null | undefined) => boolean;
+    updateVisibleItems: (itemsChanged: boolean, checkPositionDiff?: boolean) => {
+        continuous: boolean;
+    };
+}
+export interface PluginOptions {
+    installComponents?: boolean;
+    componentsPrefix?: string;
+}

package/vue-virtual-scroller/src/utils/eventEmitter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Event payload map keyed by event name.
+ */
+export type EventMap = object;
+/**
+ * Event handler for one payload shape.
+ */
+export type EventHandler<TEvent> = (event: TEvent) => void;
+/**
+ * Tiny typed emitter used for internal package coordination.
+ */
+export interface EventEmitter<TEvents extends EventMap> {
+    on: <TKey extends keyof TEvents>(type: TKey, handler: EventHandler<TEvents[TKey]>) => void;
+    off: <TKey extends keyof TEvents>(type: TKey, handler: EventHandler<TEvents[TKey]>) => void;
+    emit: <TKey extends keyof TEvents>(type: TKey, event: TEvents[TKey]) => void;
+    clear: () => void;
+}
+/**
+ * Create lightweight event emitter without external runtime dependency.
+ */
+export declare function createEventEmitter<TEvents extends EventMap>(): EventEmitter<TEvents>;

package/vue-virtual-scroller/src/utils/itemSize.d.ts

@@ -0,0 +1,13 @@
+import type { ItemSizeValue } from '../types';
+/**
+ * Return numeric fixed item size when scroller runs in fixed-size mode.
+ */
+export declare function getFixedItemSize<TItem>(itemSize: ItemSizeValue<TItem>): number | null;
+/**
+ * Resolve serializable size value for cache snapshots.
+ */
+export declare function resolveSnapshotItemSize<TItem>(item: TItem, index: number, itemSize: ItemSizeValue<TItem>, restoredSize: number | undefined, sizeField?: string): number | undefined;
+/**
+ * Resolve runtime size for variable-size mode, with safety fallback.
+ */
+export declare function resolveVariableItemSize<TItem>(item: TItem, index: number, itemSize: ItemSizeValue<TItem>, restoredSize: number | undefined, minItemSize: number | string | null | undefined, sizeField?: string): number;

package/vue-virtual-scroller/src/utils/viewStyle.d.ts

@@ -0,0 +1,29 @@
+import type { CSSProperties } from 'vue';
+import type { ScrollDirection, View } from '../types';
+/**
+ * Supported pooled-view positioning modes.
+ */
+export type PooledViewPositionMode = 'transform' | 'position' | 'flow';
+/**
+ * Shared style inputs for pooled view positioning.
+ */
+export interface PooledViewStyleOptions {
+    direction: ScrollDirection;
+    mode?: PooledViewPositionMode;
+    itemSize?: number | null;
+    gridItems?: number;
+    itemSecondarySize?: number;
+}
+/**
+ * Resolve pooled-view positioning mode from public options.
+ */
+export declare function resolvePooledViewMode(options: {
+    direction: ScrollDirection;
+    disableTransform?: boolean;
+    flowMode?: boolean;
+    gridItems?: number;
+}): PooledViewPositionMode;
+/**
+ * Build deterministic inline styles for a pooled view.
+ */
+export declare function getPooledViewStyle<TItem, TKey>(view: View<TItem, TKey>, options: PooledViewStyleOptions): CSSProperties;

package/vue-virtual-scroller/src/utils.d.ts

@@ -0,0 +1 @@
+export declare function supportsPassive(): boolean;

package/vue-virtual-scroller/vue-virtual-scroller.css

@@ -0,0 +1 @@
+.vue-recycle-scroller__resize-observer[data-v-08cc04ab]{position:absolute;inset:0;opacity:0;pointer-events:none;z-index:-1}.vue-recycle-scroller{position:relative}.vue-recycle-scroller.flow-mode{overflow-anchor:none}.vue-recycle-scroller.direction-vertical:not(.page-mode){overflow-y:auto}.vue-recycle-scroller.direction-horizontal:not(.page-mode){overflow-x:auto}.vue-recycle-scroller.grid-mode:not(.page-mode){overflow:auto}.vue-recycle-scroller.direction-horizontal{display:flex}.vue-recycle-scroller__slot{flex:auto 0 0}.vue-recycle-scroller__item-wrapper{flex:1;box-sizing:border-box;overflow:hidden;position:relative}.vue-recycle-scroller.flow-mode .vue-recycle-scroller__item-wrapper{overflow:visible;overflow-anchor:none}.vue-recycle-scroller.ready .vue-recycle-scroller__item-view{position:absolute;top:0;left:0;will-change:transform}.vue-recycle-scroller.ready.flow-mode .vue-recycle-scroller__item-view{position:static;top:auto;left:auto;will-change:auto;overflow-anchor:none}.vue-recycle-scroller.direction-vertical .vue-recycle-scroller__item-wrapper{width:100%}.vue-recycle-scroller.direction-horizontal .vue-recycle-scroller__item-wrapper{height:100%}.vue-recycle-scroller.ready.direction-vertical .vue-recycle-scroller__item-view{width:100%}.vue-recycle-scroller.ready.direction-horizontal .vue-recycle-scroller__item-view{height:100%}.vue-recycle-scroller__item-spacer{box-sizing:border-box;flex:0 0 auto;padding:0;margin:0;border:0;visibility:hidden;pointer-events:none;overflow-anchor:none}