@octanejs/visx 0.1.0

package/src/responsive/components/ParentSize.tsrx

@@ -0,0 +1,66 @@
+import type { CSSProperties, ReactNode, HTMLAttributes } from 'react';
+import type { ParentSizeState, UseParentSizeConfig } from '../hooks/useParentSize.tsrx';
+import useParentSize from '../hooks/useParentSize.tsrx';
+
+export type ParentSizeProvidedProps = ParentSizeState & {
+		ref: HTMLDivElement | null;
+		resize: (state: ParentSizeState) => void;
+	};
+
+export type ParentSizeProps = {
+		/** Optional `className` to add to the outer wrapper `div`. */
+		className?: string;
+		/**
+ * @deprecated - use `style` prop as all other props are passed directly to the outer `div`.
+ * @TODO remove in the next major version.
+ * Optional `style` object to apply to the outer wrapper `div`. Merged with default styles
+ * (`width: 100%; height: 100%; position: relative`); your values take precedence.
+ * */
+		parentSizeStyles?: CSSProperties;
+		/** Child render function `({ width, height, top, left, ref, resize }) => ReactNode`. */
+		children: (args: ParentSizeProvidedProps) => ReactNode;
+	} & UseParentSizeConfig;
+
+const defaultOuterStyles: CSSProperties = { width: '100%', height: '100%', position: 'relative' };
+
+const measurementStyles: CSSProperties = {
+	position: 'absolute',
+	top: 0,
+	right: 0,
+	bottom: 0,
+	left: 0,
+	overflow: 'hidden',
+};
+
+export default function ParentSize({
+	className,
+	children,
+	debounceTime,
+	ignoreDimensions,
+	initialSize,
+	parentSizeStyles,
+	enableDebounceLeadingCall = true,
+	resizeObserverPolyfill,
+	style,
+	...restProps
+}: ParentSizeProps & Omit<HTMLAttributes<HTMLDivElement>, keyof ParentSizeProps>) {
+	const { parentRef, node, resize, ...dimensions } = useParentSize({
+		initialSize,
+		debounceTime,
+		ignoreDimensions,
+		enableDebounceLeadingCall,
+		resizeObserverPolyfill,
+	});
+
+	const outerStyle: CSSProperties = parentSizeStyles
+		? { position: 'relative', ...parentSizeStyles, ...style }
+		: { ...defaultOuterStyles, ...style };
+
+	return <div style={outerStyle} className={className} {...restProps}>
+		<div style={measurementStyles} ref={parentRef}>{children({
+			...dimensions,
+			ref: node,
+			resize,
+		})}</div>
+	</div>;
+}

package/src/responsive/components/ParentSize.tsrx.d.ts

@@ -0,0 +1,21 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { CSSProperties, ReactNode, HTMLAttributes } from 'react';
+import type { ParentSizeState, UseParentSizeConfig } from '../hooks/useParentSize.tsrx';
+export type ParentSizeProvidedProps = ParentSizeState & {
+    ref: HTMLDivElement | null;
+    resize: (state: ParentSizeState) => void;
+};
+export type ParentSizeProps = {
+    /** Optional `className` to add to the outer wrapper `div`. */
+    className?: string;
+    /**
+* @deprecated - use `style` prop as all other props are passed directly to the outer `div`.
+* @TODO remove in the next major version.
+* Optional `style` object to apply to the outer wrapper `div`. Merged with default styles
+* (`width: 100%; height: 100%; position: relative`); your values take precedence.
+* */
+    parentSizeStyles?: CSSProperties;
+    /** Child render function `({ width, height, top, left, ref, resize }) => ReactNode`. */
+    children: (args: ParentSizeProvidedProps) => ReactNode;
+} & UseParentSizeConfig;
+export default function ParentSize({ className, children, debounceTime, ignoreDimensions, initialSize, parentSizeStyles, enableDebounceLeadingCall, resizeObserverPolyfill, style, ...restProps }: ParentSizeProps & Omit<HTMLAttributes<HTMLDivElement>, keyof ParentSizeProps>): import("react").JSX.Element;

