@pyreon/elements 0.22.0 → 0.23.0

package/README.md

@@ -1,196 +1,225 @@
 # @pyreon/elements
 
-Foundational UI components for Pyreon with responsive props.
+Five foundational layout primitives — Element, Text, List, Overlay, Portal — plus an Iterator helper.
 
-Five composable components for building buttons, cards, lists, dropdowns, tooltips, and modals. Every layout prop is responsive — pass a single value, a mobile-first array, or a breakpoint object.
+`@pyreon/elements` is the layer between `@pyreon/styler`/`@pyreon/unistyle` and the high-level UI components. Every layout prop is responsive (single value, mobile-first array, or breakpoint object). `Element` is a three-section flex container (`beforeContent` / `content` / `afterContent`) with an internal fast path that collapses one wrapper layer when only `content` is present — measured 31-45% faster across mount benchmarks. `Overlay` ships a full `useOverlay` hook handling open/close, viewport flipping, ESC, click-outside, scroll tracking, hover delay, and modal overflow-locking — no positioning logic to reinvent. `Iterator` and `List` cover data-driven children with positional metadata; `Portal` renders into an isolated wrapper inside a configurable DOM location.
 
-## Features
-
-- **Element** — three-section flex layout (beforeContent / content / afterContent)
-- **Text** — semantic text rendering with auto paragraph wrapping
-- **List** — data-driven rendering with positional metadata (first, last, odd, even)
-- **Overlay** — headless trigger+content pattern
-- **Portal** — stub (runtime-dom provides actual portal)
-- **Responsive everything** — single value, array, or breakpoint object on every layout prop
-- **Equal before/after** — `equalBeforeAfter` prop on Element to equalize slot dimensions
-
-## Installation
+## Install
 
 ```bash
-bun add @pyreon/elements
+bun add @pyreon/elements @pyreon/core @pyreon/reactivity @pyreon/ui-core @pyreon/unistyle
 ```
 
