@vitus-labs/elements 2.0.0-alpha.9 → 2.0.0-beta.1

package/lib/index.js

@@ -1,6 +1,6 @@
 import { Provider, alignContent, extendCss, makeItResponsive, value } from "@vitus-labs/unistyle";
 import { config, context, isEmpty, omit, pick, render, throttle } from "@vitus-labs/core";
-import { Children, createContext, forwardRef, memo, useCallback, useContext, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { Children, createContext, memo, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { isFragment } from "react-is";
 import { createPortal } from "react-dom";
@@ -21,7 +21,7 @@ const IS_DEVELOPMENT = process.env.NODE_ENV !== "production";
 * equalCols flex distribution. The "content" slot gets `flex: 1` to
 * fill remaining space between before and after.
 */
-const { styled: styled$2, css: css$2, component: component$2 } = config;
+const { styled: styled$2, css: css$2, component: component$1 } = config;
 const equalColsCSS = `
   flex: 1;
 `;
@@ -67,7 +67,7 @@ const styles$2 = ({ css, theme: t, rootSize }) => css`
 
   ${t.extraStyles && extendCss(t.extraStyles)};
 `;
-const StyledComponent = styled$2(component$2)`
+const StyledComponent = styled$2(component$1)`
   ${`box-sizing: border-box;`};
 
   display: flex;
@@ -86,11 +86,22 @@ const StyledComponent = styled$2(component$2)`
 
 //#endregion
 //#region src/helpers/Content/component.tsx
-const Component$9 = ({ contentType, tag, parentDirection, direction, alignX, alignY, equalCols, gap, extendCss, ...props }) => {
+/**
+* Memoized content area used inside Element to render one of the three
+* layout slots (before, content, after). Passes alignment, direction,
+* gap, and equalCols styling props to the underlying styled component.
+* Adds a `data-vl-element` attribute in development for debugging.
+*
+* Children are passed as raw content and rendered inside the memo boundary
+* via core `render()` — this lets React.memo skip re-renders when the
+* content reference is stable (common for component-type or string content).
+*/
+const Component$9 = ({ contentType, tag, parentDirection, direction, alignX, alignY, equalCols, gap, extendCss, children, ...props }) => {
+	const debugProps = IS_DEVELOPMENT ? { "data-vl-element": contentType } : {};
 	return /* @__PURE__ */ jsx(StyledComponent, {
 		as: tag,
 		$contentType: contentType,
-		$element: {
+		$element: useMemo(() => ({
 			contentType,
 			parentDirection,
 			direction,
@@ -99,16 +110,26 @@ const Component$9 = ({ contentType, tag, parentDirection, direction, alignX, ali
 			equalCols,
 			gap,
 			extraStyles: extendCss
-		},
-		...IS_DEVELOPMENT ? { "data-vl-element": contentType } : {},
-		...props
+		}), [
+			contentType,
+			parentDirection,
+			direction,
+			alignX,
+			alignY,
+			equalCols,
+			gap,
+			extendCss
+		]),
+		...debugProps,
+		...props,
+		children: render(children)
 	});
 };
-var component_default = memo(Component$9);
+var component_default$1 = memo(Component$9);
 
 //#endregion
 //#region src/helpers/Content/index.ts
-var Content_default = component_default;
+var Content_default = component_default$1;
 
 //#endregion
 //#region src/helpers/Wrapper/styled.ts
@@ -119,7 +140,7 @@ var Content_default = component_default;
 * split flex behavior across two DOM nodes for button/fieldset/legend
 * elements where a single flex container is insufficient.
 */
-const { styled: styled$1, css: css$1, component: component$1 } = config;
+const { styled: styled$1, css: css$1, component } = config;
 const childFixCSS = `
   display: flex;
   flex: 1;
@@ -129,14 +150,12 @@ const childFixCSS = `
 const parentFixCSS = `
   flex-direction: column;
 `;
-const parentFixBlockCSS = `
-  width: 100%;
-`;
 const fullHeightCSS = `
   height: 100%;
 `;
 const blockCSS = `
   align-self: stretch;
+  width: 100%;
 `;
 const childFixPosition = (isBlock) => `display: ${isBlock ? "flex" : "inline-flex"};`;
 const styles$1 = ({ theme: t, css }) => css`
@@ -149,15 +168,15 @@ const styles$1 = ({ theme: t, css }) => css`
 })};
 
   ${t.block && blockCSS};
+  ${t.alignY === "block" && t.block && fullHeightCSS};
 
   ${!t.childFix && childFixPosition(t.block)};
-  ${t.parentFix && t.block && parentFixBlockCSS};
   ${t.parentFix && parentFixCSS};
 
   ${t.extraStyles && extendCss(t.extraStyles)};
 `;
 const platformCSS = `box-sizing: border-box;`;
-var styled_default$1 = styled$1(component$1)`
+var styled_default$1 = styled$1(component)`
   position: relative;
   ${platformCSS};
 
@@ -195,53 +214,68 @@ const isWebFixNeeded = (tag) => {
 //#region src/helpers/Wrapper/component.tsx
 /**
 * Wrapper component that serves as the outermost styled container for Element.
-* Uses forwardRef for ref forwarding to the underlying DOM node. On web, it
-* detects button/fieldset/legend tags and applies a two-layer flex fix
+* On web, it detects button/fieldset/legend tags and applies a two-layer flex fix
 * (parent + child Styled) because these HTML elements do not natively
 * support `display: flex` consistently across browsers.
 */
 const DEV_PROPS = IS_DEVELOPMENT ? { "data-vl-element": "Element" } : {};
-const Component$8 = forwardRef(({ children, tag, block, extendCss, direction, alignX, alignY, equalCols, isInline, ...props }, ref) => {
+const Component$8 = ({ children, ref, tag, block, extendCss, direction, alignX, alignY, equalCols, isInline, ...props }) => {
 	const COMMON_PROPS = {
 		...props,
 		...DEV_PROPS,
 		ref,
 		as: tag
 	};
-	if (!(!props.dangerouslySetInnerHTML && isWebFixNeeded(tag)) || false) return /* @__PURE__ */ jsx(styled_default$1, {
+	const needsFix = !props.dangerouslySetInnerHTML && isWebFixNeeded(tag);
+	const normalElement = useMemo(() => ({
+		block,
+		direction,
+		alignX,
+		alignY,
+		equalCols,
+		extraStyles: extendCss
+	}), [
+		block,
+		direction,
+		alignX,
+		alignY,
+		equalCols,
+		extendCss
+	]);
+	const parentFixElement = useMemo(() => ({
+		parentFix: true,
+		block,
+		extraStyles: extendCss
+	}), [block, extendCss]);
+	const childFixElement = useMemo(() => ({
+		childFix: true,
+		direction,
+		alignX,
+		alignY,
+		equalCols
+	}), [
+		direction,
+		alignX,
+		alignY,
+		equalCols
+	]);
+	if (!needsFix || false) return /* @__PURE__ */ jsx(styled_default$1, {
 		...COMMON_PROPS,
-		$element: {
-			block,
-			direction,
-			alignX,
-			alignY,
-			equalCols,
-			extraStyles: extendCss
-		},
+		$element: normalElement,
 		children
 	});
 	const asTag = isInline ? "span" : "div";
 	return /* @__PURE__ */ jsx(styled_default$1, {
 		...COMMON_PROPS,
-		$element: {
-			parentFix: true,
-			block,
-			extraStyles: extendCss
-		},
+		$element: parentFixElement,
 		children: /* @__PURE__ */ jsx(styled_default$1, {
 			as: asTag,
 			$childFix: true,
-			$element: {
-				childFix: true,
-				direction,
-				alignX,
-				alignY,
-				equalCols
-			},
+			$element: childFixElement,
 			children
 		})
 	});
-});
+};
 
 //#endregion
 //#region src/helpers/Wrapper/index.ts
@@ -332,11 +366,26 @@ const getShouldBeEmpty = (tag) => {
 * like void elements (input, img) and inline elements (span, a) by
 * skipping children or switching sub-tags accordingly.
 */
+const equalize = (el, direction) => {
+	const beforeEl = el.firstElementChild;
+	const afterEl = el.lastElementChild;
+	if (beforeEl && afterEl && beforeEl !== afterEl) {
+		const type = direction === "rows" ? "height" : "width";
+		const prop = type === "height" ? "offsetHeight" : "offsetWidth";
+		const beforeSize = beforeEl[prop];
+		const afterSize = afterEl[prop];
+		if (Number.isInteger(beforeSize) && Number.isInteger(afterSize)) {
+			const maxSize = `${Math.max(beforeSize, afterSize)}px`;
+			beforeEl.style[type] = maxSize;
+			afterEl.style[type] = maxSize;
+		}
+	}
+};
 const defaultDirection = "inline";
 const defaultContentDirection = "rows";
 const defaultAlignX = "left";
 const defaultAlignY = "center";
-const Component$7 = forwardRef(({ innerRef, tag, label, content, children, beforeContent, afterContent, block, equalCols, gap, direction, alignX = defaultAlignX, alignY = defaultAlignY, css, contentCss, beforeContentCss, afterContentCss, contentDirection = defaultContentDirection, contentAlignX = defaultAlignX, contentAlignY = defaultAlignY, beforeContentDirection = defaultDirection, beforeContentAlignX = defaultAlignX, beforeContentAlignY = defaultAlignY, afterContentDirection = defaultDirection, afterContentAlignX = defaultAlignX, afterContentAlignY = defaultAlignY, ...props }, ref) => {
+const Component$7 = ({ innerRef, ref, tag, label, content, children, beforeContent, afterContent, equalBeforeAfter, block, equalCols, gap, direction, alignX = defaultAlignX, alignY = defaultAlignY, css, contentCss, beforeContentCss, afterContentCss, contentDirection = defaultContentDirection, contentAlignX = defaultAlignX, contentAlignY = defaultAlignY, beforeContentDirection = defaultDirection, beforeContentAlignX = defaultAlignX, beforeContentAlignY = defaultAlignY, afterContentDirection = defaultDirection, afterContentAlignX = defaultAlignX, afterContentAlignY = defaultAlignY, ...props }) => {
 	const shouldBeEmpty = !!props.dangerouslySetInnerHTML || getShouldBeEmpty(tag);
 	const isSimpleElement = !beforeContent && !afterContent;
 	const CHILDREN = children ?? content ?? label;
@@ -366,8 +415,30 @@ const Component$7 = forwardRef(({ innerRef, tag, label, content, children, befor
 		alignY,
 		direction
 	]);
+	const equalizeRef = useRef(null);
+	const externalRef = ref ?? innerRef;
+	const mergedRef = useCallback((node) => {
+		equalizeRef.current = node;
+		if (typeof externalRef === "function") externalRef(node);
+		else if (externalRef != null) externalRef.current = node;
+	}, [externalRef]);
+	useLayoutEffect(() => {
+		if (!equalBeforeAfter || !beforeContent || !afterContent) return;
+		const node = equalizeRef.current;
+		if (!node) return;
+		equalize(node, direction);
+		if (typeof ResizeObserver === "undefined") return;
+		const observer = new ResizeObserver(() => equalize(node, direction));
+		observer.observe(node);
+		return () => observer.disconnect();
+	}, [
+		equalBeforeAfter,
+		beforeContent,
+		afterContent,
+		direction
+	]);
 	const WRAPPER_PROPS = {
-		ref: ref ?? innerRef,
+		ref: mergedRef,
 		extendCss: css,
 		tag,
 		block,
@@ -380,7 +451,6 @@ const Component$7 = forwardRef(({ innerRef, tag, label, content, children, befor
 		...props,
 		...WRAPPER_PROPS
 	});
-	const contentRenderOutput = render(CHILDREN);
 	return /* @__PURE__ */ jsxs(Wrapper_default, {
 		...props,
 		...WRAPPER_PROPS,
@@ -396,9 +466,9 @@ const Component$7 = forwardRef(({ innerRef, tag, label, content, children, befor
 				alignY: beforeContentAlignY,
 				equalCols,
 				gap,
-				children: render(beforeContent)
+				children: beforeContent
 			}),
-			isSimpleElement ? contentRenderOutput : /* @__PURE__ */ jsx(Content_default, {
+			isSimpleElement ? render(CHILDREN) : /* @__PURE__ */ jsx(Content_default, {
 				tag: SUB_TAG,
 				contentType: "content",
 				parentDirection: wrapperDirection,
@@ -407,7 +477,7 @@ const Component$7 = forwardRef(({ innerRef, tag, label, content, children, befor
 				alignX: contentAlignX,
 				alignY: contentAlignY,
 				equalCols,
-				children: contentRenderOutput
+				children: CHILDREN
 			}),
 			afterContent && /* @__PURE__ */ jsx(Content_default, {
 				tag: SUB_TAG,
@@ -419,63 +489,16 @@ const Component$7 = forwardRef(({ innerRef, tag, label, content, children, befor
 				alignY: afterContentAlignY,
 				equalCols,
 				gap,
-				children: render(afterContent)
+				children: afterContent
 			})
 		]
 	});
-});
+};
 const name$5 = `${PKG_NAME}/Element`;
 Component$7.displayName = name$5;
 Component$7.pkgName = PKG_NAME;
 Component$7.VITUS_LABS__COMPONENT = name$5;
 
-//#endregion
-//#region src/Element/withEqualSizeBeforeAfter.tsx
-/**
-* HOC that equalizes the dimensions of beforeContent and afterContent areas.
-* After render, it measures both DOM nodes via useLayoutEffect and sets the
-* larger dimension on both so they match. Uses width for inline direction
-* and height for rows direction. This is useful for centering the main
-* content when before/after slots have different intrinsic sizes.
-*/
-const types = {
-	height: "offsetHeight",
-	width: "offsetWidth"
-};
-const equalize = (beforeEl, afterEl, type) => {
-	const prop = types[type];
-	const beforeSize = beforeEl[prop];
-	const afterSize = afterEl[prop];
-	if (Number.isInteger(beforeSize) && Number.isInteger(afterSize)) {
-		const maxSize = `${Math.max(beforeSize, afterSize)}px`;
-		beforeEl.style[type] = maxSize;
-		afterEl.style[type] = maxSize;
-	}
-};
-const withEqualBeforeAfter = (WrappedComponent) => {
-	const displayName = WrappedComponent.displayName ?? WrappedComponent.name ?? "Component";
-	const Enhanced = ({ equalBeforeAfter, direction, afterContent, beforeContent, ref, ...rest }) => {
-		const internalRef = useRef(null);
-		useImperativeHandle(ref, () => internalRef.current);
-		useLayoutEffect(() => {
-			if (!equalBeforeAfter || !beforeContent || !afterContent) return;
-			if (!internalRef.current) return;
-			const el = internalRef.current;
-			const beforeEl = el.firstElementChild;
-			const afterEl = el.lastElementChild;
-			if (beforeEl && afterEl && beforeEl !== afterEl) equalize(beforeEl, afterEl, direction === "rows" ? "height" : "width");
-		});
-		return /* @__PURE__ */ jsx(WrappedComponent, {
-			...rest,
-			afterContent,
-			beforeContent,
-			ref: internalRef
-		});
-	};
-	Enhanced.displayName = `withEqualSizeBeforeAfter(${displayName})`;
-	return Enhanced;
-};
-
 //#endregion
 //#region src/Element/index.ts
 var Element_default = Component$7;
@@ -490,27 +513,6 @@ var Element_default = Component$7;
 * wrapped with `wrapComponent`. Children always take priority over the
 * component+data prop pattern.
 */
-const classifyData = (data) => {
-	const items = data.filter((item) => item != null && !(typeof item === "object" && isEmpty(item)));
-	if (items.length === 0) return null;
-	let isSimple = true;
-	let isComplex = true;
-	for (const item of items) if (typeof item === "string" || typeof item === "number") isComplex = false;
-	else if (typeof item === "object") isSimple = false;
-	else {
-		isSimple = false;
-		isComplex = false;
-	}
-	if (isSimple) return {
-		type: "simple",
-		data: items
-	};
-	if (isComplex) return {
-		type: "complex",
-		data: items
-	};
-	return null;
-};
 const RESERVED_PROPS = [
 	"children",
 	"component",
@@ -521,7 +523,7 @@ const RESERVED_PROPS = [
 	"itemProps",
 	"wrapProps"
 ];
-const attachItemProps = ({ i, length }) => {
+const buildExtendedProps = (i, length) => {
 	const position = i + 1;
 	return {
 		index: i,
@@ -532,113 +534,105 @@ const attachItemProps = ({ i, length }) => {
 		position
 	};
 };
-const Component$6 = (props) => {
-	const { itemKey, valueName, children, component, data, wrapComponent: Wrapper, wrapProps, itemProps } = props;
-	const injectItemProps = useMemo(() => typeof itemProps === "function" ? itemProps : () => itemProps, [itemProps]);
-	const injectWrapItemProps = useMemo(() => typeof wrapProps === "function" ? wrapProps : () => wrapProps, [wrapProps]);
-	const getKey = useCallback((item, index) => {
-		if (typeof itemKey === "function") return itemKey(item, index);
-		return index;
-	}, [itemKey]);
-	const renderChild = (child, total = 1, i = 0) => {
-		if (!itemProps && !Wrapper) return child;
-		const extendedProps = attachItemProps({
-			i,
-			length: total
-		});
-		const finalItemProps = itemProps ? injectItemProps({}, extendedProps) : {};
-		if (Wrapper) return /* @__PURE__ */ jsx(Wrapper, {
-			...wrapProps ? injectWrapItemProps({}, extendedProps) : {},
-			children: render(child, finalItemProps)
-		}, i);
-		return render(child, {
-			key: i,
-			...finalItemProps
-		});
-	};
-	const renderChildren = () => {
-		if (!children) return null;
-		if (Array.isArray(children)) return Children.map(children, (item, i) => renderChild(item, children.length, i));
-		if (isFragment(children)) {
-			const fragmentChildren = children.props.children;
-			const childrenLength = fragmentChildren.length;
-			return fragmentChildren.map((item, i) => renderChild(item, childrenLength, i));
-		}
-		return renderChild(children);
-	};
-	const renderSimpleArray = (data) => {
-		const { length } = data;
-		if (length === 0) return null;
-		return data.map((item, i) => {
-			const key = getKey(item, i);
-			const keyName = valueName ?? "children";
-			const extendedProps = attachItemProps({
-				i,
-				length
-			});
-			const finalItemProps = {
-				...itemProps ? injectItemProps({ [keyName]: item }, extendedProps) : {},
-				[keyName]: item
-			};
-			if (Wrapper) return /* @__PURE__ */ jsx(Wrapper, {
-				...wrapProps ? injectWrapItemProps({ [keyName]: item }, extendedProps) : {},
-				children: render(component, finalItemProps)
-			}, key);
-			return render(component, {
-				key,
-				...finalItemProps
-			});
-		});
-	};
-	const getObjectKey = (item, index) => {
-		if (!itemKey) return item.key ?? item.id ?? item.itemId ?? index;
-		if (typeof itemKey === "function") return itemKey(item, index);
-		if (typeof itemKey === "string") return item[itemKey];
-		return index;
+const resolveCallback = (cb, source, ext) => {
+	if (!cb) return {};
+	return typeof cb === "function" ? cb(source, ext) : cb;
+};
+const renderSpec = (spec, ext, itemProps, wrapProps, Wrapper) => {
+	const finalItemProps = {
+		...resolveCallback(itemProps, spec.source, ext),
+		...spec.base
 	};
-	const renderComplexArray = (data) => {
-		const { length } = data;
-		if (length === 0) return null;
-		return data.map((item, i) => {
-			const { component: itemComponent, ...restItem } = item;
-			const renderItem = itemComponent ?? component;
-			const key = getObjectKey(restItem, i);
-			const extendedProps = attachItemProps({
-				i,
-				length
-			});
-			const finalItemProps = {
-				...itemProps ? injectItemProps(item, extendedProps) : {},
-				...restItem
-			};
-			if (Wrapper && !itemComponent) return /* @__PURE__ */ jsx(Wrapper, {
-				...wrapProps ? injectWrapItemProps(item, extendedProps) : {},
-				children: render(renderItem, finalItemProps)
-			}, key);
-			return render(renderItem, {
-				key,
-				...finalItemProps
-			});
-		});
+	if (Wrapper && !spec.skipWrap) return /* @__PURE__ */ jsx(Wrapper, {
+		...resolveCallback(wrapProps, spec.source, ext),
+		children: spec.isNode ? render(spec.target, finalItemProps) : render(spec.target, finalItemProps)
+	}, spec.key);
+	const propsWithKey = {
+		key: spec.key,
+		...finalItemProps
 	};
-	const renderItems = () => {
-		if (children) return renderChildren();
-		if (component && Array.isArray(data)) {
-			const classified = classifyData(data);
-			if (!classified) return null;
-			if (classified.type === "simple") return renderSimpleArray(classified.data);
-			return renderComplexArray(classified.data);
-		}
-		return null;
+	return spec.isNode ? render(spec.target, propsWithKey) : render(spec.target, propsWithKey);
+};
+/** Normalize children (single, array, or fragment) into an array of nodes. */
+const flattenChildren = (children) => {
+	if (Array.isArray(children)) return children;
+	if (isFragment(children)) return children.props.children;
+	return [children];
+};
+/** Drop nullish entries and empty objects (matches legacy behavior). */
+const filterValidItems = (data) => data.filter((item) => item != null && !(typeof item === "object" && isEmpty(item)));
+/** Determine if the array is uniformly simple (string/number) or complex (object). Mixed → null. */
+const detectKind = (items) => {
+	let kind = null;
+	for (const item of items) {
+		const t = typeof item === "string" || typeof item === "number" ? "simple" : typeof item === "object" ? "complex" : null;
+		if (t === null) return null;
+		if (kind === null) kind = t;
+		else if (kind !== t) return null;
+	}
+	return kind;
+};
+const objectKey = (item, index, itemKey) => {
+	if (!itemKey) return item.key ?? item.id ?? item.itemId ?? index;
+	if (typeof itemKey === "function") return itemKey(item, index);
+	if (typeof itemKey === "string") return item[itemKey] ?? index;
+	return index;
+};
+const buildChildrenSpecs = (children) => flattenChildren(children).map((node, i) => ({
+	key: i,
+	target: node,
+	source: {},
+	base: {},
+	isNode: true,
+	skipWrap: false
+}));
+const buildSimpleSpecs = (items, component, valueName, itemKey) => {
+	const keyName = valueName ?? "children";
+	return items.map((value, i) => ({
+		key: typeof itemKey === "function" ? itemKey(value, i) : i,
+		target: component,
+		source: { [keyName]: value },
+		base: { [keyName]: value },
+		isNode: false,
+		skipWrap: false
+	}));
+};
+const buildObjectSpecs = (items, component, itemKey) => items.map((item, i) => {
+	const { component: itemComponent, ...rest } = item;
+	return {
+		key: objectKey(rest, i, itemKey),
+		target: itemComponent ?? component,
+		source: item,
+		base: rest,
+		isNode: false,
+		skipWrap: Boolean(itemComponent)
 	};
-	return renderItems();
+});
+const buildDataSpecs = (data, component, valueName, itemKey) => {
+	const items = filterValidItems(data);
+	if (items.length === 0) return null;
+	const kind = detectKind(items);
+	if (!kind) return null;
+	return kind === "simple" ? buildSimpleSpecs(items, component, valueName, itemKey) : buildObjectSpecs(items, component, itemKey);
+};
+const Component$6 = ({ itemKey, valueName, children, component, data, wrapComponent: Wrapper, wrapProps, itemProps }) => {
+	let specs = null;
+	if (children) {
+		if (!Array.isArray(children) && !isFragment(children) && !itemProps && !Wrapper) return children;
+		specs = buildChildrenSpecs(children);
+	} else if (component && Array.isArray(data)) specs = buildDataSpecs(data, component, valueName, itemKey);
+	if (!specs || specs.length === 0) return null;
+	const total = specs.length;
+	return Children.toArray(specs.map((spec, i) => renderSpec(spec, buildExtendedProps(i, total), itemProps, wrapProps, Wrapper)));
 };
-Component$6.isIterator = true;
-Component$6.RESERVED_PROPS = RESERVED_PROPS;
+var component_default = Object.assign(memo(Component$6), {
+	isIterator: true,
+	RESERVED_PROPS
+});
 
 //#endregion
 //#region src/helpers/Iterator/index.ts
-var Iterator_default = Component$6;
+var Iterator_default = component_default;
 
 //#endregion
 //#region src/List/component.tsx
@@ -649,7 +643,7 @@ var Iterator_default = Component$6;
 * is wrapped in an Element that receives all non-iterator props (e.g.,
 * layout, alignment, css), allowing the list to be styled as a single block.
 */
-const Component$5 = forwardRef(({ rootElement = false, ...props }, ref) => {
+const Component$5 = ({ rootElement = false, ref, ...props }) => {
 	const renderedList = /* @__PURE__ */ jsx(Iterator_default, { ...pick(props, Iterator_default.RESERVED_PROPS) });
 	if (!rootElement) return renderedList;
 	return /* @__PURE__ */ jsx(Element_default, {
@@ -657,114 +651,12 @@ const Component$5 = forwardRef(({ rootElement = false, ...props }, ref) => {
 		...omit(props, Iterator_default.RESERVED_PROPS),
 		children: renderedList
 	});
-});
+};
 const name$4 = `${PKG_NAME}/List`;
 Component$5.displayName = name$4;
 Component$5.pkgName = PKG_NAME;
 Component$5.VITUS_LABS__COMPONENT = name$4;
 
-//#endregion
-//#region src/List/withActiveState.tsx
-/**
-* HOC that adds single or multi selection state management to a list component.
-* Tracks which items are active via a scalar key (single mode) or a Map of
-* key-to-boolean entries (multi mode). Injects `itemProps` callback that
-* provides each item with `active`, `handleItemActive`, `toggleItemActive`,
-* and other selection helpers. Supports `activeItemRequired` to prevent
-* deselecting the last active item.
-*/
-const RESERVED_KEYS = [
-	"type",
-	"activeItems",
-	"itemProps",
-	"activeItemRequired"
-];
-const component = (WrappedComponent) => {
-	const displayName = WrappedComponent.displayName || WrappedComponent.name || "Component";
-	const Enhanced = (props) => {
-		const { type = "single", activeItemRequired, activeItems, itemProps = {}, ...rest } = props;
-		const initActiveItems = () => {
-			if (type === "single") {
-				if (!Array.isArray(activeItems)) return activeItems;
-			} else if (type === "multi") {
-				const activeItemsHelper = Array.isArray(activeItems) ? activeItems : [activeItems];
-				return new Map(activeItemsHelper.map((id) => [id, true]));
-			}
-		};
-		const [innerActiveItems, setActiveItems] = useState(initActiveItems());
-		const countActiveItems = (data) => {
-			let result = 0;
-			data.forEach((value) => {
-				if (value) result += 1;
-			});
-			return result;
-		};
-		const updateItemState = (key) => {
-			if (type === "single") setActiveItems((prevState) => {
-				if (activeItemRequired) return key;
-				if (prevState === key) return void 0;
-				return key;
-			});
-			else if (type === "multi") setActiveItems((prevState) => {
-				const activeItems = new Map(prevState);
-				if (activeItemRequired && activeItems.get(key) && countActiveItems(activeItems) === 1) return activeItems;
-				activeItems.set(key, !activeItems.get(key));
-				return activeItems;
-			});
-			else setActiveItems(void 0);
-		};
-		const handleItemActive = (key) => {
-			updateItemState(key);
-		};
-		const updateAllItemsState = (status) => {
-			if (!status) setActiveItems(/* @__PURE__ */ new Map());
-		};
-		const setItemActive = (key) => {
-			updateItemState(key);
-		};
-		const unsetItemActive = (key) => {
-			updateItemState(key);
-		};
-		const toggleItemActive = (key) => {
-			updateItemState(key);
-		};
-		const unsetAllItemsActive = () => {
-			updateAllItemsState(false);
-		};
-		const isItemActive = (key) => {
-			if (!innerActiveItems) return false;
-			if (type === "single") return innerActiveItems === key;
-			if (type === "multi" && innerActiveItems instanceof Map) return !!innerActiveItems.get(key);
-			return false;
-		};
-		const attachMultipleProps = { unsetAllItemsActive };
-		const attachItemProps = (props) => {
-			const { key } = props;
-			return {
-				...typeof itemProps === "object" ? itemProps : itemProps(props),
-				active: isItemActive(key),
-				handleItemActive: () => handleItemActive(key),
-				setItemActive,
-				unsetItemActive,
-				toggleItemActive,
-				...type === "multi" ? attachMultipleProps : {}
-			};
-		};
-		useEffect(() => {
-			if (type === "single" && Array.isArray(activeItems)) {
-				if (process.env.NODE_ENV !== "production") console.warn("[@vitus-labs/elements] List/withActiveState: `activeItems` was passed as an array but `type` is \"single\". In single selection mode, `activeItems` should be a single key (string | number). The array value will be ignored.");
-			}
-		}, [type, activeItems]);
-		return /* @__PURE__ */ jsx(WrappedComponent, {
-			...rest,
-			itemProps: attachItemProps
-		});
-	};
-	Enhanced.RESERVED_KEYS = RESERVED_KEYS;
-	Enhanced.displayName = `@vitus-labs/elements/List/withActiveState(${displayName})`;
-	return Enhanced;
-};
-
 //#endregion
 //#region src/List/index.ts
 var List_default = Component$5;
@@ -828,14 +720,12 @@ const Component = ({ children, blocked, setBlocked, setUnblocked }) => {
 };
 
 //#endregion
-//#region src/Overlay/useOverlay.tsx
+//#region src/Overlay/positionMath.ts
 /**
-* Core hook powering the Overlay component. Manages open/close state, DOM
-* event listeners (click, hover, scroll, resize, ESC key), and dynamic
-* positioning of overlay content relative to its trigger. Supports dropdown,
-* tooltip, popover, and modal types with automatic edge-of-viewport flipping.
-* Event handlers are throttled for performance, and nested overlay blocking
-* is coordinated through the overlay context.
+* Pure positioning math for the Overlay component. No React, no DOM mutations.
+* Given the current trigger and content rects (plus alignment options), computes
+* the final viewport-relative position and the alignment that was actually used
+* (which may differ from the requested alignment when an edge would be clipped).
 */
 const sel = (cond, a, b) => cond ? a : b;
 const devWarn = (msg) => {
@@ -1005,24 +895,192 @@ const processVisibilityEvent = (e, active, openOn, closeOn, isTrigger, isContent
 	else if (closeOn === "clickOnTrigger" && isTrigger(e)) hideContent();
 	else if (closeOn === "clickOutsideContent" && !isContent(e)) hideContent();
 };
-const useOverlay = ({ isOpen = false, openOn = "click", closeOn = "click", type = "dropdown", position = "fixed", align = "bottom", alignX = "left", alignY = "bottom", offsetX = 0, offsetY = 0, throttleDelay = 200, parentContainer, closeOnEsc = true, disabled, onOpen, onClose } = {}) => {
+
+//#endregion
+//#region src/Overlay/useEscapeKey.ts
+/** Closes the overlay on Escape keypress when `enabled` and `active`. */
+const useEscapeKey = (enabled, active, blocked, hide) => {
+	useEffect(() => {
+		if (!enabled || !active || blocked) return void 0;
+		const onKey = (e) => {
+			if (e.key === "Escape") hide();
+		};
+		window.addEventListener("keydown", onKey);
+		return () => window.removeEventListener("keydown", onKey);
+	}, [
+		enabled,
+		active,
+		blocked,
+		hide
+	]);
+};
+
+//#endregion
+//#region src/Overlay/useHoverListeners.ts
+/**
+* Hover-based open/close. Uses mouseenter/mouseleave on trigger + content
+* (instead of window-level mousemove) and a configurable delay to bridge
+* the gap between trigger and content elements without flicker.
+*/
+const useHoverListeners = ({ triggerRef, contentRef, isContentLoaded, active, blocked, disabled, openOn, closeOn, hoverDelay, showContent, hideContent }) => {
+	const hoverTimeoutRef = useRef(null);
+	useEffect(() => {
+		if (blocked || disabled || !(openOn === "hover" || closeOn === "hover")) return void 0;
+		const trigger = triggerRef.current;
+		const content = contentRef.current;
+		const clearHoverTimeout = () => {
+			if (hoverTimeoutRef.current != null) {
+				clearTimeout(hoverTimeoutRef.current);
+				hoverTimeoutRef.current = null;
+			}
+		};
+		const scheduleHide = () => {
+			clearHoverTimeout();
+			hoverTimeoutRef.current = setTimeout(hideContent, hoverDelay);
+		};
+		const onTriggerEnter = () => {
+			clearHoverTimeout();
+			if (openOn === "hover" && !active) showContent();
+		};
+		const onTriggerLeave = () => {
+			if (closeOn === "hover" && active) scheduleHide();
+		};
+		const onContentEnter = () => {
+			clearHoverTimeout();
+		};
+		const onContentLeave = () => {
+			if (closeOn === "hover" && active) scheduleHide();
+		};
+		if (trigger) {
+			trigger.addEventListener("mouseenter", onTriggerEnter);
+			trigger.addEventListener("mouseleave", onTriggerLeave);
+		}
+		if (content) {
+			content.addEventListener("mouseenter", onContentEnter);
+			content.addEventListener("mouseleave", onContentLeave);
+		}
+		return () => {
+			clearHoverTimeout();
+			if (trigger) {
+				trigger.removeEventListener("mouseenter", onTriggerEnter);
+				trigger.removeEventListener("mouseleave", onTriggerLeave);
+			}
+			if (content) {
+				content.removeEventListener("mouseenter", onContentEnter);
+				content.removeEventListener("mouseleave", onContentLeave);
+			}
+		};
+	}, [
+		active,
+		isContentLoaded,
+		blocked,
+		disabled,
+		openOn,
+		closeOn,
+		hoverDelay,
+		showContent,
+		hideContent
+	]);
+};
+
+//#endregion
+//#region src/Overlay/useScrollReposition.ts
+let modalOverflowCount = 0;
+/**
+* Window-level scroll/resize listeners that reposition active overlays and
+* re-evaluate close-on-scroll behavior. Also manages the body overflow lock
+* for modal overlays (refcounted across nested modals).
+*/
+const useWindowReposition = (active, type, handleContentPosition, handleVisibility) => {
+	useEffect(() => {
+		if (!active) return void 0;
+		const shouldSetOverflow = type === "modal";
+		const onScroll = (e) => {
+			handleContentPosition();
+			handleVisibility(e);
+		};
+		if (shouldSetOverflow) {
+			modalOverflowCount++;
+			if (modalOverflowCount === 1) document.body.style.overflow = "hidden";
+		}
+		window.addEventListener("resize", handleContentPosition);
+		window.addEventListener("scroll", onScroll, { passive: true });
+		return () => {
+			handleContentPosition.cancel();
+			handleVisibility.cancel();
+			if (shouldSetOverflow) {
+				modalOverflowCount--;
+				if (modalOverflowCount === 0) document.body.style.overflow = "";
+			}
+			window.removeEventListener("resize", handleContentPosition);
+			window.removeEventListener("scroll", onScroll);
+		};
+	}, [
+		active,
+		type,
+		handleContentPosition,
+		handleVisibility
+	]);
+};
+/**
+* Same as `useWindowReposition` but for a custom scrollable ancestor.
+* Locks the parent's overflow while the overlay is active (unless hover-driven,
+* which expects the parent to keep scrolling).
+*/
+const useParentContainerReposition = (active, parentContainer, closeOn, handleContentPosition, handleVisibility) => {
+	useEffect(() => {
+		if (!active || !parentContainer) return void 0;
+		if (closeOn !== "hover") parentContainer.style.overflow = "hidden";
+		const onScroll = (e) => {
+			handleContentPosition();
+			handleVisibility(e);
+		};
+		parentContainer.addEventListener("scroll", onScroll, { passive: true });
+		return () => {
+			parentContainer.style.overflow = "";
+			parentContainer.removeEventListener("scroll", onScroll);
+		};
+	}, [
+		active,
+		parentContainer,
+		closeOn,
+		handleContentPosition,
+		handleVisibility
+	]);
+};
+const useScrollReposition = ({ active, type, parentContainer, closeOn, handleContentPosition, handleVisibility }) => {
+	useWindowReposition(active, type, handleContentPosition, handleVisibility);
+	useParentContainerReposition(active, parentContainer, closeOn, handleContentPosition, handleVisibility);
+};
+
+//#endregion
+//#region src/Overlay/useOverlay.tsx
+/**
+* Core hook powering the Overlay component. Manages open/close state, DOM
+* event listeners (click, hover, scroll, resize, ESC key), and dynamic
+* positioning of overlay content relative to its trigger. Supports dropdown,
+* tooltip, popover, and modal types with automatic edge-of-viewport flipping.
+*
+* Pure positioning math lives in `./positionMath`. Event-listener concerns
+* live in dedicated hooks: `./useEscapeKey`, `./useHoverListeners`,
+* `./useScrollReposition`.
+*/
+const useOverlay = ({ isOpen = false, openOn = "click", closeOn = "click", type = "dropdown", position = "fixed", align = "bottom", alignX = "left", alignY = "bottom", offsetX = 0, offsetY = 0, throttleDelay = 200, parentContainer, closeOnEsc = true, hoverDelay = 100, disabled, onOpen, onClose } = {}) => {
 	const { rootSize } = useContext(context);
 	const ctx = useOverlayContext();
 	const [isContentLoaded, setContentLoaded] = useState(false);
 	const [innerAlignX, setInnerAlignX] = useState(alignX);
 	const [innerAlignY, setInnerAlignY] = useState(alignY);
-	const [blocked, handleBlocked] = useState(false);
-	const [active, handleActive] = useState(isOpen);
+	const [blockedCount, setBlockedCount] = useState(0);
+	const blocked = blockedCount > 0;
+	const [active, setActive] = useState(isOpen);
 	const triggerRef = useRef(null);
 	const contentRef = useRef(null);
-	const setBlocked = useCallback(() => handleBlocked(true), []);
-	const setUnblocked = useCallback(() => handleBlocked(false), []);
-	const showContent = useCallback(() => {
-		handleActive(true);
-	}, []);
-	const hideContent = useCallback(() => {
-		handleActive(false);
-	}, []);
+	const prevFocusRef = useRef(null);
+	const setBlocked = useCallback(() => setBlockedCount((c) => c + 1), []);
+	const setUnblocked = useCallback(() => setBlockedCount((c) => Math.max(0, c - 1)), []);
+	const showContent = useCallback(() => setActive(true), []);
+	const hideContent = useCallback(() => setActive(false), []);
 	const getAncestorOffset = useCallback(() => {
 		if (position !== "absolute" || !contentRef.current) return {
 			top: 0,
@@ -1091,7 +1149,7 @@ const useOverlay = ({ isOpen = false, openOn = "click", closeOn = "click", type
 	const latestHandleVisibility = useRef(handleVisibilityByEventType);
 	latestHandleVisibility.current = handleVisibilityByEventType;
 	const handleContentPosition = useMemo(() => throttle(() => latestSetContentPosition.current(), throttleDelay), [throttleDelay]);
-	const handleClick = handleVisibilityByEventType;
+	const handleClick = useCallback((e) => latestHandleVisibility.current(e), []);
 	const handleVisibility = useMemo(() => throttle((e) => latestHandleVisibility.current(e), throttleDelay), [throttleDelay]);
 	useEffect(() => {
 		setInnerAlignX(alignX);
@@ -1138,60 +1196,30 @@ const useOverlay = ({ isOpen = false, openOn = "click", closeOn = "click", type
 		onOpen
 	]);
 	useEffect(() => {
-		if (!closeOnEsc || !active || blocked) return void 0;
-		const handleEscKey = (e) => {
-			if (e.key === "Escape") hideContent();
-		};
-		window.addEventListener("keydown", handleEscKey);
-		return () => {
-			window.removeEventListener("keydown", handleEscKey);
-		};
+		if (type !== "modal") return;
+		if (active && isContentLoaded && contentRef.current) {
+			prevFocusRef.current = document.activeElement;
+			if (contentRef.current.tabIndex < 0) contentRef.current.tabIndex = -1;
+			contentRef.current.focus();
+		}
+		if (!active && prevFocusRef.current) {
+			prevFocusRef.current.focus();
+			prevFocusRef.current = null;
+		}
 	}, [
 		active,
-		blocked,
-		closeOnEsc,
-		hideContent
+		isContentLoaded,
+		type
 	]);
-	useEffect(() => {
-		if (!active) return void 0;
-		const shouldSetOverflow = type === "modal";
-		const onScroll = (e) => {
-			handleContentPosition();
-			handleVisibility(e);
-		};
-		if (shouldSetOverflow) document.body.style.overflow = "hidden";
-		window.addEventListener("resize", handleContentPosition);
-		window.addEventListener("scroll", onScroll, { passive: true });
-		return () => {
-			if (shouldSetOverflow) document.body.style.overflow = "";
-			window.removeEventListener("resize", handleContentPosition);
-			window.removeEventListener("scroll", onScroll);
-		};
-	}, [
+	useEscapeKey(closeOnEsc, active, blocked, hideContent);
+	useScrollReposition({
 		active,
 		type,
-		handleVisibility,
-		handleContentPosition
-	]);
-	useEffect(() => {
-		if (!active || !parentContainer) return void 0;
-		if (closeOn !== "hover") parentContainer.style.overflow = "hidden";
-		const onScroll = (e) => {
-			handleContentPosition();
-			handleVisibility(e);
-		};
-		parentContainer.addEventListener("scroll", onScroll, { passive: true });
-		return () => {
-			parentContainer.style.overflow = "";
-			parentContainer.removeEventListener("scroll", onScroll);
-		};
-	}, [
-		active,
 		parentContainer,
 		closeOn,
 		handleContentPosition,
 		handleVisibility
-	]);
+	});
 	useEffect(() => {
 		if (blocked || disabled) return void 0;
 		if (openOn === "click" || [
@@ -1199,9 +1227,7 @@ const useOverlay = ({ isOpen = false, openOn = "click", closeOn = "click", type
 			"clickOnTrigger",
 			"clickOutsideContent"
 		].includes(closeOn)) window.addEventListener("click", handleClick);
-		return () => {
-			window.removeEventListener("click", handleClick);
-		};
+		return () => window.removeEventListener("click", handleClick);
 	}, [
 		openOn,
 		closeOn,
@@ -1209,70 +1235,24 @@ const useOverlay = ({ isOpen = false, openOn = "click", closeOn = "click", type
 		disabled,
 		handleClick
 	]);
-	const hoverTimeoutRef = useRef(null);
-	useEffect(() => {
-		if (blocked || disabled || !(openOn === "hover" || closeOn === "hover")) return void 0;
-		const trigger = triggerRef.current;
-		const content = contentRef.current;
-		const clearHoverTimeout = () => {
-			if (hoverTimeoutRef.current != null) {
-				clearTimeout(hoverTimeoutRef.current);
-				hoverTimeoutRef.current = null;
-			}
-		};
-		const scheduleHide = () => {
-			clearHoverTimeout();
-			hoverTimeoutRef.current = setTimeout(hideContent, 100);
-		};
-		const onTriggerEnter = () => {
-			clearHoverTimeout();
-			if (openOn === "hover" && !active) showContent();
-		};
-		const onTriggerLeave = () => {
-			if (closeOn === "hover" && active) scheduleHide();
-		};
-		const onContentEnter = () => {
-			clearHoverTimeout();
-		};
-		const onContentLeave = () => {
-			if (closeOn === "hover" && active) scheduleHide();
-		};
-		if (trigger) {
-			trigger.addEventListener("mouseenter", onTriggerEnter);
-			trigger.addEventListener("mouseleave", onTriggerLeave);
-		}
-		if (content) {
-			content.addEventListener("mouseenter", onContentEnter);
-			content.addEventListener("mouseleave", onContentLeave);
-		}
-		return () => {
-			clearHoverTimeout();
-			if (trigger) {
-				trigger.removeEventListener("mouseenter", onTriggerEnter);
-				trigger.removeEventListener("mouseleave", onTriggerLeave);
-			}
-			if (content) {
-				content.removeEventListener("mouseenter", onContentEnter);
-				content.removeEventListener("mouseleave", onContentLeave);
-			}
-		};
-	}, [
-		active,
+	useHoverListeners({
+		triggerRef,
+		contentRef,
 		isContentLoaded,
+		active,
 		blocked,
 		disabled,
 		openOn,
 		closeOn,
+		hoverDelay,
 		showContent,
 		hideContent
-	]);
+	});
 	return {
 		triggerRef,
 		contentRef: useCallback((node) => {
-			if (node) {
-				contentRef.current = node;
-				setContentLoaded(true);
-			}
+			contentRef.current = node;
+			setContentLoaded(!!node);
 		}, []),
 		active,
 		align,
@@ -1299,11 +1279,22 @@ const useOverlay = ({ isOpen = false, openOn = "click", closeOn = "click", type
 const IS_BROWSER = typeof window !== "undefined";
 const Component$3 = ({ children, trigger, DOMLocation, triggerRefName = "ref", contentRefName = "ref", ...props }) => {
 	const { active, triggerRef, contentRef, showContent, hideContent, align, alignX, alignY, Provider, ...ctx } = useOverlay(props);
-	const { openOn, closeOn } = props;
+	const { openOn, closeOn, type } = props;
+	const contentId = useId();
 	const passHandlers = useMemo(() => openOn === "manual" || closeOn === "manual" || closeOn === "clickOutsideContent", [openOn, closeOn]);
+	const ariaHasPopup = useMemo(() => {
+		switch (type) {
+			case "modal": return "dialog";
+			case "tooltip": return "true";
+			default: return "menu";
+		}
+	}, [type]);
 	return /* @__PURE__ */ jsxs(Fragment, { children: [render(trigger, {
 		[triggerRefName]: triggerRef,
 		active,
+		"aria-expanded": active,
+		"aria-haspopup": ariaHasPopup,
+		"aria-controls": active ? contentId : void 0,
 		...passHandlers ? {
 			showContent,
 			hideContent
@@ -1314,6 +1305,9 @@ const Component$3 = ({ children, trigger, DOMLocation, triggerRefName = "ref", c
 			...ctx,
 			children: render(children, {
 				[contentRefName]: contentRef,
+				id: contentId,
+				role: type === "modal" ? "dialog" : void 0,
+				"aria-modal": type === "modal" ? true : void 0,
 				active,
 				align,
 				alignX,
@@ -1348,9 +1342,11 @@ const styles = ({ css, theme: t }) => css`
   ${t.extraStyles && extendCss(t.extraStyles)};
 `;
 var styled_default = styled(textComponent)`
-  color: inherit;
-  font-weight: inherit;
-  line-height: 1;
+  ${css`
+    color: inherit;
+    font-weight: inherit;
+    line-height: 1;
+  `};
 
   ${makeItResponsive({
 	key: "$text",
@@ -1362,7 +1358,7 @@ var styled_default = styled(textComponent)`
 
 //#endregion
 //#region src/Text/component.tsx
-const Component$2 = forwardRef(({ paragraph, label, children, tag, css, ...props }, ref) => {
+const Component$2 = ({ paragraph, label, children, tag, css, ref, ...props }) => {
 	const renderContent = (as = void 0) => /* @__PURE__ */ jsx(styled_default, {
 		ref,
 		as,
@@ -1374,7 +1370,7 @@ const Component$2 = forwardRef(({ paragraph, label, children, tag, css, ...props
 	if (paragraph) finalTag = "p";
 	else finalTag = tag;
 	return renderContent(finalTag);
-});
+};
 const name$1 = `${PKG_NAME}/Text`;
 Component$2.displayName = name$1;
 Component$2.pkgName = PKG_NAME;
@@ -1409,5 +1405,5 @@ Component$1.VITUS_LABS__COMPONENT = name;
 var Util_default = Component$1;
 
 //#endregion
-export { Element_default as Element, List_default as List, Overlay_default as Overlay, Component as OverlayProvider, Portal_default as Portal, Provider, Text_default as Text, Util_default as Util, useOverlay, component as withActiveState, withEqualBeforeAfter as withEqualSizeBeforeAfter };
+export { Element_default as Element, List_default as List, Overlay_default as Overlay, Component as OverlayProvider, Portal_default as Portal, Provider, Text_default as Text, Util_default as Util, useOverlay };
 //# sourceMappingURL=index.js.map