@vitus-labs/elements 2.0.0-beta.0 → 2.0.0-beta.2

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 import { Provider } from "@vitus-labs/unistyle";
 import { BreakpointKeys, HTMLTags, HTMLTextTags, config, render } from "@vitus-labs/core";
-import * as react from "react";
-import { ComponentType, FC, ForwardRefExoticComponent, ForwardedRef, PropsWithoutRef, ReactNode, RefAttributes } from "react";
+import * as _$react from "react";
+import { ComponentType, FC, ForwardRefExoticComponent, ForwardedRef, ReactElement, ReactNode } from "react";
 
 //#region src/types.d.ts
 type ExtractNullableKeys<T> = { [P in keyof T as T[P] extends null | undefined ? never : P]: T[P] };
@@ -24,8 +24,9 @@ type Direction = ContentDirection | ContentDirection[] | Partial<Record<Breakpoi
 type ResponsiveBoolType = ContentBoolean | ContentBoolean[] | Partial<Record<BreakpointKeys, ContentBoolean>>;
 type Responsive = ContentSimpleValue | ContentSimpleValue[] | Partial<Record<BreakpointKeys, number | string>>;
 type ExtendCss = Css | Css[] | Partial<Record<BreakpointKeys, Css>>;
-type VLForwardedComponent<P extends Record<string, unknown> = {}> = ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<any>> & VLStatic;
-type VLComponent<P extends Record<string, any> = {}> = FC<P> & VLStatic;
+type VLComponent<P extends Record<string, any> = {}> = ((props: P & {
+  ref?: any;
+}) => ReactElement | null) & VLStatic;
 interface VLStatic {
   /**
    * React displayName
@@ -291,7 +292,9 @@ type Props = Partial<{
    */
   afterContentCss: ExtendCss;
 }>;
-type VLElement<P extends Record<string, unknown> = {}> = ForwardRefExoticComponent<PropsWithoutRef<Props & P> & RefAttributes<any>> & VLStatic;
+type VLElement<P extends Record<string, unknown> = {}> = ((props: Props & P & {
+  ref?: any;
+}) => ReactElement | null) & VLStatic;
 //#endregion
 //#region src/Element/component.d.ts
 declare const Component: VLElement;
@@ -385,10 +388,13 @@ declare const Component$3: FC<Context & {
   children: ReactNode;
 }>;
 //#endregion
-//#region src/Overlay/useOverlay.d.ts
+//#region src/Overlay/positionMath.d.ts
 type Align$1 = 'bottom' | 'top' | 'left' | 'right';
 type AlignX$2 = 'left' | 'center' | 'right';
 type AlignY$2 = 'bottom' | 'top' | 'center';
+type OverlayType = 'dropdown' | 'tooltip' | 'popover' | 'modal' | 'custom';
+//#endregion
+//#region src/Overlay/useOverlay.d.ts
 type UseOverlayProps = Partial<{
   /**
    * Defines default state whether **Overlay** component should be active.
@@ -412,7 +418,7 @@ type UseOverlayProps = Partial<{
    * has different positioning calculations than others.
    * @defaultValue `dropdown`
    */
-  type: 'dropdown' | 'tooltip' | 'popover' | 'modal' | 'custom';
+  type: OverlayType;
   /**
    * Defines how `content` is treated regarding CSS positioning.
    * @defaultValue `fixed`
@@ -461,6 +467,12 @@ type UseOverlayProps = Partial<{
    * @defaultValue `true`
    */
   closeOnEsc: boolean;
+  /**
+   * Delay in milliseconds before hiding content on hover leave. Bridges the
+   * gap between trigger and content elements to prevent flicker.
+   * @defaultValue `100`
+   */
+  hoverDelay: number;
   /**
    * When set to `true`, **Overlay** is automatically closed and is blocked for
    * being opened.
@@ -491,11 +503,12 @@ declare const useOverlay: ({
   throttleDelay,
   parentContainer,
   closeOnEsc,
+  hoverDelay,
   disabled,
   onOpen,
   onClose
 }?: Partial<UseOverlayProps>) => {
-  triggerRef: react.RefObject<HTMLElement | null>;
+  triggerRef: _$react.RefObject<HTMLElement | null>;
   contentRef: (node: HTMLElement | null) => void;
   active: boolean;
   align: Align$1;
@@ -506,8 +519,8 @@ declare const useOverlay: ({
   blocked: boolean;
   setBlocked: () => void;
   setUnblocked: () => void;
-  Provider: react.FC<Context & {
-    children: react.ReactNode;
+  Provider: _$react.FC<Context & {
+    children: _$react.ReactNode;
   }>;
 };
 //#endregion
@@ -601,7 +614,7 @@ type Props$5 = Partial<{
    */
   css: ExtendCss;
 }>;