-## Components
-
-### Element
-
-The core layout primitive. Renders a three-section flex container with optional beforeContent and afterContent slots around the main content.
-
-```ts
-import { Element } from '@pyreon/elements'
-
-Element({
-  tag: 'button',
-  beforeContent: Icon({ name: 'star' }),
-  afterContent: Icon({ name: 'chevron-right' }),
-  direction: 'inline',
-  alignX: 'center',
-  alignY: 'center',
-  gap: 8,
-  children: 'Click me',
-})
+## Quick start
+
+```tsx
+import { Element, Text, List, Overlay, Portal, Provider } from '@pyreon/elements'
+
+<Provider>
+  <Element
+    tag="button"
+    direction="inline"
+    alignX="center"
+    alignY="center"
+    gap={8}
+    beforeContent={<Icon name="star" />}
+    afterContent={<Icon name="chevron-right" />}
+  >
+    Click me
+  </Element>
+</Provider>
 ```
 
-When only content is present (no beforeContent/afterContent), Element optimizes by skipping the inner wrapper layer.
+`Provider` is re-exported from `@pyreon/unistyle` — set it once near the app root to scope breakpoints, root-size, and theme defaults.
+
+## `Element` — three-section flex layout
+
+Most-used primitive. Renders an outer container with optional `beforeContent` / `afterContent` slots flanking the main `content` (children).
+
+```tsx
+<Element
+  tag="button"
+  direction="inline"        // 'inline' | 'rows' | 'reverseInline' | 'reverseRows'
+  alignX="center"            // 'left' | 'center' | 'right' | 'spaceBetween' | ...
+  alignY="center"            // 'top' | 'center' | 'bottom' | 'stretch' | ...
+  gap={8}
+  block                     // flex vs inline-flex
+  equalCols                  // equalize before/after widths via ResizeObserver
+  equalBeforeAfter
+  beforeContent={<Icon />}
+  afterContent={<Icon />}
+>
+  Action
+</Element>
+```
 
-**Content props** (rendered in priority order: children > content > label):
+**Content slots** (priority: `children` > `content` > `label`):
 
-| Prop          | Type    | Description                           |
-| ------------- | ------- | ------------------------------------- |
-| children      | `VNode` | Standard children                     |
-| content       | `VNode` | Alternative to children               |
-| label         | `VNode` | Alternative to children/content       |
-| beforeContent | `VNode` | Content rendered before the main slot |
-| afterContent  | `VNode` | Content rendered after the main slot  |
+| Prop | Type | Notes |
+|---|---|---|
+| `children` | `VNodeChild` | Standard JSX children |
+| `content` | `VNodeChild` | Alternative slot when `children` is awkward |
+| `label` | `VNodeChild` | Third fallback; useful in data-driven `List` |
+| `beforeContent` | `VNodeChild` | Rendered before the main slot |
+| `afterContent` | `VNodeChild` | Rendered after the main slot |
 
 **Layout props** (all responsive):
 
-| Prop      | Type        | Default    | Description                                                    |
-| --------- | ----------- | ---------- | -------------------------------------------------------------- |
-| tag       | `HTMLTags`  | `'div'`    | HTML element tag                                               |
-| block     | `boolean`   | —          | `flex` vs `inline-flex`                                        |
-| direction | `Direction` | `'inline'` | `'inline'` \| `'rows'` \| `'reverseInline'` \| `'reverseRows'` |
-| alignX    | `AlignX`    | `'left'`   | Horizontal alignment                                           |
-| alignY    | `AlignY`    | `'center'` | Vertical alignment                                             |
-| gap       | `number`    | —          | Gap between content sections                                   |
-| equalCols | `boolean`   | —          | Equal width/height for before/after                            |
+| Prop | Default | Description |
+|---|---|---|
+| `tag` | `'div'` | Outer HTML tag |
+| `direction` | `'inline'` | `'inline'` (row) / `'rows'` (column) / `'reverseInline'` / `'reverseRows'` |
+| `alignX` | `'left'` | Horizontal alignment along the flex direction |
+| `alignY` | `'center'` | Cross-axis alignment |
+| `gap` | — | Gap between sections |
+| `block` | — | `flex` vs `inline-flex` |
+| `equalCols` | — | Equal width for before/after columns (snapshot at mount) |
+| `equalBeforeAfter` | — | Equalize before/after via live `ResizeObserver` (resilient to async font/content changes) |
+| `dangerouslySetInnerHTML` | — | Forwards to `runtime-dom` / `runtime-server` |
 
-Each section (content, beforeContent, afterContent) has its own direction, alignX, and alignY props prefixed with the section name:
+Per-section overrides: `contentDirection`, `contentAlignX`, `beforeContentAlignY`, `afterContentDirection`, etc. — every section accepts the same axis props prefixed with the section name.
 
-```ts
-Element({
-  contentDirection: 'rows',
-  contentAlignX: 'center',
-  beforeContentAlignY: 'top',
-  afterContentDirection: 'inline',
-})
-```
-
-### Text
-
-Semantic text component with optional paragraph auto-wrapping.
+**Simple-path fast path**: when there's no `beforeContent` / `afterContent` and the tag doesn't need the button/fieldset/legend two-layer flex fix, Element inlines the wrapper helper into ONE styled invocation. Saves one component invocation + one `splitProps` + one `mountChild` per Element. Real-Chromium benchmark drops a 500-child mount from 2.9ms to 1.6ms (-45%).
 
-```ts
-import { Text } from '@pyreon/elements'
+## `Text` — semantic typography
 
-Text({ tag: 'h1', children: 'Heading' })
-Text({ paragraph: true, children: 'This renders as a p tag.' })
-Text({ tag: 'strong', label: 'Bold text' })
+```tsx
+<Text tag="h1">Heading</Text>
+<Text paragraph>This renders as a <p>.</Text>
+<Text tag="strong">Bold</Text>
 ```
 