package/src/responsive/components/ScaleSVG.tsrx

@@ -0,0 +1,44 @@
+import type { ReactNode, Ref } from 'react';
+
+export type ScaleSVGProps = {
+	/** Child SVG to scale, rendered as the child of the parent wrappers provided by this component `<div><svg>{children}</svg></div>`. */
+	children?: ReactNode;
+	/** Width of the desired SVG. */
+	width?: number | string;
+	/** Height of the desired SVG. */
+	height?: number | string;
+	/** xOrigin of the desired SVG. */
+	xOrigin?: number | string;
+	/** yOrigin of the desired SVG. */
+	yOrigin?: number | string;
+	/** Whether to preserve SVG aspect ratio. */
+	preserveAspectRatio?: string;
+	/** Ref to the parent `<svg />` used for scaling. */
+	innerRef?: Ref<SVGSVGElement>;
+};
+
+export default function ScaleSVG({
+	children,
+	width,
+	height,
+	xOrigin = 0,
+	yOrigin = 0,
+	preserveAspectRatio = 'xMinYMin meet',
+	innerRef,
+}: ScaleSVGProps) {
+	return <div
+		style={{
+			display: 'inline-block',
+			position: 'relative',
+			width: '100%',
+			verticalAlign: 'top',
+			overflow: 'hidden',
+		}}
+	>
+		<svg
+			preserveAspectRatio={preserveAspectRatio}
+			viewBox={`${xOrigin} ${yOrigin} ${width} ${height}`}
+			ref={innerRef}
+		>{children}</svg>
+	</div>;
+}

package/src/responsive/components/ScaleSVG.tsrx.d.ts

@@ -0,0 +1,19 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { ReactNode, Ref } from 'react';
+export type ScaleSVGProps = {
+    /** Child SVG to scale, rendered as the child of the parent wrappers provided by this component `<div><svg>{children}</svg></div>`. */
+    children?: ReactNode;
+    /** Width of the desired SVG. */
+    width?: number | string;
+    /** Height of the desired SVG. */
+    height?: number | string;
+    /** xOrigin of the desired SVG. */
+    xOrigin?: number | string;
+    /** yOrigin of the desired SVG. */
+    yOrigin?: number | string;
+    /** Whether to preserve SVG aspect ratio. */
+    preserveAspectRatio?: string;
+    /** Ref to the parent `<svg />` used for scaling. */
+    innerRef?: Ref<SVGSVGElement>;
+};
+export default function ScaleSVG({ children, width, height, xOrigin, yOrigin, preserveAspectRatio, innerRef, }: ScaleSVGProps): import("react").JSX.Element;

package/src/responsive/enhancers/withParentSize.tsrx

