@juspay/blend-design-system 0.0.19 → 0.0.20-beta

package/dist/components/Charts/ChartUtils.d.ts

@@ -1,4 +1,4 @@
-import { NewNestedDataPoint, FlattenedDataPoint, AxisType, XAxisConfig } from './types';
+import { NewNestedDataPoint, FlattenedDataPoint, AxisConfig } from './types';
 export declare function transformNestedData(data: NewNestedDataPoint[], selectedKeys?: string[]): FlattenedDataPoint[];
 export declare function transformScatterData(data: NewNestedDataPoint[], selectedKeys?: string[]): Array<{
     name: string;
@@ -9,7 +9,94 @@ export declare function transformScatterData(data: NewNestedDataPoint[], selecte
 export declare function lightenHexColor(hex: string, amount?: number): string;
 export declare const formatNumber: (value: number | string) => string;
 export declare const capitaliseCamelCase: (text: string) => string;
-export declare const createSmartDateTimeFormatter: (timeZone?: string, hour12?: boolean, showYear?: boolean) => ((value: string | number) => string);
-export declare const getAxisFormatterWithConfig: (axisType: AxisType, dateOnly?: boolean, smart?: boolean, timeZone?: string, hour12?: boolean, showYear?: boolean, forTooltip?: boolean) => ((value: string | number) => string);
-export declare const createStableSmartFormatter: (xAxisConfig: XAxisConfig, flattenedData: FlattenedDataPoint[]) => ((value: string | number) => string) | undefined;
-export declare const getAxisFormatter: (axisType: AxisType, timeZone?: string, hour12?: boolean) => ((value: string | number) => string);
+export type DateTimeFormatterOptions = {
+    useUTC?: boolean;
+    formatString?: string;
+    dateOnly?: boolean;
+    timeOnly?: boolean;
+    showYear?: boolean;
+    smartDateTimeFormat?: boolean;
+};
+/**
+ * Creates a DateTime formatter with custom options
+ * @param options - Configuration options for the formatter
+ * @param options.useUTC - Whether to use UTC timezone (default: true)
+ * @param options.formatString - Optional custom format string
+ * @param options.dateOnly - Show only dates (e.g., "1. Oct", "2. Oct")
+ * @param options.timeOnly - Show only times (e.g., "12:00", "13:00")
+ * @param options.showYear - Include year in the output (works with dateOnly and default mode)
+ * @param options.smartDateTimeFormat - Alternates between date and time like Highcharts
+ * @returns A formatter function that handles timestamps from any timezone
+ *
+ * @example
+ * // Date only without year: "1. Oct" "2. Oct" "3. Oct"
+ * createDateTimeFormatter({ dateOnly: true, showYear: false })
+ *
+ * @example
+ * // Date only with year: "1. Oct 2024" "2. Oct 2024"
+ * createDateTimeFormatter({ dateOnly: true, showYear: true })
+ *
+ * @example
+ * // Time only: "00:00" "06:00" "12:00"
+ * createDateTimeFormatter({ timeOnly: true })
+ *
+ * @example
+ * // Smart format (alternates): "1. Oct" "12:00" "2. Oct" "12:00"
+ * createDateTimeFormatter({ smartDateTimeFormat: true })
+ *
+ * @example
+ * // Default with year: "1 Oct 2024, 12:00"
+ * createDateTimeFormatter({ showYear: true })
+ */
+export declare const createDateTimeFormatter: (options?: DateTimeFormatterOptions) => ((value: string | number) => string);
+/**
+ * Get a formatter function based on axis type with optional DateTime customization
+ * @param axisType - The type of axis (DATE_TIME, CURRENCY, PERCENTAGE, NUMBER)
+ * @param dateTimeOptions - Options for DateTime formatting (only used when axisType is DATE_TIME)
+ * @returns A formatter function for the specified axis type
+ *
+ * @example
+ * // Simple usage with default UTC
+ * getAxisFormatter(AxisType.DATE_TIME)
+ *
+ * @example
+ * // Date only without year
+ * getAxisFormatter(AxisType.DATE_TIME, { dateOnly: true })
+ *
+ * @example
+ * // Date only with year
+ * getAxisFormatter(AxisType.DATE_TIME, { dateOnly: true, showYear: true })
+ *
+ * @example
+ * // Time only
+ * getAxisFormatter(AxisType.DATE_TIME, { timeOnly: true })
+ *
+ * @example
+ * // Local timezone instead of UTC
+ * getAxisFormatter(AxisType.DATE_TIME, { useUTC: false })
+ */
+export declare const getAxisFormatter: (finalAxis: AxisConfig) => ((value: string | number) => string);
+/**
+ * Suggests an optimal tick interval based on the data range
+ * Automatically determines whether to use minutes, hours, days, etc.
+ */
+export declare function getSuggestedTickInterval(data: NewNestedDataPoint[], maxTicks?: number): {
+    interval: number;
+    description: string;
+    unit: string;
+};
+/**
+ * Generates consistent, evenly-spaced tick values for datetime axes
+ * This mimics Highcharts behavior where ticks are at regular intervals
+ *
+ * @param data - Chart data with timestamps in 'name' field
+ * @param options - Configuration options
+ * @returns Object containing tick array (as strings to match data format) and formatter function
+ */
+export declare function generateConsistentDateTimeTicks(data: NewNestedDataPoint[], options?: DateTimeFormatterOptions & {
+    maxTicks?: number;
+    customInterval?: number;
+}): {
+    ticks: string[];
+    formatter: (value: string | number) => string;
+};

package/dist/components/Charts/DateTimeFormatter.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Highcharts-style DateTime Formatter Utility for Charts (Functional)
+ *
+ * This utility provides Highcharts-compatible datetime formatting for charts.
+ * It intelligently formats timestamps based on the data range and supports
+ * custom format strings similar to Highcharts' dateTimeLabelFormats.
+ */
+export declare const TIME_UNITS: {
+    readonly millisecond: 1;
+    readonly second: 1000;
+    readonly minute: 60000;
+    readonly hour: 3600000;
+    readonly day: 86400000;
+    readonly week: 604800000;
+    readonly month: 2592000000;
+    readonly year: 31536000000;
+};
+export type TimeUnit = keyof typeof TIME_UNITS;
+export declare const DEFAULT_DATE_TIME_FORMATS: Record<TimeUnit, string>;
+export interface DateTimeFormatterConfig {
+    useUTC?: boolean;
+    customFormats?: Partial<Record<TimeUnit, string>>;
+    startOfWeek?: number;
+}
+/**
+ * Parse and validate a timestamp value
+ * Handles: numbers, numeric strings, ISO strings, seconds vs milliseconds
+ */
+export declare function parseTimestamp(value: string | number): number | null;
+/**
+ * Determines the most appropriate time unit based on data range
+ */
+export declare function getTimeUnit(dataRange: number): TimeUnit;
+/**
+ * Get time unit from an array of timestamps
+ */
+export declare function getTimeUnitFromData(timestamps: number[]): TimeUnit;
+/**
+ * Normalize timestamp to the nearest time unit boundary
+ * This ensures consistent tick positioning like Highcharts
+ */
+export declare function normalizeTimestamp(timestamp: number, timeUnit: TimeUnit, config?: DateTimeFormatterConfig): number;
+/**
+ * Formats a timestamp according to a format string (Highcharts-style)
+ *
+ * Format tokens:
+ * - %Y: 4-digit year (2024)
+ * - %y: 2-digit year (24)
+ * - %m: 2-digit month (01-12)
+ * - %b: Short month name (Jan)
+ * - %B: Full month name (January)
+ * - %d: 2-digit day (01-31)
+ * - %e: Day without leading zero (1-31)
+ * - %H: 2-digit hour 24h (00-23)
+ * - %I: 2-digit hour 12h (01-12)
+ * - %M: 2-digit minute (00-59)
+ * - %S: 2-digit second (00-59)
+ * - %L: Milliseconds (000-999)
+ * - %p: AM/PM
+ * - %A: Full weekday name (Monday)
+ * - %a: Short weekday name (Mon)
+ * - %%: Literal % character
+ */
+export declare function dateFormat(formatString: string, timestamp: number, config?: DateTimeFormatterConfig): string;
+/**
+ * Get the appropriate date format for a given time unit
+ */
+export declare function getDateFormat(timeUnit: TimeUnit, config?: DateTimeFormatterConfig): string;
+/**
+ * Get optimal tick interval to prevent cluttered axes
+ * Returns recommended number of milliseconds between ticks
+ */
+export declare function getOptimalTickInterval(dataRange: number, maxTicks?: number): {
+    interval: number;
+    unit: TimeUnit;
+};
+/**
+ * Generate evenly spaced tick values for a time range
+ * This prevents cluttered axes by ensuring consistent spacing
+ */
+export declare function generateTickValues(minTimestamp: number, maxTimestamp: number, maxTicks?: number, config?: DateTimeFormatterConfig): number[];
+/**
+ * Generate ticks at a custom interval (in milliseconds)
+ * Useful for forcing specific tick spacing (e.g., every 6 hours)
+ */
+export declare function generateTicksAtInterval(minTimestamp: number, maxTimestamp: number, intervalMs: number, timeUnit?: TimeUnit, config?: DateTimeFormatterConfig): number[];
+/**
+ * Create a basic formatter function for a specific time unit
+ */
+export declare function createFormatter(timeUnit: TimeUnit, config?: DateTimeFormatterConfig): (value: number) => string;
+/**
+ * Create a formatter function for chart axes with auto time unit detection
+ */
+export declare function createAxisFormatter(timestamps: number[], config?: DateTimeFormatterConfig): (value: number) => string;
+/**
+ * Create a smart formatter that shows date on day change, time otherwise
+ * Similar to Highcharts' smart datetime formatting
+ */
+export declare function createSmartFormatter(timestamps: number[], showYear?: boolean, config?: DateTimeFormatterConfig): (value: number) => string;
+/**
+ * Create an alternating date/time formatter
+ * Shows date on even ticks, time on odd ticks (e.g., "1 Oct", "12:00", "2 Oct", "12:00")
+ */
+export declare function createAlternatingFormatter(ticks: number[], dateFormatStr?: string, timeFormatStr?: string, config?: DateTimeFormatterConfig): (value: number) => string;
+/**
+ * Format multiple timestamps
+ */
+export declare function formatMultiple(timestamps: number[], timeUnit?: TimeUnit, config?: DateTimeFormatterConfig): string[];
+/**
+ * Generate date-only ticks (for Charts dateOnly mode)
+ * Returns ticks at day boundaries with date-only labels
+ */
+export declare function createDateOnlyTicksAndFormatter(minTimestamp: number, maxTimestamp: number, maxTicks?: number, showYear?: boolean, config?: DateTimeFormatterConfig): {
+    ticks: number[];
+    formatter: (value: number) => string;
+};
+/**
+ * Generate time-only ticks spanning the entire data range
+ * Shows times at regular intervals (e.g., every 15 minutes, 1 hour, etc.)
+ */
+export declare function createTimeOnlyTicksAndFormatter(minTimestamp: number, maxTimestamp: number, intervalMinutes?: number, maxTicks?: number, config?: DateTimeFormatterConfig): {
+    ticks: number[];
+    formatter: (value: number) => string;
+};
+/**
+ * Generate ticks with alternating date and time labels
+ * Pattern: Date, Time, Date, Time, etc.
+ */
+export declare function createDateTimeAlternatingTicksAndFormatter(minTimestamp: number, maxTimestamp: number, intervalMs?: number, showYear?: boolean, maxTicks?: number, config?: DateTimeFormatterConfig): {
+    ticks: number[];
+    formatter: (value: number) => string;
+};
+/**
+ * All-in-one helper: Generate ticks and create alternating formatter
+ */
+export declare function createAlternatingTicksAndFormatter(minTimestamp: number, maxTimestamp: number, intervalMs: number, options?: {
+    timeUnit?: TimeUnit;
+    dateFormat?: string;
+    timeFormat?: string;
+}, config?: DateTimeFormatterConfig): {
+    ticks: number[];
+    formatter: (value: number) => string;
+};
+/**
+ * Create a dynamic tick generator that adapts to available width
+ * This prevents tick collision by adjusting density based on chart width
+ */
+export declare function createResponsiveTicksAndFormatter(minTimestamp: number, maxTimestamp: number, chartWidthPx: number, avgLabelWidthPx?: number, mode?: 'dateOnly' | 'timeOnly' | 'alternating' | 'smart', showYear?: boolean, config?: DateTimeFormatterConfig): {
+    ticks: number[];
+    formatter: (value: number) => string;
+};

package/dist/components/Charts/types.d.ts

@@ -67,10 +67,14 @@ export type AxisConfig = {
     tickFormatter?: (value: string | number) => string;
     customTick?: React.ComponentType<TickProps>;
     dateOnly?: boolean;
-    smart?: boolean;
-    timeZone?: string;
-    hour12?: boolean;
+    useUTC?: boolean;
+    formatString?: string;
+    timeOnly?: boolean;
     showYear?: boolean;
+    ticks?: (number | string)[];
+    autoConsistentTicks?: boolean;
+    maxTicks?: number;
+    smartDateTimeFormat?: boolean;
 };
 export type XAxisConfig = AxisConfig;
 export type YAxisConfig = AxisConfig;

package/dist/components/Menu/Menu.d.ts

@@ -2,7 +2,7 @@ import { CSSObject } from 'styled-components';
 import { MenuV2Props } from './types';
 export declare const contentBaseStyle: CSSObject;
 declare const Menu: {
-    ({ trigger, items, asModal, alignment, side, sideOffset, alignOffset, collisonBoundaryRef, maxHeight, enableSearch, searchPlaceholder, minWidth, maxWidth, open, onOpenChange, }: MenuV2Props): import("react/jsx-runtime").JSX.Element;
+    ({ trigger, items, asModal, alignment, side, sideOffset, alignOffset, collisonBoundaryRef, maxHeight, enableSearch, searchPlaceholder, minWidth, maxWidth, open, onOpenChange, enableVirtualScrolling, virtualItemHeight, virtualOverscan, virtualScrollThreshold, }: MenuV2Props): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };
 export default Menu;

package/dist/components/Menu/types.d.ts

@@ -19,6 +19,10 @@ export type MenuV2Props = {
     minWidth?: number;
     enableSearch?: boolean;
     searchPlaceholder?: string;
+    enableVirtualScrolling?: boolean;
+    virtualItemHeight?: number | ((item: MenuItemV2Type, index: number) => number);
+    virtualOverscan?: number;
+    virtualScrollThreshold?: number;
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
     asModal?: boolean;

package/dist/components/MultiSelect/MultiSelect.d.ts

@@ -1,3 +1,3 @@
 import { MultiSelectProps } from './types';
-declare const MultiSelect: ({ selectedValues, onChange, items, label, sublabel, disabled, helpIconHintText, name, required, variant, selectionTagType, slot, hintText, placeholder, size, enableSearch, searchPlaceholder, enableSelectAll, selectAllText, maxSelections, customTrigger, useDrawerOnMobile, minMenuWidth, maxMenuWidth, maxMenuHeight, alignment, side, sideOffset, alignOffset, inline, onBlur, onFocus, error, errorMessage, showActionButtons, primaryAction, secondaryAction, showItemDividers, showHeaderBorder, fullWidth, }: MultiSelectProps) => import("react/jsx-runtime").JSX.Element;
+declare const MultiSelect: ({ selectedValues, onChange, items, label, sublabel, disabled, helpIconHintText, name, required, variant, selectionTagType, slot, hintText, placeholder, size, enableSearch, searchPlaceholder, enableSelectAll, selectAllText, maxSelections, customTrigger, useDrawerOnMobile, minMenuWidth, maxMenuWidth, maxMenuHeight, alignment, side, sideOffset, alignOffset, inline, onBlur, onFocus, error, errorMessage, showActionButtons, primaryAction, secondaryAction, showItemDividers, showHeaderBorder, fullWidth, enableVirtualization, virtualListItemHeight, virtualListOverscan, itemsToRender, onEndReached, endReachedThreshold, hasMore, loadingComponent, }: MultiSelectProps) => import("react/jsx-runtime").JSX.Element;
 export default MultiSelect;

package/dist/components/MultiSelect/MultiSelectMenu.d.ts

@@ -1,3 +1,3 @@
 import { MultiSelectMenuProps } from './types';
-declare const MultiSelectMenu: ({ items, selected, onSelect, trigger, minMenuWidth, maxMenuWidth, maxMenuHeight, disabled, enableSearch, searchPlaceholder, enableSelectAll, selectAllText, maxSelections, onSelectAll, alignment, side, sideOffset, alignOffset, open, onOpenChange, showActionButtons, primaryAction, secondaryAction, }: MultiSelectMenuProps) => import("react/jsx-runtime").JSX.Element;
+declare const MultiSelectMenu: ({ items, selected, onSelect, trigger, minMenuWidth, maxMenuWidth, maxMenuHeight, disabled, enableSearch, searchPlaceholder, enableSelectAll, selectAllText, maxSelections, onSelectAll, alignment, side, sideOffset, alignOffset, open, onOpenChange, showActionButtons, primaryAction, secondaryAction, enableVirtualization, virtualListItemHeight, virtualListOverscan, itemsToRender, onEndReached, endReachedThreshold, hasMore, loadingComponent, }: MultiSelectMenuProps) => import("react/jsx-runtime").JSX.Element;
 export default MultiSelectMenu;

package/dist/components/MultiSelect/types.d.ts

@@ -104,6 +104,14 @@ export type MultiSelectProps = {
     showItemDividers?: boolean;
     showHeaderBorder?: boolean;
     fullWidth?: boolean;
+    enableVirtualization?: boolean;
+    virtualListItemHeight?: number;
+    virtualListOverscan?: number;
+    itemsToRender?: number;
+    onEndReached?: () => void;
+    endReachedThreshold?: number;
+    hasMore?: boolean;
+    loadingComponent?: React.ReactNode;
 };
 export type MultiSelectMenuProps = {
     items: MultiSelectMenuGroupType[];
@@ -139,4 +147,12 @@ export type MultiSelectMenuProps = {
         disabled?: boolean;
         loading?: boolean;
     };
+    enableVirtualization?: boolean;
+    virtualListItemHeight?: number;
+    virtualListOverscan?: number;
+    itemsToRender?: number;
+    onEndReached?: () => void;
+    endReachedThreshold?: number;
+    hasMore?: boolean;
+    loadingComponent?: React.ReactNode;
 };

package/dist/components/SingleSelect/SingleSelect.d.ts

@@ -1,3 +1,3 @@
 import { SingleSelectProps } from './types';
-declare const SingleSelect: ({ label, subLabel, hintText, required, helpIconText, placeholder, error, errorMessage, size, items, name, variant, disabled, selected, onSelect, enableSearch, searchPlaceholder, slot, customTrigger, useDrawerOnMobile, alignment, side, sideOffset, alignOffset, minMenuWidth, maxMenuWidth, maxMenuHeight, onBlur, onFocus, inline, fullWidth, }: SingleSelectProps) => import("react/jsx-runtime").JSX.Element;
+declare const SingleSelect: ({ label, subLabel, hintText, required, helpIconText, placeholder, error, errorMessage, size, items, name, variant, disabled, selected, onSelect, enableSearch, searchPlaceholder, slot, customTrigger, useDrawerOnMobile, alignment, side, sideOffset, alignOffset, minMenuWidth, maxMenuWidth, maxMenuHeight, onBlur, onFocus, inline, fullWidth, enableVirtualization, virtualListItemHeight, virtualListOverscan, itemsToRender, onEndReached, endReachedThreshold, hasMore, loadingComponent, }: SingleSelectProps) => import("react/jsx-runtime").JSX.Element;
 export default SingleSelect;

package/dist/components/SingleSelect/SingleSelectMenu.d.ts

@@ -17,6 +17,14 @@ type SingleSelectMenuProps = {
     alignOffset?: number;
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    enableVirtualization?: boolean;
+    virtualListItemHeight?: number;
+    virtualListOverscan?: number;
+    itemsToRender?: number;
+    onEndReached?: () => void;
+    endReachedThreshold?: number;
+    hasMore?: boolean;
+    loadingComponent?: React.ReactNode;
 };
-declare const SingleSelectMenu: ({ items, selected, onSelect, trigger, minMenuWidth, maxMenuWidth, maxMenuHeight, enableSearch, searchPlaceholder, disabled, alignment, side, sideOffset, alignOffset, open, onOpenChange, }: SingleSelectMenuProps) => import("react/jsx-runtime").JSX.Element;
+declare const SingleSelectMenu: ({ items, selected, onSelect, trigger, minMenuWidth, maxMenuWidth, maxMenuHeight, enableSearch, searchPlaceholder, disabled, alignment, side, sideOffset, alignOffset, open, onOpenChange, enableVirtualization, virtualListItemHeight, virtualListOverscan, itemsToRender, onEndReached, endReachedThreshold, hasMore, loadingComponent, }: SingleSelectMenuProps) => import("react/jsx-runtime").JSX.Element;
 export default SingleSelectMenu;

package/dist/components/SingleSelect/types.d.ts

@@ -95,4 +95,12 @@ export type SingleSelectProps = {
     error?: boolean;
     errorMessage?: string;
     fullWidth?: boolean;
+    enableVirtualization?: boolean;
+    virtualListItemHeight?: number;
+    virtualListOverscan?: number;
+    itemsToRender?: number;
+    onEndReached?: () => void;
+    endReachedThreshold?: number;
+    hasMore?: boolean;
+    loadingComponent?: React.ReactNode;
 };

package/dist/components/StatCard/types.d.ts

@@ -24,9 +24,11 @@ export type StatCardAxisConfig = {
     type?: AxisType;
     tickFormatter?: (value: string | number) => string;
     dateOnly?: boolean;
-    smart?: boolean;
-    timeZone?: string;
-    hour12?: boolean;
+    useUTC?: boolean;
+    formatString?: string;
+    timeOnly?: boolean;
+    showYear?: boolean;
+    smartDateTimeFormat?: boolean;
 };
 export type StatCardProps = {
     title: string;

package/dist/components/Tooltip/Tooltip.d.ts

@@ -1,3 +1,3 @@
 import { TooltipProps } from './types';
-export declare const Tooltip: ({ children: trigger, content, side, align, showArrow, size, slot, slotDirection, delayDuration, offset, open, }: TooltipProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Tooltip: ({ children: trigger, content, side, align, showArrow, size, slot, slotDirection, delayDuration, offset, open, maxWidth, }: TooltipProps) => import("react/jsx-runtime").JSX.Element;
 export default Tooltip;

package/dist/components/Tooltip/types.d.ts

@@ -30,4 +30,5 @@ export type TooltipProps = {
     slotDirection?: TooltipSlotDirection;
     delayDuration?: number;
     offset?: number;
+    maxWidth?: string;
 };

package/dist/components/VirtualList/VirtualList.d.ts

@@ -0,0 +1,4 @@
+import { default as React } from 'react';
+import { VirtualListProps, VirtualListRef, VirtualListItem } from './types';
+declare const VirtualList: React.ForwardRefExoticComponent<VirtualListProps<VirtualListItem> & React.RefAttributes<VirtualListRef>>;
+export default VirtualList;

package/dist/components/VirtualList/index.d.ts

@@ -0,0 +1,3 @@
+export { default as VirtualList } from './VirtualList';
+export { useVirtualList } from './utils';
+export type { VirtualListItem, VirtualListProps, VirtualListRef, VirtualListRenderParams, UseVirtualListParams, UseVirtualListReturn, } from './types';

package/dist/components/VirtualList/types.d.ts

@@ -0,0 +1,79 @@
+import { default as React } from 'react';
+export type VirtualListItem = {
+    id: string | number;
+    height?: number;
+    data?: Record<string, unknown>;
+};
+export type VirtualListRenderParams<T extends VirtualListItem> = {
+    item: T;
+    index: number;
+    style: React.CSSProperties;
+};
+export type ScrollAlignment = 'start' | 'center' | 'end' | 'auto';
+export type VisibleRange = {
+    startIndex: number;
+    endIndex: number;
+};
+export type VirtualListProps<T extends VirtualListItem> = {
+    items: T[];
+    itemHeight?: number | ((item: T, index: number) => number);
+    containerHeight?: number;
+    overscan?: number;
+    onScroll?: (scrollTop: number) => void;
+    renderItem: (params: VirtualListRenderParams<T>) => React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    getItemHeight?: (item: T, index: number) => number;
+    dynamicHeight?: boolean;
+    estimatedItemHeight?: number;
+    ssrMode?: boolean;
+    ariaRole?: 'listbox' | 'menu' | 'table' | 'list';
+    onKeyDown?: (event: React.KeyboardEvent) => void;
+    emptyState?: React.ReactNode;
+    throttleScrollMs?: number;
+    onEndReached?: () => void;
+    endReachedThreshold?: number;
+    isLoading?: boolean;
+    loadingComponent?: React.ReactNode;
+    hasMore?: boolean;
+    onRangeChange?: (range: VisibleRange) => void;
+    initialScrollOffset?: number;
+    initialScrollIndex?: number;
+    scrollAlignment?: ScrollAlignment;
+    itemsToRender?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    maintainScrollPosition?: boolean;
+};
+export type VirtualListRef = {
+    scrollTo: (scrollTop: number, smooth?: boolean) => void;
+    scrollToIndex: (index: number, alignment?: ScrollAlignment, smooth?: boolean) => void;
+    getScrollOffset: () => number;
+    recalculateHeights: () => void;
+    getVisibleRange: () => VisibleRange;
+    measureItem: (index: number) => void;
+};
+export type UseVirtualListParams<T extends VirtualListItem> = {
+    items: T[];
+    itemHeight?: number | ((item: T, index: number) => number);
+    containerHeight: number;
+    overscan?: number;
+    getItemHeight?: (item: T, index: number) => number;
+    dynamicHeight?: boolean;
+    ssrMode?: boolean;
+    estimatedItemHeight?: number;
+    itemsToRender?: number;
+    minHeight?: number;
+    maxHeight?: number;
+};
+export type UseVirtualListReturn = {
+    scrollTop: number;
+    setScrollTop: React.Dispatch<React.SetStateAction<number>>;
+    totalHeight: number;
+    itemOffsets: number[];
+    itemHeights: number[];
+    recalculateHeights: () => void;
+    startIndex: number;
+    endIndex: number;
+    measureItem: (index: number, height: number) => void;
+};

package/dist/components/VirtualList/utils.d.ts

@@ -0,0 +1,30 @@
+import { VirtualListItem, UseVirtualListParams, UseVirtualListReturn, ScrollAlignment } from './types';
+export declare function throttle<T extends (...args: unknown[]) => unknown>(func: T, wait: number): (...args: Parameters<T>) => void;
+export declare const isBrowser: boolean;
+export declare const findEndIndexBinarySearch: (startIndex: number, viewportBottom: number, itemOffsets: number[], itemsLength: number, overscan: number) => number;
+export declare const calculateFixedHeightRange: (scrollTop: number, containerHeight: number, itemHeight: number, itemsLength: number, overscan: number, itemsToRender?: number) => {
+    startIndex: number;
+    endIndex: number;
+};
+export declare const calculateDynamicHeightRange: (scrollTop: number, containerHeight: number, itemOffsets: number[], itemsLength: number, overscan: number, itemsToRender?: number) => {
+    startIndex: number;
+    endIndex: number;
+};
+export declare const calculateItemHeights: <T extends VirtualListItem>(items: T[], itemHeight?: number | ((item: T, index: number) => number), getItemHeight?: (item: T, index: number) => number, estimatedItemHeight?: number, minHeight?: number, maxHeight?: number, measuredHeights?: Map<number, number>) => number[];
+export declare const constrainHeight: (height: number, minHeight?: number, maxHeight?: number) => number;
+export declare const calculateItemOffsets: (itemHeights: number[]) => {
+    totalHeight: number;
+    itemOffsets: number[];
+};
+export declare function useVirtualList<T extends VirtualListItem>({ items, itemHeight, containerHeight, overscan, getItemHeight, ssrMode, estimatedItemHeight, itemsToRender, minHeight, maxHeight, }: UseVirtualListParams<T>): UseVirtualListReturn;
+export declare const handleVirtualListKeyDown: (e: React.KeyboardEvent<HTMLDivElement>, ariaRole: string, totalHeight: number, containerRef: React.RefObject<HTMLDivElement | null>, onKeyDown?: (event: React.KeyboardEvent) => void) => void;
+export declare const calculateScrollForAlignment: (index: number, alignment: ScrollAlignment, containerHeight: number, itemOffsets: number[], itemHeights: number[], itemsLength: number) => number;
+export declare const scrollToPosition: (containerRef: React.RefObject<HTMLDivElement | null>, scrollTop: number, smooth?: boolean) => void;
+export declare const scrollToIndex: (containerRef: React.RefObject<HTMLDivElement | null>, index: number, itemOffsets: number[], itemHeights: number[], itemsLength: number, containerHeight: number, alignment?: ScrollAlignment, smooth?: boolean) => void;
+export declare const createVirtualItemStyle: (top: number, height: number, useAbsolute?: boolean) => React.CSSProperties;
+export declare const setupResizeObserver: (dynamicHeight: boolean, isMounted: boolean, containerRef: React.RefObject<HTMLDivElement | null>, measureItem: (index: number, height: number) => void) => (() => void) | undefined;
+export declare const checkEndReached: (scrollTop: number, totalHeight: number, containerHeight: number, threshold: number) => boolean;
+export declare const usePreviousRange: (startIndex: number, endIndex: number, onRangeChange?: (range: {
+    startIndex: number;
+    endIndex: number;
+}) => void) => void;

package/dist/main.d.ts

@@ -31,6 +31,7 @@ export * from './components/ProgressBar';
 export * from './components/Drawer';
 export * from './components/Skeleton';
 export * from './components/KeyValuePair';
+export * from './components/VirtualList';
 export * from './components/ButtonGroup';
 export * from './components/Button';
 export * from './context';