@elastic/eui 88.0.0 → 88.2.0

package/eui.d.ts

@@ -514,8 +514,8 @@ declare module '@elastic/eui/src/global_styling/variables/typography' {
 	/**
 	 * Font units of measure
 	 */
-	export const EuiThemeFontSizeMeasurements: readonly ["rem", "px", "em"];
-	export type _EuiThemeFontSizeMeasurement = (typeof EuiThemeFontSizeMeasurements)[number];
+	export const EuiThemeFontUnits: readonly ["rem", "px", "em"];
+	export type _EuiThemeFontUnit = (typeof EuiThemeFontUnits)[number];
 	export const EuiThemeFontScales: readonly ["xxxs", "xxs", "xs", "s", "m", "l", "xl", "xxl"];
 	export type _EuiThemeFontScale = (typeof EuiThemeFontScales)[number];
 	export type _EuiThemeFontScales = Record<_EuiThemeFontScale, number>;
@@ -538,6 +538,16 @@ declare module '@elastic/eui/src/global_styling/variables/typography' {
 	     * https://developer.mozilla.org/en-US/docs/Web/CSS/font-feature-settings
 	     */
 	    featureSettings?: string;
+	    /**
+	     * Sets the default units used for font size & line height set by UI components
+	     * like EuiText or EuiTitle. Defaults to `rem`.
+	     *
+	     * NOTE: This may overridden by some internal usages, e.g.
+	     * EuiText's `relative` size which must use `em`.
+	     *
+	     * @default 'rem'
+	     */
+	    defaultUnits: _EuiThemeFontUnit;
 	    /**
 	     * A computed number that is 1/4 of `base`
 	     */
@@ -663,6 +673,7 @@ declare module '@elastic/eui/src/global_styling/variables/levels' {
 
 }
 declare module '@elastic/eui/src/services/theme/types' {
+	import type { CSSObject } from '@emotion/react';
 	import { RecursivePartial, ValueOf } from '@elastic/eui/src/components/common';
 	import { _EuiThemeAnimation } from '@elastic/eui/src/global_styling/variables/animations';
 	import { _EuiThemeBreakpoints } from '@elastic/eui/src/global_styling/variables/breakpoint';
@@ -720,6 +731,10 @@ declare module '@elastic/eui/src/services/theme/types' {
 	    hasDifferentColorFromGlobalTheme: boolean;
 	    bodyColor: string;
 	    colorClassName: string;
+	    setGlobalCSSVariables: Function;
+	    globalCSSVariables?: CSSObject;
+	    setNearestThemeCSSVariables: Function;
+	    themeCSSVariables?: CSSObject;
 	};
 
 }
@@ -1356,16 +1371,26 @@ declare module '@elastic/eui/src/services/theme/hooks' {
 	export const RenderWithEuiTheme: <T extends {} = {}>({ children, }: {
 	    children: (theme: UseEuiTheme) => React.ReactElement;
 	}) => React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+	/**
+	 * Minor syntactical sugar hook for theme CSS variables.
+	 * Primarily meant for internal EUI usage.
+	 */
+	export const useEuiThemeCSSVariables: () => {
+	    setGlobalCSSVariables: Function;
+	    globalCSSVariables: import("@emotion/serialize").CSSObject | undefined;
+	    setNearestThemeCSSVariables: Function;
+	    themeCSSVariables: import("@emotion/serialize").CSSObject | undefined;
+	};
 
 }
 declare module '@elastic/eui/src/global_styling/functions/typography' {
-	import { _EuiThemeFontScale, _EuiThemeFontSizeMeasurement, _EuiThemeFontWeights } from '@elastic/eui/src/global_styling/variables/typography';
+	import { _EuiThemeFontScale, _EuiThemeFontUnit, _EuiThemeFontWeights } from '@elastic/eui/src/global_styling/variables/typography';
 	import { UseEuiTheme } from '@elastic/eui/src/services/theme/hooks';
 	export interface _FontScaleOptions {
 	    /**
-	     * The returned string measurement
+	     * The font-size or line-height unit to return
 	     */
-	    measurement?: _EuiThemeFontSizeMeasurement;
+	    unit?: _EuiThemeFontUnit;
 	    /**
 	     * An additional custom scale multiplier to use against the current scale
 	     * This parameter can be used (e.g. by EuiText sizes) to get sizes of text smaller than the default
@@ -1380,7 +1405,7 @@ declare module '@elastic/eui/src/global_styling/functions/typography' {
 	 *
 	 * @returns string - Calculated font-size value
 	 */
-	export function euiFontSizeFromScale(scale: _EuiThemeFontScale, { base, font }: UseEuiTheme['euiTheme'], { measurement, customScale }?: _FontScaleOptions): string;
+	export function euiFontSizeFromScale(scale: _EuiThemeFontScale, { base, font }: UseEuiTheme['euiTheme'], { unit, customScale }?: _FontScaleOptions): string;
 	/**
 	 * Calculates the line-height to the closest multiple of the baseline
 	 * EX: A proper line-height for text is 1.5 times the font-size.
@@ -1392,7 +1417,7 @@ declare module '@elastic/eui/src/global_styling/functions/typography' {
 	 *
 	 * @returns string - Calculated line-height value aligned to baseline
 	 */
-	export function euiLineHeightFromBaseline(scale: _EuiThemeFontScale, { base, font }: UseEuiTheme['euiTheme'], { measurement, customScale }?: _FontScaleOptions): string;
+	export function euiLineHeightFromBaseline(scale: _EuiThemeFontScale, { base, font }: UseEuiTheme['euiTheme'], { unit, customScale }?: _FontScaleOptions): string;
 	/**
 	 * Text weight shifting
 	 *
@@ -7788,6 +7813,20 @@ declare module '@elastic/eui/src/services/theme/context' {
 	export const EuiThemeContext: import("react").Context<EuiThemeComputed<{}>>;
 	export const EuiNestedThemeContext: import("react").Context<EuiThemeNested>;
 
+}
+declare module '@elastic/eui/src/services/emotion/clone_element' {
+	import React from 'react';
+	/**
+	 * React.cloneElement does not work if the cloned element does not already have the
+	 * `css` prop - as a result, we need to use `jsx()` to manually clone the element
+	 * See https://github.com/emotion-js/emotion/issues/1404
+	 */
+	export const cloneElementWithCss: (element: any, props: any) => React.ReactElement;
+
+}
+declare module '@elastic/eui/src/services/emotion' {
+	export * from '@elastic/eui/src/services/emotion/clone_element';
+
 }
 declare module '@elastic/eui/src/services/theme/emotion' {
 	import { FunctionComponent, PropsWithChildren } from 'react';
@@ -7832,7 +7871,7 @@ declare module '@elastic/eui/src/services/theme/provider' {
 declare module '@elastic/eui/src/services/theme' {
 	export { EuiSystemContext, EuiThemeContext, EuiNestedThemeContext, EuiModificationsContext, EuiColorModeContext, } from '@elastic/eui/src/services/theme/context';
 	export type { UseEuiTheme, WithEuiThemeProps } from '@elastic/eui/src/services/theme/hooks';
-	export { useEuiTheme, withEuiTheme, RenderWithEuiTheme } from '@elastic/eui/src/services/theme/hooks';
+	export { useEuiTheme, withEuiTheme, RenderWithEuiTheme, useEuiThemeCSSVariables, } from '@elastic/eui/src/services/theme/hooks';
 	export type { EuiThemeProviderProps } from '@elastic/eui/src/services/theme/provider';
 	export { EuiThemeProvider } from '@elastic/eui/src/services/theme/provider';
 	export { getEuiDevProviderWarning, setEuiDevProviderWarning } from '@elastic/eui/src/services/theme/warning';
@@ -7940,20 +7979,6 @@ declare module '@elastic/eui/src/services/console' {
 declare module '@elastic/eui/src/services/copy_to_clipboard' {
 	export function copyToClipboard(text: string): boolean;
 
-}
-declare module '@elastic/eui/src/services/emotion/clone_element' {
-	import React from 'react';
-	/**
-	 * React.cloneElement does not work if the cloned element does not already have the
-	 * `css` prop - as a result, we need to use `jsx()` to manually clone the element
-	 * See https://github.com/emotion-js/emotion/issues/1404
-	 */
-	export const cloneElementWithCss: (element: any, props: any) => React.ReactElement;
-
-}
-declare module '@elastic/eui/src/services/emotion' {
-	export * from '@elastic/eui/src/services/emotion/clone_element';
-
 }
 declare module '@elastic/eui/src/services/findElement' {
 	/**
@@ -8518,9 +8543,22 @@ declare module '@elastic/eui/src/components/accessibility' {
 }
 declare module '@elastic/eui/src/components/accordion/accordion.styles' {
 	import { UseEuiTheme } from '@elastic/eui/src/services';
+	export const euiAccordionStyles: ({ euiTheme }: UseEuiTheme) => {
+	    euiAccordion: import("@emotion/utils").SerializedStyles;
+	    borders: {
+	        borders: import("@emotion/utils").SerializedStyles;
+	        horizontal: import("@emotion/utils").SerializedStyles;
+	        all: import("@emotion/utils").SerializedStyles;
+	    };
+	};
 	export const euiAccordionButtonStyles: (euiThemeContext: UseEuiTheme) => {
 	    euiAccordion__button: import("@emotion/utils").SerializedStyles;
 	    disabled: import("@emotion/utils").SerializedStyles;
+	    s: import("@emotion/utils").SerializedStyles;
+	    m: import("@emotion/utils").SerializedStyles;
+	    l: import("@emotion/utils").SerializedStyles;
+	    arrowLeft: import("@emotion/utils").SerializedStyles;
+	    arrowRight: import("@emotion/utils").SerializedStyles;
 	};
 	export const euiAccordionChildrenStyles: ({ euiTheme }: UseEuiTheme) => {
 	    euiAccordion__children: import("@emotion/utils").SerializedStyles;
@@ -8571,9 +8609,14 @@ declare module '@elastic/eui/src/components/accordion/accordion' {
 	     */
 	    buttonClassName?: string;
 	    /**
-	     * Apply more props to the triggering button
+	     * Apply more props to the triggering button.
+	     *
+	     * Includes optional `paddingSize` prop which allows sizes of `s`, `m`, or `l`.
+	     * Note: Padding will not be present on the side closest to the accordion arrow.
 	     */
-	    buttonProps?: CommonProps & HTMLAttributes<HTMLElement>;
+	    buttonProps?: CommonProps & HTMLAttributes<HTMLElement> & {
+	        paddingSize?: 's' | 'm' | 'l';
+	    };
 	    /**
 	     * Class that will apply to the trigger content for the accordion.
 	     */
@@ -8611,6 +8654,10 @@ declare module '@elastic/eui/src/components/accordion/accordion' {
 	     * Placement of the arrow indicator, or 'none' to hide it.
 	     */
 	    arrowDisplay?: 'left' | 'right' | 'none';
+	    /**
+	     * Optional border styling. Defaults to 'none'.
+	     */
+	    borders?: 'horizontal' | 'all' | 'none';
 	    /**
 	     * Control the opening of accordion via prop
 	     */
@@ -8633,6 +8680,7 @@ declare module '@elastic/eui/src/components/accordion/accordion' {
 	export class EuiAccordionClass extends Component<WithEuiThemeProps & EuiAccordionProps, EuiAccordionState> {
 	    static defaultProps: {
 	        initialIsOpen: boolean;
+	        borders: "none";
 	        paddingSize: "none";
 	        arrowDisplay: "left";
 	        isLoading: boolean;
@@ -10580,6 +10628,11 @@ declare module '@elastic/eui/src/components/collapsible_nav_beta/collapsible_nav
 	     * Whether the navigation flyout should default to initially collapsed or expanded
 	     */
 	    initialIsCollapsed?: boolean;
+	    /**
+	     * Optional callback that fires when the user toggles the nav between
+	     * collapsed and uncollapsed states
+	     */
+	    onCollapseToggle?: (isCollapsed: boolean) => void;
 	    /**
 	     * Defaults to 248px wide. The navigation width determines behavior at
 	     * various responsive breakpoints.
@@ -14206,6 +14259,20 @@ declare module '@elastic/eui/src/components/description_list/description_list_ty
 	     * Only applies to `column` and `responsiveColumn` types.
 	     */
 	    columnGutterSize?: EuiDescriptionListColumnGapSizes;
+	    /**
+	     * Allows customizing specific column widths (e.g. `['100px', '200px']`). The first
+	     * array value applies to the title column, and the second applies to the description column.
+	     *
+	     * Passing numbers instead of CSS width strings will use a ratio of widths.
+	     * For example, [1, 3] will render a description column 3x the width of the title column.
+	     * In other words, descriptions will have a width of `75%` and titles will have a width of `25%`.
+	     *
+	     * Only applies to `column` and `responsiveColumn` types.
+	     *
+	     * _Advanced usage note:_ column width strings also accept [CSS grid special units,
+	     * sizing, keywords, and sizing functions](https://css-tricks.com/snippets/css/complete-guide-grid/#aa-special-units-functions).
+	     */
+	    columnWidths?: [number | string, number | string];
 	}
 	export const CHILD_TYPES: readonly ["row", "inline", "column"];
 	export type EuiDescriptionListChildTypes = (typeof CHILD_TYPES)[number];
@@ -16356,6 +16423,12 @@ declare module '@elastic/eui/src/components/header/header' {
 	    theme?: 'default' | 'dark';
 	};
 	export const EuiHeader: FunctionComponent<EuiHeaderProps>;
+	/**
+	 * Fixed headers - logic around dynamically calculating the total
+	 * page offset and setting the `top` position of subsequent headers
+	 */
+	export let euiFixedHeadersCount: number;
+	export const EuiFixedHeader: FunctionComponent<EuiHeaderProps>;
 	export {};
 
 }
@@ -22029,6 +22102,190 @@ declare module '@elastic/eui/src/components/text_diff' {
 	export type { EuiTextDiffProps } from '@elastic/eui/src/components/text_diff/text_diff';
 	export { useEuiTextDiff } from '@elastic/eui/src/components/text_diff/text_diff';
 
+}
+declare module '@elastic/eui/src/components/text_truncate/utils' {
+	import type { ExclusiveUnion } from '@elastic/eui/src/components/common';
+	interface SharedParams {
+	    fullText: string;
+	    ellipsis: string;
+	    availableWidth: number;
+	}
+	interface DOMParams extends SharedParams {
+	    container: HTMLElement;
+	} type CanvasParams = SharedParams & ExclusiveUnion<{
+	    container: HTMLElement;
+	}, {
+	    font: CanvasTextDrawingStyles['font'];
+	}>; abstract class _TruncationUtils {
+	    protected fullText: SharedParams['fullText'];
+	    protected ellipsis: SharedParams['ellipsis'];
+	    protected availableWidth: SharedParams['availableWidth'];
+	    constructor({ fullText, ellipsis, availableWidth }: SharedParams);
+	    /**
+	     * Internal measurement utils which will be overridden depending on the
+	     * rendering approach used (e.g. DOM vs Canvas).
+	     */
+	    abstract textWidth: number;
+	    abstract setTextToCheck: (text: string) => void;
+	    /**
+	     * Early return checks
+	     */
+	    checkIfTruncationIsNeeded: () => false | undefined;
+	    checkSufficientEllipsisWidth: (truncation: string) => false | undefined;
+	    checkTruncationOffsetWidth: (text: string) => false | undefined;
+	    /**
+	     * Truncation types logic. This is where the magic happens
+	     */
+	    truncateStart: (truncationOffset?: number | undefined) => string;
+	    truncateEnd: (truncationOffset?: number | undefined) => string;
+	    truncateStartEndAtPosition: (truncationPosition: number) => string;
+	    truncateStartEndAtMiddle: () => string;
+	    truncateMiddle: () => string;
+	}
+	/**
+	 * Creates a temporary vanilla JS DOM element for manipulating text and
+	 * determining text width.
+	 *
+	 * Requires passing in a container element to which the temporary element
+	 * will be appended. Any CSS/font styles that need to be accounted for should
+	 * be automatically inherited from the container.
+	 *
+	 * NOTE: The consumer is responsible for calling the `cleanup()` method manually
+	 * to remove the temporary DOM node once their usage of this utility is complete.
+	 */
+	export class TruncationUtilsWithDOM extends _TruncationUtils {
+	    container: DOMParams['container'];
+	    span: HTMLSpanElement;
+	    constructor({ container, ...rest }: DOMParams);
+	    get textWidth(): number;
+	    setTextToCheck: (text: string) => void;
+	    cleanup: () => void;
+	}
+	/**
+	 * Creates a temporary Canvas element for manipulating text & determining
+	 * text width. This method is compatible with charts or other canvas-rendered
+	 * frameworks, and requires no cleanup method.
+	 *
+	 * To accurately measure text, canvas rendering requires either a container to
+	 * compute/derive font styles from, or a static font string (useful for usage
+	 * outside the DOM). Particular care should be applied when fallback fonts are
+	 * used, as more fallback fonts can lead to less precision.
+	 *
+	 * Please note that while canvas is more performant than DOM measurement, there
+	 * are subpixel to single digit pixel differences between DOM and canvas
+	 * measurement due to the different rendering engines used.
+	 */
+	export class TruncationUtilsWithCanvas extends _TruncationUtils {
+	    context: CanvasRenderingContext2D;
+	    currentText: string;
+	    constructor({ font, container, ...rest }: CanvasParams);
+	    computeFontFromElement: (element: HTMLElement) => string;
+	    get textWidth(): number;
+	    setTextToCheck: (text: string) => void;
+	}
+	export {};
+
+}
+declare module '@elastic/eui/src/components/text_truncate/text_truncate.styles' {
+	export const euiTextTruncateStyles: {
+	    euiTextTruncate: import("@emotion/utils").SerializedStyles;
+	    /**
+	     * The below CSS is a hack to get double clicking and selecting the *full* text
+	     * instead of the truncated text (useful for copying/pasting, and mimics how
+	     * `text-overflow: ellipsis` works).
+	     *
+	     * Real talk: I'm lowkey amazed it works and it wouldn't surprise me if we ran into
+	     * cross-browser issues with this at some point. Hopefully CSS natively implements
+	     * custom text truncation some day (https://github.com/w3c/csswg-drafts/issues/3937)
+	     * and there'll be no need for the entire component at that point 🙏
+	     */
+	    truncatedText: import("@emotion/utils").SerializedStyles;
+	    fullText: import("@emotion/utils").SerializedStyles;
+	};
+
+}
+declare module '@elastic/eui/src/components/text_truncate/text_truncate' {
+	import { HTMLAttributes, FunctionComponent, ReactNode } from 'react';
+	import type { CommonProps } from '@elastic/eui/src/components/common'; const TRUNCATION_TYPES: readonly ["end", "start", "startEnd", "middle"];
+	export type EuiTextTruncationTypes = (typeof TRUNCATION_TYPES)[number];
+	export type EuiTextTruncateProps = Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'onResize'> & CommonProps & {
+	    /**
+	     * The full text string to truncate
+	     */
+	    text: string;
+	    /**
+	     * The truncation type desired. Determines where the ellipses are placed.
+	     */
+	    truncation?: EuiTextTruncationTypes;
+	    /**
+	     * This prop **only** applies to the `start` and `end` truncation types.
+	     * It allows preserving a certain number of characters of either the
+	     * starting or ending text.
+	     *
+	     * If the passed offset is greater than the total text length,
+	     * the offset will be ignored.
+	     */
+	    truncationOffset?: number;
+	    /**
+	     * This prop **only** applies to the `startEnd` truncation type.
+	     * It allows customizing the anchor position of the displayed text,
+	     * which otherwise defaults to the middle of the text string.
+	     *
+	     * The primary use case for this prop for is search highlighting - e.g., if
+	     * a user searches for a specific word in the text, pass the index of that
+	     * found word to ensure it is always visible.
+	     *
+	     * This behavior will intelligently detect when positions are close to the start
+	     * or end of the text, and omit leading or trailing ellipses when necessary.
+	     * If the passed position is greater than the total text length,
+	     * the truncation will simply default to `start` instead.
+	     */
+	    truncationPosition?: number;
+	    /**
+	     * Defaults to the horizontal ellipsis character.
+	     * Can be optionally configured to use other punctuation,
+	     * e.g. spaces, brackets, hyphens, asterisks, etc.
+	     */
+	    ellipsis?: string;
+	    /**
+	     * By default, EuiTextTruncate will render a resize observer to detect the
+	     * available width it has. For performance reasons (e.g. multiple truncated
+	     * text items within the same container), you may opt to pass in your own
+	     * container width, which will skip initializing a resize observer.
+	     */
+	    width?: number;
+	    /**
+	     * Optional callback that fires when the default resizer observer both mounts and
+	     * registers a size change. This callback will **not** fire if `width` is passed.
+	     */
+	    onResize?: (width: number) => void;
+	    /**
+	     * By default, EuiTextTruncate will calculate its truncation via DOM manipulation
+	     * and measurement, which has the benefit of automatically inheriting font styles.
+	     * However, if this approach proves to have a significant performance impact for your
+	     * usage, consider using the `canvas` API instead, which is more performant.
+	     *
+	     * Please note that there are minute pixel to subpixel differences between the
+	     * two options due to different rendering engines.
+	     */
+	    measurementRenderAPI?: 'dom' | 'canvas';
+	    /**
+	     * By default, EuiTextTruncate will render the truncated string directly.
+	     * You can optionally pass a render prop function to the component, which
+	     * allows for more flexible text rendering, e.g. adding custom markup
+	     * or highlighting
+	     */
+	    children?: (truncatedString: string) => ReactNode;
+	};
+	export const EuiTextTruncate: FunctionComponent<EuiTextTruncateProps>;
+	export {};
+
+}
+declare module '@elastic/eui/src/components/text_truncate' {
+	export type { EuiTextTruncateProps, EuiTextTruncationTypes, } from '@elastic/eui/src/components/text_truncate/text_truncate';
+	export { EuiTextTruncate } from '@elastic/eui/src/components/text_truncate/text_truncate';
+	export { TruncationUtilsWithDOM, TruncationUtilsWithCanvas } from '@elastic/eui/src/components/text_truncate/utils';
+
 }
 declare module '@elastic/eui/src/components/toast/toast.styles' {
 	import { UseEuiTheme } from '@elastic/eui/src/services';
@@ -22724,6 +22981,7 @@ declare module '@elastic/eui/src/components' {
 	export * from '@elastic/eui/src/components/tabs';
 	export * from '@elastic/eui/src/components/text';
 	export * from '@elastic/eui/src/components/text_diff';
+	export * from '@elastic/eui/src/components/text_truncate';
 	export * from '@elastic/eui/src/components/timeline';
 	export * from '@elastic/eui/src/components/title';
 	export * from '@elastic/eui/src/components/toast';