vlist 0.1.2 → 1.5.4

package/dist/rendering/viewport.d.ts

@@ -0,0 +1,139 @@
+/**
+ * vlist - Virtual Scrolling Core
+ * Pure functions for virtual scroll calculations
+ *
+ * Compression support is NOT imported here — it's injected via
+ * CompressionState parameters. When compression is inactive
+ * (the common case), all calculations use simple size-cache math
+ * with zero dependency on the compression module.
+ *
+ * This keeps the builder core lightweight. The withCompression feature
+ * and the monolithic createVList entry point import compression
+ * separately and pass the state in.
+ */
+import type { Range, ViewportState } from "../types";
+import type { SizeCache } from "./sizes";
+/** Compression calculation result */
+export interface CompressionState {
+    /** Whether compression is active */
+    isCompressed: boolean;
+    /** The actual total size (uncompressed) */
+    actualSize: number;
+    /** The virtual size (capped at MAX_VIRTUAL_SIZE) */
+    virtualSize: number;
+    /** Compression ratio (1 = no compression, <1 = compressed) */
+    ratio: number;
+}
+/**
+ * A "no compression" state for lists that don't need it.
+ * Used by the builder core when withCompression is not installed.
+ */
+export declare const NO_COMPRESSION: CompressionState;
+/**
+ * Create a trivial compression state from a size cache.
+ * No compression logic — just reads the total height.
+ * For use when the full compression module is not loaded.
+ */
+export declare const getSimpleCompressionState: (_totalItems: number, sizeCache: SizeCache) => CompressionState;
+/**
+ * Signature for the function that calculates the visible item range.
+ * The compression module provides a version that handles compressed scroll;
+ * virtual.ts provides a simple fallback for non-compressed lists.
+ */
+export type VisibleRangeFn = (scrollPosition: number, containerHeight: number, sizeCache: SizeCache, totalItems: number, compression: CompressionState, out: Range) => Range;
+/**
+ * Signature for the scroll-to-index calculator.
+ */
+export type ScrollToIndexFn = (index: number, sizeCache: SizeCache, containerHeight: number, totalItems: number, compression: CompressionState, align: "start" | "center" | "end") => number;
+/**
+ * Calculate visible range using size cache lookups.
+ * Fast path for lists that don't need compression (< ~350 000 items at 48px).
+ * Mutates `out` to avoid allocation on the scroll hot path.
+ */
+export declare const simpleVisibleRange: VisibleRangeFn;
+/**
+ * Calculate render range (adds overscan around visible range).
+ * This function is compression-agnostic — works for both paths.
+ * Mutates `out` to avoid allocation on the scroll hot path.
+ */
+export declare const calculateRenderRange: (visibleRange: Range, overscan: number, totalItems: number, out: Range) => Range;
+/**
+ * Simple scroll-to-index calculation (non-compressed).
+ * Uses size cache offsets directly.
+ */
+export declare const simpleScrollToIndex: ScrollToIndexFn;
+/**
+ * Calculate total content height.
+ * Uses compression's virtualSize when compressed, raw height otherwise.
+ */
+export declare const calculateTotalSize: (_totalItems: number, sizeCache: SizeCache, compression?: CompressionState | null) => number;
+/**
+ * Calculate actual total size (without compression cap)
+ */
+export declare const calculateActualSize: (_totalItems: number, sizeCache: SizeCache) => number;
+/**
+ * Calculate the offset (translateY) for an item
+ * For non-compressed lists only
+ */
+export declare const calculateItemOffset: (index: number, sizeCache: SizeCache) => number;
+/**
+ * Clamp scroll position to valid range
+ */
+export declare const clampScrollPosition: (scrollPosition: number, totalHeight: number, containerHeight: number) => number;
+/**
+ * Determine scroll direction
+ */
+export declare const getScrollDirection: (currentScrollTop: number, previousScrollTop: number) => "up" | "down";
+/**
+ * Create initial viewport state.
+ *
+ * Accepts an optional `visibleRangeFn` so that compression-aware callers
+ * can inject the compressed version. Defaults to `simpleVisibleRange`.
+ */
+export declare const createViewportState: (containerHeight: number, sizeCache: SizeCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
+/**
+ * Update viewport state after scroll.
+ * Mutates state in place for performance on the scroll hot path.
+ */
+export declare const updateViewportState: (state: ViewportState, scrollPosition: number, sizeCache: SizeCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
+/**
+ * Update viewport state when container resizes.
+ * Mutates state in place for performance.
+ */
+export declare const updateViewportSize: (state: ViewportState, containerHeight: number, sizeCache: SizeCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
+/**
+ * Update viewport state when total items changes.
+ * Mutates state in place for performance.
+ */
+export declare const updateViewportItems: (state: ViewportState, sizeCache: SizeCache, totalItems: number, overscan: number, compression: CompressionState, visibleRangeFn?: VisibleRangeFn) => ViewportState;
+/**
+ * Calculate scroll position to bring an index into view.
+ *
+ * Accepts an optional `scrollToIndexFn` so that compression-aware callers
+ * can inject the compressed version. Defaults to `simpleScrollToIndex`.
+ */
+export declare const calculateScrollToIndex: (index: number, sizeCache: SizeCache, containerHeight: number, totalItems: number, align: "start" | "center" | "end" | undefined, compression: CompressionState, scrollToIndexFn?: ScrollToIndexFn) => number;
+/**
+ * Check if two ranges are equal
+ */
+export declare const rangesEqual: (a: Range, b: Range) => boolean;
+/**
+ * Check if an index is within a range
+ */
+export declare const isInRange: (index: number, range: Range) => boolean;
+/**
+ * Get the count of items in a range
+ */
+export declare const getRangeCount: (range: Range) => number;
+/**
+ * Create an array of indices from a range
+ */
+export declare const rangeToIndices: (range: Range) => number[];
+/**
+ * Calculate which indices need to be added/removed when range changes
+ */
+export declare const diffRanges: (oldRange: Range, newRange: Range) => {
+    add: number[];
+    remove: number[];
+};
+//# sourceMappingURL=viewport.d.ts.map

package/dist/size.json

@@ -0,0 +1 @@
+{"base":{"minified":"27.0","gzipped":"10.4"},"withGrid":{"minified":"39.0","gzipped":"14.3"},"withMasonry":{"minified":"36.6","gzipped":"13.8"},"withGroups":{"minified":"35.4","gzipped":"13.1"},"withAsync":{"minified":"39.6","gzipped":"14.8"},"withSelection":{"minified":"37.0","gzipped":"13.1"},"withScale":{"minified":"37.9","gzipped":"13.5"},"withScrollbar":{"minified":"30.9","gzipped":"11.5"},"withPage":{"minified":"28.4","gzipped":"10.8"},"withSnapshots":{"minified":"29.4","gzipped":"11.2"},"withTable":{"minified":"44.6","gzipped":"15.9"},"withAutoSize":{"minified":"29.8","gzipped":"11.3"}}

package/dist/types.d.ts

@@ -0,0 +1,487 @@
+/**
+ * vlist - Core Types
+ * Minimal, clean interfaces for the virtual list
+ */
+/** Base event map with index signature */
+export type EventMap = Record<string, unknown>;
+/** Base item interface - must have an id */
+export interface VListItem {
+    id: string | number;
+    [key: string]: unknown;
+}
+/** Groups configuration for createVList */
+export interface GroupHeaderConfig {
+    /**
+     * Header size in pixels along the main axis (vertical scrolling).
+     * - `number` — Fixed size for all headers
+     * - `(group: string, groupIndex: number) => number` — Variable size per group
+     *
+     * Required when `orientation` is `'vertical'` (default).
+     * Ignored when `orientation` is `'horizontal'`.
+     */
+    height?: number | ((group: string, groupIndex: number) => number);
+    /**
+     * Header size in pixels along the main axis (horizontal scrolling).
+     * - `number` — Fixed size for all headers
+     * - `(group: string, groupIndex: number) => number` — Variable size per group
+     *
+     * Required when `orientation` is `'horizontal'`.
+     * Ignored when `orientation` is `'vertical'` (default).
+     */
+    width?: number | ((group: string, groupIndex: number) => number);
+    /**
+     * Template function to render a group header.
+     * Receives the group key and the group's sequential index (0-based).
+     */
+    template: (group: string, groupIndex: number) => string | HTMLElement;
+}
+export interface GroupsConfig {
+    /**
+     * Determine which group an item belongs to.
+     * Called with the DATA index (index into the original items array).
+     * Items with the same group key are grouped together.
+     *
+     * Items MUST be pre-sorted by group — the function is called in order
+     * and a new header is inserted whenever the return value changes.
+     */
+    getGroupForIndex: (index: number) => string;
+    /**
+     * Group header configuration — mirrors the `item` config shape.
+     */
+    header?: GroupHeaderConfig;
+    /**
+     * @deprecated Use `header.height` instead.
+     */
+    headerHeight?: number | ((group: string, groupIndex: number) => number);
+    /**
+     * @deprecated Use `header.template` instead.
+     */
+    headerTemplate?: (group: string, groupIndex: number) => string | HTMLElement;
+    /**
+     * Enable sticky headers (default: true).
+     * When true, the current group's header "sticks" to the top of the
+     * viewport and is pushed out by the next group's header approaching.
+     */
+    sticky?: boolean;
+}
+/** Grid configuration for createVList */
+export interface GridConfig {
+    /**
+     * Number of columns in the grid.
+     * Item width = containerWidth / columns (minus gaps).
+     *
+     * Must be a positive integer ≥ 1.
+     */
+    columns: number;
+    /**
+     * Gap between grid items in pixels (default: 0).
+     * Applied both horizontally (between columns) and vertically (between rows).
+     */
+    gap?: number;
+}
+/** Masonry configuration for createVList */
+export interface MasonryConfig {
+    /**
+     * Number of cross-axis divisions (columns in vertical, rows in horizontal).
+     * Items flow into the shortest column/row.
+     *
+     * Must be a positive integer ≥ 1.
+     */
+    columns: number;
+    /**
+     * Gap between masonry items in pixels (default: 0).
+     * Applied both horizontally and vertically.
+     */
+    gap?: number;
+}
+/** Item-specific configuration */
+/** Context provided to size function in grid mode */
+export interface GridSizeContext {
+    /** Current container width */
+    containerWidth: number;
+    /** Number of columns */
+    columns: number;
+    /** Gap between items in pixels */
+    gap: number;
+    /** Calculated column width */
+    columnWidth: number;
+}
+/** @deprecated Use GridSizeContext instead */
+export type GridHeightContext = GridSizeContext;
+export interface ItemConfig<T extends VListItem = VListItem> {
+    /**
+     * Item size in pixels along the main axis (required for vertical scrolling, cross-axis size for horizontal)
+     *
+     * - `number` — Fixed size for all items (fast path, zero overhead)
+     * - `(index: number) => number` — Variable size per item (prefix-sum based lookups)
+     * - `(index: number, context?: GridSizeContext) => number` — Dynamic size based on grid state
+     *
+     * In grid mode, the size function receives grid context as a second parameter,
+     * allowing you to calculate size based on column width to maintain aspect ratios:
+     *
+     * ```ts
+     * height: (index, context) => {
+     *   if (context) {
+     *     return context.columnWidth * 0.75; // 4:3 aspect ratio
+     *   }
+     *   return 200; // fallback for non-grid
+     * }
+     * ```
+     *
+     * Required when `orientation` is `'vertical'` (default).
+     * Optional when `orientation` is `'horizontal'` (used as cross-axis size).
+     */
+    height?: number | ((index: number, context?: GridSizeContext) => number);
+    /**
+     * Item width in pixels (required for horizontal scrolling)
+     *
+     * - `number` — Fixed width for all items (fast path, zero overhead)
+     * - `(index: number) => number` — Variable width per item (prefix-sum based lookups)
+     *
+     * Required when `orientation` is `'horizontal'`.
+     * Ignored when `orientation` is `'vertical'` (default).
+     */
+    width?: number | ((index: number) => number);
+    /**
+     * Estimated item height for auto-measurement (Mode B — vertical scrolling)
+     *
+     * When set, vlist renders items using this estimated size, measures their
+     * actual DOM height after render via ResizeObserver, caches the result,
+     * and adjusts scroll position to prevent visual jumps.
+     *
+     * Use this for content with unknown heights: variable-length text,
+     * images with unknown aspect ratios, mixed-media feeds, etc.
+     *
+     * Takes precedence only when `height` is not set — if both are provided,
+     * `height` wins (Mode A) and `estimatedHeight` is ignored.
+     *
+     * Ignored when `orientation` is `'horizontal'`.
+     */
+    estimatedHeight?: number;
+    /**
+     * Estimated item width for auto-measurement (Mode B — horizontal scrolling)
+     *
+     * Horizontal equivalent of `estimatedHeight`. When set, vlist renders items
+     * using this estimated width, measures actual DOM width after render,
+     * caches the result, and adjusts scroll position to prevent visual jumps.
+     *
+     * Takes precedence only when `width` is not set — if both are provided,
+     * `width` wins (Mode A) and `estimatedWidth` is ignored.
+     *
+     * Only used when `orientation` is `'horizontal'`.
+     */
+    estimatedWidth?: number;
+    /**
+     * Add a `.vlist-item--odd` class on odd-indexed items for zebra-stripe styling.
+     *
+     * Virtual lists recycle DOM elements out of document order, so CSS
+     * `:nth-child(even/odd)` does not match the logical item index.
+     * When enabled, vlist toggles the class based on the real item index,
+     * giving you a reliable CSS hook:
+     *
+     * ```css
+     * .vlist-item--odd { background: #fafafb; }
+     * ```
+     *
+     * - `true` — all items (including group headers) count for even/odd.
+     * - `"data"` — only data items count; group headers are excluded from
+     *   the stripe index so they don't shift the alternating pattern.
+     * - `"even"` — counter resets after each group header; first data row
+     *   in every group is even (non-striped). macOS Finder behavior.
+     * - `"odd"` — counter resets after each group header; first data row
+     *   in every group is odd (striped).
+     *
+     * Default: `false` (no extra work on the render hot path).
+     */
+    striped?: boolean | "data" | "even" | "odd";
+    /**
+     * Gap between items in pixels along the main axis (default: 0).
+     *
+     * Adds consistent spacing between items without requiring CSS margin
+     * or padding hacks on `.vlist-item`. The gap is baked into the size
+     * cache (each slot = itemSize + gap) and subtracted from the DOM
+     * element height, so items are positioned with precise spacing.
+     *
+     * Works identically to the `gap` option in grid and masonry modes.
+     *
+     * ```ts
+     * item: {
+     *   height: 60,
+     *   gap: 10,        // 10px between each item
+     *   template: …,
+     * }
+     * ```
+     */
+    gap?: number;
+    /** Template function to render each item */
+    template: ItemTemplate<T>;
+}
+/** Scroll position snapshot for save/restore */
+export interface ScrollSnapshot {
+    /** First visible item index */
+    index: number;
+    /** Pixel offset within the first visible item (how far it's scrolled off) */
+    offsetInItem: number;
+    /** Total item count at snapshot time (used by restore to set sizeCache) */
+    total?: number;
+    /** Selected item IDs (optional, included for convenience) */
+    selectedIds?: Array<string | number>;
+}
+/** Options for scrollToIndex / scrollToItem */
+export interface ScrollToOptions {
+    /** Alignment within the viewport (default: 'start') */
+    align?: "start" | "center" | "end";
+    /** Scroll behavior (default: 'auto' = instant) */
+    behavior?: "auto" | "smooth";
+    /** Animation duration in ms (default: 300, only used with behavior: 'smooth') */
+    duration?: number;
+}
+/** Scroll behavior configuration */
+export interface ScrollConfig {
+    /** Enable mouse wheel scrolling (default: true) */
+    wheel?: boolean;
+    /**
+     * Scrollbar gutter behavior for the native scrollbar (default: 'auto').
+     *
+     * - `'auto'` — Default browser behavior. On macOS with overlay scrollbars,
+     *   no space is reserved. On Windows/Linux, the classic scrollbar takes
+     *   ~15-17px from the content area when it appears.
+     * - `'stable'` — Always reserves space for the scrollbar via
+     *   `scrollbar-gutter: stable`. Prevents layout shift when content
+     *   grows past the container. Recommended for Windows/Linux targets.
+     *
+     * Has no effect when `withScrollbar()` is active (the native scrollbar
+     * is hidden and replaced by an absolute-positioned custom scrollbar).
+     */
+    gutter?: "auto" | "stable";
+    /**
+     * Wrap around when scrolling past boundaries (default: false).
+     *
+     * When `true`, `scrollToIndex` wraps around:
+     * - Index past the last item → wraps to the beginning
+     * - Negative index → wraps from the end
+     *
+     * Useful for carousels, wizards, and circular navigation.
+     */
+    wrap?: boolean;
+    /**
+     * Scrollbar mode (default: custom scrollbar).
+     *
+     * - *omitted* — Custom scrollbar (default), native scrollbar hidden via CSS
+     * - `'native'` — Browser native scrollbar (falls back to custom in compressed mode)
+     * - `'none'` — No scrollbar at all (native hidden, custom not created)
+     * - `ScrollbarOptions` — Custom scrollbar with fine-tuning options
+     */
+    scrollbar?: "native" | "none" | ScrollbarOptions;
+    /** External scroll element for window scrolling */
+    element?: Window;
+    /** Scroll idle detection timeout in ms (default: 150) */
+    idleTimeout?: number;
+}
+/** Custom scrollbar fine-tuning options */
+export interface ScrollbarOptions {
+    /** Auto-hide scrollbar after idle (default: true) */
+    autoHide?: boolean;
+    /** Auto-hide delay in milliseconds (default: 1000) */
+    autoHideDelay?: number;
+    /** Minimum thumb size in pixels (default: 30) */
+    minThumbSize?: number;
+    /**
+     * Show scrollbar when hovering near the scrollbar edge (default: true).
+     * When true, an invisible hover zone is placed along the scrollbar edge.
+     * Moving the mouse into this zone reveals the scrollbar; it stays visible
+     * as long as the cursor remains over the zone or the track.
+     */
+    showOnHover?: boolean;
+    /**
+     * Width of the invisible hover zone in pixels (default: 16).
+     * Only used when `showOnHover` is true.
+     * A wider zone makes the scrollbar easier to discover;
+     * a narrower zone avoids interference with content near the edge.
+     */
+    hoverZoneWidth?: number;
+    /**
+     * Show scrollbar when the mouse enters the list viewport (default: true).
+     * When false, the scrollbar only appears on scroll or when hovering
+     * near the scrollbar edge (if `showOnHover` is true).
+     */
+    showOnViewportEnter?: boolean;
+}
+/**
+ * Scrollbar configuration.
+ * @deprecated Use `scroll.scrollbar` in `ScrollConfig` instead.
+ */
+export interface ScrollbarConfig {
+    /** Enable scrollbar (default: true) */
+    enabled?: boolean;
+    /** Auto-hide scrollbar after idle (default: true) */
+    autoHide?: boolean;
+    /** Auto-hide delay in milliseconds (default: 1000) */
+    autoHideDelay?: number;
+    /** Minimum thumb size in pixels (default: 30) */
+    minThumbSize?: number;
+}
+/** Item template function */
+export type ItemTemplate<T = VListItem> = (item: T, index: number, state: ItemState) => string | HTMLElement;
+/** State passed to template */
+export interface ItemState {
+    selected: boolean;
+    focused: boolean;
+}
+/** Selection mode */
+export type SelectionMode = "none" | "single" | "multiple";
+/** Selection configuration */
+export interface SelectionConfig {
+    /** Selection mode (default: 'none') */
+    mode?: SelectionMode;
+    /** Initially selected item IDs */
+    initial?: Array<string | number>;
+}
+/** Selection state */
+export interface SelectionState {
+    /** Currently selected item IDs */
+    selected: Set<string | number>;
+    /** Currently focused item index (-1 if none) */
+    focusedIndex: number;
+    /** Whether the focus ring should be visible (true for keyboard, false for mouse) */
+    focusVisible: boolean;
+}
+/** Adapter for async data loading */
+export interface VListAdapter<T extends VListItem = VListItem> {
+    /** Fetch items for a range */
+    read: (params: AdapterParams) => Promise<AdapterResponse<T>>;
+}
+/** Parameters passed to adapter.read */
+export interface AdapterParams {
+    /** Starting offset */
+    offset: number;
+    /** Number of items to fetch */
+    limit: number;
+    /** Optional cursor for cursor-based pagination */
+    cursor: string | undefined;
+}
+/** Response from adapter.read */
+export interface AdapterResponse<T extends VListItem = VListItem> {
+    /** Fetched items */
+    items: T[];
+    /** Total count (if known) */
+    total?: number;
+    /** Next cursor (for cursor-based pagination) */
+    cursor?: string;
+    /** Whether more items exist */
+    hasMore?: boolean;
+}
+/** Visible range of items */
+export interface Range {
+    start: number;
+    end: number;
+}
+/** Viewport state */
+export interface ViewportState {
+    /** Current scroll position along main axis (scrollTop for vertical, scrollLeft for horizontal) */
+    scrollPosition: number;
+    /** Container size along main axis (height for vertical, width for horizontal) */
+    containerSize: number;
+    /** Total content size (may be capped for compression) */
+    totalSize: number;
+    /** Actual total size without compression */
+    actualSize: number;
+    /** Whether compression is active */
+    isCompressed: boolean;
+    /** Compression ratio (1 = no compression, <1 = compressed) */
+    compressionRatio: number;
+    /** Visible item range */
+    visibleRange: Range;
+    /** Render range (includes overscan) */
+    renderRange: Range;
+}
+/** Viewport state snapshot attached to error events for debugging */
+export interface ErrorViewportSnapshot {
+    scrollPosition: number;
+    containerSize: number;
+    visibleRange: {
+        start: number;
+        end: number;
+    };
+    renderRange: {
+        start: number;
+        end: number;
+    };
+    totalItems: number;
+    isCompressed: boolean;
+}
+/** Event types and their payloads */
+export interface VListEvents<T extends VListItem = VListItem> extends EventMap {
+    /** Item clicked */
+    "item:click": {
+        item: T;
+        index: number;
+        event: MouseEvent;
+    };
+    /** Item double-clicked */
+    "item:dblclick": {
+        item: T;
+        index: number;
+        event: MouseEvent;
+    };
+    /** Selection changed */
+    "selection:change": {
+        selected: Array<string | number>;
+        items: T[];
+    };
+    /** Scroll position changed */
+    scroll: {
+        scrollPosition: number;
+        direction: "up" | "down";
+    };
+    /** Scroll velocity changed */
+    "velocity:change": {
+        velocity: number;
+        reliable: boolean;
+    };
+    /** Visible range changed */
+    "range:change": {
+        range: Range;
+    };
+    /** Data loading started */
+    "load:start": {
+        offset: number;
+        limit: number;
+    };
+    /** Data loading completed */
+    "load:end": {
+        items: T[];
+        total?: number;
+        offset?: number;
+    };
+    /** Error occurred (includes viewport state when available) */
+    error: {
+        error: Error;
+        context: string;
+        viewport?: ErrorViewportSnapshot;
+    };
+    /** Container resized */
+    resize: {
+        height: number;
+        width: number;
+    };
+    /** Scroll idle — fired after scrolling stops and idle timeout elapses */
+    "scroll:idle": {
+        scrollPosition: number;
+    };
+    /** Data changed — fired after item removal or other data mutations */
+    "data:change": {
+        type: "remove";
+        id: string | number;
+    } | {
+        type: "update";
+        id: string | number;
+    };
+    /** Destroy — fired just before the instance is torn down */
+    destroy: undefined;
+}
+/** Event handler type */
+export type EventHandler<T> = (payload: T) => void;
+/** Unsubscribe function */
+export type Unsubscribe = () => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/padding.d.ts

@@ -0,0 +1,38 @@
+/**
+ * vlist/utils — Padding Resolution
+ * Shared helpers for resolving the CSS-shorthand padding config into
+ * concrete pixel values. Used by core (to apply CSS) and by features
+ * (to subtract cross-axis padding from container dimensions).
+ */
+import type { BuilderConfig } from "../builder/types";
+/** Padding config — re-exported from BuilderConfig for convenience */
+export type PaddingConfig = NonNullable<BuilderConfig["padding"]>;
+/** Resolved padding — all four sides in pixels */
+export interface ResolvedPadding {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+}
+/**
+ * Resolve a padding config into all four sides.
+ *
+ * - `undefined`        → { 0, 0, 0, 0 }
+ * - `number`           → equal on all sides
+ * - `[v, h]`           → top/bottom = v, left/right = h
+ * - `[t, r, b, l]`     → per-side (CSS order)
+ *
+ * Returns a frozen singleton for the zero case (no allocation).
+ */
+export declare const resolvePadding: (padding: PaddingConfig | undefined) => ResolvedPadding;
+/**
+ * Total padding along the main axis (scroll direction).
+ * Vertical → top + bottom. Horizontal → left + right.
+ */
+export declare const mainAxisPaddingFrom: (p: ResolvedPadding, isHorizontal: boolean) => number;
+/**
+ * Total padding along the cross axis (perpendicular to scroll).
+ * Vertical → left + right. Horizontal → top + bottom.
+ */
+export declare const crossAxisPaddingFrom: (p: ResolvedPadding, isHorizontal: boolean) => number;
+//# sourceMappingURL=padding.d.ts.map