@pyreon/elements 0.12.12 → 0.12.14

package/src/Overlay/positioning.ts

@@ -0,0 +1,191 @@
+/**
+ * Pure positioning helpers for the Overlay component. Split out from
+ * `useOverlay.tsx` so the SSR-fallback branches (`typeof window === 'undefined'`)
+ * can be exercised directly by tests that stub `globalThis.window` — the
+ * `useOverlay` hook itself runs these via event handlers registered inside
+ * `onMount`, which are unreachable during module-level test imports in
+ * happy-dom (where `window` is always defined).
+ */
+
+export type OverlayPosition = Partial<{
+  top: number | string
+  bottom: number | string
+  left: number | string
+  right: number | string
+}>
+
+export type Align = 'bottom' | 'top' | 'left' | 'right'
+export type AlignX = 'left' | 'center' | 'right'
+export type AlignY = 'bottom' | 'top' | 'center'
+
+export type PositionResult = {
+  pos: OverlayPosition
+  resolvedAlignX: AlignX
+  resolvedAlignY: AlignY
+}
+
+const sel = <T,>(cond: boolean, a: T, b: T): T => (cond ? a : b)
+
+export const calcDropdownVertical = (
+  c: DOMRect,
+  t: DOMRect,
+  align: 'top' | 'bottom',
+  alignX: AlignX,
+  offsetX: number,
+  offsetY: number,
+): PositionResult => {
+  // SSR-fallback: positioning only runs in the mounted browser context, but
+  // the explicit guard documents the SSR-safety contract at the callsite
+  // and lets `no-window-in-ssr` prove it locally. Return shape mirrors the
+  // "no element" path below (empty `pos`, alignment preserved).
+  if (typeof window === 'undefined') return { pos: {}, resolvedAlignX: alignX, resolvedAlignY: align }
+  const pos: OverlayPosition = {}
+
+  const topPos = t.top - offsetY - c.height
+  const bottomPos = t.bottom + offsetY
+  const leftPos = t.left + offsetX
+  const rightPos = t.right - offsetX - c.width
+
+  const fitsTop = topPos >= 0
+  const fitsBottom = bottomPos + c.height <= window.innerHeight
+  const fitsLeft = leftPos + c.width <= window.innerWidth
+  const fitsRight = rightPos >= 0
+
+  const useTop = sel(align === 'top', fitsTop, !fitsBottom)
+  pos.top = sel(useTop, topPos, bottomPos)
+  const resolvedAlignY: AlignY = sel(useTop, 'top', 'bottom')
+
+  let resolvedAlignX: AlignX = alignX
+  if (alignX === 'left') {
+    pos.left = sel(fitsLeft, leftPos, rightPos)
+    resolvedAlignX = sel(fitsLeft, 'left', 'right')
+  } else if (alignX === 'right') {
+    pos.left = sel(fitsRight, rightPos, leftPos)
+    resolvedAlignX = sel(fitsRight, 'right', 'left')
+  } else {
+    const center = t.left + (t.right - t.left) / 2 - c.width / 2
+    const fitsCL = center >= 0
+    const fitsCR = center + c.width <= window.innerWidth
+
+    if (fitsCL && fitsCR) {
+      resolvedAlignX = 'center'
+      pos.left = center
+    } else if (fitsCL) {
+      resolvedAlignX = 'left'
+      pos.left = leftPos
+    } else if (fitsCR) {
+      resolvedAlignX = 'right'
+      pos.left = rightPos
+    }
+  }
+
+  return { pos, resolvedAlignX, resolvedAlignY }
+}
+
+export const calcDropdownHorizontal = (
+  c: DOMRect,
+  t: DOMRect,
+  align: 'left' | 'right',
+  alignY: AlignY,
+  offsetX: number,
+  offsetY: number,
+): PositionResult => {
+  if (typeof window === 'undefined') return { pos: {}, resolvedAlignX: align, resolvedAlignY: alignY }
+  const pos: OverlayPosition = {}
+
+  const leftPos = t.left - offsetX - c.width
+  const rightPos = t.right + offsetX
+  const topPos = t.top + offsetY
+  const bottomPos = t.bottom - offsetY - c.height
+
+  const fitsLeft = leftPos >= 0
+  const fitsRight = rightPos + c.width <= window.innerWidth
+  const fitsTop = topPos + c.height <= window.innerHeight
+  const fitsBottom = bottomPos >= 0
+
+  const useLeft = sel(align === 'left', fitsLeft, !fitsRight)
+  pos.left = sel(useLeft, leftPos, rightPos)
+  const resolvedAlignX: AlignX = sel(useLeft, 'left', 'right')
+
+  let resolvedAlignY: AlignY = alignY
+  if (alignY === 'top') {
+    pos.top = sel(fitsTop, topPos, bottomPos)
+    resolvedAlignY = sel(fitsTop, 'top', 'bottom')
+  } else if (alignY === 'bottom') {
+    pos.top = sel(fitsBottom, bottomPos, topPos)
+    resolvedAlignY = sel(fitsBottom, 'bottom', 'top')
+  } else {
+    const center = t.top + (t.bottom - t.top) / 2 - c.height / 2
+    const fitsCT = center >= 0
+    const fitsCB = center + c.height <= window.innerHeight
+
+    if (fitsCT && fitsCB) {
+      resolvedAlignY = 'center'
+      pos.top = center
+    } else if (fitsCT) {
+      resolvedAlignY = 'top'
+      pos.top = topPos
+    } else if (fitsCB) {
+      resolvedAlignY = 'bottom'
+      pos.top = bottomPos
+    }
+  }
+
+  return { pos, resolvedAlignX, resolvedAlignY }
+}
+
+export const calcModalPos = (
+  c: DOMRect,
+  alignX: AlignX,
+  alignY: AlignY,
+  offsetX: number,
+  offsetY: number,
+): OverlayPosition => {
+  if (typeof window === 'undefined') return {}
+  const pos: OverlayPosition = {}
+
+  switch (alignX) {
+    case 'right':
+      pos.right = offsetX
+      break
+    case 'left':
+      pos.left = offsetX
+      break
+    case 'center':
+      pos.left = window.innerWidth / 2 - c.width / 2
+      break
+    default:
+      pos.right = offsetX
+  }
+
+  switch (alignY) {
+    case 'top':
+      pos.top = offsetY
+      break
+    case 'center':
+      pos.top = window.innerHeight / 2 - c.height / 2
+      break
+    case 'bottom':
+      pos.bottom = offsetY
+      break
+    default:
+      pos.top = offsetY
+  }
+
+  return pos
+}
+
+export const adjustForAncestor = (
+  pos: OverlayPosition,
+  ancestor: { top: number; left: number },
+): OverlayPosition => {
+  if (ancestor.top === 0 && ancestor.left === 0) return pos
+
+  const result = { ...pos }
+  if (typeof result.top === 'number') result.top -= ancestor.top
+  if (typeof result.bottom === 'number') result.bottom += ancestor.top
+  if (typeof result.left === 'number') result.left -= ancestor.left
+  if (typeof result.right === 'number') result.right += ancestor.left
+
+  return result
+}