@@ -0,0 +1,101 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'octane';
+import type { ComponentType, CSSProperties } from 'react';
+import type { DebounceSettings, Simplify, PrivateWindow, ResizeObserverPolyfill } from '../types';
+import { debounce } from '../utils/debounce';
+
+const CONTAINER_STYLES: CSSProperties = {
+	width: '100%',
+	height: '100%',
+	position: 'relative',
+};
+
+const MEASUREMENT_STYLES: CSSProperties = {
+	position: 'absolute',
+	top: 0,
+	right: 0,
+	bottom: 0,
+	left: 0,
+	overflow: 'hidden',
+};
+
+/** @deprecated @TODO remove in the next major version - exported for backwards compatibility */
+export type WithParentSizeProps = DebounceSettings;
+
+type WithParentSizeConfig = {
+	initialWidth?: number;
+	initialHeight?: number;
+} & DebounceSettings;
+
+type WithParentSizeState = {
+	parentWidth?: number;
+	parentHeight?: number;
+};
+
+export type WithParentSizeProvidedProps = WithParentSizeState;
+
+type WithParentSizeComponentProps<P extends WithParentSizeProvidedProps> = Simplify<
+	Omit<P, keyof WithParentSizeProvidedProps> & WithParentSizeConfig
+>;
+
+export default function withParentSize<P extends WithParentSizeProvidedProps>(
+	BaseComponent: ComponentType<P>,
+	resizeObserverPolyfill?: ResizeObserverPolyfill,
+): ComponentType<WithParentSizeComponentProps<P>> {
+	function WrappedComponent(props: WithParentSizeComponentProps<P>) {
+		const [size, setSize] = useState<WithParentSizeState>({});
+		const containerRef = useRef<HTMLDivElement | null>(null);
+		const animationFrameRef = useRef(0);
+		const resize = useMemo(
+			() =>
+				debounce(
+					({ width, height }: { width: number; height: number }) => {
+						setSize({ parentWidth: width, parentHeight: height });
+					},
+					props.debounceTime ?? 300,
+					{ leading: props.enableDebounceLeadingCall ?? true },
+				),
+			[props.debounceTime, props.enableDebounceLeadingCall],
+		);
+		const setContainerRef = useCallback((node: HTMLDivElement | null) => {
+			containerRef.current = node;
+		}, []);
+
+		useEffect(() => {
+			const ResizeObserverLocal =
+				resizeObserverPolyfill || (window as unknown as PrivateWindow).ResizeObserver;
+			const observer = new ResizeObserverLocal((entries) => {
+				entries.forEach((entry) => {
+					const { width, height } = entry.contentRect;
+					animationFrameRef.current = window.requestAnimationFrame(() => {
+						resize({ width, height });
+					});
+				});
+			});
+			if (containerRef.current) observer.observe(containerRef.current);
+			return () => {
+				window.cancelAnimationFrame(animationFrameRef.current);
+				observer.disconnect();
+				resize.cancel();
+			};
+		}, [resize]);
+
+		const parentWidth = size.parentWidth ?? props.initialWidth;
+		const parentHeight = size.parentHeight ?? props.initialHeight;
+		return (
+			<div style={CONTAINER_STYLES}>
+				<div style={MEASUREMENT_STYLES} ref={setContainerRef}>
+					{parentWidth != null && parentHeight != null && (
+						<BaseComponent
+							parentWidth={parentWidth}
+							parentHeight={parentHeight}
+							{...(props as P)}
+						/>
+					)}
+				</div>
+			</div>
+		);
+	}
+
+	WrappedComponent.displayName = `withParentSize(${BaseComponent.displayName ?? BaseComponent.name ?? 'Component'})`;
+	return WrappedComponent as ComponentType<WithParentSizeComponentProps<P>>;
+}

package/src/responsive/enhancers/withParentSize.tsrx.d.ts

@@ -0,0 +1,17 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { ComponentType } from 'react';
+import type { DebounceSettings, Simplify, ResizeObserverPolyfill } from '../types';
+/** @deprecated @TODO remove in the next major version - exported for backwards compatibility */
+export type WithParentSizeProps = DebounceSettings;
+type WithParentSizeConfig = {
+    initialWidth?: number;
+    initialHeight?: number;
+} & DebounceSettings;
+type WithParentSizeState = {
+    parentWidth?: number;
+    parentHeight?: number;
+};
+export type WithParentSizeProvidedProps = WithParentSizeState;
+type WithParentSizeComponentProps<P extends WithParentSizeProvidedProps> = Simplify<Omit<P, keyof WithParentSizeProvidedProps> & WithParentSizeConfig>;
+export default function withParentSize<P extends WithParentSizeProvidedProps>(BaseComponent: ComponentType<P>, resizeObserverPolyfill?: ResizeObserverPolyfill): ComponentType<WithParentSizeComponentProps<P>>;
+export {};

package/src/responsive/enhancers/withScreenSize.tsrx

