@pyreon/elements 0.15.0 → 0.18.0

package/lib/index.d.ts

@@ -182,54 +182,87 @@ type ExtendedProps = {
   even: boolean;
   position: number;
 };
-type PropsCallback = TObj | ((itemProps: Record<string, never> | Record<string, SimpleValue> | ObjectValue, extendedProps: ExtendedProps) => TObj);
-type Props$1 = Partial<{
+/**
+ * Iterator over an array of strings/numbers. Each item is wrapped in
+ * `{ [valueName]: item }` and that object is what callbacks see + what's
+ * spread onto the rendered component.
+ */
+type SimpleProps<T extends SimpleValue> = {
+  data: Array<T | MaybeNull>; /** A component to be rendered per item. */
+  component: ElementType;
   /**
-   * Valid children
-   */
+   * Key under which each primitive value is exposed to `component` and
+   * callbacks. Defaults to `'children'` at runtime — i.e. the value is
+   * passed to the component as its children.
+   */
+  valueName?: string; /** Optional wrapper around each item. */
+  wrapComponent?: ElementType; /** Stable key per item (defaults to index). */
+  itemKey?: (item: T, index: number) => SimpleValue; /** Extra props merged onto the rendered component, optionally per-item. */
+  itemProps?: TObj | ((item: {
+    [k: string]: T;
+  }, ext: ExtendedProps) => TObj); /** Extra props merged onto the wrapper, optionally per-item. */
+  wrapProps?: TObj | ((item: {
+    [k: string]: T;
+  }, ext: ExtendedProps) => TObj);
+  children?: never;
+};
+/**
+ * Iterator over an array of objects. Each item is spread onto the rendered
+ * component as props. Per-item `component` overrides also work — when an
+ * item carries its own `component` field, the wrapper is bypassed.
+ */
+type ObjectProps<T extends ObjectValue> = {
+  data: Array<T | MaybeNull>; /** Default component to be rendered per item (item-level `component` overrides). */
+  component: ElementType; /** `valueName` is meaningless when iterating objects — TS forbids it. */
+  valueName?: never; /** Optional wrapper around each item. */
+  wrapComponent?: ElementType; /** Stable key per item — pick a key from the item, or compute it. */
+  itemKey?: keyof T | ((item: T, index: number) => SimpleValue); /** Extra props merged onto the rendered component, optionally per-item. */
+  itemProps?: TObj | ((item: T, ext: ExtendedProps) => TObj); /** Extra props merged onto the wrapper, optionally per-item. */
+  wrapProps?: TObj | ((item: T, ext: ExtendedProps) => TObj);
+  children?: never;
+};
+/**
+ * Iterator over `children` — no `data`/`component`. Each child gets
+ * positional metadata via `itemProps` and an optional `wrapComponent`.
+ */
+type ChildrenProps = {
+  children: VNodeChild;
+  data?: never;
+  component?: never;
+  valueName?: never;
+  itemKey?: never;
+  wrapComponent?: ElementType;
+  itemProps?: TObj | ((_: Record<string, never>, ext: ExtendedProps) => TObj);
+  wrapProps?: TObj | ((_: Record<string, never>, ext: ExtendedProps) => TObj);
+};
+type PropsCallback = TObj | ((itemProps: Record<string, never> | Record<string, SimpleValue> | ObjectValue, extendedProps: ExtendedProps) => TObj);
+type LooseProps = Partial<{
   children: VNodeChild;
-  /**
-   * Array of data passed to `component` prop
-   */
   data: Array<SimpleValue | ObjectValue | MaybeNull>;
-  /**
-   * A component to be rendered within list
-   */
   component: ElementType;
-  /**
-   * Defines name of the prop to be passed to the iteration component
-   * when **data** prop is type of `string[]`, `number[]` or combination
-   * of both. Otherwise ignored.
-   */
   valueName: string;
-  /**
-   * A component to be rendered within list. `wrapComponent`
-   * wraps `component`. Therefore it can be used to enhance the behavior
-   * of the list component
-   */
   wrapComponent: ElementType;
-  /**
-   * Extension of **item** `component` props to be passed
-   */
   itemProps: PropsCallback;
-  /**
-   * Extension of **item** `wrapComponent` props to be passed
-   */
-  wrapProps?: PropsCallback;
-  /**
-   * Extension of **item** `wrapComponent` props to be passed
-   */
-  itemKey?: keyof ObjectValue | ((item: SimpleValue | Omit<ObjectValue, 'component'>, index: number) => SimpleValue);
+  wrapProps: PropsCallback;
+  itemKey: keyof ObjectValue | ((item: SimpleValue | Omit<ObjectValue, 'component'>, index: number) => SimpleValue);
 }>;
+type Props$1<T = unknown> = unknown extends T ? LooseProps : T extends SimpleValue ? SimpleProps<T> : T extends ObjectValue ? ObjectProps<T> : ChildrenProps;
 //#endregion
 //#region src/helpers/Iterator/component.d.ts
-declare const _default: ((props: Props$1) => VNodeChild) & {
+declare const RESERVED_PROPS: readonly ["children", "component", "wrapComponent", "data", "itemKey", "valueName", "itemProps", "wrapProps"];
+interface IteratorComponent {
+  <T extends SimpleValue>(props: SimpleProps<T>): VNodeChild;
+  <T extends ObjectValue>(props: ObjectProps<T>): VNodeChild;
+  (props: ChildrenProps): VNodeChild;
+  (props: LooseProps): VNodeChild;
   isIterator: true;
-  RESERVED_PROPS: readonly ["children", "component", "wrapComponent", "data", "itemKey", "valueName", "itemProps", "wrapProps"];
-};
+  RESERVED_PROPS: typeof RESERVED_PROPS;
+  displayName?: string;
+}
+declare const Iterator: IteratorComponent;
 //#endregion
 //#region src/List/component.d.ts
-type ListProps = {
+type ListOnly = {
   /**
    * A boolean value. When set to `false`, component returns fragment.
    * When set to `true`, component returns as the **root** element `Element`
@@ -239,14 +272,38 @@ type ListProps = {
   /**
    * Label prop from `Element` component is being ignored.
    */
-  label: never;
+  label?: never;
   /**
    * Content prop from `Element` component is being ignored.
    */
-  content: never;
+  content?: never;
 };
-type Props$2 = MergeTypes<[Props$1, ListProps]> & Partial<Omit<Props, 'children' | 'content' | 'label'>>;
-declare const Component$1: PyreonElement<Props$2>;
+/**
+ * Props that List accepts on top of the Iterator branch — the Element prop
+ * surface (so `tag`, `direction`, `alignX`, etc. forward when
+ * `rootElement` is true) plus the List-only toggle.
+ */
+type ListExtras = Partial<Omit<Props, 'children' | 'content' | 'label'>> & ListOnly;
+/**
+ * Public Props — generic over the data element type so callers get the same
+ * inference Iterator does, plus the List-specific `rootElement` toggle and
+ * Element prop forwarding.
+ *
+ *   Props<string>          → SimpleProps & ListExtras  (valueName REQUIRED)
+ *   Props<{ id; name }>    → ObjectProps & ListExtras  (valueName FORBIDDEN)
+ *   Props<unknown> / Props → LooseProps & ListExtras   (today's behavior)
+ */
+type Props$2<T = unknown> = MergeTypes<[Props$1<T>, ListExtras]>;
+interface ListComponent {
+  <T extends SimpleValue>(props: SimpleProps<T> & ListExtras): VNodeChild;
+  <T extends ObjectValue>(props: ObjectProps<T> & ListExtras): VNodeChild;
+  (props: ChildrenProps & ListExtras): VNodeChild;
+  (props: LooseProps & ListExtras): VNodeChild;
+  displayName?: string;
+  pkgName?: string;
+  PYREON__COMPONENT?: string;
+}
+declare const _default: ListComponent;
 //#endregion
 //#region src/Overlay/context.d.ts
 interface OverlayContext {
@@ -254,7 +311,7 @@ interface OverlayContext {
   setBlocked: () => void;
   setUnblocked: () => void;
 }
-declare const Component$3: (props: OverlayContext & {
+declare const Component$2: (props: OverlayContext & {
   children: VNodeChild;
 }) => _$_pyreon_core0.VNode;
 //#endregion
@@ -343,24 +400,24 @@ type Props$3 = {
   triggerRefName?: string;
   contentRefName?: string;
 } & UseOverlayProps;
-declare const Component$2: PyreonComponent<Props$3>;
+declare const Component$1: PyreonComponent<Props$3>;
 //#endregion
 //#region src/Portal/component.d.ts
 interface Props$4 {
   /**
-   * Defines a HTML DOM where children to be appended.
+   * DOM element to mount the wrapper into. Defaults to `document.body`.
    */
   DOMLocation?: HTMLElement;
   /**
-   * Children to be rendered within **Portal** component.
+   * Children rendered inside the wrapper.
    */
   children: VNodeChild;
   /**
-   * Valid HTML Tag
+   * HTML tag for the per-instance wrapper element. Defaults to `'div'`.
    */
   tag?: string;
 }
-declare const Component$4: PyreonComponent<Props$4>;
+declare const Component$3: PyreonComponent<Props$4>;
 //#endregion
 //#region src/Text/component.d.ts
 type Props$5 = Partial<{
@@ -385,7 +442,7 @@ type Props$5 = Partial<{
    */
   css: ExtendCss;
 }> & PyreonHTMLAttributes;
-declare const Component$5: PyreonComponent<Props$5> & {
+declare const Component$4: PyreonComponent<Props$5> & {
   isText?: true;
 };
 //#endregion
@@ -404,7 +461,7 @@ interface Props$6 {
    */
   style?: Record<string, unknown> | undefined;
 }
-declare const Component$6: PyreonComponent<Props$6>;
+declare const Component$5: PyreonComponent<Props$6>;
 //#endregion
-export { type AlignX, type AlignY, type Content, type ContentBoolean, type Direction, Component as Element, type Props as ElementProps, type ElementType, type ExtendCss, type ExtendedProps, type InnerRef, _default as Iterator, type Props$1 as IteratorProps, Component$1 as List, type Props$2 as ListProps, type MaybeNull, type ObjectValue, Component$2 as Overlay, type Props$3 as OverlayProps, Component$3 as OverlayProvider, Component$4 as Portal, type Props$4 as PortalProps, type PropsCallback, Provider, type PyreonElement, type PyreonStatic, type Responsive, type ResponsiveBoolType, type SimpleValue, Component$5 as Text, type Props$5 as TextProps, type UseOverlayProps, Component$6 as Util, type Props$6 as UtilProps, useOverlay };
+export { type AlignX, type AlignY, type Content, type ContentBoolean, type Direction, Component as Element, type Props as ElementProps, type ElementType, type ExtendCss, type ExtendedProps, type InnerRef, Iterator, type ChildrenProps as IteratorChildrenProps, type LooseProps as IteratorLooseProps, type ObjectProps as IteratorObjectProps, type Props$1 as IteratorProps, type SimpleProps as IteratorSimpleProps, _default as List, type Props$2 as ListProps, type MaybeNull, type ObjectValue, Component$1 as Overlay, type Props$3 as OverlayProps, Component$2 as OverlayProvider, Component$3 as Portal, type Props$4 as PortalProps, type PropsCallback, Provider, type PyreonElement, type PyreonStatic, type Responsive, type ResponsiveBoolType, type SimpleValue, Component$4 as Text, type Props$5 as TextProps, type UseOverlayProps, Component$5 as Util, type Props$6 as UtilProps, useOverlay };
 //# sourceMappingURL=index2.d.ts.map

package/lib/index.js

@@ -1,5 +1,5 @@
 import { Provider, alignContent, extendCss, makeItResponsive, value } from "@pyreon/unistyle";
-import { Fragment, Portal, createContext, nativeCompat, onMount, provide, splitProps, useContext } from "@pyreon/core";
+import { Fragment, Portal, createContext, h, nativeCompat, onMount, onUnmount, provide, splitProps, useContext } from "@pyreon/core";
 import { config, isEmpty, omit, pick, render, throttle } from "@pyreon/ui-core";
 import { Fragment as Fragment$1, jsx, jsxs } from "@pyreon/core/jsx-runtime";
 import { signal } from "@pyreon/reactivity";
@@ -264,28 +264,25 @@ const childFixCSS = `
 const parentFixCSS = `
   flex-direction: column;
 `;
-const fullHeightCSS = `
-  height: 100%;
-`;
-const blockCSS = `
-  align-self: stretch;
-  flex: 1;
-  min-width: 0;
-`;
-const childFixPosition = (isBlock) => `display: ${isBlock ? "flex" : "inline-flex"};`;
 const styles$1 = ({ theme: t, css: cssFn }) => cssFn`
-  ${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)};
@@ -334,6 +331,34 @@ const isWebFixNeeded = (tag) => {
 * support `display: flex` consistently across browsers.
 */
 const DEV_PROPS = IS_DEVELOPMENT ? { "data-pyr-element": "Element" } : {};
+/**
+* Build a props object for `h(Styled, ...)` by copying own property
+* DESCRIPTORS from `rest`, then layering the additional fields. Compiler-
+* emitted reactive props (`_rp(() => signal())` converted to getters by
+* `makeReactiveProps`) survive end-to-end with their getter intact.
+*
+* Why we bypass JSX spread here: the standard JSX automatic-runtime
+* compilation lowers `<Styled {...rest} foo={x}>` to roughly
+* `jsx(Styled, { ...rest, foo: x })`. That `{...rest, foo: x}` object
+* literal is evaluated at JS level — it fires every getter on `rest` and
+* stores the resolved value before `jsx()` ever sees the object. No
+* amount of in-runtime descriptor preservation can recover the getters
+* once they've been collapsed by the surface-level spread. The fix is
+* structural: don't use JSX spread for reactive-prop forwarding. Build
+* the props object with descriptor preservation and pass it to `h()`
+* directly — `h()` stores props as-is on the vnode, no copy, getters
+* survive into mount.
+*/
+const buildStyledProps = (rest, refValue, asTag, extras) => {
+	const result = {};
+	const descriptors = Object.getOwnPropertyDescriptors(rest);
+	for (const key in descriptors) Object.defineProperty(result, key, descriptors[key]);
+	for (const key in DEV_PROPS) result[key] = DEV_PROPS[key];
+	result.ref = refValue;
+	result.as = asTag;
+	for (const key in extras) result[key] = extras[key];
+	return result;
+};
 const OWN_KEYS = [
 	"children",
 	"tag",
@@ -349,14 +374,9 @@ const OWN_KEYS = [
 ];
 const Component$8 = (props) => {
 	const [own, rest] = splitProps(props, OWN_KEYS);
-	const commonProps = {
-		...rest,
-		...DEV_PROPS,
-		ref: own.ref,
-		as: own.tag
-	};
 	const needsFix = !own.dangerouslySetInnerHTML && isWebFixNeeded(own.tag);
 	const isVoidTag = !own.dangerouslySetInnerHTML && getShouldBeEmpty(own.tag);
+	const innerHTML = own.dangerouslySetInnerHTML;
 	if (!needsFix) {
 		const bundle = internElementBundle({
 			block: own.block,
@@ -366,15 +386,15 @@ const Component$8 = (props) => {
 			equalCols: own.equalCols,
 			extraStyles: own.extendCss
 		});
-		if (isVoidTag) return /* @__PURE__ */ jsx(styled_default$1, {
-			...commonProps,
-			$element: bundle
-		});
-		return /* @__PURE__ */ jsx(styled_default$1, {
-			...commonProps,
+		if (isVoidTag) return h(styled_default$1, buildStyledProps(rest, own.ref, own.tag, { $element: bundle }));
+		if (innerHTML) return h(styled_default$1, buildStyledProps(rest, own.ref, own.tag, {
+			$element: bundle,
+			dangerouslySetInnerHTML: innerHTML
+		}));
+		return h(styled_default$1, buildStyledProps(rest, own.ref, own.tag, {
 			$element: bundle,
 			children: own.children
-		});
+		}));
 	}
 	const asTag = own.isInline ? "span" : "div";
 	const parentBundle = internElementBundle({
@@ -389,16 +409,24 @@ const Component$8 = (props) => {
 		alignY: own.alignY,
 		equalCols: own.equalCols
 	});
-	return /* @__PURE__ */ jsx(styled_default$1, {
-		...commonProps,
+	if (innerHTML) return h(styled_default$1, buildStyledProps(rest, own.ref, own.tag, {
+		$element: parentBundle,
+		children: h(styled_default$1, {
+			as: asTag,
+			$childFix: true,
+			$element: childBundle,
+			dangerouslySetInnerHTML: innerHTML
+		})
+	}));
+	return h(styled_default$1, buildStyledProps(rest, own.ref, own.tag, {
 		$element: parentBundle,
-		children: /* @__PURE__ */ jsx(styled_default$1, {
+		children: h(styled_default$1, {
 			as: asTag,
 			$childFix: true,
 			$element: childBundle,
 			children: own.children
 		})
-	});
+	}));
 };
 
 //#endregion
@@ -499,7 +527,13 @@ const Component = (props) => {
 		else if (externalRef != null) externalRef.current = node;
 	};
 	if (own.equalBeforeAfter && own.beforeContent && own.afterContent) onMount(() => {
-		if (equalizeRef) equalize(equalizeRef, own.direction);
+		const node = equalizeRef;
+		if (!node) return void 0;
+		equalize(node, own.direction);
+		if (typeof ResizeObserver === "undefined") return void 0;
+		const observer = new ResizeObserver(() => equalize(node, own.direction));
+		observer.observe(node);
+		return () => observer.disconnect();
 	});
 	const WRAPPER_PROPS = {
 		ref: mergedRef,
@@ -730,34 +764,28 @@ const Component$7 = (props) => {
 	};
 	return renderItems();
 };
-var component_default = Object.assign(Component$7, {
+const Iterator = Object.assign(Component$7, {
 	isIterator: true,
 	RESERVED_PROPS
 });
 
 //#endregion
 //#region src/helpers/Iterator/index.ts
-var Iterator_default = component_default;
+var Iterator_default = Iterator;
 
 //#endregion
 //#region src/List/component.tsx
-/**
-* List component that combines Iterator (data-driven rendering) with an
-* optional Element root wrapper. When `rootElement` is false (default),
-* it renders a bare Iterator as a fragment. When true, the Iterator output
-* 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$1 = ((allProps) => {
+const LooseIterator = Iterator_default;
+const Component$1 = (allProps) => {
 	const [own, props] = splitProps(allProps, ["rootElement", "ref"]);
-	const renderedList = /* @__PURE__ */ jsx(Iterator_default, { ...pick(props, Iterator_default.RESERVED_PROPS) });
+	const renderedList = /* @__PURE__ */ jsx(LooseIterator, { ...pick(props, Iterator_default.RESERVED_PROPS) });
 	if (!own.rootElement) return renderedList;
 	return /* @__PURE__ */ jsx(Component, {
-		...own.ref ? { ref: own.ref } : {},
+		ref: own.ref,
 		...omit(props, Iterator_default.RESERVED_PROPS),
 		children: renderedList
 	});
-});
+};
 const name$4 = `${PKG_NAME}/List`;
 Component$1.displayName = name$4;
 Component$1.pkgName = PKG_NAME;
@@ -1237,10 +1265,16 @@ nativeCompat(Component$2);
 //#endregion
 //#region src/Portal/component.tsx
 const Component$4 = (props) => {
-	const target = props.DOMLocation ?? (typeof document !== "undefined" ? document.body : void 0);
-	if (!target) return null;
+	if (typeof document === "undefined") return null;
+	const tag = props.tag ?? "div";
+	const target = props.DOMLocation ?? document.body;
+	const wrapper = document.createElement(tag);
+	target.appendChild(wrapper);
+	onUnmount(() => {
+		wrapper.remove();
+	});
 	return /* @__PURE__ */ jsx(Portal, {
-		target,
+		target: wrapper,
 		children: props.children
 	});
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/elements",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "description": "Foundational UI components for Pyreon",
   "license": "MIT",
   "repository": {
@@ -42,21 +42,21 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@pyreon/core": "^0.15.0",
-    "@pyreon/reactivity": "^0.15.0",
-    "@pyreon/runtime-dom": "^0.15.0",
-    "@pyreon/test-utils": "^0.13.2",
-    "@pyreon/typescript": "^0.15.0",
+    "@pyreon/core": "^0.18.0",
+    "@pyreon/reactivity": "^0.18.0",
+    "@pyreon/runtime-dom": "^0.18.0",
+    "@pyreon/test-utils": "^0.13.5",
+    "@pyreon/typescript": "^0.18.0",
     "@vitest/browser-playwright": "^4.1.4",
     "@vitus-labs/tools-rolldown": "^2.3.0"
   },
-  "peerDependencies": {
-    "@pyreon/core": "^0.15.0",
-    "@pyreon/reactivity": "^0.15.0",
-    "@pyreon/ui-core": "^0.15.0",
-    "@pyreon/unistyle": "^0.15.0"
-  },
   "engines": {
     "node": ">= 22"
+  },
+  "dependencies": {
+    "@pyreon/core": "^0.18.0",
+    "@pyreon/reactivity": "^0.18.0",
+    "@pyreon/ui-core": "^0.18.0",
+    "@pyreon/unistyle": "^0.18.0"
   }
 }

package/src/Element/component.tsx

@@ -137,9 +137,20 @@ const Component: PyreonElement = (props) => {
   }
 
   if (own.equalBeforeAfter && own.beforeContent && own.afterContent) {
+    // Run once on mount AND continue equalizing as the element resizes —
+    // catches async slot content (font swaps, lazy text, viewport resize)
+    // that a one-shot measurement would miss. Mirrors vitus-labs's Element
+    // useLayoutEffect + ResizeObserver pattern.
     onMount(() => {
-      if (equalizeRef) equalize(equalizeRef, own.direction)
-      return undefined
+      const node = equalizeRef
+      if (!node) return undefined
+
+      equalize(node, own.direction)
+
+      if (typeof ResizeObserver === 'undefined') return undefined
+      const observer = new ResizeObserver(() => equalize(node, own.direction))
+      observer.observe(node)
+      return () => observer.disconnect()
     })
   }
 

package/src/List/component.tsx

@@ -5,16 +5,25 @@
  * 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.
  */
+import type { VNodeChild } from '@pyreon/core'
 import { splitProps } from '@pyreon/core'
 import { omit, pick } from '@pyreon/ui-core'
 import { PKG_NAME } from '../constants'
-import type { ElementProps, PyreonElement } from '../Element'
+import type { ElementProps } from '../Element'
 import { Element } from '../Element'
-import type { Props as IteratorProps } from '../helpers/Iterator'
+import type {
+  ChildrenProps as IteratorChildrenProps,
+  LooseProps as IteratorLooseProps,
+  ObjectProps as IteratorObjectProps,
+  Props as IteratorProps,
+  SimpleProps as IteratorSimpleProps,
+  ObjectValue,
+  SimpleValue,
+} from '../helpers/Iterator'
 import Iterator from '../helpers/Iterator'
 import type { MergeTypes } from '../types'
 
-type ListProps = {
+type ListOnly = {
   /**
    * A boolean value. When set to `false`, component returns fragment.
    * When set to `true`, component returns as the **root** element `Element`
@@ -24,32 +33,73 @@ type ListProps = {
   /**
    * Label prop from `Element` component is being ignored.
    */
-  label: never
+  label?: never
   /**
    * Content prop from `Element` component is being ignored.
    */
-  content: never
+  content?: never
 }
 
-export type Props = MergeTypes<[IteratorProps, ListProps]> & Partial<Omit<ElementProps, 'children' | 'content' | 'label'>>
+/**
+ * Props that List accepts on top of the Iterator branch — the Element prop
+ * surface (so `tag`, `direction`, `alignX`, etc. forward when
+ * `rootElement` is true) plus the List-only toggle.
+ */
+type ListExtras = Partial<Omit<ElementProps, 'children' | 'content' | 'label'>> & ListOnly
+
+/**
+ * Public Props — generic over the data element type so callers get the same
+ * inference Iterator does, plus the List-specific `rootElement` toggle and
+ * Element prop forwarding.
+ *
+ *   Props<string>          → SimpleProps & ListExtras  (valueName REQUIRED)
+ *   Props<{ id; name }>    → ObjectProps & ListExtras  (valueName FORBIDDEN)
+ *   Props<unknown> / Props → LooseProps & ListExtras   (today's behavior)
+ */
+export type Props<T = unknown> = MergeTypes<[IteratorProps<T>, ListExtras]>
 
-const Component: PyreonElement<Props> = ((allProps: Partial<Props & ElementProps>) => {
-  const [own, props] = splitProps(allProps, ['rootElement', 'ref'])
-  const renderedList = <Iterator {...pick(props, Iterator.RESERVED_PROPS)} />
+// Internal spread — runtime is correct, but the picked subset can't satisfy
+// any specific Iterator overload statically (which is good — the public
+// overloads enforce constraints). Cast Iterator to a loose callable for
+// the internal forwarding only; public consumers still see the strict
+// overloaded interface.
+const LooseIterator = Iterator as unknown as (props: IteratorLooseProps) => VNodeChild
+
+const Component = (allProps: IteratorLooseProps & ListExtras) => {
+  const [own, props] = splitProps(allProps as Record<string, unknown>, ['rootElement', 'ref'])
+  const renderedList = <LooseIterator {...pick(props, Iterator.RESERVED_PROPS)} />
 
   if (!own.rootElement) return renderedList
 
   return (
-    <Element {...(own.ref ? { ref: own.ref } : {})} {...omit(props, Iterator.RESERVED_PROPS)}>
+    <Element ref={own.ref as ElementProps['ref']} {...omit(props, Iterator.RESERVED_PROPS)}>
       {renderedList}
     </Element>
   )
-}) as PyreonElement<Props>
+}
 
 const name = `${PKG_NAME}/List` as const
 
-Component.displayName = name
-Component.pkgName = PKG_NAME
-Component.PYREON__COMPONENT = name
+;(Component as { displayName?: string }).displayName = name
+;(Component as { pkgName?: string }).pkgName = PKG_NAME
+;(Component as { PYREON__COMPONENT?: string }).PYREON__COMPONENT = name
+
+// ---------------------------------------------------------------------------
+// Public callable type — same overload pattern as Iterator so JSX-site
+// inference flows through without callers having to spell out `<T>`.
+// ---------------------------------------------------------------------------
+export interface ListComponent {
+  // T inferred from `data`. Order: SimpleProps, ObjectProps, ChildrenProps,
+  // then a LooseProps fallback for forwarding patterns where derived
+  // `$$types['data']` is a wide union that doesn't bind to any narrow
+  // overload. See Iterator's IteratorComponent for the full rationale.
+  <T extends SimpleValue>(props: IteratorSimpleProps<T> & ListExtras): VNodeChild
+  <T extends ObjectValue>(props: IteratorObjectProps<T> & ListExtras): VNodeChild
+  (props: IteratorChildrenProps & ListExtras): VNodeChild
+  (props: IteratorLooseProps & ListExtras): VNodeChild
+  displayName?: string
+  pkgName?: string
+  PYREON__COMPONENT?: string
+}
 
-export default Component
+export default Component as unknown as ListComponent