-| Prop             | Type           | Description                                              |
-| ---------------- | -------------- | -------------------------------------------------------- |
-| tag              | `HTMLTextTags` | `'h1'`–`'h6'`, `'p'`, `'span'`, `'strong'`, `'em'`, etc. |
-| paragraph        | `boolean`      | Shorthand for `tag="p"`                                  |
-| children / label | `VNode`        | Text content                                             |
-| css              | `ExtendCss`    | Extend styling                                           |
-
-### List
+| Prop | Type | Notes |
+|---|---|---|
+| `tag` | `'h1'`-`'h6'` / `'p'` / `'span'` / `'strong'` / `'em'` / `'small'` / … | Inline-by-default |
+| `paragraph` | `boolean` | Shorthand for `tag="p"` |
+| `children` / `label` | `VNodeChild` | Text content |
+| `css` | `ExtendCss` | Extend styling |
 
-Data-driven list renderer with positional metadata.
-
-```ts
-import { List, Element } from '@pyreon/elements'
+## `List` — data-driven children with positional metadata
 
-// Simple string data
-List({
-  component: Element,
-  data: ['Apple', 'Banana', 'Cherry'],
-  valueName: 'label',
-})
-
-// Object data with positional metadata
-List({
-  component: ListItem,
-  data: [
+```tsx
+<List
+  component={ListItem}
+  data={[
     { id: 1, name: 'Alice' },
     { id: 2, name: 'Bob' },
-  ],
-  itemKey: 'id',
-  itemProps: (item, { first, last, odd, even, index }) => ({
+  ]}
+  itemKey="id"
+  itemProps={(item, { first, last, odd, even, index }) => ({
     highlighted: first,
     separator: !last,
-  }),
-})
-
-// With root Element wrapper
-List({
-  rootElement: true,
-  direction: 'rows',
-  gap: 8,
-  component: Card,
-  data: items,
-})
+  })}
+/>
+
+// With root Element wrapper — gap/direction/align take effect
+<List
+  rootElement
+  direction="rows"
+  gap={8}
+  component={Card}
+  data={items}
+/>
 ```
 
-| Prop          | Type                 | Description                                            |
-| ------------- | -------------------- | ------------------------------------------------------ |
-| data          | `Array`              | Array of strings, numbers, or objects                  |
-| component     | `ComponentFn`        | Component to render for each item                      |
-| valueName     | `string`             | Prop name for scalar values (default: `'children'`)    |
-| itemKey       | `string \| function` | Key extraction for list items                          |
-| itemProps     | `object \| function` | Extra props injected into each item                    |
-| wrapComponent | `ComponentFn`        | Wrapper around each item                               |
-| rootElement   | `boolean`            | Wrap list in an Element (enables direction, gap, etc.) |
+| Prop | Type | Notes |
+|---|---|---|
+| `data` | `Array<string \| number \| object>` | Source data |
+| `component` | `ComponentFn` | Renders per item |
+| `valueName` | `string` | Prop name for scalar values (default `'children'`) |
+| `itemKey` | `string \| (item) => Key` | Key extractor |
+| `itemProps` | `object \| (item, meta) => object` | Extra props injected per item |
+| `wrapComponent` | `ComponentFn` | Wrapper around each item |
+| `rootElement` | `boolean` | Wrap in an `Element` (enables `direction` / `gap` / `align`) |
+
+Positional metadata (`{ index, first, last, odd, even, position }`) is passed to both `itemKey` and `itemProps` callbacks.
+
+## `Iterator` — lower-level data iterator
+
+Same data/component model as `List`, four typed overloads (simple values, object values, children-only, loose forwarding) so spread-pattern wrapping (`<Iterator {...wrapperProps} />`) typechecks. Use when you don't need List's auto-wrap layout — e.g. emitting a flat array of `<option>` elements inside a `<select>`.
+
+## `Overlay` + `useOverlay` — dropdowns / tooltips / popovers / modals
+
+```tsx
+<Overlay
+  openOn="click"
+  closeOn="clickOutsideContent"
+  type="dropdown"
+  align="bottom"
+  alignX="left"
+  offsetX={0}
+  offsetY={4}
+  closeOnEsc
+  hoverDelay={150}
+  trigger={<Button>Open menu</Button>}
+>
+  <DropdownMenu />
+</Overlay>
+```
 
-**Positional metadata** passed to `itemProps` callback:
+For headless control, use the hook directly:
 
-`index`, `first`, `last`, `odd`, `even`, `position` (1-based)
+```tsx
+const overlay = useOverlay({
+  openOn: 'click',
+  closeOn: 'clickOnTrigger',
+  type: 'tooltip',
+  align: 'top',
+  onOpen: () => track('tooltip-open'),
+})
+// overlay.isOpen / overlay.toggle / overlay.open / overlay.close / overlay.position()
+```
 
-### Overlay
+Built-in behaviour:
+- **Viewport-edge flipping** — automatically flips align when the content would overflow.
+- **Throttled positioning** — scroll + resize listeners throttled (default delay 60ms).
+- **ESC + click-outside** — opt-in via `closeOnEsc` / `closeOn: 'clickOutsideContent'`.
+- **Hover delay** — `hoverDelay` debounces both open and close for `openOn: 'hover'`.
+- **Modal overflow lock** — `type: 'modal'` ref-counts `document.body` overflow so nested modals don't double-lock.
 
-Headless trigger+content pattern for dropdowns, tooltips, and modals.
+`OverlayProvider` + `useOverlayContext` coordinate nested overlays (a parent dropdown can block its children's click-outside).
 
-```ts
-import { Overlay } from '@pyreon/elements'
+## `Portal` — render into a different DOM location
 