@@ -0,0 +1,64 @@
+import { useEffect, useMemo, useState } from 'octane';
+import type { ComponentType } from 'react';
+import type { Simplify, DebounceSettings } from '../types';
+import { debounce } from '../utils/debounce';
+
+type WithScreenSizeConfig = {
+	/** @deprecated use `debounceTime` instead */
+	windowResizeDebounceTime?: number;
+} & DebounceSettings;
+
+/** @deprecated @TODO remove in the next major version - exported for backwards compatibility */
+export type WithParentSizeProps = Omit<WithScreenSizeConfig, 'debounceTime'>;
+
+type WithScreenSizeState = {
+	screenWidth?: number;
+	screenHeight?: number;
+};
+
+export type WithScreenSizeProvidedProps = WithScreenSizeState;
+
+type WithScreenSizeComponentProps<P extends WithScreenSizeProvidedProps> = Simplify<
+	Omit<P, keyof WithScreenSizeProvidedProps> & WithScreenSizeConfig
+>;
+
+export default function withScreenSize<P extends WithScreenSizeProvidedProps>(
+	BaseComponent: ComponentType<P>,
+): ComponentType<WithScreenSizeComponentProps<P>> {
+	function WrappedComponent(props: WithScreenSizeComponentProps<P>) {
+		const [size, setSize] = useState<WithScreenSizeState>({});
+		const resize = useMemo(
+			() =>
+				debounce(
+					() =>
+						setSize({
+							screenWidth: window.innerWidth,
+							screenHeight: window.innerHeight,
+						}),
+					props.debounceTime ?? props.windowResizeDebounceTime ?? 300,
+					{ leading: props.enableDebounceLeadingCall ?? true },
+				),
+			[props.debounceTime, props.enableDebounceLeadingCall, props.windowResizeDebounceTime],
+		);
+
+		useEffect(() => {
+			window.addEventListener('resize', resize, false);
+			resize();
+			return () => {
+				window.removeEventListener('resize', resize, false);
+				resize.cancel();
+			};
+		}, [resize]);
+
+		return size.screenWidth == null || size.screenHeight == null ? null : (
+			<BaseComponent
+				screenWidth={size.screenWidth}
+				screenHeight={size.screenHeight}
+				{...(props as P)}
+			/>
+		);
+	}
+
+	WrappedComponent.displayName = `withScreenSize(${BaseComponent.displayName ?? BaseComponent.name ?? 'Component'})`;
+	return WrappedComponent as ComponentType<WithScreenSizeComponentProps<P>>;
+}

package/src/responsive/enhancers/withScreenSize.tsrx.d.ts

@@ -0,0 +1,17 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { ComponentType } from 'react';
+import type { Simplify, DebounceSettings } from '../types';
+type WithScreenSizeConfig = {
+    /** @deprecated use `debounceTime` instead */
+    windowResizeDebounceTime?: number;
+} & DebounceSettings;
+/** @deprecated @TODO remove in the next major version - exported for backwards compatibility */
+export type WithParentSizeProps = Omit<WithScreenSizeConfig, 'debounceTime'>;
+type WithScreenSizeState = {
+    screenWidth?: number;
+    screenHeight?: number;
+};
+export type WithScreenSizeProvidedProps = WithScreenSizeState;
+type WithScreenSizeComponentProps<P extends WithScreenSizeProvidedProps> = Simplify<Omit<P, keyof WithScreenSizeProvidedProps> & WithScreenSizeConfig>;
+export default function withScreenSize<P extends WithScreenSizeProvidedProps>(BaseComponent: ComponentType<P>): ComponentType<WithScreenSizeComponentProps<P>>;
+export {};

package/src/responsive/hooks/useParentSize.tsrx