-declare const Component$5: VLForwardedComponent<Props$5> & {
+declare const Component$5: VLComponent<Props$5> & {
   isText?: true;
 };
 //#endregion

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, 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";
@@ -150,27 +150,25 @@ const childFixCSS = `
 const parentFixCSS = `
   flex-direction: column;
 `;
-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`
-  ${t.alignY === "block" && fullHeightCSS};
-
   ${alignContent({
 	direction: t.direction,
 	alignX: t.alignX,
 	alignY: t.alignY
 })};
 
-  ${t.block && blockCSS};
-  ${t.alignY === "block" && t.block && fullHeightCSS};
+  /*
+   * Always emit a value for the block-related properties so a responsive
+   * theme that flips from \`block: true\` at one breakpoint to \`block: false\`
+   * at another resets cleanly. Previously \`align-self\` / \`width\` / \`height\`
+   * were only set when the truthy branch matched, which left the prior
+   * breakpoint's values cascading through.
+   */
+  ${`align-self: ${t.block ? "stretch" : "auto"};
+     width: ${t.block ? "100%" : "auto"};
+     height: ${t.alignY === "block" ? "100%" : "auto"};`};
 
-  ${!t.childFix && childFixPosition(t.block)};
+  ${!t.childFix && `display: ${t.block ? "flex" : "inline-flex"};`};
   ${t.parentFix && parentFixCSS};
 
   ${t.extraStyles && extendCss(t.extraStyles)};
@@ -214,13 +212,12 @@ 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,
@@ -276,7 +273,7 @@ const Component$8 = forwardRef(({ children, tag, block, extendCss, direction, al
 			children
 		})
 	});
-});
+};
 
 //#endregion
 //#region src/helpers/Wrapper/index.ts
@@ -386,7 +383,7 @@ const defaultDirection = "inline";
 const defaultContentDirection = "rows";
 const defaultAlignX = "left";
 const defaultAlignY = "center";
-const Component$7 = forwardRef(({ innerRef, 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 }, 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;
@@ -425,7 +422,13 @@ const Component$7 = forwardRef(({ innerRef, tag, label, content, children, befor
 	}, [externalRef]);
 	useLayoutEffect(() => {
 		if (!equalBeforeAfter || !beforeContent || !afterContent) return;
-		if (equalizeRef.current) equalize(equalizeRef.current, direction);
+		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,
@@ -488,7 +491,7 @@ const Component$7 = forwardRef(({ innerRef, tag, label, content, children, befor
 			})
 		]
 	});
-});
+};
 const name$5 = `${PKG_NAME}/Element`;
 Component$7.displayName = name$5;
 Component$7.pkgName = PKG_NAME;
@@ -508,27 +511,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",
@@ -539,7 +521,7 @@ const RESERVED_PROPS = [
 	"itemProps",
 	"wrapProps"
 ];