-Overlay({
-  openOn: 'click',
-  closeOn: 'clickOutsideContent',
-  align: 'bottom',
-  alignX: 'left',
-  trigger: Button({ label: 'Open menu' }),
-  children: DropdownMenu({}),
-})
+```tsx
+<Portal target={document.body} tag="div" data-modal-id="settings">
+  <Modal />
+</Portal>
 ```
 
-### Portal
+Creates a per-instance wrapper element (default `<div>`, configurable via `tag`) INSIDE `target` (default `document.body`). Multiple portals share `target` without intermingling children — each gets its own wrapper.
 
-Stub component — the actual portal implementation is provided by `@pyreon/core`'s runtime-dom.
+| Prop | Default | Notes |
+|---|---|---|
+| `target` | `document.body` | Destination element (`HTMLElement \| (() => HTMLElement) \| null`) |
+| `tag` | `'div'` | Wrapper HTML tag |
+| Any data-/aria- attrs | — | Forwarded to the wrapper |
 
-## Responsive Values
+## `Util` — utility wrapper for non-layout primitives
 
-Every layout prop (direction, alignX, alignY, gap, block, equalCols) supports three formats:
+Reserved escape-hatch for components that need styler integration without Element's layout props (e.g. SVG roots). Same theme/style pipeline, no axis/gap props.
+
+## Responsive values
 
 ```ts
-// Single value — all breakpoints
-Element({ direction: 'inline' })
+direction="inline"                                  // single value
+direction={['rows', 'inline']}                       // mobile-first array
+direction={{ xs: 'rows', md: 'inline', lg: 'inline' }} // breakpoint object
+```
 
-// Array — mobile-first, maps to breakpoints by position
-Element({ direction: ['rows', 'inline'] })
+Applies to `tag`, `direction`, `alignX`, `alignY`, `gap`, `block`, `equalCols`, and every per-section variant.
 