package/src/Overlay/useOverlay.tsx

@@ -12,17 +12,16 @@ import { throttle } from '@pyreon/ui-core'
 import { value } from '@pyreon/unistyle'
 import { IS_DEVELOPMENT } from '../utils'
 import Provider, { useOverlayContext } from './context'
-
-type OverlayPosition = Partial<{
-  top: number | string
-  bottom: number | string
-  left: number | string
-  right: number | string
-}>
-
-type Align = 'bottom' | 'top' | 'left' | 'right'
-type AlignX = 'left' | 'center' | 'right'
-type AlignY = 'bottom' | 'top' | 'center'
+import {
+  adjustForAncestor,
+  calcDropdownHorizontal,
+  calcDropdownVertical,
+  calcModalPos,
+  type Align,
+  type AlignX,
+  type AlignY,
+  type OverlayPosition,
+} from './positioning'
 
 export type UseOverlayProps = Partial<{
   isOpen: boolean
@@ -44,179 +43,15 @@ export type UseOverlayProps = Partial<{
   onClose: () => void
 }>
 
-type PositionResult = {
-  pos: OverlayPosition
-  resolvedAlignX: AlignX
-  resolvedAlignY: AlignY
-}
-
 // Reference counter for nested modals sharing document.body overflow lock.
 let modalOverflowCount = 0
 
-const sel = <T,>(cond: boolean, a: T, b: T): T => (cond ? a : b)
-
 const devWarn = (msg: string) => {
   if (!IS_DEVELOPMENT) return
   // oxlint-disable-next-line no-console
   console.warn(msg)
 }
 
-const calcDropdownVertical = (
-  c: DOMRect,
-  t: DOMRect,
-  align: 'top' | 'bottom',
-  alignX: AlignX,
-  offsetX: number,
-  offsetY: number,
-): PositionResult => {
-  const pos: OverlayPosition = {}
-
-  const topPos = t.top - offsetY - c.height
-  const bottomPos = t.bottom + offsetY
-  const leftPos = t.left + offsetX
-  const rightPos = t.right - offsetX - c.width
-
-  const fitsTop = topPos >= 0
-  const fitsBottom = bottomPos + c.height <= window.innerHeight
-  const fitsLeft = leftPos + c.width <= window.innerWidth
-  const fitsRight = rightPos >= 0
-
-  const useTop = sel(align === 'top', fitsTop, !fitsBottom)
-  pos.top = sel(useTop, topPos, bottomPos)
-  const resolvedAlignY: AlignY = sel(useTop, 'top', 'bottom')
-
-  let resolvedAlignX: AlignX = alignX
-  if (alignX === 'left') {
-    pos.left = sel(fitsLeft, leftPos, rightPos)
-    resolvedAlignX = sel(fitsLeft, 'left', 'right')
-  } else if (alignX === 'right') {
-    pos.left = sel(fitsRight, rightPos, leftPos)
-    resolvedAlignX = sel(fitsRight, 'right', 'left')
-  } else {
-    const center = t.left + (t.right - t.left) / 2 - c.width / 2
-    const fitsCL = center >= 0
-    const fitsCR = center + c.width <= window.innerWidth
-
-    if (fitsCL && fitsCR) {
-      resolvedAlignX = 'center'
-      pos.left = center
-    } else if (fitsCL) {
-      resolvedAlignX = 'left'
-      pos.left = leftPos
-    } else if (fitsCR) {
-      resolvedAlignX = 'right'
-      pos.left = rightPos
-    }
-  }
-
-  return { pos, resolvedAlignX, resolvedAlignY }
-}
-
-const calcDropdownHorizontal = (
-  c: DOMRect,
-  t: DOMRect,
-  align: 'left' | 'right',
-  alignY: AlignY,
-  offsetX: number,
-  offsetY: number,
-): PositionResult => {
-  const pos: OverlayPosition = {}
-
-  const leftPos = t.left - offsetX - c.width
-  const rightPos = t.right + offsetX
-  const topPos = t.top + offsetY
-  const bottomPos = t.bottom - offsetY - c.height
-
-  const fitsLeft = leftPos >= 0
-  const fitsRight = rightPos + c.width <= window.innerWidth
-  const fitsTop = topPos + c.height <= window.innerHeight
-  const fitsBottom = bottomPos >= 0
-
-  const useLeft = sel(align === 'left', fitsLeft, !fitsRight)
-  pos.left = sel(useLeft, leftPos, rightPos)
-  const resolvedAlignX: AlignX = sel(useLeft, 'left', 'right')
-
-  let resolvedAlignY: AlignY = alignY
-  if (alignY === 'top') {
-    pos.top = sel(fitsTop, topPos, bottomPos)
-    resolvedAlignY = sel(fitsTop, 'top', 'bottom')
-  } else if (alignY === 'bottom') {
-    pos.top = sel(fitsBottom, bottomPos, topPos)
-    resolvedAlignY = sel(fitsBottom, 'bottom', 'top')
-  } else {
-    const center = t.top + (t.bottom - t.top) / 2 - c.height / 2
-    const fitsCT = center >= 0
-    const fitsCB = center + c.height <= window.innerHeight
-
-    if (fitsCT && fitsCB) {
-      resolvedAlignY = 'center'
-      pos.top = center
-    } else if (fitsCT) {
-      resolvedAlignY = 'top'
-      pos.top = topPos
-    } else if (fitsCB) {
-      resolvedAlignY = 'bottom'
-      pos.top = bottomPos
-    }
-  }
-
-  return { pos, resolvedAlignX, resolvedAlignY }
-}
-
-const calcModalPos = (
-  c: DOMRect,
-  alignX: AlignX,
-  alignY: AlignY,
-  offsetX: number,
-  offsetY: number,
-): OverlayPosition => {
-  const pos: OverlayPosition = {}
-
-  switch (alignX) {
-    case 'right':
-      pos.right = offsetX
-      break
-    case 'left':
-      pos.left = offsetX
-      break
-    case 'center':
-      pos.left = window.innerWidth / 2 - c.width / 2
-      break
-    default:
-      pos.right = offsetX
-  }
-
-  switch (alignY) {
-    case 'top':
-      pos.top = offsetY
-      break
-    case 'center':
-      pos.top = window.innerHeight / 2 - c.height / 2
-      break
-    case 'bottom':
-      pos.bottom = offsetY
-      break
-    default:
-      pos.top = offsetY
-  }
-
-  return pos
-}
-
-const adjustForAncestor = (
-  pos: OverlayPosition,
-  ancestor: { top: number; left: number },
-): OverlayPosition => {
-  if (ancestor.top === 0 && ancestor.left === 0) return pos
-
-  const result = { ...pos }
-  if (typeof result.top === 'number') result.top -= ancestor.top
-  if (typeof result.bottom === 'number') result.bottom += ancestor.top
-  if (typeof result.left === 'number') result.left -= ancestor.left
-  if (typeof result.right === 'number') result.right += ancestor.left
-
-  return result
-}
 
 type ComputeResult = {
   pos: OverlayPosition
@@ -374,6 +209,7 @@ const useOverlay = ({
 
   // Position calculation helpers
   const getAncestorOffset = () => {
+    if (typeof document === 'undefined') return { top: 0, left: 0 }
     if (position !== 'absolute' || !contentEl) {
       return { top: 0, left: 0 }
     }
@@ -460,6 +296,7 @@ const useOverlay = ({
   // Set up all event listeners on mount, clean up on unmount
   // --------------------------------------------------------------------------
   const setupListeners = () => {
+    if (typeof window === 'undefined') return () => {}
     const cleanups: (() => void)[] = []
 
     // Click-based open/close

package/src/__tests__/elements.browser.test.tsx

@@ -0,0 +1,59 @@
+/** @jsxImportSource @pyreon/core */
+import { describe, expect, it } from 'vitest'
+import { signal } from '@pyreon/reactivity'
+import { flush, mountInBrowser } from '@pyreon/test-utils/browser'
+import { Element } from '../Element'
+import { Portal } from '../Portal'
+import { Text } from '../Text'
+
+describe('@pyreon/elements browser smoke', () => {
+  it('Element mounts into real DOM with structural rendering', () => {
+    const { container, unmount } = mountInBrowser(
+      <Element tag="div" data-id="el"><span>hello</span></Element>,
+    )
+    const el = container.querySelector('[data-id="el"]')
+    expect(el?.tagName.toLowerCase()).toBe('div')
+    expect(el?.querySelector('span')?.textContent).toBe('hello')
+    unmount()
+  })
+
+  it('Element forwards a reactive text child to the DOM', async () => {
+    const label = signal('hello')
+    const { container, unmount } = mountInBrowser(
+      <Element tag="div">
+        <span data-id="lbl">{() => label()}</span>
+      </Element>,
+    )
+    const lbl = container.querySelector('[data-id="lbl"]')
+    expect(lbl?.textContent).toBe('hello')
+    label.set('world')
+    await flush()
+    expect(lbl?.textContent).toBe('world')
+    unmount()
+  })
+
+  it('Text renders as inline element', () => {
+    const { container, unmount } = mountInBrowser(<Text tag="span" data-id="t">hi</Text>)
+    const el = container.querySelector('[data-id="t"]')
+    expect(el?.tagName.toLowerCase()).toBe('span')
+    expect(el?.textContent).toBe('hi')
+    unmount()
+  })
+
+  it('Portal projects children to document.body by default', () => {
+    const { unmount } = mountInBrowser(
+      <Portal>
+        <div data-portal-id="p">portal-content</div>
+      </Portal>,
+    )
+    const projected = document.querySelector('[data-portal-id="p"]')
+    expect(projected?.textContent).toBe('portal-content')
+    unmount()
+    expect(document.querySelector('[data-portal-id="p"]')).toBeNull()
+  })
+
+  it('runs in a real browser — `typeof process` is undefined, `import.meta.env.DEV` is true', () => {
+    expect(typeof process).toBe('undefined')
+    expect(import.meta.env.DEV).toBe(true)
+  })
+})

package/src/__tests__/positioning.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  adjustForAncestor,
+  calcDropdownHorizontal,
+  calcDropdownVertical,
+  calcModalPos,
+} from '../Overlay/positioning'
+
+const rect = (top: number, left: number, width: number, height: number): DOMRect => ({
+  top,
+  left,
+  right: left + width,
+  bottom: top + height,
+  width,
+  height,
+  x: left,
+  y: top,
+  toJSON: () => ({ top, left, width, height }),
+})
+
+describe('positioning helpers — browser path (happy-dom)', () => {
+  it('calcDropdownVertical: fits below → positions under the trigger', () => {
+    const trigger = rect(100, 200, 80, 30) // top=100
+    const content = rect(0, 0, 60, 40)
+    const result = calcDropdownVertical(content, trigger, 'bottom', 'left', 0, 4)
+    expect(result.resolvedAlignY).toBe('bottom')
+    expect(result.pos.top).toBe(trigger.bottom + 4)
+  })
+
+  it('calcDropdownHorizontal: flips to right when left does not fit', () => {
+    const trigger = rect(100, 10, 80, 30) // near left edge
+    const content = rect(0, 0, 120, 40) // wider than trigger.left
+    const result = calcDropdownHorizontal(content, trigger, 'left', 'top', 0, 0)
+    expect(result.resolvedAlignX).toBe('right')
+  })
+
+  it('calcModalPos: centers horizontally and vertically', () => {
+    const content = rect(0, 0, 400, 300)
+    const pos = calcModalPos(content, 'center', 'center', 0, 0)
+    expect(typeof pos.left).toBe('number')
+    expect(typeof pos.top).toBe('number')
+  })
+
+  it('adjustForAncestor: subtracts ancestor offset from absolute positions', () => {
+    const adjusted = adjustForAncestor({ top: 100, left: 200 }, { top: 30, left: 50 })
+    expect(adjusted.top).toBe(70)
+    expect(adjusted.left).toBe(150)
+  })
+
+  it('adjustForAncestor: returns input unchanged when ancestor is origin', () => {
+    const input = { top: 10, left: 20 }
+    expect(adjustForAncestor(input, { top: 0, left: 0 })).toBe(input)
+  })
+})
+
+// SSR-fallback path: the positioning helpers are only reachable via mounted
+// event handlers in production, so `typeof window === 'undefined'` never
+// fires in browser tests. We force the fallback by stubbing `globalThis.window`
+// to `undefined` for the duration of a single test. happy-dom resets on
+// teardown; we restore the original window afterwards.
+describe('positioning helpers — SSR fallback (window undefined)', () => {
+  const realWindow = globalThis.window
+  const realWindowDesc = Object.getOwnPropertyDescriptor(globalThis, 'window')
+
+  afterEach(() => {
+    if (realWindowDesc) Object.defineProperty(globalThis, 'window', realWindowDesc)
+    else (globalThis as { window?: unknown }).window = realWindow
+  })
+
+  it('calcDropdownVertical returns alignment-preserving empty fallback', () => {
+    Object.defineProperty(globalThis, 'window', { value: undefined, configurable: true, writable: true })
+    const result = calcDropdownVertical(rect(0, 0, 60, 40), rect(100, 200, 80, 30), 'bottom', 'left', 0, 0)
+    expect(result.pos).toEqual({})
+    expect(result.resolvedAlignX).toBe('left')
+    expect(result.resolvedAlignY).toBe('bottom')
+  })
+
+  it('calcDropdownHorizontal returns alignment-preserving empty fallback', () => {
+    Object.defineProperty(globalThis, 'window', { value: undefined, configurable: true, writable: true })
+    const result = calcDropdownHorizontal(rect(0, 0, 60, 40), rect(100, 200, 80, 30), 'right', 'top', 0, 0)
+    expect(result.pos).toEqual({})
+    expect(result.resolvedAlignX).toBe('right')
+    expect(result.resolvedAlignY).toBe('top')
+  })
+
+  it('calcModalPos returns empty object', () => {
+    Object.defineProperty(globalThis, 'window', { value: undefined, configurable: true, writable: true })
+    expect(calcModalPos(rect(0, 0, 400, 300), 'center', 'center', 0, 0)).toEqual({})
+  })
+})

package/src/helpers/Wrapper/component.tsx

@@ -4,6 +4,7 @@
  * fix (parent + child Styled) because these HTML elements do not natively
  * support `display: flex` consistently across browsers.
  */
+import { splitProps } from '@pyreon/core'
 import { IS_DEVELOPMENT } from '../../utils'
 import Styled from './styled'
 import type { Props } from './types'
@@ -11,65 +12,76 @@ import { isWebFixNeeded } from './utils'
 
 const DEV_PROPS: Record<string, string> = IS_DEVELOPMENT ? { 'data-pyr-element': 'Element' } : {}
 
-const Component = ({
-  children,
-  tag,
-  block,
-  extendCss,
-  direction,
-  alignX,
-  alignY,
-  equalCols,
-  isInline,
-  ref,
-  ...props
-}: Partial<Props> & { ref?: any }) => {
-  const COMMON_PROPS = {
-    ...props,
-    ...DEV_PROPS,
-    ref,
-    as: tag,
-  }
-
-  const needsFix = !props.dangerouslySetInnerHTML && isWebFixNeeded(tag)
+// Layout / ref keys consumed by Wrapper itself. Everything else is forwarded
+// onto the underlying DOM node. Listed as a tuple so `splitProps` narrows
+// `own` correctly while preserving reactive prop tracking on both halves.
+const OWN_KEYS: Array<keyof Props | 'ref'> = [
+  'children',
+  'tag',
+  'block',
+  'extendCss',
+  'direction',
+  'alignX',
+  'alignY',
+  'equalCols',
+  'isInline',
+  'ref',
+  'dangerouslySetInnerHTML',
+]
 
-  const normalElement = {
-    block,
-    direction,
-    alignX,
-    alignY,
-    equalCols,
-    extraStyles: extendCss,
-  }
+const Component = (props: Partial<Props> & { ref?: unknown }) => {
+  const [own, rest] = splitProps(props, OWN_KEYS)
 
-  const parentFixElement = {
-    parentFix: true as const,
-    block,
-    extraStyles: extendCss,
+  const commonProps = {
+    ...rest,
+    ...DEV_PROPS,
+    ref: own.ref,
+    as: own.tag,
   }
 
-  const childFixElement = {
-    childFix: true as const,
-    direction,
-    alignX,
-    alignY,
-    equalCols,
-  }
+  const needsFix = !own.dangerouslySetInnerHTML && isWebFixNeeded(own.tag)
 
   if (!needsFix) {
     return (
-      <Styled {...COMMON_PROPS} $element={normalElement}>
-        {children}
+      <Styled
+        {...commonProps}
+        $element={{
+          block: own.block,
+          direction: own.direction,
+          alignX: own.alignX,
+          alignY: own.alignY,
+          equalCols: own.equalCols,
+          extraStyles: own.extendCss,
+        }}
+      >
+        {own.children}
       </Styled>
     )
   }
 
-  const asTag = isInline ? 'span' : 'div'
+  const asTag = own.isInline ? 'span' : 'div'
 
   return (
-    <Styled {...COMMON_PROPS} $element={parentFixElement}>
-      <Styled as={asTag} $childFix $element={childFixElement}>
-        {children}
+    <Styled
+      {...commonProps}
+      $element={{
+        parentFix: true as const,
+        block: own.block,
+        extraStyles: own.extendCss,
+      }}
+    >
+      <Styled
+        as={asTag}
+        $childFix
+        $element={{
+          childFix: true as const,
+          direction: own.direction,
+          alignX: own.alignX,
+          alignY: own.alignY,
+          equalCols: own.equalCols,
+        }}
+      >
+        {own.children}
       </Styled>
     </Styled>
   )