@@ -0,0 +1,103 @@
+import type { Ref } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'octane';
+import type { DebounceSettings, PrivateWindow, ResizeObserverPolyfill } from '../types';
+import { debounce } from '../utils/debounce';
+
+export type ParentSizeState = {
+	width: number;
+	height: number;
+	top: number;
+	left: number;
+};
+
+export type UseParentSizeConfig<T extends HTMLElement = HTMLDivElement> = {
+		/** Initial size before measuring the parent. */
+		initialSize?: Partial<ParentSizeState>;
+		/** Optionally inject a ResizeObserver polyfill, else this *must* be globally available. */
+		resizeObserverPolyfill?: ResizeObserverPolyfill;
+		/** Optional dimensions provided won't trigger a state change when changed. */
+		ignoreDimensions?: keyof ParentSizeState | (keyof ParentSizeState)[];
+		/** Optional external ref that also receives the measured DOM node. */
+		externalRef?: Ref<T>;
+	} & DebounceSettings;
+
+export type UseParentSizeResult<T extends HTMLElement = HTMLDivElement> = ParentSizeState & {
+		parentRef: (node: T | null) => void;
+		node: T | null;
+		resize: (state: ParentSizeState) => void;
+	};
+
+const defaultIgnoreDimensions: UseParentSizeConfig['ignoreDimensions'] = [];
+const defaultInitialSize: ParentSizeState = {
+	width: 0,
+	height: 0,
+	top: 0,
+	left: 0,
+};
+
+export default function useParentSize<T extends HTMLElement = HTMLDivElement>(
+	{
+		initialSize = defaultInitialSize,
+		debounceTime = 300,
+		ignoreDimensions = defaultIgnoreDimensions,
+		enableDebounceLeadingCall = true,
+		resizeObserverPolyfill,
+		externalRef,
+	}: UseParentSizeConfig<T> = {},
+): UseParentSizeResult<T> {
+	const [node, setNode] = useState<T | null>(null);
+	const parentRef = useCallback((el: T | null) => {
+		setNode(el);
+		if (typeof externalRef === 'function') {
+			externalRef(el);
+		} else if (externalRef != null) {
+			// eslint-disable-next-line no-param-reassign -- standard ref-merging pattern
+			(externalRef as { current: T | null }).current = el;
+		}
+	}, [externalRef]);
+	const animationFrameID = useRef(0);
+
+	const [state, setState] = useState<ParentSizeState>({ ...defaultInitialSize, ...initialSize });
+
+	const resize = useMemo(() => {
+		const normalized = Array.isArray(ignoreDimensions) ? ignoreDimensions : [ignoreDimensions];
+
+		return debounce((incoming: ParentSizeState) => {
+			setState((existing) => {
+				const stateKeys = Object.keys(existing) as (keyof ParentSizeState)[];
+				const keysWithChanges = stateKeys.filter((key) => existing[key] !== incoming[key]);
+				const shouldBail = keysWithChanges.every((key) => normalized.includes(key));
+
+				return shouldBail ? existing : incoming;
+			});
+		}, debounceTime, { leading: enableDebounceLeadingCall });
+	}, [debounceTime, enableDebounceLeadingCall, ignoreDimensions]);
+
+	useEffect(() => {
+		if (!node) {
+			resize.cancel();
+			return;
+		}
+
+		const LocalResizeObserver =
+			resizeObserverPolyfill || (window as unknown as PrivateWindow).ResizeObserver;
+
+		const observer = new LocalResizeObserver((entries) => {
+			entries.forEach((entry) => {
+				const { left, top, width, height } = entry?.contentRect ?? {};
+				animationFrameID.current = window.requestAnimationFrame(() => {
+					resize({ width, height, top, left });
+				});
+			});
+		});
+		observer.observe(node);
+
+		return () => {
+			window.cancelAnimationFrame(animationFrameID.current);
+			observer.disconnect();
+			resize.cancel();
+		};
+	}, [node, resize, resizeObserverPolyfill]);
+
+	return { parentRef, node, resize, ...state };
+}

package/src/responsive/hooks/useParentSize.tsrx.d.ts