-const attachItemProps = ({ i, length }) => {
+const buildExtendedProps = (i, length) => {
 	const position = i + 1;
 	return {
 		index: i,
@@ -550,106 +532,96 @@ 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)));
 };
 var component_default = Object.assign(memo(Component$6), {
 	isIterator: true,
@@ -669,7 +641,7 @@ var Iterator_default = component_default;
 * 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, {
@@ -677,7 +649,7 @@ 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;
@@ -746,14 +718,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) => {
@@ -923,24 +893,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,
@@ -1009,7 +1147,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);
@@ -1056,62 +1194,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 () => {
-			handleContentPosition.cancel();
-			handleVisibility.cancel();
-			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" || [
@@ -1119,9 +1225,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,
@@ -1129,63 +1233,19 @@ 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) => {
@@ -1217,11 +1277,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
@@ -1232,6 +1303,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,
@@ -1282,7 +1356,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,
@@ -1294,7 +1368,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;

package/lib/vitus-labs-elements.native.js

@@ -1,6 +1,6 @@
 import { Provider, alignContent, extendCss, makeItResponsive, value } from "@vitus-labs/unistyle";
 import { config, isEmpty, omit, pick, render } from "@vitus-labs/core";
-import { Children, forwardRef, memo, useCallback, useLayoutEffect, useMemo, useRef } from "react";
+import { Children, memo, useCallback, useLayoutEffect, useMemo, useRef } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { isFragment } from "react-is";
 
@@ -146,20 +146,20 @@ const childFixCSS = `
   width: 100%;
   height: 100%;
 `;
-const blockCSS = `
-  align-self: stretch;
-  width: 100%;
-`;
 const styles$1 = ({ theme: t, css }) => css`
-  ${false};
-
   ${alignContent({
 	direction: t.direction,
 	alignX: t.alignX,
 	alignY: t.alignY
 })};
 
-  ${t.block && blockCSS};
+  /*
+   * Always emit a value for the block-related properties so a responsive
+   * theme that flips from \`block: true\` at one breakpoint to \`block: false\`
+   * at another resets cleanly. Previously \`align-self\` / \`width\` / \`height\`
+   * were only set when the truthy branch matched, which left the prior
+   * breakpoint's values cascading through.
+   */
   ${false};
 
   ${false};
@@ -186,13 +186,12 @@ var styled_default$1 = styled$1(component)`
 //#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$5 = forwardRef(({ children, tag, block, extendCss, direction, alignX, alignY, equalCols, isInline, ...props }, ref) => {
+const Component$5 = ({ children, ref, tag, block, extendCss, direction, alignX, alignY, equalCols, isInline, ...props }) => {
 	const COMMON_PROPS = {
 		...props,
 		...DEV_PROPS,
@@ -236,7 +235,7 @@ const Component$5 = forwardRef(({ children, tag, block, extendCss, direction, al
 		$element: normalElement,
 		children
 	});
-});
+};
 
 //#endregion
 //#region src/helpers/Wrapper/index.ts
@@ -256,7 +255,7 @@ const defaultDirection = "inline";
 const defaultContentDirection = "rows";
 const defaultAlignX = "left";
 const defaultAlignY = "center";
-const Component$4 = forwardRef(({ innerRef, 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 }, ref) => {
+const Component$4 = ({ 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 isSimpleElement = !beforeContent && !afterContent;
 	const CHILDREN = children ?? content ?? label;
 	const isInline = false;
@@ -350,7 +349,7 @@ const Component$4 = forwardRef(({ innerRef, tag, label, content, children, befor
 			})
 		]
 	});
-});
+};
 const name$3 = `${PKG_NAME}/Element`;
 Component$4.displayName = name$3;
 Component$4.pkgName = PKG_NAME;
@@ -370,27 +369,6 @@ var Element_default = Component$4;
 * 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",
@@ -401,7 +379,7 @@ const RESERVED_PROPS = [
 	"itemProps",
 	"wrapProps"
 ];
-const attachItemProps = ({ i, length }) => {
+const buildExtendedProps = (i, length) => {
 	const position = i + 1;
 	return {
 		index: i,
@@ -412,106 +390,96 @@ const attachItemProps = ({ i, length }) => {
 		position
 	};
 };
-const Component$3 = (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$3 = ({ 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)));
 };
 var component_default = Object.assign(memo(Component$3), {
 	isIterator: true,
@@ -531,7 +499,7 @@ var Iterator_default = component_default;
 * 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$2 = forwardRef(({ rootElement = false, ...props }, ref) => {
+const Component$2 = ({ 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, {
@@ -539,7 +507,7 @@ const Component$2 = forwardRef(({ rootElement = false, ...props }, ref) => {
 		...omit(props, Iterator_default.RESERVED_PROPS),
 		children: renderedList
 	});
-});
+};
 const name$2 = `${PKG_NAME}/List`;
 Component$2.displayName = name$2;
 Component$2.pkgName = PKG_NAME;
@@ -574,7 +542,7 @@ var styled_default = styled(textComponent)`
 
 //#endregion
 //#region src/Text/component.tsx
-const Component$1 = forwardRef(({ paragraph, label, children, tag, css, ...props }, ref) => {
+const Component$1 = ({ paragraph, label, children, tag, css, ref, ...props }) => {
 	const renderContent = (as = void 0) => /* @__PURE__ */ jsx(styled_default, {
 		ref,
 		as,
@@ -584,7 +552,7 @@ const Component$1 = forwardRef(({ paragraph, label, children, tag, css, ...props
 	});
 	let finalTag;
 	return renderContent(finalTag);
-});
+};
 const name$1 = `${PKG_NAME}/Text`;
 Component$1.displayName = name$1;
 Component$1.pkgName = PKG_NAME;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitus-labs/elements",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0-beta.2",
   "license": "MIT",
   "author": "Vit Bokisch <vit@bokisch.cz>",
   "maintainers": [
@@ -58,8 +58,8 @@
     "version": "node ../../scripts/sync-peer-deps.mjs"
   },
   "peerDependencies": {
-    "@vitus-labs/core": "2.0.0-alpha.27",
-    "@vitus-labs/unistyle": "2.0.0-alpha.27",
+    "@vitus-labs/core": "2.0.0-beta.2",
+    "@vitus-labs/unistyle": "2.0.0-beta.2",
     "react": ">= 19",
     "react-dom": ">= 19",
     "react-native": ">= 0.76"
@@ -73,15 +73,14 @@
     }
   },
   "devDependencies": {
-    "@vitus-labs/core": "2.0.0-beta.0",
-    "@vitus-labs/rocketstyle": "2.0.0-beta.0",
-    "@vitus-labs/tools-rolldown": "1.10.0",
-    "@vitus-labs/tools-storybook": "1.10.0",
-    "@vitus-labs/tools-typescript": "1.10.0",
-    "@vitus-labs/unistyle": "2.0.0-beta.0"
+    "@vitus-labs/core": "workspace:*",
+    "@vitus-labs/rocketstyle": "workspace:*",
+    "@vitus-labs/tools-rolldown": "2.2.0",
+    "@vitus-labs/tools-storybook": "2.2.0",
+    "@vitus-labs/tools-typescript": "2.1.0",
+    "@vitus-labs/unistyle": "workspace:*"
   },
   "dependencies": {
     "react-is": "^19.2.4"
-  },
-  "gitHead": "dd8b9f356086ecd8bfb69c87fcad1e8bfa9ab1f4"
+  }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023-present Vit Bokisch
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.