@carbon/ibm-products
Version:
Carbon for IBM Products
101 lines • 4.68 kB
TypeScript
/**
* Copyright IBM Corp. 2025
*
* This source code is licensed under the Apache-2.0 license found in the
* LICENSE file in the root directory of this source tree.
*/
/**
* This file has test coverage in @carbon/utilities. This is a copy of the utility
* that adds margin calculations to an element's size. This should ideally be
* merged back into the utility.
*/
/**
* Calculates the size (width or height) of a given HTML element.
*
* This function performs an expensive calculation by temporarily changing the
* display style of the element if it is not currently visible. It then uses
* `getBoundingClientRect` to retrieve the size of the element.
*
* @param el - The HTML element whose size is to be calculated.
* @param dimension - The dimension to measure ('width' or 'height').
* @returns The size of the element in pixels. Returns 0 if the element is not provided.
*/
export declare function getSize(el: HTMLElement, dimension: 'width' | 'height'): number;
/**
* Options for updating the overflow handler.
* Determines which items should be visible and which should be hidden
* based on the container size, item sizes, and other constraints.
*/
export interface UpdateOverflowHandlerOptions {
/** The container element that holds the items. */
container: HTMLElement;
/** An array of item elements to be managed for overflow. */
items: HTMLElement[];
/** An element that represents the offset, which can be shown or hidden based on overflow. Identified by `data-offset` attribute. */
offset: HTMLElement;
/** An array of sizes corresponding to each item in the `items` array. */
sizes: number[];
/** An array of sizes corresponding to each item in the fixed items array. */
fixedSizes: number[];
/** The size of the offset element. */
offsetSize: number;
/** The maximum number of items that can be visible at once. If undefined, all items can be visible. */
maxVisibleItems?: number;
/** The dimension to consider for overflow, either 'width' or 'height'. */
dimension: 'width' | 'height';
/** A callback function that is called when the visible or hidden items change. */
onChange: (visibleItems: HTMLElement[], hiddenItems: HTMLElement[]) => void;
/** An array of previously hidden items to compare against the new hidden items. */
previousHiddenItems?: HTMLElement[];
}
/**
* Updates the overflow handler by determining which items should be visible and which should be hidden.
*
* @param options - Configuration options for updating the overflow handler.
* @param options.container - Container for overflowing
* @param options.items - Child elements within container
* @param options.offset - Children with data-offset attribute
* @param options.sizes - Sizes of child elements
* @param options.fixedSizes - Fixed sizes of child elements with data-fixed attribute
* @param options.offsetSize - Total offset size
* @param options.maxVisibleItems - Max visible items
* @param options.dimension - width | height used to measure overflow
* @param options.onChange - onChange callback
* @param options.previousHiddenItems - Array of previously hidden items
* @returns An array of hidden items after the update.
*/
export declare function updateOverflowHandler({ container, items, offset, sizes, fixedSizes, offsetSize, maxVisibleItems, dimension, onChange, previousHiddenItems, }: UpdateOverflowHandlerOptions): HTMLElement[];
/**
* Options for initializing an overflow handler.
*/
export interface OverflowHandlerOptions {
/**
* The container element that holds the items. along with offset item
*/
container: HTMLElement;
/**
* Maximum number of visible items. If provided, only this number of items will be shown.
*/
maxVisibleItems?: number;
/**
* Callback function invoked when the visible and hidden items change.
* @param visibleItems - The array of items that are currently visible.
* @param hiddenItems - The array of items that are currently hidden.
*/
onChange: (visibleItems: HTMLElement[], hiddenItems: HTMLElement[]) => void;
/**
* The dimension to consider for overflow calculations. Defaults to 'width'.
*/
dimension?: 'width' | 'height';
}
/**
* Represents an instance of an overflow handler.
*/
export interface OverflowHandler {
/**
* Disconnects the overflow handler, cleaning up any event listeners or resources.
*/
disconnect: () => void;
}
export declare function createOverflowHandler({ container, maxVisibleItems, onChange, dimension, }: OverflowHandlerOptions): OverflowHandler;
//# sourceMappingURL=overflowHandler.d.ts.map