@@ -0,0 +1,25 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { Ref } from 'react';
+import type { DebounceSettings, ResizeObserverPolyfill } from '../types';
+export type ParentSizeState = {
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+};
+export type UseParentSizeConfig<T extends HTMLElement = HTMLDivElement> = {
+    /** Initial size before measuring the parent. */
+    initialSize?: Partial<ParentSizeState>;
+    /** Optionally inject a ResizeObserver polyfill, else this *must* be globally available. */
+    resizeObserverPolyfill?: ResizeObserverPolyfill;
+    /** Optional dimensions provided won't trigger a state change when changed. */
+    ignoreDimensions?: keyof ParentSizeState | (keyof ParentSizeState)[];
+    /** Optional external ref that also receives the measured DOM node. */
+    externalRef?: Ref<T>;
+} & DebounceSettings;
+export type UseParentSizeResult<T extends HTMLElement = HTMLDivElement> = ParentSizeState & {
+    parentRef: (node: T | null) => void;
+    node: T | null;
+    resize: (state: ParentSizeState) => void;
+};
+export default function useParentSize<T extends HTMLElement = HTMLDivElement>({ initialSize, debounceTime, ignoreDimensions, enableDebounceLeadingCall, resizeObserverPolyfill, externalRef, }?: UseParentSizeConfig<T>): UseParentSizeResult<T>;

package/src/responsive/hooks/useScreenSize.tsrx

@@ -0,0 +1,53 @@
+import { useEffect, useMemo, useState } from 'octane';
+import type { DebounceSettings } from '../types/index';
+import { debounce } from '../utils/debounce';
+
+interface ScreenSize {
+	width: number;
+	height: number;
+}
+
+const defaultInitialSize: ScreenSize = {
+	width: 0,
+	height: 0,
+};
+
+export type UseScreenSizeConfig = {
+		/** Initial size before measuring the screen. */
+		initialSize?: ScreenSize;
+	} & DebounceSettings;
+
+const useScreenSize = (
+	{
+		initialSize = defaultInitialSize,
+		debounceTime = 300,
+		enableDebounceLeadingCall = true,
+	}: UseScreenSizeConfig = {},
+) => {
+	const [screenSize, setScreenSize] = useState<ScreenSize>(initialSize);
+
+	const handleResize = useMemo(
+		() => debounce(() => {
+			setScreenSize(
+				() => ({
+					width: window.innerWidth,
+					height: window.innerHeight,
+				}),
+			);
+		}, debounceTime, { leading: enableDebounceLeadingCall }),
+		[debounceTime, enableDebounceLeadingCall],
+	);
+
+	useEffect(() => {
+		handleResize();
+		window.addEventListener('resize', handleResize, false);
+		return () => {
+			window.removeEventListener('resize', handleResize, false);
+			handleResize.cancel();
+		};
+	}, [handleResize]);
+
+	return screenSize;
+};
+
+export default useScreenSize

package/src/responsive/hooks/useScreenSize.tsrx.d.ts

@@ -0,0 +1,12 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { DebounceSettings } from '../types/index';
+interface ScreenSize {
+    width: number;
+    height: number;
+}
+export type UseScreenSizeConfig = {
+    /** Initial size before measuring the screen. */
+    initialSize?: ScreenSize;
+} & DebounceSettings;
+declare const useScreenSize: ({ initialSize, debounceTime, enableDebounceLeadingCall, }?: UseScreenSizeConfig) => ScreenSize;
+export default useScreenSize;

package/src/responsive/index.ts

@@ -0,0 +1,21 @@
+// @octanejs/visx/responsive
+export { default as ParentSize } from './components/ParentSize.tsrx';
+export { default as ScaleSVG } from './components/ScaleSVG.tsrx';
+export { default as withParentSize } from './enhancers/withParentSize.tsrx';
+export type { WithParentSizeProvidedProps } from './enhancers/withParentSize.tsrx';
+export { default as withScreenSize } from './enhancers/withScreenSize.tsrx';
+export type { WithScreenSizeProvidedProps } from './enhancers/withScreenSize.tsrx';
+export { default as useParentSize } from './hooks/useParentSize.tsrx';
+export type {
+	UseParentSizeConfig,
+	UseParentSizeResult,
+	ParentSizeState,
+} from './hooks/useParentSize.tsrx';
+export { default as useScreenSize } from './hooks/useScreenSize.tsrx';
+export type { UseScreenSizeConfig } from './hooks/useScreenSize.tsrx';
+
+export type { ParentSizeProps, ParentSizeProvidedProps } from './components/ParentSize.tsrx';
+export type { ScaleSVGProps } from './components/ScaleSVG.tsrx';
+export type * from './types';
+export { debounce } from './utils/debounce';
+export type { DebouncedFunction } from './utils/debounce';