-// Object — explicit breakpoints
-Element({ direction: { xs: 'rows', md: 'inline', lg: 'inline' } })
-```
+## Gotchas
+
+- **Wrapper drops the children slot for void tags** (`<hr>`, `<input>`, `<img>`, `<br>`, etc.) so `{undefined}` JSX slots don't trip runtime-dom's "void element cannot have children" warning. If you author a custom wrapper that forwards `children`, branch on `getShouldBeEmpty(tag)` first.
+- **`<Portal>` creates a per-instance wrapper INSIDE `target`** — `document.body.firstChild` is not your modal; query via `document.body.querySelector('[data-modal-id]').parentElement`.
+- **`equalBeforeAfter` uses `ResizeObserver`** and falls back to a one-shot measurement when the API is unavailable (SSR, older runtimes). For async content (font swaps, lazy images) you want `equalBeforeAfter`, not `equalCols`.
+- **Element's `direction` accepts `'inline' | 'rows' | 'reverseInline' | 'reverseRows'`** — `'row'` is invalid (caught by TS).
+- **`Iterator` ships 4 overloads with a `LooseProps` fallback** so `<Iterator {...wrapperProps} />` forwarding patterns typecheck. The trade-off: mixed-shape arrays (`[1, {id:1}, null]`) bind to the fallback rather than failing at the type level. Runtime still picks the right mode based on which props are populated.
 
-## Peer Dependencies
+## Documentation
 
-| Package            | Version  |
-| ------------------ | -------- |
-| @pyreon/core       | >= 0.0.1 |
-| @pyreon/reactivity | >= 0.0.1 |
-| @pyreon/ui-core    | >= 0.0.1 |
-| @pyreon/unistyle   | >= 0.0.1 |
+Full docs: [docs.pyreon.dev/docs/elements](https://docs.pyreon.dev/docs/elements) (or `docs/docs/elements.md` in this repo).
 
 ## License
 

package/lib/index.js

@@ -664,7 +664,8 @@ const attachItemProps = ({ i, length }) => {
 	};
 };
 const Component$7 = (props) => {
-	const { itemKey, valueName, children, component, data, wrapComponent: Wrapper, wrapProps, itemProps } = props;
+	const { itemKey, valueName, children: rawChildren, component, data, wrapComponent: Wrapper, wrapProps, itemProps } = props;
+	const children = typeof rawChildren === "function" ? rawChildren() : rawChildren;
 	const injectItemProps = typeof itemProps === "function" ? itemProps : () => itemProps;
 	const injectWrapItemProps = typeof wrapProps === "function" ? wrapProps : () => wrapProps;
 	const getKey = (item, index) => {

package/package.json

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

package/src/__tests__/iterator-function-children.test.tsx

@@ -0,0 +1,120 @@
+/** @jsxImportSource @pyreon/core */
+/**
+ * Regression: `<Iterator>{items}</Iterator>` where the Pyreon compiler
+ * wrapped `items` in `() => items` (the prop-inlining pass) used to
+ * silently misrender — the `Array.isArray(children)` and Fragment-type
+ * checks both fell through (a function is neither), and the fallthrough
+ * `renderChild(function)` called `render(function, props)` which
+ * interpreted the function as a COMPONENT FUNCTION. That accidentally
+ * worked at the DOM level (the wrapped function's call returned the array
+ * and mountChild rendered it), but the per-item metadata (`first`/`last`/
+ * `position`/`index`/`odd`/`even`) was LOST because the iteration loop
+ * was never reached.
+ *
+ * Fix: unwrap eagerly at component-body entry — `typeof children ===
+ * 'function' ? children() : children`. Mirrors kinetic's `resolveChildren`
+ * pattern (PR #731 + top-level Transition/Stagger parallel fix).
+ *
+ * Bisect-verified: reverting the `typeof rawChildren === 'function'`
+ * unwrap fails this spec — per-item `first`/`last` props arrive as
+ * `undefined` because the iteration loop was skipped.
+ */
+import type { VNode, VNodeChild } from '@pyreon/core'
+import { h } from '@pyreon/core'
+import { mount } from '@pyreon/runtime-dom'
+import { afterEach, describe, expect, it } from 'vitest'
+import Iterator from '../helpers/Iterator/component'
+
+let containers: HTMLElement[] = []
+afterEach(() => {
+  for (const c of containers) c.remove()
+  containers = []
+})
+
+describe('<Iterator> — function-wrapped children', () => {
+  it('iterates function-wrapped children with per-item metadata via wrapProps', () => {
+    let firstFlagSet = false
+    let lastFlagSet = false
+    const positions: number[] = []
+
+    // ItemWrapper just renders <li>. The per-item metadata is captured
+    // via the `wrapProps` injector — Iterator calls it with the
+    // attached metadata `{first, last, position, index, odd, even}`.
+    // Counting positions/flags proves the iteration loop fired.
+    const ItemWrapper = (props: {
+      children?: VNodeChild
+      'data-first'?: string
+      'data-last'?: string
+      'data-position'?: number
+    }) => h('li', props as never, props.children as never)
+
+    const items: VNode[] = [
+      h('span', { 'data-id': 'item-a' }, 'A'),
+      h('span', { 'data-id': 'item-b' }, 'B'),
+      h('span', { 'data-id': 'item-c' }, 'C'),
+    ]
+
+    // Compiler-emitted shape: children is `() => items` (the prop-inlining
+    // wrap for stable references). Pre-fix: the function was treated as a
+    // component → iteration loop skipped → per-item metadata not attached.
+    const tree = h(Iterator, {
+      wrapComponent: ItemWrapper,
+      // wrapProps receives `(itemProps, extendedProps)` where
+      // extendedProps carries the per-item metadata. Captured here to
+      // prove the iteration loop fired (which the fallthrough wouldn't).
+      wrapProps: (_: object, ext: { first: boolean; last: boolean; position: number }) => {
+        positions.push(ext.position)
+        if (ext.first) firstFlagSet = true
+        if (ext.last) lastFlagSet = true
+        return {}
+      },
+      children: (() => items) as unknown as VNodeChild,
+    })
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+
+    const dispose = mount(tree as VNode, container)
+
+    expect(
+      positions,
+      `wrapProps was called for positions=${JSON.stringify(positions)}; ` +
+        `expected [1,2,3] (per-item iteration loop must fire). ` +
+        `html=${container.innerHTML.slice(0, 400)}`,
+    ).toEqual([1, 2, 3])
+    expect(firstFlagSet, 'first=true metadata must reach wrapProps').toBe(true)
+    expect(lastFlagSet, 'last=true metadata must reach wrapProps').toBe(true)
+
+    expect(container.querySelector('[data-id="item-a"]')?.tagName).toBe('SPAN')
+    expect(container.querySelector('[data-id="item-b"]')?.tagName).toBe('SPAN')
+    expect(container.querySelector('[data-id="item-c"]')?.tagName).toBe('SPAN')
+
+    dispose()
+  })
+
+  it('static-array children control — was always working', () => {
+    let renderedItems = 0
+    const ItemWrapper = (props: { children?: VNodeChild; position?: number }) => {
+      renderedItems++
+      return h('li', { 'data-position': props.position }, props.children as never)
+    }
+
+    const tree = h(
+      Iterator,
+      { wrapComponent: ItemWrapper },
+      h('span', { 'data-id': 'static-a' }, 'A'),
+      h('span', { 'data-id': 'static-b' }, 'B'),
+    )
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+    const dispose = mount(tree as VNode, container)
+
+    expect(renderedItems).toBe(2)
+    expect(container.querySelector('[data-id="static-a"]')?.tagName).toBe('SPAN')
+
+    dispose()
+  })
+})

package/src/helpers/Iterator/component.tsx

@@ -82,7 +82,7 @@ const Component = (props: LooseProps) => {
   const {
     itemKey,
     valueName,
-    children,
+    children: rawChildren,
     component,
     data,
     wrapComponent: Wrapper,
@@ -90,6 +90,19 @@ const Component = (props: LooseProps) => {
     itemProps,
   } = props
 
+  // Unwrap the Pyreon compiler's `() => x` accessor wrap. When the parent
+  // emits `<Iterator>{items}</Iterator>` and the compiler-emitted form is
+  // `Iterator({ children: () => items })`, the downstream `Array.isArray`
+  // check returns false, the Fragment check returns false (function is not
+  // an object), and the fallthrough `renderChild(function)` calls
+  // `render(function, props)` which interprets the function as a component
+  // function — wrong shape, lost per-item metadata. Resolving eagerly here
+  // keeps every downstream branch correct. Mirrors the kinetic Stagger /
+  // TransitionItem fix (PR #731 + parallel top-level fixes).
+  const children = typeof rawChildren === 'function'
+    ? (rawChildren as () => VNodeChild)()
+    : rawChildren
+
   const injectItemProps = typeof itemProps === 'function' ? itemProps : () => itemProps
 
   const injectWrapItemProps = typeof wrapProps === 'function' ? wrapProps : () => wrapProps