package/src/responsive/types/index.ts

@@ -0,0 +1,36 @@
+// @TODO remove all these types when upgraded to TS 4 which has its own declaration
+interface ResizeObserverEntry {
+	contentRect: {
+		left: number;
+		top: number;
+		width: number;
+		height: number;
+	};
+}
+
+type ResizeObserverCallback = (entries: ResizeObserverEntry[], observer: ResizeObserver) => void;
+
+export declare class ResizeObserver {
+	constructor(callback: ResizeObserverCallback);
+	observe(target: Element, options?: any): void;
+	unobserve(target: Element): void;
+	disconnect(): void;
+	static toString(): string;
+}
+
+export interface ResizeObserverPolyfill {
+	new (callback: ResizeObserverCallback): ResizeObserver;
+}
+
+export interface PrivateWindow {
+	ResizeObserver: ResizeObserverPolyfill;
+}
+
+export type Simplify<T> = { [Key in keyof T]: T[Key] } & {};
+
+export interface DebounceSettings {
+	/** Child render updates upon resize are delayed until `debounceTime` milliseconds _after_ the last resize event is observed. Defaults to `300`. */
+	debounceTime?: number;
+	/** Optional flag to toggle leading debounce calls. When set to true this will ensure that the component always renders immediately. Defaults to `true`. */
+	enableDebounceLeadingCall?: boolean;
+}

package/src/responsive/utils/debounce.ts

@@ -0,0 +1,59 @@
+export interface DebouncedFunction<T extends (...args: any[]) => any> {
+	(...args: Parameters<T>): void;
+	cancel(): void;
+}
+
+interface DebounceOptions {
+	leading?: boolean;
+}
+
+/**
+ * Creates a debounced function that delays invoking `func` until after `wait` milliseconds
+ * have elapsed since the last invocation.
+ *
+ * When `leading` is true, the function fires immediately on the first call (leading edge),
+ * and also fires on the trailing edge if there were subsequent calls during the wait period
+ * (matching lodash behavior with leading:true, trailing:true).
+ */
+export function debounce<T extends (...args: any[]) => any>(
+	func: T,
+	wait: number,
+	options: DebounceOptions = {},
+): DebouncedFunction<T> {
+	const { leading = false } = options;
+	let timeoutId: ReturnType<typeof setTimeout> | undefined;
+	// Track args for the trailing call; null means no subsequent calls after leading
+	let pendingArgs: Parameters<T> | null = null;
+	let pendingContext: unknown;
+
+	function debounced(this: unknown, ...args: Parameters<T>) {
+		if (leading && timeoutId === undefined) {
+			// Fire immediately on the leading edge, no pending trailing needed yet
+			func.apply(this, args);
+			pendingArgs = null;
+		} else {
+			// Record these args for the trailing call
+			pendingArgs = args;
+			pendingContext = this;
+		}
+
+		clearTimeout(timeoutId);
+		timeoutId = setTimeout(() => {
+			timeoutId = undefined;
+			if (pendingArgs !== null) {
+				func.apply(pendingContext, pendingArgs);
+				pendingArgs = null;
+				pendingContext = undefined;
+			}
+		}, wait);
+	}
+
+	debounced.cancel = function cancel() {
+		clearTimeout(timeoutId);
+		timeoutId = undefined;
+		pendingArgs = null;
+		pendingContext = undefined;
+	};
+
+	return debounced as DebouncedFunction<T>;
+}